既存のWebアプリに注釈UIを足すViteプラグイン「Markable」を作った

成果物

Webアプリに注釈とコメントの機能を追加するViteプラグインを作りました。既存の画面にレイヤーを重ね、右下のボタンから対象要素や画面範囲を選んでコメントできます。

GitHub - f4ah6o/markable

Contribute to f4ah6o/markable development by creating an account on GitHub.

GitHub

動くサンプルはこちらです。別の方が作ったWebアプリのサンプルにMarkableを追加しています。

https://f4ah6o.github.io/markable/

Vue Todoデモでは、既存の画面へ注釈UIを重ねています。

Vue TodoデモにMarkableの注釈UIを重ねた画面

オリジナルのサンプルページと並べると、アプリ本体はそのままで、右下にfeedbackボタンだけが追加されていることがわかります。

オリジナルのVue TodoデモとMarkableを追加したVue Todoデモの比較

本番向けのfeedbackモードでは、右下にフィードバックを想定したボタンを表示します。

コメント対象は、DOM要素として選ぶことも、画面上の矩形範囲として選ぶこともできます。

要素選択とBox選択をしている Markable の画面

登録後は、最近のマークとして画面上に残ります。 JSONボタンから、対象要素やビューポートなどを含むデータをコピーできます。

Markableで登録したコメントが最近のマークとして表示された画面

きっかけ

Codex appのIn-appブラウザにある注釈機能が便利だと思っていたところ、次のポストを見つけました。

Yuichi Uemura (@u1) on X

codex/claude codeでhtmlレポート作成をリッチにするプラグインを公開しました｡notionみたいにコメントを入れてそれをAIが読んで直すというワークフローをローカルで実現出来ます https://t.co/fQslonzHGx

X (formerly Twitter)

リポジトリはこちらです。 MITライセンスで公開されています。

GitHub - u-ichi/reviewable-html-workbench: Claude Code / Codex CLI plugin for generating reviewable HTML documents with preview, inline review comments, and agent feedback ingestion.

Claude Code / Codex CLI plugin for generating reviewable HTML documents with preview, inline review comments, and agent feedback ingestion. - u-ichi/reviewable-html-workbench

GitHub

注釈UI/UXはエージェントと人間のやり取りだけでなく、人間同士の不具合報告、フィードバックにも使えそうだと感じました。

Viteプラグインにした理由

欲しかったのは、アプリの本体とは別に差し込める注釈レイヤーです。

開発中のレビューでも、運用中のフィードバックでも、必要な操作はあまり変わりません。起動するボタンがあり、画面上の要素や範囲を選び、コメントを入力できればよいはずです。

そのため、できるだけ既存の実装を触らずに追加できる形にしたくなりました。最初に思いついたのがViteプラグインです。 Viteのアプリであれば、プラグインを設定するだけで同じ注釈UIを追加できます。

設定方法

使う側で必要なのは、パッケージのインストールと vite.config.ts への追加です。

pnpm add @f12o/markable

Viteの設定では、通常のプラグインと同じようにpluginsへ追加します。

import { defineConfig } from "vite";
import { markable } from "@f12o/markable/vite";

export default defineConfig({
  plugins: [
    markable({
      mode: "auto",
      locale: "ja",
      commentsFile: ".markable/comments.json",
      endpoint: "/__markable/comments",
      poweredBy: true,
    }),
  ],
});

mode: "auto"にすると、Viteの開発時はreviewモード、本番ビルド時はfeedbackモードになります。開発中はレビュー用の「Mark」ボタンを出し、本番では利用者向けの「Feedback」ボタンを出す想定です。

commentsFileは、開発サーバーで投稿された注釈を保存する JSONファイルです。 endpoint は、そのJSONを読み書きするためのローカルエンドポイントです。静的な GitHub PagesではPOST先がないため、外部の保存先を設定しない限り、投稿内容はそのセッション内の表示に留まります。

locale には "en" と "ja" を指定できます。ボタン、入力欄、保存後の表示など、Markable が注入する UI の文言が切り替わります。

アプリ本体のコンポーネントは変更しません。 Vite プラグインがHTMLにMarkableのクライアントスクリプトを注入します。

実装まで

初期実装はCodexもClaude Codeも使わず、チャットで進めました。 Vite プラグインとして実装できそうだとわかり、そのまま GitHub プラグインからリポジトリを操作し、コードまで書いてもらいました。

リポジトリの作成と GitHub Pages の設定は、iPhone のブラウザから行いました。パソコンを開かなくても、GitHub Pages にデプロイしたサンプルページまで確認できました。

今後は、

登録済みの注釈位置にピンを表示
エージェントと共有する動線の確立

などを追加できればと思います。