From 847d5f6a7b435a632ab055f7faf14aa319f83bda Mon Sep 17 00:00:00 2001
From: Yuma Ishikawa <yuma.fuu05@gmail.com>
Date: Wed, 5 Aug 2026 17:15:56 +0900
Subject: [PATCH 1/5] feat(mdp): markdown preview with google-docs-style PR
 review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mdp renders GitHub-flavored markdown through the GitHub API and serves it
locally. For a pull request it previews every changed markdown file and
turns the page into a Google Docs-style review surface:

- left sidebar with the changed files (common path prefixes trimmed) and
  the active file's outline nested beneath it, with scroll-spy
- review comments in a right margin column, aligned to the text they
  reference; PR conversation comments and unanchorable threads group at
  the top under 行に紐づかないコメント
- select text to comment on a range: the quote plus a hidden mdp:range
  marker go into the comment body, so mdp can re-highlight the exact
  range later while GitHub still shows a normal line comment
- reply by clicking a card, resolve with the blue check, and react with
  GitHub's eight emoji
- mermaid blocks rendered as diagrams, light/dark themes, font-size cycle

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-07-07-mdp-pr-comments.md       |  858 ++++++++++++
 .../plans/2026-07-16-mdp-post-comments.md     | 1185 +++++++++++++++++
 .../plans/2026-08-04-mdp-gdocs-layout.md      |   58 +
 .../2026-06-23-mdp-markdown-preview-design.md |  117 ++
 .../2026-07-07-mdp-pr-comments-design.md      |   89 ++
 .../2026-07-16-mdp-post-comments-design.md    |   75 ++
 .../2026-07-17-mdp-ja-typography-design.md    |   21 +
 .../2026-08-04-mdp-gdocs-layout-design.md     |   29 +
 tools/mdp/.gitignore                          |   22 +
 tools/mdp/README.md                           |   76 ++
 tools/mdp/bun.lock                            |   31 +
 tools/mdp/mdp.ts                              |  336 +++++
 tools/mdp/package.json                        |   18 +
 tools/mdp/src/args.test.ts                    |   35 +
 tools/mdp/src/args.ts                         |   27 +
 tools/mdp/src/comments.test.ts                |  468 +++++++
 tools/mdp/src/comments.ts                     |  325 +++++
 tools/mdp/src/input.test.ts                   |   71 +
 tools/mdp/src/input.ts                        |   79 ++
 tools/mdp/src/links.test.ts                   |   45 +
 tools/mdp/src/links.ts                        |   26 +
 tools/mdp/src/mermaid.test.ts                 |   64 +
 tools/mdp/src/mermaid.ts                      |   41 +
 tools/mdp/src/post.test.ts                    |  381 ++++++
 tools/mdp/src/post.ts                         |  313 +++++
 tools/mdp/src/pr.test.ts                      |   64 +
 tools/mdp/src/pr.ts                           |   78 ++
 tools/mdp/src/render.test.ts                  |   50 +
 tools/mdp/src/render.ts                       |   43 +
 tools/mdp/src/resolve.test.ts                 |   57 +
 tools/mdp/src/server.test.ts                  |   85 ++
 tools/mdp/src/server.ts                       |   95 ++
 tools/mdp/src/tabs.test.ts                    |   34 +
 tools/mdp/src/tabs.ts                         |   17 +
 tools/mdp/src/template.test.ts                |  189 +++
 tools/mdp/src/template.ts                     |  852 ++++++++++++
 tools/mdp/src/toc.test.ts                     |   44 +
 tools/mdp/src/toc.ts                          |   35 +
 tools/mdp/themes/designdoc.css                |  156 +++
 tools/mdp/tsconfig.json                       |   14 +
 40 files changed, 6603 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-07-mdp-pr-comments.md
 create mode 100644 docs/superpowers/plans/2026-07-16-mdp-post-comments.md
 create mode 100644 docs/superpowers/plans/2026-08-04-mdp-gdocs-layout.md
 create mode 100644 docs/superpowers/specs/2026-06-23-mdp-markdown-preview-design.md
 create mode 100644 docs/superpowers/specs/2026-07-07-mdp-pr-comments-design.md
 create mode 100644 docs/superpowers/specs/2026-07-16-mdp-post-comments-design.md
 create mode 100644 docs/superpowers/specs/2026-07-17-mdp-ja-typography-design.md
 create mode 100644 docs/superpowers/specs/2026-08-04-mdp-gdocs-layout-design.md
 create mode 100644 tools/mdp/.gitignore
 create mode 100644 tools/mdp/README.md
 create mode 100644 tools/mdp/bun.lock
 create mode 100755 tools/mdp/mdp.ts
 create mode 100644 tools/mdp/package.json
 create mode 100644 tools/mdp/src/args.test.ts
 create mode 100644 tools/mdp/src/args.ts
 create mode 100644 tools/mdp/src/comments.test.ts
 create mode 100644 tools/mdp/src/comments.ts
 create mode 100644 tools/mdp/src/input.test.ts
 create mode 100644 tools/mdp/src/input.ts
 create mode 100644 tools/mdp/src/links.test.ts
 create mode 100644 tools/mdp/src/links.ts
 create mode 100644 tools/mdp/src/mermaid.test.ts
 create mode 100644 tools/mdp/src/mermaid.ts
 create mode 100644 tools/mdp/src/post.test.ts
 create mode 100644 tools/mdp/src/post.ts
 create mode 100644 tools/mdp/src/pr.test.ts
 create mode 100644 tools/mdp/src/pr.ts
 create mode 100644 tools/mdp/src/render.test.ts
 create mode 100644 tools/mdp/src/render.ts
 create mode 100644 tools/mdp/src/resolve.test.ts
 create mode 100644 tools/mdp/src/server.test.ts
 create mode 100644 tools/mdp/src/server.ts
 create mode 100644 tools/mdp/src/tabs.test.ts
 create mode 100644 tools/mdp/src/tabs.ts
 create mode 100644 tools/mdp/src/template.test.ts
 create mode 100644 tools/mdp/src/template.ts
 create mode 100644 tools/mdp/src/toc.test.ts
 create mode 100644 tools/mdp/src/toc.ts
 create mode 100644 tools/mdp/themes/designdoc.css
 create mode 100644 tools/mdp/tsconfig.json

diff --git a/docs/superpowers/plans/2026-07-07-mdp-pr-comments.md b/docs/superpowers/plans/2026-07-07-mdp-pr-comments.md
new file mode 100644
index 0000000..7f0ea46
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-07-mdp-pr-comments.md
@@ -0,0 +1,858 @@
+# mdp PR インラインコメント表示 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `mdp <PR>` のプレビューに、PR の既存インラインレビューコメントを本文中の該当位置へ GitHub 風に表示する。
+
+**Architecture:** 起動時に `gh api graphql` で reviewThreads を取得し、各スレッドのアンカーテキスト（対象ソース行を markdown 記法除去+空白正規化したもの）とレンダリング済みコメント本文を JSON としてページに埋め込む。クライアント JS がレンダリング済み HTML のブロック要素をテキストマッチして直後にスレッドボックスを挿入し、マッチ失敗分は末尾の Comments セクションへ。
+
+**Tech Stack:** Bun + TypeScript（既存 mdp と同じ）。`gh` CLI（GraphQL）、GitHub `/markdown` API（コメント本文レンダリング）。
+
+Spec: `docs/superpowers/specs/2026-07-07-mdp-pr-comments-design.md`
+
+## Global Constraints
+
+- 依存追加なし。`gh` 呼び出しは既存の `RunGh` 注入スタイル（`src/pr.ts` 参照）
+- reviewThreads / comments とも first 100、超過時は stderr に warning
+- `gh` 失敗・レンダリング失敗時は warning を出してコメントなしでプレビュー続行
+- テストは `bun test`、既存の `src/*.test.ts` スタイル
+- クライアント JS は既存 `CONTROLS_JS` と同じく template.ts 内の文字列定数
+
+---
+
+### Task 1: comments.ts の純粋関数（URL パース・アンカーテキスト抽出）
+
+**Files:**
+- Create: `src/comments.ts`
+- Test: `src/comments.test.ts`
+
+**Interfaces:**
+- Produces:
+  - `parsePrUrl(url: string): { owner: string; repo: string; number: number } | null`
+  - `stripMarkdownLine(s: string): string`
+  - `normalizeText(s: string): string`
+  - `anchorTextFor(thread: { line: number | null; diffHunk: string }, markdown: string): string | null`
+
+- [ ] **Step 1: Write the failing tests**
+
+`src/comments.test.ts`:
+
+```ts
+import { describe, expect, test } from "bun:test";
+import {
+  anchorTextFor,
+  normalizeText,
+  parsePrUrl,
+  stripMarkdownLine,
+} from "./comments.ts";
+
+describe("parsePrUrl", () => {
+  test("parses owner/repo/number from a PR URL", () => {
+    expect(parsePrUrl("https://github.com/o/r/pull/123")).toEqual({
+      owner: "o",
+      repo: "r",
+      number: 123,
+    });
+  });
+
+  test("rejects non-PR URLs", () => {
+    expect(parsePrUrl("https://github.com/o/r/issues/1")).toBeNull();
+    expect(parsePrUrl("not a url")).toBeNull();
+  });
+});
+
+describe("stripMarkdownLine", () => {
+  test("strips heading markers", () => {
+    expect(stripMarkdownLine("## 設計方針")).toBe("設計方針");
+  });
+
+  test("strips list markers and task boxes", () => {
+    expect(stripMarkdownLine("- [x] done item")).toBe("done item");
+    expect(stripMarkdownLine("  1. numbered")).toBe("numbered");
+  });
+
+  test("strips emphasis, code and links, keeping text", () => {
+    expect(stripMarkdownLine("use **Redis** for `cache` [docs](http://x)")).toBe(
+      "use Redis for cache docs",
+    );
+  });
+
+  test("turns table pipes into spaces", () => {
+    expect(normalizeText(stripMarkdownLine("| a | b |"))).toBe("a b");
+  });
+});
+
+describe("normalizeText", () => {
+  test("collapses whitespace and trims", () => {
+    expect(normalizeText("  a \t b\n c ")).toBe("a b c");
+  });
+});
+
+describe("anchorTextFor", () => {
+  const md = "# Title\n\nキャッシュは **Redis** を使用する。\n";
+
+  test("uses the source line when line is set", () => {
+    expect(anchorTextFor({ line: 3, diffHunk: "" }, md)).toBe(
+      "キャッシュは Redis を使用する。",
+    );
+  });
+
+  test("falls back to the diff hunk's last line when line is null", () => {
+    const hunk = "@@ -1,2 +1,2 @@\n unchanged\n+**added** line";
+    expect(anchorTextFor({ line: null, diffHunk: hunk }, md)).toBe("added line");
+  });
+
+  test("falls back to the hunk when the source line is blank", () => {
+    const hunk = "@@ -1 +1 @@\n+real text";
+    expect(anchorTextFor({ line: 2, diffHunk: hunk }, md)).toBe("real text");
+  });
+
+  test("returns null when nothing yields text", () => {
+    expect(anchorTextFor({ line: null, diffHunk: "" }, md)).toBeNull();
+    expect(anchorTextFor({ line: null, diffHunk: "@@\n+   " }, md)).toBeNull();
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bun test src/comments.test.ts`
+Expected: FAIL（`comments.ts` が存在しない）
+
+- [ ] **Step 3: Write the implementation**
+
+`src/comments.ts`:
+
+```ts
+/** Parse a github.com pull request URL into owner / repo / number. */
+export function parsePrUrl(
+  url: string,
+): { owner: string; repo: string; number: number } | null {
+  const m = url.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+  return m ? { owner: m[1], repo: m[2], number: Number(m[3]) } : null;
+}
+
+/** Strip leading block markers and inline markdown syntax from a source line. */
+export function stripMarkdownLine(s: string): string {
+  return s
+    .replace(/^\s*#{1,6}\s+/, "")
+    .replace(/^\s*>\s*/, "")
+    .replace(/^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?/, "")
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/(\*\*|__|~~|\*|_|`)/g, "")
+    .replace(/\|/g, " ");
+}
+
+/** Collapse runs of whitespace to single spaces (same rule as the client matcher). */
+export function normalizeText(s: string): string {
+  return s.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * The text a thread anchors to in the rendered document: the commented source
+ * line, or the diff hunk's last line when the source line is gone or blank.
+ * Null when neither yields visible text (the thread goes to the trailing section).
+ */
+export function anchorTextFor(
+  thread: { line: number | null; diffHunk: string },
+  markdown: string,
+): string | null {
+  let raw: string | undefined;
+  if (thread.line !== null) raw = markdown.split("\n")[thread.line - 1];
+  if (raw === undefined || raw.trim() === "") {
+    const hunk = thread.diffHunk.split("\n");
+    raw = hunk[hunk.length - 1]?.replace(/^[+\- ]/, "");
+  }
+  if (raw === undefined) return null;
+  const text = normalizeText(stripMarkdownLine(raw));
+  return text === "" ? null : text;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bun test src/comments.test.ts`
+Expected: PASS（全テスト）
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/src/comments.ts tools/mdp/src/comments.test.ts
+git commit -m "feat(mdp): add PR comment anchor-text helpers"
+```
+
+---
+
+### Task 2: reviewThreads の取得と ThreadView 構築
+
+**Files:**
+- Modify: `src/comments.ts`（追記）
+- Test: `src/comments.test.ts`（追記）
+
+**Interfaces:**
+- Consumes: Task 1 の `parsePrUrl` / `anchorTextFor`。`src/pr.ts` の `RunGh` 型
+- Produces:
+  - `type ReviewThread = { path: string; line: number | null; isResolved: boolean; isOutdated: boolean; diffHunk: string; comments: { author: string; body: string; createdAt: string; url: string }[] }`
+  - `type ThreadView = { anchorText: string | null; isResolved: boolean; isOutdated: boolean; comments: { author: string; createdAt: string; url: string; bodyHtml: string }[] }`
+  - `loadPrThreads(prUrl: string, runGh: RunGh): Promise<ReviewThread[]>`
+  - `threadViewsFor(threads: ReviewThread[], doc: { name: string; markdown: string }, renderBody: (md: string) => Promise<string>): Promise<ThreadView[]>`
+  - `toEmbeddedJson(views: ThreadView[]): string`
+
+- [ ] **Step 1: Write the failing tests**
+
+`src/comments.test.ts` に追記:
+
+```ts
+import {
+  loadPrThreads,
+  threadViewsFor,
+  toEmbeddedJson,
+  type ReviewThread,
+} from "./comments.ts";
+
+const graphqlResponse = JSON.stringify({
+  data: {
+    repository: {
+      pullRequest: {
+        reviewThreads: {
+          totalCount: 2,
+          nodes: [
+            {
+              path: "docs/a.md",
+              line: 3,
+              isResolved: false,
+              isOutdated: false,
+              comments: {
+                nodes: [
+                  {
+                    author: { login: "alice" },
+                    body: "TTL は?",
+                    createdAt: "2026-07-01T00:00:00Z",
+                    url: "https://github.com/o/r/pull/1#discussion_r1",
+                    diffHunk: "@@ -1 +3 @@\n+line three",
+                  },
+                  {
+                    author: null,
+                    body: "1h で",
+                    createdAt: "2026-07-02T00:00:00Z",
+                    url: "https://github.com/o/r/pull/1#discussion_r2",
+                    diffHunk: "@@ -1 +3 @@\n+line three",
+                  },
+                ],
+              },
+            },
+            {
+              path: "other.md",
+              line: null,
+              isResolved: true,
+              isOutdated: true,
+              comments: {
+                nodes: [
+                  {
+                    author: { login: "bob" },
+                    body: "old",
+                    createdAt: "2026-06-01T00:00:00Z",
+                    url: "https://github.com/o/r/pull/1#discussion_r3",
+                    diffHunk: "@@ -9 +9 @@\n+gone line",
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    },
+  },
+});
+
+describe("loadPrThreads", () => {
+  test("queries graphql with owner/name/number and maps threads", async () => {
+    let seen: string[] = [];
+    const threads = await loadPrThreads(
+      "https://github.com/o/r/pull/1",
+      async (args) => {
+        seen = args;
+        return graphqlResponse;
+      },
+    );
+    expect(seen[0]).toBe("api");
+    expect(seen[1]).toBe("graphql");
+    expect(seen).toContain("owner=o");
+    expect(seen).toContain("name=r");
+    expect(seen).toContain("number=1");
+    expect(threads).toHaveLength(2);
+    expect(threads[0]).toEqual({
+      path: "docs/a.md",
+      line: 3,
+      isResolved: false,
+      isOutdated: false,
+      diffHunk: "@@ -1 +3 @@\n+line three",
+      comments: [
+        {
+          author: "alice",
+          body: "TTL は?",
+          createdAt: "2026-07-01T00:00:00Z",
+          url: "https://github.com/o/r/pull/1#discussion_r1",
+        },
+        {
+          author: "ghost",
+          body: "1h で",
+          createdAt: "2026-07-02T00:00:00Z",
+          url: "https://github.com/o/r/pull/1#discussion_r2",
+        },
+      ],
+    });
+  });
+
+  test("throws on a non-PR url", async () => {
+    await expect(loadPrThreads("nope", async () => "")).rejects.toThrow(
+      "not a PR URL",
+    );
+  });
+
+  test("throws when the response has no thread data", async () => {
+    await expect(
+      loadPrThreads(
+        "https://github.com/o/r/pull/1",
+        async () => JSON.stringify({ data: { repository: { pullRequest: null } } }),
+      ),
+    ).rejects.toThrow("no review thread data");
+  });
+});
+
+describe("threadViewsFor", () => {
+  const mkThread = (over: Partial<ReviewThread>): ReviewThread => ({
+    path: "docs/a.md",
+    line: 1,
+    isResolved: false,
+    isOutdated: false,
+    diffHunk: "",
+    comments: [
+      {
+        author: "alice",
+        body: "*hi*",
+        createdAt: "2026-07-01T00:00:00Z",
+        url: "u",
+      },
+    ],
+    ...over,
+  });
+  const doc = { name: "docs/a.md", markdown: "line one\nline two\n" };
+  const renderBody = async (md: string) => `<p>${md}</p>`;
+
+  test("keeps only this doc's threads, sorted by line", async () => {
+    const views = await threadViewsFor(
+      [
+        mkThread({ line: 2 }),
+        mkThread({ path: "other.md" }),
+        mkThread({ line: 1 }),
+      ],
+      doc,
+      renderBody,
+    );
+    expect(views).toHaveLength(2);
+    expect(views[0].anchorText).toBe("line one");
+    expect(views[1].anchorText).toBe("line two");
+  });
+
+  test("renders comment bodies", async () => {
+    const views = await threadViewsFor([mkThread({})], doc, renderBody);
+    expect(views[0].comments[0]).toEqual({
+      author: "alice",
+      createdAt: "2026-07-01T00:00:00Z",
+      url: "u",
+      bodyHtml: "<p>*hi*</p>",
+    });
+  });
+});
+
+describe("toEmbeddedJson", () => {
+  test("escapes < so </script> cannot break out", () => {
+    const views = [
+      {
+        anchorText: null,
+        isResolved: false,
+        isOutdated: false,
+        comments: [
+          {
+            author: "a",
+            createdAt: "c",
+            url: "u",
+            bodyHtml: "<script>alert(1)</script>",
+          },
+        ],
+      },
+    ];
+    const json = toEmbeddedJson(views);
+    expect(json).not.toContain("</script>");
+    expect(JSON.parse(json)).toEqual(views);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bun test src/comments.test.ts`
+Expected: FAIL（`loadPrThreads` などが未定義）
+
+- [ ] **Step 3: Write the implementation**
+
+`src/comments.ts` に追記:
+
+```ts
+import type { RunGh } from "./pr.ts";
+
+export type ThreadComment = {
+  author: string;
+  body: string;
+  createdAt: string;
+  url: string;
+};
+
+export type ReviewThread = {
+  path: string;
+  line: number | null;
+  isResolved: boolean;
+  isOutdated: boolean;
+  diffHunk: string;
+  comments: ThreadComment[];
+};
+
+export type ThreadViewComment = {
+  author: string;
+  createdAt: string;
+  url: string;
+  bodyHtml: string;
+};
+
+export type ThreadView = {
+  anchorText: string | null;
+  isResolved: boolean;
+  isOutdated: boolean;
+  comments: ThreadViewComment[];
+};
+
+const THREADS_QUERY = `query($owner:String!,$name:String!,$number:Int!){
+repository(owner:$owner,name:$name){pullRequest(number:$number){
+reviewThreads(first:100){totalCount nodes{path line isResolved isOutdated
+comments(first:100){nodes{author{login} body createdAt url diffHunk}}}}}}}`;
+
+/** Load a PR's inline review threads via the gh GraphQL API (first 100). */
+export async function loadPrThreads(
+  prUrl: string,
+  runGh: RunGh,
+): Promise<ReviewThread[]> {
+  const ref = parsePrUrl(prUrl);
+  if (!ref) throw new Error(`not a PR URL: ${prUrl}`);
+  const out = await runGh([
+    "api",
+    "graphql",
+    "-f",
+    `query=${THREADS_QUERY}`,
+    "-f",
+    `owner=${ref.owner}`,
+    "-f",
+    `name=${ref.repo}`,
+    "-F",
+    `number=${ref.number}`,
+  ]);
+  const threads =
+    JSON.parse(out)?.data?.repository?.pullRequest?.reviewThreads;
+  if (!threads) throw new Error(`no review thread data for ${prUrl}`);
+  if (threads.totalCount > threads.nodes.length) {
+    console.error(
+      `mdp: warning: showing ${threads.nodes.length} of ${threads.totalCount} review threads`,
+    );
+  }
+  type CommentNode = {
+    author: { login: string } | null;
+    body: string;
+    createdAt: string;
+    url: string;
+    diffHunk: string;
+  };
+  type ThreadNode = {
+    path: string;
+    line: number | null;
+    isResolved: boolean;
+    isOutdated: boolean;
+    comments: { nodes: CommentNode[] };
+  };
+  return (threads.nodes as ThreadNode[]).map((n) => ({
+    path: n.path,
+    line: n.line,
+    isResolved: n.isResolved,
+    isOutdated: n.isOutdated,
+    diffHunk: n.comments.nodes[0]?.diffHunk ?? "",
+    comments: n.comments.nodes.map((c) => ({
+      author: c.author?.login ?? "ghost",
+      body: c.body,
+      createdAt: c.createdAt,
+      url: c.url,
+    })),
+  }));
+}
+
+/** Build the page-embeddable views for one document's threads (bodies rendered). */
+export async function threadViewsFor(
+  threads: ReviewThread[],
+  doc: { name: string; markdown: string },
+  renderBody: (md: string) => Promise<string>,
+): Promise<ThreadView[]> {
+  const mine = threads
+    .filter((t) => t.path === doc.name)
+    .sort((a, b) => (a.line ?? Infinity) - (b.line ?? Infinity));
+  return Promise.all(
+    mine.map(async (t) => ({
+      anchorText: anchorTextFor(t, doc.markdown),
+      isResolved: t.isResolved,
+      isOutdated: t.isOutdated,
+      comments: await Promise.all(
+        t.comments.map(async (c) => ({
+          author: c.author,
+          createdAt: c.createdAt,
+          url: c.url,
+          bodyHtml: await renderBody(c.body),
+        })),
+      ),
+    })),
+  );
+}
+
+/** JSON safe to embed in a <script> tag ("<" escaped so "</script>" can't break out). */
+export function toEmbeddedJson(views: ThreadView[]): string {
+  return JSON.stringify(views).replaceAll("<", "\\u003c");
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bun test src/comments.test.ts`
+Expected: PASS（全テスト）
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/src/comments.ts tools/mdp/src/comments.test.ts
+git commit -m "feat(mdp): load PR review threads and build embeddable views"
+```
+
+---
+
+### Task 3: template.ts — コメント JSON の埋め込みとクライアント表示
+
+**Files:**
+- Modify: `src/template.ts`
+- Test: `src/template.test.ts`（追記）
+
+**Interfaces:**
+- Consumes: `PageOptions`（既存）
+- Produces: `PageOptions.comments?: string`（`toEmbeddedJson` の出力を渡す）。値があるとページに `<script type="application/json" id="mdp-comments">` と挿入スクリプトが載る
+
+- [ ] **Step 1: Write the failing tests**
+
+`src/template.test.ts` に追記（既存の import に合わせて `buildPage` を使う）:
+
+```ts
+describe("comments", () => {
+  test("embeds the comments JSON and the inserter script when given", () => {
+    const page = buildPage("<p>hi</p>", [], "", {
+      comments: '[{"anchorText":"hi"}]',
+    });
+    expect(page).toContain(
+      '<script type="application/json" id="mdp-comments">[{"anchorText":"hi"}]</script>',
+    );
+    expect(page).toContain("mdp-thread");
+  });
+
+  test("omits the comments block when not given", () => {
+    const page = buildPage("<p>hi</p>", [], "");
+    expect(page).not.toContain('id="mdp-comments"');
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bun test src/template.test.ts`
+Expected: FAIL（`comments` オプション未実装）
+
+- [ ] **Step 3: Write the implementation**
+
+`src/template.ts` を変更する。
+
+`PageOptions` に追加:
+
+```ts
+export type PageOptions = {
+  mermaid?: boolean;
+  darkCss?: string;
+  toc?: string;
+  files?: string;
+  title?: string;
+  /** Embed-ready JSON of the document's review threads (see toEmbeddedJson). */
+  comments?: string;
+};
+```
+
+`LAYOUT_CSS` の末尾（`@media` の前）に追記:
+
+```css
+.mdp-thread {
+  margin: 8px 0 16px; border: 1px solid #d0d7de; border-radius: 6px;
+  overflow: hidden; background: #f6f8fa;
+  font: 13px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+[data-theme="dark"] .mdp-thread { border-color: #30363d; background: #161b22; }
+.mdp-thread-head {
+  display: flex; align-items: center; gap: 8px; width: 100%;
+  padding: 6px 12px; border: 0; background: transparent; color: #656d76;
+  font: inherit; cursor: pointer; text-align: left;
+}
+[data-theme="dark"] .mdp-thread-head { color: #9198a1; }
+.mdp-badge {
+  display: inline-block; padding: 0 7px; border: 1px solid #d0d7de;
+  border-radius: 999px; font-size: 11px; line-height: 18px; color: #656d76;
+}
+.mdp-badge-resolved { border-color: #8250df; color: #8250df; }
+[data-theme="dark"] .mdp-badge { border-color: #30363d; color: #9198a1; }
+[data-theme="dark"] .mdp-badge-resolved { border-color: #ab7df8; color: #ab7df8; }
+.mdp-comment { padding: 8px 12px; background: #fff; }
+.mdp-comment + .mdp-comment,
+.mdp-thread-head + .mdp-thread-comments .mdp-comment { border-top: 1px solid #d0d7de; }
+[data-theme="dark"] .mdp-comment { background: #0d1117; }
+[data-theme="dark"] .mdp-comment + .mdp-comment,
+[data-theme="dark"] .mdp-thread-head + .mdp-thread-comments .mdp-comment { border-color: #30363d; }
+.mdp-comment-head { margin-bottom: 4px; color: #656d76; }
+[data-theme="dark"] .mdp-comment-head { color: #9198a1; }
+.mdp-comment-head a { color: inherit; text-decoration: none; }
+.mdp-comment-head a:hover { text-decoration: underline; }
+.mdp-comment-body { font-size: 13px; }
+.mdp-comment-body > :first-child { margin-top: 0; }
+.mdp-comment-body > :last-child { margin-bottom: 0; }
+.mdp-comments-rest { margin-top: 48px; border-top: 1px solid #d0d7de; padding-top: 16px; }
+[data-theme="dark"] .mdp-comments-rest { border-color: #30363d; }
+```
+
+`CONTROLS_JS` の後に定数を追加:
+
+```ts
+/** Parse the embedded thread JSON, text-match anchors, and insert thread boxes. */
+const COMMENTS_JS = `(function(){
+var el=document.getElementById('mdp-comments');if(!el)return;
+var threads;try{threads=JSON.parse(el.textContent)||[];}catch(e){return;}
+if(!threads.length)return;
+var body=document.querySelector('.markdown-body');if(!body)return;
+function norm(s){return s.replace(/\\s+/g,' ').trim();}
+function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');}
+function rel(iso){var t=Date.parse(iso);if(isNaN(t))return iso;
+var s=(Date.now()-t)/1000;
+if(s<3600)return Math.max(1,Math.round(s/60))+'m ago';
+if(s<86400)return Math.round(s/3600)+'h ago';
+if(s<2592000)return Math.round(s/86400)+'d ago';
+return iso.slice(0,10);}
+function build(t){
+var div=document.createElement('div');
+div.className='mdp-thread'+(t.isResolved?' mdp-thread-resolved':'');
+var html='';
+if(t.isResolved){
+var a0=t.comments.length?t.comments[0].author:'';
+html+='<button type="button" class="mdp-thread-head">'
++'<span class="mdp-badge mdp-badge-resolved">Resolved</span>'
++(t.isOutdated?'<span class="mdp-badge">Outdated</span>':'')
++'<strong>'+esc(a0)+'</strong></button>';}
+html+='<div class="mdp-thread-comments"'+(t.isResolved?' hidden':'')+'>';
+t.comments.forEach(function(c,i){
+html+='<div class="mdp-comment"><div class="mdp-comment-head"><strong>'+esc(c.author)+'</strong> '
++'<a href="'+esc(c.url)+'" target="_blank" rel="noopener">'+esc(rel(c.createdAt))+'</a>'
++(!t.isResolved&&t.isOutdated&&i===0?' <span class="mdp-badge">Outdated</span>':'')
++'</div><div class="mdp-comment-body">'+c.bodyHtml+'</div></div>';});
+html+='</div>';
+div.innerHTML=html;
+var head=div.querySelector('.mdp-thread-head');
+if(head)head.addEventListener('click',function(){
+var c=div.querySelector('.mdp-thread-comments');c.hidden=!c.hidden;});
+return div;}
+var blocks=[].slice.call(body.querySelectorAll('p,li,h1,h2,h3,h4,h5,h6,pre,blockquote,tr'));
+var texts=blocks.map(function(b){return norm(b.textContent);});
+function anchorFor(t){
+if(!t.anchorText)return null;
+for(var i=0;i<blocks.length;i++){if(texts[i].indexOf(t.anchorText)!==-1)return blocks[i];}
+return null;}
+function insertAfter(ref,node){
+var t=ref;
+if(t.tagName==='TR')t=t.closest('table')||t;
+if(t.tagName==='LI'){t.appendChild(node);return;}
+if(t.parentNode)t.parentNode.insertBefore(node,t.nextSibling);}
+var last=new Map(),rest=[];
+threads.forEach(function(t){
+var target=anchorFor(t);
+if(!target){rest.push(t);return;}
+var node=build(t),prev=last.get(target);
+if(prev&&prev.parentNode){prev.parentNode.insertBefore(node,prev.nextSibling);}
+else{insertAfter(target,node);}
+last.set(target,node);});
+if(rest.length){
+var sec=document.createElement('section');
+sec.className='mdp-comments-rest';
+var h=document.createElement('h2');h.textContent='Comments';sec.appendChild(h);
+rest.forEach(function(t){sec.appendChild(build(t));});
+body.appendChild(sec);}
+})();`;
+```
+
+`buildPage` 内、`mermaidScript` の宣言の後に:
+
+```ts
+const commentsBlock = opts.comments
+  ? `<script type="application/json" id="mdp-comments">${opts.comments}</script>
+<script>${COMMENTS_JS}</script>`
+  : "";
+```
+
+戻り値 HTML の `<script>${CONTROLS_JS}</script>` の直前に `${commentsBlock}` を挿入:
+
+```
+${mermaidScript}
+${commentsBlock}
+<script>${CONTROLS_JS}</script>
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bun test src/template.test.ts`
+Expected: PASS（既存テスト含む）
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/src/template.ts tools/mdp/src/template.test.ts
+git commit -m "feat(mdp): render review threads in the page"
+```
+
+---
+
+### Task 4: mdp.ts の配線・README・E2E 確認
+
+**Files:**
+- Modify: `mdp.ts`
+- Modify: `README.md`
+
+**Interfaces:**
+- Consumes: Task 2 の `loadPrThreads` / `threadViewsFor` / `toEmbeddedJson` / `ReviewThread`、Task 3 の `PageOptions.comments`
+
+- [ ] **Step 1: Wire comments into main**
+
+`mdp.ts` の import に追加:
+
+```ts
+import {
+  loadPrThreads,
+  threadViewsFor,
+  toEmbeddedJson,
+  type ReviewThread,
+} from "./src/comments.ts";
+```
+
+`loadDocs` を PR URL も返すように変更（PR 分岐と戻り値のみ）:
+
+```ts
+async function loadDocs(
+  input: string | undefined,
+): Promise<{ docs: Doc[]; base: Base; prUrl?: string }> {
+  const prRef = parsePrRef(input);
+  if (prRef) {
+    const pr = await loadPrDocs(prRef, runGh);
+    return { docs: pr.docs, base: { kind: "none" }, prUrl: pr.url };
+  }
+  // ... 以下は変更なし
+```
+
+`main` の変更。`loadDocs` の呼び出しと routes ループ:
+
+```ts
+  const { docs, base, prUrl } = await loadDocs(args.input);
+```
+
+`const routes = new Map<string, string>();` の直前に:
+
+```ts
+  let threads: ReviewThread[] = [];
+  if (prUrl) {
+    try {
+      threads = await loadPrThreads(prUrl, runGh);
+    } catch (e) {
+      console.error(
+        `mdp: warning: could not load PR comments: ${(e as Error)?.message ?? e}`,
+      );
+    }
+  }
+```
+
+ループ内、`buildPage` 呼び出しの前に:
+
+```ts
+    let comments: string | undefined;
+    if (threads.length > 0) {
+      try {
+        const views = await threadViewsFor(threads, docs[i], (md) =>
+          renderMarkdown(md, { token }),
+        );
+        if (views.length > 0) comments = toEmbeddedJson(views);
+      } catch (e) {
+        console.error(
+          `mdp: warning: could not render comments for ${docs[i].name}: ${(e as Error)?.message ?? e}`,
+        );
+      }
+    }
+```
+
+`buildPage` のオプションに `comments` を追加:
+
+```ts
+      buildPage(fragment, cssBlocks, githubCss, {
+        mermaid: blocks.length > 0,
+        darkCss,
+        toc,
+        files: filesNav(docs, i),
+        title: docs[i].name,
+        comments,
+      }),
+```
+
+- [ ] **Step 2: Run the full test suite and typecheck**
+
+Run: `bun test && bunx tsc --noEmit`
+Expected: 全テスト PASS、型エラーなし
+
+- [ ] **Step 3: Update README**
+
+`README.md` の PR の usage 行の下の説明（`The page has a left **Files** panel ...` の段落の前）に追記:
+
+```markdown
+When previewing a PR, inline review comments already on the PR are shown
+inside the document at the commented text (resolved threads collapse to a
+gray header; anything that can't be located falls back to a Comments
+section at the end).
+```
+
+- [ ] **Step 4: E2E 確認**
+
+インラインレビューコメントのある実在の PR で確認する:
+
+```sh
+cd tools/mdp && ./mdp.ts <レビューコメントつき PR の URL>
+```
+
+確認項目:
+- コメントが本文中の該当テキスト直後に表示される
+- resolved スレッドが折りたたまれ、クリックで展開できる
+- dark テーマでも破綻しない
+- コメントのない PR / 非 PR 入力（`mdp README.md`）が従来どおり動く
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/mdp.ts tools/mdp/README.md
+git commit -m "feat(mdp): show existing PR review comments in previews"
+```
diff --git a/docs/superpowers/plans/2026-07-16-mdp-post-comments.md b/docs/superpowers/plans/2026-07-16-mdp-post-comments.md
new file mode 100644
index 0000000..123ea1f
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-16-mdp-post-comments.md
@@ -0,0 +1,1185 @@
+# mdp コメント投稿機能 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `mdp <PR>` のプレビュー上でテキストを選択し、その場で PR にレビューコメント(行内範囲情報付き)を投稿できるようにする。
+
+**Architecture:** ページ JS は選択情報(doc パス・選択テキスト・ブロックテキスト、いずれも空白正規化済み)を mdp ローカルサーバーの `POST /api/comment` に送る。サーバーが markdown ソースを使って選択→ソース行のマッピングを行い、diff 内ならインラインレビューコメント、diff 外なら issue コメントとして `gh api` で投稿する。範囲情報は「引用 + `<!-- mdp:range {…} -->` 隠しマーカー」として本文に埋め込み、表示側はマーカーをパースして CSS Custom Highlight API で該当範囲をハイライトする。
+
+**Tech Stack:** Bun + TypeScript(既存 mdp と同じ)。`gh` CLI(REST)。クライアントは素の JS 文字列定数。
+
+Spec: `docs/superpowers/specs/2026-07-16-mdp-post-comments-design.md`
+
+## Global Constraints
+
+- 依存追加なし。`gh` 呼び出しは既存の `RunGh` 注入スタイル(`src/pr.ts` 参照)
+- `gh` 失敗・情報取得失敗時は stderr に warning を出して投稿機能なしでプレビュー続行
+- テストは `bun test`、既存の `src/*.test.ts` スタイル(依存注入・純粋関数中心)
+- クライアント JS は既存 `CONTROLS_JS` / `COMMENTS_JS` と同じく template.ts 内の文字列定数
+- 投稿は即時単発(`POST /pulls/{n}/comments`)。pending review・返信は扱わない
+- spec からの意図的な調整: フォームの外側クリッククローズは textarea が空のときのみ(入力消失防止)
+
+---
+
+### Task 1: post.ts の純粋関数(diff パース・行マッピング・本文組み立て・リクエスト検証)
+
+**Files:**
+- Create: `src/post.ts`
+- Test: `src/post.test.ts`
+
+**Interfaces:**
+- Consumes: `src/comments.ts` の `normalizeText` / `stripMarkdownLine`
+- Produces:
+  - `parseDiffLines(patch: string): Set<number>` — unified diff パッチ → RIGHT 側コメント可能行(追加+文脈)の 1-based 行番号集合
+  - `findSourceLine(markdown: string, selectedText: string, blockText: string): number | null`
+  - `buildCommentBody(selectedText: string, body: string): string`
+  - `type PostRequest = { doc: string; selectedText: string; blockText: string; body: string }`
+  - `parsePostRequest(body: unknown): PostRequest | null`
+
+- [ ] **Step 1: Write the failing tests**
+
+`src/post.test.ts`:
+
+```ts
+import { describe, expect, test } from "bun:test";
+import {
+  buildCommentBody,
+  findSourceLine,
+  parseDiffLines,
+  parsePostRequest,
+} from "./post.ts";
+
+describe("parseDiffLines", () => {
+  test("collects added and context right-side lines across hunks", () => {
+    const patch = [
+      "@@ -1,3 +1,4 @@",
+      " context line",
+      "-removed",
+      "+added one",
+      "+added two",
+      " tail",
+      "@@ -10,2 +11,2 @@",
+      " ctx",
+      "+new",
+    ].join("\n");
+    expect(parseDiffLines(patch)).toEqual(new Set([1, 2, 3, 4, 11, 12]));
+  });
+
+  test("ignores 'no newline' markers and empty patches", () => {
+    expect(parseDiffLines("@@ -1 +1 @@\n+only\n\\ No newline at end of file")).toEqual(
+      new Set([1]),
+    );
+    expect(parseDiffLines("")).toEqual(new Set());
+  });
+});
+
+describe("findSourceLine", () => {
+  const md = [
+    "# Title",
+    "",
+    "First paragraph line one",
+    "continues on line two.",
+    "",
+    "- item **bold** text",
+  ].join("\n");
+
+  test("finds the line containing the selection", () => {
+    expect(
+      findSourceLine(
+        md,
+        "paragraph line",
+        "First paragraph line one continues on line two.",
+      ),
+    ).toBe(3);
+    expect(
+      findSourceLine(
+        md,
+        "on line two",
+        "First paragraph line one continues on line two.",
+      ),
+    ).toBe(4);
+  });
+
+  test("resolves a selection spanning two source lines to the first", () => {
+    expect(
+      findSourceLine(
+        md,
+        "line one continues",
+        "First paragraph line one continues on line two.",
+      ),
+    ).toBe(3);
+  });
+
+  test("matches through stripped markdown syntax", () => {
+    expect(findSourceLine(md, "bold text", "item bold text")).toBe(6);
+    expect(findSourceLine(md, "Title", "Title")).toBe(1);
+  });
+
+  test("returns null when nothing matches", () => {
+    expect(findSourceLine(md, "nonexistent", "zzz")).toBeNull();
+    expect(findSourceLine(md, "", "First paragraph line one")).toBeNull();
+  });
+});
+
+describe("buildCommentBody", () => {
+  test("composes quote, body and machine-readable marker", () => {
+    expect(buildCommentBody("selected text", "my comment")).toBe(
+      '> selected text\n\nmy comment\n\n<!-- mdp:range {"text":"selected text"} -->',
+    );
+  });
+
+  test("escapes -- inside the marker so the html comment cannot terminate early", () => {
+    const body = buildCommentBody("a -- b", "c");
+    expect(body).toBe(
+      '> a -- b\n\nc\n\n<!-- mdp:range {"text":"a -\\u002d b"} -->',
+    );
+  });
+});
+
+describe("parsePostRequest", () => {
+  const valid = {
+    doc: "docs/a.md",
+    selectedText: "sel",
+    blockText: "block sel text",
+    body: "comment",
+  };
+
+  test("accepts a well-formed request", () => {
+    expect(parsePostRequest(valid)).toEqual(valid);
+  });
+
+  test("rejects missing fields, wrong types and empty bodies", () => {
+    expect(parsePostRequest(null)).toBeNull();
+    expect(parsePostRequest("x")).toBeNull();
+    expect(parsePostRequest({ ...valid, doc: 1 })).toBeNull();
+    expect(parsePostRequest({ ...valid, body: "  " })).toBeNull();
+    const { blockText: _omitted, ...missing } = valid;
+    expect(parsePostRequest(missing)).toBeNull();
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd tools/mdp && bun test src/post.test.ts`
+Expected: FAIL(`post.ts` が存在しない)
+
+- [ ] **Step 3: Write the implementation**
+
+`src/post.ts`:
+
+```ts
+import { normalizeText, stripMarkdownLine } from "./comments.ts";
+
+/** RIGHT 側(head)のコメント可能行 — unified diff の追加行と文脈行。 */
+export function parseDiffLines(patch: string): Set<number> {
+  const lines = new Set<number>();
+  let right = 0;
+  for (const l of patch.split("\n")) {
+    const h = l.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (h) {
+      right = Number(h[1]);
+      continue;
+    }
+    if (right === 0) continue;
+    if (l.startsWith("+") || l.startsWith(" ")) {
+      lines.add(right);
+      right++;
+    }
+  }
+  return lines;
+}
+
+/**
+ * レンダリング済みテキストの選択をソース行(1-based)へ写像する。
+ * ブロックテキストに含まれる行を候補とし、選択を含む最初の行、
+ * なければ選択と重なる最初の行を返す。どれも重ならなければ null。
+ */
+export function findSourceLine(
+  markdown: string,
+  selectedText: string,
+  blockText: string,
+): number | null {
+  const sel = normalizeText(selectedText);
+  const block = normalizeText(blockText);
+  if (sel === "" || block === "") return null;
+  const lines = markdown.split("\n");
+  const candidates: { line: number; text: string }[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const text = normalizeText(stripMarkdownLine(lines[i]));
+    if (text !== "" && block.includes(text)) candidates.push({ line: i + 1, text });
+  }
+  const containing = candidates.find((c) => c.text.includes(sel));
+  if (containing) return containing.line;
+  const overlapping = candidates.find(
+    (c) => sel.includes(c.text) || suffixOverlaps(c.text, sel),
+  );
+  return overlapping?.line ?? null;
+}
+
+/** `a` の末尾(4文字以上)が `b` の先頭と一致 — 行の途中から選択が続いている形。 */
+function suffixOverlaps(a: string, b: string): boolean {
+  for (let k = Math.min(a.length, b.length); k >= 4; k--) {
+    if (a.slice(-k) === b.slice(0, k)) return true;
+  }
+  return false;
+}
+
+/**
+ * 投稿本文: 選択テキストの引用 + ユーザー本文 + 機械可読マーカー。
+ * マーカーは HTML コメントなので JSON 中の "--" は - でエスケープする。
+ */
+export function buildCommentBody(selectedText: string, body: string): string {
+  const json = JSON.stringify({ text: selectedText }).replaceAll("--", "-\\u002d");
+  return `> ${selectedText}\n\n${body.trim()}\n\n<!-- mdp:range ${json} -->`;
+}
+
+export type PostRequest = {
+  doc: string;
+  selectedText: string;
+  blockText: string;
+  body: string;
+};
+
+/** /api/comment の JSON ボディを検証つきで PostRequest にする。 */
+export function parsePostRequest(body: unknown): PostRequest | null {
+  if (typeof body !== "object" || body === null) return null;
+  const b = body as Record<string, unknown>;
+  if (
+    typeof b.doc !== "string" ||
+    typeof b.selectedText !== "string" ||
+    typeof b.blockText !== "string" ||
+    typeof b.body !== "string" ||
+    b.body.trim() === ""
+  ) {
+    return null;
+  }
+  return {
+    doc: b.doc,
+    selectedText: b.selectedText,
+    blockText: b.blockText,
+    body: b.body,
+  };
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd tools/mdp && bun test src/post.test.ts`
+Expected: PASS(全テスト)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/src/post.ts tools/mdp/src/post.test.ts
+git commit -m "feat(mdp): add comment posting pure helpers"
+```
+
+---
+
+### Task 2: comments.ts — 範囲マーカーのパースと ThreadView.rangeText
+
+**Files:**
+- Modify: `src/comments.ts`
+- Test: `src/comments.test.ts`(追記+既存2箇所修正)
+
+**Interfaces:**
+- Consumes: Task 1 の `buildCommentBody`(round-trip テストのみ)
+- Produces:
+  - `parseRangeText(body: string): string | null`
+  - `stripRangeMarker(body: string): string`
+  - `ThreadView.rangeText: string | null`(スレッド先頭コメントのマーカー由来)
+
+- [ ] **Step 1: Write the failing tests**
+
+`src/comments.test.ts` に追記:
+
+```ts
+import { buildCommentBody } from "./post.ts";
+import { parseRangeText, stripRangeMarker } from "./comments.ts";
+
+describe("parseRangeText", () => {
+  test("extracts the marker's selected text", () => {
+    expect(parseRangeText('hi\n\n<!-- mdp:range {"text":"sel"} -->')).toBe("sel");
+  });
+
+  test("round-trips buildCommentBody's escaped marker", () => {
+    expect(parseRangeText(buildCommentBody("a -- b", "c"))).toBe("a -- b");
+  });
+
+  test("returns null without a marker or with bad json", () => {
+    expect(parseRangeText("plain")).toBeNull();
+    expect(parseRangeText("<!-- mdp:range {oops} -->")).toBeNull();
+  });
+});
+
+describe("stripRangeMarker", () => {
+  test("removes the marker, keeping the rest", () => {
+    expect(stripRangeMarker('body\n\n<!-- mdp:range {"text":"sel"} -->')).toBe(
+      "body",
+    );
+  });
+
+  test("keeps bodies without a marker", () => {
+    expect(stripRangeMarker("body")).toBe("body");
+  });
+});
+```
+
+`threadViewsFor` の describe 内に追記:
+
+```ts
+  test("extracts rangeText from the first comment and strips markers", async () => {
+    const views = await threadViewsFor(
+      [
+        mkThread({
+          comments: [
+            {
+              author: "alice",
+              avatarUrl: "",
+              body: 'hi\n\n<!-- mdp:range {"text":"line one"} -->',
+              createdAt: "2026-07-01T00:00:00Z",
+              url: "u",
+            },
+          ],
+        }),
+      ],
+      doc,
+      renderBody,
+    );
+    expect(views[0].rangeText).toBe("line one");
+    expect(views[0].comments[0].bodyHtml).toBe("<p>hi</p>");
+  });
+
+  test("has null rangeText without a marker", async () => {
+    const views = await threadViewsFor([mkThread({})], doc, renderBody);
+    expect(views[0].rangeText).toBeNull();
+  });
+```
+
+既存テストの修正(型エラー防止): `toEmbeddedJson` テストの views オブジェクトに `rangeText: null,` を追加(`anchorText: null,` の直後)。
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd tools/mdp && bun test src/comments.test.ts`
+Expected: FAIL(`parseRangeText` 未定義)
+
+- [ ] **Step 3: Write the implementation**
+
+`src/comments.ts` を変更。`ThreadView` に追加:
+
+```ts
+export type ThreadView = {
+  anchorText: string | null;
+  /** 行内選択範囲のレンダリング済みテキスト(mdp:range マーカー由来)。 */
+  rangeText: string | null;
+  isResolved: boolean;
+  isOutdated: boolean;
+  comments: ThreadViewComment[];
+};
+```
+
+`normalizeText` の後に追加:
+
+```ts
+const RANGE_MARKER = /<!--\s*mdp:range\s+(\{.*?\})\s*-->/;
+
+/** mdp:range マーカーが持つ選択テキスト。なければ null。 */
+export function parseRangeText(body: string): string | null {
+  const m = body.match(RANGE_MARKER);
+  if (!m) return null;
+  try {
+    const text = JSON.parse(m[1]).text;
+    return typeof text === "string" ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 表示用に mdp:range マーカーを取り除いた本文。 */
+export function stripRangeMarker(body: string): string {
+  return body.replace(RANGE_MARKER, "").trimEnd();
+}
+```
+
+`threadViewsFor` の map 内を変更:
+
+```ts
+    mine.map(async (t) => ({
+      anchorText: anchorTextFor(t, doc.markdown),
+      rangeText: parseRangeText(t.comments[0]?.body ?? ""),
+      isResolved: t.isResolved,
+      isOutdated: t.isOutdated,
+      comments: await Promise.all(
+        t.comments.map(async (c) => ({
+          author: c.author,
+          avatarUrl: c.avatarUrl,
+          createdAt: c.createdAt,
+          url: c.url,
+          bodyHtml: await renderBody(stripRangeMarker(c.body)),
+        })),
+      ),
+    })),
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd tools/mdp && bun test src/comments.test.ts`
+Expected: PASS(既存テスト含む)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/src/comments.ts tools/mdp/src/comments.test.ts
+git commit -m "feat(mdp): parse range markers into thread views"
+```
+
+---
+
+### Task 3: post.ts — PostContext の取得と投稿(インライン / issue 振り分け)
+
+**Files:**
+- Modify: `src/post.ts`(追記)
+- Test: `src/post.test.ts`(追記)
+
+**Interfaces:**
+- Consumes: Task 1 の各関数、`src/comments.ts` の `parsePrUrl`、`src/pr.ts` の `RunGh`
+- Produces:
+  - `type PostContext = { owner: string; repo: string; number: number; headSha: string; diffLines: Map<string, Set<number>> }`
+  - `loadPostContext(prUrl: string, runGh: RunGh): Promise<PostContext>`
+  - `type PostResult = { kind: "inline" | "issue"; url: string }`
+  - `postComment(req: PostRequest, ctx: PostContext, markdown: string, runGh: RunGh): Promise<PostResult>`
+
+- [ ] **Step 1: Write the failing tests**
+
+`src/post.test.ts` に追記:
+
+```ts
+import {
+  loadPostContext,
+  postComment,
+  type PostContext,
+} from "./post.ts";
+
+describe("loadPostContext", () => {
+  test("loads head sha and per-file commentable lines", async () => {
+    const ctx = await loadPostContext(
+      "https://github.com/o/r/pull/5",
+      async (args) => {
+        if (args[1] === "repos/o/r/pulls/5") {
+          return JSON.stringify({ head: { sha: "abc" } });
+        }
+        expect(args[1]).toBe("repos/o/r/pulls/5/files?per_page=100");
+        return JSON.stringify([
+          { filename: "docs/a.md", patch: "@@ -1 +1,2 @@\n line1\n+line2" },
+          { filename: "bin.png" },
+        ]);
+      },
+    );
+    expect(ctx).toEqual({
+      owner: "o",
+      repo: "r",
+      number: 5,
+      headSha: "abc",
+      diffLines: new Map([["docs/a.md", new Set([1, 2])]]),
+    });
+  });
+
+  test("throws on a non-PR url", async () => {
+    await expect(loadPostContext("nope", async () => "")).rejects.toThrow(
+      "not a PR URL",
+    );
+  });
+});
+
+describe("postComment", () => {
+  const ctx: PostContext = {
+    owner: "o",
+    repo: "r",
+    number: 5,
+    headSha: "abc",
+    diffLines: new Map([["docs/a.md", new Set([3])]]),
+  };
+  const md = "# T\n\nhello world here\n";
+  const req = {
+    doc: "docs/a.md",
+    selectedText: "hello world",
+    blockText: "hello world here",
+    body: "nit",
+  };
+
+  test("posts an inline review comment when the line is in the diff", async () => {
+    let seen: string[] = [];
+    const res = await postComment(req, ctx, md, async (args) => {
+      seen = args;
+      return JSON.stringify({ html_url: "http://c" });
+    });
+    expect(seen[1]).toBe("repos/o/r/pulls/5/comments");
+    expect(seen).toContain("path=docs/a.md");
+    expect(seen).toContain("line=3");
+    expect(seen).toContain("side=RIGHT");
+    expect(seen).toContain("commit_id=abc");
+    expect(seen.join("\n")).toContain("> hello world");
+    expect(res).toEqual({ kind: "inline", url: "http://c" });
+  });
+
+  test("falls back to an issue comment for out-of-diff lines", async () => {
+    let seen: string[] = [];
+    const res = await postComment(
+      req,
+      { ...ctx, diffLines: new Map() },
+      md,
+      async (args) => {
+        seen = args;
+        return JSON.stringify({ html_url: "http://i" });
+      },
+    );
+    expect(seen[1]).toBe("repos/o/r/issues/5/comments");
+    expect(seen.join("\n")).toContain("**docs/a.md:3**");
+    expect(res).toEqual({ kind: "issue", url: "http://i" });
+  });
+
+  test("falls back without a line number when mapping fails", async () => {
+    let seen: string[] = [];
+    await postComment(
+      { ...req, selectedText: "no such text", blockText: "zzz" },
+      ctx,
+      md,
+      async (args) => {
+        seen = args;
+        return JSON.stringify({ html_url: "http://i" });
+      },
+    );
+    expect(seen[1]).toBe("repos/o/r/issues/5/comments");
+    expect(seen.join("\n")).toContain("**docs/a.md**\n\n> no such text");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd tools/mdp && bun test src/post.test.ts`
+Expected: FAIL(`loadPostContext` / `postComment` 未定義)
+
+- [ ] **Step 3: Write the implementation**
+
+`src/post.ts` の import を変更し、末尾に追記:
+
+```ts
+import { normalizeText, parsePrUrl, stripMarkdownLine } from "./comments.ts";
+import type { RunGh } from "./pr.ts";
+```
+
+```ts
+export type PostContext = {
+  owner: string;
+  repo: string;
+  number: number;
+  headSha: string;
+  /** path → RIGHT 側コメント可能行。 */
+  diffLines: Map<string, Set<number>>;
+};
+
+/** 投稿に必要な PR 情報(head SHA と各ファイルの diff 行)を取得する。 */
+export async function loadPostContext(
+  prUrl: string,
+  runGh: RunGh,
+): Promise<PostContext> {
+  const ref = parsePrUrl(prUrl);
+  if (!ref) throw new Error(`not a PR URL: ${prUrl}`);
+  const base = `repos/${ref.owner}/${ref.repo}/pulls/${ref.number}`;
+  const pr = JSON.parse(await runGh(["api", base]));
+  const files = JSON.parse(await runGh(["api", `${base}/files?per_page=100`]));
+  const diffLines = new Map<string, Set<number>>();
+  for (const f of files as { filename: string; patch?: string }[]) {
+    if (f.patch) diffLines.set(f.filename, parseDiffLines(f.patch));
+  }
+  return { ...ref, headSha: pr.head.sha, diffLines };
+}
+
+export type PostResult = { kind: "inline" | "issue"; url: string };
+
+/**
+ * コメントを投稿する。ソース行が特定でき diff に含まれればインライン
+ * レビューコメント、そうでなければファイル名(と行番号)付きの issue コメント。
+ */
+export async function postComment(
+  req: PostRequest,
+  ctx: PostContext,
+  markdown: string,
+  runGh: RunGh,
+): Promise<PostResult> {
+  const body = buildCommentBody(req.selectedText, req.body);
+  const line = findSourceLine(markdown, req.selectedText, req.blockText);
+  const repo = `repos/${ctx.owner}/${ctx.repo}`;
+  if (line !== null && (ctx.diffLines.get(req.doc)?.has(line) ?? false)) {
+    const out = await runGh([
+      "api",
+      `${repo}/pulls/${ctx.number}/comments`,
+      "-f",
+      `body=${body}`,
+      "-f",
+      `commit_id=${ctx.headSha}`,
+      "-f",
+      `path=${req.doc}`,
+      "-F",
+      `line=${line}`,
+      "-f",
+      "side=RIGHT",
+    ]);
+    return { kind: "inline", url: JSON.parse(out).html_url ?? "" };
+  }
+  const loc = line !== null ? `**${req.doc}:${line}**` : `**${req.doc}**`;
+  const out = await runGh([
+    "api",
+    `${repo}/issues/${ctx.number}/comments`,
+    "-f",
+    `body=${loc}\n\n${body}`,
+  ]);
+  return { kind: "issue", url: JSON.parse(out).html_url ?? "" };
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd tools/mdp && bun test src/post.test.ts`
+Expected: PASS(全テスト)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/src/post.ts tools/mdp/src/post.test.ts
+git commit -m "feat(mdp): post inline or issue comments via gh"
+```
+
+---
+
+### Task 4: server.ts — POST /api ルーティング
+
+**Files:**
+- Modify: `src/server.ts`
+- Test: `src/server.test.ts`(追記)
+
+**Interfaces:**
+- Consumes: 既存 `Base` / `resolveAsset`
+- Produces:
+  - `type ApiHandler = (pathname: string, body: unknown) => Promise<Response | null>`(null = 未処理)
+  - `makeFetchHandler(routes: Map<string, string>, base: Base, api?: ApiHandler): (req: Request) => Promise<Response>`
+  - `serve(routes, base, api?)` — 既存シグネチャに第3引数を追加
+
+- [ ] **Step 1: Write the failing tests**
+
+`src/server.test.ts` に追記:
+
+```ts
+import { makeFetchHandler } from "./server.ts";
+
+describe("makeFetchHandler", () => {
+  const routes = new Map([["/", "<html>home</html>"]]);
+
+  test("serves routes for GET", async () => {
+    const handle = makeFetchHandler(routes, { kind: "none" });
+    const res = await handle(new Request("http://x/"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("<html>home</html>");
+  });
+
+  test("dispatches POST json to the api handler", async () => {
+    let got: unknown;
+    const handle = makeFetchHandler(routes, { kind: "none" }, async (path, body) => {
+      got = { path, body };
+      return Response.json({ ok: true });
+    });
+    const res = await handle(
+      new Request("http://x/api/comment", {
+        method: "POST",
+        body: JSON.stringify({ a: 1 }),
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(got).toEqual({ path: "/api/comment", body: { a: 1 } });
+  });
+
+  test("400 on unparsable POST bodies", async () => {
+    const handle = makeFetchHandler(routes, { kind: "none" }, async () =>
+      Response.json({ ok: true }),
+    );
+    const res = await handle(
+      new Request("http://x/api/comment", { method: "POST", body: "not json" }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("404 for POSTs the handler declines or without a handler", async () => {
+    const declined = makeFetchHandler(routes, { kind: "none" }, async () => null);
+    const res1 = await declined(
+      new Request("http://x/other", { method: "POST", body: "{}" }),
+    );
+    expect(res1.status).toBe(404);
+    const none = makeFetchHandler(routes, { kind: "none" });
+    const res2 = await none(
+      new Request("http://x/api/comment", { method: "POST", body: "{}" }),
+    );
+    expect(res2.status).toBe(404);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd tools/mdp && bun test src/server.test.ts`
+Expected: FAIL(`makeFetchHandler` 未定義)
+
+- [ ] **Step 3: Write the implementation**
+
+`src/server.ts` — `resolveAsset` の後に追加し、`serve` を書き換え:
+
+```ts
+/** POST /api/* を処理するハンドラ。null を返すと未処理(404)。 */
+export type ApiHandler = (
+  pathname: string,
+  body: unknown,
+) => Promise<Response | null>;
+
+/** ルート・アセット・API を捌く fetch ハンドラ(Bun.serve から独立してテスト可能)。 */
+export function makeFetchHandler(
+  routes: Map<string, string>,
+  base: Base,
+  api?: ApiHandler,
+): (req: Request) => Promise<Response> {
+  return async (req) => {
+    const { pathname } = new URL(req.url);
+    if (req.method === "POST") {
+      if (api) {
+        let body: unknown;
+        try {
+          body = await req.json();
+        } catch {
+          return Response.json({ error: "invalid JSON body" }, { status: 400 });
+        }
+        const res = await api(pathname, body);
+        if (res) return res;
+      }
+      return new Response("Not found", { status: 404 });
+    }
+    const page = routes.get(pathname);
+    if (page !== undefined) {
+      return new Response(page, {
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
+    const asset = resolveAsset(base, decodeURIComponent(pathname));
+    if (asset.type === "redirect") {
+      return Response.redirect(asset.url, 302);
+    }
+    if (asset.type === "file") {
+      const file = Bun.file(asset.path);
+      if (await file.exists()) return new Response(file);
+    }
+    return new Response("Not found", { status: 404 });
+  };
+}
+
+/** Serve the route map on an ephemeral port, opening it in the browser. Resolves on SIGINT. */
+export async function serve(
+  routes: Map<string, string>,
+  base: Base,
+  api?: ApiHandler,
+): Promise<void> {
+  const server = Bun.serve({ port: 0, fetch: makeFetchHandler(routes, base, api) });
+
+  const url = `http://localhost:${server.port}`;
+  console.error(`mdp serving ${url} (Ctrl-C to quit)`);
+  Bun.spawn(["open", url]);
+
+  await new Promise<void>((resolve) => {
+    process.on("SIGINT", () => {
+      server.stop();
+      resolve();
+    });
+  });
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd tools/mdp && bun test src/server.test.ts`
+Expected: PASS(既存テスト含む)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/src/server.ts tools/mdp/src/server.test.ts
+git commit -m "feat(mdp): route POST /api requests through the server"
+```
+
+---
+
+### Task 5: template.ts — 選択ポップアップ・投稿フォーム・範囲ハイライト
+
+**Files:**
+- Modify: `src/template.ts`
+- Test: `src/template.test.ts`(追記)
+
+**Interfaces:**
+- Consumes: `PageOptions`(既存)、`POST /api/comment`(Task 4/6 の配線先; レスポンス `{ kind, url }` or `{ error }`)
+- Produces: `PageOptions.postDoc?: string` — 設定するとページに選択→コメント UI が載り、この doc パスで `/api/comment` に POST する
+
+- [ ] **Step 1: Write the failing tests**
+
+`src/template.test.ts` に追記:
+
+```ts
+describe("post ui", () => {
+  test("embeds the selection script with the doc path when postDoc is set", () => {
+    const page = buildPage("<p>hi</p>", [], "", { postDoc: "docs/a.md" });
+    expect(page).toContain('data-mdp-doc="docs/a.md"');
+    expect(page).toContain("mdp-post-btn");
+    expect(page).toContain("/api/comment");
+  });
+
+  test("escapes the doc path attribute", () => {
+    const page = buildPage("<p>hi</p>", [], "", { postDoc: 'a"b.md' });
+    expect(page).toContain('data-mdp-doc="a&quot;b.md"');
+  });
+
+  test("omits the post ui when postDoc is not set", () => {
+    const page = buildPage("<p>hi</p>", [], "");
+    expect(page).not.toContain("data-mdp-doc");
+    expect(page).not.toContain("/api/comment");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd tools/mdp && bun test src/template.test.ts`
+Expected: FAIL(`postDoc` 未実装)
+
+- [ ] **Step 3: Write the implementation**
+
+`src/template.ts` を変更する。
+
+**(a)** `PageOptions` に追加:
+
+```ts
+  /** Doc path to post selection comments for; enables the posting UI. */
+  postDoc?: string;
+```
+
+**(b)** `LAYOUT_CSS` の `.mdp-comments-rest` ブロックの後(`@media` の前)に追記:
+
+```css
+#mdp-post-btn {
+  position: absolute; z-index: 20; padding: 4px 10px;
+  border: 1px solid #d0d7de; border-radius: 6px; background: #fff; color: #1f2328;
+  font: 12px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  cursor: pointer; box-shadow: 0 2px 8px rgba(31,35,40,0.18);
+}
+[data-theme="dark"] #mdp-post-btn { background: #161b22; color: #e6edf3; border-color: #30363d; }
+.mdp-post-quote {
+  padding: 2px 8px; margin-bottom: 8px; border-left: 3px solid #d0d7de;
+  color: #656d76; overflow-wrap: anywhere;
+}
+[data-theme="dark"] .mdp-post-quote { border-color: #30363d; color: #9198a1; }
+.mdp-post-text {
+  width: 100%; resize: vertical; padding: 6px 8px;
+  border: 1px solid #d0d7de; border-radius: 6px;
+  background: #fff; color: inherit; font: inherit;
+}
+[data-theme="dark"] .mdp-post-text { background: #0d1117; border-color: #30363d; }
+.mdp-post-err { margin-top: 6px; color: #d1242f; }
+[data-theme="dark"] .mdp-post-err { color: #f85149; }
+.mdp-post-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 8px; }
+.mdp-post-actions button {
+  padding: 4px 12px; border-radius: 6px; border: 1px solid #d0d7de;
+  cursor: pointer; font: inherit;
+}
+.mdp-post-submit { background: #1f883d; border-color: #1f883d; color: #fff; }
+.mdp-post-cancel { background: transparent; color: inherit; }
+[data-theme="dark"] .mdp-post-actions button { border-color: #30363d; }
+[data-theme="dark"] .mdp-post-submit { background: #238636; border-color: #238636; }
+::highlight(mdp-range) { background: rgba(255, 212, 0, 0.35); }
+[data-theme="dark"] ::highlight(mdp-range) { background: rgba(187, 128, 9, 0.4); }
+```
+
+**(c)** `COMMENTS_JS` に範囲ハイライトを足す。`function anchorFor(t){...}` の直前に追加:
+
+```js
+function findRange(block,needle){
+if(!needle)return null;
+var walker=document.createTreeWalker(block,NodeFilter.SHOW_TEXT);
+var map=[],normed='',lastSpace=true,n;
+while(n=walker.nextNode()){var s=n.nodeValue;
+for(var i=0;i<s.length;i++){
+if(/\\s/.test(s[i])){if(!lastSpace){normed+=' ';map.push({n:n,o:i});lastSpace=true;}}
+else{normed+=s[i];map.push({n:n,o:i});lastSpace=false;}}}
+var idx=normed.indexOf(needle);if(idx<0)return null;
+var st=map[idx],en=map[idx+needle.length-1];
+var r=document.createRange();r.setStart(st.n,st.o);r.setEnd(en.n,en.o+1);return r;}
+function addHighlight(r){
+if(!window.Highlight||!CSS.highlights||!r)return;
+var h=CSS.highlights.get('mdp-range')||new Highlight();
+h.add(r);CSS.highlights.set('mdp-range',h);}
+```
+
+`threads.forEach(function(t){` 内の `if(!target){rest.push(t);return;}` の直後に追加:
+
+```js
+if(t.rangeText)addHighlight(findRange(target,norm(t.rangeText)));
+```
+
+**(d)** `COMMENTS_JS` の後に `POST_JS` 定数を追加:
+
+```ts
+/** Selection popup + comment form; posts to /api/comment and highlights the range. */
+const POST_JS = `(function(){
+var DOC=document.currentScript.dataset.mdpDoc;
+var body=document.querySelector('.markdown-body');if(!body||!DOC)return;
+function norm(s){return s.replace(/\\s+/g,' ').trim();}
+function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');}
+var BLOCK='p,li,h1,h2,h3,h4,h5,h6,pre,blockquote,tr';
+function blockOf(node){
+var el=node.nodeType===1?node:node.parentElement;
+if(!el)return null;
+if(el.closest('.mdp-thread,.mdp-post-form'))return null;
+var b=el.closest(BLOCK);
+return b&&body.contains(b)?b:null;}
+function insertAfter(ref,node){
+var t=ref;
+if(t.tagName==='TR')t=t.closest('table')||t;
+if(t.tagName==='LI'){t.appendChild(node);return;}
+if(t.parentNode)t.parentNode.insertBefore(node,t.nextSibling);}
+function highlight(range){
+if(!window.Highlight||!CSS.highlights||!range)return;
+var h=CSS.highlights.get('mdp-range')||new Highlight();
+h.add(range);CSS.highlights.set('mdp-range',h);}
+var btn=document.createElement('button');
+btn.type='button';btn.id='mdp-post-btn';btn.textContent='\\ud83d\\udcac Comment';btn.hidden=true;
+document.body.appendChild(btn);
+var pending=null;
+document.addEventListener('mouseup',function(e){
+if(e.target===btn||btn.contains(e.target))return;
+if(e.target.closest&&e.target.closest('.mdp-post-form'))return;
+setTimeout(function(){
+var sel=window.getSelection();
+if(!sel||sel.isCollapsed||!sel.rangeCount){btn.hidden=true;return;}
+var r=sel.getRangeAt(0);
+var b1=blockOf(r.startContainer),b2=blockOf(r.endContainer);
+var text=norm(sel.toString());
+if(!b1||b1!==b2||!text){btn.hidden=true;return;}
+pending={block:b1,text:text,blockText:norm(b1.textContent),range:r.cloneRange()};
+var rect=r.getBoundingClientRect();
+btn.style.left=(rect.left+window.scrollX)+'px';
+btn.style.top=(rect.bottom+window.scrollY+6)+'px';
+btn.hidden=false;},0);});
+document.addEventListener('mousedown',function(e){
+if(e.target!==btn&&!btn.contains(e.target))btn.hidden=true;
+var form=document.querySelector('.mdp-post-form');
+if(form&&!form.contains(e.target)&&!form.querySelector('.mdp-post-text').value)form.remove();
+},true);
+btn.addEventListener('click',function(){
+if(!pending)return;
+btn.hidden=true;
+var p=pending;pending=null;
+var old=document.querySelector('.mdp-post-form');if(old)old.remove();
+var form=document.createElement('div');
+form.className='mdp-thread mdp-post-form';
+form.innerHTML='<div class="mdp-comment">'
++'<div class="mdp-post-quote">'+esc(p.text)+'</div>'
++'<textarea class="mdp-post-text" rows="3" placeholder="Leave a comment"></textarea>'
++'<div class="mdp-post-err" hidden></div>'
++'<div class="mdp-post-actions">'
++'<button type="button" class="mdp-post-cancel">Cancel</button>'
++'<button type="button" class="mdp-post-submit">Comment</button>'
++'</div></div>';
+insertAfter(p.block,form);
+var ta=form.querySelector('.mdp-post-text');ta.focus();
+function submit(){
+var text=ta.value.trim();if(!text)return;
+var sb=form.querySelector('.mdp-post-submit');sb.disabled=true;sb.textContent='\\u2026';
+var err=form.querySelector('.mdp-post-err');err.hidden=true;
+fetch('/api/comment',{method:'POST',headers:{'Content-Type':'application/json'},
+body:JSON.stringify({doc:DOC,selectedText:p.text,blockText:p.blockText,body:text})})
+.then(function(res){return res.json().then(function(j){return{ok:res.ok,j:j};});})
+.then(function(r){
+if(!r.ok)throw new Error(r.j&&r.j.error||'post failed');
+highlight(p.range);
+var box=document.createElement('div');
+box.className='mdp-thread';
+box.innerHTML='<div class="mdp-comment"><div class="mdp-comment-head"><strong>you</strong> '
++'<a href="'+esc(r.j.url)+'" target="_blank" rel="noopener">just now</a>'
++(r.j.kind==='issue'?' <span class="mdp-badge">PR comment</span>':'')
++'</div><div class="mdp-comment-body">'+esc(text)+'</div></div>';
+form.replaceWith(box);})
+.catch(function(e){
+err.textContent=String(e&&e.message||e);err.hidden=false;
+sb.disabled=false;sb.textContent='Comment';});}
+form.querySelector('.mdp-post-cancel').addEventListener('click',function(){form.remove();});
+form.querySelector('.mdp-post-submit').addEventListener('click',submit);
+ta.addEventListener('keydown',function(e){
+if(e.key==='Escape')form.remove();
+if(e.key==='Enter'&&(e.metaKey||e.ctrlKey))submit();});
+});
+})();`;
+```
+
+**(e)** `buildPage` に配線。ファイル末尾(`buildPage` の前)に属性エスケープを追加:
+
+```ts
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+```
+
+`commentsBlock` の宣言の後に:
+
+```ts
+  const postBlock = opts.postDoc
+    ? `<script data-mdp-doc="${escapeAttr(opts.postDoc)}">${POST_JS}</script>`
+    : "";
+```
+
+戻り値 HTML の `${commentsBlock}` の直後の行に `${postBlock}` を挿入:
+
+```
+${mermaidScript}
+${commentsBlock}
+${postBlock}
+<script>${CONTROLS_JS}</script>
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd tools/mdp && bun test src/template.test.ts`
+Expected: PASS(既存テスト含む)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/src/template.ts tools/mdp/src/template.test.ts
+git commit -m "feat(mdp): selection comment form and range highlights"
+```
+
+---
+
+### Task 6: mdp.ts の配線・README・E2E 確認
+
+**Files:**
+- Modify: `mdp.ts`
+- Modify: `README.md`
+
+**Interfaces:**
+- Consumes: Task 3 の `loadPostContext` / `postComment` / `parsePostRequest` / `PostContext`、Task 4 の `serve(routes, base, api)`、Task 5 の `PageOptions.postDoc`
+
+- [ ] **Step 1: Wire posting into main**
+
+`mdp.ts` の import に追加:
+
+```ts
+import {
+  loadPostContext,
+  parsePostRequest,
+  postComment,
+  type PostContext,
+} from "./src/post.ts";
+```
+
+`main` 内、threads 取得ブロックの直後に:
+
+```ts
+  let postCtx: PostContext | undefined;
+  if (prUrl) {
+    try {
+      postCtx = await loadPostContext(prUrl, runGh);
+    } catch (e) {
+      console.error(
+        `mdp: warning: posting disabled: ${(e as Error)?.message ?? e}`,
+      );
+    }
+  }
+```
+
+routes ループ内、`buildPage` のオプションに追加:
+
+```ts
+        postDoc: postCtx ? docs[i].name : undefined,
+```
+
+`serve` の呼び出しを変更(`await serve(routes, base);` を置き換え):
+
+```ts
+  const ctx = postCtx;
+  const api = ctx
+    ? async (pathname: string, body: unknown): Promise<Response | null> => {
+        if (pathname !== "/api/comment") return null;
+        const req = parsePostRequest(body);
+        if (!req) {
+          return Response.json({ error: "invalid request" }, { status: 400 });
+        }
+        const doc = docs.find((d) => d.name === req.doc);
+        if (!doc) {
+          return Response.json(
+            { error: `unknown doc: ${req.doc}` },
+            { status: 400 },
+          );
+        }
+        try {
+          return Response.json(await postComment(req, ctx, doc.markdown, runGh));
+        } catch (e) {
+          return Response.json(
+            { error: (e as Error)?.message ?? String(e) },
+            { status: 500 },
+          );
+        }
+      }
+    : undefined;
+
+  await serve(routes, base, api);
+```
+
+- [ ] **Step 2: Run the full test suite and typecheck**
+
+Run: `cd tools/mdp && bun test && bunx tsc --noEmit`
+Expected: 全テスト PASS、型エラーなし
+
+- [ ] **Step 3: Update README**
+
+`README.md` の「When previewing a PR, inline review comments ...」段落の後に追記:
+
+```markdown
+You can also post comments from the preview: select text in the document and
+click the floating **💬 Comment** button. The comment lands on the PR as an
+inline review comment on the selected line (or as a regular PR comment when
+the line isn't part of the diff), quoting the selected range; mdp highlights
+that exact range when the preview is opened again.
+```
+
+- [ ] **Step 4: E2E 確認**
+
+自分の PR(またはテスト用 PR)で確認する:
+
+```sh
+cd tools/mdp && ./mdp.ts <markdown を変更した PR の URL>
+```
+
+確認項目:
+- テキスト選択でボタンが出る。複数ブロックまたぎ・スレッドボックス内では出ない
+- diff 内の行 → インラインレビューコメントが付く(GitHub 上で引用+本文が見える、マーカーは不可視)
+- diff 外の行 → `**path:line**` 付きの通常 PR コメントになる
+- 投稿後、その場でボックス化+選択範囲がハイライトされる
+- mdp を再起動すると、投稿したコメントがスレッド表示され、範囲がハイライトされる
+- Cmd+Enter 送信、Esc/Cancel クローズ、空フォームの外側クリッククローズ
+- 非 PR 入力(`mdp README.md`)で UI が出ない・従来どおり動く
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/mdp/mdp.ts tools/mdp/README.md
+git commit -m "feat(mdp): post range comments from PR previews"
+```
diff --git a/docs/superpowers/plans/2026-08-04-mdp-gdocs-layout.md b/docs/superpowers/plans/2026-08-04-mdp-gdocs-layout.md
new file mode 100644
index 0000000..a8042ed
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-04-mdp-gdocs-layout.md
@@ -0,0 +1,58 @@
+# mdp Google Docs 風レイアウト Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** コメントを右マージンカラムへ、Outline を左へ、ファイルを上部タブへ移すレイアウト刷新。
+
+**Architecture:** `buildPage` の構造を「header → タブバー → [toc | 本文 | gutter]」に変更。gutter 内のカード配置は共有クライアント JS(GUTTER_JS)が `window.mdpGutter = { add, remove, layout }` として提供し、COMMENTS_JS(既存スレッド)と POST_JS(投稿フォーム)がそれを使う。サーバー・API・マーカー形式は変更なし。
+
+**Tech Stack:** 既存どおり(Bun + TS、クライアント JS は文字列定数)。
+
+Spec: `docs/superpowers/specs/2026-08-04-mdp-gdocs-layout-design.md`
+
+注: クライアント JS はユニットテスト対象外(既存方針どおり)のため、本プランは構造・テスト変更を規定し、JS 本文は実装時に書く。
+
+## Global Constraints
+
+- 依存追加なし。`bun test` + `tsc --noEmit` green を維持
+- 挙動の詳細(配置・再配置トリガ・狭い画面)は spec に従う
+
+---
+
+### Task 1: buildPage 構造と CSS(タブバー / toc 左 / gutter)
+
+**Files:**
+- Modify: `src/template.ts`, `mdp.ts`
+- Test: `src/template.test.ts`
+
+**Steps:**
+- [ ] template.test.ts を更新: files→`mdp-tabs`(タブバー、layout より前)、toc は article より前、gutter は comments/postDoc 指定時のみ `id="mdp-gutter"`。実行して FAIL 確認
+- [ ] template.ts: `.mdp-files*` CSS を `.mdp-tabs` に置換、`.mdp-toc` を border-right の左カラムに、`.mdp-gutter`/`.mdp-card`/`.mdp-anchor-hover`/`.mdp-gutter-divider` CSS 追加、本文 max-width 900px、media query を 1280px(toc)/1000px(gutter+ボタン)に変更。buildPage の HTML を「header → tabs → layout(toc, article, gutter)」に変更
+- [ ] mdp.ts: `filesNav` を `<a>` タブ列に変更し、`docs.length > 1` のときだけ渡す
+- [ ] `bun test src/template.test.ts` PASS → commit "feat(mdp): tabs-top / outline-left / comments-gutter layout"
+
+### Task 2: GUTTER_JS と COMMENTS_JS の gutter 対応
+
+**Files:**
+- Modify: `src/template.ts`
+
+**Steps:**
+- [ ] GUTTER_JS 追加(comments || postDoc のとき COMMENTS_JS/POST_JS より前に挿入): カード管理・アンカー整列(重なりは押し下げ)・loose カードの「Other comments」区切り・ホバーで `.mdp-anchor-hover`・クリックでアンカーへスクロール・resize/load/テーマ切替で再レイアウト
+- [ ] COMMENTS_JS: インライン挿入(insertAfter・rest セクション)を廃止し `mdpGutter.add(build(t), anchorFor(t))` に。resolved 開閉時に `mdpGutter.layout()`
+- [ ] `bun test` PASS → commit "feat(mdp): place review threads in the margin gutter"
+
+### Task 3: POST_JS の gutter 対応
+
+**Files:**
+- Modify: `src/template.ts`
+
+**Steps:**
+- [ ] フォームを `mdpGutter.add(form, block)` で右欄に出す。Cancel/Esc/空で外側クリック → `mdpGutter.remove`。textarea input で layout()。成功時はフォーム要素をカード内容に書き換えて layout()。`blockOf` は `.mdp-gutter` 内を除外
+- [ ] `bun test` + `tsc --noEmit` PASS → commit "feat(mdp): post form lives in the margin gutter"
+
+### Task 4: E2E・README
+
+**Steps:**
+- [ ] 実 PR でタブ・左 Outline・右コメント欄・投稿フォームの配置を確認(投稿はしない)。非 PR 入力で gutter/タブが出ないこと
+- [ ] README のレイアウト説明を更新(top tabs / left Outline / right margin comments)
+- [ ] commit "docs(mdp): describe the gdocs-style layout"
diff --git a/docs/superpowers/specs/2026-06-23-mdp-markdown-preview-design.md b/docs/superpowers/specs/2026-06-23-mdp-markdown-preview-design.md
new file mode 100644
index 0000000..cfcd31f
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-23-mdp-markdown-preview-design.md
@@ -0,0 +1,117 @@
+# mdp — GitHub Markdown Preview (design)
+
+Date: 2026-06-23
+
+## 目的
+
+GitHub からダウンロードした (あるいはローカルの) Markdown を、GitHub と同じ見た目でブラウザにプレビューする CLI ツール。主用途はパイプ入力:
+
+```sh
+curl -sL https://raw.githubusercontent.com/owner/repo/main/README.md | mdp -
+```
+
+カスタム CSS で見た目を上書きできる:
+
+```sh
+mdp README.md --css 'h1 { color: red }' --css '.markdown-body { max-width: 1000px }'
+```
+
+## 配置
+
+既存ツールと同じく `tools/mdp/` に bun CLI として置く。`package.json` の `bin` で `mdp` を公開。
+
+```
+tools/mdp/
+  mdp.ts          # エントリ: argパース → 入力 → render → serve → open
+  src/
+    input.ts      # stdin / file / URL から { markdown, base } を解決
+    render.ts     # GitHub API /markdown に POST して HTML を得る
+    template.ts   # github-markdown-css + 注入CSS でHTMLページ組み立て
+    server.ts     # Bun.serve でページ + 相対アセット配信、openで起動
+  package.json
+  tsconfig.json
+```
+
+## コンポーネント
+
+### input.ts — 入力解決
+
+`resolveInput(arg?: string): Promise<{ markdown: string; base: Base }>`
+
+分岐ルール:
+
+1. `arg === "-"`、または `arg` が無く stdin が非 TTY → **stdin** を全部読む。base なし
+2. `arg` が `http://` / `https://` で始まる → **URL**。`fetch` で取得。
+   - GitHub の `blob` URL (`github.com/o/r/blob/ref/path`) は raw (`raw.githubusercontent.com/o/r/ref/path`) に正規化してから取得
+   - base = 取得元の raw ディレクトリ URL (相対画像解決用)
+3. それ以外 → **ローカルファイル**。読み込み、base = ファイルの親ディレクトリ (絶対パス)
+
+`Base` は `{ kind: "none" } | { kind: "url"; dir: string } | { kind: "file"; dir: string }`。
+
+### render.ts — GitHub API でレンダリング
+
+`renderMarkdown(markdown: string): Promise<string>` (HTML 断片を返す)
+
+- `POST https://api.github.com/markdown`、body `{ text, mode: "gfm" }`、`Accept: application/vnd.github+json`
+- `GITHUB_TOKEN` または `GH_TOKEN` 環境変数があれば `Authorization: Bearer <token>` を付与 (未認証 60 req/h → 認証 5000 req/h)
+- 失敗時 (401/403/429/5xx/ネットワーク) は status と短い理由を添えて throw。レート制限超過は分かりやすいメッセージにする
+
+### template.ts — HTML ページ組み立て
+
+`buildPage(htmlFragment: string, customCss: string[]): string`
+
+- `github-markdown-css` の CSS を `<head>` にインライン (依存として bundle、オフラインでも動くように)
+- 本文を `<article class="markdown-body">…</article>` でラップ
+- `github-markdown-css` の **後ろ** に `--css` の生 CSS 群を順に `<style>` で注入 → ユーザー指定が後勝ちで上書きできる
+- light/dark は `prefers-color-scheme` 対応版を使う (github-markdown-css の auto)
+
+### server.ts — 配信 + ブラウザ起動
+
+`serve(page: string, base: Base): Promise<void>`
+
+- `Bun.serve({ port: 0 })` で空きポートに起動
+- `GET /` → `page` (HTML) を返す
+- それ以外のパス → base に応じて相対アセットを解決
+  - `file` base → 親ディレクトリ配下のファイルを静的配信 (ディレクトリ外への traversal は拒否)
+  - `url` base → `<dir>/<path>` の GitHub raw URL へ 302 リダイレクト
+  - `none` base → 404
+- 起動後 `open http://localhost:<port>` (macOS) でブラウザを開く
+- フォアグラウンドで待機し、Ctrl-C (SIGINT) で終了
+
+## 引数
+
+```
+mdp [input] [--css <raw-css>]...
+
+input:
+  -            stdin から読む (省略時 stdin が非TTYならこれ)
+  <path>       ローカル Markdown ファイル
+  <url>        http(s) の Markdown / GitHub blob URL
+
+--css <css>    本文に注入する生CSS。複数回指定可 (後ろほど優先)
+-h, --help     使い方表示
+```
+
+## エラーハンドリング
+
+- 入力が空 (stdin も引数も無し) → usage を表示して exit 1
+- ファイルが存在しない / 読めない → パス付きエラーで exit 1
+- URL fetch 失敗 (非 2xx) → status 付きエラーで exit 1
+- GitHub API エラー → status と理由 (レート制限など) を表示して exit 1
+- それ以外の例外は最上位で catch し message を表示して exit 1
+
+## テスト
+
+`bun test` で純粋ロジックを中心に:
+
+- `input.ts`: blob→raw 正規化、URL/ファイル/stdin の分岐判定、base の算出
+- `template.ts`: `--css` が github-markdown-css より後ろに入る (後勝ち)、複数 `--css` の順序、本文ラップ
+- `render.ts`: token 有無でヘッダが変わる / エラー時に例外 (fetch をモック)
+- `server.ts`: パス解決ロジック (traversal 拒否、url base の raw リダイレクト URL 生成) を関数として切り出して単体テスト
+
+## スコープ外 (YAGNI)
+
+- ファイル監視によるライブリロード (主用途がパイプ一発のため。サーバー構成は将来追加しやすく保つ)
+- ローカル Markdown ライブラリへのフォールバック (今回は GitHub API 一本)
+- CSS のファイルパス / JSON オブジェクト指定 (生 CSS 文字列のみ)
+- macOS 以外の `open` 相当コマンド対応 (必要になれば後で)
diff --git a/docs/superpowers/specs/2026-07-07-mdp-pr-comments-design.md b/docs/superpowers/specs/2026-07-07-mdp-pr-comments-design.md
new file mode 100644
index 0000000..2e8baeb
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-07-mdp-pr-comments-design.md
@@ -0,0 +1,89 @@
+# mdp: PR の既存インラインレビューコメント表示
+
+2026-07-07
+
+## 目的
+
+`mdp <PR>` で PR の markdown ファイルをプレビューするとき、その PR に
+すでについているインラインレビューコメントを本文中の該当位置に GitHub 風に
+表示する。レビュー内容を GitHub を開かずに文書と一緒に読めるようにする。
+
+## スコープ
+
+- 対象: PR のインラインレビューコメント（reviewThreads）のうち、
+  プレビュー対象の markdown ファイルに紐づくもの
+- 対象外:
+  - PR 会話タブのコメント（issue コメント）・レビュー本文
+  - コメントの新規投稿・返信・resolve 操作（表示のみ）
+  - リアルタイム更新（起動時に 1 回取得のみ）
+  - markdown 以外のファイルへのコメント
+
+## データ取得（新規 `src/comments.ts`）
+
+- `loadPrDocs` と同様に `RunGh` 注入スタイルで実装する
+- `gh api graphql` で PR の `reviewThreads`（first 100）を取得する。
+  取得フィールド: `path`, `line`, `originalLine`, `isResolved`,
+  `isOutdated`, `diffSide`, comments（first 100）の
+  `author.login`, `body`, `createdAt`, `url`
+- 100 件を超えるスレッドは切り捨てる（ページングしない）。
+  切り捨てが起きた場合は stderr に warning を出す
+- プレビュー対象の markdown ファイル（`PrDoc.name`）に `path` が一致する
+  スレッドのみ残す
+- アンカーテキストの決定（純関数として切り出す）:
+  1. `line` が非 null → head の raw markdown（`PrDoc.markdown`）の
+     その行のテキスト
+  2. `line` が null（outdated）→ `diffHunk` の最終行から `+`/`-`/` `
+     プレフィックスを除いたテキスト
+  3. どちらも空行・空白のみになった場合はアンカーなし（末尾セクション行き）
+- コメント本文は markdown なので、既存の `renderMarkdown`（GitHub
+  `/markdown` API）で各コメントを並列レンダリングする
+- `gh` の graphql 呼び出しやレンダリングが失敗した場合は stderr に
+  warning を出し、コメントなしで通常のプレビューを続行する
+  （プレビュー本体は死なせない）
+
+## ページへの埋め込み（`template.ts` 拡張）
+
+- `PageOptions` に `comments?: string`（スレッドデータの JSON）を追加
+- スレッドデータを `<script type="application/json" id="mdp-comments">`
+  としてページに埋め込む。1 スレッドあたり:
+  `anchorText`, `isResolved`, `isOutdated`, `url`,
+  comments 配列（`author`, `createdAt`, `bodyHtml`）
+- クライアント JS（`COMMENTS_JS`）:
+  - `.markdown-body` 配下のブロック要素（p, li, tr, pre, h1–h6 など）を
+    文書順に走査し、空白正規化（連続空白を 1 つに・トリム）したテキストに
+    アンカーテキスト（同じく正規化）を含む**最初の**要素を探す
+  - 見つかったらその直後にスレッドボックスを挿入する。同一要素に複数
+    スレッドがマッチした場合は `line` 順に並べて挿入する
+  - マッチしなかったスレッド（アンカーなし含む）は本文末尾に
+    「Comments」セクションとしてまとめて表示する（取りこぼしゼロ）
+- 表示:
+  - スレッドボックスは GitHub 風（枠線・角丸・author と相対日時の
+    ヘッダ・本文）。ヘッダの日時は GitHub の該当コメントへのリンク
+  - resolved スレッドはグレーの 1 行ヘッダ（`Resolved` バッジ +
+    最初のコメントの author）に折りたたみ、クリックで展開/再折りたたみ
+  - outdated スレッドには `Outdated` バッジを付ける
+  - light / dark 両テーマに対応（既存の `[data-theme="dark"]` パターン）
+
+## データフロー
+
+1. `mdp.ts`: PR 入力のとき `loadPrDocs` に続けて `loadPrComments` を呼ぶ
+2. 各 `PrDoc` のページ生成時に、そのファイルのスレッド JSON を
+   `buildPage` に渡す
+3. ブラウザで `COMMENTS_JS` がテキストマッチして DOM に挿入する
+
+## テスト
+
+- `src/comments.test.ts`:
+  - graphql レスポンス処理（`RunGh` モック、既存 `pr.test.ts` と同様）
+  - アンカーテキスト抽出: line あり / outdated（diffHunk フォールバック）/
+    空白のみでアンカーなし
+  - テキスト正規化・マッチ判定の純関数
+- クライアント側のマッチロジックは、TS 側の純関数と同じ正規化仕様を
+  JS 文字列内に複製する（既存 `CONTROLS_JS` と同じ方式）。仕様の一致は
+  純関数側のテストで担保する
+
+## 既知の制限
+
+- 同一テキストが複数箇所にある場合、最初の出現位置に挿入される
+  （位置がずれうる）。ずれてもコメント自体は必ずどこかに表示される
+- reviewThreads / comments とも first 100 まで
diff --git a/docs/superpowers/specs/2026-07-16-mdp-post-comments-design.md b/docs/superpowers/specs/2026-07-16-mdp-post-comments-design.md
new file mode 100644
index 0000000..4ab6fde
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-16-mdp-post-comments-design.md
@@ -0,0 +1,75 @@
+# mdp コメント投稿機能 Design
+
+**Goal:** `mdp <PR>` のプレビュー上でテキストを選択し、その場で PR にレビューコメントを投稿できるようにする。GitHub API は行単位までしか受け付けないが、選択した行内の特定範囲をコメント本文に埋め込むことで、範囲単位のコメントを実現する。
+
+**前提:** PR インラインコメントの「表示」機能(`src/comments.ts`, spec: `2026-07-07-mdp-pr-comments-design.md`)は実装済み。本機能はその投稿側。
+
+## 決定事項
+
+- 範囲情報は「選択テキストの引用 + 隠し HTML コメントマーカー」の両方をコメント本文に埋め込む
+- 投稿方式は即時単発投稿(`POST /pulls/{n}/comments`)。pending review は扱わない
+- 新規コメントのみ。既存スレッドへの返信はスコープ外
+- diff に含まれない行への選択は、通常の PR コメント(issue コメント)へ自動フォールバック
+- アーキテクチャはローカルサーバー経由: ページ JS は選択情報を mdp サーバーの `POST /api/comment` に送り、サーバー側で行マッピングと `gh api` 投稿を行う(トークン非露出・テスト容易)
+
+## 1. UX フロー
+
+1. PR プレビューの `.markdown-body` 内でテキストを選択すると、選択範囲の近くに小さな「コメント」ボタンが浮かぶ
+2. クリックするとその場(選択したブロックの直後)にコメントフォーム(textarea + Comment ボタン)が開く。既存スレッドボックスと同じ見た目の枠
+3. 送信(ボタン or Cmd+Enter)で `POST /api/comment`。成功したらフォームがそのままスレッドボックスに置き換わり、選択範囲が `<mark>` でハイライトされる。失敗はフォーム内に赤字エラー表示(入力内容は保持)
+4. Esc または外側クリックでフォームを閉じる
+5. 選択が複数ブロックをまたぐ場合はボタンを出さない(単一ブロック内の選択のみ対応)
+6. 非 PR 入力(ローカルファイル・URL・stdin)ではこの機能自体を出さない
+
+## 2. 投稿されるコメントの形式
+
+```markdown
+> 選択したテキスト
+
+ユーザーが書いたコメント本文
+
+<!-- mdp:range {"text":"選択したテキスト"} -->
+```
+
+- **インライン(diff 内の行)**: `POST /repos/{o}/{r}/pulls/{n}/comments` に `path` / `line`(ソース行番号) / `side: RIGHT` / `commit_id`(head SHA) を付けて投稿
+- **フォールバック(diff 外・マッピング失敗)**: `POST /repos/{o}/{r}/issues/{n}/comments` に、上記本文の先頭へ `**ファイル名:行番号**`(行が特定できた場合)または `**ファイル名**` を付けて投稿
+- マーカーの `text` は選択した**レンダリング済みテキスト**(空白正規化済み)。再表示時にレンダリング済み DOM からこのテキストを探してハイライトするため、ソース行内オフセットより堅牢
+- マーカーは HTML コメントなので GitHub 上のレンダリングには現れない。JSON 内に `-->` が含まれる場合はエスケープする
+- 表示側は body 中のマーカーをパースして `rangeText` として取り出し、表示用 body からマーカー行を除去する
+
+## 3. 選択テキスト → ソース行のマッピング(サーバー側)
+
+クライアントは `{ doc, selectedText, blockText }`(いずれも空白正規化済み)を送る。サーバーは:
+
+1. markdown を行に分割し、各行を既存の `stripMarkdownLine` + `normalizeText` で正規化
+2. 「正規化した行テキストが `blockText` に含まれる行」を候補とし、その中で `selectedText` を含む最初の行を選ぶ。含む行がない場合(選択がソース複数行にまたがる場合)は、`selectedText` と部分的に重なる最初の候補行を選ぶ
+3. 見つかった行番号が PR diff のコメント可能行(RIGHT 側: 追加行+文脈行)に含まれるかを、起動時に取得した diff パッチのパース結果で判定し、インライン / issue コメントを振り分ける
+4. どの行にもマッチしない場合も issue コメントへフォールバック(引用があるので文脈は伝わる)
+
+## 4. コンポーネント構成
+
+- `src/post.ts`(新規): 純粋関数群 + 投稿関数
+  - `findSourceLine(markdown, selectedText, blockText): number | null`
+  - `buildCommentBody(selectedText, body): string`
+  - `parseDiffLines(patch): Set<number>`(unified diff パッチ → RIGHT 側コメント可能行集合)
+  - `postComment(req, ctx, runGh): Promise<PostedView>`(振り分け・gh 呼び出し。`RunGh` 注入)
+- `src/comments.ts`(変更): `ThreadView` に `rangeText: string | null` を追加。マーカーのパース関数と、表示用 body からのマーカー除去
+- `src/template.ts`(変更): 選択ポップアップ+フォームの JS/CSS(既存 `COMMENTS_JS` と同様の文字列定数)。ハイライト表示を COMMENTS_JS に追加。`PageOptions` に PR モードフラグ(post 有効化)を追加
+- `src/server.ts`(変更): `serve()` に POST ハンドラ(`onApi?: (pathname, body) => Promise<Response>` 相当)を追加し、`POST /api/comment` を受ける
+- `mdp.ts`(変更): PR モード時に head SHA(`gh api /pulls/{n}` の `head.sha`)と各ファイルの diff 行集合(`/pulls/{n}/files` の `patch`)を取得し、post ハンドラを配線
+
+## 5. エラー処理
+
+- `gh` 失敗時は 500 + エラーメッセージを返し、フォーム内に赤字表示。入力は保持
+- マッピング失敗は issue コメントへの自動フォールバックであり、ユーザーには成功として見える
+- head SHA / diff 情報の取得失敗時は warning を出して投稿機能なしでプレビュー続行(既存の表示機能と同じ方針)
+
+## 6. テスト
+
+- `bun test` 既存スタイル(依存注入・純粋関数中心):
+  - `findSourceLine`: 単一行段落・複数行段落・リスト・見出し・マッチなし
+  - `parseDiffLines`: 追加行・文脈行・削除行の除外・複数ハンク
+  - `buildCommentBody`: 引用+本文+マーカーの組み立て、`-->` エスケープ
+  - マーカーのパース / body からの除去
+  - server: `POST /api/comment` のルーティングと JSON エラー応答
+- E2E(実 PR): diff 内の行への投稿 / diff 外 → issue コメント / 再起動後にマーカー由来のハイライトが出ること / 非 PR 入力で UI が出ないこと
diff --git a/docs/superpowers/specs/2026-07-17-mdp-ja-typography-design.md b/docs/superpowers/specs/2026-07-17-mdp-ja-typography-design.md
new file mode 100644
index 0000000..acdb48d
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-17-mdp-ja-typography-design.md
@@ -0,0 +1,21 @@
+# mdp designdoc テーマ日本語可読性改善 Design
+
+**Goal:** mdp のデフォルトテーマ(designdoc)で日本語文章を読みやすくする。主因は `line-height: 1.3` の窮屈さ。
+
+**変更対象:** `tools/mdp/themes/designdoc.css` のみ(CSS だけ、コード変更なし)。
+
+## 変更内容
+
+1. **行間**: 据え置き(`1.3`)。1.8 / 1.65 / 1.55 / 1.45 を実際に比較した結果、1.3 が好みと確定(2026-07-17)
+2. **フォントスタック**: 欧文は `"Helvetica Neue", Arial` のまま(和欧混植)、日本語側は `"Hiragino Sans"` を `Hiragino Kaku Gothic ProN` より優先。Windows フォールバック(`"Yu Gothic", Meiryo`)は維持
+3. **字間**: 本文に `letter-spacing: 0.02em`。`pre` / `code` は `letter-spacing: normal` で除外
+4. **既存の意図は維持**: ヘルパーテキスト(`em` 13px/1.35)、`strong` 500 などはそのまま
+
+## スコープ外
+
+- コメントスレッドボックス等の UI フォント(13px システムフォント)
+- 明朝テーマの追加
+
+## 検証
+
+CSS のみのため自動テストなし。日本語ドキュメントを mdp で開き、本文の行間・字間、見出し、コードブロックが崩れていないことを目視確認する。
diff --git a/docs/superpowers/specs/2026-08-04-mdp-gdocs-layout-design.md b/docs/superpowers/specs/2026-08-04-mdp-gdocs-layout-design.md
new file mode 100644
index 0000000..1a1e36b
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-04-mdp-gdocs-layout-design.md
@@ -0,0 +1,29 @@
+# mdp Google Docs 風レイアウト Design
+
+**Goal:** mdp のプレビューを Google Docs 風のレイアウトにする — コメントは右マージン、Outline は左、ファイルは上部タブ。
+
+## 決定事項
+
+- **左サイドバー(GDocs ドキュメントタブ風)** *(2026-08-04 更新: 当初の上部タブバー案は見づらく廃止)*: 変更ファイルを縦に列挙し、全ファイル共通のディレクトリ接頭辞は省略表示(フルパスは tooltip)。アクティブファイルの直下にアウトラインをネストし、ファイル名クリックで折りたたみ/展開。他ファイル名クリックで遷移。scroll-spy 維持
+- **コメント**: 本文への差し込み(インライン挿入・末尾 Comments セクション)を廃止し、右側の専用カラム(gutter、約 320px)に配置。PR モード(comments または postDoc あり)のときだけ gutter を描画
+- 本文 `max-width` は 980px → 900px
+
+## コメント欄の挙動(GDocs 風)
+
+- スレッドカードはアンカーブロックの縦位置(offsetTop)に合わせて absolute 配置。重なる場合は下へ押し下げ
+- カードにホバーで該当ブロックをハイライト、範囲マーカー付きは既存 Custom Highlight も併用。カードクリックでアンカーへスクロール(リンク・ボタン・textarea クリックは除外)
+- アンカー不明スレッドは gutter 最下部に「Other comments」区切りの下へ積む
+- 投稿フォームも gutter に出す: 選択 → 💬 → 選択ブロックの高さに合わせて右欄にフォーム。投稿成功でそのままカード化。Cancel/Esc/空のまま外側クリックで除去
+- 再配置トリガ: 初期化後・window load・resize(デバウンス)・テーマ切替・resolved 折りたたみ開閉・textarea 入力
+
+## 狭い画面
+
+- 〜1280px で Outline 非表示、〜1000px で gutter と 💬 ボタン非表示
+
+## 実装範囲
+
+- `template.ts`: レイアウト構造(タブバー・toc 左・gutter)、CSS、クライアント JS(共有 GUTTER_JS + COMMENTS_JS / POST_JS の gutter 対応)
+- `mdp.ts`: `filesNav` をタブ用マークアップに変更、複数ファイル時のみ渡す
+- サーバー・投稿 API・マーカー形式は変更なし
+- `template.test.ts` のレイアウト前提を更新、gutter の有無テストを追加
+- README のレイアウト説明を更新
diff --git a/tools/mdp/.gitignore b/tools/mdp/.gitignore
new file mode 100644
index 0000000..dcbd974
--- /dev/null
+++ b/tools/mdp/.gitignore
@@ -0,0 +1,22 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# logs
+logs
+*.log
+
+# dotenv environment variable files
+.env
+.env.local
+
+# caches
+.cache
+*.tsbuildinfo
+
+# Finder (MacOS) folder config
+.DS_Store
diff --git a/tools/mdp/README.md b/tools/mdp/README.md
new file mode 100644
index 0000000..c30362a
--- /dev/null
+++ b/tools/mdp/README.md
@@ -0,0 +1,76 @@
+# mdp
+
+Preview GitHub-flavored Markdown in the browser, rendered by the GitHub API so
+it looks exactly like github.com.
+
+## Usage
+
+```sh
+# pipe (the original use case)
+curl -sL https://raw.githubusercontent.com/owner/repo/main/README.md | mdp -
+
+# a local file (sibling images/links are served too)
+mdp README.md
+
+# a URL directly (github.com blob URLs are normalized to raw)
+mdp https://github.com/owner/repo/blob/main/README.md
+
+# a pull request — previews the markdown files it changed (uses gh)
+mdp https://github.com/owner/repo/pull/126531
+mdp 126531        # bare PR number, resolved in the current repo
+
+# pick a different bundled theme (default is designdoc)
+mdp https://github.com/owner/repo/blob/main/doc.md --theme other
+```
+
+The `designdoc` theme is applied by default. Themes live in `themes/<name>.css`;
+add a file there to create a new one and select it with `--theme <name>`.
+Mermaid code blocks (` ```mermaid `) are rendered as diagrams automatically.
+
+When previewing a PR, inline review comments already on the PR are shown in
+a right margin column, aligned with the text they reference (Google Docs
+style). Hovering a comment highlights its anchor; clicking scrolls to it.
+Resolved threads collapse to a gray header.
+
+The PR's conversation comments — the ones not tied to a line — are grouped at
+the top of that column under 「行に紐づかないコメント」, together with any
+inline thread whose text could not be located. Clicking a card opens a reply
+box, the blue check resolves the thread, and 🙂+ adds any of GitHub's eight
+emoji reactions.
+
+You can also post comments from the preview: select text in the document and
+click the floating **💬 Comment** button. The comment lands on the PR as an
+inline review comment on the selected line (or as a regular PR comment when
+the line isn't part of the diff), quoting the selected range; mdp highlights
+that exact range when the preview is opened again.
+
+The page has a left sidebar listing the document(s) — for a PR, every changed
+markdown file (common directory prefixes are trimmed; click a name to
+switch). The active file expands to its **Outline** built from the headings
+(with scroll-spy; click the file name to collapse it, Google Docs style).
+Review comments live in the right margin column. The top header has two
+controls:
+
+- **A** — cycle the body font size (small / medium / large)
+- **◐** — toggle light / dark
+
+Both choices persist in `localStorage`; the initial theme is light.
+
+`mdp` starts a local server, opens it in your browser, and stays in the
+foreground. Press `Ctrl-C` to quit.
+
+## Notes
+
+- Rendering uses the GitHub `POST /markdown` API (`mode: gfm`), so task lists,
+  alerts (`> [!NOTE]`), emoji, etc. match github.com.
+- Set `GITHUB_TOKEN` or `GH_TOKEN` to raise the API rate limit
+  (60 req/h unauthenticated → 5000 req/h).
+- Styling is `github-markdown-css` (bundled, auto light/dark). Each `--css`
+  block is injected after it so your rules override.
+
+## Develop
+
+```sh
+bun install
+bun test
+```
diff --git a/tools/mdp/bun.lock b/tools/mdp/bun.lock
new file mode 100644
index 0000000..f289842
--- /dev/null
+++ b/tools/mdp/bun.lock
@@ -0,0 +1,31 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "mdp",
+      "dependencies": {
+        "github-markdown-css": "^5.9.0",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "github-markdown-css": ["github-markdown-css@5.9.0", "", {}, "sha512-tmT5sY+zvg2302XLYEfH2mtkViIM1SWf2nvYoF5N1ZsO0V6B2qZTiw3GOzw4vpjLygK/KG35qRlPFweHqfzz5w=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+  }
+}
diff --git a/tools/mdp/mdp.ts b/tools/mdp/mdp.ts
new file mode 100755
index 0000000..8013ee3
--- /dev/null
+++ b/tools/mdp/mdp.ts
@@ -0,0 +1,336 @@
+#!/usr/bin/env bun
+import { join } from "node:path";
+import { parseArgs } from "./src/args.ts";
+import {
+  issueCommentViewsFor,
+  loadPrIssueComments,
+  loadPrThreads,
+  threadViewsFor,
+  toEmbeddedJson,
+  type ReviewThread,
+} from "./src/comments.ts";
+import { resolveInput } from "./src/input.ts";
+import { rewriteRelativeUrls } from "./src/links.ts";
+import { extractMermaid, injectMermaid } from "./src/mermaid.ts";
+import {
+  loadPostContext,
+  parsePostRequest,
+  parseReactRequest,
+  parseReplyRequest,
+  parseResolveRequest,
+  postComment,
+  postReply,
+  react,
+  resolveThread,
+  type PostContext,
+} from "./src/post.ts";
+import { loadPrDocs, parsePrRef } from "./src/pr.ts";
+import { renderMarkdown } from "./src/render.ts";
+import type { Base } from "./src/server.ts";
+import { serve } from "./src/server.ts";
+import { tabLabels } from "./src/tabs.ts";
+import { buildPage } from "./src/template.ts";
+import { buildToc } from "./src/toc.ts";
+
+const DEFAULT_THEME = "designdoc";
+
+const USAGE = `mdp - preview GitHub-flavored Markdown in the browser
+
+Usage:
+  mdp [input] [--theme <name>]
+
+Input:
+  -            read markdown from stdin (default when stdin is piped)
+  <path>       a local markdown file
+  <url>        an http(s) markdown URL (github.com blob URLs are supported)
+  <pr-url>     a github pull request URL — previews its changed markdown files
+  <number>     a PR number in the current repo (resolved with gh)
+
+Options:
+  --theme <name>  bundled theme from themes/<name>.css (default: designdoc)
+  -h, --help      show this help
+
+Environment:
+  GITHUB_TOKEN / GH_TOKEN   raise the GitHub API rate limit
+`;
+
+async function loadGitHubCss(): Promise<string> {
+  const path = Bun.resolveSync(
+    "github-markdown-css/github-markdown-light.css",
+    import.meta.dir,
+  );
+  return Bun.file(path).text();
+}
+
+/** GitHub's dark stylesheet, scoped so it only applies under [data-theme="dark"]. */
+async function loadDarkCss(): Promise<string> {
+  const path = Bun.resolveSync(
+    "github-markdown-css/github-markdown-dark.css",
+    import.meta.dir,
+  );
+  const css = await Bun.file(path).text();
+  return css.replaceAll(".markdown-body", '[data-theme="dark"] .markdown-body');
+}
+
+/** A short document label for the header, derived from the input. */
+function titleFor(input: string | undefined): string {
+  if (!input || input === "-") return "stdin";
+  try {
+    const last = new URL(input).pathname.split("/").pop();
+    if (last) return decodeURIComponent(last);
+  } catch {
+    // not a URL
+  }
+  return input.split("/").pop() || input;
+}
+
+/** A bundled theme name resolves to themes/<name>.css next to the tool. */
+async function loadTheme(name: string): Promise<string> {
+  const path = join(import.meta.dir, "themes", `${name}.css`);
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    throw new Error(`unknown theme "${name}" (looked for ${path})`);
+  }
+  return file.text();
+}
+
+/** Run `gh` and return its stdout, throwing with stderr on failure. */
+async function runGh(args: string[]): Promise<string> {
+  const proc = Bun.spawn(["gh", ...args], { stdout: "pipe", stderr: "pipe" });
+  const stdout = await new Response(proc.stdout).text();
+  if ((await proc.exited) !== 0) {
+    const err = (await new Response(proc.stderr).text()).trim();
+    throw new Error(`gh ${args[0]} failed: ${err || "non-zero exit"}`);
+  }
+  return stdout;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+type Doc = {
+  name: string;
+  markdown: string;
+  hrefBase?: string;
+  srcBase?: string;
+};
+
+/** Collect the document(s) to show: PR changed-markdown files, or a single input. */
+async function loadDocs(
+  input: string | undefined,
+): Promise<{ docs: Doc[]; base: Base; prUrl?: string }> {
+  const prRef = parsePrRef(input);
+  if (prRef) {
+    const pr = await loadPrDocs(prRef, runGh);
+    return { docs: pr.docs, base: { kind: "none" }, prUrl: pr.url };
+  }
+  const { markdown, base } = await resolveInput(input, {
+    stdinIsTTY: process.stdin.isTTY ?? false,
+    readStdin: () => new Response(Bun.stdin.stream()).text(),
+    readFile: (p) => Bun.file(p).text(),
+    fetchFn: (url) => fetch(url),
+  });
+  // For a remote URL, resolve relative links/images against its directory.
+  const urlBase = base.kind === "url" ? `${base.dir}/` : undefined;
+  return {
+    docs: [{ name: titleFor(input), markdown, hrefBase: urlBase, srcBase: urlBase }],
+    base,
+  };
+}
+
+const routeFor = (i: number): string => (i === 0 ? "/" : `/f/${i}`);
+
+const FILE_ICON = `<svg class="mdp-file-icon" viewBox="0 0 24 24" width="18" height="18" aria-hidden="true"><path fill="currentColor" d="M19 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2zm-5 14H7v-2h7v2zm3-4H7v-2h10v2zm0-4H7V7h10v2z"/></svg>`;
+
+/** GDocs 風サイドバー: ファイル一覧 + アクティブファイル直下にアウトライン。 */
+function sidebarNav(
+  docs: Doc[],
+  active: number,
+  toc: string,
+  counts: number[],
+): string {
+  const labels = tabLabels(docs.map((d) => d.name));
+  return docs
+    .map((d, i) => {
+      const inner =
+        FILE_ICON +
+        `<span class="mdp-file-label">${escapeHtml(labels[i])}</span>` +
+        (counts[i] > 0 ? `<span class="mdp-file-badge">${counts[i]}</span>` : "");
+      const title = escapeHtml(d.name);
+      if (i !== active) {
+        return `<div class="mdp-file"><a class="mdp-file-name" href="${routeFor(i)}" title="${title}">${inner}</a></div>`;
+      }
+      return `<div class="mdp-file active"><button type="button" class="mdp-file-name" id="mdp-file-toggle" title="${title}">${inner}</button>${toc}</div>`;
+    })
+    .join("");
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const { docs, base, prUrl } = await loadDocs(args.input);
+  const cssBlocks: string[] = [await loadTheme(args.theme ?? DEFAULT_THEME)];
+  const githubCss = await loadGitHubCss();
+  const darkCss = await loadDarkCss();
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+
+  let threads: ReviewThread[] = [];
+  if (prUrl) {
+    try {
+      threads = await loadPrThreads(prUrl, runGh);
+    } catch (e) {
+      console.error(
+        `mdp: warning: could not load PR comments: ${(e as Error)?.message ?? e}`,
+      );
+    }
+  }
+
+  // 行に紐づかない PR 会話コメントは全ファイル共通なので一度だけ組む。
+  let prComments: string | undefined;
+  if (prUrl) {
+    try {
+      const issue = await loadPrIssueComments(prUrl, runGh);
+      if (issue.length > 0) {
+        const views = await issueCommentViewsFor(issue, (md) =>
+          renderMarkdown(md, { token }),
+        );
+        prComments = toEmbeddedJson(views);
+      }
+    } catch (e) {
+      console.error(
+        `mdp: warning: could not load PR comments: ${(e as Error)?.message ?? e}`,
+      );
+    }
+  }
+
+  let postCtx: PostContext | undefined;
+  if (prUrl) {
+    try {
+      postCtx = await loadPostContext(prUrl, runGh);
+    } catch (e) {
+      console.error(
+        `mdp: warning: posting disabled: ${(e as Error)?.message ?? e}`,
+      );
+    }
+  }
+
+  const routes = new Map<string, string>();
+  for (let i = 0; i < docs.length; i++) {
+    const { markdown: withoutMermaid, blocks } = extractMermaid(docs[i].markdown);
+    const rendered = await renderMarkdown(withoutMermaid, { token });
+    const linked = rewriteRelativeUrls(rendered, docs[i].hrefBase, docs[i].srcBase);
+    const { fragment, toc } = buildToc(injectMermaid(linked, blocks));
+    let comments: string | undefined;
+    if (threads.length > 0) {
+      try {
+        const views = await threadViewsFor(threads, docs[i], (md) =>
+          renderMarkdown(md, { token }),
+        );
+        if (views.length > 0) comments = toEmbeddedJson(views);
+      } catch (e) {
+        console.error(
+          `mdp: warning: could not render comments for ${docs[i].name}: ${(e as Error)?.message ?? e}`,
+        );
+      }
+    }
+    routes.set(
+      routeFor(i),
+      buildPage(fragment, cssBlocks, githubCss, {
+        mermaid: blocks.length > 0,
+        darkCss,
+        sidebar: sidebarNav(
+          docs,
+          i,
+          toc,
+          docs.map((d) => threads.filter((t) => t.path === d.name).length),
+        ),
+        title: docs[i].name,
+        comments,
+        prComments,
+        postDoc: postCtx ? docs[i].name : undefined,
+        postUser: postCtx?.user,
+        prUrl,
+      }),
+    );
+  }
+
+  const ctx = postCtx;
+  const api = ctx
+    ? async (pathname: string, body: unknown): Promise<Response | null> => {
+        if (pathname === "/api/reply") {
+          const req = parseReplyRequest(body);
+          if (!req) {
+            return Response.json({ error: "invalid request" }, { status: 400 });
+          }
+          try {
+            return Response.json(await postReply(req, ctx, runGh));
+          } catch (e) {
+            return Response.json(
+              { error: (e as Error)?.message ?? String(e) },
+              { status: 500 },
+            );
+          }
+        }
+        if (pathname === "/api/react") {
+          const req = parseReactRequest(body);
+          if (!req) {
+            return Response.json({ error: "invalid request" }, { status: 400 });
+          }
+          try {
+            return Response.json(await react(req, runGh));
+          } catch (e) {
+            return Response.json(
+              { error: (e as Error)?.message ?? String(e) },
+              { status: 500 },
+            );
+          }
+        }
+        if (pathname === "/api/resolve") {
+          const req = parseResolveRequest(body);
+          if (!req) {
+            return Response.json({ error: "invalid request" }, { status: 400 });
+          }
+          try {
+            return Response.json(await resolveThread(req.threadId, runGh));
+          } catch (e) {
+            return Response.json(
+              { error: (e as Error)?.message ?? String(e) },
+              { status: 500 },
+            );
+          }
+        }
+        if (pathname !== "/api/comment") return null;
+        const req = parsePostRequest(body);
+        if (!req) {
+          return Response.json({ error: "invalid request" }, { status: 400 });
+        }
+        const doc = docs.find((d) => d.name === req.doc);
+        if (!doc) {
+          return Response.json(
+            { error: `unknown doc: ${req.doc}` },
+            { status: 400 },
+          );
+        }
+        try {
+          return Response.json(await postComment(req, ctx, doc.markdown, runGh));
+        } catch (e) {
+          return Response.json(
+            { error: (e as Error)?.message ?? String(e) },
+            { status: 500 },
+          );
+        }
+      }
+    : undefined;
+
+  await serve(routes, base, api);
+}
+
+main().catch((e) => {
+  console.error(`mdp: ${e?.message ?? String(e)}`);
+  process.exit(1);
+});
diff --git a/tools/mdp/package.json b/tools/mdp/package.json
new file mode 100644
index 0000000..d5fc640
--- /dev/null
+++ b/tools/mdp/package.json
@@ -0,0 +1,18 @@
+{
+  "name": "mdp",
+  "module": "mdp.ts",
+  "type": "module",
+  "private": true,
+  "bin": {
+    "mdp": "./mdp.ts"
+  },
+  "dependencies": {
+    "github-markdown-css": "^5.9.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}
diff --git a/tools/mdp/src/args.test.ts b/tools/mdp/src/args.test.ts
new file mode 100644
index 0000000..9faab36
--- /dev/null
+++ b/tools/mdp/src/args.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { parseArgs } from "./args.ts";
+
+describe("parseArgs", () => {
+  test("defaults to no input, no theme, no help", () => {
+    expect(parseArgs([])).toEqual({
+      input: undefined,
+      theme: undefined,
+      help: false,
+    });
+  });
+
+  test("takes the first non-flag as input", () => {
+    expect(parseArgs(["README.md"]).input).toBe("README.md");
+  });
+
+  test("accepts '-' as input", () => {
+    expect(parseArgs(["-"]).input).toBe("-");
+  });
+
+  test("parses --theme <name> alongside an input in any order", () => {
+    const r = parseArgs(["--theme", "designdoc", "file.md"]);
+    expect(r.input).toBe("file.md");
+    expect(r.theme).toBe("designdoc");
+  });
+
+  test("throws when --theme has no value", () => {
+    expect(() => parseArgs(["--theme"])).toThrow(/--theme/);
+  });
+
+  test("sets help for -h and --help", () => {
+    expect(parseArgs(["-h"]).help).toBe(true);
+    expect(parseArgs(["--help"]).help).toBe(true);
+  });
+});
diff --git a/tools/mdp/src/args.ts b/tools/mdp/src/args.ts
new file mode 100644
index 0000000..d590ba7
--- /dev/null
+++ b/tools/mdp/src/args.ts
@@ -0,0 +1,27 @@
+export type ParsedArgs = {
+  input: string | undefined;
+  theme: string | undefined;
+  help: boolean;
+};
+
+/** Parse mdp's CLI arguments: an optional input, --theme, and --help. */
+export function parseArgs(argv: string[]): ParsedArgs {
+  let input: string | undefined;
+  let theme: string | undefined;
+  let help = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") {
+      help = true;
+    } else if (a === "--theme") {
+      const val = argv[++i];
+      if (val === undefined) throw new Error("--theme requires a value");
+      theme = val;
+    } else if (input === undefined) {
+      input = a;
+    }
+  }
+
+  return { input, theme, help };
+}
diff --git a/tools/mdp/src/comments.test.ts b/tools/mdp/src/comments.test.ts
new file mode 100644
index 0000000..0de8e5c
--- /dev/null
+++ b/tools/mdp/src/comments.test.ts
@@ -0,0 +1,468 @@
+import { describe, expect, test } from "bun:test";
+import {
+  anchorTextFor,
+  issueCommentViewsFor,
+  loadPrIssueComments,
+  loadPrThreads,
+  normalizeText,
+  parsePrUrl,
+  parseRangeText,
+  stripMarkdownLine,
+  stripRangeMarker,
+  threadViewsFor,
+  toEmbeddedJson,
+  type ReviewThread,
+} from "./comments.ts";
+import { buildCommentBody } from "./post.ts";
+
+describe("parseRangeText", () => {
+  test("extracts the marker's selected text", () => {
+    expect(parseRangeText('hi\n\n<!-- mdp:range {"text":"sel"} -->')).toBe("sel");
+  });
+
+  test("round-trips buildCommentBody's escaped marker", () => {
+    expect(parseRangeText(buildCommentBody("a -- b", "c"))).toBe("a -- b");
+  });
+
+  test("returns null without a marker or with bad json", () => {
+    expect(parseRangeText("plain")).toBeNull();
+    expect(parseRangeText("<!-- mdp:range {oops} -->")).toBeNull();
+  });
+});
+
+describe("stripRangeMarker", () => {
+  test("removes the marker, keeping the rest", () => {
+    expect(stripRangeMarker('body\n\n<!-- mdp:range {"text":"sel"} -->')).toBe(
+      "body",
+    );
+  });
+
+  test("keeps bodies without a marker", () => {
+    expect(stripRangeMarker("body")).toBe("body");
+  });
+});
+
+describe("parsePrUrl", () => {
+  test("parses owner/repo/number from a PR URL", () => {
+    expect(parsePrUrl("https://github.com/o/r/pull/123")).toEqual({
+      owner: "o",
+      repo: "r",
+      number: 123,
+    });
+  });
+
+  test("rejects non-PR URLs", () => {
+    expect(parsePrUrl("https://github.com/o/r/issues/1")).toBeNull();
+    expect(parsePrUrl("not a url")).toBeNull();
+  });
+});
+
+describe("stripMarkdownLine", () => {
+  test("strips heading markers", () => {
+    expect(stripMarkdownLine("## 設計方針")).toBe("設計方針");
+  });
+
+  test("strips list markers and task boxes", () => {
+    expect(stripMarkdownLine("- [x] done item")).toBe("done item");
+    expect(stripMarkdownLine("  1. numbered")).toBe("numbered");
+  });
+
+  test("strips emphasis, code and links, keeping text", () => {
+    expect(stripMarkdownLine("use **Redis** for `cache` [docs](http://x)")).toBe(
+      "use Redis for cache docs",
+    );
+  });
+
+  test("turns table pipes into spaces", () => {
+    expect(normalizeText(stripMarkdownLine("| a | b |"))).toBe("a b");
+  });
+});
+
+describe("normalizeText", () => {
+  test("collapses whitespace and trims", () => {
+    expect(normalizeText("  a \t b\n c ")).toBe("a b c");
+  });
+});
+
+describe("anchorTextFor", () => {
+  const md = "# Title\n\nキャッシュは **Redis** を使用する。\n";
+
+  test("uses the source line when line is set", () => {
+    expect(anchorTextFor({ line: 3, diffHunk: "" }, md)).toBe(
+      "キャッシュは Redis を使用する。",
+    );
+  });
+
+  test("falls back to the diff hunk's last line when line is null", () => {
+    const hunk = "@@ -1,2 +1,2 @@\n unchanged\n+**added** line";
+    expect(anchorTextFor({ line: null, diffHunk: hunk }, md)).toBe("added line");
+  });
+
+  test("falls back to the hunk when the source line is blank", () => {
+    const hunk = "@@ -1 +1 @@\n+real text";
+    expect(anchorTextFor({ line: 2, diffHunk: hunk }, md)).toBe("real text");
+  });
+
+  test("returns null when nothing yields text", () => {
+    expect(anchorTextFor({ line: null, diffHunk: "" }, md)).toBeNull();
+    expect(anchorTextFor({ line: null, diffHunk: "@@\n+   " }, md)).toBeNull();
+  });
+});
+
+const graphqlResponse = JSON.stringify({
+  data: {
+    repository: {
+      pullRequest: {
+        reviewThreads: {
+          totalCount: 2,
+          nodes: [
+            {
+              id: "RT_1",
+              path: "docs/a.md",
+              line: 3,
+              isResolved: false,
+              isOutdated: false,
+              comments: {
+                nodes: [
+                  {
+                    id: "C_1",
+                    databaseId: 101,
+                    author: { login: "alice", avatarUrl: "https://avatars.example/alice" },
+                    body: "TTL は?",
+                    createdAt: "2026-07-01T00:00:00Z",
+                    url: "https://github.com/o/r/pull/1#discussion_r1",
+                    diffHunk: "@@ -1 +3 @@\n+line three",
+                    reactionGroups: [
+                      { content: "THUMBS_UP", viewerHasReacted: true, reactors: { totalCount: 2 } },
+                      { content: "EYES", viewerHasReacted: false, reactors: { totalCount: 0 } },
+                    ],
+                  },
+                  {
+                    id: "C_2",
+                    databaseId: 102,
+                    author: null,
+                    body: "1h で",
+                    createdAt: "2026-07-02T00:00:00Z",
+                    url: "https://github.com/o/r/pull/1#discussion_r2",
+                    diffHunk: "@@ -1 +3 @@\n+line three",
+                  },
+                ],
+              },
+            },
+            {
+              id: "RT_2",
+              path: "other.md",
+              line: null,
+              isResolved: true,
+              isOutdated: true,
+              comments: {
+                nodes: [
+                  {
+                    id: "C_3",
+                    databaseId: 103,
+                    author: { login: "bob", avatarUrl: "https://avatars.example/bob" },
+                    body: "old",
+                    createdAt: "2026-06-01T00:00:00Z",
+                    url: "https://github.com/o/r/pull/1#discussion_r3",
+                    diffHunk: "@@ -9 +9 @@\n+gone line",
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    },
+  },
+});
+
+describe("loadPrThreads", () => {
+  test("queries graphql with owner/name/number and maps threads", async () => {
+    let seen: string[] = [];
+    const threads = await loadPrThreads(
+      "https://github.com/o/r/pull/1",
+      async (args) => {
+        seen = args;
+        return graphqlResponse;
+      },
+    );
+    expect(seen[0]).toBe("api");
+    expect(seen[1]).toBe("graphql");
+    expect(seen).toContain("owner=o");
+    expect(seen).toContain("name=r");
+    expect(seen).toContain("number=1");
+    expect(threads).toHaveLength(2);
+    expect(threads[0]).toEqual({
+      threadNodeId: "RT_1",
+      path: "docs/a.md",
+      line: 3,
+      isResolved: false,
+      isOutdated: false,
+      diffHunk: "@@ -1 +3 @@\n+line three",
+      comments: [
+        {
+          id: 101,
+          nodeId: "C_1",
+          author: "alice",
+          avatarUrl: "https://avatars.example/alice",
+          body: "TTL は?",
+          createdAt: "2026-07-01T00:00:00Z",
+          url: "https://github.com/o/r/pull/1#discussion_r1",
+          reactions: [{ content: "THUMBS_UP", count: 2, viewerReacted: true }],
+        },
+        {
+          id: 102,
+          nodeId: "C_2",
+          author: "ghost",
+          avatarUrl: "",
+          body: "1h で",
+          createdAt: "2026-07-02T00:00:00Z",
+          url: "https://github.com/o/r/pull/1#discussion_r2",
+          reactions: [],
+        },
+      ],
+    });
+  });
+
+  test("throws on a non-PR url", async () => {
+    await expect(loadPrThreads("nope", async () => "")).rejects.toThrow(
+      "not a PR URL",
+    );
+  });
+
+  test("throws when the response has no thread data", async () => {
+    await expect(
+      loadPrThreads(
+        "https://github.com/o/r/pull/1",
+        async () => JSON.stringify({ data: { repository: { pullRequest: null } } }),
+      ),
+    ).rejects.toThrow("no review thread data");
+  });
+});
+
+describe("threadViewsFor", () => {
+  const mkThread = (over: Partial<ReviewThread>): ReviewThread => ({
+    threadNodeId: "RT_7",
+    path: "docs/a.md",
+    line: 1,
+    isResolved: false,
+    isOutdated: false,
+    diffHunk: "",
+    comments: [
+      {
+        id: 7,
+        nodeId: "C_7",
+        author: "alice",
+        avatarUrl: "https://avatars.example/alice",
+        body: "*hi*",
+        createdAt: "2026-07-01T00:00:00Z",
+        url: "u",
+        reactions: [{ content: "HEART", count: 1, viewerReacted: false }],
+      },
+    ],
+    ...over,
+  });
+  const doc = { name: "docs/a.md", markdown: "line one\nline two\n" };
+  const renderBody = async (md: string) => `<p>${md}</p>`;
+
+  test("keeps only this doc's threads, sorted by line", async () => {
+    const views = await threadViewsFor(
+      [
+        mkThread({ line: 2 }),
+        mkThread({ path: "other.md" }),
+        mkThread({ line: 1 }),
+      ],
+      doc,
+      renderBody,
+    );
+    expect(views).toHaveLength(2);
+    expect(views[0].anchorText).toBe("line one");
+    expect(views[1].anchorText).toBe("line two");
+  });
+
+  test("extracts rangeText from the first comment and strips markers", async () => {
+    const views = await threadViewsFor(
+      [
+        mkThread({
+          comments: [
+            {
+              id: 8,
+              nodeId: "C_8",
+              author: "alice",
+              avatarUrl: "",
+              reactions: [],
+              body: 'hi\n\n<!-- mdp:range {"text":"line one"} -->',
+              createdAt: "2026-07-01T00:00:00Z",
+              url: "u",
+            },
+          ],
+        }),
+      ],
+      doc,
+      renderBody,
+    );
+    expect(views[0].rangeText).toBe("line one");
+    expect(views[0].comments[0].bodyHtml).toBe("<p>hi</p>");
+  });
+
+  test("has null rangeText without a marker", async () => {
+    const views = await threadViewsFor([mkThread({})], doc, renderBody);
+    expect(views[0].rangeText).toBeNull();
+  });
+
+  test("carries the first comment's id as replyTo", async () => {
+    const views = await threadViewsFor([mkThread({})], doc, renderBody);
+    expect(views[0].replyTo).toBe(7);
+  });
+
+  test("carries the thread node id for resolving", async () => {
+    const views = await threadViewsFor([mkThread({})], doc, renderBody);
+    expect(views[0].threadNodeId).toBe("RT_7");
+  });
+
+  test("renders comment bodies", async () => {
+    const views = await threadViewsFor([mkThread({})], doc, renderBody);
+    expect(views[0].comments[0]).toEqual({
+      nodeId: "C_7",
+      author: "alice",
+      avatarUrl: "https://avatars.example/alice",
+      createdAt: "2026-07-01T00:00:00Z",
+      url: "u",
+      bodyHtml: "<p>*hi*</p>",
+      reactions: [{ content: "HEART", count: 1, viewerReacted: false }],
+    });
+  });
+});
+
+describe("toEmbeddedJson", () => {
+  test("escapes < so </script> cannot break out", () => {
+    const views = [
+      {
+        anchorText: null,
+        rangeText: null,
+        replyTo: null,
+        threadNodeId: "RT_x",
+        isResolved: false,
+        isOutdated: false,
+        comments: [
+          {
+            nodeId: "C_x",
+            author: "a",
+            avatarUrl: "",
+            createdAt: "c",
+            url: "u",
+            bodyHtml: "<script>alert(1)</script>",
+            reactions: [],
+          },
+        ],
+      },
+    ];
+    const json = toEmbeddedJson(views);
+    expect(json).not.toContain("</script>");
+    expect(JSON.parse(json)).toEqual(views);
+  });
+});
+
+const issueCommentsResponse = JSON.stringify({
+  data: {
+    repository: {
+      pullRequest: {
+        comments: {
+          totalCount: 2,
+          nodes: [
+            {
+              id: "IC_1",
+              author: { login: "carol", avatarUrl: "https://avatars.example/carol" },
+              body: "全体的に良さそう",
+              createdAt: "2026-08-01T00:00:00Z",
+              url: "https://github.com/o/r/pull/1#issuecomment-1",
+              reactionGroups: [
+                { content: "HEART", viewerHasReacted: false, reactors: { totalCount: 3 } },
+                { content: "EYES", viewerHasReacted: false, reactors: { totalCount: 0 } },
+              ],
+            },
+            {
+              id: "IC_2",
+              author: null,
+              body: '**docs/a.md:3**\n\n> sel\n\nnit\n\n<!-- mdp:range {"text":"sel"} -->',
+              createdAt: "2026-08-02T00:00:00Z",
+              url: "https://github.com/o/r/pull/1#issuecomment-2",
+              reactionGroups: [],
+            },
+          ],
+        },
+      },
+    },
+  },
+});
+
+describe("loadPrIssueComments", () => {
+  test("maps PR conversation comments with reactions", async () => {
+    let seen: string[] = [];
+    const comments = await loadPrIssueComments(
+      "https://github.com/o/r/pull/1",
+      async (args) => {
+        seen = args;
+        return issueCommentsResponse;
+      },
+    );
+    expect(seen).toContain("owner=o");
+    expect(seen).toContain("number=1");
+    expect(comments).toHaveLength(2);
+    expect(comments[0]).toEqual({
+      nodeId: "IC_1",
+      author: "carol",
+      avatarUrl: "https://avatars.example/carol",
+      body: "全体的に良さそう",
+      createdAt: "2026-08-01T00:00:00Z",
+      url: "https://github.com/o/r/pull/1#issuecomment-1",
+      reactions: [{ content: "HEART", count: 3, viewerReacted: false }],
+    });
+    expect(comments[1].author).toBe("ghost");
+    expect(comments[1].reactions).toEqual([]);
+  });
+
+  test("throws on a non-PR url", async () => {
+    await expect(loadPrIssueComments("nope", async () => "")).rejects.toThrow(
+      "not a PR URL",
+    );
+  });
+
+  test("throws when the response has no comment data", async () => {
+    await expect(
+      loadPrIssueComments("https://github.com/o/r/pull/1", async () =>
+        JSON.stringify({ data: { repository: { pullRequest: null } } }),
+      ),
+    ).rejects.toThrow("no issue comment data");
+  });
+});
+
+describe("issueCommentViewsFor", () => {
+  test("renders bodies and strips range markers", async () => {
+    const views = await issueCommentViewsFor(
+      [
+        {
+          nodeId: "IC_2",
+          author: "ghost",
+          avatarUrl: "",
+          body: 'nit\n\n<!-- mdp:range {"text":"sel"} -->',
+          createdAt: "2026-08-02T00:00:00Z",
+          url: "u",
+          reactions: [],
+        },
+      ],
+      async (md) => `<p>${md}</p>`,
+    );
+    expect(views).toEqual([
+      {
+        nodeId: "IC_2",
+        author: "ghost",
+        avatarUrl: "",
+        createdAt: "2026-08-02T00:00:00Z",
+        url: "u",
+        bodyHtml: "<p>nit</p>",
+        reactions: [],
+      },
+    ]);
+  });
+});
diff --git a/tools/mdp/src/comments.ts b/tools/mdp/src/comments.ts
new file mode 100644
index 0000000..864f9fc
--- /dev/null
+++ b/tools/mdp/src/comments.ts
@@ -0,0 +1,325 @@
+import type { RunGh } from "./pr.ts";
+
+export type CommentReaction = {
+  /** GraphQL ReactionContent(THUMBS_UP など)。 */
+  content: string;
+  count: number;
+  viewerReacted: boolean;
+};
+
+export type ThreadComment = {
+  /** REST の review comment id(返信先の指定に使う)。 */
+  id: number;
+  /** GraphQL node id(リアクションの subjectId)。 */
+  nodeId: string;
+  author: string;
+  avatarUrl: string;
+  body: string;
+  createdAt: string;
+  url: string;
+  reactions: CommentReaction[];
+};
+
+export type ReviewThread = {
+  /** GraphQL の thread node id(resolve mutation に使う)。 */
+  threadNodeId: string;
+  path: string;
+  line: number | null;
+  isResolved: boolean;
+  isOutdated: boolean;
+  diffHunk: string;
+  comments: ThreadComment[];
+};
+
+export type ThreadViewComment = {
+  nodeId: string;
+  author: string;
+  avatarUrl: string;
+  createdAt: string;
+  url: string;
+  bodyHtml: string;
+  reactions: CommentReaction[];
+};
+
+export type ThreadView = {
+  anchorText: string | null;
+  /** 行内選択範囲のレンダリング済みテキスト(mdp:range マーカー由来)。 */
+  rangeText: string | null;
+  /** 返信先(スレッド先頭コメントの review comment id)。 */
+  replyTo: number | null;
+  /** resolve mutation 用の thread node id。 */
+  threadNodeId: string;
+  isResolved: boolean;
+  isOutdated: boolean;
+  comments: ThreadViewComment[];
+};
+
+/** Parse a github.com pull request URL into owner / repo / number. */
+export function parsePrUrl(
+  url: string,
+): { owner: string; repo: string; number: number } | null {
+  const m = url.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+  return m ? { owner: m[1], repo: m[2], number: Number(m[3]) } : null;
+}
+
+/** Strip leading block markers and inline markdown syntax from a source line. */
+export function stripMarkdownLine(s: string): string {
+  return s
+    .replace(/^\s*#{1,6}\s+/, "")
+    .replace(/^\s*>\s*/, "")
+    .replace(/^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?/, "")
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/(\*\*|__|~~|\*|_|`)/g, "")
+    .replace(/\|/g, " ");
+}
+
+/** Collapse runs of whitespace to single spaces (same rule as the client matcher). */
+export function normalizeText(s: string): string {
+  return s.replace(/\s+/g, " ").trim();
+}
+
+const RANGE_MARKER = /<!--\s*mdp:range\s+(\{.*?\})\s*-->/;
+
+/** mdp:range マーカーが持つ選択テキスト。なければ null。 */
+export function parseRangeText(body: string): string | null {
+  const m = body.match(RANGE_MARKER);
+  if (!m) return null;
+  try {
+    const text = JSON.parse(m[1]).text;
+    return typeof text === "string" ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 表示用に mdp:range マーカーを取り除いた本文。 */
+export function stripRangeMarker(body: string): string {
+  return body.replace(RANGE_MARKER, "").trimEnd();
+}
+
+/**
+ * The text a thread anchors to in the rendered document: the commented source
+ * line, or the diff hunk's last line when the source line is gone or blank.
+ * Null when neither yields visible text (the thread goes to the trailing section).
+ */
+export function anchorTextFor(
+  thread: { line: number | null; diffHunk: string },
+  markdown: string,
+): string | null {
+  let raw: string | undefined;
+  if (thread.line !== null) raw = markdown.split("\n")[thread.line - 1];
+  if (raw === undefined || raw.trim() === "") {
+    const hunk = thread.diffHunk.split("\n");
+    raw = hunk[hunk.length - 1]?.replace(/^[+\- ]/, "");
+  }
+  if (raw === undefined) return null;
+  const text = normalizeText(stripMarkdownLine(raw));
+  return text === "" ? null : text;
+}
+
+const THREADS_QUERY = `query($owner:String!,$name:String!,$number:Int!){
+repository(owner:$owner,name:$name){pullRequest(number:$number){
+reviewThreads(first:100){totalCount nodes{id path line isResolved isOutdated
+comments(first:100){nodes{id databaseId author{login avatarUrl} body createdAt url diffHunk
+reactionGroups{content viewerHasReacted reactors{totalCount}}}}}}}}}`;
+
+/** Load a PR's inline review threads via the gh GraphQL API (first 100). */
+export async function loadPrThreads(
+  prUrl: string,
+  runGh: RunGh,
+): Promise<ReviewThread[]> {
+  const ref = parsePrUrl(prUrl);
+  if (!ref) throw new Error(`not a PR URL: ${prUrl}`);
+  const out = await runGh([
+    "api",
+    "graphql",
+    "-f",
+    `query=${THREADS_QUERY}`,
+    "-f",
+    `owner=${ref.owner}`,
+    "-f",
+    `name=${ref.repo}`,
+    "-F",
+    `number=${ref.number}`,
+  ]);
+  const threads =
+    JSON.parse(out)?.data?.repository?.pullRequest?.reviewThreads;
+  if (!threads) throw new Error(`no review thread data for ${prUrl}`);
+  if (threads.totalCount > threads.nodes.length) {
+    console.error(
+      `mdp: warning: showing ${threads.nodes.length} of ${threads.totalCount} review threads`,
+    );
+  }
+  type CommentNode = {
+    id: string;
+    databaseId: number | null;
+    author: { login: string; avatarUrl: string } | null;
+    body: string;
+    createdAt: string;
+    url: string;
+    diffHunk: string;
+    reactionGroups?: {
+      content: string;
+      viewerHasReacted: boolean;
+      reactors: { totalCount: number };
+    }[];
+  };
+  type ThreadNode = {
+    id: string;
+    path: string;
+    line: number | null;
+    isResolved: boolean;
+    isOutdated: boolean;
+    comments: { nodes: CommentNode[] };
+  };
+  return (threads.nodes as ThreadNode[]).map((n) => ({
+    threadNodeId: n.id,
+    path: n.path,
+    line: n.line,
+    isResolved: n.isResolved,
+    isOutdated: n.isOutdated,
+    diffHunk: n.comments.nodes[0]?.diffHunk ?? "",
+    comments: n.comments.nodes.map((c) => ({
+      id: c.databaseId ?? 0,
+      nodeId: c.id,
+      author: c.author?.login ?? "ghost",
+      avatarUrl: c.author?.avatarUrl ?? "",
+      body: c.body,
+      createdAt: c.createdAt,
+      url: c.url,
+      reactions: (c.reactionGroups ?? [])
+        .filter((g) => g.reactors.totalCount > 0)
+        .map((g) => ({
+          content: g.content,
+          count: g.reactors.totalCount,
+          viewerReacted: g.viewerHasReacted,
+        })),
+    })),
+  }));
+}
+
+/** 行に紐づかない PR 会話コメント(issue comment)。 */
+export type PrIssueComment = {
+  nodeId: string;
+  author: string;
+  avatarUrl: string;
+  body: string;
+  createdAt: string;
+  url: string;
+  reactions: CommentReaction[];
+};
+
+const ISSUE_COMMENTS_QUERY = `query($owner:String!,$name:String!,$number:Int!){
+repository(owner:$owner,name:$name){pullRequest(number:$number){
+comments(first:100){totalCount nodes{id author{login avatarUrl} body createdAt url
+reactionGroups{content viewerHasReacted reactors{totalCount}}}}}}}`;
+
+/** PR の会話コメント(行に紐づかないコメント)を取得する。 */
+export async function loadPrIssueComments(
+  prUrl: string,
+  runGh: RunGh,
+): Promise<PrIssueComment[]> {
+  const ref = parsePrUrl(prUrl);
+  if (!ref) throw new Error(`not a PR URL: ${prUrl}`);
+  const out = await runGh([
+    "api",
+    "graphql",
+    "-f",
+    `query=${ISSUE_COMMENTS_QUERY}`,
+    "-f",
+    `owner=${ref.owner}`,
+    "-f",
+    `name=${ref.repo}`,
+    "-F",
+    `number=${ref.number}`,
+  ]);
+  const comments = JSON.parse(out)?.data?.repository?.pullRequest?.comments;
+  if (!comments) throw new Error(`no issue comment data for ${prUrl}`);
+  if (comments.totalCount > comments.nodes.length) {
+    console.error(
+      `mdp: warning: showing ${comments.nodes.length} of ${comments.totalCount} PR comments`,
+    );
+  }
+  type Node = {
+    id: string;
+    author: { login: string; avatarUrl: string } | null;
+    body: string;
+    createdAt: string;
+    url: string;
+    reactionGroups?: {
+      content: string;
+      viewerHasReacted: boolean;
+      reactors: { totalCount: number };
+    }[];
+  };
+  return (comments.nodes as Node[]).map((c) => ({
+    nodeId: c.id,
+    author: c.author?.login ?? "ghost",
+    avatarUrl: c.author?.avatarUrl ?? "",
+    body: c.body,
+    createdAt: c.createdAt,
+    url: c.url,
+    reactions: (c.reactionGroups ?? [])
+      .filter((g) => g.reactors.totalCount > 0)
+      .map((g) => ({
+        content: g.content,
+        count: g.reactors.totalCount,
+        viewerReacted: g.viewerHasReacted,
+      })),
+  }));
+}
+
+/** PR 会話コメントの表示用ビュー(本文レンダリング + マーカー除去)。 */
+export async function issueCommentViewsFor(
+  comments: PrIssueComment[],
+  renderBody: (md: string) => Promise<string>,
+): Promise<ThreadViewComment[]> {
+  return Promise.all(
+    comments.map(async (c) => ({
+      nodeId: c.nodeId,
+      author: c.author,
+      avatarUrl: c.avatarUrl,
+      createdAt: c.createdAt,
+      url: c.url,
+      bodyHtml: await renderBody(stripRangeMarker(c.body)),
+      reactions: c.reactions,
+    })),
+  );
+}
+
+/** Build the page-embeddable views for one document's threads (bodies rendered). */
+export async function threadViewsFor(
+  threads: ReviewThread[],
+  doc: { name: string; markdown: string },
+  renderBody: (md: string) => Promise<string>,
+): Promise<ThreadView[]> {
+  const mine = threads
+    .filter((t) => t.path === doc.name)
+    .sort((a, b) => (a.line ?? Infinity) - (b.line ?? Infinity));
+  return Promise.all(
+    mine.map(async (t) => ({
+      anchorText: anchorTextFor(t, doc.markdown),
+      rangeText: parseRangeText(t.comments[0]?.body ?? ""),
+      replyTo: t.comments[0]?.id || null,
+      threadNodeId: t.threadNodeId,
+      isResolved: t.isResolved,
+      isOutdated: t.isOutdated,
+      comments: await Promise.all(
+        t.comments.map(async (c) => ({
+          nodeId: c.nodeId,
+          author: c.author,
+          avatarUrl: c.avatarUrl,
+          createdAt: c.createdAt,
+          url: c.url,
+          bodyHtml: await renderBody(stripRangeMarker(c.body)),
+          reactions: c.reactions,
+        })),
+      ),
+    })),
+  );
+}
+
+/** JSON safe to embed in a <script> tag ("<" escaped so "</script>" can't break out). */
+export function toEmbeddedJson(views: unknown): string {
+  return JSON.stringify(views).replaceAll("<", "\\u003c");
+}
diff --git a/tools/mdp/src/input.test.ts b/tools/mdp/src/input.test.ts
new file mode 100644
index 0000000..678d143
--- /dev/null
+++ b/tools/mdp/src/input.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import { classifyArg, normalizeGitHubUrl, urlBaseDir } from "./input.ts";
+
+describe("classifyArg", () => {
+  test("treats '-' as stdin regardless of tty", () => {
+    expect(classifyArg("-", true)).toEqual({ kind: "stdin" });
+    expect(classifyArg("-", false)).toEqual({ kind: "stdin" });
+  });
+
+  test("treats missing arg as stdin when stdin is piped (not a tty)", () => {
+    expect(classifyArg(undefined, false)).toEqual({ kind: "stdin" });
+  });
+
+  test("treats missing arg as none when stdin is a tty", () => {
+    expect(classifyArg(undefined, true)).toEqual({ kind: "none" });
+  });
+
+  test("treats http(s) args as url", () => {
+    expect(classifyArg("https://example.com/x.md", true)).toEqual({
+      kind: "url",
+      url: "https://example.com/x.md",
+    });
+    expect(classifyArg("http://example.com/x.md", true)).toEqual({
+      kind: "url",
+      url: "http://example.com/x.md",
+    });
+  });
+
+  test("treats anything else as a file path", () => {
+    expect(classifyArg("README.md", true)).toEqual({
+      kind: "file",
+      path: "README.md",
+    });
+    expect(classifyArg("./docs/a.md", false)).toEqual({
+      kind: "file",
+      path: "./docs/a.md",
+    });
+  });
+});
+
+describe("normalizeGitHubUrl", () => {
+  test("converts a github blob url to raw", () => {
+    expect(
+      normalizeGitHubUrl("https://github.com/owner/repo/blob/main/docs/README.md"),
+    ).toBe("https://raw.githubusercontent.com/owner/repo/main/docs/README.md");
+  });
+
+  test("leaves a raw url unchanged", () => {
+    const raw = "https://raw.githubusercontent.com/owner/repo/main/README.md";
+    expect(normalizeGitHubUrl(raw)).toBe(raw);
+  });
+
+  test("leaves unrelated urls unchanged", () => {
+    const u = "https://example.com/a/b.md";
+    expect(normalizeGitHubUrl(u)).toBe(u);
+  });
+});
+
+describe("urlBaseDir", () => {
+  test("returns the directory url of a file url", () => {
+    expect(
+      urlBaseDir("https://raw.githubusercontent.com/o/r/main/docs/README.md"),
+    ).toBe("https://raw.githubusercontent.com/o/r/main/docs");
+  });
+
+  test("handles a url at the root path", () => {
+    expect(urlBaseDir("https://example.com/README.md")).toBe(
+      "https://example.com",
+    );
+  });
+});
diff --git a/tools/mdp/src/input.ts b/tools/mdp/src/input.ts
new file mode 100644
index 0000000..aa753c1
--- /dev/null
+++ b/tools/mdp/src/input.ts
@@ -0,0 +1,79 @@
+import { dirname, resolve } from "node:path";
+import type { Base } from "./server.ts";
+
+export type InputKind =
+  | { kind: "stdin" }
+  | { kind: "url"; url: string }
+  | { kind: "file"; path: string }
+  | { kind: "none" };
+
+/** Decide where the markdown comes from, given the CLI arg and whether stdin is a TTY. */
+export function classifyArg(
+  arg: string | undefined,
+  stdinIsTTY: boolean,
+): InputKind {
+  if (arg === "-") return { kind: "stdin" };
+  if (arg === undefined) {
+    return stdinIsTTY ? { kind: "none" } : { kind: "stdin" };
+  }
+  if (arg.startsWith("http://") || arg.startsWith("https://")) {
+    return { kind: "url", url: arg };
+  }
+  return { kind: "file", path: arg };
+}
+
+/** Rewrite a github.com blob URL to its raw.githubusercontent.com equivalent. */
+export function normalizeGitHubUrl(url: string): string {
+  const m = url.match(
+    /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/(.+)$/,
+  );
+  if (!m) return url;
+  const [, owner, repo, rest] = m;
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${rest}`;
+}
+
+/** Directory URL of a file URL (everything up to, but not including, the last segment). */
+export function urlBaseDir(url: string): string {
+  const idx = url.lastIndexOf("/");
+  return url.slice(0, idx);
+}
+
+export type ResolveDeps = {
+  stdinIsTTY: boolean;
+  readStdin: () => Promise<string>;
+  readFile: (path: string) => Promise<string>;
+  fetchFn: (url: string) => Promise<Response>;
+};
+
+/** Resolve the CLI arg into the markdown text plus the base used for asset resolution. */
+export async function resolveInput(
+  arg: string | undefined,
+  deps: ResolveDeps,
+): Promise<{ markdown: string; base: Base }> {
+  const input = classifyArg(arg, deps.stdinIsTTY);
+
+  switch (input.kind) {
+    case "none":
+      throw new Error("no input: pass a file/URL, or pipe markdown to stdin");
+    case "stdin":
+      return { markdown: await deps.readStdin(), base: { kind: "none" } };
+    case "file": {
+      const abs = resolve(input.path);
+      return {
+        markdown: await deps.readFile(input.path),
+        base: { kind: "file", dir: dirname(abs) },
+      };
+    }
+    case "url": {
+      const url = normalizeGitHubUrl(input.url);
+      const res = await deps.fetchFn(url);
+      if (!res.ok) {
+        throw new Error(`failed to fetch ${url}: HTTP ${res.status}`);
+      }
+      return {
+        markdown: await res.text(),
+        base: { kind: "url", dir: urlBaseDir(url) },
+      };
+    }
+  }
+}
diff --git a/tools/mdp/src/links.test.ts b/tools/mdp/src/links.test.ts
new file mode 100644
index 0000000..dd5806e
--- /dev/null
+++ b/tools/mdp/src/links.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { rewriteRelativeUrls } from "./links.ts";
+
+const hrefBase = "https://github.com/o/r/blob/sha/cross/docs/design-doc/";
+const srcBase = "https://raw.githubusercontent.com/o/r/sha/cross/docs/design-doc/";
+
+describe("rewriteRelativeUrls", () => {
+  test("resolves relative href against the href base", () => {
+    const out = rewriteRelativeUrls(
+      '<a href="../../../.github/docs/mergeops.md">x</a>',
+      hrefBase,
+      srcBase,
+    );
+    expect(out).toContain(
+      'href="https://github.com/o/r/blob/sha/.github/docs/mergeops.md"',
+    );
+  });
+
+  test("resolves relative img src against the src (raw) base", () => {
+    const out = rewriteRelativeUrls(
+      '<img src="diagram.png">',
+      hrefBase,
+      srcBase,
+    );
+    expect(out).toContain(
+      'src="https://raw.githubusercontent.com/o/r/sha/cross/docs/design-doc/diagram.png"',
+    );
+  });
+
+  test("leaves absolute urls untouched", () => {
+    const html = '<a href="https://example.com/x">x</a><img src="http://e/i.png">';
+    expect(rewriteRelativeUrls(html, hrefBase, srcBase)).toBe(html);
+  });
+
+  test("leaves in-page anchors, mailto and data uris untouched", () => {
+    const html =
+      '<a href="#section">a</a><a href="mailto:x@y.z">m</a><img src="data:image/png;base64,AAAA">';
+    expect(rewriteRelativeUrls(html, hrefBase, srcBase)).toBe(html);
+  });
+
+  test("does nothing when no base is provided", () => {
+    const html = '<a href="../x.md">x</a>';
+    expect(rewriteRelativeUrls(html, undefined, undefined)).toBe(html);
+  });
+});
diff --git a/tools/mdp/src/links.ts b/tools/mdp/src/links.ts
new file mode 100644
index 0000000..95c1a60
--- /dev/null
+++ b/tools/mdp/src/links.ts
@@ -0,0 +1,26 @@
+const ABSOLUTE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+
+/**
+ * Rewrite relative href/src attributes to absolute URLs so they resolve against
+ * the document's real location rather than the local preview server.
+ *
+ * Links use `hrefBase` (e.g. a GitHub blob URL); images use `srcBase` (raw URL).
+ * Absolute URLs, in-page anchors, mailto/data/etc. are left untouched. When a
+ * base is undefined those attributes are left as-is.
+ */
+export function rewriteRelativeUrls(
+  html: string,
+  hrefBase: string | undefined,
+  srcBase: string | undefined,
+): string {
+  return html.replace(/(href|src)="([^"]*)"/g, (m, attr: string, url: string) => {
+    if (!url || ABSOLUTE.test(url)) return m;
+    const base = attr === "src" ? srcBase : hrefBase;
+    if (!base) return m;
+    try {
+      return `${attr}="${new URL(url, base).href}"`;
+    } catch {
+      return m;
+    }
+  });
+}
diff --git a/tools/mdp/src/mermaid.test.ts b/tools/mdp/src/mermaid.test.ts
new file mode 100644
index 0000000..aad4dce
--- /dev/null
+++ b/tools/mdp/src/mermaid.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { extractMermaid, injectMermaid } from "./mermaid.ts";
+
+describe("extractMermaid", () => {
+  test("pulls a mermaid block out and leaves a placeholder", () => {
+    const md = "# Hi\n\n```mermaid\nflowchart TD\n  a --> b\n```\n\nbye";
+    const { markdown, blocks } = extractMermaid(md);
+    expect(blocks).toEqual(["flowchart TD\n  a --> b"]);
+    expect(markdown).not.toContain("```mermaid");
+    expect(markdown).toContain("MDPMERMAID0MDP");
+    expect(markdown).toContain("# Hi");
+    expect(markdown).toContain("bye");
+  });
+
+  test("indexes multiple mermaid blocks", () => {
+    const md = "```mermaid\ngraph LR\nx-->y\n```\n\ntext\n\n```mermaid\nsequenceDiagram\nA->>B: hi\n```";
+    const { markdown, blocks } = extractMermaid(md);
+    expect(blocks.length).toBe(2);
+    expect(blocks[1]).toBe("sequenceDiagram\nA->>B: hi");
+    expect(markdown).toContain("MDPMERMAID0MDP");
+    expect(markdown).toContain("MDPMERMAID1MDP");
+  });
+
+  test("leaves non-mermaid fences untouched", () => {
+    const md = "```yaml\nspec: 1\n```";
+    const { markdown, blocks } = extractMermaid(md);
+    expect(blocks).toEqual([]);
+    expect(markdown).toBe(md);
+  });
+
+  test("ignores an inline-code mention of the mermaid fence", () => {
+    const md =
+      "Mermaid code blocks (` ```mermaid `) are rendered automatically.\n\n```sh\nbun test\n```\n";
+    const { markdown, blocks } = extractMermaid(md);
+    expect(blocks).toEqual([]);
+    expect(markdown).toBe(md);
+  });
+
+  test("extracts an indented fence but requires line-start fences", () => {
+    const md = "- item\n\n  ```mermaid\n  graph LR\n  x-->y\n  ```\n";
+    const { blocks } = extractMermaid(md);
+    expect(blocks).toEqual(["  graph LR\n  x-->y"]);
+  });
+});
+
+describe("injectMermaid", () => {
+  test("replaces a placeholder paragraph with a mermaid pre", () => {
+    const html = "<h1>Hi</h1>\n<p>MDPMERMAID0MDP</p>\n<p>bye</p>";
+    const out = injectMermaid(html, ["flowchart TD\n a-->b"]);
+    expect(out).toContain('<pre class="mermaid">');
+    expect(out).not.toContain("MDPMERMAID0MDP");
+    expect(out).toContain("bye");
+  });
+
+  test("html-escapes the diagram source", () => {
+    const out = injectMermaid("<p>MDPMERMAID0MDP</p>", ["a --> b & c"]);
+    expect(out).toContain("a --&gt; b &amp; c");
+  });
+
+  test("does nothing when there are no blocks", () => {
+    const html = "<p>plain</p>";
+    expect(injectMermaid(html, [])).toBe(html);
+  });
+});
diff --git a/tools/mdp/src/mermaid.ts b/tools/mdp/src/mermaid.ts
new file mode 100644
index 0000000..7f60c80
--- /dev/null
+++ b/tools/mdp/src/mermaid.ts
@@ -0,0 +1,41 @@
+// 行頭(+インデント)のフェンスのみ。インラインコード中の ```mermaid 言及は対象外。
+const FENCE = /^[ \t]*```[ \t]*mermaid[^\n]*\n([\s\S]*?)^[ \t]*```[ \t]*$/gm;
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function token(i: number): string {
+  return `MDPMERMAID${i}MDP`;
+}
+
+/**
+ * Pull ```mermaid fenced blocks out of the markdown (the GitHub API would
+ * otherwise render them as plain code). Each is replaced by a text placeholder
+ * that survives markdown rendering and is restored later by injectMermaid.
+ */
+export function extractMermaid(markdown: string): {
+  markdown: string;
+  blocks: string[];
+} {
+  const blocks: string[] = [];
+  const out = markdown.replace(FENCE, (_m, body: string) => {
+    const i = blocks.length;
+    blocks.push(body.replace(/\n$/, ""));
+    return `\n\n${token(i)}\n\n`;
+  });
+  return { markdown: out, blocks };
+}
+
+/** Restore extracted mermaid blocks as <pre class="mermaid"> elements. */
+export function injectMermaid(html: string, blocks: string[]): string {
+  let out = html;
+  blocks.forEach((code, i) => {
+    const el = `<pre class="mermaid">${escapeHtml(code)}</pre>`;
+    out = out.replace(`<p>${token(i)}</p>`, el).replace(token(i), el);
+  });
+  return out;
+}
diff --git a/tools/mdp/src/post.test.ts b/tools/mdp/src/post.test.ts
new file mode 100644
index 0000000..f8a4916
--- /dev/null
+++ b/tools/mdp/src/post.test.ts
@@ -0,0 +1,381 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildCommentBody,
+  findSourceLine,
+  loadPostContext,
+  parseDiffLines,
+  parsePostRequest,
+  parseReactRequest,
+  parseReplyRequest,
+  parseResolveRequest,
+  postComment,
+  postReply,
+  react,
+  resolveThread,
+  type PostContext,
+} from "./post.ts";
+
+describe("parseDiffLines", () => {
+  test("collects added and context right-side lines across hunks", () => {
+    const patch = [
+      "@@ -1,3 +1,4 @@",
+      " context line",
+      "-removed",
+      "+added one",
+      "+added two",
+      " tail",
+      "@@ -10,2 +11,2 @@",
+      " ctx",
+      "+new",
+    ].join("\n");
+    expect(parseDiffLines(patch)).toEqual(new Set([1, 2, 3, 4, 11, 12]));
+  });
+
+  test("ignores 'no newline' markers and empty patches", () => {
+    expect(parseDiffLines("@@ -1 +1 @@\n+only\n\\ No newline at end of file")).toEqual(
+      new Set([1]),
+    );
+    expect(parseDiffLines("")).toEqual(new Set());
+  });
+});
+
+describe("findSourceLine", () => {
+  const md = [
+    "# Title",
+    "",
+    "First paragraph line one",
+    "continues on line two.",
+    "",
+    "- item **bold** text",
+  ].join("\n");
+
+  test("finds the line containing the selection", () => {
+    expect(
+      findSourceLine(
+        md,
+        "paragraph line",
+        "First paragraph line one continues on line two.",
+      ),
+    ).toBe(3);
+    expect(
+      findSourceLine(
+        md,
+        "on line two",
+        "First paragraph line one continues on line two.",
+      ),
+    ).toBe(4);
+  });
+
+  test("resolves a selection spanning two source lines to the first", () => {
+    expect(
+      findSourceLine(
+        md,
+        "line one continues",
+        "First paragraph line one continues on line two.",
+      ),
+    ).toBe(3);
+  });
+
+  test("matches through stripped markdown syntax", () => {
+    expect(findSourceLine(md, "bold text", "item bold text")).toBe(6);
+    expect(findSourceLine(md, "Title", "Title")).toBe(1);
+  });
+
+  test("returns null when nothing matches", () => {
+    expect(findSourceLine(md, "nonexistent", "zzz")).toBeNull();
+    expect(findSourceLine(md, "", "First paragraph line one")).toBeNull();
+  });
+});
+
+describe("buildCommentBody", () => {
+  test("composes quote, body and machine-readable marker", () => {
+    expect(buildCommentBody("selected text", "my comment")).toBe(
+      '> selected text\n\nmy comment\n\n<!-- mdp:range {"text":"selected text"} -->',
+    );
+  });
+
+  test("escapes -- inside the marker so the html comment cannot terminate early", () => {
+    const body = buildCommentBody("a -- b", "c");
+    expect(body).toBe(
+      '> a -- b\n\nc\n\n<!-- mdp:range {"text":"a -\\u002d b"} -->',
+    );
+  });
+});
+
+describe("loadPostContext", () => {
+  test("loads head sha, per-file commentable lines and the viewer", async () => {
+    const ctx = await loadPostContext(
+      "https://github.com/o/r/pull/5",
+      async (args) => {
+        if (args[1] === "repos/o/r/pulls/5") {
+          return JSON.stringify({ head: { sha: "abc" } });
+        }
+        if (args[1] === "user") {
+          return JSON.stringify({ login: "yuma", avatar_url: "http://av" });
+        }
+        expect(args[1]).toBe("repos/o/r/pulls/5/files?per_page=100");
+        return JSON.stringify([
+          { filename: "docs/a.md", patch: "@@ -1 +1,2 @@\n line1\n+line2" },
+          { filename: "bin.png" },
+        ]);
+      },
+    );
+    expect(ctx).toEqual({
+      owner: "o",
+      repo: "r",
+      number: 5,
+      headSha: "abc",
+      diffLines: new Map([["docs/a.md", new Set([1, 2])]]),
+      user: { login: "yuma", avatarUrl: "http://av" },
+    });
+  });
+
+  test("keeps posting enabled when the viewer lookup fails", async () => {
+    const ctx = await loadPostContext(
+      "https://github.com/o/r/pull/5",
+      async (args) => {
+        if (args[1] === "repos/o/r/pulls/5") {
+          return JSON.stringify({ head: { sha: "abc" } });
+        }
+        if (args[1] === "user") throw new Error("no auth");
+        return JSON.stringify([]);
+      },
+    );
+    expect(ctx.user).toEqual({ login: "", avatarUrl: "" });
+  });
+
+  test("throws on a non-PR url", async () => {
+    await expect(loadPostContext("nope", async () => "")).rejects.toThrow(
+      "not a PR URL",
+    );
+  });
+});
+
+describe("postComment", () => {
+  const ctx: PostContext = {
+    owner: "o",
+    repo: "r",
+    number: 5,
+    headSha: "abc",
+    diffLines: new Map([["docs/a.md", new Set([3])]]),
+    user: { login: "yuma", avatarUrl: "" },
+  };
+  const md = "# T\n\nhello world here\n";
+  const req = {
+    doc: "docs/a.md",
+    selectedText: "hello world",
+    blockText: "hello world here",
+    body: "nit",
+  };
+
+  test("posts an inline review comment when the line is in the diff", async () => {
+    let seen: string[] = [];
+    const res = await postComment(req, ctx, md, async (args) => {
+      seen = args;
+      return JSON.stringify({ id: 777, node_id: "C_new", html_url: "http://c" });
+    });
+    expect(seen[1]).toBe("repos/o/r/pulls/5/comments");
+    expect(seen).toContain("path=docs/a.md");
+    expect(seen).toContain("line=3");
+    expect(seen).toContain("side=RIGHT");
+    expect(seen).toContain("commit_id=abc");
+    expect(seen.join("\n")).toContain("> hello world");
+    expect(res).toEqual({
+      kind: "inline",
+      url: "http://c",
+      replyTo: 777,
+      subjectId: "C_new",
+    });
+  });
+
+  test("falls back to an issue comment for out-of-diff lines", async () => {
+    let seen: string[] = [];
+    const res = await postComment(
+      req,
+      { ...ctx, diffLines: new Map() },
+      md,
+      async (args) => {
+        seen = args;
+        return JSON.stringify({ html_url: "http://i" });
+      },
+    );
+    expect(seen[1]).toBe("repos/o/r/issues/5/comments");
+    expect(seen.join("\n")).toContain("**docs/a.md:3**");
+    expect(res).toEqual({
+      kind: "issue",
+      url: "http://i",
+      replyTo: null,
+      subjectId: null,
+    });
+  });
+
+  test("falls back without a line number when mapping fails", async () => {
+    let seen: string[] = [];
+    await postComment(
+      { ...req, selectedText: "no such text", blockText: "zzz" },
+      ctx,
+      md,
+      async (args) => {
+        seen = args;
+        return JSON.stringify({ html_url: "http://i" });
+      },
+    );
+    expect(seen[1]).toBe("repos/o/r/issues/5/comments");
+    expect(seen.join("\n")).toContain("**docs/a.md**\n\n> no such text");
+  });
+});
+
+describe("parseReplyRequest", () => {
+  test("accepts a thread id and body", () => {
+    expect(parseReplyRequest({ threadId: 12, body: "ok" })).toEqual({
+      threadId: 12,
+      body: "ok",
+    });
+  });
+
+  test("rejects bad ids and empty bodies", () => {
+    expect(parseReplyRequest(null)).toBeNull();
+    expect(parseReplyRequest({ threadId: "12", body: "ok" })).toBeNull();
+    expect(parseReplyRequest({ threadId: 0, body: "ok" })).toBeNull();
+    expect(parseReplyRequest({ threadId: 12, body: " " })).toBeNull();
+  });
+});
+
+describe("postReply", () => {
+  test("posts to the review-comment replies endpoint", async () => {
+    const ctx: PostContext = {
+      owner: "o",
+      repo: "r",
+      number: 5,
+      headSha: "abc",
+      diffLines: new Map(),
+      user: { login: "yuma", avatarUrl: "" },
+    };
+    let seen: string[] = [];
+    const res = await postReply({ threadId: 42, body: "reply!" }, ctx, async (args) => {
+      seen = args;
+      return JSON.stringify({ node_id: "C_rep", html_url: "http://rep" });
+    });
+    expect(seen[1]).toBe("repos/o/r/pulls/5/comments/42/replies");
+    expect(seen).toContain("body=reply!");
+    expect(res).toEqual({ url: "http://rep", subjectId: "C_rep" });
+  });
+});
+
+describe("parsePostRequest", () => {
+  const valid = {
+    doc: "docs/a.md",
+    selectedText: "sel",
+    blockText: "block sel text",
+    body: "comment",
+  };
+
+  test("accepts a well-formed request", () => {
+    expect(parsePostRequest(valid)).toEqual(valid);
+  });
+
+  test("rejects missing fields, wrong types and empty bodies", () => {
+    expect(parsePostRequest(null)).toBeNull();
+    expect(parsePostRequest("x")).toBeNull();
+    expect(parsePostRequest({ ...valid, doc: 1 })).toBeNull();
+    expect(parsePostRequest({ ...valid, body: "  " })).toBeNull();
+    const { blockText: _omitted, ...missing } = valid;
+    expect(parsePostRequest(missing)).toBeNull();
+  });
+});
+
+describe("parseResolveRequest", () => {
+  test("accepts a node id", () => {
+    expect(parseResolveRequest({ threadId: "RT_1" })).toEqual({
+      threadId: "RT_1",
+    });
+  });
+
+  test("rejects missing or empty ids", () => {
+    expect(parseResolveRequest(null)).toBeNull();
+    expect(parseResolveRequest({ threadId: 3 })).toBeNull();
+    expect(parseResolveRequest({ threadId: " " })).toBeNull();
+  });
+});
+
+describe("resolveThread", () => {
+  test("runs the resolveReviewThread mutation", async () => {
+    let seen: string[] = [];
+    const res = await resolveThread("RT_1", async (args) => {
+      seen = args;
+      return JSON.stringify({
+        data: { resolveReviewThread: { thread: { isResolved: true } } },
+      });
+    });
+    expect(seen[0]).toBe("api");
+    expect(seen[1]).toBe("graphql");
+    expect(seen.join("\n")).toContain("resolveReviewThread");
+    expect(seen).toContain("id=RT_1");
+    expect(res).toEqual({ resolved: true });
+  });
+
+  test("throws when the mutation does not resolve", async () => {
+    await expect(
+      resolveThread("RT_1", async () => JSON.stringify({ data: {} })),
+    ).rejects.toThrow("could not resolve");
+  });
+});
+
+describe("parseReactRequest", () => {
+  test("accepts a subject, known content and on flag", () => {
+    expect(
+      parseReactRequest({ subjectId: "C_1", content: "HEART", on: true }),
+    ).toEqual({ subjectId: "C_1", content: "HEART", on: true });
+  });
+
+  test("rejects unknown contents and bad shapes", () => {
+    expect(parseReactRequest(null)).toBeNull();
+    expect(
+      parseReactRequest({ subjectId: "", content: "HEART", on: true }),
+    ).toBeNull();
+    expect(
+      parseReactRequest({ subjectId: "C_1", content: "SPARKLE", on: true }),
+    ).toBeNull();
+    expect(
+      parseReactRequest({ subjectId: "C_1", content: "HEART", on: "yes" }),
+    ).toBeNull();
+  });
+});
+
+describe("react", () => {
+  test("adds a reaction via graphql", async () => {
+    let seen: string[] = [];
+    const res = await react(
+      { subjectId: "C_1", content: "THUMBS_UP", on: true },
+      async (args) => {
+        seen = args;
+        return JSON.stringify({ data: { addReaction: {} } });
+      },
+    );
+    expect(seen[1]).toBe("graphql");
+    expect(seen.join("\n")).toContain("addReaction");
+    expect(seen).toContain("id=C_1");
+    expect(seen).toContain("c=THUMBS_UP");
+    expect(res).toEqual({ ok: true });
+  });
+
+  test("removes a reaction via graphql", async () => {
+    let seen: string[] = [];
+    await react(
+      { subjectId: "C_1", content: "EYES", on: false },
+      async (args) => {
+        seen = args;
+        return JSON.stringify({ data: { removeReaction: {} } });
+      },
+    );
+    expect(seen.join("\n")).toContain("removeReaction");
+  });
+
+  test("throws when the mutation returns no data", async () => {
+    await expect(
+      react({ subjectId: "C_1", content: "EYES", on: true }, async () =>
+        JSON.stringify({}),
+      ),
+    ).rejects.toThrow("reaction failed");
+  });
+});
diff --git a/tools/mdp/src/post.ts b/tools/mdp/src/post.ts
new file mode 100644
index 0000000..e263a71
--- /dev/null
+++ b/tools/mdp/src/post.ts
@@ -0,0 +1,313 @@
+import { normalizeText, parsePrUrl, stripMarkdownLine } from "./comments.ts";
+import type { RunGh } from "./pr.ts";
+
+/** RIGHT 側(head)のコメント可能行 — unified diff の追加行と文脈行。 */
+export function parseDiffLines(patch: string): Set<number> {
+  const lines = new Set<number>();
+  let right = 0;
+  for (const l of patch.split("\n")) {
+    const h = l.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (h) {
+      right = Number(h[1]);
+      continue;
+    }
+    if (right === 0) continue;
+    if (l.startsWith("+") || l.startsWith(" ")) {
+      lines.add(right);
+      right++;
+    }
+  }
+  return lines;
+}
+
+/**
+ * レンダリング済みテキストの選択をソース行(1-based)へ写像する。
+ * ブロックテキストに含まれる行を候補とし、選択を含む最初の行、
+ * なければ選択と重なる最初の行を返す。どれも重ならなければ null。
+ */
+export function findSourceLine(
+  markdown: string,
+  selectedText: string,
+  blockText: string,
+): number | null {
+  const sel = normalizeText(selectedText);
+  const block = normalizeText(blockText);
+  if (sel === "" || block === "") return null;
+  const lines = markdown.split("\n");
+  const candidates: { line: number; text: string }[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const text = normalizeText(stripMarkdownLine(lines[i]));
+    if (text !== "" && block.includes(text)) candidates.push({ line: i + 1, text });
+  }
+  const containing = candidates.find((c) => c.text.includes(sel));
+  if (containing) return containing.line;
+  const overlapping = candidates.find(
+    (c) => sel.includes(c.text) || suffixOverlaps(c.text, sel),
+  );
+  return overlapping?.line ?? null;
+}
+
+/** `a` の末尾(4文字以上)が `b` の先頭と一致 — 行の途中から選択が続いている形。 */
+function suffixOverlaps(a: string, b: string): boolean {
+  for (let k = Math.min(a.length, b.length); k >= 4; k--) {
+    if (a.slice(-k) === b.slice(0, k)) return true;
+  }
+  return false;
+}
+
+/**
+ * 投稿本文: 選択テキストの引用 + ユーザー本文 + 機械可読マーカー。
+ * マーカーは HTML コメントなので JSON 中の "--" は - でエスケープする。
+ */
+export function buildCommentBody(selectedText: string, body: string): string {
+  const json = JSON.stringify({ text: selectedText }).replaceAll("--", "-\\u002d");
+  return `> ${selectedText}\n\n${body.trim()}\n\n<!-- mdp:range ${json} -->`;
+}
+
+export type PostRequest = {
+  doc: string;
+  selectedText: string;
+  blockText: string;
+  body: string;
+};
+
+/** /api/comment の JSON ボディを検証つきで PostRequest にする。 */
+export function parsePostRequest(body: unknown): PostRequest | null {
+  if (typeof body !== "object" || body === null) return null;
+  const b = body as Record<string, unknown>;
+  if (
+    typeof b.doc !== "string" ||
+    typeof b.selectedText !== "string" ||
+    typeof b.blockText !== "string" ||
+    typeof b.body !== "string" ||
+    b.body.trim() === ""
+  ) {
+    return null;
+  }
+  return {
+    doc: b.doc,
+    selectedText: b.selectedText,
+    blockText: b.blockText,
+    body: b.body,
+  };
+}
+
+export type PostContext = {
+  owner: string;
+  repo: string;
+  number: number;
+  headSha: string;
+  /** path → RIGHT 側コメント可能行。 */
+  diffLines: Map<string, Set<number>>;
+  /** 投稿者(表示用)。取得失敗時は空文字。 */
+  user: { login: string; avatarUrl: string };
+};
+
+/** 投稿に必要な PR 情報(head SHA と各ファイルの diff 行)を取得する。 */
+export async function loadPostContext(
+  prUrl: string,
+  runGh: RunGh,
+): Promise<PostContext> {
+  const ref = parsePrUrl(prUrl);
+  if (!ref) throw new Error(`not a PR URL: ${prUrl}`);
+  const base = `repos/${ref.owner}/${ref.repo}/pulls/${ref.number}`;
+  const pr = JSON.parse(await runGh(["api", base]));
+  const files = JSON.parse(await runGh(["api", `${base}/files?per_page=100`]));
+  const diffLines = new Map<string, Set<number>>();
+  for (const f of files as { filename: string; patch?: string }[]) {
+    if (f.patch) diffLines.set(f.filename, parseDiffLines(f.patch));
+  }
+  let user = { login: "", avatarUrl: "" };
+  try {
+    const me = JSON.parse(await runGh(["api", "user"]));
+    user = { login: me.login ?? "", avatarUrl: me.avatar_url ?? "" };
+  } catch {
+    // 表示用の情報なので取れなくても投稿機能は生かす
+  }
+  return { ...ref, headSha: pr.head.sha, diffLines, user };
+}
+
+export type ReplyRequest = { threadId: number; body: string };
+
+/** /api/reply の JSON ボディを検証つきで ReplyRequest にする。 */
+export function parseReplyRequest(body: unknown): ReplyRequest | null {
+  if (typeof body !== "object" || body === null) return null;
+  const b = body as Record<string, unknown>;
+  if (
+    typeof b.threadId !== "number" ||
+    !Number.isInteger(b.threadId) ||
+    b.threadId <= 0 ||
+    typeof b.body !== "string" ||
+    b.body.trim() === ""
+  ) {
+    return null;
+  }
+  return { threadId: b.threadId, body: b.body };
+}
+
+/** 既存レビュースレッド(先頭コメント id)への返信。 */
+export async function postReply(
+  req: ReplyRequest,
+  ctx: PostContext,
+  runGh: RunGh,
+): Promise<{ url: string; subjectId: string | null }> {
+  const out = await runGh([
+    "api",
+    `repos/${ctx.owner}/${ctx.repo}/pulls/${ctx.number}/comments/${req.threadId}/replies`,
+    "-f",
+    `body=${req.body}`,
+  ]);
+  const j = JSON.parse(out);
+  return {
+    url: j.html_url ?? "",
+    subjectId: typeof j.node_id === "string" ? j.node_id : null,
+  };
+}
+
+export type ResolveRequest = { threadId: string };
+
+/** /api/resolve の JSON ボディを検証つきで ResolveRequest にする。 */
+export function parseResolveRequest(body: unknown): ResolveRequest | null {
+  if (typeof body !== "object" || body === null) return null;
+  const b = body as Record<string, unknown>;
+  if (typeof b.threadId !== "string" || b.threadId.trim() === "") return null;
+  return { threadId: b.threadId };
+}
+
+const RESOLVE_MUTATION =
+  "mutation($id:ID!){resolveReviewThread(input:{threadId:$id}){thread{isResolved}}}";
+
+/** レビュースレッドを resolve する(GraphQL mutation)。 */
+export async function resolveThread(
+  threadId: string,
+  runGh: RunGh,
+): Promise<{ resolved: true }> {
+  const out = await runGh([
+    "api",
+    "graphql",
+    "-f",
+    `query=${RESOLVE_MUTATION}`,
+    "-f",
+    `id=${threadId}`,
+  ]);
+  const resolved =
+    JSON.parse(out)?.data?.resolveReviewThread?.thread?.isResolved;
+  if (resolved !== true) throw new Error(`could not resolve thread ${threadId}`);
+  return { resolved: true };
+}
+
+const REACTION_CONTENTS = [
+  "THUMBS_UP",
+  "THUMBS_DOWN",
+  "LAUGH",
+  "HOORAY",
+  "CONFUSED",
+  "HEART",
+  "ROCKET",
+  "EYES",
+] as const;
+
+export type ReactRequest = {
+  /** リアクション対象コメントの GraphQL node id。 */
+  subjectId: string;
+  content: string;
+  /** true で追加、false で解除。 */
+  on: boolean;
+};
+
+/** /api/react の JSON ボディを検証つきで ReactRequest にする。 */
+export function parseReactRequest(body: unknown): ReactRequest | null {
+  if (typeof body !== "object" || body === null) return null;
+  const b = body as Record<string, unknown>;
+  if (
+    typeof b.subjectId !== "string" ||
+    b.subjectId.trim() === "" ||
+    typeof b.content !== "string" ||
+    !(REACTION_CONTENTS as readonly string[]).includes(b.content) ||
+    typeof b.on !== "boolean"
+  ) {
+    return null;
+  }
+  return { subjectId: b.subjectId, content: b.content, on: b.on };
+}
+
+/** コメントへのリアクションを追加/解除する(GraphQL mutation)。 */
+export async function react(
+  req: ReactRequest,
+  runGh: RunGh,
+): Promise<{ ok: true }> {
+  const name = req.on ? "addReaction" : "removeReaction";
+  const mutation = `mutation($id:ID!,$c:ReactionContent!){${name}(input:{subjectId:$id,content:$c}){clientMutationId}}`;
+  const out = await runGh([
+    "api",
+    "graphql",
+    "-f",
+    `query=${mutation}`,
+    "-f",
+    `id=${req.subjectId}`,
+    "-f",
+    `c=${req.content}`,
+  ]);
+  if (!JSON.parse(out)?.data) throw new Error("reaction failed");
+  return { ok: true };
+}
+
+export type PostResult = {
+  kind: "inline" | "issue";
+  url: string;
+  /** インライン投稿された新コメントの id(そのまま返信先に使える)。 */
+  replyTo: number | null;
+  /** 新コメントの GraphQL node id(リアクション用)。 */
+  subjectId: string | null;
+};
+
+/**
+ * コメントを投稿する。ソース行が特定でき diff に含まれればインライン
+ * レビューコメント、そうでなければファイル名(と行番号)付きの issue コメント。
+ */
+export async function postComment(
+  req: PostRequest,
+  ctx: PostContext,
+  markdown: string,
+  runGh: RunGh,
+): Promise<PostResult> {
+  const body = buildCommentBody(req.selectedText, req.body);
+  const line = findSourceLine(markdown, req.selectedText, req.blockText);
+  const repo = `repos/${ctx.owner}/${ctx.repo}`;
+  if (line !== null && (ctx.diffLines.get(req.doc)?.has(line) ?? false)) {
+    const out = await runGh([
+      "api",
+      `${repo}/pulls/${ctx.number}/comments`,
+      "-f",
+      `body=${body}`,
+      "-f",
+      `commit_id=${ctx.headSha}`,
+      "-f",
+      `path=${req.doc}`,
+      "-F",
+      `line=${line}`,
+      "-f",
+      "side=RIGHT",
+    ]);
+    const j = JSON.parse(out);
+    return {
+      kind: "inline",
+      url: j.html_url ?? "",
+      replyTo: typeof j.id === "number" ? j.id : null,
+      subjectId: typeof j.node_id === "string" ? j.node_id : null,
+    };
+  }
+  const loc = line !== null ? `**${req.doc}:${line}**` : `**${req.doc}**`;
+  const out = await runGh([
+    "api",
+    `${repo}/issues/${ctx.number}/comments`,
+    "-f",
+    `body=${loc}\n\n${body}`,
+  ]);
+  return {
+    kind: "issue",
+    url: JSON.parse(out).html_url ?? "",
+    replyTo: null,
+    subjectId: null,
+  };
+}
diff --git a/tools/mdp/src/pr.test.ts b/tools/mdp/src/pr.test.ts
new file mode 100644
index 0000000..937328a
--- /dev/null
+++ b/tools/mdp/src/pr.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import {
+  contentApiPath,
+  filterMarkdownFiles,
+  parsePrRef,
+} from "./pr.ts";
+
+describe("parsePrRef", () => {
+  test("accepts a github pull request URL", () => {
+    expect(parsePrRef("https://github.com/o/r/pull/126531")).toBe(
+      "https://github.com/o/r/pull/126531",
+    );
+  });
+
+  test("accepts a bare PR number", () => {
+    expect(parsePrRef("126531")).toBe("126531");
+  });
+
+  test("accepts a #-prefixed PR number", () => {
+    expect(parsePrRef("#126531")).toBe("126531");
+  });
+
+  test("rejects file paths and non-pull URLs", () => {
+    expect(parsePrRef("README.md")).toBeNull();
+    expect(parsePrRef("https://github.com/o/r/blob/main/x.md")).toBeNull();
+    expect(parsePrRef("-")).toBeNull();
+    expect(parsePrRef(undefined)).toBeNull();
+  });
+});
+
+describe("filterMarkdownFiles", () => {
+  test("keeps only .md and .markdown paths", () => {
+    const files = [
+      { path: "docs/a.md" },
+      { path: "src/b.ts" },
+      { path: "c.markdown" },
+      { path: "d.MD" },
+      { path: "readme" },
+    ];
+    expect(filterMarkdownFiles(files)).toEqual([
+      "docs/a.md",
+      "c.markdown",
+      "d.MD",
+    ]);
+  });
+
+  test("returns an empty list when nothing matches", () => {
+    expect(filterMarkdownFiles([{ path: "a.ts" }])).toEqual([]);
+  });
+});
+
+describe("contentApiPath", () => {
+  test("builds a contents API path at a ref", () => {
+    expect(contentApiPath("o", "r", "docs/a.md", "abc123")).toBe(
+      "repos/o/r/contents/docs/a.md?ref=abc123",
+    );
+  });
+
+  test("url-encodes the path segments", () => {
+    expect(contentApiPath("o", "r", "cross/設計.md", "sha")).toBe(
+      "repos/o/r/contents/cross/%E8%A8%AD%E8%A8%88.md?ref=sha",
+    );
+  });
+});
diff --git a/tools/mdp/src/pr.ts b/tools/mdp/src/pr.ts
new file mode 100644
index 0000000..d73872a
--- /dev/null
+++ b/tools/mdp/src/pr.ts
@@ -0,0 +1,78 @@
+export type PrDoc = {
+  name: string;
+  markdown: string;
+  hrefBase: string;
+  srcBase: string;
+};
+export type PrResult = { title: string; url: string; docs: PrDoc[] };
+
+/** A function that runs `gh` with the given args and resolves its stdout. */
+export type RunGh = (args: string[]) => Promise<string>;
+
+/** Recognise a PR reference: a github pull URL or a (optionally #-prefixed) number. */
+export function parsePrRef(arg: string | undefined): string | null {
+  if (!arg) return null;
+  if (/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+/.test(arg)) return arg;
+  const m = arg.match(/^#?(\d+)$/);
+  return m ? m[1] : null;
+}
+
+/** Keep only markdown file paths from a PR's changed-files list. */
+export function filterMarkdownFiles(files: { path: string }[]): string[] {
+  return files
+    .map((f) => f.path)
+    .filter((p) => /\.(md|markdown)$/i.test(p));
+}
+
+/** Build a GitHub contents API path for a file at a ref (path segments encoded). */
+export function contentApiPath(
+  owner: string,
+  repo: string,
+  path: string,
+  ref: string,
+): string {
+  const encoded = path.split("/").map(encodeURIComponent).join("/");
+  return `repos/${owner}/${repo}/contents/${encoded}?ref=${ref}`;
+}
+
+/** Load the changed markdown files of a PR (at the PR head) via `gh`. */
+export async function loadPrDocs(
+  ref: string,
+  runGh: RunGh,
+): Promise<PrResult> {
+  const meta = JSON.parse(
+    await runGh([
+      "pr",
+      "view",
+      ref,
+      "--json",
+      "files,title,url,headRefOid,headRepository,headRepositoryOwner",
+    ]),
+  );
+  const owner: string = meta.headRepositoryOwner.login;
+  const repo: string = meta.headRepository.name;
+  const sha: string = meta.headRefOid;
+
+  const paths = filterMarkdownFiles(meta.files ?? []);
+  if (paths.length === 0) {
+    throw new Error(`no markdown files changed in PR ${ref}`);
+  }
+
+  const docs: PrDoc[] = [];
+  for (const path of paths) {
+    const markdown = await runGh([
+      "api",
+      contentApiPath(owner, repo, path, sha),
+      "-H",
+      "Accept: application/vnd.github.raw",
+    ]);
+    const dir = path.includes("/") ? `${path.slice(0, path.lastIndexOf("/"))}/` : "";
+    docs.push({
+      name: path,
+      markdown,
+      hrefBase: `https://github.com/${owner}/${repo}/blob/${sha}/${dir}`,
+      srcBase: `https://raw.githubusercontent.com/${owner}/${repo}/${sha}/${dir}`,
+    });
+  }
+  return { title: meta.title, url: meta.url, docs };
+}
diff --git a/tools/mdp/src/render.test.ts b/tools/mdp/src/render.test.ts
new file mode 100644
index 0000000..0a4d8df
--- /dev/null
+++ b/tools/mdp/src/render.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { buildMarkdownRequest, renderMarkdown } from "./render.ts";
+
+describe("buildMarkdownRequest", () => {
+  test("posts gfm text to the github markdown api", () => {
+    const { url, init } = buildMarkdownRequest("# Hi");
+    expect(url).toBe("https://api.github.com/markdown");
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({
+      text: "# Hi",
+      mode: "gfm",
+    });
+  });
+
+  test("omits Authorization when no token is given", () => {
+    const { init } = buildMarkdownRequest("x");
+    const headers = init.headers as Record<string, string>;
+    expect(headers.Authorization).toBeUndefined();
+  });
+
+  test("adds a bearer Authorization header when a token is given", () => {
+    const { init } = buildMarkdownRequest("x", "tok123");
+    const headers = init.headers as Record<string, string>;
+    expect(headers.Authorization).toBe("Bearer tok123");
+  });
+});
+
+describe("renderMarkdown", () => {
+  test("returns the response body html on success", async () => {
+    const fakeFetch = async () =>
+      new Response("<h1>Hi</h1>", { status: 200 });
+    const html = await renderMarkdown("# Hi", { fetchFn: fakeFetch });
+    expect(html).toBe("<h1>Hi</h1>");
+  });
+
+  test("throws a rate-limit message on 403", async () => {
+    const fakeFetch = async () => new Response("", { status: 403 });
+    expect(renderMarkdown("x", { fetchFn: fakeFetch })).rejects.toThrow(
+      /rate limit/i,
+    );
+  });
+
+  test("throws with the status on other errors", async () => {
+    const fakeFetch = async () =>
+      new Response("boom", { status: 500 });
+    expect(renderMarkdown("x", { fetchFn: fakeFetch })).rejects.toThrow(
+      /500/,
+    );
+  });
+});
diff --git a/tools/mdp/src/render.ts b/tools/mdp/src/render.ts
new file mode 100644
index 0000000..af2af80
--- /dev/null
+++ b/tools/mdp/src/render.ts
@@ -0,0 +1,43 @@
+const API_URL = "https://api.github.com/markdown";
+
+type FetchFn = (url: string, init: RequestInit) => Promise<Response>;
+
+/** Build the GitHub markdown API request (pure). */
+export function buildMarkdownRequest(
+  markdown: string,
+  token?: string,
+): { url: string; init: RequestInit } {
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "Content-Type": "application/json",
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return {
+    url: API_URL,
+    init: {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ text: markdown, mode: "gfm" }),
+    },
+  };
+}
+
+/** Render markdown to an HTML fragment via the GitHub API. */
+export async function renderMarkdown(
+  markdown: string,
+  opts: { token?: string; fetchFn?: FetchFn } = {},
+): Promise<string> {
+  const { url, init } = buildMarkdownRequest(markdown, opts.token);
+  const fetchFn = opts.fetchFn ?? fetch;
+  const res = await fetchFn(url, init);
+  if (!res.ok) {
+    if (res.status === 403 || res.status === 429) {
+      throw new Error(
+        `GitHub API rate limit hit (HTTP ${res.status}). Set GITHUB_TOKEN to raise the limit.`,
+      );
+    }
+    throw new Error(`GitHub markdown API failed: HTTP ${res.status}`);
+  }
+  return res.text();
+}
diff --git a/tools/mdp/src/resolve.test.ts b/tools/mdp/src/resolve.test.ts
new file mode 100644
index 0000000..4cb97f3
--- /dev/null
+++ b/tools/mdp/src/resolve.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { resolveInput } from "./input.ts";
+
+const baseDeps = {
+  stdinIsTTY: true,
+  readStdin: async () => "STDIN_MD",
+  readFile: async (p: string) => `FILE:${p}`,
+  fetchFn: async (_u: string) => new Response("URL_MD", { status: 200 }),
+};
+
+describe("resolveInput", () => {
+  test("reads stdin for '-' with a none base", async () => {
+    const r = await resolveInput("-", baseDeps);
+    expect(r).toEqual({ markdown: "STDIN_MD", base: { kind: "none" } });
+  });
+
+  test("reads an absolute file path and sets a file base of its dir", async () => {
+    const r = await resolveInput("/home/u/docs/README.md", baseDeps);
+    expect(r.markdown).toBe("FILE:/home/u/docs/README.md");
+    expect(r.base).toEqual({ kind: "file", dir: "/home/u/docs" });
+  });
+
+  test("fetches a github blob url (normalized to raw) with a url base", async () => {
+    let fetched = "";
+    const r = await resolveInput(
+      "https://github.com/o/r/blob/main/docs/README.md",
+      {
+        ...baseDeps,
+        fetchFn: async (u: string) => {
+          fetched = u;
+          return new Response("URL_MD", { status: 200 });
+        },
+      },
+    );
+    expect(fetched).toBe(
+      "https://raw.githubusercontent.com/o/r/main/docs/README.md",
+    );
+    expect(r.markdown).toBe("URL_MD");
+    expect(r.base).toEqual({
+      kind: "url",
+      dir: "https://raw.githubusercontent.com/o/r/main/docs",
+    });
+  });
+
+  test("throws when there is no input", async () => {
+    expect(resolveInput(undefined, baseDeps)).rejects.toThrow(/no input/i);
+  });
+
+  test("throws when a url fetch fails", async () => {
+    expect(
+      resolveInput("https://example.com/x.md", {
+        ...baseDeps,
+        fetchFn: async () => new Response("", { status: 404 }),
+      }),
+    ).rejects.toThrow(/404/);
+  });
+});
diff --git a/tools/mdp/src/server.test.ts b/tools/mdp/src/server.test.ts
new file mode 100644
index 0000000..e6dd613
--- /dev/null
+++ b/tools/mdp/src/server.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { makeFetchHandler, resolveAsset } from "./server.ts";
+
+describe("resolveAsset", () => {
+  test("returns notfound for a 'none' base", () => {
+    expect(resolveAsset({ kind: "none" }, "/img/a.png")).toEqual({
+      type: "notfound",
+    });
+  });
+
+  test("resolves a relative path under a file base dir", () => {
+    expect(
+      resolveAsset({ kind: "file", dir: "/home/u/docs" }, "/img/a.png"),
+    ).toEqual({ type: "file", path: "/home/u/docs/img/a.png" });
+  });
+
+  test("rejects path traversal outside the file base dir", () => {
+    expect(
+      resolveAsset({ kind: "file", dir: "/home/u/docs" }, "/../secret.txt"),
+    ).toEqual({ type: "notfound" });
+  });
+
+  test("redirects a relative path to the raw url base", () => {
+    expect(
+      resolveAsset(
+        { kind: "url", dir: "https://raw.githubusercontent.com/o/r/main/docs" },
+        "/img/a.png",
+      ),
+    ).toEqual({
+      type: "redirect",
+      url: "https://raw.githubusercontent.com/o/r/main/docs/img/a.png",
+    });
+  });
+});
+
+describe("makeFetchHandler", () => {
+  const routes = new Map([["/", "<html>home</html>"]]);
+
+  test("serves routes for GET", async () => {
+    const handle = makeFetchHandler(routes, { kind: "none" });
+    const res = await handle(new Request("http://x/"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("<html>home</html>");
+  });
+
+  test("dispatches POST json to the api handler", async () => {
+    let got: unknown;
+    const handle = makeFetchHandler(routes, { kind: "none" }, async (path, body) => {
+      got = { path, body };
+      return Response.json({ ok: true });
+    });
+    const res = await handle(
+      new Request("http://x/api/comment", {
+        method: "POST",
+        body: JSON.stringify({ a: 1 }),
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(got).toEqual({ path: "/api/comment", body: { a: 1 } });
+  });
+
+  test("400 on unparsable POST bodies", async () => {
+    const handle = makeFetchHandler(routes, { kind: "none" }, async () =>
+      Response.json({ ok: true }),
+    );
+    const res = await handle(
+      new Request("http://x/api/comment", { method: "POST", body: "not json" }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("404 for POSTs the handler declines or without a handler", async () => {
+    const declined = makeFetchHandler(routes, { kind: "none" }, async () => null);
+    const res1 = await declined(
+      new Request("http://x/other", { method: "POST", body: "{}" }),
+    );
+    expect(res1.status).toBe(404);
+    const none = makeFetchHandler(routes, { kind: "none" });
+    const res2 = await none(
+      new Request("http://x/api/comment", { method: "POST", body: "{}" }),
+    );
+    expect(res2.status).toBe(404);
+  });
+});
diff --git a/tools/mdp/src/server.ts b/tools/mdp/src/server.ts
new file mode 100644
index 0000000..9916231
--- /dev/null
+++ b/tools/mdp/src/server.ts
@@ -0,0 +1,95 @@
+import { join, sep } from "node:path";
+
+export type Base =
+  | { kind: "none" }
+  | { kind: "file"; dir: string }
+  | { kind: "url"; dir: string };
+
+export type AssetResult =
+  | { type: "file"; path: string }
+  | { type: "redirect"; url: string }
+  | { type: "notfound" };
+
+/** Map a request pathname to a local file or a redirect, based on the input's base. */
+export function resolveAsset(base: Base, pathname: string): AssetResult {
+  if (base.kind === "none") return { type: "notfound" };
+
+  if (base.kind === "url") {
+    const rel = pathname.replace(/^\/+/, "");
+    return { type: "redirect", url: `${base.dir}/${rel}` };
+  }
+
+  const target = join(base.dir, pathname);
+  if (target !== base.dir && !target.startsWith(base.dir + sep)) {
+    return { type: "notfound" };
+  }
+  return { type: "file", path: target };
+}
+
+/** POST /api/* を処理するハンドラ。null を返すと未処理(404)。 */
+export type ApiHandler = (
+  pathname: string,
+  body: unknown,
+) => Promise<Response | null>;
+
+/** ルート・アセット・API を捌く fetch ハンドラ(Bun.serve から独立してテスト可能)。 */
+export function makeFetchHandler(
+  routes: Map<string, string>,
+  base: Base,
+  api?: ApiHandler,
+): (req: Request) => Promise<Response> {
+  return async (req) => {
+    const { pathname } = new URL(req.url);
+    if (req.method === "POST") {
+      if (api) {
+        let body: unknown;
+        try {
+          body = await req.json();
+        } catch {
+          return Response.json({ error: "invalid JSON body" }, { status: 400 });
+        }
+        const res = await api(pathname, body);
+        if (res) return res;
+      }
+      return new Response("Not found", { status: 404 });
+    }
+    const page = routes.get(pathname);
+    if (page !== undefined) {
+      return new Response(page, {
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
+    const asset = resolveAsset(base, decodeURIComponent(pathname));
+    if (asset.type === "redirect") {
+      return Response.redirect(asset.url, 302);
+    }
+    if (asset.type === "file") {
+      const file = Bun.file(asset.path);
+      if (await file.exists()) return new Response(file);
+    }
+    return new Response("Not found", { status: 404 });
+  };
+}
+
+/** Serve the route map on an ephemeral port, opening it in the browser. Resolves on SIGINT. */
+export async function serve(
+  routes: Map<string, string>,
+  base: Base,
+  api?: ApiHandler,
+): Promise<void> {
+  const server = Bun.serve({
+    port: 0,
+    fetch: makeFetchHandler(routes, base, api),
+  });
+
+  const url = `http://localhost:${server.port}`;
+  console.error(`mdp serving ${url} (Ctrl-C to quit)`);
+  Bun.spawn(["open", url]);
+
+  await new Promise<void>((resolve) => {
+    process.on("SIGINT", () => {
+      server.stop();
+      resolve();
+    });
+  });
+}
diff --git a/tools/mdp/src/tabs.test.ts b/tools/mdp/src/tabs.test.ts
new file mode 100644
index 0000000..a710082
--- /dev/null
+++ b/tools/mdp/src/tabs.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { tabLabels } from "./tabs.ts";
+
+describe("tabLabels", () => {
+  test("strips the directory prefix common to all files", () => {
+    expect(
+      tabLabels([
+        "docs/agents/design/done.md",
+        "docs/agents/design/execplan.md",
+        "docs/agents/design/research.md",
+      ]),
+    ).toEqual(["done.md", "execplan.md", "research.md"]);
+  });
+
+  test("keeps the distinguishing directories", () => {
+    expect(tabLabels(["docs/a/x.md", "docs/b/x.md"])).toEqual([
+      "a/x.md",
+      "b/x.md",
+    ]);
+  });
+
+  test("leaves names without a common directory unchanged", () => {
+    expect(tabLabels(["x.md", "docs/y.md"])).toEqual(["x.md", "docs/y.md"]);
+  });
+
+  test("never strips the basename itself", () => {
+    expect(tabLabels(["docs/x.md", "docs/x.md"])).toEqual(["x.md", "x.md"]);
+  });
+
+  test("passes single or empty lists through", () => {
+    expect(tabLabels(["docs/a/x.md"])).toEqual(["docs/a/x.md"]);
+    expect(tabLabels([])).toEqual([]);
+  });
+});
diff --git a/tools/mdp/src/tabs.ts b/tools/mdp/src/tabs.ts
new file mode 100644
index 0000000..1a78810
--- /dev/null
+++ b/tools/mdp/src/tabs.ts
@@ -0,0 +1,17 @@
+/**
+ * タブ表示用ラベル: 全ファイルに共通するディレクトリ接頭辞を落とした残り。
+ * basename は必ず残す。1 件以下ならそのまま。
+ */
+export function tabLabels(names: string[]): string[] {
+  if (names.length < 2) return [...names];
+  const split = names.map((n) => n.split("/"));
+  const maxCommon = Math.min(...split.map((p) => p.length - 1));
+  let common = 0;
+  while (
+    common < maxCommon &&
+    split.every((p) => p[common] === split[0][common])
+  ) {
+    common++;
+  }
+  return split.map((p) => p.slice(common).join("/"));
+}
diff --git a/tools/mdp/src/template.test.ts b/tools/mdp/src/template.test.ts
new file mode 100644
index 0000000..9513b1f
--- /dev/null
+++ b/tools/mdp/src/template.test.ts
@@ -0,0 +1,189 @@
+import { describe, expect, test } from "bun:test";
+import { buildPage } from "./template.ts";
+
+describe("buildPage", () => {
+  test("wraps the fragment in a markdown-body article", () => {
+    const html = buildPage("<h1>Hi</h1>", [], ".markdown-body{color:black}");
+    expect(html).toContain('<article class="markdown-body">');
+    expect(html).toContain("<h1>Hi</h1>");
+    expect(html).toContain("</article>");
+  });
+
+  test("includes the base css", () => {
+    const html = buildPage("x", [], ".markdown-body{color:black}");
+    expect(html).toContain(".markdown-body{color:black}");
+  });
+
+  test("injects custom css after the base css so it wins", () => {
+    const html = buildPage("x", ["h1 { color: red }"], "BASE_CSS");
+    expect(html).toContain("h1 { color: red }");
+    expect(html.indexOf("BASE_CSS")).toBeLessThan(
+      html.indexOf("h1 { color: red }"),
+    );
+  });
+
+  test("injects multiple custom css blocks in order", () => {
+    const html = buildPage("x", ["A_CSS", "B_CSS"], "BASE_CSS");
+    expect(html.indexOf("A_CSS")).toBeLessThan(html.indexOf("B_CSS"));
+  });
+
+  test("produces a full html document", () => {
+    const html = buildPage("x", [], "");
+    expect(html).toStartWith("<!doctype html>");
+    expect(html).toContain("<html");
+    expect(html).toContain("</html>");
+  });
+
+  test("defaults to light, overridable from storage", () => {
+    const html = buildPage("x", [], "");
+    expect(html).toContain("mdp-theme");
+    expect(html).toContain("'light'");
+    expect(html).not.toContain("prefers-color-scheme");
+  });
+
+  test("renders a header with theme and font-size buttons", () => {
+    const html = buildPage("x", [], "");
+    expect(html).toContain('id="mdp-theme-btn"');
+    expect(html).toContain('id="mdp-font-btn"');
+  });
+
+  test("embeds the scoped dark stylesheet when provided", () => {
+    const html = buildPage("x", [], "", { darkCss: "DARK_BLOCK_CSS" });
+    expect(html).toContain("DARK_BLOCK_CSS");
+  });
+
+  test("renders the left sidebar when sidebar html is provided", () => {
+    const html = buildPage("x", [], "", { sidebar: "SIDEBAR_HTML" });
+    expect(html).toContain("mdp-sidebar");
+    expect(html).toContain("SIDEBAR_HTML");
+    expect(html.indexOf("SIDEBAR_HTML")).toBeLessThan(
+      html.indexOf('class="markdown-body"'),
+    );
+  });
+
+  test("omits the sidebar when not given", () => {
+    const html = buildPage("x", [], "");
+    expect(html).not.toContain("<nav");
+  });
+
+  test("puts the title in the header", () => {
+    const html = buildPage("x", [], "", { title: "design.md" });
+    expect(html).toContain("design.md");
+  });
+
+  test("omits the mermaid script by default", () => {
+    const html = buildPage("x", [], "");
+    expect(html).not.toContain("mermaid.run");
+    expect(html).not.toContain("cdn.jsdelivr.net/npm/mermaid");
+  });
+
+  test("includes the mermaid script when requested", () => {
+    const html = buildPage("x", [], "", { mermaid: true });
+    expect(html).toContain("cdn.jsdelivr.net/npm/mermaid");
+    expect(html).toContain("mermaid.run");
+  });
+});
+
+describe("comments", () => {
+  test("embeds the comments JSON and the inserter script when given", () => {
+    const page = buildPage("<p>hi</p>", [], "", {
+      comments: '[{"anchorText":"hi"}]',
+    });
+    expect(page).toContain(
+      '<script type="application/json" id="mdp-comments">[{"anchorText":"hi"}]</script>',
+    );
+    expect(page).toContain("mdp-thread");
+  });
+
+  test("omits the comments block when not given", () => {
+    const page = buildPage("<p>hi</p>", [], "");
+    expect(page).not.toContain('id="mdp-comments"');
+  });
+});
+
+describe("pr link", () => {
+  test("renders a github icon link in the header when prUrl is given", () => {
+    const page = buildPage("x", [], "", {
+      prUrl: "https://github.com/o/r/pull/1",
+    });
+    expect(page).toContain("mdp-pr-link");
+    expect(page).toContain('href="https://github.com/o/r/pull/1"');
+  });
+
+  test("omits the link when prUrl is not given", () => {
+    expect(buildPage("x", [], "")).not.toContain("mdp-pr-link");
+  });
+});
+
+describe("gutter", () => {
+  test("renders the comments gutter for comments, postDoc or prComments", () => {
+    expect(buildPage("x", [], "", { comments: "[]" })).toContain(
+      'id="mdp-gutter"',
+    );
+    expect(buildPage("x", [], "", { postDoc: "a.md" })).toContain(
+      'id="mdp-gutter"',
+    );
+    expect(buildPage("x", [], "", { prComments: "[]" })).toContain(
+      'id="mdp-gutter"',
+    );
+  });
+
+  test("embeds PR conversation comments and the inserter script", () => {
+    const page = buildPage("x", [], "", { prComments: '[{"nodeId":"IC_1"}]' });
+    expect(page).toContain(
+      '<script type="application/json" id="mdp-pr-comments">[{"nodeId":"IC_1"}]</script>',
+    );
+    expect(page).toContain("行に紐づかないコメント");
+  });
+
+  test("omits the PR comments block when not given", () => {
+    expect(buildPage("x", [], "")).not.toContain('id="mdp-pr-comments"');
+  });
+
+  test("puts the gutter after the article and omits it otherwise", () => {
+    const html = buildPage("x", [], "", { comments: "[]" });
+    expect(html.indexOf('class="markdown-body"')).toBeLessThan(
+      html.indexOf('id="mdp-gutter"'),
+    );
+    expect(buildPage("x", [], "")).not.toContain('id="mdp-gutter"');
+  });
+});
+
+describe("post ui", () => {
+  test("embeds the selection script with the doc path when postDoc is set", () => {
+    const page = buildPage("<p>hi</p>", [], "", { postDoc: "docs/a.md" });
+    expect(page).toContain('data-mdp-doc="docs/a.md"');
+    expect(page).toContain("mdp-post-btn");
+    expect(page).toContain("/api/comment");
+  });
+
+  test("puts the post script before the comments script so replies can see it", () => {
+    const page = buildPage("<p>hi</p>", [], "", {
+      comments: "[]",
+      postDoc: "a.md",
+    });
+    expect(page.indexOf("data-mdp-doc")).toBeLessThan(
+      page.indexOf('id="mdp-comments"'),
+    );
+  });
+
+  test("embeds the viewer identity for the post ui", () => {
+    const page = buildPage("<p>hi</p>", [], "", {
+      postDoc: "a.md",
+      postUser: { login: "yuma", avatarUrl: "http://av" },
+    });
+    expect(page).toContain('data-mdp-user="yuma"');
+    expect(page).toContain('data-mdp-avatar="http://av"');
+  });
+
+  test("escapes the doc path attribute", () => {
+    const page = buildPage("<p>hi</p>", [], "", { postDoc: 'a"b.md' });
+    expect(page).toContain('data-mdp-doc="a&quot;b.md"');
+  });
+
+  test("omits the post ui when postDoc is not set", () => {
+    const page = buildPage("<p>hi</p>", [], "");
+    expect(page).not.toContain("data-mdp-doc");
+    expect(page).not.toContain("/api/comment");
+  });
+});
diff --git a/tools/mdp/src/template.ts b/tools/mdp/src/template.ts
new file mode 100644
index 0000000..e40509b
--- /dev/null
+++ b/tools/mdp/src/template.ts
@@ -0,0 +1,852 @@
+export type PageOptions = {
+  mermaid?: boolean;
+  darkCss?: string;
+  /** 左サイドバーの中身(ファイル一覧 + アクティブファイル直下のアウトライン)。 */
+  sidebar?: string;
+  title?: string;
+  /** Embed-ready JSON of the document's review threads (see toEmbeddedJson). */
+  comments?: string;
+  /** Embed-ready JSON of the PR's conversation (line-less) comments. */
+  prComments?: string;
+  /** Doc path to post selection comments for; enables the posting UI. */
+  postDoc?: string;
+  /** 投稿フォームに表示する自分の GitHub アカウント。 */
+  postUser?: { login: string; avatarUrl: string };
+  /** header に GitHub アイコンで置く PR へのリンク。 */
+  prUrl?: string;
+};
+
+/** Layout, header, toc and dark/light chrome — independent of the markdown theme. */
+const LAYOUT_CSS = `
+* { box-sizing: border-box; }
+html { scroll-behavior: smooth; }
+body { margin: 0; background: #fff; color: #1f2328; }
+[data-theme="light"] { color-scheme: light; }
+[data-theme="dark"] { color-scheme: dark; }
+[data-theme="dark"] body { background: #0d1117; color: #e6edf3; }
+
+.mdp-header {
+  position: sticky; top: 0; z-index: 10;
+  display: flex; align-items: center; gap: 12px;
+  height: 48px; padding: 0 16px;
+  background: inherit; border-bottom: 1px solid #d0d7de;
+  font: 13px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+[data-theme="dark"] .mdp-header { border-color: #30363d; }
+.mdp-title { color: #656d76; margin-right: auto; overflow: hidden;
+  text-overflow: ellipsis; white-space: nowrap; }
+.mdp-controls { display: flex; gap: 6px; }
+.mdp-controls button,
+.mdp-controls a {
+  height: 32px; min-width: 32px; padding: 0 8px;
+  display: inline-flex; align-items: center; justify-content: center;
+  border: 1px solid #d0d7de; border-radius: 6px;
+  background: transparent; color: inherit; cursor: pointer; font-size: 13px;
+  text-decoration: none;
+}
+.mdp-controls button:hover,
+.mdp-controls a:hover { background: rgba(0,0,0,0.05); }
+[data-theme="dark"] .mdp-controls button,
+[data-theme="dark"] .mdp-controls a { border-color: #30363d; }
+[data-theme="dark"] .mdp-controls button:hover,
+[data-theme="dark"] .mdp-controls a:hover { background: rgba(255,255,255,0.06); }
+
+.mdp-layout { display: flex; align-items: flex-start; }
+.mdp-side {
+  position: sticky; top: 48px; align-self: flex-start;
+  max-height: calc(100vh - 48px); overflow: auto;
+  padding: 16px 12px;
+  font: 13px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+.mdp-sidebar { flex: 0 0 280px; }
+.mdp-side-head { font-size: 13px; color: #5f6368; padding: 4px 14px 10px; }
+[data-theme="dark"] .mdp-side-head { color: #9aa0a6; }
+.mdp-file { margin: 2px 0; }
+.mdp-file-name {
+  display: flex; align-items: center; gap: 10px;
+  width: 100%; padding: 8px 14px; border: 0; border-radius: 999px;
+  background: transparent; color: #444746; font: inherit; font-size: 14px;
+  text-align: left; text-decoration: none; cursor: pointer;
+}
+.mdp-file-name:hover { background: rgba(0,0,0,0.05); }
+.mdp-file.active > .mdp-file-name { background: #d3e3fd; color: #0b57d0; font-weight: 600; }
+.mdp-file-icon { flex: none; }
+.mdp-file-label {
+  flex: 1 1 auto; min-width: 0;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.mdp-file-badge {
+  flex: none; min-width: 24px; height: 24px; padding: 0 6px;
+  border-radius: 999px; background: #fff; color: #444746;
+  font-size: 12px; font-weight: 500; line-height: 24px; text-align: center;
+}
+.mdp-file:not(.active) .mdp-file-badge { background: #f1f3f4; }
+.mdp-file.active.collapsed .mdp-toc-list { display: none; }
+.mdp-file .mdp-toc-list { margin: 6px 0 14px 24px; border-left: 2px solid #c4c7c5; }
+[data-theme="dark"] .mdp-file-name { color: #bdc1c6; }
+[data-theme="dark"] .mdp-file-name:hover { background: rgba(255,255,255,0.06); }
+[data-theme="dark"] .mdp-file.active > .mdp-file-name { background: #0842a0; color: #d3e3fd; }
+[data-theme="dark"] .mdp-file-badge { background: #202124; color: #bdc1c6; }
+[data-theme="dark"] .mdp-file:not(.active) .mdp-file-badge { background: #3c4043; }
+[data-theme="dark"] .mdp-file .mdp-toc-list { border-color: #5f6368; }
+
+.mdp-gutter {
+  flex: 0 0 320px; position: relative; min-width: 0;
+  padding: 16px 16px 48px 8px;
+  font: 13px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+.mdp-card { position: absolute; left: 8px; right: 16px; transition: top 0.15s ease; }
+.mdp-card .mdp-thread { margin: 0; }
+.mdp-card.mdp-thread { margin: 0; }
+.mdp-anchor-hover { background: rgba(255,212,0,0.12); }
+[data-theme="dark"] .mdp-anchor-hover { background: rgba(187,128,9,0.18); }
+.mdp-gutter-divider {
+  position: absolute; left: 8px; right: 16px;
+  color: #8c959f; font-size: 11px; text-transform: uppercase;
+  letter-spacing: 0.04em; border-bottom: 1px solid #d0d7de; padding-bottom: 4px;
+}
+[data-theme="dark"] .mdp-gutter-divider { border-color: #30363d; }
+.mdp-toc-list { list-style: none; margin: 0; padding: 0; }
+.mdp-toc-list li { margin: 0; }
+.mdp-toc-list a {
+  position: relative; display: block; padding: 7px 8px 7px 18px;
+  color: #444746; font-size: 13.5px; text-decoration: none;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.mdp-toc-list a:hover { color: #1f1f1f; }
+[data-theme="dark"] .mdp-toc-list a { color: #bdc1c6; }
+[data-theme="dark"] .mdp-toc-list a:hover { color: #e8eaed; }
+.mdp-toc-list a.active { color: #0b57d0; font-weight: 600; }
+.mdp-toc-list a.active::before {
+  content: ""; position: absolute; left: -2px; top: 6px; bottom: 6px;
+  width: 3px; border-radius: 2px; background: #0b57d0;
+}
+[data-theme="dark"] .mdp-toc-list a.active { color: #8ab4f8; }
+[data-theme="dark"] .mdp-toc-list a.active::before { background: #8ab4f8; }
+.mdp-toc-lvl1 { padding-left: 0; }
+.mdp-toc-lvl2 { padding-left: 12px; }
+.mdp-toc-lvl3 { padding-left: 24px; }
+.mdp-toc-lvl4 { padding-left: 36px; }
+.mdp-toc-lvl5 { padding-left: 48px; }
+.mdp-toc-lvl6 { padding-left: 60px; }
+
+.markdown-body {
+  flex: 1 1 auto; min-width: 0;
+  max-width: 900px; margin: 0 auto; padding: 32px 45px;
+}
+.markdown-body :is(h1,h2,h3,h4,h5,h6) { scroll-margin-top: 64px; }
+@keyframes mdp-target-flash {
+  0% { background: rgba(255, 212, 0, 0.45); }
+  100% { background: transparent; }
+}
+.markdown-body :is(h1,h2,h3,h4,h5,h6):target {
+  animation: mdp-target-flash 1.6s ease-out;
+}
+.markdown-body pre.mermaid {
+  background: transparent; border: 0; padding: 8px 0;
+  line-height: normal; text-align: center;
+}
+
+[data-font="s"] .markdown-body { font-size: 14px; }
+[data-font="m"] .markdown-body { font-size: 16px; }
+[data-font="l"] .markdown-body { font-size: 18.5px; }
+
+.mdp-thread {
+  margin: 12px 0 20px; border: 0; border-radius: 12px;
+  overflow: hidden; background: #f8f9fa;
+  font: 13px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  transition: background 0.15s ease;
+}
+[data-theme="dark"] .mdp-thread { background: #292a2d; }
+.mdp-replyable { cursor: pointer; }
+.mdp-replyable:hover { background: #f1f3f4; }
+[data-theme="dark"] .mdp-replyable:hover { background: #313235; }
+.mdp-focused, .mdp-replyable.mdp-focused:hover { background: #fff; }
+.mdp-focused {
+  box-shadow: 0 1px 3px rgba(0,0,0,0.2), 0 6px 16px rgba(0,0,0,0.12);
+}
+[data-theme="dark"] .mdp-focused,
+[data-theme="dark"] .mdp-replyable.mdp-focused:hover {
+  background: #1e1f20; box-shadow: 0 1px 3px rgba(0,0,0,0.5);
+}
+.mdp-reply { padding: 4px 16px 14px; cursor: auto; }
+.mdp-reactions {
+  position: relative; display: flex; flex-wrap: wrap; gap: 4px;
+  align-items: center; margin-top: 8px;
+}
+.mdp-react-pill {
+  border: 1px solid #d0d7de; border-radius: 999px; background: transparent;
+  padding: 1px 8px; font-size: 12px; line-height: 18px;
+  color: inherit; cursor: pointer;
+}
+.mdp-react-pill.mine {
+  border-color: #0b57d0; background: rgba(11,87,208,0.08); color: #0b57d0;
+}
+[data-theme="dark"] .mdp-react-pill { border-color: #3c4043; }
+[data-theme="dark"] .mdp-react-pill.mine {
+  border-color: #8ab4f8; background: rgba(138,180,248,0.12); color: #8ab4f8;
+}
+.mdp-react-add {
+  border: 0; background: transparent; cursor: pointer; color: #5f6368;
+  height: 22px; padding: 0 6px; border-radius: 999px; font-size: 12px;
+}
+.mdp-react-add:hover { background: rgba(0,0,0,0.06); }
+[data-theme="dark"] .mdp-react-add { color: #9aa0a6; }
+[data-theme="dark"] .mdp-react-add:hover { background: rgba(255,255,255,0.08); }
+.mdp-react-picker {
+  position: absolute; bottom: calc(100% + 4px); left: 0; z-index: 5;
+  display: flex; gap: 2px; padding: 4px 6px;
+  background: #fff; border: 1px solid #e0e0e0; border-radius: 999px;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+}
+[data-theme="dark"] .mdp-react-picker { background: #2d2e30; border-color: #3c4043; }
+.mdp-react-picker button {
+  border: 0; background: transparent; font-size: 16px; cursor: pointer;
+  border-radius: 50%; width: 28px; height: 28px; padding: 0;
+}
+.mdp-react-picker button:hover { background: rgba(0,0,0,0.08); }
+[data-theme="dark"] .mdp-react-picker button:hover { background: rgba(255,255,255,0.1); }
+.mdp-resolve-btn {
+  margin-left: auto; flex: none; width: 32px; height: 32px;
+  display: flex; align-items: center; justify-content: center;
+  border: 0; border-radius: 50%; background: transparent;
+  color: #0b57d0; cursor: pointer;
+}
+.mdp-resolve-btn:hover { background: rgba(11,87,208,0.08); }
+.mdp-resolve-btn:disabled { color: #9aa0a6; cursor: default; }
+[data-theme="dark"] .mdp-resolve-btn { color: #8ab4f8; }
+[data-theme="dark"] .mdp-resolve-btn:hover { background: rgba(138,180,248,0.12); }
+.mdp-avatar {
+  width: 20px; height: 20px; border-radius: 50%; flex: none;
+  vertical-align: text-bottom; background: #d0d7de;
+}
+.mdp-thread-head {
+  display: flex; align-items: center; gap: 8px; width: 100%;
+  padding: 6px 12px; border: 0; background: transparent; color: #656d76;
+  font: inherit; cursor: pointer; text-align: left;
+}
+[data-theme="dark"] .mdp-thread-head { color: #9198a1; }
+.mdp-badge {
+  display: inline-block; padding: 0 7px; border: 1px solid #d0d7de;
+  border-radius: 999px; font-size: 11px; line-height: 18px; color: #656d76;
+}
+.mdp-badge-resolved { border-color: #8250df; color: #8250df; }
+[data-theme="dark"] .mdp-badge { border-color: #30363d; color: #9198a1; }
+[data-theme="dark"] .mdp-badge-resolved { border-color: #ab7df8; color: #ab7df8; }
+.mdp-comment { padding: 14px 16px; background: transparent; }
+.mdp-comment + .mdp-comment,
+.mdp-thread-head + .mdp-thread-comments .mdp-comment { border-top: 1px solid #e8eaed; }
+[data-theme="dark"] .mdp-comment + .mdp-comment,
+[data-theme="dark"] .mdp-thread-head + .mdp-thread-comments .mdp-comment { border-color: #3c4043; }
+.mdp-comment-head { display: flex; align-items: center; gap: 10px; margin-bottom: 8px; }
+.mdp-comment-head .mdp-avatar { width: 36px; height: 36px; }
+.mdp-comment-head strong { font-size: 14px; font-weight: 700; color: #1f1f1f; }
+[data-theme="dark"] .mdp-comment-head strong { color: #e8eaed; }
+.mdp-comment-meta {
+  display: flex; flex-direction: column; min-width: 0; line-height: 1.35;
+}
+.mdp-comment-time { font-size: 12px; color: #5f6368; text-decoration: none; }
+.mdp-comment-time:hover { text-decoration: underline; }
+[data-theme="dark"] .mdp-comment-time { color: #9aa0a6; }
+.mdp-comment-body { font-size: 13px; color: #1f1f1f; }
+[data-theme="dark"] .mdp-comment-body { color: #e8eaed; }
+.mdp-comment-body > :first-child { margin-top: 0; }
+.mdp-comment-body > :last-child { margin-bottom: 0; }
+#mdp-post-btn {
+  position: absolute; z-index: 20; width: 40px; height: 40px;
+  display: flex; align-items: center; justify-content: center;
+  border: 0; border-radius: 999px; background: #fff; color: #444746;
+  cursor: pointer;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.3), 0 2px 8px rgba(0,0,0,0.15);
+}
+#mdp-post-btn:hover { background: #f1f3f4; }
+[data-theme="dark"] #mdp-post-btn { background: #2d2e30; color: #e8eaed; }
+[data-theme="dark"] #mdp-post-btn:hover { background: #3c4043; }
+.mdp-post-form {
+  background: #fff; border: 1px solid #e0e0e0; border-radius: 12px;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.15), 0 4px 8px rgba(0,0,0,0.08);
+  padding: 12px 14px;
+}
+[data-theme="dark"] .mdp-post-form { background: #1e1f20; border-color: #3c4043; }
+.mdp-post-head {
+  display: flex; align-items: center; gap: 8px;
+  margin-bottom: 10px; font-size: 14px;
+}
+.mdp-post-head .mdp-avatar { width: 28px; height: 28px; }
+.mdp-post-text {
+  width: 100%; resize: none; padding: 8px 12px;
+  border: 1px solid #747775; border-radius: 16px;
+  background: transparent; color: inherit; font: inherit;
+  outline: none;
+}
+.mdp-post-text:focus { border-color: #0b57d0; box-shadow: inset 0 0 0 1px #0b57d0; }
+[data-theme="dark"] .mdp-post-text { border-color: #5f6368; }
+[data-theme="dark"] .mdp-post-text:focus { border-color: #8ab4f8; box-shadow: inset 0 0 0 1px #8ab4f8; }
+.mdp-post-err { margin-top: 6px; color: #d1242f; }
+[data-theme="dark"] .mdp-post-err { color: #f85149; }
+.mdp-post-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 10px; }
+.mdp-post-actions button {
+  padding: 6px 16px; border-radius: 999px; border: 0;
+  cursor: pointer; font: inherit; font-weight: 500;
+}
+.mdp-post-cancel { background: transparent; color: #0b57d0; }
+.mdp-post-cancel:hover { background: rgba(11,87,208,0.08); }
+.mdp-post-submit { background: #0b57d0; color: #fff; }
+.mdp-post-submit:disabled { background: #e9e9e9; color: #9aa0a6; cursor: default; }
+[data-theme="dark"] .mdp-post-cancel { color: #8ab4f8; }
+[data-theme="dark"] .mdp-post-cancel:hover { background: rgba(138,180,248,0.12); }
+[data-theme="dark"] .mdp-post-submit { background: #8ab4f8; color: #202124; }
+[data-theme="dark"] .mdp-post-submit:disabled { background: #3c4043; color: #7e8388; }
+::highlight(mdp-range) { background: rgba(255, 212, 0, 0.35); }
+[data-theme="dark"] ::highlight(mdp-range) { background: rgba(187, 128, 9, 0.4); }
+::highlight(mdp-composing) { background: rgba(246, 168, 35, 0.55); }
+[data-theme="dark"] ::highlight(mdp-composing) { background: rgba(246, 168, 35, 0.4); }
+
+@media (max-width: 1100px) { .mdp-sidebar { display: none; } }
+@media (max-width: 1000px) { .mdp-gutter, #mdp-post-btn { display: none; } }
+`;
+
+/** Set theme/font before first paint (light by default, overridden by saved choice). */
+const PREPAINT_JS = `(function(){var r=document.documentElement;
+var t=null;try{t=localStorage.getItem('mdp-theme');}catch(e){}
+r.dataset.theme=t||'light';
+var f=null;try{f=localStorage.getItem('mdp-font');}catch(e){}
+r.dataset.font=f||'m';})();`;
+
+/** Wire the header buttons and the toc scroll-spy. */
+const CONTROLS_JS = `(function(){var r=document.documentElement;
+var tb=document.getElementById('mdp-theme-btn');
+if(tb)tb.addEventListener('click',function(){var t=r.dataset.theme==='dark'?'light':'dark';
+r.dataset.theme=t;try{localStorage.setItem('mdp-theme',t);}catch(e){}
+window.dispatchEvent(new Event('mdp-theme-change'));});
+var sizes=['s','m','l'];
+var fb=document.getElementById('mdp-font-btn');
+if(fb)fb.addEventListener('click',function(){var n=sizes[(sizes.indexOf(r.dataset.font)+1)%3]||'m';
+r.dataset.font=n;try{localStorage.setItem('mdp-font',n);}catch(e){}});
+var ft=document.getElementById('mdp-file-toggle');
+if(ft)ft.addEventListener('click',function(){ft.parentElement.classList.toggle('collapsed');});
+var links=[].slice.call(document.querySelectorAll('.mdp-toc-list a'));
+if(links.length){var map={};links.forEach(function(a){map[a.getAttribute('href').slice(1)]=a;});
+links.forEach(function(a){a.addEventListener('click',function(){
+links.forEach(function(x){x.classList.remove('active');});
+a.classList.add('active');});});
+var obs=new IntersectionObserver(function(es){es.forEach(function(e){if(e.isIntersecting){
+links.forEach(function(a){a.classList.remove('active');});
+var a=map[e.target.id];if(a){a.classList.add('active');a.scrollIntoView({block:'nearest'});}}});},
+{rootMargin:'-48px 0px -70% 0px'});
+document.querySelectorAll('.markdown-body h1,.markdown-body h2,.markdown-body h3,.markdown-body h4,.markdown-body h5,.markdown-body h6').forEach(function(h){if(h.id)obs.observe(h);});}})();`;
+
+/** Margin-gutter card manager: anchor-aligned absolute placement, shared by
+    COMMENTS_JS and POST_JS via window.mdpGutter. */
+const GUTTER_JS = `(function(){
+var gutter=document.getElementById('mdp-gutter');if(!gutter)return;
+var cards=[];
+var divider=document.createElement('div');
+divider.className='mdp-gutter-divider';divider.textContent='行に紐づかないコメント';
+divider.hidden=true;gutter.appendChild(divider);
+function yOf(el){return el.getBoundingClientRect().top+window.scrollY;}
+function layout(){
+var base=yOf(gutter);
+var anchored=[],loose=[];
+cards.forEach(function(c){
+(c.anchor&&document.contains(c.anchor)?anchored:loose).push(c);});
+anchored.sort(function(a,b){return yOf(a.anchor)-yOf(b.anchor);});
+var bottom=16;
+// 行に紐づかないコメントは欄の一番上にまとめる。
+if(loose.length){
+divider.hidden=false;divider.style.top=bottom+'px';
+bottom+=divider.offsetHeight+10;
+loose.forEach(function(c){c.el.style.top=bottom+'px';bottom+=c.el.offsetHeight+8;});
+bottom+=16;}
+else{divider.hidden=true;}
+anchored.forEach(function(c){
+var top=Math.max(yOf(c.anchor)-base,bottom);
+c.el.style.top=top+'px';
+bottom=top+c.el.offsetHeight+8;});
+gutter.style.minHeight=(bottom+24)+'px';}
+function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');}
+var focusedCard=null;
+function unfocusCard(){
+if(!focusedCard)return;
+focusedCard.classList.remove('mdp-focused');
+var box=focusedCard.querySelector('.mdp-reply');
+if(box&&!box.querySelector('textarea').value)box.remove();
+focusedCard=null;layout();}
+document.addEventListener('mousedown',function(e){
+if(focusedCard&&!focusedCard.contains(e.target))unfocusCard();
+[].forEach.call(document.querySelectorAll('.mdp-react-picker'),function(p){
+if(!p.hidden&&!p.parentElement.contains(e.target))p.hidden=true;});},true);
+var EMOJI={THUMBS_UP:'\\ud83d\\udc4d',THUMBS_DOWN:'\\ud83d\\udc4e',LAUGH:'\\ud83d\\ude04',
+HOORAY:'\\ud83c\\udf89',CONFUSED:'\\ud83d\\ude15',HEART:'\\u2764\\ufe0f',
+ROCKET:'\\ud83d\\ude80',EYES:'\\ud83d\\udc40'};
+function reactionBar(subjectId,groups){
+var bar=document.createElement('div');bar.className='mdp-reactions';
+var state={};
+(groups||[]).forEach(function(g){
+if(g.count>0)state[g.content]={count:g.count,mine:!!g.viewerReacted};});
+var addBtn=document.createElement('button');
+addBtn.type='button';addBtn.className='mdp-react-add';addBtn.title='リアクション';
+addBtn.textContent='\\ud83d\\ude42+';
+var picker=document.createElement('div');
+picker.className='mdp-react-picker';picker.hidden=true;
+Object.keys(EMOJI).forEach(function(c){
+var b=document.createElement('button');b.type='button';b.textContent=EMOJI[c];
+b.addEventListener('click',function(){picker.hidden=true;toggle(c);});
+picker.appendChild(b);});
+addBtn.addEventListener('click',function(){picker.hidden=!picker.hidden;layout();});
+function render(){
+[].forEach.call(bar.querySelectorAll('.mdp-react-pill'),function(p){p.remove();});
+Object.keys(state).forEach(function(c){
+if(state[c].count<=0)return;
+var p=document.createElement('button');
+p.type='button';p.className='mdp-react-pill'+(state[c].mine?' mine':'');
+p.textContent=EMOJI[c]+' '+state[c].count;
+p.addEventListener('click',function(){toggle(c);});
+bar.insertBefore(p,addBtn);});
+layout();}
+function toggle(c){
+var cur=state[c]||{count:0,mine:false};
+var on=!cur.mine;
+state[c]={count:cur.count+(on?1:-1),mine:on};
+render();
+fetch('/api/react',{method:'POST',headers:{'Content-Type':'application/json'},
+body:JSON.stringify({subjectId:subjectId,content:c,on:on})})
+.then(function(res){if(!res.ok)throw new Error('react failed');})
+.catch(function(){state[c]=cur;render();});}
+bar.appendChild(addBtn);bar.appendChild(picker);
+render();
+return bar;}
+function attachReply(card,threadId){
+var ps=document.querySelector('script[data-mdp-doc]');
+if(!ps||!threadId)return;
+var user=ps.dataset.mdpUser||'you',avatarUrl=ps.dataset.mdpAvatar||'';
+card.classList.add('mdp-replyable');
+card.addEventListener('click',function(e){
+if(e.target.closest('a,button'))return;
+focusCard();});
+function focusCard(){
+if(focusedCard===card)return;
+unfocusCard();
+focusedCard=card;
+card.classList.add('mdp-focused');
+if(!card.querySelector('.mdp-reply'))card.appendChild(buildBox());
+layout();}
+function buildBox(){
+var box=document.createElement('div');
+box.className='mdp-reply';
+box.innerHTML='<textarea class="mdp-post-text" rows="1" placeholder="返信"></textarea>'
++'<div class="mdp-post-err" hidden></div>'
++'<div class="mdp-post-actions" hidden>'
++'<button type="button" class="mdp-post-cancel">キャンセル</button>'
++'<button type="button" class="mdp-post-submit" disabled>返信</button></div>';
+var ta=box.querySelector('textarea'),sb=box.querySelector('.mdp-post-submit');
+var actions=box.querySelector('.mdp-post-actions');
+function reset(){
+ta.value='';ta.style.height='auto';sb.disabled=true;actions.hidden=true;layout();}
+function submit(){
+var text=ta.value.trim();if(!text)return;
+sb.disabled=true;sb.textContent='\\u2026';
+var err=box.querySelector('.mdp-post-err');err.hidden=true;
+fetch('/api/reply',{method:'POST',headers:{'Content-Type':'application/json'},
+body:JSON.stringify({threadId:threadId,body:text})})
+.then(function(res){return res.json().then(function(j){return{ok:res.ok,j:j};});})
+.then(function(r){
+if(!r.ok)throw new Error(r.j&&r.j.error||'reply failed');
+var c=document.createElement('div');
+c.className='mdp-comment';
+c.innerHTML='<div class="mdp-comment-head">'
++(avatarUrl?'<img class="mdp-avatar" src="'+esc(avatarUrl)+'" alt="">':'')
++'<div class="mdp-comment-meta"><strong>'+esc(user)+'</strong>'
++'<a class="mdp-comment-time" href="'+esc(r.j.url)+'" target="_blank" rel="noopener">just now</a></div>'
++'</div><div class="mdp-comment-body">'+esc(text)+'</div>';
+var list=card.querySelector('.mdp-thread-comments');
+if(list)list.appendChild(c);else card.insertBefore(c,box);
+if(r.j.subjectId)c.appendChild(reactionBar(r.j.subjectId,[]));
+sb.textContent='返信';reset();})
+.catch(function(e){
+var err=box.querySelector('.mdp-post-err');
+err.textContent=String(e&&e.message||e);err.hidden=false;
+sb.disabled=false;sb.textContent='返信';});}
+ta.addEventListener('focus',function(){actions.hidden=false;layout();});
+ta.addEventListener('input',function(){
+sb.disabled=!ta.value.trim();
+ta.style.height='auto';ta.style.height=ta.scrollHeight+'px';
+layout();});
+ta.addEventListener('keydown',function(e){
+if(e.key==='Escape')unfocusCard();
+if(e.key==='Enter'&&(e.metaKey||e.ctrlKey))submit();});
+box.querySelector('.mdp-post-cancel').addEventListener('click',function(){
+ta.value='';unfocusCard();});
+sb.addEventListener('click',submit);
+return box;}}
+window.mdpGutter={
+attachReply:attachReply,
+reactionBar:reactionBar,
+add:function(el,anchor){
+el.classList.add('mdp-card');
+gutter.appendChild(el);
+cards.push({el:el,anchor:anchor||null});
+if(anchor){
+el.addEventListener('mouseenter',function(){anchor.classList.add('mdp-anchor-hover');});
+el.addEventListener('mouseleave',function(){anchor.classList.remove('mdp-anchor-hover');});
+el.addEventListener('click',function(e){
+if(e.target.closest('a,button,textarea'))return;
+anchor.scrollIntoView({block:'center',behavior:'smooth'});});}
+layout();
+return el;},
+remove:function(el){
+cards=cards.filter(function(c){return c.el!==el;});
+el.remove();layout();},
+layout:layout};
+var t;function relayout(){clearTimeout(t);t=setTimeout(layout,60);}
+window.addEventListener('resize',relayout);
+window.addEventListener('load',relayout);
+window.addEventListener('mdp-theme-change',function(){setTimeout(layout,150);});
+setTimeout(layout,300);setTimeout(layout,1500);
+})();`;
+
+/** Parse the embedded thread JSON, text-match anchors, and add gutter cards. */
+const COMMENTS_JS = `(function(){
+function readJson(id){
+var el=document.getElementById(id);if(!el)return [];
+try{return JSON.parse(el.textContent)||[];}catch(e){return [];}}
+var threads=readJson('mdp-comments'),prComments=readJson('mdp-pr-comments');
+if(!threads.length&&!prComments.length)return;
+var body=document.querySelector('.markdown-body');if(!body)return;
+function norm(s){return s.replace(/\\s+/g,' ').trim();}
+function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');}
+function rel(iso){var t=Date.parse(iso);if(isNaN(t))return iso;
+var s=(Date.now()-t)/1000;
+if(s<3600)return Math.max(1,Math.round(s/60))+'m ago';
+if(s<86400)return Math.round(s/3600)+'h ago';
+if(s<2592000)return Math.round(s/86400)+'d ago';
+return iso.slice(0,10);}
+function avatar(c){
+return c.avatarUrl?'<img class="mdp-avatar" src="'+esc(c.avatarUrl)+'" alt="">':'';}
+var canPost=!!document.querySelector('script[data-mdp-doc]');
+var CHECK='<svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true">'
++'<path fill="currentColor" d="M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/></svg>';
+function wireResolve(div,t){
+var rb=div.querySelector('.mdp-resolve-btn');if(!rb)return;
+rb.addEventListener('click',function(){
+rb.disabled=true;
+fetch('/api/resolve',{method:'POST',headers:{'Content-Type':'application/json'},
+body:JSON.stringify({threadId:t.threadNodeId})})
+.then(function(res){return res.json().then(function(j){return{ok:res.ok,j:j};});})
+.then(function(r){
+if(!r.ok)throw new Error(r.j&&r.j.error||'resolve failed');
+div.classList.remove('mdp-replyable','mdp-focused');
+var reply=div.querySelector('.mdp-reply');if(reply)reply.remove();
+var comments=div.querySelector('.mdp-thread-comments');
+comments.hidden=true;
+var head=document.createElement('button');
+head.type='button';head.className='mdp-thread-head';
+head.innerHTML='<span class="mdp-badge mdp-badge-resolved">Resolved</span>';
+head.addEventListener('click',function(){comments.hidden=!comments.hidden;
+if(window.mdpGutter)window.mdpGutter.layout();});
+div.insertBefore(head,div.firstChild);
+rb.remove();
+if(window.mdpGutter)window.mdpGutter.layout();})
+.catch(function(e){
+rb.disabled=false;
+var err=document.createElement('div');
+err.className='mdp-post-err';
+err.textContent=String(e&&e.message||e);
+rb.closest('.mdp-comment').appendChild(err);
+setTimeout(function(){err.remove();if(window.mdpGutter)window.mdpGutter.layout();},4000);
+if(window.mdpGutter)window.mdpGutter.layout();});});}
+function build(t){
+var div=document.createElement('div');
+div.className='mdp-thread'+(t.isResolved?' mdp-thread-resolved':'');
+var html='';
+if(t.isResolved){
+var c0=t.comments.length?t.comments[0]:null;
+html+='<button type="button" class="mdp-thread-head">'
++'<span class="mdp-badge mdp-badge-resolved">Resolved</span>'
++(t.isOutdated?'<span class="mdp-badge">Outdated</span>':'')
++(c0?avatar(c0)+'<strong>'+esc(c0.author)+'</strong>':'')+'</button>';}
+html+='<div class="mdp-thread-comments"'+(t.isResolved?' hidden':'')+'>';
+t.comments.forEach(function(c,i){
+html+='<div class="mdp-comment"><div class="mdp-comment-head">'+avatar(c)
++'<div class="mdp-comment-meta"><strong>'+esc(c.author)+'</strong>'
++'<a class="mdp-comment-time" href="'+esc(c.url)+'" target="_blank" rel="noopener">'+esc(rel(c.createdAt))+'</a></div>'
++(!t.isResolved&&t.isOutdated&&i===0?'<span class="mdp-badge">Outdated</span>':'')
++(i===0&&!t.isResolved&&t.threadNodeId&&canPost?'<button type="button" class="mdp-resolve-btn" title="解決">'+CHECK+'</button>':'')
++'</div><div class="mdp-comment-body">'+c.bodyHtml+'</div></div>';});
+html+='</div>';
+div.innerHTML=html;
+var head=div.querySelector('.mdp-thread-head');
+if(head)head.addEventListener('click',function(){
+var c=div.querySelector('.mdp-thread-comments');c.hidden=!c.hidden;
+if(window.mdpGutter)window.mdpGutter.layout();});
+return div;}
+var blocks=[].slice.call(body.querySelectorAll('p,li,h1,h2,h3,h4,h5,h6,pre,blockquote,tr'));
+var texts=blocks.map(function(b){return norm(b.textContent);});
+function findRange(block,needle){
+if(!needle)return null;
+var walker=document.createTreeWalker(block,NodeFilter.SHOW_TEXT);
+var map=[],normed='',lastSpace=true,n;
+while(n=walker.nextNode()){var s=n.nodeValue;
+for(var i=0;i<s.length;i++){
+if(/\\s/.test(s[i])){if(!lastSpace){normed+=' ';map.push({n:n,o:i});lastSpace=true;}}
+else{normed+=s[i];map.push({n:n,o:i});lastSpace=false;}}}
+var idx=normed.indexOf(needle);if(idx<0)return null;
+var st=map[idx],en=map[idx+needle.length-1];
+var r=document.createRange();r.setStart(st.n,st.o);r.setEnd(en.n,en.o+1);return r;}
+function addHighlight(r){
+if(!window.Highlight||!CSS.highlights||!r)return;
+var h=CSS.highlights.get('mdp-range')||new Highlight();
+h.add(r);CSS.highlights.set('mdp-range',h);}
+function anchorFor(t){
+if(!t.anchorText)return null;
+for(var i=0;i<blocks.length;i++){if(texts[i].indexOf(t.anchorText)!==-1)return blocks[i];}
+return null;}
+if(!window.mdpGutter)return;
+// 行に紐づかない PR 会話コメント: アンカーなしカードとして欄の一番上に入る。
+prComments.forEach(function(c){
+var div=document.createElement('div');
+div.className='mdp-thread';
+div.innerHTML='<div class="mdp-comment"><div class="mdp-comment-head">'+avatar(c)
++'<div class="mdp-comment-meta"><strong>'+esc(c.author)+'</strong>'
++'<a class="mdp-comment-time" href="'+esc(c.url)+'" target="_blank" rel="noopener">'
++esc(rel(c.createdAt))+'</a></div>'
++'<span class="mdp-badge">PR</span>'
++'</div><div class="mdp-comment-body">'+c.bodyHtml+'</div></div>';
+if(canPost&&c.nodeId)div.querySelector('.mdp-comment')
+.appendChild(window.mdpGutter.reactionBar(c.nodeId,c.reactions));
+window.mdpGutter.add(div,null);});
+threads.forEach(function(t){
+var target=anchorFor(t);
+if(target&&t.rangeText)addHighlight(findRange(target,norm(t.rangeText)));
+var card=build(t);
+wireResolve(card,t);
+if(canPost)[].forEach.call(card.querySelectorAll('.mdp-comment'),function(el,i){
+var c=t.comments[i];
+if(c&&c.nodeId)el.appendChild(window.mdpGutter.reactionBar(c.nodeId,c.reactions));});
+if(t.replyTo)window.mdpGutter.attachReply(card,t.replyTo);
+window.mdpGutter.add(card,target);});
+})();`;
+
+/** Selection popup + comment form; posts to /api/comment and highlights the range. */
+const POST_JS = `(function(){
+var DOC=document.currentScript.dataset.mdpDoc;
+var USER=document.currentScript.dataset.mdpUser||'you';
+var AVATAR=document.currentScript.dataset.mdpAvatar||'';
+var body=document.querySelector('.markdown-body');if(!body||!DOC)return;
+function norm(s){return s.replace(/\\s+/g,' ').trim();}
+function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');}
+var BLOCK='p,li,h1,h2,h3,h4,h5,h6,pre,blockquote,tr';
+function blockOf(node){
+var el=node.nodeType===1?node:node.parentElement;
+if(!el)return null;
+if(el.closest('.mdp-gutter,.mdp-thread,.mdp-post-form'))return null;
+var b=el.closest(BLOCK);
+return b&&body.contains(b)?b:null;}
+function highlight(range){
+if(!window.Highlight||!CSS.highlights||!range)return;
+var h=CSS.highlights.get('mdp-range')||new Highlight();
+h.add(range);CSS.highlights.set('mdp-range',h);}
+function setComposing(range){
+if(!window.Highlight||!CSS.highlights||!range)return;
+CSS.highlights.set('mdp-composing',new Highlight(range));}
+function clearComposing(){
+if(CSS.highlights)CSS.highlights.delete('mdp-composing');}
+function avatarImg(){
+return AVATAR?'<img class="mdp-avatar" src="'+esc(AVATAR)+'" alt="">':'';}
+var btn=document.createElement('button');
+btn.type='button';btn.id='mdp-post-btn';btn.title='コメントを追加';btn.hidden=true;
+btn.innerHTML='<svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true">'
++'<path fill="currentColor" d="M22 4c0-1.1-.9-2-2-2H4c-1.1 0-2 .9-2 2v12c0 1.1.9 2 2 2h14l4 4V4zm-5 7h-4v4h-2v-4H7V9h4V5h2v4h4v2z"/></svg>';
+document.body.appendChild(btn);
+var pending=null;
+document.addEventListener('mouseup',function(e){
+if(e.target===btn||btn.contains(e.target))return;
+if(e.target.closest&&e.target.closest('.mdp-post-form'))return;
+setTimeout(function(){
+var sel=window.getSelection();
+if(!sel||sel.isCollapsed||!sel.rangeCount){btn.hidden=true;return;}
+var r=sel.getRangeAt(0);
+var b1=blockOf(r.startContainer),b2=blockOf(r.endContainer);
+var text=norm(sel.toString());
+if(!b1||b1!==b2||!text){btn.hidden=true;return;}
+pending={block:b1,text:text,blockText:norm(b1.textContent),range:r.cloneRange()};
+var rect=r.getBoundingClientRect();
+btn.style.left=(rect.left+window.scrollX)+'px';
+btn.style.top=(rect.bottom+window.scrollY+6)+'px';
+btn.hidden=false;},0);});
+function removeForm(form){
+clearComposing();
+if(window.mdpGutter)window.mdpGutter.remove(form);else form.remove();}
+document.addEventListener('mousedown',function(e){
+if(e.target!==btn&&!btn.contains(e.target))btn.hidden=true;
+var form=document.querySelector('.mdp-post-form');
+if(form&&!form.contains(e.target)&&!form.querySelector('.mdp-post-text').value)removeForm(form);
+},true);
+btn.addEventListener('click',function(){
+if(!pending||!window.mdpGutter)return;
+btn.hidden=true;
+var p=pending;pending=null;
+var old=document.querySelector('.mdp-post-form');if(old)removeForm(old);
+var form=document.createElement('div');
+form.className='mdp-post-form';
+form.innerHTML='<div class="mdp-post-head">'+avatarImg()
++'<strong>'+esc(USER)+'</strong></div>'
++'<textarea class="mdp-post-text" rows="1" placeholder="コメントを追加"></textarea>'
++'<div class="mdp-post-err" hidden></div>'
++'<div class="mdp-post-actions">'
++'<button type="button" class="mdp-post-cancel">キャンセル</button>'
++'<button type="button" class="mdp-post-submit" disabled>コメント</button>'
++'</div>';
+setComposing(p.range);
+window.mdpGutter.add(form,p.block);
+var ta=form.querySelector('.mdp-post-text');ta.focus({preventScroll:true});
+var sb0=form.querySelector('.mdp-post-submit');
+ta.addEventListener('input',function(){
+sb0.disabled=!ta.value.trim();
+ta.style.height='auto';ta.style.height=ta.scrollHeight+'px';
+window.mdpGutter.layout();});
+function submit(){
+var text=ta.value.trim();if(!text)return;
+var sb=form.querySelector('.mdp-post-submit');sb.disabled=true;sb.textContent='\\u2026';
+var err=form.querySelector('.mdp-post-err');err.hidden=true;
+fetch('/api/comment',{method:'POST',headers:{'Content-Type':'application/json'},
+body:JSON.stringify({doc:DOC,selectedText:p.text,blockText:p.blockText,body:text})})
+.then(function(res){return res.json().then(function(j){return{ok:res.ok,j:j};});})
+.then(function(r){
+if(!r.ok)throw new Error(r.j&&r.j.error||'post failed');
+clearComposing();
+highlight(p.range);
+form.classList.remove('mdp-post-form');
+form.classList.add('mdp-thread');
+form.innerHTML='<div class="mdp-comment"><div class="mdp-comment-head">'+avatarImg()
++'<div class="mdp-comment-meta"><strong>'+esc(USER)+'</strong>'
++'<a class="mdp-comment-time" href="'+esc(r.j.url)+'" target="_blank" rel="noopener">just now</a></div>'
++(r.j.kind==='issue'?'<span class="mdp-badge">PR comment</span>':'')
++'</div><div class="mdp-comment-body">'+esc(text)+'</div></div>';
+if(r.j.replyTo)window.mdpGutter.attachReply(form,r.j.replyTo);
+if(r.j.subjectId)form.querySelector('.mdp-comment')
+.appendChild(window.mdpGutter.reactionBar(r.j.subjectId,[]));
+window.mdpGutter.layout();})
+.catch(function(e){
+err.textContent=String(e&&e.message||e);err.hidden=false;
+sb.disabled=false;sb.textContent='Comment';});}
+form.querySelector('.mdp-post-cancel').addEventListener('click',function(){removeForm(form);});
+form.querySelector('.mdp-post-submit').addEventListener('click',submit);
+ta.addEventListener('keydown',function(e){
+if(e.key==='Escape')removeForm(form);
+if(e.key==='Enter'&&(e.metaKey||e.ctrlKey))submit();});
+});
+})();`;
+
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Assemble a full HTML page from a rendered markdown fragment.
+ *
+ * `baseCss` (light github-markdown-css) goes first; `opts.darkCss` (already
+ * scoped under [data-theme="dark"]) and the layout chrome follow; each entry of
+ * `customCss` (the theme) is appended last so its rules win.
+ */
+export function buildPage(
+  fragment: string,
+  customCss: string[],
+  baseCss: string,
+  opts: PageOptions = {},
+): string {
+  const custom = customCss
+    .map((css) => `<style>\n${css}\n</style>`)
+    .join("\n");
+  const dark = opts.darkCss ? `<style>\n${opts.darkCss}\n</style>` : "";
+  const title = opts.title ?? "mdp";
+  const sidebar = opts.sidebar
+    ? `<nav class="mdp-side mdp-sidebar"><div class="mdp-side-head">ドキュメント タブ</div>${opts.sidebar}</nav>`
+    : "";
+  const gutter =
+    opts.comments || opts.postDoc || opts.prComments
+      ? `<aside class="mdp-gutter" id="mdp-gutter"></aside>`
+      : "";
+  const mermaidScript = opts.mermaid
+    ? `<script type="module">
+import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+var nodes=[].slice.call(document.querySelectorAll("pre.mermaid"));
+nodes.forEach(function(n){n.dataset.src=n.textContent;});
+function render(){
+  mermaid.initialize({startOnLoad:false,securityLevel:"loose",
+    theme:document.documentElement.dataset.theme==="dark"?"dark":"default",
+    flowchart:{curve:"basis",useMaxWidth:true},fontFamily:"inherit"});
+  nodes.forEach(function(n){n.removeAttribute("data-processed");n.innerHTML=n.dataset.src;});
+  mermaid.run({nodes:nodes});
+}
+render();
+window.addEventListener("mdp-theme-change",render);
+</script>`
+    : "";
+  const prCommentsJson = opts.prComments
+    ? `<script type="application/json" id="mdp-pr-comments">${opts.prComments}</script>`
+    : "";
+  const commentsBlock =
+    opts.comments || opts.prComments
+      ? `${
+          opts.comments
+            ? `<script type="application/json" id="mdp-comments">${opts.comments}</script>`
+            : ""
+        }${prCommentsJson}
+<script>${COMMENTS_JS}</script>`
+      : "";
+  const postBlock = opts.postDoc
+    ? `<script data-mdp-doc="${escapeAttr(opts.postDoc)}" data-mdp-user="${escapeAttr(
+        opts.postUser?.login ?? "",
+      )}" data-mdp-avatar="${escapeAttr(opts.postUser?.avatarUrl ?? "")}">${POST_JS}</script>`
+    : "";
+  const gutterScript = gutter ? `<script>${GUTTER_JS}</script>` : "";
+  const prLink = opts.prUrl
+    ? `<a class="mdp-pr-link" href="${escapeAttr(opts.prUrl)}" target="_blank" rel="noopener" title="GitHub で PR を開く">` +
+      `<svg viewBox="0 0 16 16" width="18" height="18" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg></a>`
+    : "";
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>${title}</title>
+<script>${PREPAINT_JS}</script>
+<style>
+${baseCss}
+</style>
+${dark}
+<style>${LAYOUT_CSS}</style>
+${custom}
+</head>
+<body>
+<header class="mdp-header">
+<span class="mdp-title">${title}</span>
+<div class="mdp-controls">
+${prLink}
+<button id="mdp-font-btn" title="Font size">A</button>
+<button id="mdp-theme-btn" title="Light / dark">◐</button>
+</div>
+</header>
+<div class="mdp-layout">
+${sidebar}
+<article class="markdown-body">
+${fragment}
+</article>
+${gutter}
+</div>
+${mermaidScript}
+${gutterScript}
+${postBlock}
+${commentsBlock}
+<script>${CONTROLS_JS}</script>
+</body>
+</html>
+`;
+}
diff --git a/tools/mdp/src/toc.test.ts b/tools/mdp/src/toc.test.ts
new file mode 100644
index 0000000..6bb8f06
--- /dev/null
+++ b/tools/mdp/src/toc.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { buildToc } from "./toc.ts";
+
+describe("buildToc", () => {
+  test("returns empty toc and unchanged fragment when there are no headings", () => {
+    const { fragment, toc } = buildToc("<p>hi</p>");
+    expect(toc).toBe("");
+    expect(fragment).toBe("<p>hi</p>");
+  });
+
+  test("adds sequential ids to headings", () => {
+    const { fragment } = buildToc("<h1>One</h1><h2>Two</h2>");
+    expect(fragment).toContain('<h1 id="mdp-h0">One</h1>');
+    expect(fragment).toContain('<h2 id="mdp-h1">Two</h2>');
+  });
+
+  test("builds a list of links pointing at the heading ids", () => {
+    const { toc } = buildToc("<h1>One</h1><h2>Two</h2>");
+    expect(toc).toContain('<a href="#mdp-h0">One</a>');
+    expect(toc).toContain('<a href="#mdp-h1">Two</a>');
+  });
+
+  test("records the heading level for indentation", () => {
+    const { toc } = buildToc("<h1>One</h1><h3>Deep</h3>");
+    expect(toc).toContain("mdp-toc-lvl1");
+    expect(toc).toContain("mdp-toc-lvl3");
+  });
+
+  test("uses the text content of headings that contain markup", () => {
+    const { toc } = buildToc("<h2>Use <code>bm sync</code> now</h2>");
+    expect(toc).toContain(">Use bm sync now</a>");
+  });
+
+  test("escapes special characters in the toc text", () => {
+    const { toc } = buildToc("<h1>A &amp; B &lt; C</h1>");
+    expect(toc).toContain("A &amp; B &lt; C");
+  });
+
+  test("preserves existing heading attributes when adding an id", () => {
+    const { fragment } = buildToc('<h1 class="x">One</h1>');
+    expect(fragment).toContain('class="x"');
+    expect(fragment).toContain('id="mdp-h0"');
+  });
+});
diff --git a/tools/mdp/src/toc.ts b/tools/mdp/src/toc.ts
new file mode 100644
index 0000000..8bc0811
--- /dev/null
+++ b/tools/mdp/src/toc.ts
@@ -0,0 +1,35 @@
+type TocItem = { level: number; id: string; text: string };
+
+/**
+ * Add stable ids to every heading in the rendered fragment and build a flat,
+ * level-tagged table of contents linking to them. Heading text is taken from
+ * the inner HTML with tags stripped; entities are already escaped by the API,
+ * so the text is reused as-is.
+ */
+export function buildToc(fragment: string): { fragment: string; toc: string } {
+  const items: TocItem[] = [];
+  let i = 0;
+
+  const out = fragment.replace(
+    /<h([1-6])([^>]*)>([\s\S]*?)<\/h\1>/g,
+    (_m, level: string, attrs: string, inner: string) => {
+      const id = `mdp-h${i++}`;
+      items.push({
+        level: Number(level),
+        id,
+        text: inner.replace(/<[^>]+>/g, "").trim(),
+      });
+      return `<h${level}${attrs} id="${id}">${inner}</h${level}>`;
+    },
+  );
+
+  if (items.length === 0) return { fragment: out, toc: "" };
+
+  const lis = items
+    .map(
+      (it) =>
+        `<li class="mdp-toc-lvl${it.level}"><a href="#${it.id}">${it.text}</a></li>`,
+    )
+    .join("\n");
+  return { fragment: out, toc: `<ul class="mdp-toc-list">\n${lis}\n</ul>` };
+}
diff --git a/tools/mdp/themes/designdoc.css b/tools/mdp/themes/designdoc.css
new file mode 100644
index 0000000..2dfe777
--- /dev/null
+++ b/tools/mdp/themes/designdoc.css
@@ -0,0 +1,156 @@
+/* DesignDoc theme — mimics the Google Docs "DesignDoc" look. */
+
+.markdown-body {
+  font-family: "Helvetica Neue", Arial, "Hiragino Sans",
+    "Hiragino Kaku Gothic ProN", "Yu Gothic", Meiryo, sans-serif;
+  color: #222;
+  background: #fff;
+  line-height: 1.3;
+  letter-spacing: 0.02em;
+  font-weight: 400;
+}
+
+/* コードは字間を広げない */
+.markdown-body pre,
+.markdown-body code {
+  letter-spacing: normal;
+}
+
+/* Go easy on bold — lots of **strong** gets tiring at full weight. */
+.markdown-body strong {
+  font-weight: 500;
+}
+
+/* Green headings, no underline, lighter weight — like Google Docs headings. */
+.markdown-body h1,
+.markdown-body h2,
+.markdown-body h3,
+.markdown-body h4,
+.markdown-body h5,
+.markdown-body h6 {
+  color: #38761d;
+  font-weight: 400;
+  border-bottom: none;
+  padding-bottom: 0;
+  margin-top: 1.4em;
+}
+
+/* 見出しの緑は h1 だけ。h2 以下はグレーで控えめに。 */
+.markdown-body h2,
+.markdown-body h3,
+.markdown-body h4,
+.markdown-body h5,
+.markdown-body h6 {
+  color: #5f6368;
+}
+
+.markdown-body h1 {
+  font-size: 1.9em;
+}
+
+/* The very first H1 is the document title — make it large like the Doc title. */
+.markdown-body h1:first-of-type {
+  font-size: 2.2em;
+  margin-top: 0.2em;
+}
+
+.markdown-body h2 {
+  font-size: 1.5em;
+}
+
+/* Helper / template text is wrapped in _italics_; make it small and faint. */
+.markdown-body em {
+  color: #8a8a8a;
+  font-size: 13px; /* smaller than the 16px body */
+  line-height: 1.35; /* tighten the helper-text paragraphs */
+}
+
+/* Bold "※" notes that trail the italic helper text get the same subdued look. */
+.markdown-body p em ~ strong {
+  color: #8a8a8a;
+  font-size: 13px;
+  font-weight: 400;
+}
+
+/* Inline code in the same green as the headings. */
+.markdown-body code {
+  color: #38761d;
+}
+
+/* Code blocks: dark background with GitHub-dark syntax highlighting.
+   Language-tagged blocks come wrapped in .highlight, which the base stylesheet
+   targets more specifically, so override that selector too. */
+.markdown-body pre,
+.markdown-body .highlight pre {
+  background: #22272e;
+  border-radius: 10px;
+  padding: 16px 20px;
+  color: #adbac7;
+}
+.markdown-body pre code {
+  color: #adbac7;
+}
+.markdown-body pre .pl-c {
+  color: #9198a1;
+}
+.markdown-body pre .pl-c1,
+.markdown-body pre .pl-s .pl-v {
+  color: #79c0ff;
+}
+.markdown-body pre .pl-e,
+.markdown-body pre .pl-en {
+  color: #d2a8ff;
+}
+.markdown-body pre .pl-smi,
+.markdown-body pre .pl-s .pl-s1 {
+  color: #f0f6fc;
+}
+.markdown-body pre .pl-ent {
+  color: #7ee787;
+}
+.markdown-body pre .pl-k {
+  color: #ff7b72;
+}
+.markdown-body pre .pl-s,
+.markdown-body pre .pl-pds,
+.markdown-body pre .pl-sr {
+  color: #a5d6ff;
+}
+.markdown-body pre .pl-v,
+.markdown-body pre .pl-smw {
+  color: #ffa657;
+}
+
+/* Dark mode: keep the green accent (brighter), dark canvas, light body text.
+   Code blocks are already dark, so they carry over unchanged. */
+[data-theme="dark"] .markdown-body {
+  background: #0d1117;
+  color: #c9d1d9;
+}
+[data-theme="dark"] .markdown-body h1,
+[data-theme="dark"] .markdown-body h2,
+[data-theme="dark"] .markdown-body h3,
+[data-theme="dark"] .markdown-body h4,
+[data-theme="dark"] .markdown-body h5,
+[data-theme="dark"] .markdown-body h6,
+[data-theme="dark"] .markdown-body code {
+  color: #7ee787;
+}
+[data-theme="dark"] .markdown-body h2,
+[data-theme="dark"] .markdown-body h3,
+[data-theme="dark"] .markdown-body h4,
+[data-theme="dark"] .markdown-body h5,
+[data-theme="dark"] .markdown-body h6 {
+  color: #9198a1;
+}
+[data-theme="dark"] .markdown-body h1,
+[data-theme="dark"] .markdown-body h2 {
+  border-bottom: none;
+}
+[data-theme="dark"] .markdown-body em,
+[data-theme="dark"] .markdown-body p em ~ strong {
+  color: #768390;
+}
+[data-theme="dark"] .markdown-body a {
+  color: #4493f8;
+}
diff --git a/tools/mdp/tsconfig.json b/tools/mdp/tsconfig.json
new file mode 100644
index 0000000..5a88b41
--- /dev/null
+++ b/tools/mdp/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["bun-types"]
+  }
+}

From 4dd6986417974187f9af2df91979379883e01533 Mon Sep 17 00:00:00 2001
From: Yuma Ishikawa <yuma.fuu05@gmail.com>
Date: Wed, 5 Aug 2026 17:21:03 +0900
Subject: [PATCH 2/5] fix(mdp): fall back to the gh cli token for rendering

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 tools/mdp/mdp.ts            |  6 ++++--
 tools/mdp/src/render.ts     |  6 +++++-
 tools/mdp/src/token.test.ts | 40 +++++++++++++++++++++++++++++++++++++
 tools/mdp/src/token.ts      | 21 +++++++++++++++++++
 4 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 tools/mdp/src/token.test.ts
 create mode 100644 tools/mdp/src/token.ts

diff --git a/tools/mdp/mdp.ts b/tools/mdp/mdp.ts
index 8013ee3..b4c2037 100755
--- a/tools/mdp/mdp.ts
+++ b/tools/mdp/mdp.ts
@@ -30,6 +30,7 @@ import type { Base } from "./src/server.ts";
 import { serve } from "./src/server.ts";
 import { tabLabels } from "./src/tabs.ts";
 import { buildPage } from "./src/template.ts";
+import { resolveToken } from "./src/token.ts";
 import { buildToc } from "./src/toc.ts";
 
 const DEFAULT_THEME = "designdoc";
@@ -51,7 +52,8 @@ Options:
   -h, --help      show this help
 
 Environment:
-  GITHUB_TOKEN / GH_TOKEN   raise the GitHub API rate limit
+  GITHUB_TOKEN / GH_TOKEN   token for the rendering API
+                            (falls back to \`gh auth token\`)
 `;
 
 async function loadGitHubCss(): Promise<string> {
@@ -177,7 +179,7 @@ async function main(): Promise<void> {
   const cssBlocks: string[] = [await loadTheme(args.theme ?? DEFAULT_THEME)];
   const githubCss = await loadGitHubCss();
   const darkCss = await loadDarkCss();
-  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  const token = await resolveToken(process.env, runGh);
 
   let threads: ReviewThread[] = [];
   if (prUrl) {
diff --git a/tools/mdp/src/render.ts b/tools/mdp/src/render.ts
index af2af80..e77ed43 100644
--- a/tools/mdp/src/render.ts
+++ b/tools/mdp/src/render.ts
@@ -34,7 +34,11 @@ export async function renderMarkdown(
   if (!res.ok) {
     if (res.status === 403 || res.status === 429) {
       throw new Error(
-        `GitHub API rate limit hit (HTTP ${res.status}). Set GITHUB_TOKEN to raise the limit.`,
+        `GitHub API rate limit hit (HTTP ${res.status}). ${
+          opts.token
+            ? "Wait for the limit to reset."
+            : "Run `gh auth login`, or set GITHUB_TOKEN, to raise the limit."
+        }`,
       );
     }
     throw new Error(`GitHub markdown API failed: HTTP ${res.status}`);
diff --git a/tools/mdp/src/token.test.ts b/tools/mdp/src/token.test.ts
new file mode 100644
index 0000000..07b9b6c
--- /dev/null
+++ b/tools/mdp/src/token.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { resolveToken } from "./token.ts";
+
+describe("resolveToken", () => {
+  const never = async () => {
+    throw new Error("gh should not be called");
+  };
+
+  test("prefers GITHUB_TOKEN, then GH_TOKEN", async () => {
+    expect(
+      await resolveToken({ GITHUB_TOKEN: "a", GH_TOKEN: "b" }, never),
+    ).toBe("a");
+    expect(await resolveToken({ GH_TOKEN: "b" }, never)).toBe("b");
+  });
+
+  test("falls back to the gh cli token", async () => {
+    let seen: string[] = [];
+    const token = await resolveToken({}, async (args) => {
+      seen = args;
+      return "gho_fromgh\n";
+    });
+    expect(seen).toEqual(["auth", "token"]);
+    expect(token).toBe("gho_fromgh");
+  });
+
+  test("ignores blank env values", async () => {
+    expect(
+      await resolveToken({ GITHUB_TOKEN: "", GH_TOKEN: "  " }, async () => "gh_t"),
+    ).toBe("gh_t");
+  });
+
+  test("returns undefined when gh has no token", async () => {
+    expect(await resolveToken({}, async () => "  ")).toBeUndefined();
+    expect(
+      await resolveToken({}, async () => {
+        throw new Error("not logged in");
+      }),
+    ).toBeUndefined();
+  });
+});
diff --git a/tools/mdp/src/token.ts b/tools/mdp/src/token.ts
new file mode 100644
index 0000000..c64c27b
--- /dev/null
+++ b/tools/mdp/src/token.ts
@@ -0,0 +1,21 @@
+import type { RunGh } from "./pr.ts";
+
+/**
+ * レンダリング API 用のトークン。環境変数が無ければ `gh auth token` に頼る
+ * (gh でログイン済みなら 60 req/h の未認証枠を踏まずに済む)。
+ */
+export async function resolveToken(
+  env: Record<string, string | undefined>,
+  runGh: RunGh,
+): Promise<string | undefined> {
+  const fromEnv = [env.GITHUB_TOKEN, env.GH_TOKEN]
+    .map((v) => v?.trim())
+    .find((v) => v);
+  if (fromEnv) return fromEnv;
+  try {
+    const out = (await runGh(["auth", "token"])).trim();
+    return out === "" ? undefined : out;
+  } catch {
+    return undefined;
+  }
+}

From f2d2820e02e9556ae7a6dd855287abfe6453954c Mon Sep 17 00:00:00 2001
From: Yuma Ishikawa <yuma.fuu05@gmail.com>
Date: Thu, 13 Aug 2026 17:47:22 +0900
Subject: [PATCH 3/5] fix(mdp): accept longer and tilde mermaid fences

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 tools/mdp/src/mermaid.test.ts | 13 +++++++++++++
 tools/mdp/src/mermaid.ts      |  4 +++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/tools/mdp/src/mermaid.test.ts b/tools/mdp/src/mermaid.test.ts
index aad4dce..745c0e7 100644
--- a/tools/mdp/src/mermaid.test.ts
+++ b/tools/mdp/src/mermaid.test.ts
@@ -36,6 +36,19 @@ describe("extractMermaid", () => {
     expect(markdown).toBe(md);
   });
 
+  test("extracts fences longer than three backticks", () => {
+    const md = "````mermaid\nflowchart TD\n  a --> b\n````\n";
+    const { markdown, blocks } = extractMermaid(md);
+    expect(blocks).toEqual(["flowchart TD\n  a --> b"]);
+    expect(markdown).not.toContain("mermaid\n");
+  });
+
+  test("extracts tilde fences", () => {
+    const md = "~~~mermaid\nstateDiagram-v2\n  [*] --> A\n~~~\n";
+    const { blocks } = extractMermaid(md);
+    expect(blocks).toEqual(["stateDiagram-v2\n  [*] --> A"]);
+  });
+
   test("extracts an indented fence but requires line-start fences", () => {
     const md = "- item\n\n  ```mermaid\n  graph LR\n  x-->y\n  ```\n";
     const { blocks } = extractMermaid(md);
diff --git a/tools/mdp/src/mermaid.ts b/tools/mdp/src/mermaid.ts
index 7f60c80..0a0c048 100644
--- a/tools/mdp/src/mermaid.ts
+++ b/tools/mdp/src/mermaid.ts
@@ -1,5 +1,7 @@
 // 行頭(+インデント)のフェンスのみ。インラインコード中の ```mermaid 言及は対象外。
-const FENCE = /^[ \t]*```[ \t]*mermaid[^\n]*\n([\s\S]*?)^[ \t]*```[ \t]*$/gm;
+// CommonMark どおり ``` / ~~~ どちらも、3 文字以上の長さを受ける。
+const FENCE =
+  /^[ \t]*(?:`{3,}|~{3,})[ \t]*mermaid[^\n]*\n([\s\S]*?)^[ \t]*(?:`{3,}|~{3,})[ \t]*$/gm;
 
 function escapeHtml(s: string): string {
   return s

From 12de3c9435f2b3bbf077b3dc2e5fb193d46c1c86 Mon Sep 17 00:00:00 2001
From: Yuma Ishikawa <yuma.fuu05@gmail.com>
Date: Thu, 13 Aug 2026 18:14:49 +0900
Subject: [PATCH 4/5] fix(mdp): keep hidden pickers and buttons hidden

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 tools/mdp/src/template.test.ts | 7 +++++++
 tools/mdp/src/template.ts      | 2 ++
 2 files changed, 9 insertions(+)

diff --git a/tools/mdp/src/template.test.ts b/tools/mdp/src/template.test.ts
index 9513b1f..20c55d3 100644
--- a/tools/mdp/src/template.test.ts
+++ b/tools/mdp/src/template.test.ts
@@ -77,6 +77,13 @@ describe("buildPage", () => {
     expect(html).not.toContain("cdn.jsdelivr.net/npm/mermaid");
   });
 
+  test("keeps [hidden] elements hidden despite author display rules", () => {
+    const html = buildPage("x", [], "", { postDoc: "a.md" });
+    // .mdp-react-picker / #mdp-post-btn / .mdp-post-actions all set display,
+    // which would otherwise beat the UA stylesheet's [hidden] rule.
+    expect(html).toContain("[hidden] { display: none !important; }");
+  });
+
   test("includes the mermaid script when requested", () => {
     const html = buildPage("x", [], "", { mermaid: true });
     expect(html).toContain("cdn.jsdelivr.net/npm/mermaid");
diff --git a/tools/mdp/src/template.ts b/tools/mdp/src/template.ts
index e40509b..0062314 100644
--- a/tools/mdp/src/template.ts
+++ b/tools/mdp/src/template.ts
@@ -19,6 +19,8 @@ export type PageOptions = {
 /** Layout, header, toc and dark/light chrome — independent of the markdown theme. */
 const LAYOUT_CSS = `
 * { box-sizing: border-box; }
+/* Our display:flex rules would otherwise beat the UA sheet's [hidden]. */
+[hidden] { display: none !important; }
 html { scroll-behavior: smooth; }
 body { margin: 0; background: #fff; color: #1f2328; }
 [data-theme="light"] { color-scheme: light; }

From 9eb370e37da382c2425f432be21ba0953606a9ef Mon Sep 17 00:00:00 2001
From: Yuma Ishikawa <yuma.fuu05@gmail.com>
Date: Thu, 13 Aug 2026 19:43:22 +0900
Subject: [PATCH 5/5] fix(mdp): stop mangling snake_case when matching source
 lines

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 tools/mdp/src/comments.test.ts | 12 ++++++++++++
 tools/mdp/src/comments.ts      | 16 ++++++++++++++--
 tools/mdp/src/post.test.ts     |  7 +++++++
 3 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/tools/mdp/src/comments.test.ts b/tools/mdp/src/comments.test.ts
index 0de8e5c..2856322 100644
--- a/tools/mdp/src/comments.test.ts
+++ b/tools/mdp/src/comments.test.ts
@@ -73,6 +73,18 @@ describe("stripMarkdownLine", () => {
     );
   });
 
+  test("keeps underscores inside words (snake_case is not emphasis)", () => {
+    expect(stripMarkdownLine("  pull_request:")).toBe("  pull_request:");
+    expect(stripMarkdownLine("auto_dismiss と snake_case_name")).toBe(
+      "auto_dismiss と snake_case_name",
+    );
+  });
+
+  test("still strips underscore emphasis at word boundaries", () => {
+    expect(stripMarkdownLine("use _emphasis_ here")).toBe("use emphasis here");
+    expect(stripMarkdownLine("__bold__ text")).toBe("bold text");
+  });
+
   test("turns table pipes into spaces", () => {
     expect(normalizeText(stripMarkdownLine("| a | b |"))).toBe("a b");
   });
diff --git a/tools/mdp/src/comments.ts b/tools/mdp/src/comments.ts
index 864f9fc..ec8685e 100644
--- a/tools/mdp/src/comments.ts
+++ b/tools/mdp/src/comments.ts
@@ -62,14 +62,26 @@ export function parsePrUrl(
   return m ? { owner: m[1], repo: m[2], number: Number(m[3]) } : null;
 }
 
-/** Strip leading block markers and inline markdown syntax from a source line. */
+const WORD = /[A-Za-z0-9]/;
+
+/**
+ * Strip leading block markers and inline markdown syntax from a source line.
+ * Underscores between word characters are kept: `pull_request` is an
+ * identifier, not emphasis (CommonMark forbids intraword `_` emphasis), and
+ * mangling it would break matching against the rendered text.
+ */
 export function stripMarkdownLine(s: string): string {
   return s
     .replace(/^\s*#{1,6}\s+/, "")
     .replace(/^\s*>\s*/, "")
     .replace(/^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?/, "")
     .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
-    .replace(/(\*\*|__|~~|\*|_|`)/g, "")
+    .replace(/(\*\*|~~|\*|`)/g, "")
+    .replace(/__?/g, (m, offset: number, whole: string) =>
+      WORD.test(whole[offset - 1] ?? "") && WORD.test(whole[offset + m.length] ?? "")
+        ? m
+        : "",
+    )
     .replace(/\|/g, " ");
 }
 
diff --git a/tools/mdp/src/post.test.ts b/tools/mdp/src/post.test.ts
index f8a4916..187776d 100644
--- a/tools/mdp/src/post.test.ts
+++ b/tools/mdp/src/post.test.ts
@@ -81,6 +81,13 @@ describe("findSourceLine", () => {
     expect(findSourceLine(md, "Title", "Title")).toBe(1);
   });
 
+  test("maps a selection inside snake_case code", () => {
+    const yaml = "# T\n\n```yaml\non:\n  pull_request:\n    types: [opened]\n```\n";
+    expect(
+      findSourceLine(yaml, "pull_request", "on: pull_request: types: [opened]"),
+    ).toBe(5);
+  });
+
   test("returns null when nothing matches", () => {
     expect(findSourceLine(md, "nonexistent", "zzz")).toBeNull();
     expect(findSourceLine(md, "", "First paragraph line one")).toBeNull();