外部（Claude in Chrome 等）から window.formBuilder を介して操作できます。座標とサイズはすべて A4 縦 (210mm × 297mm) の mm 単位、原点は左上です。例: 紙面の中央は x = 105mm。
getImageInfo() — 用紙情報を返す。戻り値は loaded（真偽値）、width（210）、height（297）、units（'mm'）、paper（'A4-portrait'）、imageWidth、imageHeight（参考: 元画像のピクセルサイズ）、fieldCount を持つオブジェクト。
addField(オブジェクト) — 欄を追加する。引数オブジェクトの中身：
- x — 数値、A4 上の横位置 mm（必須、範囲 0〜210）
- y — 数値、A4 上の縦位置 mm（必須、範囲 0〜297）
- width — 数値、欄の幅 mm（必須）
- height — 数値、欄の高さ mm（必須）
- value — 文字列、初期値（任意）
- label — 文字列、欄の名前（任意）
- fontSize — 数値、文字サイズ mm（任意、未指定時は欄の高さ × 0.55）
戻り値は追加した欄のID（文字列）。値は内部で 0.1mm 精度に丸められる。
listFields() — 現在の全フィールドを配列で返す。各要素は id、x、y、width、height、value、label、fontSize を持つ（すべて mm）。
updateField(id, props) — 指定IDの欄を更新する。props には変更したいプロパティのみ含めればよい（部分更新）。戻り値は成功時 true、IDが見つからなければ false。
removeField(id) — 指定IDの欄を削除する。
clear() — 全欄削除。
print() — 印刷ダイアログを開く。注意: Claude in Chrome 等のエージェントが制御したタブには可視化インジケータ (用紙外周の赤系の縁取り) が残り、`print()` 経由で PDF にすると焼き付きます。これは Cowork (Anthropic) 側の仕様で、ページ側 CSS では抑制できません。回避策: フィールド配置を終えた段階で、該当タブをタブバーごとドラッグして別ウィンドウへ分離するとインジケータがリセットされます。その状態でエージェントは触らず、ユーザーが UI の「印刷プレビュー」ボタンから印刷するとクリーンな PDF が得られます。分離後にエージェントが javascript_tool 等の実行系を叩くとそのウィンドウでインジケータが再点灯するため、分離 → 印刷の間はエージェント操作を控えること。
使い方の例
用紙は常に A4 縦 (210mm × 297mm)。読み込んだ画像は A4 にフィットして表示される。座標は紙面上の物理位置として考える: 例えば「氏名欄は左から20mm、上から50mm、幅80mm、高さ8mm」のように指定する。getImageInfo は確認用で、座標推定そのものには使わない (常に 210×297 が返る)。値を後から流し込む場合は updateField の value プロパティで更新する。
プリセットの保存と復元
同じ書式を繰り返し使う場合、最初の1回だけ座標推定をして配置情報を JSON として保存しておくと、次回からは1ステップで再現できます。paperscribe は保存先を持たないため (バックエンド不要の設計を維持)、JSON の書き出し・読み込みはエージェント側に委ねます。
- 保存:
listFields() を呼び、戻り値の配列を JSON でファイルに書き出す。各要素は x, y, width, height, value, label, fontSize を含む
- 復元: ファイルを読み込んで配列に戻し、各要素を
addField() に渡してループする。id は再発行されるが、座標・値・ラベルはそのまま再現される
- 推奨形式は
{ source, paper: 'A4-portrait', units: 'mm', fields: [...] }。samples/sample-form-positions.json にサンプルがある
頻出パターンの扱い (Tips)
- 「年 月 日」テンプレートのある日付欄: 日付文字列全体を1つの欄に置くのではなく、年・月・日の数字をそれぞれ別の addField で配置すること。例えば「2026年5月27日」を埋めるなら、「2026」を「年」の左、「5」を「月」の左、「27」を「日」の左に、3つのフィールドとして置く。
- チェックボックス・ラジオボタン: 専用UIはない。チェック対象のボックスの位置に「✓」や「レ」を1文字テキストとして addField で配置する。
- フリガナ欄: 対応する漢字欄の上にある小さな帯。漢字欄より高さを低めに (たとえば 4mm 程度)、文字サイズも小さめに (2.5mm 程度) 指定して配置する。
- 〒マーク付き郵便番号欄: 〒記号は既に書類に印字されているので含めない。郵便番号7桁の数字 (またはハイフン区切り) のみを 〒 の右隣に配置する。
- 罫線で区切られた表形式の欄: 「氏名」など1行に見える欄でも、罫線で囲まれた領域に対して1フィールドを置く。複数のセルがある表は、各セルごとに1フィールドずつ配置する。