@tanishqkancharla/diffmap 0.4.0 → 0.6.0

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"
+  > She is signed out.
 step "The browser submits the form"
   Browser -> API: POST /login
 step "The API asks Auth to verify"
@@ -261,6 +276,11 @@ 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
+  can say what the initial state shows. 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.
@@ -270,7 +290,7 @@ step "The API sets the session cookie"
   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.0",
   "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,122 @@
 # 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.**
 
-```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.
-
-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.
-
-## Show a change, not a wall of text
-
-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.
-
-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.
-
-### ✅ Phase 1: Call stacks that open the code
+`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.
 
-**Today**
+You can try `diffmap` before you install it. In a repository that has changes, paste this prompt into your agent:
 
-The agent describes the call path in a paragraph. You search for each function it names and guess how they connect.
-
-**Proposed**
-
-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
+```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.
 ```
 
-### ✅ Phase 2: Diagrams you can click
-
-**Today**
-
-The agent draws a flow in ASCII boxes. The boxes do not link to anything, and they break when a label gets long.
+If you like the result, install the skill:
 
-**Proposed**
-
-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]]
+```sh
+npx skills add tanishqkancharla/diffmap --skill generate-diffmap
 ```
 
-### ✅ Phase 3: Services you can play
+`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.
+
+## See the main ideas
 
-**Today**
+Your agent selects the best diagram for each idea. Each part of the diagram has a link to its code.
 
-A sequence diagram shows the messages between services, but not what each message changes. You keep the state of every service in your head.
+### Service diagrams
 
-**Proposed**
+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.
 
-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:
+To see how `diffmap serve` opens a spec, press **Play**. To read about a name with a dotted line, put the pointer on the name:
 
 ```services
 service Laptop
-  > Your machine. serve reads files here and uploads nothing.
+  > This is your computer. diffmap serve reads files here and does not upload them.
   service Agent "coding agent"
-    > Writes the spec and runs diffmap for you.
+    > The 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.
+    > This small server uses git to read your repository.
     state url = none
-  service Repo "your repo"
-    > Holds the spec and the commits it links to.
+  service Repo "your repository"
+    > The repository contains the spec and the commits that the spec refers 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.
+    > The Diff panel opens next to the spec. It shows the code for the link that you clicked.
     state shows = none
 
+start "diffmap serve opens a spec in your browser"
+  > The agent has written the spec, but nothing serves it yet.
+
 step "The agent serves the spec"
+  > Your agent runs diffmap serve with the path of the spec.
   Agent -> CLI: serve specs/search.md
-step "serve checks every commit the spec links to"
+step "serve examines each commit in the spec"
+  > Before the server starts, it uses git to read each commit and line range that the spec refers to.
   CLI -> Repo: readDocumentChanges [[src/git.ts#readDocumentChanges]]
-    > A wrong SHA or line range fails here, so you never meet a broken link.
+    > If a SHA or a line range is wrong, the command stops here. Thus, the page has no broken links.
 step "serve prints a URL for you"
+  > The server starts on your computer and gives the agent a local URL.
   CLI -> Agent: localhost URL
   CLI.url = localhost:4321
 step "You open the page"
+  > Your browser gets the spec from the server and shows it as a page.
   Page -> CLI: GET /
   CLI -> Page: spec
   Page.page = rendered
 step "You click a call stack row"
+  > The Diff panel asks the server for the code that the row refers to.
   Panel -> CLI: /__diffmap/source
   CLI -> Repo: git show
-    > Reads the file at the commit the row names, not the working tree.
+    > The server reads the file from the commit in the row, not from the working tree.
 step "The Diff panel shows the code"
+  > The server sends the lines, and the Diff panel shows them next to the spec.
   CLI -> Panel: lines
   Panel.shows = code
 ```
 
-### ✅ Phase 4: Open code from prose
+### Mermaid diagrams
+
+The page shows Mermaid diagrams. Each node and each arrow can have a link to its code. This diagram shows what occurs when you click a link:
+
+```mermaid
+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]]
+```
+
+### Call stacks
 
-**Today**
+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.
 
-A paragraph names a function as plain code, like `shareMarkdownFile`. You search the repo to find it.
+This call stack shows how `diffmap` draws call stacks:
 
-**Proposed**
+```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
+```
+
+## 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 +133,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 +169,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 +183,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 +197,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

@@ -62,7 +62,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,
   };
 }