pdfedit 0.1.0__tar.gz

pdfedit-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+*_edited.pdf
+.DS_Store
+dist/
+build/
+*.egg-info/
+.pytest_cache/

pdfedit-0.1.0/LICENSE

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

pdfedit-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: pdfedit
+Version: 0.1.0
+Summary: Find and edit any text in a PDF while matching the original font, size, and color
+Project-URL: Homepage, https://github.com/sachinpandey22/pdfedit
+Project-URL: Repository, https://github.com/sachinpandey22/pdfedit
+Project-URL: Issues, https://github.com/sachinpandey22/pdfedit/issues
+Author-email: Sachin Pandey <xachin300@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: edit,font,pdf,pymupdf,redaction,text
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pymupdf>=1.28.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pdfedit
+
+A command-line tool that finds and edits **any** text in a PDF while matching
+the original font, size, and color — not a fixed find-and-replace on known
+form fields. It walks every text span via [PyMuPDF](https://pymupdf.readthedocs.io/),
+resolves each span's real font (embedded extraction, or the closest Base-14
+fallback), then redacts the old glyphs and redraws the replacement in the
+same font, size, and color at the same position.
+
+The original file is never modified — every edit writes `<name>_edited.pdf`
+next to the input.
+
+> **Status:** alpha, pre-1.0 — the API and CLI may still change.
+> White-fill redaction only (colored backgrounds not yet sampled); no
+> paragraph reflow; scanned pages are detected and warned about, not OCR'd.
+
+## Install
+
+```bash
+pip install pdfedit
+```
+
+This puts a `pdfedit` command on your PATH. You can also run it as
+`python -m pdfedit`.
+
+From source (for development):
+
+```bash
+git clone https://github.com/sachinpandey22/pdfedit && cd pdfedit
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"      # editable install + pytest
+```
+
+## Usage
+
+```bash
+pdfedit inspect your-document.pdf          # read-only: list every text span with its id, font, size, color
+pdfedit edit your-document.pdf             # interactive: pick a span id, type a replacement, `save`
+pdfedit batch your-document.pdf edits.json  # non-interactive: apply a list of edits
+```
+
+### `inspect`
+
+Prints one row per span. The `ID` (`p<page>-b<block>-l<line>-s<span>`) is the
+handle you pass to `edit` or a batch file.
+
+### `edit`
+
+A small REPL. Enter a span id, then the replacement text; the edit is
+**queued** with a before/after preview (and the resolved font, and an
+auto-shrink note if the text had to be made smaller to fit). `save` applies
+every queued edit at once and writes the output. `quit` discards everything.
+
+### `batch`
+
+`edits.json` is a JSON array; each entry is either:
+
+```json
+[
+  { "id": "p1-b0-l0-s0", "new_text": "New Name" },
+  { "find": "Old Company", "new_text": "New Company" }
+]
+```
+
+- `id` targets one exact span.
+- `find` replaces that substring in **every** span containing it. Multiple
+  `find` entries against the same span compose in order.
+
+The whole file is validated first — if any entry is malformed or names a
+missing span id, nothing is written and the command exits non-zero.
+
+### Autofit
+
+If a replacement is wider than the original box, the font size shrinks (down
+to 60% of the original) until it fits. Past that floor it's drawn at the
+minimum size and a warning is printed rather than overflowing silently.
+
+### Encrypted PDFs
+
+You're prompted for the password. Note: the `_edited.pdf` copy is written
+**without** encryption.
+
+## Development
+
+```bash
+pytest                                   # run the test suite
+python tests/fixtures/make_sample.py      # regenerate the synthetic test fixture
+```
+
+There's no separate lint config. See
+[`CLAUDE.md`](https://github.com/sachinpandey22/pdfedit/blob/main/CLAUDE.md)
+for the architecture and the two redraw pitfalls the engine works around,
+and [`docs/`](https://github.com/sachinpandey22/pdfedit/tree/main/docs) for
+longer background.

pdfedit-0.1.0/README.md

@@ -0,0 +1,94 @@
+# pdfedit
+
+A command-line tool that finds and edits **any** text in a PDF while matching
+the original font, size, and color — not a fixed find-and-replace on known
+form fields. It walks every text span via [PyMuPDF](https://pymupdf.readthedocs.io/),
+resolves each span's real font (embedded extraction, or the closest Base-14
+fallback), then redacts the old glyphs and redraws the replacement in the
+same font, size, and color at the same position.
+
+The original file is never modified — every edit writes `<name>_edited.pdf`
+next to the input.
+
+> **Status:** alpha, pre-1.0 — the API and CLI may still change.
+> White-fill redaction only (colored backgrounds not yet sampled); no
+> paragraph reflow; scanned pages are detected and warned about, not OCR'd.
+
+## Install
+
+```bash
+pip install pdfedit
+```
+
+This puts a `pdfedit` command on your PATH. You can also run it as
+`python -m pdfedit`.
+
+From source (for development):
+
+```bash
+git clone https://github.com/sachinpandey22/pdfedit && cd pdfedit
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"      # editable install + pytest
+```
+
+## Usage
+
+```bash
+pdfedit inspect your-document.pdf          # read-only: list every text span with its id, font, size, color
+pdfedit edit your-document.pdf             # interactive: pick a span id, type a replacement, `save`
+pdfedit batch your-document.pdf edits.json  # non-interactive: apply a list of edits
+```
+
+### `inspect`
+
+Prints one row per span. The `ID` (`p<page>-b<block>-l<line>-s<span>`) is the
+handle you pass to `edit` or a batch file.
+
+### `edit`
+
+A small REPL. Enter a span id, then the replacement text; the edit is
+**queued** with a before/after preview (and the resolved font, and an
+auto-shrink note if the text had to be made smaller to fit). `save` applies
+every queued edit at once and writes the output. `quit` discards everything.
+
+### `batch`
+
+`edits.json` is a JSON array; each entry is either:
+
+```json
+[
+  { "id": "p1-b0-l0-s0", "new_text": "New Name" },
+  { "find": "Old Company", "new_text": "New Company" }
+]
+```
+
+- `id` targets one exact span.
+- `find` replaces that substring in **every** span containing it. Multiple
+  `find` entries against the same span compose in order.
+
+The whole file is validated first — if any entry is malformed or names a
+missing span id, nothing is written and the command exits non-zero.
+
+### Autofit
+
+If a replacement is wider than the original box, the font size shrinks (down
+to 60% of the original) until it fits. Past that floor it's drawn at the
+minimum size and a warning is printed rather than overflowing silently.
+
+### Encrypted PDFs
+
+You're prompted for the password. Note: the `_edited.pdf` copy is written
+**without** encryption.
+
+## Development
+
+```bash
+pytest                                   # run the test suite
+python tests/fixtures/make_sample.py      # regenerate the synthetic test fixture
+```
+
+There's no separate lint config. See
+[`CLAUDE.md`](https://github.com/sachinpandey22/pdfedit/blob/main/CLAUDE.md)
+for the architecture and the two redraw pitfalls the engine works around,
+and [`docs/`](https://github.com/sachinpandey22/pdfedit/tree/main/docs) for
+longer background.

pdfedit-0.1.0/docs/README.md

@@ -0,0 +1,84 @@
+# pdfedit — Documentation
+
+`pdfedit` is a command-line tool that finds and edits **any** text in a PDF while
+matching the original font, size, and color — not just a fixed find-and-replace on
+known form fields.
+
+These docs serve two purposes:
+
+- **Learning** — how PDFs store text, and how PyMuPDF lets us take it apart and
+  put it back together. See [concepts.md](concepts.md).
+- **Using** — how to run the CLI to inspect and edit a real document. See
+  [usage.md](usage.md).
+
+## Map of the docs
+
+| Doc | What it covers |
+| --- | --- |
+| [concepts.md](concepts.md) | Background: PDF text model, spans, fonts, redaction. Read this first if the code is confusing. |
+| [architecture.md](architecture.md) | How the four modules fit together and the flow of an edit from keystroke to saved file. |
+| [usage.md](usage.md) | Every CLI subcommand, with examples. |
+| [modules/model.md](modules/model.md) | `pdfedit/model.py` — span extraction, the text model. |
+| [modules/fonts.md](modules/fonts.md) | `pdfedit/fonts.py` — font resolution (embedded extraction + Base-14 fallback). |
+| [modules/engine.md](modules/engine.md) | `pdfedit/engine.py` — the redact-and-rewrite engine. |
+| [modules/cli.md](modules/cli.md) | `pdfedit/cli.py` — argument parsing and the interactive REPL. |
+| [glossary.md](glossary.md) | Quick definitions of terms used throughout. |
+| [maintaining-these-docs.md](maintaining-these-docs.md) | How these docs stay in sync with the code, plus a change log. |
+
+## Project status
+
+The build is milestone-driven (see [pdf-text-editor-plan.md](../pdf-text-editor-plan.md)).
+As of this writing (2026-09-10):
+
+- **M1 done** — span extraction + `inspect` command.
+- **M2 done** — font resolution (Base-14 fallback verified pixel-identical;
+  embedded-font extraction implemented but not yet verified against a real
+  embedded-font PDF).
+- **M3 done** — single/multi-span queued replace via the `edit` REPL, with the
+  redaction-collision fix (`_shrink_to_avoid`, plus a containment guard so a
+  neighbor box that straddles the target doesn't invert the redaction rect).
+- **M4 done** — autofit: replacement text that overflows is shrunk analytically
+  down to 60% of the original size, then clamped + warned.
+- **M5 done** — `batch file.pdf edits.json`: apply a JSON list of `{id}` or
+  `{find}` edits non-interactively, validated up front, all-or-nothing.
+- **Packaged (v0.1.0, not yet tagged)** — `pyproject.toml` (hatchling), a
+  `pdfedit` console script, and a `pytest` suite (`tests/`, 48 pass + 1
+  skipped) run off a synthetic fixture. See [PLAN.md](PLAN.md).
+- **Removed:** the `find` subcommand (only ever an error stub — substring
+  replace lives on as `{"find": ...}` batch entries).
+- **Not done:** M6 background-color sampling, M7 render-diff verification,
+  M8 paragraph reflow / OCR.
+
+There is also a [CLAUDE.md](../CLAUDE.md) at the repo root — orientation for
+Claude Code sessions. It overlaps these docs; the authority order on conflicts is
+**source code → `pdf-text-editor-plan.md` → these docs**.
+
+> **Note:** the code is under active development in a parallel session. If a code
+> snippet here doesn't match the file, trust the file — then fix the doc.
+
+## Requirements
+
+- Python 3.10+ (developed on 3.14.7)
+- `pymupdf>=1.28.2` — imported as `import pymupdf`, **not** the deprecated `import fitz`
+
+```
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"      # editable install + pytest; drop [dev] to skip
+```
+
+This puts a `pdfedit` command on your PATH while the venv is active. You can
+also run it as a module (a `pdfedit/__main__.py` shim makes this work):
+
+```
+pdfedit inspect tests/fixtures/sample.pdf
+python -m pdfedit inspect tests/fixtures/sample.pdf   # equivalent
+```
+
+`tests/fixtures/sample.pdf` is the committed fixture — a synthetic, fictional
+one-page resume (regenerate with `python tests/fixtures/make_sample.py`).
+
+Run the test suite with `pytest` (48 pass + 1 skipped — the skip is the
+embedded-font path, which still needs a real-world PDF). The suite is the
+release gate; the manual render-and-look-at-it check (`page.get_pixmap`) is now
+the backup for any change to the redact/redraw path.

pdfedit-0.1.0/docs/architecture.md

@@ -0,0 +1,96 @@
+# Architecture
+
+## Package layout
+
+```
+pdfedit/
+├── __init__.py   Package marker + `__version__` (hatchling reads it for the build)
+├── __main__.py   One-line shim so `python -m pdfedit` calls cli.main()
+├── model.py      Text model: extract spans, unpack colors, detect scanned pages
+├── fonts.py      Font resolution: embedded extraction + Base-14 fallback + cache
+├── engine.py     Edit engine: queue edits, autofit, redact, redraw with TextWriter, save
+└── cli.py        Argument parsing + the interactive `edit` REPL + batch mode
+
+pyproject.toml    hatchling build; `pdfedit` console script → `pdfedit.cli:main`
+tests/            pytest suite (48 pass + 1 skipped) + `fixtures/sample.pdf`
+                  and `fixtures/make_sample.py` (regenerates the synthetic fixture)
+```
+
+Two ways to invoke: the installed `pdfedit` command, or `python -m pdfedit`.
+
+Dependency direction (nothing circular):
+
+```
+cli.py  ──►  engine.py  ──►  fonts.py  ──►  model.py
+   └─────────────────────────────────────►  model.py
+```
+
+- `model.py` depends on nothing but `pymupdf`.
+- `fonts.py` uses `Span` / `SpanStyle` from `model.py`.
+- `engine.py` orchestrates `model.py` + `fonts.py`.
+- `cli.py` is the only module that talks to the user (stdin/stdout, argparse).
+
+## The objects
+
+| Class | Module | Role |
+| --- | --- | --- |
+| `Span` | model | One immutable text run: id, page, text, bbox, origin, font, size, color, style. |
+| `SpanStyle` | model | Decoded bold/italic/serif/monospace/superscript booleans + `short_label()`. |
+| `FontResolution` | fonts | Result of resolving one span's font: alias, `embedded` bool, optional `fontbuffer` bytes, optional warning. |
+| `FontResolver` | fonts | Per-document cache. `resolve(span)` → `FontResolution`; `font_object(res)` → `pymupdf.Font`. |
+| `QueuedEdit` | engine | A pending edit: `span`, `new_text`, and the autofit-resolved `font_size` to draw with. |
+| `EditPreview` | engine | What the REPL/batch shows before applying: `font_alias`, `embedded`, `font_size`, `shrunk`, `fits`. |
+| `EditEngine` | engine | Holds the open doc, all spans, and the edit queue. `queue_edit`, `queue_find_replace`, `current_text`, `apply_all`, `save`. |
+
+## Flow of one edit
+
+```
+   user types "p1-b3-l0-s0"  then  "Jane Doe"
+            │
+            ▼
+  cli.cmd_edit REPL loop
+            │  engine.get_span(id)          → Span
+            │  engine.queue_edit(id, text)
+            ▼
+  EditEngine.preview(span, new_text)
+            │  resolver.resolve(span)       → FontResolution   (fonts.py)
+            │  resolver.font_object(res)    → pymupdf.Font
+            │  _fit_font_size(font, text, span.size, bbox width)  → (size, fits)
+            ▼
+  EditPreview  (printed: before/after, font used, autofit size, shrunk?, fits?)
+            │
+   user types "save"
+            ▼
+  EditEngine.apply_all()
+            │  group queue by page
+            │  for each page:
+            │     for each edit: build redact rect, _shrink_to_avoid(every other span)
+            │        (clamp skipped when a neighbor straddles the box — _MAX_CLAMP_FRACTION)
+            │     page.add_redact_annot(rect, fill=white)
+            │     page.apply_redactions(images=NONE)
+            │     group edits by color
+            │     for each color: one TextWriter, append(origin, text, font, edit.font_size), write_text(page, color)
+            ▼
+  EditEngine.save("<name>_edited.pdf")     original untouched
+```
+
+`batch` mode replaces the REPL box with `cmd_batch`: parse JSON, validate every
+entry up front (abort with nothing written on any error), then `queue_edit` /
+`queue_find_replace` per entry → `apply_all` → `save`.
+
+## Design choices worth knowing
+
+- **Span-granular by default.** Edits target one span. Paragraph reflow is a
+  stretch goal (M8), not the default.
+- **Original file is never opened for writing.** Output always goes to a new
+  `_edited.pdf` next to the source.
+- **Font extraction happens at most once per unique font name.** `FontResolver`
+  caches by `span.font`, and caches the built `pymupdf.Font` objects by alias.
+- **Warnings, not failures.** Overflowing text, Type1 fallback, scanned pages —
+  all print a warning and continue.
+- **The engine is UI-free.** `EditEngine` never calls `print()` or `input()`; it
+  returns warning strings for `cli.py` to display. This is what let `batch` mode
+  reuse it directly with no refactor.
+- **`find`-mode edits chain.** `queue_find_replace` reads `current_text` (the
+  already-queued replacement if any, else the original), so several batch entries
+  can build on each other instead of clobbering.

pdfedit-0.1.0/docs/concepts.md

@@ -0,0 +1,146 @@
+# Concepts — how PDF text works and why editing it is hard
+
+If you've only ever thought of a PDF as "a document," this is the mental model you
+need before the code makes sense.
+
+## A PDF is a bag of drawing instructions, not a document
+
+A PDF page does not contain paragraphs. It contains a **content stream**: a list of
+low-level operators like "set font to F1 at 11pt", "move to x=72 y=709", "show the
+string `Riley Morgan`", "move to...". There is no notion of "the name field" or
+"the second bullet point." Everything is absolute positioning.
+
+Consequences:
+
+- **There is no reflow.** If you make a word longer, nothing after it moves. You
+  have to manage spacing yourself.
+- **You can't just "replace text."** You must erase the pixels/operators that drew
+  the old text, then draw new text at the same spot with the same font.
+- **The same visible letter can be encoded many ways** depending on the font's
+  internal character map (cmap). This is why font handling is the hard part.
+
+## Spans — the unit we work with
+
+PyMuPDF's `page.get_text("dict")` re-groups those raw operators into a tidy
+hierarchy:
+
+```
+page
+└── block      (roughly a paragraph or a distinct region)
+    └── line   (one visual line of text)
+        └── span   (a run of characters with ONE uniform style)
+```
+
+A **span** is the smallest chunk where font, size, color, and style don't change.
+"**Senior** Engineer" is two spans if "Senior" is bold: one bold span, one
+regular span.
+
+Each span from PyMuPDF gives us:
+
+| Field | Meaning |
+| --- | --- |
+| `text` | the actual characters |
+| `bbox` | `(x0, y0, x1, y1)` bounding box, in PDF points (1/72 inch), origin top-left |
+| `origin` | `(x, y)` of the text **baseline** start — where drawing begins |
+| `font` | font name as embedded, e.g. `ABCDEE+Calibri` or `Helvetica` |
+| `size` | font size in points |
+| `color` | a single packed integer, e.g. `0x1a1a1a` — see below |
+| `flags` | bitfield: bold / italic / serif / monospace / superscript |
+
+`pdfedit` wraps each in a [`Span`](modules/model.md) dataclass and gives it a
+**stable ID** like `p1-b2-l1-s0` (page 1, block 2, line 1, span 0) so you can
+refer to it on the command line.
+
+### The packed color int
+
+`color` is `(r << 16) | (g << 8) | b`, each channel 0–255. To get the 0–1 floats
+PyMuPDF's drawing APIs want:
+
+```python
+r = (color >> 16) & 255
+g = (color >> 8) & 255
+b = color & 255
+rgb01 = (r / 255, g / 255, b / 255)
+```
+
+This is `unpack_color()` in [model.py](modules/model.md).
+
+## Fonts — embedded vs. not
+
+To redraw text so it looks identical, you need the **same typeface**. Two cases:
+
+1. **Font is embedded in the PDF** (common for designed documents). The font
+   program bytes are literally inside the file. We can pull them out with
+   `doc.extract_font(xref)` and hand them to a `pymupdf.Font(fontbuffer=...)`.
+   - Works reliably for TrueType (`ttf`) and OpenType (`otf`).
+   - Embedded **Type1** (old PostScript fonts) often comes back in a form the API
+     can't reuse → we fall back.
+
+2. **Font is not embedded** (e.g. the `tests/fixtures/sample.pdf` fixture uses
+   Helvetica, one of the "Base-14" fonts every PDF reader is required to
+   have). Nothing to extract. We
+   pick the closest of PyMuPDF's 14 built-in aliases (`helv`, `hebo` = Helvetica
+   bold, `tiro` = Times roman, `cour` = Courier, ...) using the style flags.
+
+[fonts.md](modules/fonts.md) covers the resolution logic and caching.
+
+### Why `TextWriter`, not `insert_text`
+
+This bit the project during M2. `page.insert_text(..., fontname="helv")` uses a
+legacy simple-encoding code path. If your replacement text has a bullet (`•`), an
+en-dash (`–`), or a curly quote, it renders a placeholder middle-dot **even
+though the font contains the glyph**. The lookup table it uses just doesn't cover
+those characters.
+
+`pymupdf.TextWriter` + a real `pymupdf.Font` object resolves glyphs through the
+font's actual cmap and renders correctly. So the engine always draws via
+`TextWriter`. One quirk: `TextWriter` sets color per `write_text()` call, not per
+appended string — so the engine groups edits by color and uses one writer per
+color.
+
+## Redaction — erasing the old text
+
+To remove text we use PyMuPDF **redaction annotations**:
+
+```python
+page.add_redact_annot(rect, fill=(1, 1, 1))   # queue a white box over rect
+page.apply_redactions(images=pymupdf.PDF_REDACT_IMAGE_NONE)  # actually remove
+```
+
+`apply_redactions()` genuinely deletes the underlying text operators (not just
+covers them), then paints `fill` over the area.
+
+**Gotcha handled in the engine:** `apply_redactions()` drops an entire
+text-drawing operation if the redaction rect overlaps it *at all*. Span bboxes use
+full font ascent/descent, so on tight line spacing a span's box can poke a point
+or two into the line above/below — redacting one line would silently wipe its
+neighbor. The engine shrinks the rect along the shallow-overlap axis to avoid
+this (`_shrink_to_avoid` in [engine.md](modules/engine.md)). A guard
+(`_MAX_CLAMP_FRACTION`) skips the clamp and redacts the full box when the cut
+would exceed half the rect — that means the neighbor genuinely straddles or
+contains the target (e.g. a big heading whose metric box spans a small line in
+its whitespace), and clamping would invert the rect to nothing and redact
+nothing at all.
+
+Real documents aren't white under the text, so a future milestone (M6) samples the
+actual background color. Right now the fill is hard-coded white.
+
+## The full edit, end to end
+
+1. **Extract** every span, assign IDs. (`model.py`)
+2. User picks a span ID and types replacement text. (`cli.py`)
+3. **Resolve** that span's font — extract embedded bytes or choose a Base-14
+   alias. (`fonts.py`)
+4. **Preview**: measure the new text's width vs. the old box. If it's wider,
+   **autofit** solves for the largest font size that fits (down to a 60% floor);
+   if it still won't fit at the floor, warn.
+5. On `save`: for each edited page —
+   a. redact every edited span's box (shrinking to protect neighbors),
+   b. `apply_redactions()`,
+   c. group edits by color, and for each color draw all its new strings at the
+      original baselines with `TextWriter`, at the autofit-resolved size.
+6. **Save** to `<name>_edited.pdf`. The original file is never modified.
+
+`batch` mode runs the same steps 3–6 without the REPL, from a JSON edit list.
+
+See [architecture.md](architecture.md) for where each step lives.

pdfedit-0.1.0/docs/glossary.md

@@ -0,0 +1,68 @@
+# Glossary
+
+**autofit** — shrinking the replacement text's font size so it fits the original
+span's box width. `pdfedit` solves for the size directly (glyph widths scale
+linearly with size) rather than stepping, and won't go below 60% of the original
+size (`_AUTOFIT_MIN_RATIO`) — past that it clamps and warns.
+
+**Base-14 fonts** — the 14 typefaces (Helvetica ×4, Times ×4, Courier ×4, Symbol,
+ZapfDingbats) every PDF viewer must provide. A PDF using only these doesn't embed
+any font. `pdfedit` falls back to these when it can't reuse an embedded font.
+
+**bbox** — bounding box, `(x0, y0, x1, y1)` in PDF points. `(x0, y0)` top-left,
+`(x1, y1)` bottom-right. From `get_text("dict")` it spans the full font
+ascent/descent, not just the visible glyph ink.
+
+**block** — PyMuPDF's coarsest text grouping, roughly a paragraph or a distinct
+page region. `block["type"]`: `0` = text, `1` = image.
+
+**cmap (character map)** — a font's internal table mapping character codes to
+glyph outlines. The reason "replace text" isn't trivial: the same visible letter
+can be encoded differently in different fonts.
+
+**content stream** — the actual list of drawing operators for a PDF page. Text is
+"show string at position with font", with no paragraph or field structure.
+
+**embedded font** — a font whose program bytes are stored inside the PDF.
+Extractable with `doc.extract_font(xref)`; reusable for TrueType/OpenType.
+
+**origin** — `(x, y)` of a span's baseline start. Where `TextWriter` begins
+drawing. Distinct from `bbox` top-left (the baseline sits above the descender).
+
+**packed color int** — `(r << 16) | (g << 8) | b`. `unpack_color()` in model.py
+converts to 0–1 float RGB.
+
+**point (pt)** — 1/72 inch. PDF's unit for everything. A US Letter page is
+612 × 792 pt.
+
+**redaction annotation** — PyMuPDF mechanism to *remove* content in a rectangle
+(not just cover it). `add_redact_annot(rect, fill=...)` queues one;
+`apply_redactions()` executes all queued ones on the page.
+
+**span** — a run of characters with uniform font, size, color, and style. The
+smallest unit `pdfedit` edits. `pdfedit` gives each a stable id
+`p<page>-b<block>-l<line>-s<span>`.
+
+**span id** — e.g. `p1-b2-l1-s0`. The handle you type in the `edit` REPL. Comes
+from `inspect`.
+
+**style flags** — a bitfield on each span: superscript(1), italic(2), serif(4),
+monospace(8), bold(16). Decoded into `SpanStyle`.
+
+**subsetting** — embedding only the glyphs a document actually uses. An embedded
+`ABCDEE+Calibri` (the `ABCDEE+` prefix marks a subset) may lack characters your
+replacement text needs.
+
+**chaining (batch find edits)** — when several `{find}` entries in one batch
+target the same span, each sees the previous one's result (`EditEngine.current_text`)
+so they compose in order instead of overwriting each other.
+
+**Type1 font** — older PostScript font format. Often embedded in a form PyMuPDF
+can't feed back into `pymupdf.Font`, so `pdfedit` falls back to Base-14 for it.
+
+**TextWriter** — `pymupdf.TextWriter`, the correct API for drawing new text.
+Resolves glyphs through the font's real cmap (unlike `insert_text`, which mangles
+bullets/dashes/quotes). Color is set per `write_text()` call, not per string.
+
+**xref** — a PDF object's cross-reference number, its address within the file.
+Fonts, images, pages are all addressed by xref.