evidence-marker (evimark)

スクリーンショットに 赤枠・コメント・両者を結ぶ矢印 を CLI で足して、.drawio.png （画像としてそのまま貼れて、Draw.io Integration でそのまま編集できる形式）を作ります。

• 1 回のコマンド実行 = 注釈 1 組 = draw.io のレイヤー 1 枚
• 座標はすべて 元スクリーンショットのピクセル座標
• 出力 PNG には注釈が焼き込まれ、同じファイルに draw.io の図（mxfile）も埋め込まれる

セットアップ

make setup          # npm ci && npm run build
npm link            # evimark をパスに通す（または node dist/cli.js で直接実行）

日本語フォント（assets/NotoSansJP-Regular.otf）はリポジトリに同梱しているので、 OS 側へのフォントインストールは不要です。ライセンスについてはライセンスを参照してください。

使い方

# 1) スクリーンショットを背景にした .drawio.png を作る
evimark init sample/サンプルサイト.png -o evidence.drawio.png

# 2) 赤枠とコメントのペアを 1 レイヤーとして追加（何度でも実行できる）
evimark add evidence.drawio.png \
  --rect 10,250,220,50 \
  --comment 310,250,320,60 \
  --text "STATUS: ONLINE | VER 2.0.4 と表示されていること"

evimark list   evidence.drawio.png          # レイヤー一覧
evimark remove evidence.drawio.png --last   # 直前のレイヤーを取り消す
evimark render evidence.drawio.png          # XML からラスタだけ焼き直す

add のオプション

| オプション | 既定 | 説明 | | --- | --- | --- | | --rect X,Y,W,H | — | 赤枠の位置とサイズ | | --comment X,Y[,W[,H]] | W=290 / H は本文から自動 | コメント枠の位置とサイズ | | --text <string> | — | コメント本文（--comment を使うなら必須）。改行できます → 複数行のコメント | | --layer <name> | 参照箇所N | レイヤー名 | | --no-arrow | — | 赤枠とコメントを結ぶ矢印を引かない | | --arrow-from <side> | 自動 | 矢印の出る辺 left/right/top/bottom | | --arrow-to <side> | 自動 | 矢印の刺さる辺 | | --rect-color <color> | #FF0000 | 赤枠の色 | | --rect-width <n> | 3 | 赤枠の線幅 | | --arrow-width <n> | 3 | 矢印の線幅。矢尻も連動して大きくなる |

--rect と --comment はどちらか一方だけでも構いません（片方だけのときは矢印は引かれません）。 両方あるときは、位置関係から矢印の出入りする辺が自動で選ばれます。

複数行のコメント

--text は改行を含められます。シェルの改行と <br> のどちらでも同じ結果になります。

# シェルの改行（bash / zsh の $'...'）
evimark add evidence.drawio.png --rect 10,250,220,50 --comment 320,240 \
  --text $'STATUS: ONLINE と表示されていること\nVER が 2.0.4 であること'

# <br>（シェルの種類を選ばない）
evimark add evidence.drawio.png --rect 10,250,220,50 --comment 320,240 \
  --text 'STATUS: ONLINE と表示されていること<br>VER が 2.0.4 であること'

--comment の H を省略していれば、枠の高さは行数に合わせて自動で広がります。 枠幅を超える長い行は指定しなくても折り返されるので、改行は「ここで必ず区切りたい」 箇所にだけ使ってください。

編集との往復

生成された .drawio.png は VS Code の Draw.io Integration でそのまま開けます （拡張機能は .devcontainer/devcontainer.json で自動インストールされます）。 draw.io 側で要素を動かして保存したあとでも、続けて evimark add できます。 draw.io が図を圧縮形式で保存した場合も読み込めます。

キャンバスは draw.io の PNG エクスポートと同じく全要素の外接矩形になるため、 背景画像の外にコメントを置くと、その分だけ余白が広がります。

仕組み

.drawio.png は「PNG ラスタ」＋「mxfile という keyword の tEXt チャンクに入った URL エンコード済み XML」という構造です。evimark は毎回この両方を更新します。

evimark add
  ├ tEXt から mxfile XML を取り出す
  ├ <root> の末尾にレイヤー 1 枚（赤枠 / コメント / 矢印）を追記
  ├ XML の内容を @napi-rs/canvas でラスタライズ
  └ 焼き上がった PNG に XML を埋め戻して上書き保存

既存の XML は文字列として温存したまま追記するので、draw.io が書いた属性順や整形は 崩れません。

コメント本文は draw.io の HTML ラベル（html=1）として保存されるため、--text の改行は <br> に変換してから書き込みます。生の改行のままだと XML の属性値正規化で空白 1 個に 潰れてしまい、焼き込み PNG では複数行なのに draw.io では 1 行、というズレが起きるためです。

| ファイル | 役割 | | --- | --- | | src/cli.ts | サブコマンドと引数の解釈 | | src/png.ts | PNG チャンクの読み書きと mxfile の出し入れ | | src/xmlscan.ts | 要素の範囲と属性だけを取る最小 XML スキャナ | | src/mxfile.ts | レイヤーの追記・削除、init の骨格生成 | | src/render.ts | ラスタ描画 | | src/style.ts | 色・線幅・フォントなどの既定値 |

src/style.ts の既定値は sample/sample.drawio.png（draw.io で手作業で作った見本）の スタイル文字列をそのまま踏襲しています。

テスト

make test

描画結果そのものは自動判定していません。見た目を確認するときは次を実行し、 sample/sample.drawio.png と見比べてください（同じ座標・同じ本文で作った見本です）。

evimark init sample/サンプルサイト.png -o /tmp/e.drawio.png
evimark add /tmp/e.drawio.png \
  --rect 10,250,220,50 --comment 310,250,320,60 \
  --text "STATUS: ONLINE | VER 2.0.4 と表示されていること"

ライセンス

evimark 本体（src/、test/、設定ファイル）は MIT License です。全文は LICENSE を参照してください。

同梱している日本語フォントだけは別ライセンス（SIL Open Font License 1.1）です。 再配布する際は下記に従ってください。

同梱フォントについて

assets/NotoSansJP-Regular.otf は Noto Sans JP（Copyright © 2014-2021 Adobe、 Noto は Google Inc. の商標）で、SIL Open Font License 1.1 の下で配布されています。 ライセンス全文と著作権表示は assets/NotoSansJP-Regular.LICENSE.txt に同梱しています。

OFL 1.1 はソフトウェアへのフォント同梱を明示的に許可しており（条件 2）、その代わりに 配布物のすべてのコピーに著作権表示とライセンス全文を含めることを求めます。 このリポジトリを再配布・公開する場合は、assets/NotoSansJP-Regular.LICENSE.txt を 必ず一緒に配布してください（package.json の files に assets が入っているため、 npm 公開時は自動的に含まれます）。

このフォントには Reserved Font Name の宣言がなく、evimark はフォントを改変せず そのまま埋め込むだけなので、条件 3（改変版の名称制限）は該当しません。 また条件 5 の「フォントは OFL のまま配布する」はフォントファイル自体に対する要求で、 evimark のコードや evimark が出力する PNG は OFL に縛られません。

フォントを取得し直す場合は make setup-font を使ってください （ライセンス全文も同時に取得され、置き去りになりません）。