@shuji-bonji/pdf-writer-mcp 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,129 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.6.0] - 2026-07-16
+
+### Added
+
+- **`fill_form`** — fill AcroForm fields: text, checkbox, dropdown, optionlist,
+  radio. Values are validated against the field's type and, for choice fields,
+  against its options; both errors name what the document actually offers.
+  Naming a field that does not exist lists the real field names, which is how a
+  caller discovers the form without a separate listing tool.
+
+  - Values are rendered with an **embedded font**, so Japanese works. pdf-lib
+    would otherwise regenerate every appearance with Helvetica on `save()` and
+    fail on `WinAnsi cannot encode "山"`; the font goes through the same
+    font-manager as the create tools (ADR-7/8).
+  - `flatten: true` fills and flattens in one pass.
+  - Filling does **not** touch the structure tree, so a tagged PDF keeps whatever
+    conformance it came in with.
+
+- **`flatten_form`** — flatten an AcroForm so the filled values become static
+  content, for fixing values before distribution.
+
+  - **Refuses tagged PDFs by default.** Flattening removes the Widget
+    annotations that the `Form` structure elements point to and bakes their
+    appearance in as untagged content. Measured, not assumed: veraPDF reports
+    `7.1-3 Content shall be marked as Artifact or tagged as real content`.
+    `allowBreakingTags: true` overrides and reports a warning.
+  - Drops the now-empty `/AcroForm` and prunes the dangling references that
+    pdf-lib's `flatten()` leaves behind in `/Annots` and `/Kids` (poppler
+    otherwise reports `Invalid XRef entry`).
+
+- **`add_watermark`** — overlay a diagonal watermark ("社外秘" / "DRAFT" /
+  "COPY") at the centre of each page.
+
+  - `text`, `fontSize` (60), `color` (`#808080`), `opacity` (0.15), `angle` (45),
+    `behind` (true), `pages`.
+  - **Behind the body content by default.** pdf-lib can only append to a content
+    stream, so the watermark is drawn and then moved to the front of the
+    `/Contents` array; each stream is self-contained in `q`/`Q`, so reordering is
+    safe.
+  - **Becomes an artifact on tagged PDFs** (PDF/UA-1 7.1-3). Verified: veraPDF
+    `ua1` 106/106.
+
+- **`stamp_page_numbers`** — stamp page numbers onto an existing PDF.
+
+  - `format` expands `{n}` and `{total}` (`{n} / {total}`, `- {n} -`, `{n} ページ`).
+  - `position` (six corners), `margin`, `fontSize`, `color`, `pages`, `startAt` —
+    `pages: "2-"` with `startAt: 1` numbers everything but the cover from 1.
+  - **Stamps become artifacts on tagged PDFs** (PDF/UA-1 7.1-3). Page numbers
+    carry no meaning for a screen reader, and content that is neither tagged nor
+    marked as an artifact breaks conformance. Verified: veraPDF `ua1` 106/106.
+  - Rotated pages (`/Rotate`) are compensated for, so "bottom-right" lands where
+    the reader sees the bottom right.
+  - The first editing tool that needs a font: it goes through the same
+    font-manager as the create tools, so harfbuzz subsetting (ADR-7/8) and the
+    missing-glyph check apply. Japanese formats need `fontPath` or
+    `PDF_WRITER_FONT`.
+
+### Changed
+
+- **biome adopted** for linting and formatting, matching the rest of the family
+  (same `biome.json`, same scripts). `npm run check` now runs in CI and in the
+  publish workflow. Existing sources were reformatted; the suite is clean.
+- The version is pinned to an exact `2.5.4` rather than a caret range. Biome's
+  formatting output changes between minor releases, so a range lets a local
+  `npm install` drift ahead of CI and produce spurious diffs.
+
+### Fixed
+
+- `parsePageSpec` reported an open-ended chunk past the end (`"2-"` on a 1-page
+  document) as *reversed* rather than *out of range* — the open end collapses to
+  `pageCount`, which made `from > to` trigger first.
+- `handleCreateTablePdf` duplicated the Latin-1 check as a regex containing
+  control characters; it now reuses the existing `hasNonLatin1` helper.
+- `src/config.ts` imports `node:module` rather than the bare `module` specifier.
+
+
+- **`attach_file`** — embed a file in a PDF (Tier B, first tool). Registers it in
+  `/Names /EmbeddedFiles`, references it from the catalog `/AF`, and sets
+  `/AFRelationship`. This is the shape PDF/A-3 (ISO 19005-3) requires, and the
+  one used to bundle a human-readable invoice with its machine-readable
+  counterpart (CSV/XML) in a single file — the 電子帳簿保存法 use case.
+
+  - `relationship`: `Data` (machine-readable counterpart), `Source` (the data the
+    document came from), `Alternative`, `Supplement`, `Unspecified` (default).
+    Omitting it produces a warning — PDF/A-3 §6.8 wants a meaningful value, and
+    `Unspecified` says nothing about why the file is there.
+  - `mimeType` is inferred from the extension when omitted (`.csv` → `text/csv`),
+    falling back to `application/octet-stream`.
+  - `name` renames the attachment inside the PDF; duplicates are rejected because
+    name-tree keys must be unique.
+  - Attaching to a tagged PDF leaves it conformant (verified: veraPDF `ua1`,
+    106/106).
+
+  Descriptions and names round-trip in Japanese, and attached bytes come back
+  byte-identical.
+
+## [0.5.1] - 2026-07-16
+
+### Added
+
+- **`add_annotation` keeps tagged PDFs conformant.** When the target document is
+  tagged, the annotation is now nested in an `Annot` structure element and the
+  page gets `/Tabs /S` — PDF/UA-1 7.18.1-1 and 7.18.3-1. Verified: adding an
+  annotation to a tagged document still passes veraPDF `--flavour ua1` (106/106).
+
+  This closes the gap 0.4.0 left behind: `add_annotation` shipped before tagging
+  existed, and veraPDF flagged it once 0.5.0 made tagged output possible.
+
+- **`alt` option on `add_annotation`** — the alternate text for the `Annot`
+  element. Omitting it on a tagged document produces a `warnings` entry rather
+  than silently emitting an annotation assistive technology cannot describe.
+
+### Notes
+
+`services/struct-append.ts` is a new counterpart to `struct-tree.ts`: the latter
+*builds* a tree from scratch (create tools), the former *appends* to an existing
+one (edit tools). Appending means reading `/ParentTreeNextKey`, inserting into
+the number tree while keeping keys ascending, and writing `/StructParent` back
+onto the annotation — the mechanics a future `ensure_tagged` (Tier C) will need.
+
+Untagged documents are left untouched: no structure tree is invented just because
+an annotation was added.
+
 ## [0.5.0] - 2026-07-16
 
 ### Added
@@ -47,23 +170,6 @@ All notable changes to this project will be documented in this file.
 - XMP metadata is written as UTF-8 bytes. `context.stream(string)` writes one
   byte per character, which mangled Japanese titles.
 
-## [Unreleased]
-
-### Changed
-
-- **biome adopted** for linting and formatting, matching the rest of the family
-  (same `biome.json`, same scripts). `npm run check` now runs in CI and in the
-  publish workflow. Existing sources were reformatted; the suite is clean.
-- The version is pinned to an exact `2.5.4` rather than a caret range. Biome's
-  formatting output changes between minor releases, so a range lets a local
-  `npm install` drift ahead of CI and produce spurious diffs.
-
-### Fixed
-
-- `handleCreateTablePdf` duplicated the Latin-1 check as a regex containing
-  control characters; it now reuses the existing `hasNonLatin1` helper.
-- `src/config.ts` imports `node:module` rather than the bare `module` specifier.
-
 ## [0.4.0] - 2026-07-16
 
 ### Added

package/README.ja.md

@@ -48,7 +48,12 @@ PDF/UA はタイトルを要求するため、`tagged: true` では `title` が
 | `reorder_pages` | 全ページの順列による並べ替え |
 | `rotate_pages` | 時計回りに回転（90/180/270）。既存の回転に加算 |
 | `add_bookmarks` | しおり（アウトライン）の設定。`children` で入れ子にでき、既存のしおりは置換 |
-| `add_annotation` | 付箋（`text`）/ ハイライト（`highlight`）/ 矩形（`square`）の注釈を追加 |
+| `add_annotation` | 付箋（`text`）/ ハイライト（`highlight`）/ 矩形（`square`）の注釈を追加。タグ付き PDF では `Annot` 構造要素に内包され PDF/UA 準拠を維持する（`alt` で説明を渡す） |
+| `attach_file` | ファイルを埋め込む（`/Names /EmbeddedFiles` + catalog `/AF` + `/AFRelationship`）。PDF/A-3 が要求する形式で、機械可読データを文書に同梱する |
+| `stamp_page_numbers` | ページ番号を刻む（`{n}` / `{total}`、6 箇所の配置、`pages`、`startAt`）。タグ付き PDF では Artifact になるため準拠を維持する |
+| `fill_form` | AcroForm に値を記入する。日本語は埋め込みフォントで描画。同時にフラット化も可能 |
+| `flatten_form` | フォームを静的な内容に焼き込む。タグ付き PDF は既定で拒否（PDF/UA が壊れるため） |
+| `add_watermark` | 斜めの透かしを重ねる（"社外秘" / "DRAFT"）。既定で本文の背面。タグ付き PDF では Artifact になる |
 
 共通オプション: `outputPath` / `returnBase64` / `allowBreakingSignatures`。
 
@@ -63,7 +68,7 @@ PDF/UA はタイトルを要求するため、`tagged: true` では `title` が
   "mcpServers": {
     "pdf-writer": {
       "command": "npx",
-      "args": ["-y", "@shuji-bonji/pdf-writer-mcp"],
+      "args": ["-y", "@shuji-bonji/pdf-writer-mcp@latest"],
       "env": {
         "PDF_WRITER_FONT": "/absolute/path/to/NotoSansJP-Regular.otf"
       }
@@ -74,6 +79,8 @@ PDF/UA はタイトルを要求するため、`tagged: true` では `title` が
 
 `PDF_WRITER_FONT` を設定しておくと、各ツールで `fontPath` を省略しても日本語が出せます。
 
+> **`@latest` を付ける（またはバージョンを固定する）ことを推奨します。** バージョン指定なしの `npx -y <pkg>` は、**最初にキャッシュした版を使い続けます**（`-y` はインストール確認を省くだけで、更新確認はしません）。数か月前の版が動き続けることもあります。`@latest` にすると起動のたびにレジストリを確認します。再現性を優先するなら `@0.5.0` のように固定してください。キャッシュを消すには `rm -rf ~/.npm/_npx`。
+
 ## フォント
 
 標準 PDF フォント（Helvetica）は **ASCII のみ** です。日本語など非ラテン文字を描画するには、`fontPath` または `PDF_WRITER_FONT` で埋め込み可能な**単一フェイス**のフォント（`.ttf` / `.otf`）を指定してください。
@@ -143,8 +150,10 @@ TEST_FONT_PATH=/path/to/NotoSansJP-Regular.otf npm test
 - [x] 編集系 Tier A 第1波 — メタデータ・ページ操作（v0.2.0）
 - [x] 編集系 Tier A 第2波 — しおり・注釈（v0.4.0）
 - [x] タグ付き PDF / PDF/UA-1 — veraPDF で準拠を確認（v0.5.0）
-- [ ] 編集系 Tier B — フォーム記入 / フラット化、透かし、添付ファイル、ページ番号スタンプ
-- [ ] 画像の代替テキスト（`Figure` + `/Alt`）、タグ付き出力での注釈の `Annot` タグ内包
+- [x] タグ付き出力での注釈の `Annot` タグ内包（v0.5.1）
+- [x] 編集系 Tier B — 添付ファイル（v0.6.0）
+- [ ] 編集系 Tier B — フォーム記入 / フラット化、透かし、ページ番号スタンプ
+- [ ] 画像の代替テキスト（`Figure` + `/Alt`）
 - [ ] `.ttc` からのフェイス自動抽出
 - [ ] 見出し用と本文用のフォント分け（太字フェイス埋め込み）
 - [ ] 画像埋め込み、ヘッダー / フッター

package/README.md

@@ -48,7 +48,12 @@ PDF/UA mandates a document title, so `tagged: true` requires `title`. `lang` (BC
 | `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 |
+| `add_annotation` | Add a sticky note (`text`), `highlight`, or `square` annotation to a page. On tagged PDFs the annotation is nested in an `Annot` element and stays PDF/UA conformant — pass `alt` to describe it |
+| `attach_file` | Embed a file (`/Names /EmbeddedFiles` + catalog `/AF` + `/AFRelationship`) — the PDF/A-3 shape for bundling machine-readable data with a document |
+| `stamp_page_numbers` | Stamp page numbers (`{n}` / `{total}`, six positions, `pages`, `startAt`). Becomes an artifact on tagged PDFs, so conformance holds |
+| `fill_form` | Fill AcroForm fields. Japanese values via an embedded font; can flatten in the same pass |
+| `flatten_form` | Flatten a form into static content. Refuses tagged PDFs by default (breaks PDF/UA) |
+| `add_watermark` | Overlay a diagonal watermark ("社外秘" / "DRAFT"). Behind the body content by default; artifact on tagged PDFs |
 
 Shared options: `outputPath`, `returnBase64`, `allowBreakingSignatures`.
 
@@ -63,7 +68,7 @@ Page specs use `"1,3-5,8-"` (1-based; `-3` means up to page 3, `8-` means page 8
   "mcpServers": {
     "pdf-writer": {
       "command": "npx",
-      "args": ["-y", "@shuji-bonji/pdf-writer-mcp"],
+      "args": ["-y", "@shuji-bonji/pdf-writer-mcp@latest"],
       "env": {
         "PDF_WRITER_FONT": "/absolute/path/to/NotoSansJP-Regular.otf"
       }
@@ -74,6 +79,8 @@ Page specs use `"1,3-5,8-"` (1-based; `-3` means up to page 3, `8-` means page 8
 
 `PDF_WRITER_FONT` lets every tool omit `fontPath` and still render CJK text.
 
+> **Use `@latest` (or pin a version).** `npx -y <pkg>` without a version keeps running whatever it cached the first time — `-y` only skips the install prompt, it does not check for updates. A bare specifier will happily run a months-old release. `@latest` makes npx check the registry on each start; pin `@0.5.0` instead if you want reproducibility. To clear a stale cache: `rm -rf ~/.npm/_npx`.
+
 ## 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`).
@@ -143,8 +150,10 @@ TEST_FONT_PATH=/path/to/NotoSansJP-Regular.otf npm test
 - [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)
 - [x] Tagged PDF / PDF/UA-1 — verified by veraPDF (v0.5.0)
-- [ ] Editing Tier B — form filling/flattening, watermarks, attachments, page-number stamping
-- [ ] Images with alt text (`Figure` + `/Alt`), annotations nested in `Annot` tags for tagged output
+- [x] Annotations nested in `Annot` tags on tagged output (v0.5.1)
+- [x] Editing Tier B — file attachments (v0.6.0)
+- [ ] Editing Tier B — form filling/flattening, watermarks, page-number stamping
+- [ ] Images with alt text (`Figure` + `/Alt`)
 - [ ] Automatic face extraction from `.ttc`
 - [ ] Separate faces for headings and body (bold face embedding)
 - [ ] Image embedding, headers/footers

package/dist/constants.d.ts

@@ -36,7 +36,30 @@ export declare const LIMITS: {
     /** しおりの最大総数・最大ネスト深さ */
     readonly BOOKMARK_MAX_TOTAL: 2000;
     readonly BOOKMARK_MAX_DEPTH: 8;
+    /** 埋め込みファイルの最大サイズ（バイト）。PDF 全体がメモリに載るため上限を設ける */
+    readonly ATTACHMENT_MAX_BYTES: number;
 };
+/** stamp_page_numbers の配置 */
+export declare const STAMP_POSITIONS: readonly ['bottom-left', 'bottom-center', 'bottom-right', 'top-left', 'top-center', 'top-right'];
+/** stamp_page_numbers の既定値 */
+export declare const STAMP_DEFAULTS: {
+    readonly format: '{n}';
+    readonly position: 'bottom-center';
+    readonly margin: 24;
+    readonly fontSize: 9;
+    readonly color: '#666666';
+    readonly startAt: 1;
+};
+/** add_watermark の既定値 */
+export declare const WATERMARK_DEFAULTS: {
+    readonly fontSize: 60;
+    readonly color: '#808080';
+    readonly opacity: 0.15;
+    readonly angle: 45;
+    readonly behind: true;
+};
+/** attach_file が受け付ける AFRelationship（PDF/A-3 §6.8） */
+export declare const ATTACHMENT_RELATIONSHIPS: readonly ['Source', 'Data', 'Alternative', 'Supplement', 'Unspecified'];
 /** add_annotation が受け付ける注釈種別 */
 export declare const ANNOTATION_TYPES: readonly ['text', 'highlight', 'square'];
 /** text 注釈のアイコン名（ISO 32000-1 Table 172 の一般的な値） */

package/dist/constants.js

@@ -35,7 +35,43 @@ export const LIMITS = {
     /** しおりの最大総数・最大ネスト深さ */
     BOOKMARK_MAX_TOTAL: 2_000,
     BOOKMARK_MAX_DEPTH: 8,
+    /** 埋め込みファイルの最大サイズ（バイト）。PDF 全体がメモリに載るため上限を設ける */
+    ATTACHMENT_MAX_BYTES: 100 * 1024 * 1024,
 };
+/** stamp_page_numbers の配置 */
+export const STAMP_POSITIONS = [
+    'bottom-left',
+    'bottom-center',
+    'bottom-right',
+    'top-left',
+    'top-center',
+    'top-right',
+];
+/** stamp_page_numbers の既定値 */
+export const STAMP_DEFAULTS = {
+    format: '{n}',
+    position: 'bottom-center',
+    margin: 24,
+    fontSize: 9,
+    color: '#666666',
+    startAt: 1,
+};
+/** add_watermark の既定値 */
+export const WATERMARK_DEFAULTS = {
+    fontSize: 60,
+    color: '#808080',
+    opacity: 0.15,
+    angle: 45,
+    behind: true,
+};
+/** attach_file が受け付ける AFRelationship（PDF/A-3 §6.8） */
+export const ATTACHMENT_RELATIONSHIPS = [
+    'Source',
+    'Data',
+    'Alternative',
+    'Supplement',
+    'Unspecified',
+];
 /** add_annotation が受け付ける注釈種別 */
 export const ANNOTATION_TYPES = ['text', 'highlight', 'square'];
 /** text 注釈のアイコン名（ISO 32000-1 Table 172 の一般的な値） */

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;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;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAExD;;;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;IACrB,gDAAgD;IAChD,oBAAoB,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;CAC/B,CAAC;AAEX,6BAA6B;AAC7B,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,aAAa;IACb,eAAe;IACf,cAAc;IACd,UAAU;IACV,YAAY;IACZ,WAAW;CACH,CAAC;AAEX,8BAA8B;AAC9B,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,KAAK;IACb,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,EAAE;IACV,QAAQ,EAAE,CAAC;IACX,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,CAAC;CACF,CAAC;AAEX,yBAAyB;AACzB,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,QAAQ,EAAE,EAAE;IACZ,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,IAAI;CACJ,CAAC;AAEX,sDAAsD;AACtD,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,QAAQ;IACR,MAAM;IACN,aAAa;IACb,YAAY;IACZ,aAAa;CACL,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;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAExD;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,mCAAmC;IACnC,GAAG,EAAE,MAAM;CACH,CAAC"}

package/dist/services/annotation.d.ts

@@ -9,9 +9,17 @@
  *
  * 座標系は PDF 準拠（左下原点・pt）。生成系レンダラの top 基準とは異なる点に注意。
  */
-import { type PDFDocument, type RGB } from 'pdf-lib';
+import { type PDFDocument, type PDFPage, type PDFRef, 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;
+export interface AddedAnnotation {
+    /** 追加後のそのページの注釈数 */
+    count: number;
+    /** 追加した注釈への参照（構造木へ結び付けるのに使う） */
+    ref: PDFRef;
+    /** 対象ページ */
+    page: PDFPage;
+}
+/** 注釈をページに追加する */
+export declare function addAnnotation(doc: PDFDocument, args: AddAnnotationArgs): AddedAnnotation;

package/dist/services/annotation.js

@@ -25,7 +25,7 @@ export function parseHexColor(hex) {
 function colorArray(doc, color) {
     return doc.context.obj([color.red, color.green, color.blue]);
 }
-/** 注釈をページに追加する。@returns 追加後のそのページの注釈数 */
+/** 注釈をページに追加する */
 export function addAnnotation(doc, args) {
     const pages = doc.getPages();
     const pageIndex = args.page - 1;
@@ -74,8 +74,9 @@ export function addAnnotation(doc, args) {
         annots = context.obj([]);
         page.node.set(PDFName.of('Annots'), annots);
     }
-    annots.push(context.register(dict));
-    return annots.size();
+    const ref = context.register(dict);
+    annots.push(ref);
+    return { count: annots.size(), ref, page };
 }
 function defaultColor(type) {
     switch (type) {

package/dist/services/annotation.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotation.js","sourceRoot":"","sources":["../../src/services/annotation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"annotation.js","sourceRoot":"","sources":["../../src/services/annotation.ts"],"names":[],"mappings":"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"}

package/dist/services/attachment.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Embedded files (attachments)
+ *
+ * PDF に別ファイルを埋め込む（ISO 32000-1 §7.11.4 / §14.13）。
+ * pdf-lib の `doc.attach()` が /Names /EmbeddedFiles・catalog /AF・/UF・/Params まで
+ * 書いてくれるため、本モジュールは
+ *   - 入力の検証（存在・サイズ・重複名）
+ *   - MIME 型の推定
+ *   - AFRelationship の既定値と用途の説明
+ *   - 既存の添付一覧の読み取り
+ * を担う。
+ *
+ * PDF/A-3（ISO 19005-3）と電子帳簿保存法の文脈:
+ *   PDF/A-3 は任意形式のファイルを埋め込める唯一の PDF/A 部で、
+ *   「人が読む請求書（PDF）＋機械可読データ（CSV/XML）」を 1 ファイルに束ねる用途に使う。
+ *   その際 /AFRelationship は必須で、機械可読データなら Data、
+ *   元データなら Source を指定する（§6.8）。
+ */
+import { type PDFDocument } from 'pdf-lib';
+import type { AttachmentRelationship } from '../types/index.js';
+export declare function guessMimeType(fileName: string): string;
+export interface EmbeddedFileInfo {
+    name: string;
+    description?: string;
+    relationship?: string;
+    mimeType?: string;
+}
+/** 既に埋め込まれているファイルの一覧を返す */
+export declare function listEmbeddedFiles(doc: PDFDocument): EmbeddedFileInfo[];
+export interface AttachFileOptions {
+    /** 埋め込むファイルのパス */
+    filePath: string;
+    /** PDF 内での表示名。省略時は元のファイル名 */
+    name?: string;
+    /** 説明（/Desc） */
+    description?: string;
+    /** MIME 型。省略時は拡張子から推定 */
+    mimeType?: string;
+    /** PDF/A-3 §6.8 の関係。既定 Unspecified */
+    relationship?: AttachmentRelationship;
+}
+export interface AttachedFile {
+    name: string;
+    bytes: number;
+    mimeType: string;
+    relationship: string;
+}
+/**
+ * ファイルを PDF に埋め込む。
+ * 同名の添付が既にある場合はエラー（名前ツリーのキーは一意であるべき）。
+ */
+export declare function attachFile(doc: PDFDocument, options: AttachFileOptions): Promise<AttachedFile>;

package/dist/services/attachment.js

@@ -0,0 +1,145 @@
+/**
+ * Embedded files (attachments)
+ *
+ * PDF に別ファイルを埋め込む（ISO 32000-1 §7.11.4 / §14.13）。
+ * pdf-lib の `doc.attach()` が /Names /EmbeddedFiles・catalog /AF・/UF・/Params まで
+ * 書いてくれるため、本モジュールは
+ *   - 入力の検証（存在・サイズ・重複名）
+ *   - MIME 型の推定
+ *   - AFRelationship の既定値と用途の説明
+ *   - 既存の添付一覧の読み取り
+ * を担う。
+ *
+ * PDF/A-3（ISO 19005-3）と電子帳簿保存法の文脈:
+ *   PDF/A-3 は任意形式のファイルを埋め込める唯一の PDF/A 部で、
+ *   「人が読む請求書（PDF）＋機械可読データ（CSV/XML）」を 1 ファイルに束ねる用途に使う。
+ *   その際 /AFRelationship は必須で、機械可読データなら Data、
+ *   元データなら Source を指定する（§6.8）。
+ */
+import { readFile } from 'node:fs/promises';
+import { basename, extname, resolve } from 'node:path';
+import { AFRelationship, PDFArray, PDFDict, PDFName } from 'pdf-lib';
+import { LIMITS } from '../constants.js';
+/** 拡張子 → MIME 型（電帳法・請求まわりで実際に使うものに絞る） */
+const MIME_TYPES = {
+    '.csv': 'text/csv',
+    '.xml': 'application/xml',
+    '.json': 'application/json',
+    '.txt': 'text/plain',
+    '.pdf': 'application/pdf',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.xls': 'application/vnd.ms-excel',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.doc': 'application/msword',
+    '.zip': 'application/zip',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.html': 'text/html',
+};
+const DEFAULT_MIME = 'application/octet-stream';
+export function guessMimeType(fileName) {
+    return MIME_TYPES[extname(fileName).toLowerCase()] ?? DEFAULT_MIME;
+}
+/** pdf-lib の AFRelationship へ変換する */
+function toAFRelationship(rel) {
+    switch (rel) {
+        case 'Source':
+            return AFRelationship.Source;
+        case 'Data':
+            return AFRelationship.Data;
+        case 'Alternative':
+            return AFRelationship.Alternative;
+        case 'Supplement':
+            return AFRelationship.Supplement;
+        default:
+            return AFRelationship.Unspecified;
+    }
+}
+/** 既に埋め込まれているファイルの一覧を返す */
+export function listEmbeddedFiles(doc) {
+    const names = doc.catalog.lookup(PDFName.of('Names'));
+    if (!(names instanceof PDFDict))
+        return [];
+    const ef = names.lookup(PDFName.of('EmbeddedFiles'));
+    if (!(ef instanceof PDFDict))
+        return [];
+    const arr = ef.lookup(PDFName.of('Names'));
+    if (!(arr instanceof PDFArray))
+        return [];
+    const out = [];
+    // 名前ツリーの /Names は [name1, spec1, name2, spec2, ...]
+    for (let i = 0; i + 1 < arr.size(); i += 2) {
+        const nameObj = arr.lookup(i);
+        const spec = arr.lookup(i + 1);
+        const name = decodeName(nameObj);
+        if (name === null)
+            continue;
+        const info = { name };
+        if (spec instanceof PDFDict) {
+            const desc = spec.lookup(PDFName.of('Desc'));
+            const decoded = decodeName(desc);
+            if (decoded)
+                info.description = decoded;
+            const rel = spec.lookup(PDFName.of('AFRelationship'));
+            if (rel instanceof PDFName)
+                info.relationship = rel.decodeText();
+            const efDict = spec.lookup(PDFName.of('EF'));
+            if (efDict instanceof PDFDict) {
+                const stream = efDict.get(PDFName.of('F'));
+                const resolved = stream ? doc.context.lookup(stream) : undefined;
+                const subtype = resolved && 'dict' in resolved
+                    ? resolved.dict.get(PDFName.of('Subtype'))
+                    : undefined;
+                if (subtype instanceof PDFName)
+                    info.mimeType = subtype.decodeText();
+            }
+        }
+        out.push(info);
+    }
+    return out;
+}
+/** PDFString / PDFHexString のいずれでもテキストとして読む */
+function decodeName(value) {
+    if (value && typeof value === 'object' && 'decodeText' in value) {
+        return value.decodeText();
+    }
+    return null;
+}
+/**
+ * ファイルを PDF に埋め込む。
+ * 同名の添付が既にある場合はエラー（名前ツリーのキーは一意であるべき）。
+ */
+export async function attachFile(doc, options) {
+    const abs = resolve(options.filePath);
+    let bytes;
+    try {
+        bytes = await readFile(abs);
+    }
+    catch {
+        throw new Error(`Cannot read the file to attach: ${abs}`);
+    }
+    if (bytes.length > LIMITS.ATTACHMENT_MAX_BYTES) {
+        throw new Error(`Attachment is too large (${bytes.length} bytes, max ${LIMITS.ATTACHMENT_MAX_BYTES})`);
+    }
+    const name = options.name ?? basename(abs);
+    if (name.trim() === '') {
+        throw new Error('name must not be empty');
+    }
+    const existing = listEmbeddedFiles(doc);
+    if (existing.some((f) => f.name === name)) {
+        throw new Error(`An attachment named "${name}" already exists in this PDF. Pass a different "name".`);
+    }
+    const mimeType = options.mimeType ?? guessMimeType(name);
+    const relationship = options.relationship ?? 'Unspecified';
+    const stat = { creationDate: new Date(), modificationDate: new Date() };
+    await doc.attach(bytes, name, {
+        mimeType,
+        description: options.description,
+        afRelationship: toAFRelationship(relationship),
+        ...stat,
+    });
+    return { name, bytes: bytes.length, mimeType, relationship };
+}
+//# sourceMappingURL=attachment.js.map

package/dist/services/attachment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.js","sourceRoot":"","sources":["../../src/services/attachment.ts"],"names":[],"mappings":"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"}

package/dist/services/editor.d.ts

@@ -12,7 +12,7 @@
  *   allowBreakingSignatures: true があるときのみ続行する。
  *   署名を保持する増分更新（incremental_save）は Tier C の課題。
  */
-import type { AddAnnotationArgs, AddBookmarksArgs, CommonEditOptions, EditResult, SetMetadataArgs, SplitResult } from '../types/index.js';
+import type { AddAnnotationArgs, AddBookmarksArgs, AddWatermarkArgs, AttachFileArgs, AttachResult, CommonEditOptions, EditResult, FillFormArgs, FlattenFormArgs, FormResult, SetMetadataArgs, SplitResult, StampPageNumbersArgs, StampResult, WatermarkResult } from '../types/index.js';
 /** 入力バイト列に電子署名（/ByteRange）が含まれるかの軽量検査 */
 export declare function containsSignature(bytes: Uint8Array): boolean;
 export declare function setMetadata(args: SetMetadataArgs): Promise<EditResult>;
@@ -23,4 +23,9 @@ export declare function reorderPages(inputPath: string, order: number[], opts: C
 export declare function rotatePages(inputPath: string, rotation: number, pages: string | undefined, opts: CommonEditOptions): Promise<EditResult>;
 export declare function addBookmarks(args: AddBookmarksArgs): Promise<EditResult>;
 export declare function addAnnotation(args: AddAnnotationArgs): Promise<EditResult>;
+export declare function attachFileToPdf(args: AttachFileArgs): Promise<AttachResult>;
+export declare function stampPageNumbers(args: StampPageNumbersArgs): Promise<StampResult>;
+export declare function addWatermark(args: AddWatermarkArgs): Promise<WatermarkResult>;
+export declare function fillForm(args: FillFormArgs): Promise<FormResult>;
+export declare function flattenForm(args: FlattenFormArgs): Promise<FormResult>;
 export declare function splitPdf(inputPath: string, ranges: string[], outputDir: string, prefix: string | undefined, opts: CommonEditOptions): Promise<SplitResult>;