@shuji-bonji/pdf-writer-mcp 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.4.0] - 2026-07-16
+
+### Added
+
+- **Editing tools (Tier A, wave 2)**:
+  - `add_bookmarks` — set the document outline. Nestable via `children` (up to 8
+    levels, 2000 entries). Replaces any existing outline. Titles are written as
+    UTF-16BE so CJK round-trips correctly. Open items carry a positive `/Count`,
+    collapsed items a negative one, per ISO 32000-1 §12.3.3.
+  - `add_annotation` — add a `text` (sticky note), `highlight`, or `square`
+    annotation. Coordinates use PDF space (origin bottom-left, points). Colors
+    are `#rrggbb`; `contents` and `author` accept CJK.
+
+  pdf-lib exposes no outline or annotation API, so both are built from the
+  low-level object model (`services/outline.ts`, `services/annotation.ts`).
+
+## [0.3.1] - 2026-07-16
+
+### Fixed
+
+- **Text extraction broken for digits in Latin context** (regression introduced in
+  0.3.0): `subsetFont` is now called with `noLayoutClosure: true`.
+
+  pdf-lib's `CustomFontEmbedder` (used with `subset: false`) derives glyphs
+  through two independent paths: the CIDs written into the content stream come
+  from `font.layout(text)` — **after** GSUB substitution — while the ToUnicode
+  CMap is built from `font.characterSet` → `glyphForCodePoint` — **before**
+  substitution. Noto Sans JP substitutes ASCII digits with alternate forms in
+  Latin context (`layout('English 0')` yields glyph 17460, not 17), so the two
+  disagreed and extraction returned wrong characters (`v0.3.0` → `vô.õ.ô`, and
+  poppler dropped the digits entirely). Rendering was correct throughout, which
+  made this easy to miss.
+
+  Excluding layout-reachable glyphs from the subset prevents the substitution
+  altogether, so `layout()` and `glyphsForString()` agree again. Subsets also got
+  smaller as a side effect (9.1 KB → 4.5 KB for a typical page).
+
+### Added
+
+- `render.test.ts` now asserts that the CIDs written to the page match the
+  ToUnicode CMap, so this class of regression fails the suite.
+
+## [0.3.0] - 2026-07-16
+
+### Fixed
+
+- **Japanese text rendered as blank boxes in every viewer** (Chrome, Firefox,
+  Acrobat, poppler, Claude Desktop). Font subsetting no longer goes through
+  pdf-lib's `embedFont(subset: true)`: fonts are now pre-subset with harfbuzz
+  ([subset-font](https://github.com/papandreou/subset-font)) and embedded with
+  `subset: false`.
+
+  fontkit's subsetter drops glyph outlines for CJK fonts. Because the ToUnicode
+  CMap stayed correct, text extraction kept working and the existing tests
+  passed while the visible output was broken.
+
+  | Approach | PDF size | Rendering |
+  |---|---|---|
+  | fontkit `subset: true` (previous) | 24 KB | broken |
+  | pdf-lib `subset: false` alone | 3.9 MB | correct |
+  | harfbuzz + `subset: false` (current) | 14.5 KB | correct |
+
+- The note in the design doc claiming poppler's `Embedded font file may be
+  invalid` warning was harmless is retracted — poppler followed it with
+  `Couldn't create a font`, i.e. the warning was the breakage.
+
+### Added
+
+- `render.test.ts`: extracts the embedded font program from generated PDFs and
+  verifies that every rendered character retains a real glyph outline. Verified
+  to fail against the pre-0.3.0 implementation.
+- CI fetches Noto Sans JP and sets `TEST_FONT_PATH`, so the font-dependent tests
+  no longer skip.
+
+### Changed
+
+- `loadFont` split into `openFont` (read + glyph coverage) and `embedFontFor`
+  (subset + embed). Subsetting depends on the text being drawn, so embedding is
+  deferred until the input is final.
+- **Dependency added**: `subset-font` (harfbuzz/wasm, no native binaries).
+
+## [0.2.1] - 2026-07-16
+
+### Added
+
+- **`onMissingGlyph` option** for the create tools. Characters absent from the
+  font (e.g. ✔ U+2714, which Noto Sans JP does not include) were previously
+  embedded as `.notdef` and rendered as silent blanks.
+  - `error` (default) — list the offending characters and fail
+  - `replace` — substitute 〓 and report via `warnings`
+  - `ignore` — render as before and report via `warnings`
+- `CreateResult.warnings` reports substituted or ignored characters.
+
+## [0.2.0] - 2026-07-16
+
+### Added
+
+- **Editing tools (Tier A, wave 1)** — the server now edits existing PDFs in
+  addition to creating them:
+  - `set_metadata` — update Info dictionary fields, preserving the rest
+  - `merge_pdfs` — concatenate in order (metadata inherited from the first file)
+  - `split_pdf` — one file per page range
+  - `extract_pages` — extract in the requested order (doubles as reordering)
+  - `delete_pages` — remove pages (deleting all is rejected)
+  - `reorder_pages` — reorder by an explicit permutation
+  - `rotate_pages` — rotate clockwise, accumulating over existing rotation
+- **Signature guard**: editing a PDF with `/ByteRange` fails by default, since
+  pdf-lib rewrites the whole file and would invalidate existing signatures.
+  Pass `allowBreakingSignatures: true` to proceed anyway.
+- Page specs (`"1,3-5,8-"`, 1-based, order-preserving, duplicates removed).
+- CI (`ci.yml`) and npm publish via Trusted Publisher / OIDC (`publish.yml`).
+
+## [0.1.0] - 2026-07-15
+
+Initial release.
+
+### Added
+
+- `create_text_pdf` — plain text with paragraph breaks, wrapping, pagination
+- `create_markdown_pdf` — headings, lists, code blocks, quotes, rules, tables
+- `create_table_pdf` — ruled tables with automatic column widths and repeated
+  headers across page breaks
+- Japanese font embedding, ToUnicode CMap (extractable/searchable text),
+  file or base64 output, `asserts`-based input validation.

package/README.ja.md

@@ -0,0 +1,141 @@
+# pdf-writer-mcp
+
+[![CI](https://github.com/shuji-bonji/pdf-writer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/shuji-bonji/pdf-writer-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@shuji-bonji/pdf-writer-mcp.svg)](https://www.npmjs.com/package/@shuji-bonji/pdf-writer-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+[English](./README.md)
+
+テキスト / Markdown / 表データからの **PDF 生成** と、既存 PDF の **編集**（メタデータ・ページ操作）を行う MCP (Model Context Protocol) サーバです。[pdf-lib](https://pdf-lib.js.org/) をコアに、harfbuzz サブセットによる日本語フォント埋め込みに対応します。
+
+[pdf-reader-mcp](https://github.com/shuji-bonji/pdf-reader-mcp)（構造解析）、[pdf-verify-mcp](https://github.com/shuji-bonji/pdf-verify-mcp)（真正性検証）と同じ PDF family の一員です。`pdf-reader-mcp` が「何があるか」を読み、`pdf-verify-mcp` が「本物か」を検証するのに対し、`pdf-writer-mcp` は「それを書く」役割を担います。
+
+## ツール
+
+### 生成
+
+| ツール | 役割 |
+|--------|------|
+| `create_text_pdf` | プレーンテキスト — `\n` で改行、空行で段落区切り、長い行は自動折り返し |
+| `create_markdown_pdf` | Markdown — 見出し / 段落 / 箇条書き・番号リスト / コードブロック / 引用 / 水平線 / 表 |
+| `create_table_pdf` | 罫線付き表 — 列幅の自動算出、セル内折り返し、改ページ時のヘッダ再描画 |
+
+共通オプション: `outputPath` / `returnBase64` / `fontPath` / `fontSize` / `pageSize`（A4/A3/A5/LETTER/LEGAL）/ `margin` / `title` / `author` / `onMissingGlyph`。
+
+### 編集
+
+| ツール | 役割 |
+|--------|------|
+| `set_metadata` | Info 辞書の更新（`title` / `author` / `subject` / `keywords` / `creator`）。指定フィールドのみ変更し、他は保持 |
+| `merge_pdfs` | 2〜50 個の PDF を指定順に結合。メタデータは先頭ファイルから引き継ぎ |
+| `split_pdf` | ページ範囲ごとに 1 ファイルへ分割 |
+| `extract_pages` | 指定順を保持して抽出（並べ替えを兼ねる） |
+| `delete_pages` | ページ削除（全ページの削除はエラー） |
+| `reorder_pages` | 全ページの順列による並べ替え |
+| `rotate_pages` | 時計回りに回転（90/180/270）。既存の回転に加算 |
+| `add_bookmarks` | しおり（アウトライン）の設定。`children` で入れ子にでき、既存のしおりは置換 |
+| `add_annotation` | 付箋（`text`）/ ハイライト（`highlight`）/ 矩形（`square`）の注釈を追加 |
+
+共通オプション: `outputPath` / `returnBase64` / `allowBreakingSignatures`。
+
+ページ指定は `"1,3-5,8-"` 形式（1 始まり。`-3` は先頭から 3 ページまで、`8-` は 8 ページから最終まで）。指定順を保持し、重複は除去します。
+
+> **署名について**: pdf-lib は保存時にファイル全体を再構築するため、編集すると既存の電子署名は必ず無効化されます。`/ByteRange` を含む PDF は既定でエラーとし、`allowBreakingSignatures: true` を指定したときのみ続行します。署名を保持する増分更新はロードマップ参照。
+
+## インストール
+
+```json
+{
+  "mcpServers": {
+    "pdf-writer": {
+      "command": "npx",
+      "args": ["-y", "@shuji-bonji/pdf-writer-mcp"],
+      "env": {
+        "PDF_WRITER_FONT": "/absolute/path/to/NotoSansJP-Regular.otf"
+      }
+    }
+  }
+}
+```
+
+`PDF_WRITER_FONT` を設定しておくと、各ツールで `fontPath` を省略しても日本語が出せます。
+
+## フォント
+
+標準 PDF フォント（Helvetica）は **ASCII のみ** です。日本語など非ラテン文字を描画するには、`fontPath` または `PDF_WRITER_FONT` で埋め込み可能な**単一フェイス**のフォント（`.ttf` / `.otf`）を指定してください。
+
+- 推奨入手先: [Noto Sans JP (SubsetOTF/JP)](https://github.com/notofonts/noto-cjk/tree/main/Sans/SubsetOTF/JP) — 静的・単一フェイス・SIL OFL。
+- **`.ttc`（TrueTypeCollection）は非対応**です。検知してエラーにするため、単一フェイスを抽出してください:
+
+  ```bash
+  python3 -c "from fontTools.ttLib import TTCollection; \
+    TTCollection('NotoSansCJK-Regular.ttc').fonts[0].save('NotoSansCJKjp-Regular.otf')"
+  ```
+
+### フォント未収録文字（グリフ欠落）
+
+フォントに存在しない文字（例: Noto Sans JP に無い ✔ U+2714）は、そのままだと `.notdef` として埋め込まれ、無警告で空白になります。`onMissingGlyph` でこの挙動を選べます。
+
+| 値 | 挙動 |
+|----|------|
+| `error`（既定） | 欠落文字を `"✔" (U+2714)` 形式で列挙してエラー |
+| `replace` | 〓 に置換して生成し、`warnings` で報告 |
+| `ignore` | 空白のまま生成し、`warnings` で報告 |
+
+## 返り値
+
+```jsonc
+{
+  "path": "/abs/out.pdf",     // outputPath 指定時
+  "base64": "JVBERi0xLj...",  // returnBase64 指定時、または outputPath 省略時
+  "pageCount": 3,
+  "bytes": 91788,
+  "font": "NotoSansJP-Regular.otf",
+  "warnings": ["Replaced 1 unsupported character(s) with \"〓\": \"✔\" (U+2714)"]
+}
+```
+
+編集ツールは `font` を除いた同じ形を返します。`split_pdf` は `{ files: [...], count }` を返します。
+
+## テキスト抽出
+
+生成される PDF はテキストの選択・コピー・全文検索・スクリーンリーダ読み上げが可能です。埋め込みサブセットフォントでも pdf-lib が ToUnicode CMap を出力するためで、この性質は回帰テスト（`extract.test.ts` / `render.test.ts`）で担保しています。
+
+> poppler 系のビューアは、OTF/CFF フォントを CIDFontType0 として埋め込む際に `Mismatch between font type and embedded font file` という警告を表示することがあります。これは無害で、描画・抽出とも正常です。
+
+## 開発
+
+```bash
+npm install
+npm run build      # dist/ に出力
+npm test           # vitest
+npm run typecheck  # tsc --noEmit
+```
+
+日本語フォント依存のテストは `TEST_FONT_PATH` を指定すると有効になります。
+
+```bash
+TEST_FONT_PATH=/path/to/NotoSansJP-Regular.otf npm test
+```
+
+## 既知の制約
+
+- **インライン装飾**: 太字・斜体はサイズ / 字面のみで、書体としては反映されません（1 文書につき単一フォントを埋め込むため）。
+- **`.ttc` フォント**: 単一フェイスへの抽出が必要です（上記参照）。
+- **サブセット名の接頭辞**: 慣習的な `ABCDEF+` を付けないため、一部ツールがサブセットでないと誤認します。描画・抽出には影響せず、PDF/A の厳密対応時のみ問題になります。
+
+## ロードマップ
+
+- [x] 編集系 Tier A 第1波 — メタデータ・ページ操作（v0.2.0）
+- [x] 編集系 Tier A 第2波 — しおり・注釈（v0.4.0）
+- [ ] 編集系 Tier B — フォーム記入 / フラット化、透かし、添付ファイル、ページ番号スタンプ
+- [ ] タグ付き PDF / PDF/UA（スクリーンリーダ向けの構造タグ）
+- [ ] `.ttc` からのフェイス自動抽出
+- [ ] 見出し用と本文用のフォント分け（太字フェイス埋め込み）
+- [ ] 画像埋め込み、ヘッダー / フッター
+- [ ] Tier C — 署名を保持する増分更新、本文テキスト編集、タグ木の保守
+- [ ] PDF/A 変換
+
+## ライセンス
+
+MIT © shuji-bonji

package/README.md

@@ -1,73 +1,55 @@
 # pdf-writer-mcp
 
-テキスト / Markdown / 表データからの **PDF 生成** と、既存 PDF の **編集**（メタデータ・ページ操作）を行う
-MCP (Model Context Protocol) サーバです。
-[pdf-lib](https://pdf-lib.js.org/) をコアに、日本語フォントの埋め込み（サブセット）に対応します。
-
-## 位置づけ
-
-`shuji-bonji` の PDF 系 MCP エコシステムにおける「生成（write）」担当です。
-読み取り・検証系とは責務を分けています。
-
-```mermaid
-graph LR
-  subgraph 生成
-    W[pdf-writer-mcp<br/>text/md/table→PDF]
-  end
-  subgraph 読取
-    R[pdf-reader-mcp<br/>抽出・検査]
-  end
-  subgraph 検証
-    V[pdf-verify-mcp<br/>署名・準拠性]
-  end
-  subgraph 仕様参照
-    S[pdf-spec-mcp<br/>ISO 32000]
-  end
-  W --> R
-  R --> V
-  S -.仕様根拠.-> W
-  S -.仕様根拠.-> V
-```
+[![CI](https://github.com/shuji-bonji/pdf-writer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/shuji-bonji/pdf-writer-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@shuji-bonji/pdf-writer-mcp.svg)](https://www.npmjs.com/package/@shuji-bonji/pdf-writer-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-## 特徴
+[日本語](./README.ja.md)
 
-- **3 つの生成ツール**: プレーンテキスト / Markdown / 表
-- **7 つの編集ツール**: メタデータ更新、結合・分割・抽出・削除・並べ替え・回転
-- **署名ガード**: 電子署名済み PDF（`/ByteRange` 検知）の編集は既定でエラーにし、
-  署名の意図しない無効化を防止（`allowBreakingSignatures: true` で明示的に続行可能）
-- **日本語対応**: `.ttf` / `.otf` フォントを harfbuzz でサブセット埋め込み（4.5MB のフォントでも出力は数十 KB）
-- **抽出・検索・コピー可能**: 埋め込みフォントでも ToUnicode CMap が付与されるため、
-  生成した PDF のテキストは選択・コピー・全文検索・スクリーンリーダ読み上げが可能
-- **自動レイアウト**: テキスト折り返し（日英混在・長語の強制分割）、改ページ、表の改ページ時ヘッダ再描画
-- **出力先の柔軟性**: ファイル保存 / base64 返却の両対応
-- **堅牢な入力検査**: `asserts` によるバリデーションで不正値を早期に弾く
+MCP server that **creates** PDFs from text, Markdown, or tabular data and **edits** existing ones (metadata and page operations). Built on [pdf-lib](https://pdf-lib.js.org/), with CJK font embedding via harfbuzz subsetting.
 
-## MCP クライアント設定
+Part of the PDF family alongside [pdf-reader-mcp](https://github.com/shuji-bonji/pdf-reader-mcp) (structure analysis) and [pdf-verify-mcp](https://github.com/shuji-bonji/pdf-verify-mcp) (authenticity verification). Where `pdf-reader-mcp` tells you *what is in* a PDF and `pdf-verify-mcp` tells you *whether it is genuine*, `pdf-writer-mcp` is the one that *writes it*.
 
-`claude_desktop_config.json`（例、npm 公開版を npx で起動）:
+## Tools
 
-```json
-{
-  "mcpServers": {
-    "pdf-writer": {
-      "command": "npx",
-      "args": ["-y", "@shuji-bonji/pdf-writer-mcp"],
-      "env": {
-        "PDF_WRITER_FONT": "/absolute/path/to/NotoSansJP-Regular.otf"
-      }
-    }
-  }
-}
-```
+### Creation
+
+| Tool | Purpose |
+|------|---------|
+| `create_text_pdf` | Plain text — honours `\n`, blank lines separate paragraphs, long lines wrap |
+| `create_markdown_pdf` | Markdown — headings, paragraphs, bullet/ordered lists, code blocks, quotes, rules, tables |
+| `create_table_pdf` | Ruled tables — automatic column widths, cell wrapping, headers repeated across page breaks |
 
-ローカルのソースから起動する場合:
+Shared options: `outputPath`, `returnBase64`, `fontPath`, `fontSize`, `pageSize` (A4/A3/A5/LETTER/LEGAL), `margin`, `title`, `author`, `onMissingGlyph`.
+
+### Editing
+
+| Tool | Purpose |
+|------|---------|
+| `set_metadata` | Update Info dictionary fields (`title` / `author` / `subject` / `keywords` / `creator`), preserving the rest |
+| `merge_pdfs` | Concatenate 2–50 PDFs in order; metadata inherited from the first file |
+| `split_pdf` | One output file per page range |
+| `extract_pages` | Extract pages in the requested order (doubles as reordering) |
+| `delete_pages` | Remove pages (deleting every page is rejected) |
+| `reorder_pages` | Reorder by an explicit permutation of all pages |
+| `rotate_pages` | Rotate clockwise (90/180/270), accumulating over existing rotation |
+| `add_bookmarks` | Set the outline (bookmarks); nestable via `children`, replaces any existing outline |
+| `add_annotation` | Add a sticky note (`text`), `highlight`, or `square` annotation to a page |
+
+Shared options: `outputPath`, `returnBase64`, `allowBreakingSignatures`.
+
+Page specs use `"1,3-5,8-"` (1-based; `-3` means up to page 3, `8-` means page 8 to the end). Order is preserved and duplicates are removed.
+
+> **Signatures**: pdf-lib rewrites the whole file on save, so editing always invalidates existing signatures. PDFs containing `/ByteRange` are rejected by default; pass `allowBreakingSignatures: true` to proceed anyway. Signature-preserving incremental updates are on the roadmap.
+
+## Install
 
 ```json
 {
   "mcpServers": {
     "pdf-writer": {
-      "command": "node",
-      "args": ["/absolute/path/to/pdf-writer-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@shuji-bonji/pdf-writer-mcp"],
       "env": {
         "PDF_WRITER_FONT": "/absolute/path/to/NotoSansJP-Regular.otf"
       }
@@ -76,147 +58,84 @@ graph LR
 }
 ```
 
-`PDF_WRITER_FONT` を設定しておくと、各ツールで `fontPath` を省略しても日本語が出せます。
-
-## 開発
+`PDF_WRITER_FONT` lets every tool omit `fontPath` and still render CJK text.
 
-```bash
-npm install
-npm run build      # dist/ に出力
-npm test           # vitest
-npm run typecheck  # tsc --noEmit
-```
+## Fonts
 
-## フォントについて（重要）
+The standard PDF font (Helvetica) covers **ASCII only**. To render Japanese or any non-Latin text, point `fontPath` or `PDF_WRITER_FONT` at an embeddable **single-face** font (`.ttf` / `.otf`).
 
-- 標準フォント（Helvetica）は **ASCII のみ**。日本語を含む場合は `fontPath` か `PDF_WRITER_FONT` で
-  埋め込み可能な **単一フォント（`.ttf` / `.otf`）** を指定してください。
-- **`.ttc`（TrueTypeCollection）は非対応**です（pdf-lib がサブセット化できないため、検知してエラーにします）。
-  `.ttc` しか手元にない場合は、単一フェイスを抽出してください。
+- Recommended source: [Noto Sans JP (SubsetOTF/JP)](https://github.com/notofonts/noto-cjk/tree/main/Sans/SubsetOTF/JP) — static, single-face, SIL OFL.
+- **`.ttc` (TrueType Collection) is not supported** — the file is detected and rejected. Extract a single face first:
 
   ```bash
-  # 例: Noto Sans CJK の .ttc から日本語フェイス(index 0)を .otf として取り出す
   python3 -c "from fontTools.ttLib import TTCollection; \
     TTCollection('NotoSansCJK-Regular.ttc').fonts[0].save('NotoSansCJKjp-Regular.otf')"
   ```
 
-- 日本語フォントの入手先の例:
-  [notofonts/noto-cjk の日本語サブセット OTF](https://github.com/notofonts/noto-cjk/tree/main/Sans/SubsetOTF/JP)（SIL OFL、静的・単一フェイス）。
+### Missing glyphs
 
-### フォント未収録文字（グリフ欠落）の扱い
+Characters absent from the font (e.g. ✔ U+2714, which Noto Sans JP does not include) would otherwise be embedded as `.notdef` and render as silent blanks. `onMissingGlyph` controls this:
 
-指定フォントに存在しない文字（例: Noto Sans JP に無い ✔ U+2714 や絵文字）を検知した場合の
-挙動を `onMissingGlyph` で選べます（v0.2.1〜）:
+| Value | Behaviour |
+|-------|-----------|
+| `error` (default) | Fail, listing the offending characters as `"✔" (U+2714)` |
+| `replace` | Substitute 〓 and report via `warnings` |
+| `ignore` | Render as blanks and report via `warnings` |
 
-| 値 | 挙動 |
-|----|------|
-| `error`（既定） | 欠落文字を `"✔" (U+2714)` 形式で列挙してエラー。無警告の空白出力を防ぐ |
-| `replace` | 〓（下駄記号）に置換して生成し、`warnings` で報告 |
-| `ignore` | そのまま生成（該当文字は空白になる）し、`warnings` で報告 |
-
-## ツール
-
-### `create_text_pdf`
-
-プレーンテキスト → PDF。`\n` で改行、空行で段落区切り。長い行は自動折り返し。
-
-| 引数 | 型 | 必須 | 説明 |
-|------|----|:---:|------|
-| `text` | string | ✓ | 本文 |
-| `outputPath` | string |  | 保存先。省略時は base64 を返す |
-| `returnBase64` | boolean |  | 保存に加えて base64 も返す |
-| `fontPath` | string |  | 埋め込むフォント（日本語は必須） |
-| `fontSize` | number |  | 本文サイズ pt（既定 11、4〜96） |
-| `pageSize` | enum |  | A4/A3/A5/LETTER/LEGAL（既定 A4） |
-| `margin` | number |  | 余白 pt（既定 56、0〜300） |
-| `title` | string |  | タイトル（メタデータ＋冒頭見出し） |
-| `author` | string |  | 作成者（メタデータ） |
-| `onMissingGlyph` | enum |  | フォント未収録文字の扱い: error（既定）/ replace / ignore |
-
-### `create_markdown_pdf`
-
-Markdown → PDF。対応要素: 見出し / 段落 / 箇条書き・番号リスト / コードブロック / 引用 / 水平線 / 表。
-インライン装飾（`**bold**` など）は単一フォントのため **記号を除去して字面のみ** 反映します。
-
-引数は `text` の代わりに `markdown`（string, 必須）。その他は共通。
-
-### `create_table_pdf`
-
-ヘッダ + 行データ → 罫線付きの表 PDF。列幅は内容から自動算出、セル内は折り返し、改ページ時はヘッダを再描画。
-
-| 引数 | 型 | 必須 | 説明 |
-|------|----|:---:|------|
-| `headers` | string[] | ✓ | 列見出し |
-| `rows` | string[][] | ✓ | データ行（各行は headers と同数の列を推奨） |
-
-その他は共通引数。
-
-## 編集ツール（v0.2.0〜）
-
-既存 PDF に対する操作です。共通引数: `outputPath`（省略時は base64 返却）/ `returnBase64` /
-`allowBreakingSignatures`（署名済み PDF の編集続行フラグ、既定 false）。
-
-ページ指定は `"1,3-5,8-"` 形式（1 始まり。`-3` = 先頭から 3 まで、`8-` = 8 から最終まで）。
-
-| ツール | 主な引数 | 説明 |
-|--------|----------|------|
-| `set_metadata` | `inputPath`, `title` / `author` / `subject` / `keywords` / `creator` | 指定フィールドのみ更新、他は保持 |
-| `merge_pdfs` | `inputPaths: string[]` | 指定順に結合（2〜50 ファイル） |
-| `split_pdf` | `inputPath`, `ranges: string[]`, `outputDir`, `prefix?` | 範囲ごとに連番ファイルへ分割 |
-| `extract_pages` | `inputPath`, `pages` | 指定順を保持して抽出（並べ替えを兼ねる） |
-| `delete_pages` | `inputPath`, `pages` | ページ削除（全削除はエラー） |
-| `reorder_pages` | `inputPath`, `order: number[]` | 全ページの順列で並べ替え |
-| `rotate_pages` | `inputPath`, `rotation: 90\|180\|270`, `pages?` | 時計回りに回転（既存回転に加算） |
-
-> **署名について**: pdf-lib はファイル全体を再構築して保存するため、編集すると既存の電子署名は
-> 必ず無効化されます。署名（`/ByteRange`）を検知した場合は既定でエラーとし、
-> `allowBreakingSignatures: true` を指定したときのみ続行します。
-> 署名を保持する増分更新は将来対応（ロードマップ参照）。
-
-### 返り値（共通）
+## Result
 
 ```jsonc
 {
-  "path": "/abs/out.pdf",   // outputPath 指定時
-  "base64": "JVBERi0xLj...", // returnBase64 or outputPath 未指定時
+  "path": "/abs/out.pdf",     // when outputPath is given
+  "base64": "JVBERi0xLj...",  // when returnBase64, or outputPath is omitted
   "pageCount": 3,
   "bytes": 91788,
-  "font": "NotoSansJP-Regular.otf"
+  "font": "NotoSansJP-Regular.otf",
+  "warnings": ["Replaced 1 unsupported character(s) with \"〓\": \"✔\" (U+2714)"]
 }
 ```
 
-## テキスト抽出・検索について
+Editing tools return the same shape without `font`; `split_pdf` returns `{ files: [...], count }`.
+
+## Text extraction
+
+Generated PDFs are selectable, copyable, searchable, and screen-reader accessible: pdf-lib emits a ToUnicode CMap even for embedded subset fonts. This is covered by regression tests (`extract.test.ts`, `render.test.ts`).
+
+> Some poppler-based viewers print `Mismatch between font type and embedded font file` for OTF/CFF fonts embedded as CIDFontType0. This is harmless — rendering and extraction are both correct.
+
+## Development
+
+```bash
+npm install
+npm run build      # emits dist/
+npm test           # vitest
+npm run typecheck  # tsc --noEmit
+```
 
-生成される PDF は **テキストの選択・コピー・全文検索が可能** です。
-埋め込みフォント使用時も pdf-lib が ToUnicode CMap（CID→Unicode の逆引き）を出力するため、
-`pdftotext` 等で本文を抽出できます。この性質は `tests/extract.test.ts` の回帰テストで担保しています
-（ToUnicode に `日 → U+65E5` のマッピングが含まれることを検証）。
+Font-dependent tests activate when `TEST_FONT_PATH` points at a CJK font:
 
-> **v0.3.0 の重要な修正**: v0.2.1 以前は pdf-lib（fontkit）のサブセッタを使っており、
-> 日本語フォントのグリフが破壊されて**すべてのビューアで文字が豆腐・空白になる**不具合がありました
-> （テキスト抽出だけは正常なため気づきにくい状態でした）。v0.3.0 で harfbuzz による事前サブセットに
-> 切り替え、サイズはより小さく（実測 24KB → 14.5KB）、描画は正常になっています。
+```bash
+TEST_FONT_PATH=/path/to/NotoSansJP-Regular.otf npm test
+```
 
-## 既知の制約
+## Known limitations
 
-- **インライン装飾**: 太字・斜体などはサイズ/字面のみで、書体としては反映されません
-  （見出し/本文/太字を別フェイスで埋め分ける対応はロードマップ参照）。
-- **`.ttc` 非対応**: 単一フェイスへの抽出が必要です（上記参照）。
-- **サブセット名の接頭辞**: pdf-lib は慣習的な `ABCDEF+` 接頭辞を付けないため、
-  一部ツールがサブセットでないと誤認します（表示・抽出には無影響。PDF/A 厳密対応時の項目）。
+- **Inline styling**: bold/italic affect size and glyph text only, not typeface — a single font is embedded per document.
+- **`.ttc` fonts** require extracting a single face (see above).
+- **Subset name prefix**: the conventional `ABCDEF+` prefix is not applied, so some tools report the font as non-subset. No effect on rendering or extraction; relevant only for strict PDF/A work.
 
-## ロードマップ
+## Roadmap
 
-- [x] 編集系 Tier A 第1波（メタデータ・ページ操作）— v0.2.0
-- [ ] 編集系 Tier A 第2波（しおり・注釈）
-- [ ] 編集系 Tier B（フォーム記入・フラット化 / 透かし / 添付ファイル / ページ番号スタンプ）
-- [ ] タグ付き PDF / PDF/UA 対応（スクリーンリーダ向けの構造タグ。抽出可否とは別レイヤの本格対応）
-- [ ] `.ttc` からのフェイス自動抽出（Node だけで完結）
-- [ ] 見出し用と本文用のフォント分け（太字フェイス埋め込み）
-- [ ] 画像埋め込み / ヘッダー・フッター
-- [ ] 署名を保持する増分更新・本文テキスト編集・タグ木保守（Tier C）
-- [ ] PDF/A 変換（サブセット命名の正規化を含む・外部ツール連携）
+- [x] Editing Tier A wave 1 — metadata and page operations (v0.2.0)
+- [x] Editing Tier A wave 2 — bookmarks and annotations (v0.4.0)
+- [ ] Editing Tier B — form filling/flattening, watermarks, attachments, page-number stamping
+- [ ] Tagged PDF / PDF/UA (structure tags for screen readers)
+- [ ] Automatic face extraction from `.ttc`
+- [ ] Separate faces for headings and body (bold face embedding)
+- [ ] Image embedding, headers/footers
+- [ ] Tier C — signature-preserving incremental updates, body text editing, tag tree maintenance
+- [ ] PDF/A conversion
 
-## ライセンス
+## License
 
 MIT © shuji-bonji

package/dist/constants.d.ts

@@ -33,7 +33,14 @@ export declare const LIMITS: {
     readonly MERGE_MAX_INPUTS: 50;
     /** split の最大分割数。暴走防止 */
     readonly SPLIT_MAX_PARTS: 200;
+    /** しおりの最大総数・最大ネスト深さ */
+    readonly BOOKMARK_MAX_TOTAL: 2000;
+    readonly BOOKMARK_MAX_DEPTH: 8;
 };
+/** add_annotation が受け付ける注釈種別 */
+export declare const ANNOTATION_TYPES: readonly ['text', 'highlight', 'square'];
+/** text 注釈のアイコン名（ISO 32000-1 Table 172 の一般的な値） */
+export declare const ANNOTATION_ICONS: readonly ['Note', 'Comment', 'Key', 'Help', 'NewParagraph', 'Paragraph', 'Insert'];
 /** rotate_pages が受け付ける回転角（時計回り・度） */
 export declare const ROTATION_ANGLES: readonly [90, 180, 270];
 /**

package/dist/constants.js

@@ -32,7 +32,22 @@ export const LIMITS = {
     MERGE_MAX_INPUTS: 50,
     /** split の最大分割数。暴走防止 */
     SPLIT_MAX_PARTS: 200,
+    /** しおりの最大総数・最大ネスト深さ */
+    BOOKMARK_MAX_TOTAL: 2_000,
+    BOOKMARK_MAX_DEPTH: 8,
 };
+/** add_annotation が受け付ける注釈種別 */
+export const ANNOTATION_TYPES = ['text', 'highlight', 'square'];
+/** text 注釈のアイコン名（ISO 32000-1 Table 172 の一般的な値） */
+export const ANNOTATION_ICONS = [
+    'Note',
+    'Comment',
+    'Key',
+    'Help',
+    'NewParagraph',
+    'Paragraph',
+    'Insert',
+];
 /** rotate_pages が受け付ける回転角（時計回り・度） */
 export const ROTATION_ANGLES = [90, 180, 270];
 /**

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IACrB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC;CACV,CAAC;AAIX;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,qBAAqB;IACrB,aAAa,EAAE,CAAC;IAChB,aAAa,EAAE,EAAE;IACjB,sCAAsC;IACtC,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,GAAG;IACf,6CAA6C;IAC7C,eAAe,EAAE,OAAO;IACxB,+BAA+B;IAC/B,cAAc,EAAE,EAAE;IAClB,cAAc,EAAE,KAAK;IACrB,4BAA4B;IAC5B,gBAAgB,EAAE,EAAE;IACpB,wBAAwB;IACxB,eAAe,EAAE,GAAG;CACZ,CAAC;AAEX,qCAAqC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAEvD;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,mCAAmC;IACnC,GAAG,EAAE,MAAM;CACH,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IACrB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC;CACV,CAAC;AAIX;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,qBAAqB;IACrB,aAAa,EAAE,CAAC;IAChB,aAAa,EAAE,EAAE;IACjB,sCAAsC;IACtC,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,GAAG;IACf,6CAA6C;IAC7C,eAAe,EAAE,OAAO;IACxB,+BAA+B;IAC/B,cAAc,EAAE,EAAE;IAClB,cAAc,EAAE,KAAK;IACrB,4BAA4B;IAC5B,gBAAgB,EAAE,EAAE;IACpB,wBAAwB;IACxB,eAAe,EAAE,GAAG;IACpB,uBAAuB;IACvB,kBAAkB,EAAE,KAAK;IACzB,kBAAkB,EAAE,CAAC;CACb,CAAC;AAEX,gCAAgC;AAChC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAEzE,kDAAkD;AAClD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM;IACN,SAAS;IACT,KAAK;IACL,MAAM;IACN,cAAc;IACd,WAAW;IACX,QAAQ;CACA,CAAC;AAEX,qCAAqC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAEvD;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,mCAAmC;IACnC,GAAG,EAAE,MAAM;CACH,CAAC"}

package/dist/services/annotation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Annotation
+ * pdf-lib の低レベル API で注釈辞書を組み立て、ページの /Annots に追加する。
+ *
+ * 対応（ISO 32000-1 §12.5.6）:
+ *   - text      : 付箋（Text annotation）。/Rect の左上にアイコン表示
+ *   - highlight : ハイライト（Highlight）。/QuadPoints が必須
+ *   - square    : 矩形（Square）
+ *
+ * 座標系は PDF 準拠（左下原点・pt）。生成系レンダラの top 基準とは異なる点に注意。
+ */
+import { PDFDocument, type RGB } from 'pdf-lib';
+import type { AddAnnotationArgs } from '../types/index.js';
+/** #rrggbb / #rgb を pdf-lib の RGB へ */
+export declare function parseHexColor(hex: string): RGB;
+/** 注釈をページに追加する。@returns 追加後のそのページの注釈数 */
+export declare function addAnnotation(doc: PDFDocument, args: AddAnnotationArgs): number;