@tanishqkancharla/diffmap 0.4.0 → 0.6.1

package/README.md

@@ -76,13 +76,14 @@ import {
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `mermaid`                                      | Beautiful Mermaid                                                                                 |
 | `services`                                     | Animated service diagram you can play or step through                                             |
+| `mermaid diff` or `services diff`              | The same diagram with [added and removed parts marked](#diagram-diffs)                            |
 | `callstack` or `diff` containing `└──` / `├──` | Interactive stack rows, no file header                                                            |
 | `diff` or `diff:path` with a file path         | Pierre patch with Pierre’s file header                                                            |
 | `diff` with no path                            | Pierre patch, no file header                                                                      |
 | `changes` with a commit, range, or empty body  | Files changed card with a Review button; empty means uncommitted changes                          |
 | `start:end:path`                               | Pierre file excerpt with Pierre’s file header                                                     |
 | `html`                                         | Trusted HTML from this file. diffmap does not sanitize it. Only use it for local files you wrote. |
-| other langs                                    | Highlighted code with optional [line highlights and notes](#highlight-lines-and-add-notes)        |
+| other langs                                    | Highlighted code with optional [titles, highlights, and notes](#highlight-lines-and-add-notes)    |
 
 Fences keep whitespace. Use them for mermaid, call stacks, and diffs.
 
@@ -110,6 +111,13 @@ function requestHandler(record: RecordInput) {
 - A symbol that does not appear, overlapping line notes, or a line number
   outside the fence is a parse error. A note line above other code stays code.
 
+Add `[Title]` after the language to show a title above the code, as in
+` ```ts [src/request.ts] {2-3} `. Call stacks and `mermaid` fences take a
+title the same way, as in ` ```mermaid diff [Request flow] `, or
+`::callstack{title="Request flow"}` and `::mermaid{title="Request flow"}` in
+MDC. A `services` fence uses its [start caption](#animated-service-diagrams)
+instead.
+
 Call stacks take the same highlights and notes, counting rows from the first.
 Write their notes with `#`. A symbol note matches the row text you see, not
 hidden references. Inside a linked row, symbol notes show on hover only; the
@@ -146,8 +154,13 @@ startServer
 ::html
 <aside>Note.</aside>
 ::
+
+::details{summary="How it works"}
+Folded content: prose, lists, and any fence above.
+::
 ```
 
+`::details` folds its content under the `summary` label until the reader opens it.
 `.md` and `.mdx` are both markdown. Curly braces in prose are plain text.
 
 ## Link call stacks to source changes
@@ -244,6 +257,8 @@ service API "HTTP server" [[src/api.ts]]
     state attempts = 0
       > Failures since the last success. Five locks the account.
 
+start "Alice logs in"
+  > The API checks her password with Auth, then sets a session cookie.
 step "The browser submits the form"
   Browser -> API: POST /login
 step "The API asks Auth to verify"
@@ -261,16 +276,21 @@ step "The API sets the session cookie"
   another to nest it. Names are unique within the diagram.
 - `state <key> = <value>` declares a value and its initial state. Indent it under
   its service.
+- `start "caption"` at column 0, before the first step, captions the whole
+  diagram, such as `start "Alice logs in"`. It shows above the diagram until
+  the reader steps, and each step's caption replaces it. A `>` line under it
+  gives an overview of the whole process. A `services` fence takes no
+  `[Title]`; the start caption is its title.
 - `step "caption"` starts a step at column 0. The caption is required: a
   sentence that says what happens, shown under the controls. Indented lines
   under it are `From -> To: label` events and `Service.key = value` updates.
-  Every event in a step travels at once, and the updates land when the events
-  arrive.
+  A step's events travel one after another, in the order written, and the
+  updates land when the last one arrives.
 - A `>` line adds text to the line above it. Indent it further than that line;
   consecutive `>` lines join.
   - Under a service or state, it is a description: the name gets a dotted
     underline and the text shows in a tooltip on hover or focus.
-  - Under a step, it explains the step and shows under the caption.
+  - Under `start` or a step, it explains the caption and shows under it.
   - Under an event or update, it is a note for that step. Notes appear in a
     column beside the diagram once the step's events land, each joined by a
     line to its event label or state row.
@@ -284,6 +304,60 @@ connection between each pair of services that talk. A request and its reply
 share that connection. Indentation is significant, so `services` has no MDC form.
 See [the runnable examples](fixtures/services.md).
 
+## Diagram diffs
+
+Add `diff` after `mermaid` or `services` to show a change in one diagram.
+Start every line with `-` for Today only, `+` for Proposed only, or a space
+for both, as in a call stack diff. Indentation starts after that column.
+
+````md
+```mermaid diff
+ flowchart LR
+   Client --> Handler
+-  Handler --> Service
++  Handler --> Validate
++  Validate --> Service
+```
+````
+
+diffmap draws every line once, so both versions share one layout. Nodes,
+edges, sequence participants, and messages that only Today has are red and
+dashed; those only Proposed has are green. A node whose label differs between
+the versions is amber and shows its Proposed label. Each version must also be
+a valid diagram on its own. To relabel a node, declare it on its own line
+(`-  B[Old]`, `+  B[New]`) so its edges are not drawn twice. In a diff,
+`%% ref edge:<index>` counts edges as drawn: within each run of changed lines,
+`+` lines come before `-` lines.
+
+````md
+```services diff
+ service API
+-  service SessionCache
+-    state active = 0
++  service Sessions
+ service Postgres
+-  state sessions = not used
++  state sessions = 0 rows
+
+ start "Sessions move to Postgres"
+-step "API caches the session"
+   API -> SessionCache: create(alice)
+   SessionCache.active = 1
++step "Sessions writes the session"
+   API -> Sessions: create(alice)
+   Sessions -> Postgres: INSERT
+   Postgres.sessions = 1 row
+```
+````
+
+In a `services diff`, lines inside a `-` or `+` service or step take its
+sign. Today replays the unmarked and `-` lines and Proposed the unmarked and
+`+` lines, so each state row shows Today's value struck through beside
+Proposed's when they differ. A `-` and a `+` declaration of the same state key
+give each version its own starting value. Added and removed steps color their
+segment of the progress bar, and their caption starts with **Added** or
+**Removed**. See [the runnable examples](fixtures/diagram-diffs.md).
+
 ## Link Mermaid nodes and edges
 
 Inside a Mermaid fence, add `%% ref node:<id> [[reference]]` to link a node or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanishqkancharla/diffmap",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "description": "Serve a spec or code walkthrough as a local page",
   "license": "MIT",
   "author": "Tanishq Kancharla",

package/src/annotations.ts

@@ -26,10 +26,26 @@ export type SourceReference = FileReference | ChangesReference;
 export type SourceAnnotation = {
   text: string;
   references: SourceReference[];
+  /** Source panel title while selected, such as a call stack row without its tree. */
+  title?: string;
 };
 
 export function parseCallStack(source: string): SourceAnnotation[] {
-  return source.split("\n").map(parseAnnotation);
+  return source.split("\n").map((line) => {
+    const annotation = parseAnnotation(line);
+    return {
+      ...annotation,
+      title: callStackRow(annotation.text).description.trim(),
+    };
+  });
+}
+
+/** A call stack row's change mark, tree prefix, and the call it describes. */
+export function callStackRow(text: string) {
+  const sign = text.startsWith("+") ? "+" : text.startsWith("-") ? "-" : " ";
+  const label = text.replace(/^[+ -]/, "");
+  const tree = /^[ \t│┃├└─]*/u.exec(label)![0];
+  return { sign, tree, description: label.slice(tree.length) };
 }
 
 export function parseAnnotation(line: string): SourceAnnotation {

package/src/extractDocument.ts

@@ -12,9 +12,17 @@ export function extractTitle(source: string) {
 export function extractFences(source: string) {
   const fences: Fence[] = [];
   for (const match of source.matchAll(fencePattern)) {
-    const lang = match[1] ?? "";
+    const lang = (match[1] ?? "").trim();
     const body = match[2] ?? "";
-    fences.push(parseFence(lang.trim(), body));
+    // A diagram's info string can add `diff`, and Mermaid a [Title].
+    const diagram = /^(mermaid|services)\b\s*(diff)?\s*(?:\[([^\]]*)\])?$/.exec(
+      lang,
+    );
+    fences.push(
+      diagram === null
+        ? parseFence(lang, body)
+        : parseFence(diagram[1]!, body, [], diagram[3], diagram[2]),
+    );
   }
   return fences;
 }

package/src/host/home.md

@@ -1,125 +1,109 @@
 # diffmap
 
-diffmap turns a Markdown file into a page like this one. Your coding agent writes it to show you a change, before and after building it: diagrams you can play, call stacks of what changes, and links that open the code.
+**Your coding agent writes more code than you can review.**
 
-Install the skill, then ask your agent to write a diffmap for a change you are planning or for a branch it just built:
+**You should be spending time reviewing design decisions and risky changes, not boilerplate.**
+
+`diffmap` is an agent skill that lets your agent visually explain their changes to you. Agents can create interactive diagrams that link back to the source code.
+
+You can try `diffmap` before you install it. In a repository that has changes, paste this prompt into your agent:
+
+```text
+Write a diffmap spec for the changes on this branch. Use the instructions at
+https://raw.githubusercontent.com/tanishqkancharla/diffmap/main/skills/generate-diffmap/SKILL.md
+Then serve the spec with npx @tanishqkancharla/diffmap and send me the link.
+```
+
+If you like the result, install the skill:
 
 ```sh
 npx skills add tanishqkancharla/diffmap --skill generate-diffmap
 ```
 
-The agent keeps the spec in `specs/<name>.md`, serves it on your machine, and can share it as a link like this page.
+`diffmap` is [open source](https://github.com/tanishqkancharla/diffmap) and MIT licensed. Diffmaps are hosted locally by default, but you can choose to [upload a diffmap as a secret gist](#share-a-spec-with-a-link) and open it on diffmap.dev.
 
-Everything below is an example spec: diffmap's own features, one per phase. Each phase uses the feature it describes. Click a call stack row, a diagram node, or anything marked ↗ to open its code.
+## See the main ideas
 
-## Show a change, not a wall of text
+Your agent selects the best diagram for each idea. Each part of the diagram has a link to its code.
 
-A coding agent explains a change in a long message. You read it, then open each file it names to check that the code says the same thing.
+### Service diagrams
 
-A diffmap puts the explanation next to the code. Each phase says what changes for you, then shows the change as call stacks and diagrams whose parts open the code they name.
+A service diagram shows each service and its state. Each step shows one event and the state that the event changes. Thus, you do not have to remember the state.
 
-### ✅ Phase 1: Call stacks that open the code
+A service diagram can also show a change. Red parts exist only today, and green parts are new. As you step, each value shows today's state crossed out next to the new state.
 
-**Today**
+This change moves login sessions from memory to a database. Press **Play** to step through it:
 
-The agent describes the call path in a paragraph. You search for each function it names and guess how they connect.
+```services diff
+ service Browser "login page"
+   state cookie = none
+ service API "HTTP server"
+-  service Cache "in-memory sessions"
+-    state sessions = 0
++  service Sessions
+ service Postgres
+-  state sessions = not used
++  state sessions = 0 rows
 
-**Proposed**
+ start "Sessions move from memory to Postgres"
+   > Alice logs in, and the API stores her session. Today it keeps the session in memory, so a server restart signs her out. After the change, Sessions writes it to Postgres, where it survives a restart.
 
-The agent draws the path as data flowing through calls: each row reads `result = call(inputs)`, `+` rows are new, `−` rows go away, and each row opens its code. This is how diffmap draws the tree below:
-
-```callstack
- fence = parseFence(lang, source) [[src/parseFence.ts#parseFence]]
-+└── lines = parseCallStack(source) # one row per line, with its links [[src/annotations.ts#parseCallStack]]
- view = Fence({ fence }) [[src/viewer/Fence.tsx#Fence]]
--└── return CodeBlock(fence.source) # the tree as plain text
-+├── if fence.kind === "callstack":
-+│   └── return CallStackDiff(fence.lines) # rows with + and − marks [[src/viewer/CallStackDiff.tsx#CallStackDiff]]
-+└── return CodeBlock(fence.source) # other languages stay pseudocode
+ step "Alice logs in"
+   Browser -> API: POST /login
+-step "The API keeps the session in memory"
+   API -> Cache: create(alice)
+   Cache.sessions = 1
+     > The server loses this when it restarts.
++step "Sessions writes the session to Postgres"
+   API -> Sessions: create(alice)
+   Sessions -> Postgres: INSERT s_81f
+   Postgres.sessions = 1 row
+     > The row survives a restart.
+ step "The API sets the session cookie"
+   API -> Browser: 200 Set-Cookie
+   Browser.cookie = sid=s_81f
 ```
 
-### ✅ Phase 2: Diagrams you can click
-
-**Today**
+### Mermaid diagrams
 
-The agent draws a flow in ASCII boxes. The boxes do not link to anything, and they break when a label gets long.
+The page shows Mermaid diagrams. Each node and each arrow can have a link to its code. A diagram can show a change in one picture: green parts are new, and red parts are removed.
 
-**Proposed**
+This diagram shows what occurs when you click a link, and what changed when diffmap.dev began to read code from GitHub:
 
-Mermaid diagrams render in the page, and each node or arrow can open its code. Here is what happens when you click a reference:
-
-```mermaid
-flowchart LR
-  Click[Click a reference] --> Find[useSourceReference]
-  Find -->|diffmap serve| Local[Read the repo with git]
-  Find -->|diffmap.dev| GitHub[fetchPinnedBlob]
-  Local --> Panel[SourceDiffPanel]
-  GitHub --> Panel
-  %% ref node:Find [[src/viewer/sourceNavigation.ts#useSourceReference]]
-  %% ref node:GitHub [[src/github/fetchRepo.ts#fetchPinnedBlob]]
-  %% ref node:Panel [[src/viewer/SourceDiffPanel.tsx#SourceDiffPanel]]
-  %% ref edge:1 [[src/viewer/sourceNavigation.ts#requestSource]]
+```mermaid diff [diffmap.dev reads linked code from GitHub]
+ flowchart LR
+   Click[Click a link] --> Find[useSourceReference]
+   Find -->|diffmap serve| Local[Read the repo with git]
++  Find -->|diffmap.dev| GitHub[fetchPinnedBlob]
+   Local --> Panel[SourceDiffPanel]
++  GitHub --> Panel
+   %% ref node:Find [[src/viewer/sourceNavigation.ts#useSourceReference]]
+   %% ref node:GitHub [[src/github/fetchRepo.ts#fetchPinnedBlob]]
+   %% ref node:Panel [[src/viewer/SourceDiffPanel.tsx#SourceDiffPanel]]
+   %% ref edge:1 [[src/viewer/sourceNavigation.ts#requestSource]]
 ```
 
-### ✅ Phase 3: Services you can play
-
-**Today**
-
-A sequence diagram shows the messages between services, but not what each message changes. You keep the state of every service in your head.
-
-**Proposed**
-
-A service diagram shows each service with its state, then steps through the events. Press **Play** to watch `diffmap serve` open a spec, or hover a dotted name to read what it is:
-
-```services
-service Laptop
-  > Your machine. serve reads files here and uploads nothing.
-  service Agent "coding agent"
-    > Writes the spec and runs diffmap for you.
-  service CLI "diffmap serve" [[src/serve.ts#startServer]]
-    > A small server that reads your repo with git.
-    state url = none
-  service Repo "your repo"
-    > Holds the spec and the commits it links to.
-service Browser
-  service Page "the spec" [[src/viewer/ViewerApp.tsx#ViewerApp]]
-    state page = empty
-  service Panel "Diff panel" [[src/viewer/SourceDiffPanel.tsx#SourceDiffPanel]]
-    > Opens beside the spec and shows the code a reference names.
-    state shows = none
-
-step "The agent serves the spec"
-  Agent -> CLI: serve specs/search.md
-step "serve checks every commit the spec links to"
-  CLI -> Repo: readDocumentChanges [[src/git.ts#readDocumentChanges]]
-    > A wrong SHA or line range fails here, so you never meet a broken link.
-step "serve prints a URL for you"
-  CLI -> Agent: localhost URL
-  CLI.url = localhost:4321
-step "You open the page"
-  Page -> CLI: GET /
-  CLI -> Page: spec
-  Page.page = rendered
-step "You click a call stack row"
-  Panel -> CLI: /__diffmap/source
-  CLI -> Repo: git show
-    > Reads the file at the commit the row names, not the working tree.
-step "The Diff panel shows the code"
-  CLI -> Panel: lines
-  Panel.shows = code
-```
+### Call stacks
 
-### ✅ Phase 4: Open code from prose
+Each row has the form `result = call(inputs)`. Thus, you can follow the data from one call to the next call. A `+` row is new code, and a `−` row is old code that the change removes. Each row has a link to its code.
 
-**Today**
+This call stack shows how `diffmap` draws call stacks:
 
-A paragraph names a function as plain code, like `shareMarkdownFile`. You search the repo to find it.
+```callstack
+ fence = parseFence(lang, source) [[src/parseFence.ts#parseFence]]
++└── lines = parseCallStack(source) # one row per line, with its links [[src/annotations.ts#parseCallStack]]
+ view = Fence({ fence }) [[src/viewer/Fence.tsx#Fence]]
+-└── return CodeBlock(fence.source) # the tree as plain text
++├── if fence.kind === "callstack":
++│   └── return CallStackDiff(fence.lines) # rows with + and − marks [[src/viewer/CallStackDiff.tsx#CallStackDiff]]
++└── return CodeBlock(fence.source) # other languages stay pseudocode
+```
 
-**Proposed**
+## Open the code
 
-A function named in a paragraph opens its code too: [[src/share.ts#shareMarkdownFile]].
+A function name in a sentence can also be a link, for example [[src/share.ts#shareMarkdownFile]].
 
-This phase is done, so it ends the way a finished phase does: with a card for the commit that built it, and references pinned to that commit. Pinned links show the code as the commit left it, even after the file moves on.
+When the work is complete, the spec shows a card for the commit. The links in the spec then refer to that commit. These links always show the code from that commit, also when the file changes later.
 
 ```changes
 6e4b5d3
@@ -136,22 +120,22 @@ This phase is done, so it ends the way a finished phase does: with a card for th
 +    └── return InlineReference(node.annotation) # a code button that opens the Diff panel [[6e4b5d3:src/viewer/ComarkView.tsx#L173-L189]]
 ```
 
-### ✅ Phase 5: Share a spec as a link
-
-**Today**
-
-To read a spec, a teammate needs diffmap and a checkout of your repo.
+## Share a spec with a link
 
-**Proposed**
-
-One command uploads the spec as a secret GitHub gist and prints a link anyone can open:
+A teammate can read your spec without a copy of your branch. One command uploads the spec as a secret GitHub gist and prints the link:
 
 ```sh
 npx @tanishqkancharla/diffmap share specs/search.md
 # prints https://diffmap.dev/g/<gistId>
 ```
 
-The page that opens has no git and no checkout, so the gist carries what the spec reads: a snapshot of each commit it links, and the current contents of each file it quotes. That is why this page can show code at all:
+::details{summary="How sharing works"}
+The shared page cannot use git or a copy of your repository. Thus, the gist also contains the data that the spec uses:
+
+- A snapshot of each commit that the spec refers to
+- The current contents of each file that the spec quotes.
+
+Because of this data, this page can show code:
 
 ```mermaid
 flowchart LR
@@ -172,7 +156,7 @@ flowchart LR
 2f96051
 ```
 
-`share` builds both snapshots before it calls `gh`, so diffmap never stores a GitHub token:
+`share` makes the two snapshots before it calls `gh`. Thus, `diffmap` does not keep a GitHub token:
 
 ```callstack
  result = shareMarkdownFile({ filePath, workspaceRoot }) [[2f96051:src/share.ts#L26-L103]]
@@ -186,7 +170,7 @@ flowchart LR
  └── return { gistId, viewerUrl: gistViewerUrl(gistId) }
 ```
 
-This excerpt is one of the quoted files, so a shared copy of this page shows it too:
+This excerpt is from one of the quoted files. Thus, a shared copy of this page also shows it:
 
 ```54:63:src/share.ts
   // It has no files either, so excerpts and references without a commit read these.
@@ -200,3 +184,5 @@ This excerpt is one of the quoted files, so a shared copy of this page shows it
   if (input.isPublic) args.push("--public");
   args.push("--desc", extractTitle(source), filePath);
 ```
+
+::

package/src/host/home.test.ts

@@ -37,6 +37,17 @@ test("homepage markdown is a real viewer document", async () => {
   const mermaid = fences.find((fence) => fence.kind === "mermaid");
   assert.notEqual(mermaid, undefined);
   if (mermaid?.kind !== "mermaid") return;
+  // The homepage shows diagram diffs, not only call stack diffs.
+  assert.notEqual(mermaid.sides, undefined);
+  assert.equal(
+    fences.some(
+      (fence) =>
+        fence.kind === "services" &&
+        fence.parsed.ok &&
+        fence.parsed.diagram.diff,
+    ),
+    true,
+  );
   assert.equal(
     mermaid.annotations.some((link) =>
       link.annotation.references.some((ref) => ref.kind === "file"),
@@ -62,7 +73,6 @@ test("homepage markdown is a real viewer document", async () => {
   const levels = new Set(document.headings.map((heading) => heading.level));
   assert.equal(levels.has(1), true);
   assert.equal(levels.has(2), true);
-  assert.equal(levels.has(3), true);
   assert.ok(
     document.references.filter((ref) => ref.rev !== undefined).length >= 3,
   );

package/src/parseFence.ts

@@ -8,8 +8,21 @@ import {
 import { parseServiceDiagram, type ServicesParse } from "./services.js";
 
 export type Fence =
-  | { kind: "mermaid"; source: string; annotations: DiagramAnnotation[] }
-  | { kind: "services"; source: string; parsed: ServicesParse }
+  | {
+      kind: "mermaid";
+      /** In a diff, every line with its sign removed; see mermaidFence. */
+      source: string;
+      annotations: DiagramAnnotation[];
+      /** From ```mermaid diff: the diagram without `+` lines, and without `-` lines. */
+      sides: { today: string; proposed: string } | undefined;
+      /** From the info string, as in ```mermaid [Request flow]. */
+      title: string | undefined;
+    }
+  | {
+      kind: "services";
+      source: string;
+      parsed: ServicesParse;
+    }
   | { kind: "html"; source: string }
   | {
       kind: "callstack";
@@ -19,6 +32,8 @@ export type Fence =
       /** 1-based rows from the info string, as in ```callstack {2}. */
       highlights: number[];
       notes: CodeNote[];
+      /** From the info string, as in ```callstack [Request flow]. */
+      title: string | undefined;
     }
   | {
       kind: "changes";
@@ -37,6 +52,8 @@ export type Fence =
       /** 1-based lines from the info string, as in ```ts {2,4-6}. */
       highlights: number[];
       notes: CodeNote[];
+      /** From the info string, as in ```ts [src/request.ts]. */
+      title: string | undefined;
     };
 
 const fileRefPattern = /^(\d+):(\d+):(.+)$/;
@@ -60,22 +77,21 @@ export function parseFence(
   lang: string,
   source: string,
   highlights: number[] = [],
+  title?: string,
+  /** The info string after the language and highlights, as in ```mermaid diff. */
+  meta?: string,
 ): Fence {
   const trimmed = source.replace(/\n$/, "");
-  if (lang === "mermaid")
-    return {
-      kind: "mermaid",
-      source: trimmed,
-      annotations: parseDiagramAnnotations(trimmed),
-    };
+  const diff = meta?.split(/\s+/).includes("diff") ?? false;
+  if (lang === "mermaid") return mermaidFence(trimmed, diff, title);
   if (lang === "services")
     return {
       kind: "services",
       source: trimmed,
-      parsed: parseServiceDiagram(trimmed),
+      parsed: parseServiceDiagram(trimmed, diff),
     };
   if (lang === "html") return { kind: "html", source: trimmed };
-  if (lang === "callstack") return callStackFence(trimmed, highlights);
+  if (lang === "callstack") return callStackFence(trimmed, highlights, title);
 
   // The first line is the rev (blank for uncommitted); each later line is a path to review.
   if (lang === "changes") {
@@ -101,7 +117,8 @@ export function parseFence(
 
   const diffPath = diffPathPattern.exec(lang);
   if (lang === "diff" || diffPath !== null) {
-    if (isCallStackSource(trimmed)) return callStackFence(trimmed, highlights);
+    if (isCallStackSource(trimmed))
+      return callStackFence(trimmed, highlights, title);
     return {
       kind: "diff",
       path: diffPath === null ? pathFromDiffSource(trimmed) : diffPath[1],
@@ -116,10 +133,61 @@ export function parseFence(
     source: code,
     highlights,
     notes,
+    title,
+  };
+}
+
+/**
+ * A diff's lines start with `-` (Today only), `+` (Proposed only), or
+ * anything else (both). The viewer draws every line, then marks what each
+ * side lacks, so Mermaid syntax never needs parsing here.
+ */
+function mermaidFence(
+  source: string,
+  diff: boolean,
+  title: string | undefined,
+): Fence {
+  if (!diff)
+    return {
+      kind: "mermaid",
+      source,
+      annotations: parseDiagramAnnotations(source),
+      sides: undefined,
+      title,
+    };
+  const rows = source.split("\n").map((line) => ({
+    sign: line[0],
+    text: line.replace(/^[+ -]/, ""),
+  }));
+  const without = (sign: string) =>
+    rows
+      .filter((row) => row.sign !== sign)
+      .map((row) => row.text)
+      .join("\n");
+  // Mermaid keeps a node's first label, so within each run of changed lines
+  // the `+` lines come first and a relabeled node shows its Proposed label.
+  const merged: string[] = [];
+  const removed: string[] = [];
+  for (const row of rows) {
+    if (row.sign === "-") removed.push(row.text);
+    else if (row.sign === "+") merged.push(row.text);
+    else merged.push(...removed.splice(0), row.text);
+  }
+  merged.push(...removed);
+  return {
+    kind: "mermaid",
+    source: merged.join("\n"),
+    annotations: parseDiagramAnnotations(merged.join("\n")),
+    sides: { today: without("+"), proposed: without("-") },
+    title,
   };
 }
 
-function callStackFence(source: string, highlights: number[]): Fence {
+function callStackFence(
+  source: string,
+  highlights: number[],
+  title: string | undefined,
+): Fence {
   const { code, notes } = parseCodeNotes(source);
   return {
     kind: "callstack",
@@ -127,5 +195,6 @@ function callStackFence(source: string, highlights: number[]): Fence {
     lines: parseCallStack(code),
     highlights,
     notes,
+    title,
   };
 }