From 95a0c00b1aac41a9c5856c7fffbfc9f97cd983ff Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 24 Jun 2026 13:52:47 +1000
Subject: [PATCH 01/20] feat(notes): recognize Pikchr diagram fences

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../src/lib/features/notes/NoteModal.svelte   |  12 +-
 .../lib/features/notes/diagramFormats.test.ts | 101 +++++++++++++++++
 .../src/lib/features/notes/diagramFormats.ts  | 106 ++++++++++++++++++
 .../lib/features/notes/noteMarkdown.test.ts   |  28 ++++-
 .../src/lib/features/notes/noteMarkdown.ts    |  35 ++++++
 5 files changed, 271 insertions(+), 11 deletions(-)
 create mode 100644 apps/staged/src/lib/features/notes/diagramFormats.test.ts
 create mode 100644 apps/staged/src/lib/features/notes/diagramFormats.ts

diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index 0dd7c955..c5d0e885 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -11,19 +11,15 @@
   import Check from '@lucide/svelte/icons/check';
   import MessageCircle from '@lucide/svelte/icons/message-circle';
   import FileText from '@lucide/svelte/icons/file-text';
-  import { marked } from 'marked';
   import * as Dialog from '$lib/components/ui/dialog';
   import { Button } from '$lib/components/ui/button';
-  import { sanitize } from '../../shared/sanitize';
   import { countAssistantMessagesAfter, handleExternalLinkClick } from '../../api/commands';
   import { formatChatButtonLabel } from '../sessions/noteFreshness';
   import InContentSearch from '../../shared/InContentSearch.svelte';
   import { highlightMatches, clearHighlights, scrollToMatch } from '../../shared/textHighlight';
   import { registerSearchShortcutTarget } from '../keyboard/searchTargets';
   import { viewport } from '../../shared/viewport.svelte';
-  import { noteMarkdownWithTitle } from './noteMarkdown';
-
-  marked.setOptions({ breaks: true, gfm: true });
+  import { noteMarkdownWithTitle, renderNoteMarkdown } from './noteMarkdown';
 
   interface Props {
     open: boolean;
@@ -113,10 +109,6 @@
     };
   });
 
-  function renderMarkdown(text: string): string {
-    return sanitize(marked.parse(text) as string);
-  }
-
   async function handleShare() {
     try {
       await navigator.clipboard.writeText(noteMarkdown);
@@ -276,7 +268,7 @@
       <div class="modal-content" bind:this={contentEl} onclick={handleExternalLinkClick}>
         {#if noteMarkdown.trim()}
           <div class="markdown-content">
-            {@html renderMarkdown(noteMarkdown)}
+            {@html renderNoteMarkdown(noteMarkdown)}
           </div>
         {:else}
           <p class="empty-note">This note has no content.</p>
diff --git a/apps/staged/src/lib/features/notes/diagramFormats.test.ts b/apps/staged/src/lib/features/notes/diagramFormats.test.ts
new file mode 100644
index 00000000..47d80ae2
--- /dev/null
+++ b/apps/staged/src/lib/features/notes/diagramFormats.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  extractNoteDiagramFences,
+  getNoteDiagramFormat,
+  isNoteDiagramFormat,
+  NOTE_DIAGRAM_FORMATS,
+  normalizeDiagramFenceLanguage,
+} from './diagramFormats';
+
+describe('note diagram format registry', () => {
+  it('registers Pikchr as the recommended general diagram format', () => {
+    expect(NOTE_DIAGRAM_FORMATS).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          language: 'pikchr',
+          displayName: 'Pikchr',
+          role: 'general',
+          recommended: true,
+        }),
+      ])
+    );
+  });
+
+  it('recognizes existing note diagram fence languages case-insensitively', () => {
+    expect(getNoteDiagramFormat('PIKCHR')?.language).toBe('pikchr');
+    expect(getNoteDiagramFormat('mermaid')?.language).toBe('mermaid');
+    expect(getNoteDiagramFormat('svg')?.language).toBe('svg');
+    expect(getNoteDiagramFormat('typescript')).toBeNull();
+  });
+
+  it('normalizes the first token from a fence info string', () => {
+    expect(normalizeDiagramFenceLanguage('  Pikchr title="draft"  ')).toBe('pikchr');
+    expect(normalizeDiagramFenceLanguage('')).toBeNull();
+  });
+
+  it('reports whether a fence language is a known note diagram format', () => {
+    expect(isNoteDiagramFormat('pikchr')).toBe(true);
+    expect(isNoteDiagramFormat('rust')).toBe(false);
+  });
+});
+
+describe('extractNoteDiagramFences', () => {
+  it('extracts Pikchr fence metadata and source', () => {
+    const diagrams = extractNoteDiagramFences(
+      [
+        '# Note',
+        '',
+        '```pikchr title="State flow"',
+        'box "Start" fit',
+        'arrow right 150%',
+        'circle "State" fit',
+        '```',
+      ].join('\n')
+    );
+
+    expect(diagrams).toEqual([
+      expect.objectContaining({
+        language: 'pikchr',
+        infoString: 'pikchr title="State flow"',
+        source: 'box "Start" fit\narrow right 150%\ncircle "State" fit',
+        startLine: 3,
+        endLine: 7,
+      }),
+    ]);
+  });
+
+  it('preserves Mermaid and SVG as recognized diagram formats', () => {
+    const diagrams = extractNoteDiagramFences(
+      ['```mermaid', 'flowchart TD', '```', '~~~svg', '<svg></svg>', '~~~'].join('\n')
+    );
+
+    expect(diagrams.map((diagram) => diagram.language)).toEqual(['mermaid', 'svg']);
+  });
+
+  it('ignores non-diagram fences while skipping their contents', () => {
+    const diagrams = extractNoteDiagramFences(
+      ['```ts', 'const sample = "```pikchr";', '```', '```pikchr', 'box "Done" fit', '```'].join(
+        '\n'
+      )
+    );
+
+    expect(diagrams).toHaveLength(1);
+    expect(diagrams[0].source).toBe('box "Done" fit');
+  });
+
+  it('handles an unclosed diagram fence through the end of the note', () => {
+    const diagrams = extractNoteDiagramFences(
+      ['Before', '```pikchr', 'box "Draft" fit'].join('\n')
+    );
+
+    expect(diagrams).toEqual([
+      expect.objectContaining({
+        language: 'pikchr',
+        source: 'box "Draft" fit',
+        startLine: 2,
+        endLine: null,
+      }),
+    ]);
+  });
+});
diff --git a/apps/staged/src/lib/features/notes/diagramFormats.ts b/apps/staged/src/lib/features/notes/diagramFormats.ts
new file mode 100644
index 00000000..82441b5e
--- /dev/null
+++ b/apps/staged/src/lib/features/notes/diagramFormats.ts
@@ -0,0 +1,106 @@
+export const NOTE_DIAGRAM_FORMATS = [
+  {
+    language: 'pikchr',
+    displayName: 'Pikchr',
+    role: 'general',
+    recommended: true,
+  },
+  {
+    language: 'mermaid',
+    displayName: 'Mermaid',
+    role: 'compatibility',
+    recommended: false,
+  },
+  {
+    language: 'svg',
+    displayName: 'SVG',
+    role: 'fallback',
+    recommended: false,
+  },
+] as const;
+
+export type NoteDiagramFormat = (typeof NOTE_DIAGRAM_FORMATS)[number];
+export type NoteDiagramLanguage = NoteDiagramFormat['language'];
+
+export interface NoteDiagramFence {
+  format: NoteDiagramFormat;
+  language: NoteDiagramLanguage;
+  infoString: string;
+  source: string;
+  startLine: number;
+  endLine: number | null;
+}
+
+const FORMATS_BY_LANGUAGE = new Map<NoteDiagramLanguage, NoteDiagramFormat>(
+  NOTE_DIAGRAM_FORMATS.map((format) => [format.language, format])
+);
+
+export function normalizeDiagramFenceLanguage(
+  infoString: string | null | undefined
+): string | null {
+  const language = infoString?.trim().split(/\s+/, 1)[0]?.toLowerCase();
+  return language || null;
+}
+
+export function getNoteDiagramFormat(
+  infoString: string | null | undefined
+): NoteDiagramFormat | null {
+  const language = normalizeDiagramFenceLanguage(infoString);
+  if (!language) return null;
+
+  return FORMATS_BY_LANGUAGE.get(language as NoteDiagramLanguage) ?? null;
+}
+
+export function isNoteDiagramFormat(infoString: string | null | undefined): boolean {
+  return getNoteDiagramFormat(infoString) !== null;
+}
+
+export function extractNoteDiagramFences(markdown: string): NoteDiagramFence[] {
+  const lines = markdown.split(/\r\n|\n|\r/);
+  const diagrams: NoteDiagramFence[] = [];
+
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const opening = lines[lineIndex].match(/^ {0,3}(`{3,}|~{3,})([^\n]*)$/);
+    if (!opening) continue;
+
+    const openingFence = opening[1];
+    const fenceChar = openingFence[0];
+    const fenceLength = openingFence.length;
+    const infoString = opening[2].trim();
+    const contentStart = lineIndex + 1;
+    let closingLineIndex: number | null = null;
+
+    for (
+      let candidateLineIndex = contentStart;
+      candidateLineIndex < lines.length;
+      candidateLineIndex++
+    ) {
+      if (isClosingFence(lines[candidateLineIndex], fenceChar, fenceLength)) {
+        closingLineIndex = candidateLineIndex;
+        break;
+      }
+    }
+
+    const contentEnd = closingLineIndex ?? lines.length;
+    const format = getNoteDiagramFormat(infoString);
+    if (format) {
+      diagrams.push({
+        format,
+        language: format.language,
+        infoString,
+        source: lines.slice(contentStart, contentEnd).join('\n'),
+        startLine: lineIndex + 1,
+        endLine: closingLineIndex === null ? null : closingLineIndex + 1,
+      });
+    }
+
+    lineIndex = closingLineIndex ?? lines.length;
+  }
+
+  return diagrams;
+}
+
+function isClosingFence(line: string, fenceChar: string, fenceLength: number): boolean {
+  const escapedFenceChar = fenceChar === '`' ? '`' : '\\~';
+  return new RegExp(`^ {0,3}${escapedFenceChar}{${fenceLength},}[ \\t]*$`).test(line);
+}
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
index fd25b4a4..841d741c 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { noteMarkdownWithTitle } from './noteMarkdown';
+import { noteMarkdownWithTitle, renderNoteMarkdown } from './noteMarkdown';
 
 describe('noteMarkdownWithTitle', () => {
   it('prepends the note title as a markdown H1', () => {
@@ -23,3 +23,29 @@ describe('noteMarkdownWithTitle', () => {
     expect(noteMarkdownWithTitle('', 'Body text.')).toBe('Body text.');
   });
 });
+
+describe('renderNoteMarkdown', () => {
+  it('marks Pikchr fenced blocks as note diagram sources', () => {
+    const html = renderNoteMarkdown('```pikchr\nbox "Start" fit\n```');
+
+    expect(html).toContain(
+      '<pre class="note-diagram-source note-diagram-source-pikchr"><code class="language-pikchr">'
+    );
+    expect(html).toContain('box "Start" fit');
+  });
+
+  it('leaves non-diagram fenced blocks as normal code blocks', () => {
+    const html = renderNoteMarkdown('```ts\nconst value = 1;\n```');
+
+    expect(html).toContain('<pre><code class="language-ts">');
+    expect(html).not.toContain('note-diagram-source');
+  });
+
+  it('keeps raw SVG fences escaped as source for now', () => {
+    const html = renderNoteMarkdown('```svg\n<svg><script>alert(1)</script></svg>\n```');
+
+    expect(html).toContain('note-diagram-source-svg');
+    expect(html).toContain('&lt;svg&gt;&lt;script&gt;alert(1)&lt;/script&gt;&lt;/svg&gt;');
+    expect(html).not.toContain('<script>');
+  });
+});
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.ts b/apps/staged/src/lib/features/notes/noteMarkdown.ts
index 64b2c108..6e9b60ab 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.ts
@@ -1,3 +1,10 @@
+import { marked, Renderer, type Tokens } from 'marked';
+
+import { sanitize } from '../../shared/sanitize';
+import { getNoteDiagramFormat } from './diagramFormats';
+
+const NOTE_MARKDOWN_RENDERER = createNoteMarkdownRenderer();
+
 export function noteMarkdownWithTitle(title: string, content: string): string {
   const normalizedTitle = title.trim();
   if (!normalizedTitle) return content;
@@ -12,3 +19,31 @@ export function noteMarkdownWithTitle(title: string, content: string): string {
 function startsWithMarkdownH1(content: string): boolean {
   return /^#[ \t]+\S/.test(content);
 }
+
+export function renderNoteMarkdown(text: string): string {
+  return sanitize(
+    marked.parse(text, {
+      breaks: true,
+      gfm: true,
+      renderer: NOTE_MARKDOWN_RENDERER,
+    }) as string
+  );
+}
+
+function createNoteMarkdownRenderer(): Renderer {
+  const renderer = new Renderer();
+  const renderCode = renderer.code.bind(renderer);
+
+  renderer.code = (token: Tokens.Code) => {
+    const rendered = renderCode(token);
+    const format = getNoteDiagramFormat(token.lang);
+    if (!format) return rendered;
+
+    return rendered.replace(
+      '<pre>',
+      `<pre class="note-diagram-source note-diagram-source-${format.language}">`
+    );
+  };
+
+  return renderer;
+}

From 3e8e171327226ddfb18dfc3d01e720958be75391 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 24 Jun 2026 14:00:44 +1000
Subject: [PATCH 02/20] feat(notes): preview Pikchr diagram fences

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../src/lib/features/notes/NoteModal.svelte   | 30 ++++++++++++++++
 .../lib/features/notes/diagramRendering.ts    | 34 +++++++++++++++++++
 .../lib/features/notes/noteMarkdown.test.ts   | 29 +++++++++++++---
 .../src/lib/features/notes/noteMarkdown.ts    | 10 ++----
 apps/staged/src/lib/shared/sanitize.ts        |  3 ++
 5 files changed, 94 insertions(+), 12 deletions(-)
 create mode 100644 apps/staged/src/lib/features/notes/diagramRendering.ts

diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index c5d0e885..ac5b817b 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -478,6 +478,36 @@
     font-size: 0.85em;
   }
 
+  .markdown-content :global(.note-diagram) {
+    margin: 0.9em 0;
+    border: 1px solid var(--border-subtle);
+    border-radius: 8px;
+    overflow: hidden;
+    background: var(--bg-primary);
+  }
+
+  .markdown-content :global(.note-diagram-caption) {
+    display: flex;
+    align-items: center;
+    min-height: 30px;
+    padding: 0 10px;
+    border-bottom: 1px solid var(--border-subtle);
+    color: var(--text-secondary);
+    background: var(--bg-chrome);
+    font-size: var(--size-xs);
+    font-weight: 600;
+  }
+
+  .markdown-content :global(.note-diagram-preview) {
+    background: var(--bg-elevated, var(--bg-hover));
+  }
+
+  .markdown-content :global(.note-diagram .note-diagram-source) {
+    margin: 0;
+    border-radius: 0;
+    background: transparent;
+  }
+
   .markdown-content :global(blockquote) {
     margin: 0.5em 0;
     padding-left: 0.75em;
diff --git a/apps/staged/src/lib/features/notes/diagramRendering.ts b/apps/staged/src/lib/features/notes/diagramRendering.ts
new file mode 100644
index 00000000..3e3b759d
--- /dev/null
+++ b/apps/staged/src/lib/features/notes/diagramRendering.ts
@@ -0,0 +1,34 @@
+import type { Tokens } from 'marked';
+
+import { getNoteDiagramFormat, type NoteDiagramFormat } from './diagramFormats';
+
+export function renderNoteDiagramCodeBlock(
+  token: Tokens.Code,
+  renderedSource: string
+): string | null {
+  const format = getNoteDiagramFormat(token.lang);
+  if (!format) return null;
+
+  const renderedDiagramSource = withDiagramSourceClass(renderedSource, format);
+  if (format.language !== 'pikchr') return renderedDiagramSource;
+
+  return renderPikchrPreview(renderedDiagramSource);
+}
+
+function withDiagramSourceClass(renderedSource: string, format: NoteDiagramFormat): string {
+  return renderedSource.replace(
+    '<pre>',
+    `<pre class="note-diagram-source note-diagram-source-${format.language}">`
+  );
+}
+
+function renderPikchrPreview(renderedSource: string): string {
+  return [
+    '<figure class="note-diagram note-diagram-pikchr">',
+    '<figcaption class="note-diagram-caption">Pikchr</figcaption>',
+    '<div class="note-diagram-preview note-diagram-preview-pikchr">',
+    renderedSource,
+    '</div>',
+    '</figure>',
+  ].join('');
+}
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
index 841d741c..3cee27fb 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
@@ -25,12 +25,13 @@ describe('noteMarkdownWithTitle', () => {
 });
 
 describe('renderNoteMarkdown', () => {
-  it('marks Pikchr fenced blocks as note diagram sources', () => {
+  it('renders Pikchr fenced blocks as inert diagram previews with escaped source', () => {
     const html = renderNoteMarkdown('```pikchr\nbox "Start" fit\n```');
 
-    expect(html).toContain(
-      '<pre class="note-diagram-source note-diagram-source-pikchr"><code class="language-pikchr">'
-    );
+    expect(html).toContain('<figure class="note-diagram note-diagram-pikchr">');
+    expect(html).toContain('<figcaption class="note-diagram-caption">Pikchr</figcaption>');
+    expect(html).toContain('<div class="note-diagram-preview note-diagram-preview-pikchr">');
+    expect(html).toContain('<pre class="note-diagram-source note-diagram-source-pikchr">');
     expect(html).toContain('box "Start" fit');
   });
 
@@ -41,6 +42,26 @@ describe('renderNoteMarkdown', () => {
     expect(html).not.toContain('note-diagram-source');
   });
 
+  it('preserves Mermaid fences as escaped diagram source blocks', () => {
+    const html = renderNoteMarkdown('```mermaid\nflowchart TD\nA-->B\n```');
+
+    expect(html).toContain(
+      '<pre class="note-diagram-source note-diagram-source-mermaid"><code class="language-mermaid">'
+    );
+    expect(html).toContain('flowchart TD');
+    expect(html).not.toContain('note-diagram-preview');
+  });
+
+  it('does not emit executable Pikchr preview surfaces before an SVG renderer exists', () => {
+    const html = renderNoteMarkdown('```pikchr\nbox "<script>alert(1)</script>" fit\n```');
+
+    expect(html).toContain('&lt;script&gt;alert(1)&lt;/script&gt;');
+    expect(html).not.toContain('<script>');
+    expect(html).not.toContain('<svg');
+    expect(html).not.toContain('<iframe');
+    expect(html).not.toContain('srcdoc');
+  });
+
   it('keeps raw SVG fences escaped as source for now', () => {
     const html = renderNoteMarkdown('```svg\n<svg><script>alert(1)</script></svg>\n```');
 
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.ts b/apps/staged/src/lib/features/notes/noteMarkdown.ts
index 6e9b60ab..33347e38 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.ts
@@ -1,7 +1,7 @@
 import { marked, Renderer, type Tokens } from 'marked';
 
 import { sanitize } from '../../shared/sanitize';
-import { getNoteDiagramFormat } from './diagramFormats';
+import { renderNoteDiagramCodeBlock } from './diagramRendering';
 
 const NOTE_MARKDOWN_RENDERER = createNoteMarkdownRenderer();
 
@@ -36,13 +36,7 @@ function createNoteMarkdownRenderer(): Renderer {
 
   renderer.code = (token: Tokens.Code) => {
     const rendered = renderCode(token);
-    const format = getNoteDiagramFormat(token.lang);
-    if (!format) return rendered;
-
-    return rendered.replace(
-      '<pre>',
-      `<pre class="note-diagram-source note-diagram-source-${format.language}">`
-    );
+    return renderNoteDiagramCodeBlock(token, rendered) ?? rendered;
   };
 
   return renderer;
diff --git a/apps/staged/src/lib/shared/sanitize.ts b/apps/staged/src/lib/shared/sanitize.ts
index 2ef08851..4c287fa5 100644
--- a/apps/staged/src/lib/shared/sanitize.ts
+++ b/apps/staged/src/lib/shared/sanitize.ts
@@ -29,6 +29,9 @@ export function sanitize(dirty: string): string {
       th: ['align'],
       code: ['class'], // for syntax-highlight class names
       span: ['class'], // for syntax-highlight class names
+      div: ['class'],
+      figcaption: ['class'],
+      figure: ['class'],
       pre: ['class'],
     },
     // Only allow checkbox inputs (GFM task lists)

From f780f5d7a9df22fe4a5f6b27aa2bf51997ae19d9 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 24 Jun 2026 14:21:10 +1000
Subject: [PATCH 03/20] feat(notes): render Pikchr diagram fences

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/package.json                      |   1 +
 .../src/lib/features/notes/NoteModal.svelte   |  41 ++++++-
 .../lib/features/notes/diagramRendering.ts    |  39 +++++-
 .../lib/features/notes/noteMarkdown.test.ts   |  62 ++++++++--
 .../src/lib/features/notes/noteMarkdown.ts    |  54 +++++++--
 .../features/notes/pikchrRendering.test.ts    |  67 +++++++++++
 .../src/lib/features/notes/pikchrRendering.ts | 112 ++++++++++++++++++
 apps/staged/src/types/sanitize-html.d.ts      |   2 +
 pnpm-lock.yaml                                |   9 ++
 9 files changed, 365 insertions(+), 22 deletions(-)
 create mode 100644 apps/staged/src/lib/features/notes/pikchrRendering.test.ts
 create mode 100644 apps/staged/src/lib/features/notes/pikchrRendering.ts

diff --git a/apps/staged/package.json b/apps/staged/package.json
index ff4d9c63..9de3cb98 100644
--- a/apps/staged/package.json
+++ b/apps/staged/package.json
@@ -53,6 +53,7 @@
     "@tauri-apps/plugin-updater": "^2.10.0",
     "ansi-to-html": "^0.7.2",
     "marked": "^17.0.1",
+    "pikchr-js": "0.1.4",
     "sanitize-html": "^2.17.0",
     "shiki": "^3.20.0"
   },
diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index ac5b817b..cc1e3b22 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -19,7 +19,9 @@
   import { highlightMatches, clearHighlights, scrollToMatch } from '../../shared/textHighlight';
   import { registerSearchShortcutTarget } from '../keyboard/searchTargets';
   import { viewport } from '../../shared/viewport.svelte';
+  import { extractNoteDiagramFences } from './diagramFormats';
   import { noteMarkdownWithTitle, renderNoteMarkdown } from './noteMarkdown';
+  import { loadNotePikchrRenderer, type NotePikchrRenderer } from './pikchrRendering';
 
   interface Props {
     open: boolean;
@@ -54,6 +56,12 @@
   let canOpenSession = $derived(Boolean(sessionId && onOpenSession));
   let showChatInfo = $derived(canOpenSession && assistantMessagesAfterNote > 0);
   let noteMarkdown = $derived(noteMarkdownWithTitle(title, content));
+  let noteHasPikchr = $derived(
+    extractNoteDiagramFences(noteMarkdown).some((diagram) => diagram.language === 'pikchr')
+  );
+  let pikchrRenderer = $state<NotePikchrRenderer | null>(null);
+  let pikchrRendererLoadFailed = $state(false);
+  let renderedNoteHtml = $derived(renderNoteMarkdown(noteMarkdown, { pikchrRenderer }));
 
   // Search state
   let searchVisible = $state(false);
@@ -81,6 +89,23 @@
     };
   });
 
+  $effect(() => {
+    if (!open || !noteHasPikchr || pikchrRenderer || pikchrRendererLoadFailed) return;
+
+    let stale = false;
+    loadNotePikchrRenderer()
+      .then((renderer) => {
+        if (!stale) pikchrRenderer = renderer;
+      })
+      .catch(() => {
+        if (!stale) pikchrRendererLoadFailed = true;
+      });
+
+    return () => {
+      stale = true;
+    };
+  });
+
   onDestroy(() => {
     unregisterSearchTarget?.();
   });
@@ -268,7 +293,7 @@
       <div class="modal-content" bind:this={contentEl} onclick={handleExternalLinkClick}>
         {#if noteMarkdown.trim()}
           <div class="markdown-content">
-            {@html renderNoteMarkdown(noteMarkdown)}
+            {@html renderedNoteHtml}
           </div>
         {:else}
           <p class="empty-note">This note has no content.</p>
@@ -499,7 +524,21 @@
   }
 
   .markdown-content :global(.note-diagram-preview) {
+    display: flex;
+    justify-content: center;
+    padding: 16px;
     background: var(--bg-elevated, var(--bg-hover));
+    overflow-x: auto;
+  }
+
+  .markdown-content :global(.note-diagram-preview svg) {
+    display: block;
+    max-width: 100%;
+    height: auto;
+  }
+
+  .markdown-content :global(.note-diagram-source-wrap) {
+    border-top: 1px solid var(--border-subtle);
   }
 
   .markdown-content :global(.note-diagram .note-diagram-source) {
diff --git a/apps/staged/src/lib/features/notes/diagramRendering.ts b/apps/staged/src/lib/features/notes/diagramRendering.ts
index 3e3b759d..8767fa76 100644
--- a/apps/staged/src/lib/features/notes/diagramRendering.ts
+++ b/apps/staged/src/lib/features/notes/diagramRendering.ts
@@ -1,18 +1,44 @@
 import type { Tokens } from 'marked';
 
+import { sanitize } from '../../shared/sanitize';
 import { getNoteDiagramFormat, type NoteDiagramFormat } from './diagramFormats';
+import { sanitizePikchrSvg, type NotePikchrRenderer } from './pikchrRendering';
+
+export interface NoteDiagramRenderingOptions {
+  pikchrRenderer?: NotePikchrRenderer | null;
+}
+
+export interface RenderedNoteDiagramCodeBlock {
+  html: string;
+  trustedHtml: boolean;
+}
 
 export function renderNoteDiagramCodeBlock(
   token: Tokens.Code,
-  renderedSource: string
-): string | null {
+  renderedSource: string,
+  options: NoteDiagramRenderingOptions = {}
+): RenderedNoteDiagramCodeBlock | null {
   const format = getNoteDiagramFormat(token.lang);
   if (!format) return null;
 
   const renderedDiagramSource = withDiagramSourceClass(renderedSource, format);
-  if (format.language !== 'pikchr') return renderedDiagramSource;
+  if (format.language !== 'pikchr') {
+    return { html: renderedDiagramSource, trustedHtml: false };
+  }
+
+  const renderedPikchr = options.pikchrRenderer?.(token.text);
+  if (!renderedPikchr || renderedPikchr.kind !== 'svg') {
+    return { html: renderedDiagramSource, trustedHtml: false };
+  }
+  const renderedSvg = sanitizePikchrSvg(renderedPikchr.svg);
+  if (!renderedSvg) {
+    return { html: renderedDiagramSource, trustedHtml: false };
+  }
 
-  return renderPikchrPreview(renderedDiagramSource);
+  return {
+    html: renderPikchrPreview(sanitize(renderedDiagramSource), renderedSvg),
+    trustedHtml: true,
+  };
 }
 
 function withDiagramSourceClass(renderedSource: string, format: NoteDiagramFormat): string {
@@ -22,11 +48,14 @@ function withDiagramSourceClass(renderedSource: string, format: NoteDiagramForma
   );
 }
 
-function renderPikchrPreview(renderedSource: string): string {
+function renderPikchrPreview(renderedSource: string, renderedSvg: string): string {
   return [
     '<figure class="note-diagram note-diagram-pikchr">',
     '<figcaption class="note-diagram-caption">Pikchr</figcaption>',
     '<div class="note-diagram-preview note-diagram-preview-pikchr">',
+    renderedSvg,
+    '</div>',
+    '<div class="note-diagram-source-wrap">',
     renderedSource,
     '</div>',
     '</figure>',
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
index 3cee27fb..f5cbd1fb 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import { noteMarkdownWithTitle, renderNoteMarkdown } from './noteMarkdown';
+import type { NotePikchrRenderer } from './pikchrRendering';
 
 describe('noteMarkdownWithTitle', () => {
   it('prepends the note title as a markdown H1', () => {
@@ -25,14 +26,13 @@ describe('noteMarkdownWithTitle', () => {
 });
 
 describe('renderNoteMarkdown', () => {
-  it('renders Pikchr fenced blocks as inert diagram previews with escaped source', () => {
+  it('renders Pikchr fenced blocks as escaped source while the renderer is unavailable', () => {
     const html = renderNoteMarkdown('```pikchr\nbox "Start" fit\n```');
 
-    expect(html).toContain('<figure class="note-diagram note-diagram-pikchr">');
-    expect(html).toContain('<figcaption class="note-diagram-caption">Pikchr</figcaption>');
-    expect(html).toContain('<div class="note-diagram-preview note-diagram-preview-pikchr">');
     expect(html).toContain('<pre class="note-diagram-source note-diagram-source-pikchr">');
     expect(html).toContain('box "Start" fit');
+    expect(html).not.toContain('<svg');
+    expect(html).not.toContain('note-diagram-preview');
   });
 
   it('leaves non-diagram fenced blocks as normal code blocks', () => {
@@ -52,14 +52,41 @@ describe('renderNoteMarkdown', () => {
     expect(html).not.toContain('note-diagram-preview');
   });
 
-  it('does not emit executable Pikchr preview surfaces before an SVG renderer exists', () => {
-    const html = renderNoteMarkdown('```pikchr\nbox "<script>alert(1)</script>" fit\n```');
+  it('renders Pikchr fenced blocks as sanitized SVG when a renderer is loaded', () => {
+    const html = renderNoteMarkdown('```pikchr\nbox "Start" fit\n```', {
+      pikchrRenderer: safePikchrRenderer,
+    });
+
+    expect(html).toContain('<figure class="note-diagram note-diagram-pikchr">');
+    expect(html).toContain('<figcaption class="note-diagram-caption">Pikchr</figcaption>');
+    expect(html).toContain('<div class="note-diagram-preview note-diagram-preview-pikchr">');
+    expect(html).toContain('<svg');
+    expect(html).toContain('class="note-pikchr-svg"');
+    expect(html).toContain('<path');
+    expect(html).toContain('stroke:rgb(0,0,0)');
+    expect(html).toContain('<div class="note-diagram-source-wrap">');
+    expect(html).toContain('<pre class="note-diagram-source note-diagram-source-pikchr">');
+    expect(html).toContain('box "Start" fit');
+    expect(html).not.toContain('STAGED_NOTE_TRUSTED_DIAGRAM_');
+  });
 
-    expect(html).toContain('&lt;script&gt;alert(1)&lt;/script&gt;');
+  it('does not allow renderer SVG through the generic Markdown sanitizer', () => {
+    const html = renderNoteMarkdown('<svg><script>alert(1)</script></svg>');
+
+    expect(html).not.toContain('<svg');
     expect(html).not.toContain('<script>');
+  });
+
+  it('falls back to escaped source when the Pikchr renderer rejects the SVG', () => {
+    const html = renderNoteMarkdown('```pikchr\nbox "Unsafe" fit\n```', {
+      pikchrRenderer: unsafePikchrRenderer,
+    });
+
+    expect(html).toContain('<pre class="note-diagram-source note-diagram-source-pikchr">');
+    expect(html).toContain('box "Unsafe" fit');
     expect(html).not.toContain('<svg');
-    expect(html).not.toContain('<iframe');
-    expect(html).not.toContain('srcdoc');
+    expect(html).not.toContain('<script>');
+    expect(html).not.toContain('onclick');
   });
 
   it('keeps raw SVG fences escaped as source for now', () => {
@@ -70,3 +97,20 @@ describe('renderNoteMarkdown', () => {
     expect(html).not.toContain('<script>');
   });
 });
+
+const safePikchrRenderer: NotePikchrRenderer = () => ({
+  kind: 'svg',
+  width: 58,
+  height: 34,
+  svg: [
+    '<svg xmlns="http://www.w3.org/2000/svg" class="note-pikchr-svg" viewBox="0 0 58 34">',
+    '<path d="M2,32L56,32L56,2L2,2Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />',
+    '<text x="29" y="17" text-anchor="middle" fill="rgb(0,0,0)" dominant-baseline="central">Start</text>',
+    '</svg>',
+  ].join(''),
+});
+
+const unsafePikchrRenderer: NotePikchrRenderer = () => ({
+  kind: 'error',
+  message: 'Pikchr rendered unsafe SVG.',
+});
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.ts b/apps/staged/src/lib/features/notes/noteMarkdown.ts
index 33347e38..727219ee 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.ts
@@ -1,9 +1,14 @@
 import { marked, Renderer, type Tokens } from 'marked';
 
 import { sanitize } from '../../shared/sanitize';
-import { renderNoteDiagramCodeBlock } from './diagramRendering';
+import { renderNoteDiagramCodeBlock, type NoteDiagramRenderingOptions } from './diagramRendering';
 
-const NOTE_MARKDOWN_RENDERER = createNoteMarkdownRenderer();
+interface TrustedHtmlReplacement {
+  placeholder: string;
+  html: string;
+}
+
+let fallbackPlaceholderSequence = 0;
 
 export function noteMarkdownWithTitle(title: string, content: string): string {
   const normalizedTitle = title.trim();
@@ -20,24 +25,59 @@ function startsWithMarkdownH1(content: string): boolean {
   return /^#[ \t]+\S/.test(content);
 }
 
-export function renderNoteMarkdown(text: string): string {
-  return sanitize(
+export function renderNoteMarkdown(
+  text: string,
+  options: NoteDiagramRenderingOptions = {}
+): string {
+  const trustedHtml: TrustedHtmlReplacement[] = [];
+  const renderedMarkdown = sanitize(
     marked.parse(text, {
       breaks: true,
       gfm: true,
-      renderer: NOTE_MARKDOWN_RENDERER,
+      renderer: createNoteMarkdownRenderer(options, trustedHtml),
     }) as string
   );
+
+  return restoreTrustedHtml(renderedMarkdown, trustedHtml);
 }
 
-function createNoteMarkdownRenderer(): Renderer {
+function createNoteMarkdownRenderer(
+  options: NoteDiagramRenderingOptions,
+  trustedHtml: TrustedHtmlReplacement[]
+): Renderer {
   const renderer = new Renderer();
   const renderCode = renderer.code.bind(renderer);
 
   renderer.code = (token: Tokens.Code) => {
     const rendered = renderCode(token);
-    return renderNoteDiagramCodeBlock(token, rendered) ?? rendered;
+    const diagram = renderNoteDiagramCodeBlock(token, rendered, options);
+    if (!diagram) return rendered;
+    if (!diagram.trustedHtml) return diagram.html;
+
+    return stashTrustedHtml(diagram.html, trustedHtml);
   };
 
   return renderer;
 }
+
+function stashTrustedHtml(html: string, trustedHtml: TrustedHtmlReplacement[]): string {
+  const placeholder = `STAGED_NOTE_TRUSTED_DIAGRAM_${trustedHtml.length}_${createPlaceholderNonce()}`;
+  trustedHtml.push({ placeholder, html });
+  return placeholder;
+}
+
+function restoreTrustedHtml(
+  renderedMarkdown: string,
+  trustedHtml: TrustedHtmlReplacement[]
+): string {
+  return trustedHtml.reduce((html, replacement) => {
+    return html.replaceAll(replacement.placeholder, replacement.html);
+  }, renderedMarkdown);
+}
+
+function createPlaceholderNonce(): string {
+  const randomUuid = globalThis.crypto?.randomUUID?.();
+  if (randomUuid) return randomUuid.replaceAll('-', '_');
+
+  return `${Date.now().toString(36)}_${fallbackPlaceholderSequence++}`;
+}
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts b/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
new file mode 100644
index 00000000..aeb2d9a3
--- /dev/null
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import { loadNotePikchrRenderer, sanitizePikchrSvg } from './pikchrRendering';
+
+describe('sanitizePikchrSvg', () => {
+  it('keeps static Pikchr geometry and path styles', () => {
+    const svg = sanitizePikchrSvg(
+      [
+        '<svg xmlns="http://www.w3.org/2000/svg" class="note-pikchr-svg" viewBox="0 0 58 34" data-pikchr-date="20260403102956">',
+        '<path d="M2,32L56,32L56,2L2,2Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />',
+        '<text x="29" y="17" text-anchor="middle" fill="rgb(0,0,0)" dominant-baseline="central">Start</text>',
+        '</svg>',
+      ].join('')
+    );
+
+    expect(svg).toContain('<svg');
+    expect(svg).toContain('viewBox="0 0 58 34"');
+    expect(svg).toContain('<path');
+    expect(svg).toContain('style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0)"');
+    expect(svg).toContain('<text');
+    expect(svg).not.toContain('data-pikchr-date');
+  });
+
+  it('strips executable and external-resource SVG surface', () => {
+    const svg = sanitizePikchrSvg(
+      [
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10" onclick="alert(1)">',
+        '<script>alert(1)</script>',
+        '<foreignObject><iframe src="https://example.com"></iframe></foreignObject>',
+        '<path d="M0,0L10,10" style="stroke:url(https://example.com/x);fill:none;" />',
+        '<text x="1" y="1" href="https://example.com">Label</text>',
+        '</svg>',
+      ].join('')
+    );
+
+    expect(svg).toContain('<svg');
+    expect(svg).not.toContain('<script');
+    expect(svg).not.toContain('foreignObject');
+    expect(svg).not.toContain('iframe');
+    expect(svg).not.toContain('onclick');
+    expect(svg).not.toContain('href');
+    expect(svg).not.toContain('url(');
+  });
+
+  it('rejects non-SVG renderer output', () => {
+    expect(sanitizePikchrSvg('<div><pre>ERROR</pre></div>')).toBeNull();
+  });
+});
+
+describe('loadNotePikchrRenderer', () => {
+  it('loads the bundled renderer and returns sanitized SVG', async () => {
+    const renderPikchr = await loadNotePikchrRenderer();
+    const rendered = renderPikchr('box "Start" fit');
+
+    expect(rendered.kind).toBe('svg');
+    if (rendered.kind !== 'svg') return;
+
+    expect(rendered.width).toBeGreaterThan(0);
+    expect(rendered.height).toBeGreaterThan(0);
+    expect(rendered.svg).toContain('<svg');
+    expect(rendered.svg).toContain('class="note-pikchr-svg"');
+    expect(rendered.svg).toContain('<path');
+    expect(rendered.svg).toContain('Start');
+    expect(rendered.svg).not.toContain('<script');
+    expect(rendered.svg).not.toContain('data-pikchr-date');
+  });
+});
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.ts b/apps/staged/src/lib/features/notes/pikchrRendering.ts
new file mode 100644
index 00000000..2afd740f
--- /dev/null
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.ts
@@ -0,0 +1,112 @@
+import type { Pikchr } from 'pikchr-js';
+import sanitizeHtml from 'sanitize-html';
+
+const PIKCHR_SVG_CLASS = 'note-pikchr-svg';
+const MAX_PIKCHR_SOURCE_LENGTH = 20_000;
+const MAX_PIKCHR_SVG_LENGTH = 250_000;
+const PIKCHR_SVG_ROOT = /^\s*<svg[\s>]/i;
+
+const CSS_NUMBER = String.raw`[-+]?(?:\d+(?:\.\d+)?|\.\d+)(?:e[-+]?\d+)?`;
+const CSS_LENGTH = new RegExp(`^(?:${CSS_NUMBER})(?:px|pt|pc|mm|cm|in|em|rem|%)?$`);
+const CSS_COLOR =
+  /^(?:none|transparent|currentColor|[a-zA-Z]+|#[0-9a-fA-F]{3,8}|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}(?:\s*,\s*(?:0|1|0?\.\d+))?\s*\))$/;
+const CSS_DASH_ARRAY = new RegExp(`^(?:${CSS_NUMBER})(?:\\s*,\\s*(?:${CSS_NUMBER}))*$`);
+
+export type RenderedPikchrDiagram =
+  | {
+      kind: 'svg';
+      svg: string;
+      width: number;
+      height: number;
+    }
+  | {
+      kind: 'error';
+      message: string;
+    };
+
+export type NotePikchrRenderer = (source: string) => RenderedPikchrDiagram;
+
+let rendererPromise: Promise<NotePikchrRenderer> | null = null;
+
+export function loadNotePikchrRenderer(): Promise<NotePikchrRenderer> {
+  rendererPromise ??= import('pikchr-js')
+    .then(({ default: loadPikchr }) => loadPikchr())
+    .then((pikchr) => {
+      return (source: string) => renderPikchrSource(pikchr, source);
+    });
+  return rendererPromise;
+}
+
+export function renderPikchrSource(pikchr: Pikchr, source: string): RenderedPikchrDiagram {
+  if (source.length > MAX_PIKCHR_SOURCE_LENGTH) {
+    return { kind: 'error', message: 'Pikchr source is too large to render safely.' };
+  }
+
+  try {
+    const rendered = pikchr.render(source, PIKCHR_SVG_CLASS);
+    if (rendered.width < 0 || rendered.height < 0 || !PIKCHR_SVG_ROOT.test(rendered.svg)) {
+      return { kind: 'error', message: 'Pikchr could not render this diagram.' };
+    }
+
+    const svg = sanitizePikchrSvg(rendered.svg);
+    if (!svg) {
+      return { kind: 'error', message: 'Pikchr rendered unsafe SVG.' };
+    }
+
+    return {
+      kind: 'svg',
+      svg,
+      width: rendered.width,
+      height: rendered.height,
+    };
+  } catch {
+    return { kind: 'error', message: 'Pikchr could not render this diagram.' };
+  }
+}
+
+export function sanitizePikchrSvg(svg: string): string | null {
+  if (svg.length > MAX_PIKCHR_SVG_LENGTH || !PIKCHR_SVG_ROOT.test(svg)) {
+    return null;
+  }
+
+  const sanitized = sanitizeHtml(svg, {
+    allowedTags: [
+      'svg',
+      'g',
+      'path',
+      'text',
+      'rect',
+      'circle',
+      'ellipse',
+      'line',
+      'polyline',
+      'polygon',
+    ],
+    allowedAttributes: {
+      svg: ['xmlns', 'viewBox', 'viewbox', 'class', 'style', 'width', 'height'],
+      g: ['class', 'transform', 'style'],
+      path: ['class', 'd', 'style'],
+      text: ['class', 'x', 'y', 'dx', 'dy', 'text-anchor', 'dominant-baseline', 'style'],
+      rect: ['class', 'x', 'y', 'width', 'height', 'rx', 'ry', 'style'],
+      circle: ['class', 'cx', 'cy', 'r', 'style'],
+      ellipse: ['class', 'cx', 'cy', 'rx', 'ry', 'style'],
+      line: ['class', 'x1', 'y1', 'x2', 'y2', 'style'],
+      polyline: ['class', 'points', 'style'],
+      polygon: ['class', 'points', 'style'],
+    },
+    allowedStyles: {
+      '*': {
+        fill: [CSS_COLOR],
+        stroke: [CSS_COLOR],
+        'stroke-width': [CSS_LENGTH],
+        'stroke-dasharray': [CSS_DASH_ARRAY],
+        'font-size': [/^initial$/, CSS_LENGTH],
+      },
+    },
+    allowedSchemes: [],
+  });
+
+  const normalized = sanitized.replace(/\sviewbox=/g, ' viewBox=');
+  if (!PIKCHR_SVG_ROOT.test(normalized)) return null;
+  return normalized;
+}
diff --git a/apps/staged/src/types/sanitize-html.d.ts b/apps/staged/src/types/sanitize-html.d.ts
index 93270031..e4a2dfde 100644
--- a/apps/staged/src/types/sanitize-html.d.ts
+++ b/apps/staged/src/types/sanitize-html.d.ts
@@ -1,9 +1,11 @@
 declare module 'sanitize-html' {
   type AllowedAttributes = Record<string, string[]>;
+  type AllowedStyles = Record<string, Record<string, RegExp[]>>;
 
   interface SanitizeHtmlOptions {
     allowedTags?: string[];
     allowedAttributes?: AllowedAttributes;
+    allowedStyles?: AllowedStyles;
     allowedSchemes?: string[];
   }
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index eb82b215..35b0fecb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -201,6 +201,9 @@ importers:
       marked:
         specifier: ^17.0.1
         version: 17.0.3
+      pikchr-js:
+        specifier: 0.1.4
+        version: 0.1.4
       sanitize-html:
         specifier: ^2.17.0
         version: 2.17.1
@@ -2550,6 +2553,10 @@ packages:
     resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
     engines: {node: '>=12'}
 
+  pikchr-js@0.1.4:
+    resolution: {integrity: sha512-ojG1pgxv5SzjGNSp/wDhkgzPo5jnK5/ycXDMh5dv5AW3vf0vhh4z60yk2ZBOh6VVx5R8ZqjO0/Ejk015gCBaPw==}
+    hasBin: true
+
   pkg-types@1.3.1:
     resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
 
@@ -5518,6 +5525,8 @@ snapshots:
 
   picomatch@4.0.4: {}
 
+  pikchr-js@0.1.4: {}
+
   pkg-types@1.3.1:
     dependencies:
       confbox: 0.1.8

From 61969dd9a98d3be565a346585b98cefd6c04ba6e Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 24 Jun 2026 16:10:22 +1000
Subject: [PATCH 04/20] fix(notes): retry Pikchr renderer initialization

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../features/notes/pikchrRendering.test.ts    | 33 ++++++++++++++++++-
 .../src/lib/features/notes/pikchrRendering.ts |  4 +++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts b/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
index aeb2d9a3..69680e5c 100644
--- a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
 import { loadNotePikchrRenderer, sanitizePikchrSvg } from './pikchrRendering';
 
@@ -64,4 +64,35 @@ describe('loadNotePikchrRenderer', () => {
     expect(rendered.svg).not.toContain('<script');
     expect(rendered.svg).not.toContain('data-pikchr-date');
   });
+
+  it('retries loading after renderer initialization fails', async () => {
+    const loadPikchr = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('initialization failed'))
+      .mockResolvedValueOnce({
+        render: () => ({
+          width: 10,
+          height: 10,
+          svg: '<svg xmlns="http://www.w3.org/2000/svg" class="note-pikchr-svg" viewBox="0 0 10 10"><path d="M0,0L10,10" /></svg>',
+        }),
+      });
+
+    vi.resetModules();
+    vi.doMock('pikchr-js', () => ({ default: loadPikchr }));
+
+    try {
+      const { loadNotePikchrRenderer } = await import('./pikchrRendering');
+
+      await expect(loadNotePikchrRenderer()).rejects.toThrow('initialization failed');
+
+      const renderPikchr = await loadNotePikchrRenderer();
+      const rendered = renderPikchr('box "Retry" fit');
+
+      expect(loadPikchr).toHaveBeenCalledTimes(2);
+      expect(rendered).toMatchObject({ kind: 'svg', width: 10, height: 10 });
+    } finally {
+      vi.doUnmock('pikchr-js');
+      vi.resetModules();
+    }
+  });
 });
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.ts b/apps/staged/src/lib/features/notes/pikchrRendering.ts
index 2afd740f..d2a0beca 100644
--- a/apps/staged/src/lib/features/notes/pikchrRendering.ts
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.ts
@@ -33,6 +33,10 @@ export function loadNotePikchrRenderer(): Promise<NotePikchrRenderer> {
     .then(({ default: loadPikchr }) => loadPikchr())
     .then((pikchr) => {
       return (source: string) => renderPikchrSource(pikchr, source);
+    })
+    .catch((error) => {
+      rendererPromise = null;
+      throw error;
     });
   return rendererPromise;
 }

From 63cca6cbde8c9a991755c548ad4e52865ae79298 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 24 Jun 2026 18:01:55 +1000
Subject: [PATCH 05/20] fix(notes): retry Pikchr renderer on reopen

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src/lib/features/notes/NoteModal.svelte | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index cc1e3b22..95e78f8c 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -106,6 +106,12 @@
     };
   });
 
+  $effect(() => {
+    if (!open) {
+      pikchrRendererLoadFailed = false;
+    }
+  });
+
   onDestroy(() => {
     unregisterSearchTarget?.();
   });

From 021be57ffc9e7697f63de17217fc33cd05f5aad4 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 24 Jun 2026 18:05:14 +1000
Subject: [PATCH 06/20] fix(notes): keep diagram classes trusted-only

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../staged/src/lib/features/notes/noteMarkdown.test.ts | 10 ++++++++++
 apps/staged/src/lib/shared/sanitize.ts                 |  3 ---
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
index f5cbd1fb..173f0fef 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
@@ -77,6 +77,16 @@ describe('renderNoteMarkdown', () => {
     expect(html).not.toContain('<script>');
   });
 
+  it('does not allow raw HTML to opt into note diagram classes', () => {
+    const html = renderNoteMarkdown(
+      '<div class="note-diagram-preview"><figcaption class="note-diagram-caption">Pikchr</figcaption></div>'
+    );
+
+    expect(html).not.toContain('class="note-diagram-preview"');
+    expect(html).not.toContain('class="note-diagram-caption"');
+    expect(html).toContain('Pikchr');
+  });
+
   it('falls back to escaped source when the Pikchr renderer rejects the SVG', () => {
     const html = renderNoteMarkdown('```pikchr\nbox "Unsafe" fit\n```', {
       pikchrRenderer: unsafePikchrRenderer,
diff --git a/apps/staged/src/lib/shared/sanitize.ts b/apps/staged/src/lib/shared/sanitize.ts
index 4c287fa5..2ef08851 100644
--- a/apps/staged/src/lib/shared/sanitize.ts
+++ b/apps/staged/src/lib/shared/sanitize.ts
@@ -29,9 +29,6 @@ export function sanitize(dirty: string): string {
       th: ['align'],
       code: ['class'], // for syntax-highlight class names
       span: ['class'], // for syntax-highlight class names
-      div: ['class'],
-      figcaption: ['class'],
-      figure: ['class'],
       pre: ['class'],
     },
     // Only allow checkbox inputs (GFM task lists)

From ea2b98bc70467211d6015b784ee05accc30e8916 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Wed, 24 Jun 2026 18:44:19 +1000
Subject: [PATCH 07/20] fix(notes): improve Pikchr diagram previews

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src/app.css                       |  2 +
 .../src/lib/features/notes/NoteModal.svelte   |  2 +-
 .../features/notes/pikchrRendering.test.ts    | 19 ++++++
 .../src/lib/features/notes/pikchrRendering.ts | 62 ++++++++++++++++---
 apps/staged/src/lib/theme.ts                  | 11 ++++
 apps/staged/src/types/sanitize-html.d.ts      |  6 ++
 6 files changed, 93 insertions(+), 9 deletions(-)

diff --git a/apps/staged/src/app.css b/apps/staged/src/app.css
index 15778332..e491cc3d 100644
--- a/apps/staged/src/app.css
+++ b/apps/staged/src/app.css
@@ -90,6 +90,8 @@
   --ui-danger-bg: rgba(248, 81, 73, 0.1);
   --ui-selection: rgba(255, 255, 255, 0.08);
 
+  --diagram-canvas-bg: #ffffff;
+
   --scrollbar-thumb: #47424d;
   --scrollbar-thumb-hover: #5d5962;
   --scrollbar-thumb-transparent: rgba(255, 255, 255, 0.15);
diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index 95e78f8c..08908720 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -533,7 +533,7 @@
     display: flex;
     justify-content: center;
     padding: 16px;
-    background: var(--bg-elevated, var(--bg-hover));
+    background: var(--diagram-canvas-bg);
     overflow-x: auto;
   }
 
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts b/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
index 69680e5c..3b16b896 100644
--- a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
@@ -18,9 +18,28 @@ describe('sanitizePikchrSvg', () => {
     expect(svg).toContain('<path');
     expect(svg).toContain('style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0)"');
     expect(svg).toContain('<text');
+    expect(svg).toContain('fill="rgb(0,0,0)"');
     expect(svg).not.toContain('data-pikchr-date');
   });
 
+  it('keeps safe direct SVG colors and strips unsafe direct SVG colors', () => {
+    const svg = sanitizePikchrSvg(
+      [
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">',
+        '<path d="M1,1L19,19" fill="none" stroke="#123456" />',
+        '<text x="10" y="10" fill="rgb(1, 2, 3)" stroke="url(https://example.com/stroke)">Label</text>',
+        '<rect x="1" y="1" width="4" height="4" fill="url(https://example.com/fill)" stroke="rgba(12, 34, 56, 0.5)" />',
+        '</svg>',
+      ].join('')
+    );
+
+    expect(svg).toContain('fill="none"');
+    expect(svg).toContain('stroke="#123456"');
+    expect(svg).toContain('fill="rgb(1, 2, 3)"');
+    expect(svg).toContain('stroke="rgba(12, 34, 56, 0.5)"');
+    expect(svg).not.toContain('url(');
+  });
+
   it('strips executable and external-resource SVG surface', () => {
     const svg = sanitizePikchrSvg(
       [
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.ts b/apps/staged/src/lib/features/notes/pikchrRendering.ts
index d2a0beca..27ac1913 100644
--- a/apps/staged/src/lib/features/notes/pikchrRendering.ts
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.ts
@@ -11,6 +11,17 @@ const CSS_LENGTH = new RegExp(`^(?:${CSS_NUMBER})(?:px|pt|pc|mm|cm|in|em|rem|%)?
 const CSS_COLOR =
   /^(?:none|transparent|currentColor|[a-zA-Z]+|#[0-9a-fA-F]{3,8}|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}(?:\s*,\s*(?:0|1|0?\.\d+))?\s*\))$/;
 const CSS_DASH_ARRAY = new RegExp(`^(?:${CSS_NUMBER})(?:\\s*,\\s*(?:${CSS_NUMBER}))*$`);
+const DIRECT_COLOR_ATTRIBUTES = ['fill', 'stroke'] as const;
+const DIRECT_COLOR_ATTRIBUTE_TAGS = new Set([
+  'path',
+  'text',
+  'rect',
+  'circle',
+  'ellipse',
+  'line',
+  'polyline',
+  'polygon',
+]);
 
 export type RenderedPikchrDiagram =
   | {
@@ -89,14 +100,25 @@ export function sanitizePikchrSvg(svg: string): string | null {
     allowedAttributes: {
       svg: ['xmlns', 'viewBox', 'viewbox', 'class', 'style', 'width', 'height'],
       g: ['class', 'transform', 'style'],
-      path: ['class', 'd', 'style'],
-      text: ['class', 'x', 'y', 'dx', 'dy', 'text-anchor', 'dominant-baseline', 'style'],
-      rect: ['class', 'x', 'y', 'width', 'height', 'rx', 'ry', 'style'],
-      circle: ['class', 'cx', 'cy', 'r', 'style'],
-      ellipse: ['class', 'cx', 'cy', 'rx', 'ry', 'style'],
-      line: ['class', 'x1', 'y1', 'x2', 'y2', 'style'],
-      polyline: ['class', 'points', 'style'],
-      polygon: ['class', 'points', 'style'],
+      path: ['class', 'd', 'fill', 'stroke', 'style'],
+      text: [
+        'class',
+        'x',
+        'y',
+        'dx',
+        'dy',
+        'text-anchor',
+        'dominant-baseline',
+        'fill',
+        'stroke',
+        'style',
+      ],
+      rect: ['class', 'x', 'y', 'width', 'height', 'rx', 'ry', 'fill', 'stroke', 'style'],
+      circle: ['class', 'cx', 'cy', 'r', 'fill', 'stroke', 'style'],
+      ellipse: ['class', 'cx', 'cy', 'rx', 'ry', 'fill', 'stroke', 'style'],
+      line: ['class', 'x1', 'y1', 'x2', 'y2', 'fill', 'stroke', 'style'],
+      polyline: ['class', 'points', 'fill', 'stroke', 'style'],
+      polygon: ['class', 'points', 'fill', 'stroke', 'style'],
     },
     allowedStyles: {
       '*': {
@@ -108,9 +130,33 @@ export function sanitizePikchrSvg(svg: string): string | null {
       },
     },
     allowedSchemes: [],
+    transformTags: {
+      '*': stripUnsafeDirectColorAttributes,
+    },
   });
 
   const normalized = sanitized.replace(/\sviewbox=/g, ' viewBox=');
   if (!PIKCHR_SVG_ROOT.test(normalized)) return null;
   return normalized;
 }
+
+function stripUnsafeDirectColorAttributes(tagName: string, attribs: Record<string, string>) {
+  const nextAttribs = { ...attribs };
+  if (!DIRECT_COLOR_ATTRIBUTE_TAGS.has(tagName.toLowerCase())) {
+    return { tagName, attribs: nextAttribs };
+  }
+
+  for (const attribute of DIRECT_COLOR_ATTRIBUTES) {
+    const value = nextAttribs[attribute];
+    if (value === undefined) continue;
+
+    const trimmedValue = value.trim();
+    if (CSS_COLOR.test(trimmedValue)) {
+      nextAttribs[attribute] = trimmedValue;
+    } else {
+      delete nextAttribs[attribute];
+    }
+  }
+
+  return { tagName, attribs: nextAttribs };
+}
diff --git a/apps/staged/src/lib/theme.ts b/apps/staged/src/lib/theme.ts
index 315e7a1c..5a915d4f 100644
--- a/apps/staged/src/lib/theme.ts
+++ b/apps/staged/src/lib/theme.ts
@@ -88,6 +88,11 @@ export interface Theme {
     selection: string; // Selected items background (theme-derived)
   };
 
+  // Diagram previews
+  diagram: {
+    canvasBg: string; // Light canvas for rendered diagrams with default dark ink
+  };
+
   // Scrollbar
   scrollbar: {
     thumb: string;
@@ -468,6 +473,10 @@ export function createAdaptiveTheme(
       selection: overlay(syntaxFg, isDark ? 0.08 : 0.1),
     },
 
+    diagram: {
+      canvasBg: '#ffffff',
+    },
+
     scrollbar: {
       thumb: borderBase,
       thumbHover: mix(primaryBg, syntaxFg, 0.25),
@@ -560,6 +569,8 @@ export function themeToVarMap(t: Theme): Record<string, string> {
     '--ui-warning-bg': t.ui.warningBg,
     '--ui-selection': t.ui.selection,
 
+    '--diagram-canvas-bg': t.diagram.canvasBg,
+
     '--scrollbar-thumb': t.scrollbar.thumb,
     '--scrollbar-thumb-hover': t.scrollbar.thumbHover,
     '--scrollbar-thumb-transparent': t.scrollbar.thumbTransparent,
diff --git a/apps/staged/src/types/sanitize-html.d.ts b/apps/staged/src/types/sanitize-html.d.ts
index e4a2dfde..8eac0a4f 100644
--- a/apps/staged/src/types/sanitize-html.d.ts
+++ b/apps/staged/src/types/sanitize-html.d.ts
@@ -1,12 +1,18 @@
 declare module 'sanitize-html' {
   type AllowedAttributes = Record<string, string[]>;
   type AllowedStyles = Record<string, Record<string, RegExp[]>>;
+  type TagAttributes = Record<string, string>;
+  type TransformTag = (
+    tagName: string,
+    attribs: TagAttributes
+  ) => { tagName: string; attribs: TagAttributes; text?: string };
 
   interface SanitizeHtmlOptions {
     allowedTags?: string[];
     allowedAttributes?: AllowedAttributes;
     allowedStyles?: AllowedStyles;
     allowedSchemes?: string[];
+    transformTags?: Record<string, TransformTag>;
   }
 
   interface SanitizeHtmlFn {

From 495f13becaa11d2a90cbb0e9f7003c3b8f1418f5 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 11:17:10 +1000
Subject: [PATCH 08/20] fix(notes): remove non-Pikchr diagram formats

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../lib/features/notes/diagramFormats.test.ts | 30 +++++++++----------
 .../src/lib/features/notes/diagramFormats.ts  | 12 --------
 .../lib/features/notes/diagramRendering.ts    |  4 ---
 .../lib/features/notes/noteMarkdown.test.ts   | 12 ++++----
 4 files changed, 20 insertions(+), 38 deletions(-)

diff --git a/apps/staged/src/lib/features/notes/diagramFormats.test.ts b/apps/staged/src/lib/features/notes/diagramFormats.test.ts
index 47d80ae2..41aebfa8 100644
--- a/apps/staged/src/lib/features/notes/diagramFormats.test.ts
+++ b/apps/staged/src/lib/features/notes/diagramFormats.test.ts
@@ -9,23 +9,21 @@ import {
 } from './diagramFormats';
 
 describe('note diagram format registry', () => {
-  it('registers Pikchr as the recommended general diagram format', () => {
-    expect(NOTE_DIAGRAM_FORMATS).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          language: 'pikchr',
-          displayName: 'Pikchr',
-          role: 'general',
-          recommended: true,
-        }),
-      ])
-    );
+  it('registers only Pikchr as the recommended general diagram format', () => {
+    expect(NOTE_DIAGRAM_FORMATS).toEqual([
+      {
+        language: 'pikchr',
+        displayName: 'Pikchr',
+        role: 'general',
+        recommended: true,
+      },
+    ]);
   });
 
-  it('recognizes existing note diagram fence languages case-insensitively', () => {
+  it('recognizes Pikchr fence languages case-insensitively', () => {
     expect(getNoteDiagramFormat('PIKCHR')?.language).toBe('pikchr');
-    expect(getNoteDiagramFormat('mermaid')?.language).toBe('mermaid');
-    expect(getNoteDiagramFormat('svg')?.language).toBe('svg');
+    expect(getNoteDiagramFormat('mermaid')).toBeNull();
+    expect(getNoteDiagramFormat('svg')).toBeNull();
     expect(getNoteDiagramFormat('typescript')).toBeNull();
   });
 
@@ -65,12 +63,12 @@ describe('extractNoteDiagramFences', () => {
     ]);
   });
 
-  it('preserves Mermaid and SVG as recognized diagram formats', () => {
+  it('ignores Mermaid and SVG fences as ordinary code fences', () => {
     const diagrams = extractNoteDiagramFences(
       ['```mermaid', 'flowchart TD', '```', '~~~svg', '<svg></svg>', '~~~'].join('\n')
     );
 
-    expect(diagrams.map((diagram) => diagram.language)).toEqual(['mermaid', 'svg']);
+    expect(diagrams).toEqual([]);
   });
 
   it('ignores non-diagram fences while skipping their contents', () => {
diff --git a/apps/staged/src/lib/features/notes/diagramFormats.ts b/apps/staged/src/lib/features/notes/diagramFormats.ts
index 82441b5e..04554414 100644
--- a/apps/staged/src/lib/features/notes/diagramFormats.ts
+++ b/apps/staged/src/lib/features/notes/diagramFormats.ts
@@ -5,18 +5,6 @@ export const NOTE_DIAGRAM_FORMATS = [
     role: 'general',
     recommended: true,
   },
-  {
-    language: 'mermaid',
-    displayName: 'Mermaid',
-    role: 'compatibility',
-    recommended: false,
-  },
-  {
-    language: 'svg',
-    displayName: 'SVG',
-    role: 'fallback',
-    recommended: false,
-  },
 ] as const;
 
 export type NoteDiagramFormat = (typeof NOTE_DIAGRAM_FORMATS)[number];
diff --git a/apps/staged/src/lib/features/notes/diagramRendering.ts b/apps/staged/src/lib/features/notes/diagramRendering.ts
index 8767fa76..2e330900 100644
--- a/apps/staged/src/lib/features/notes/diagramRendering.ts
+++ b/apps/staged/src/lib/features/notes/diagramRendering.ts
@@ -22,10 +22,6 @@ export function renderNoteDiagramCodeBlock(
   if (!format) return null;
 
   const renderedDiagramSource = withDiagramSourceClass(renderedSource, format);
-  if (format.language !== 'pikchr') {
-    return { html: renderedDiagramSource, trustedHtml: false };
-  }
-
   const renderedPikchr = options.pikchrRenderer?.(token.text);
   if (!renderedPikchr || renderedPikchr.kind !== 'svg') {
     return { html: renderedDiagramSource, trustedHtml: false };
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
index 173f0fef..2f01b77c 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
@@ -42,13 +42,12 @@ describe('renderNoteMarkdown', () => {
     expect(html).not.toContain('note-diagram-source');
   });
 
-  it('preserves Mermaid fences as escaped diagram source blocks', () => {
+  it('leaves Mermaid fenced blocks as normal code blocks', () => {
     const html = renderNoteMarkdown('```mermaid\nflowchart TD\nA-->B\n```');
 
-    expect(html).toContain(
-      '<pre class="note-diagram-source note-diagram-source-mermaid"><code class="language-mermaid">'
-    );
+    expect(html).toContain('<pre><code class="language-mermaid">');
     expect(html).toContain('flowchart TD');
+    expect(html).not.toContain('note-diagram-source');
     expect(html).not.toContain('note-diagram-preview');
   });
 
@@ -99,11 +98,12 @@ describe('renderNoteMarkdown', () => {
     expect(html).not.toContain('onclick');
   });
 
-  it('keeps raw SVG fences escaped as source for now', () => {
+  it('leaves raw SVG fenced blocks as normal escaped code blocks', () => {
     const html = renderNoteMarkdown('```svg\n<svg><script>alert(1)</script></svg>\n```');
 
-    expect(html).toContain('note-diagram-source-svg');
+    expect(html).toContain('<pre><code class="language-svg">');
     expect(html).toContain('&lt;svg&gt;&lt;script&gt;alert(1)&lt;/script&gt;&lt;/svg&gt;');
+    expect(html).not.toContain('note-diagram-source');
     expect(html).not.toContain('<script>');
   });
 });

From e0c5d9d7305c1a4a7e77065a1ecc31bd4b75d417 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 12:44:20 +1000
Subject: [PATCH 09/20] feat(notes): include Pikchr grammar guidance

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../src-tauri/resources/pikchr/grammar.md     | 393 ++++++++++++++++++
 apps/staged/src-tauri/src/session_commands.rs | 130 +++++-
 apps/staged/src-tauri/src/web_server.rs       |   7 +-
 apps/staged/src-tauri/tauri.conf.json         |   3 +
 .../features/sessions/noteFreshness.test.ts   |   2 +
 .../lib/features/sessions/noteFreshness.ts    |   6 +
 6 files changed, 533 insertions(+), 8 deletions(-)
 create mode 100644 apps/staged/src-tauri/resources/pikchr/grammar.md

diff --git a/apps/staged/src-tauri/resources/pikchr/grammar.md b/apps/staged/src-tauri/resources/pikchr/grammar.md
new file mode 100644
index 00000000..09274984
--- /dev/null
+++ b/apps/staged/src-tauri/resources/pikchr/grammar.md
@@ -0,0 +1,393 @@
+<!--
+Source: https://pikchr.org/home/doc/trunk/doc/grammar.md
+Raw source: https://pikchr.org/home/raw/doc/grammar.md?ci=trunk
+Retrieved: 2026-06-25
+Upstream project: Pikchr
+License basis: Pikchr documentation states the source code is released under the 0-clause BSD license: https://pikchr.org/home/doc/trunk/homepage.md#source-code-license-0-clause-bsd
+-->
+
+# Pikchr Grammar
+
+This file describes the grammar of the input files to Pikchr.  Keywords
+and operators are shown in **bold**.  Non-terminal symbols are shown
+in *italic*.  Special token classes are shown in ALL-CAPS.  A grammar
+symbol followed by "*" means zero-or-more.  A grammar symbol
+followed by "?" means zero-or-one.  Parentheses are used for grouping.
+Two grammar symbols within "(..|..)" means one or the other.
+ Marks of the form
+"[&#9654;info](./grammar.md)" are links to more information and are
+not part of the grammar.
+
+The following special token classes are recognized:
+
+  *  NEWLINE  &rarr;  A un-escaped newline character, U+000A.
+     A backslash followed by zero or more whitespace characters
+     and then a U+000A character is interpreted as ordinary whitespace,
+     not as a NEWLINE.
+
+  *  LABEL  &rarr;  An object or place label starting with an
+     upper-case ASCII letter and continuing with zero or more
+     ASCII letters, digits, and/or underscores.  A LABEL always starts
+     with an upper-case letter.
+
+  *  VARIABLE  &rarr;  A variable name consisting of a lower-case
+     ASCII letter or "$" or "@" and followed by zero or more
+     ASCII letters, digits, and/or underscores.  VARIABLEs may
+     contain upper-case letters, but they never begin with an upper-case.
+     In this way, VARIABLEs are distinct from LABELs.
+
+  *  NUMBER  &rarr;  A numeric literal.  The value can be a decimal
+     integer, a floating point value, or a hexadecimal literal
+     starting with "0x".  Decimal and floating point values can
+     optionally be followed by a two-character unit designator that is
+     one of:  "in", "cm", "px", "pt", "pc", or "mm".  There can be
+     no whitespace in between the numeric portion of the constant and
+     the unit.
+
+  *  ORDINAL  &rarr;  A non-zero integer literal followed by one of the
+     suffixes "st", "nd", "rd", or "th".  Examples: "1st", "2nd",
+    "3rd", "4th", "5th", and so forth.   As a special case, "first"
+     is accepted as an alternative spelling of "1st".
+
+  *  STRING  &rarr;  A string literal that begins and ends with
+     double-quotes (U+0022).  Within the string literal, a double-quote
+     character can be escaped using backslash (U+005c).  A backslash
+     can also be used to escape a backslash.  No other escape sequences
+     are recognized and standalone backslashes are elided from the output.
+     Newlines are permitted in strings.
+
+  *  COLORNAME &rarr;  One of the 140 official HTML color names, in
+     any mixture of upper and lower cases.  The value of a COLORNAME is
+     an integer which is the 24-bit RGB value of that color.  Two
+     additional color names of "None" and "Off" are also recognized and
+     have a value of -1.
+
+  *  CODEBLOCK &rarr;   All tokens contained within nested {...}.  This
+     is only used as the body of a "define" statement.
+
+There are many non-terminals in the grammar, but a few are more important.
+If you are new to the Pikchr language, begin by focusing on these
+six:
+
+  *  *statement* &rarr;  A Pikchr script is just a list of statements.
+
+  *  *attribute* &rarr;  Each graphic object is configured with zero or
+     more attributes.
+
+  *  *object* &rarr;  A reference to a prior graphic object, or `this` to
+     refer to the current object.
+
+  *  *place* &rarr;  A specific point associated with an *object*.
+
+  *  *position* &rarr;  Any (2-D) point in space.  An (x,y) pair.
+
+  *  *expr* &rarr;  A scalar expression.
+
+
+A complete input file to Pikchr consists of a single *statement-list*.
+
+## *statement-list*: [&#9654;info](./stmtlist.md)
+
+  * *statement*?
+  * *statement-list* NEWLINE *statement*?
+  * *statement-list* **;** *statement*?
+
+## *statement*:  [&#9654;info](./stmt.md)
+  * *object-definition*
+  * LABEL **:** *object-definition*
+  * LABEL **:** *place*
+  * *direction*
+  * VARIABLE *assignment-op* *expr*
+  * **define** VARIABLE CODEBLOCK     [&#9654;info](./macro.md)
+  * **print** *print-argument* (**,** *print-argument*)\*
+  * **assert (** *expr* **==** *expr* **)**
+  * **assert (** *position* **==** *position* **)**
+
+
+## *direction*:
+  * **right**
+  * **down**
+  * **left**
+  * **up**
+
+## *assignment-op*:
+  * **=**
+  * **+=**
+  * **-=**
+  * **\*=**
+  * **/=**
+
+## *print-argument*:
+  * *expr*
+  * STRING
+
+## *object-definition*:
+  * *object-class* *attribute*\*
+  * STRING *text-attribute*\* *attribute*\*
+  * **[** *statement-list* **]** *attribute*\*
+
+## *object-class*:
+  * **arc**
+  * **arrow**
+  * **box**          [&#9654;info](./boxobj.md)
+  * **circle**       [&#9654;info](./circleobj.md)
+  * **cylinder**     [&#9654;info](./cylinderobj.md)
+  * **diamond**      [&#9654;info](./diamondobj.md)
+  * **dot**
+  * **ellipse**      [&#9654;info](./ellipseobj.md)
+  * **file**         [&#9654;info](./fileobj.md)
+  * **line**
+  * **move**
+  * **oval**         [&#9654;info](./ovalobj.md)
+  * **spline**
+  * **text**
+
+## *attribute*:
+  * *path-attribute*              [&#9654;info](./pathattr.md)
+  * *location-attribute*          [&#9654;info](./locattr.md)
+  * STRING *text-attribute*\*     [&#9654;info](./annotate.md)
+  * **same**
+  * **same as** *object*
+  * *numeric-property* *new-property-value*
+  * **dashed** *expr*?
+  * **dotted** *expr*?
+  * **color** *color-expr*
+  * **fill** *color-expr*
+  * **behind** *object*      [&#9654;info](./behind.md)
+  * **cw**
+  * **ccw**
+  * **&lt;-**                [&#9654;info](./arrowdir.md)
+  * **-&gt;**                [&#9654;info](./arrowdir.md)
+  * **&lt;-&gt;**            [&#9654;info](./arrowdir.md)
+  * **invis**|**invisible**  [&#9654;info](./invis.md)
+  * **thick**                [&#9654;info](./thickthin.md)
+  * **thin**                 [&#9654;info](./thickthin.md)
+  * **solid**                [&#9654;info](./thickthin.md)
+  * **chop**                 [&#9654;info](./chop.md)
+  * **fit**                  [&#9654;info](./fit.md)
+
+## *color-expr*: [&#9654;info](./colorexpr.md)
+  * *expr*
+
+## *new-property-value*:  [&#9654;info](./newpropval.md)
+  * *expr*
+  * *expr* **%**
+
+## *numeric-property*:  [&#9654;info](./numprop.md)
+  * **diameter**
+  * **ht**
+  * **height**
+  * **rad**
+  * **radius**
+  * **thickness**
+  * **width**
+  * **wid**
+
+## *text-attribute*:  [&#9654;info](./textattr.md)
+  * **above**
+  * **aligned**
+  * **below**
+  * **big**
+  * **bold**
+  * **mono**
+  * **monospace**
+  * **center**
+  * **italic**
+  * **ljust**
+  * **rjust**
+  * **small**
+
+## *path-attribute*:   [&#9654;info](./pathattr.md)
+  * **from** *position*
+  * **then**? **to** *position*
+  * **then**? **go**? *direction* *line-length*?
+  * **then**? **go**? *direction* **until**? **even with** *position*
+  * (**then**|**go**) *line-length*? **heading** *compass-angle*
+  * (**then**|**go**) *line-length*? *compass-direction*
+  * **close**
+
+## *line-length*:  [&#9654;info](./linelen.md)
+
+  * *expr*
+  * *expr* **%**
+
+## *compass-angle*:   [&#9654;info](./compassangle.md)
+
+  * *expr*
+
+## *compass-direction*:
+  * **n**
+  * **north**
+  * **ne**
+  * **e**
+  * **east**
+  * **se**
+  * **s**
+  * **south**
+  * **sw**
+  * **w**
+  * **west**
+  * **nw**
+
+## *location-attribute*: [&#9654;info](./locattr.md)
+  * **at** *position*
+  * **with** *edgename* **at** *position*
+  * **with** *dot-edgename* **at** *position*
+
+## *position*:  [&#9654;info](./position.md)
+
+  *  *expr* **,** *expr*
+  *  *place*
+  *  *place* **+** *expr* **,** *expr*
+  *  *place* **-** *expr* **,** *expr*
+  *  *place* **+ (** *expr* **,** *expr* **)**
+  *  *place* **- (** *expr* **,** *expr* **)**
+  *  **(** *position* **,** *position* **)**
+  *  **(** *position* **)**
+  *  *fraction* **of the way between** *position* **and** *position*
+  *  *fraction* **way between** *position* **and** *position*
+  *  *fraction* **between** *position* **and** *position*
+  *  *fraction* **<** *position* **,** *position* **>**
+  *  *distance* *which-way-from* *position*
+
+## *fraction*:
+  *  *expr*
+
+## *distance*
+  *  *expr*
+
+## *which-way-from*:
+
+  *  **above**
+  *  **below**
+  *  **right of**
+  *  **left of**
+  *  **n of**
+  *  **north of**
+  *  **ne of**
+  *  **e of**
+  *  **east of**
+  *  **se of**
+  *  **s of**
+  *  **south of**
+  *  **sw of**
+  *  **w of**
+  *  **west of**
+  *  **nw of**
+  *  **heading** *compass-angle* **from**
+
+## *place*:      [&#9654;info](./place.md)
+
+  *  *object*
+  *  *object* *dot-edgename*
+  *  *edgename* **of** *object*
+  *  ORDINAL **vertex of** *object*
+
+## *object*:
+
+  *  LABEL
+  *  *object* **.** LABEL
+  *  *nth-object* **of**|**in** *object*
+
+## *nth-object*:
+
+  *  ORDINAL *object-class*
+  *  ORDINAL **last** *object-class*
+  *  ORDINAL **previous** *object-class*
+  *  **last** *object-class*
+  *  **previous** *object-class*
+  *  **last**
+  *  **previous**
+  *  ORDINAL **[]**
+  *  ORDINAL **last []**
+  *  ORDINAL **previous []**
+  *  **last []**
+  *  **previous []**
+
+## *dot-edgename*:
+  * **.n**
+  * **.north**
+  * **.t**
+  * **.top**
+  * **.ne**
+  * **.e**
+  * **.east**
+  * **.right**
+  * **.se**
+  * **.s**
+  * **.south**
+  * **.bot**
+  * **.bottom**
+  * **.sw**
+  * **.w**
+  * **.west**
+  * **.left**
+  * **.nw**
+  * **.c**
+  * **.center**
+  * **.start**
+  * **.end**
+
+## *edgename*:
+  * **n**
+  * **north**
+  * **ne**
+  * **e**
+  * **east**
+  * **se**
+  * **s**
+  * **south**
+  * **sw**
+  * **w**
+  * **west**
+  * **nw**
+  * **t**
+  * **top**
+  * **bot**
+  * **bottom**
+  * **left**
+  * **right**
+  * **c**
+  * **center**
+  * **start**
+  * **end**
+
+
+## *expr*:
+
+  *  NUMBER
+  *  VARIABLE
+  *  COLORNAME
+  *  *place* **.x**
+  *  *place* **.y**
+  *  *object* *dot-property*
+  *  **(** *expr* **)**
+  *  *expr* **+** *expr*
+  *  *expr* **-** *expr*
+  *  *expr* **\*** *expr*
+  *  *expr* **/** *expr*
+  *  **-** *expr*
+  *  **+** *expr*
+  *  **abs (** *expr* **)**
+  *  **cos (** *expr* **)**
+  *  **dist (** *position* **,** *position* **)**
+  *  **int (** *expr* **)**
+  *  **max (** *expr* **,** *expr* **)**
+  *  **min (** *expr* **,** *expr* **)**
+  *  **sin (** *expr* **)**
+  *  **sqrt (** *expr* **)**
+
+## *dot-property*:
+
+  * **.color**
+  * **.dashed**
+  * **.diameter**
+  * **.dotted**
+  * **.fill**
+  * **.ht**
+  * **.height**
+  * **.rad**
+  * **.radius**
+  * **.thickness**
+  * **.wid**
+  * **.width**
diff --git a/apps/staged/src-tauri/src/session_commands.rs b/apps/staged/src-tauri/src/session_commands.rs
index 363e60ea..3fa7ded9 100644
--- a/apps/staged/src-tauri/src/session_commands.rs
+++ b/apps/staged/src-tauri/src/session_commands.rs
@@ -21,6 +21,8 @@ use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex, OnceLock};
 
 use serde::{Deserialize, Serialize};
+use tauri::path::BaseDirectory;
+use tauri::Manager;
 
 use crate::actions::{ActionExecutor, ActionRegistry};
 use crate::agent::{self, AcpProviderInfo};
@@ -29,6 +31,9 @@ use crate::git;
 use crate::session_runner::{self, SessionConfig};
 use crate::store::{self, Store};
 
+const PIKCHR_GRAMMAR_RESOURCE: &str = "resources/pikchr/grammar.md";
+pub(crate) const PIKCHR_GRAMMAR_URL: &str = "https://pikchr.org/home/doc/trunk/doc/grammar.md";
+
 // =============================================================================
 // Helper — duplicated from lib.rs to avoid circular deps. If this grows,
 // consider extracting a shared `state.rs`.
@@ -66,6 +71,36 @@ where
         .map_err(|e| e.to_string())
 }
 
+pub(crate) fn resolve_pikchr_grammar_reference(
+    app_handle: &tauri::AppHandle,
+    is_remote: bool,
+) -> String {
+    if !is_remote {
+        if let Ok(path) = app_handle
+            .path()
+            .resolve(PIKCHR_GRAMMAR_RESOURCE, BaseDirectory::Resource)
+        {
+            if path.is_file() {
+                return path.to_string_lossy().into_owned();
+            }
+        }
+
+        let source_path = Path::new(env!("CARGO_MANIFEST_DIR")).join(PIKCHR_GRAMMAR_RESOURCE);
+        if source_path.is_file() {
+            return source_path.to_string_lossy().into_owned();
+        }
+    }
+
+    PIKCHR_GRAMMAR_URL.to_string()
+}
+
+fn pikchr_note_guidance(reference: &str) -> String {
+    format!(
+        "Staged notes support rendered diagrams in fenced `pikchr` code blocks. \
+If you need the Pikchr grammar while writing a diagram, read the reference at: {reference}"
+    )
+}
+
 // =============================================================================
 // Provider discovery
 // =============================================================================
@@ -786,7 +821,10 @@ for example #note:123, #commit:<sha>, and #review:456. When starting a repo-leve
 note, do not paste or rewrite the note contents; reference the note and relevant section instead, \
 for example: `Implement \"Step 5: unit tests\" from #note:123`.";
 
-pub(crate) fn build_project_session_action_instructions(is_remote: bool) -> String {
+pub(crate) fn build_project_session_action_instructions_with_pikchr_reference(
+    is_remote: bool,
+    pikchr_grammar_reference: &str,
+) -> String {
     let preamble = if is_remote {
         "This top-level project session runs locally and acts as a coordinator. \
 For repository-specific execution, use MCP subagent tools.\n\n\
@@ -833,6 +871,8 @@ repository edits directly here; use `start_repo_session` for implementation work
         ""
     };
 
+    let pikchr_guidance = pikchr_note_guidance(pikchr_grammar_reference);
+
     format!(
         "The user is requesting work at the project level. Investigate and \
 fulfill the request below, then produce a project note summarizing what you found and any \
@@ -840,6 +880,7 @@ actions taken.\n\n\
 {preamble}\n\n\
 {start_repo_session_desc}\n\n\
 {PROJECT_SESSION_TIMELINE_REFERENCE_GUIDANCE}\n\n\
+{pikchr_guidance}\n\n\
 - add_project_repo: Use this when the task requires a repository that isn't yet in the \
 project. Pass the GitHub repo slug to add it.\n\n\
 IMPORTANT: `add_project_repo` and `start_repo_session` are MCP tools, not shell commands. \
@@ -885,7 +926,11 @@ pub async fn start_project_session(
     let project_context = build_project_session_context(&store, &project, None);
 
     let is_remote = project.location == store::ProjectLocation::Remote;
-    let action_instructions = build_project_session_action_instructions(is_remote);
+    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(&app_handle, is_remote);
+    let action_instructions = build_project_session_action_instructions_with_pikchr_reference(
+        is_remote,
+        &pikchr_grammar_reference,
+    );
 
     let full_prompt = format!(
         "<action>\n{action_instructions}\n\nProject information:\n{project_context}\n</action>\n\n{prompt}"
@@ -984,6 +1029,7 @@ fn resolve_branch_session_provider(
 #[allow(clippy::too_many_arguments)]
 async fn prepare_branch_session_start(
     store: &Arc<Store>,
+    app_handle: &tauri::AppHandle,
     branch_id: &str,
     prompt: &str,
     session_type: BranchSessionType,
@@ -1101,13 +1147,15 @@ async fn prepare_branch_session_start(
 
     // Build the full prompt with action instructions + project information + branch context.
     let project_information = build_project_context(store, &project, &branch);
-    let full_prompt = build_full_prompt(
+    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(app_handle, is_remote);
+    let full_prompt = build_full_prompt_with_pikchr_reference(
         prompt,
         &project_information,
         &branch_context,
         &session_type,
         launch_context,
         Some(&branch.base_branch),
+        &pikchr_grammar_reference,
     );
 
     // Resolve the actual workspace path for remote branches so the remote agent
@@ -1329,6 +1377,7 @@ pub async fn start_or_queue_branch_session_for_store(
 
     let prepared = prepare_branch_session_start(
         &store,
+        &app_handle,
         &branch_id,
         &prompt,
         session_type.clone(),
@@ -1667,13 +1716,15 @@ async fn start_queued_session_for_branch(
 
     // Build the full prompt with context.
     let project_information = build_project_context(&store, &project, &branch);
-    let full_prompt = build_full_prompt(
+    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(&app_handle, is_remote);
+    let full_prompt = build_full_prompt_with_pikchr_reference(
         &prompt,
         &project_information,
         &branch_context,
         &session_type,
         launch_context.as_ref(),
         Some(&branch.base_branch),
+        &pikchr_grammar_reference,
     );
 
     // Atomically transition session from queued to running.
@@ -3265,7 +3316,27 @@ pub(crate) fn build_full_prompt(
     launch_context: Option<&BranchSessionLaunchContext>,
     base_branch: Option<&str>,
 ) -> String {
-    let action_instructions = match session_type {
+    build_full_prompt_with_pikchr_reference(
+        user_prompt,
+        project_information,
+        branch_context,
+        session_type,
+        launch_context,
+        base_branch,
+        PIKCHR_GRAMMAR_URL,
+    )
+}
+
+pub(crate) fn build_full_prompt_with_pikchr_reference(
+    user_prompt: &str,
+    project_information: &str,
+    branch_context: &str,
+    session_type: &BranchSessionType,
+    launch_context: Option<&BranchSessionLaunchContext>,
+    base_branch: Option<&str>,
+    pikchr_grammar_reference: &str,
+) -> String {
+    let mut action_instructions = match session_type {
         BranchSessionType::Note => {
             "The user is requesting a note. Generate a note based on their prompt below.
 
@@ -3411,6 +3482,11 @@ Rules:\n\
         }
     };
 
+    if matches!(session_type, BranchSessionType::Note) {
+        action_instructions.push_str("\n\n");
+        action_instructions.push_str(&pikchr_note_guidance(pikchr_grammar_reference));
+    }
+
     let action_tag = format!(
         "<action>\n{action_instructions}\n\nProject information:\n{project_information}\n</action>"
     );
@@ -4113,20 +4189,60 @@ mod tests {
         assert!(!prompt.contains("repo session is taking a long time"));
     }
 
+    fn assert_pikchr_note_guidance(prompt: &str, reference: &str) {
+        assert!(prompt.contains("Staged notes support rendered diagrams"));
+        assert!(prompt.contains("fenced `pikchr` code blocks"));
+        assert!(prompt.contains("Pikchr grammar"));
+        assert!(prompt.contains(reference));
+    }
+
     #[test]
     fn local_project_session_prompt_includes_timeline_reference_guidance() {
-        let prompt = build_project_session_action_instructions(false);
+        let prompt = build_project_session_action_instructions_with_pikchr_reference(
+            false,
+            PIKCHR_GRAMMAR_URL,
+        );
 
         assert_project_session_reference_guidance(&prompt);
         assert_project_session_repo_session_progress_guidance(&prompt);
+        assert_pikchr_note_guidance(&prompt, PIKCHR_GRAMMAR_URL);
     }
 
     #[test]
     fn remote_project_session_prompt_includes_timeline_reference_guidance() {
-        let prompt = build_project_session_action_instructions(true);
+        let prompt = build_project_session_action_instructions_with_pikchr_reference(
+            true,
+            PIKCHR_GRAMMAR_URL,
+        );
 
         assert_project_session_reference_guidance(&prompt);
         assert_project_session_repo_session_progress_guidance(&prompt);
+        assert_pikchr_note_guidance(&prompt, PIKCHR_GRAMMAR_URL);
+    }
+
+    #[test]
+    fn project_session_prompt_uses_supplied_pikchr_reference() {
+        let prompt = build_project_session_action_instructions_with_pikchr_reference(
+            false,
+            "/tmp/staged/pikchr/grammar.md",
+        );
+
+        assert_pikchr_note_guidance(&prompt, "/tmp/staged/pikchr/grammar.md");
+    }
+
+    #[test]
+    fn note_prompt_uses_supplied_pikchr_reference() {
+        let prompt = build_full_prompt_with_pikchr_reference(
+            "user prompt",
+            "project info",
+            "branch context",
+            &BranchSessionType::Note,
+            None,
+            None,
+            "/tmp/staged/pikchr/grammar.md",
+        );
+
+        assert_pikchr_note_guidance(&prompt, "/tmp/staged/pikchr/grammar.md");
     }
 
     #[test]
diff --git a/apps/staged/src-tauri/src/web_server.rs b/apps/staged/src-tauri/src/web_server.rs
index 7b634349..779da3f3 100644
--- a/apps/staged/src-tauri/src/web_server.rs
+++ b/apps/staged/src-tauri/src/web_server.rs
@@ -2908,8 +2908,13 @@ async fn dispatch(command: &str, args: Value, state: &WebAppState) -> Result<Val
                 session_commands::build_project_session_context(&store, &project, None);
 
             let is_remote = project.location == store::ProjectLocation::Remote;
+            let pikchr_grammar_reference =
+                session_commands::resolve_pikchr_grammar_reference(&app_handle, is_remote);
             let action_instructions =
-                session_commands::build_project_session_action_instructions(is_remote);
+                session_commands::build_project_session_action_instructions_with_pikchr_reference(
+                    is_remote,
+                    &pikchr_grammar_reference,
+                );
 
             let full_prompt = format!(
                 "<action>\n{action_instructions}\n\nProject information:\n{project_context}\n</action>\n\n{prompt}"
diff --git a/apps/staged/src-tauri/tauri.conf.json b/apps/staged/src-tauri/tauri.conf.json
index d588456f..a632f8d2 100644
--- a/apps/staged/src-tauri/tauri.conf.json
+++ b/apps/staged/src-tauri/tauri.conf.json
@@ -43,6 +43,9 @@
       "icons/icon.icns",
       "icons/icon.ico"
     ],
+    "resources": [
+      "resources/pikchr/grammar.md"
+    ],
     "macOS": {
       "infoPlist": "Info.plist"
     }
diff --git a/apps/staged/src/lib/features/sessions/noteFreshness.test.ts b/apps/staged/src/lib/features/sessions/noteFreshness.test.ts
index a0c471ee..b3001840 100644
--- a/apps/staged/src/lib/features/sessions/noteFreshness.test.ts
+++ b/apps/staged/src/lib/features/sessions/noteFreshness.test.ts
@@ -133,6 +133,8 @@ describe('note freshness', () => {
     expect(updateMessage).toContain('```suggested-next-steps');
     expect(updateMessage).toContain('\n---\n# <Title>');
     expect(updateMessage).toContain('Please update the note to reflect the latest chat.');
+    expect(updateMessage).toContain('fenced `pikchr` code blocks');
+    expect(updateMessage).toContain('https://pikchr.org/home/doc/trunk/doc/grammar.md');
     expect(writeMessage).toContain('Please write the note for this session.');
   });
 
diff --git a/apps/staged/src/lib/features/sessions/noteFreshness.ts b/apps/staged/src/lib/features/sessions/noteFreshness.ts
index 414c74de..eccf0b04 100644
--- a/apps/staged/src/lib/features/sessions/noteFreshness.ts
+++ b/apps/staged/src/lib/features/sessions/noteFreshness.ts
@@ -1,5 +1,9 @@
 import type { Session, SessionMessage } from '../../types';
 
+const PIKCHR_GRAMMAR_URL = 'https://pikchr.org/home/doc/trunk/doc/grammar.md';
+
+const PIKCHR_NOTE_GUIDANCE = `Staged notes support rendered diagrams in fenced \`pikchr\` code blocks. If you need the Pikchr grammar while writing a diagram, read the reference at: ${PIKCHR_GRAMMAR_URL}`;
+
 export interface LinkedNoteContext {
   id: string;
   title: string;
@@ -105,6 +109,8 @@ The user is asking you to ${hasParsedNote ? 'update the linked note' : 'write th
 
 Use the existing conversation context. Do not create commits.
 
+${PIKCHR_NOTE_GUIDANCE}
+
 Your final response must include a suggested-next-steps fenced block followed by the note content after a horizontal rule:
 
 \`\`\`suggested-next-steps

From 6467c44b69d255312b9dbc8835b3c5021bbdbf7c Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 13:33:29 +1000
Subject: [PATCH 10/20] fix(notes): hide rendered Pikchr source

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src/lib/features/notes/NoteModal.svelte    | 10 ----------
 apps/staged/src/lib/features/notes/diagramRendering.ts |  8 ++------
 .../staged/src/lib/features/notes/noteMarkdown.test.ts |  7 ++++---
 3 files changed, 6 insertions(+), 19 deletions(-)

diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index 08908720..cdf79715 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -543,16 +543,6 @@
     height: auto;
   }
 
-  .markdown-content :global(.note-diagram-source-wrap) {
-    border-top: 1px solid var(--border-subtle);
-  }
-
-  .markdown-content :global(.note-diagram .note-diagram-source) {
-    margin: 0;
-    border-radius: 0;
-    background: transparent;
-  }
-
   .markdown-content :global(blockquote) {
     margin: 0.5em 0;
     padding-left: 0.75em;
diff --git a/apps/staged/src/lib/features/notes/diagramRendering.ts b/apps/staged/src/lib/features/notes/diagramRendering.ts
index 2e330900..0bef2061 100644
--- a/apps/staged/src/lib/features/notes/diagramRendering.ts
+++ b/apps/staged/src/lib/features/notes/diagramRendering.ts
@@ -1,6 +1,5 @@
 import type { Tokens } from 'marked';
 
-import { sanitize } from '../../shared/sanitize';
 import { getNoteDiagramFormat, type NoteDiagramFormat } from './diagramFormats';
 import { sanitizePikchrSvg, type NotePikchrRenderer } from './pikchrRendering';
 
@@ -32,7 +31,7 @@ export function renderNoteDiagramCodeBlock(
   }
 
   return {
-    html: renderPikchrPreview(sanitize(renderedDiagramSource), renderedSvg),
+    html: renderPikchrPreview(renderedSvg),
     trustedHtml: true,
   };
 }
@@ -44,16 +43,13 @@ function withDiagramSourceClass(renderedSource: string, format: NoteDiagramForma
   );
 }
 
-function renderPikchrPreview(renderedSource: string, renderedSvg: string): string {
+function renderPikchrPreview(renderedSvg: string): string {
   return [
     '<figure class="note-diagram note-diagram-pikchr">',
     '<figcaption class="note-diagram-caption">Pikchr</figcaption>',
     '<div class="note-diagram-preview note-diagram-preview-pikchr">',
     renderedSvg,
     '</div>',
-    '<div class="note-diagram-source-wrap">',
-    renderedSource,
-    '</div>',
     '</figure>',
   ].join('');
 }
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
index 2f01b77c..199d93b6 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
@@ -63,9 +63,10 @@ describe('renderNoteMarkdown', () => {
     expect(html).toContain('class="note-pikchr-svg"');
     expect(html).toContain('<path');
     expect(html).toContain('stroke:rgb(0,0,0)');
-    expect(html).toContain('<div class="note-diagram-source-wrap">');
-    expect(html).toContain('<pre class="note-diagram-source note-diagram-source-pikchr">');
-    expect(html).toContain('box "Start" fit');
+    expect(html).not.toContain('note-diagram-source-wrap');
+    expect(html).not.toContain('note-diagram-source-pikchr');
+    expect(html).not.toContain('box "Start" fit');
+    expect(html).not.toContain('box &quot;Start&quot; fit');
     expect(html).not.toContain('STAGED_NOTE_TRUSTED_DIAGRAM_');
   });
 

From 5f15e4092e73c9aef39380bc38f210670260426e Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 13:40:17 +1000
Subject: [PATCH 11/20] fix(notes): add spacing for Pikchr labels

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../src/lib/features/notes/NoteModal.svelte   |  4 +++
 .../features/notes/pikchrRendering.test.ts    | 26 +++++++++++++++++++
 .../src/lib/features/notes/pikchrRendering.ts | 25 +++++++++++++++++-
 3 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index cdf79715..0d9b3c0f 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -543,6 +543,10 @@
     height: auto;
   }
 
+  .markdown-content :global(.note-diagram-preview-pikchr .note-pikchr-svg) {
+    overflow: visible;
+  }
+
   .markdown-content :global(blockquote) {
     margin: 0.5em 0;
     padding-left: 0.75em;
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts b/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
index 3b16b896..55d843ba 100644
--- a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
@@ -40,6 +40,32 @@ describe('sanitizePikchrSvg', () => {
     expect(svg).not.toContain('url(');
   });
 
+  it('adds breathing room to side-anchored Pikchr text labels', () => {
+    const svg = sanitizePikchrSvg(
+      [
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 80">',
+        '<text x="20" y="20" text-anchor="start">Right-side label</text>',
+        '<text x="20" y="40" text-anchor="end">Left-side label</text>',
+        '<text x="20" y="60" text-anchor="start" dx="1em">Custom label</text>',
+        '<text x="60" y="20" text-anchor="middle">Centered label</text>',
+        '</svg>',
+      ].join('')
+    );
+
+    expect(svg).toMatch(
+      /<text\b(?=[^>]*text-anchor="start")(?=[^>]*dx="0\.35em")[^>]*>Right-side label<\/text>/
+    );
+    expect(svg).toMatch(
+      /<text\b(?=[^>]*text-anchor="end")(?=[^>]*dx="-0\.35em")[^>]*>Left-side label<\/text>/
+    );
+    expect(svg).toMatch(
+      /<text\b(?=[^>]*text-anchor="start")(?=[^>]*dx="1em")[^>]*>Custom label<\/text>/
+    );
+    expect(svg).toMatch(
+      /<text\b(?=[^>]*text-anchor="middle")(?![^>]*\bdx=)[^>]*>Centered label<\/text>/
+    );
+  });
+
   it('strips executable and external-resource SVG surface', () => {
     const svg = sanitizePikchrSvg(
       [
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.ts b/apps/staged/src/lib/features/notes/pikchrRendering.ts
index 27ac1913..0be0216b 100644
--- a/apps/staged/src/lib/features/notes/pikchrRendering.ts
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.ts
@@ -5,6 +5,7 @@ const PIKCHR_SVG_CLASS = 'note-pikchr-svg';
 const MAX_PIKCHR_SOURCE_LENGTH = 20_000;
 const MAX_PIKCHR_SVG_LENGTH = 250_000;
 const PIKCHR_SVG_ROOT = /^\s*<svg[\s>]/i;
+const PIKCHR_SIDE_LABEL_GAP = '0.35em';
 
 const CSS_NUMBER = String.raw`[-+]?(?:\d+(?:\.\d+)?|\.\d+)(?:e[-+]?\d+)?`;
 const CSS_LENGTH = new RegExp(`^(?:${CSS_NUMBER})(?:px|pt|pc|mm|cm|in|em|rem|%)?$`);
@@ -131,7 +132,7 @@ export function sanitizePikchrSvg(svg: string): string | null {
     },
     allowedSchemes: [],
     transformTags: {
-      '*': stripUnsafeDirectColorAttributes,
+      '*': normalizePikchrSvgAttributes,
     },
   });
 
@@ -140,6 +141,28 @@ export function sanitizePikchrSvg(svg: string): string | null {
   return normalized;
 }
 
+function normalizePikchrSvgAttributes(tagName: string, attribs: Record<string, string>) {
+  const colorNormalized = stripUnsafeDirectColorAttributes(tagName, attribs);
+  if (tagName.toLowerCase() !== 'text') return colorNormalized;
+
+  return {
+    tagName,
+    attribs: addSideLabelGap(colorNormalized.attribs),
+  };
+}
+
+function addSideLabelGap(attribs: Record<string, string>) {
+  if (attribs.dx !== undefined) return attribs;
+
+  const anchor = attribs['text-anchor']?.trim().toLowerCase();
+  if (anchor !== 'start' && anchor !== 'end') return attribs;
+
+  return {
+    ...attribs,
+    dx: anchor === 'start' ? PIKCHR_SIDE_LABEL_GAP : `-${PIKCHR_SIDE_LABEL_GAP}`,
+  };
+}
+
 function stripUnsafeDirectColorAttributes(tagName: string, attribs: Record<string, string>) {
   const nextAttribs = { ...attribs };
   if (!DIRECT_COLOR_ATTRIBUTE_TAGS.has(tagName.toLowerCase())) {

From d0e678700f476f6a0cdc0307d08cefc36e1742ae Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 14:06:21 +1000
Subject: [PATCH 12/20] fix(notes): remove Pikchr diagram captions

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src/lib/features/notes/NoteModal.svelte  | 12 ------------
 .../src/lib/features/notes/diagramRendering.ts       |  1 -
 .../src/lib/features/notes/noteMarkdown.test.ts      |  2 +-
 3 files changed, 1 insertion(+), 14 deletions(-)

diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index 0d9b3c0f..7d8787eb 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -517,18 +517,6 @@
     background: var(--bg-primary);
   }
 
-  .markdown-content :global(.note-diagram-caption) {
-    display: flex;
-    align-items: center;
-    min-height: 30px;
-    padding: 0 10px;
-    border-bottom: 1px solid var(--border-subtle);
-    color: var(--text-secondary);
-    background: var(--bg-chrome);
-    font-size: var(--size-xs);
-    font-weight: 600;
-  }
-
   .markdown-content :global(.note-diagram-preview) {
     display: flex;
     justify-content: center;
diff --git a/apps/staged/src/lib/features/notes/diagramRendering.ts b/apps/staged/src/lib/features/notes/diagramRendering.ts
index 0bef2061..f1ef1829 100644
--- a/apps/staged/src/lib/features/notes/diagramRendering.ts
+++ b/apps/staged/src/lib/features/notes/diagramRendering.ts
@@ -46,7 +46,6 @@ function withDiagramSourceClass(renderedSource: string, format: NoteDiagramForma
 function renderPikchrPreview(renderedSvg: string): string {
   return [
     '<figure class="note-diagram note-diagram-pikchr">',
-    '<figcaption class="note-diagram-caption">Pikchr</figcaption>',
     '<div class="note-diagram-preview note-diagram-preview-pikchr">',
     renderedSvg,
     '</div>',
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
index 199d93b6..76f1f716 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
@@ -57,7 +57,7 @@ describe('renderNoteMarkdown', () => {
     });
 
     expect(html).toContain('<figure class="note-diagram note-diagram-pikchr">');
-    expect(html).toContain('<figcaption class="note-diagram-caption">Pikchr</figcaption>');
+    expect(html).not.toContain('note-diagram-caption');
     expect(html).toContain('<div class="note-diagram-preview note-diagram-preview-pikchr">');
     expect(html).toContain('<svg');
     expect(html).toContain('class="note-pikchr-svg"');

From 356a1e926d491253701c6035618d21fae2ce6a2d Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 14:20:16 +1000
Subject: [PATCH 13/20] fix(notes): retry Pikchr renderer on note change

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src/lib/features/notes/NoteModal.svelte | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index 7d8787eb..73683cbf 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -106,6 +106,12 @@
     };
   });
 
+  $effect(() => {
+    // Keep transient renderer import failures scoped to the note that hit them.
+    noteMarkdown;
+    pikchrRendererLoadFailed = false;
+  });
+
   $effect(() => {
     if (!open) {
       pikchrRendererLoadFailed = false;

From 19b918f8c8f44a2c49d8d4263b2d5e47d0986e52 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 15:13:49 +1000
Subject: [PATCH 14/20] feat(markdown): share Pikchr diagram renderer

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../src/lib/features/notes/NoteModal.svelte   |  54 ++---
 .../src/lib/features/notes/diagramFormats.ts  | 106 ++--------
 .../lib/features/notes/diagramRendering.ts    |  59 +-----
 .../lib/features/notes/noteMarkdown.test.ts   |  97 +--------
 .../src/lib/features/notes/noteMarkdown.ts    |  72 +------
 .../src/lib/features/notes/pikchrRendering.ts | 194 +-----------------
 .../lib/features/sessions/SessionModal.svelte |  50 ++++-
 .../markdown}/diagramFormats.test.ts          |  38 ++--
 .../src/lib/shared/markdown/diagramFormats.ts |  94 +++++++++
 .../lib/shared/markdown/diagramRendering.ts   |  54 +++++
 .../src/lib/shared/markdown/diagramStyles.css |  25 +++
 .../markdown}/pikchrRendering.test.ts         |  18 +-
 .../lib/shared/markdown/pikchrRendering.ts    | 185 +++++++++++++++++
 .../shared/markdown/renderMarkdown.test.ts    | 107 ++++++++++
 .../src/lib/shared/markdown/renderMarkdown.ts |  70 +++++++
 15 files changed, 654 insertions(+), 569 deletions(-)
 rename apps/staged/src/lib/{features/notes => shared/markdown}/diagramFormats.test.ts (66%)
 create mode 100644 apps/staged/src/lib/shared/markdown/diagramFormats.ts
 create mode 100644 apps/staged/src/lib/shared/markdown/diagramRendering.ts
 create mode 100644 apps/staged/src/lib/shared/markdown/diagramStyles.css
 rename apps/staged/src/lib/{features/notes => shared/markdown}/pikchrRendering.test.ts (86%)
 create mode 100644 apps/staged/src/lib/shared/markdown/pikchrRendering.ts
 create mode 100644 apps/staged/src/lib/shared/markdown/renderMarkdown.test.ts
 create mode 100644 apps/staged/src/lib/shared/markdown/renderMarkdown.ts

diff --git a/apps/staged/src/lib/features/notes/NoteModal.svelte b/apps/staged/src/lib/features/notes/NoteModal.svelte
index 73683cbf..ee485569 100644
--- a/apps/staged/src/lib/features/notes/NoteModal.svelte
+++ b/apps/staged/src/lib/features/notes/NoteModal.svelte
@@ -19,9 +19,10 @@
   import { highlightMatches, clearHighlights, scrollToMatch } from '../../shared/textHighlight';
   import { registerSearchShortcutTarget } from '../keyboard/searchTargets';
   import { viewport } from '../../shared/viewport.svelte';
-  import { extractNoteDiagramFences } from './diagramFormats';
+  import '../../shared/markdown/diagramStyles.css';
+  import { extractMarkdownDiagramFences } from '../../shared/markdown/diagramFormats';
+  import { loadPikchrRenderer, type PikchrRenderer } from '../../shared/markdown/pikchrRendering';
   import { noteMarkdownWithTitle, renderNoteMarkdown } from './noteMarkdown';
-  import { loadNotePikchrRenderer, type NotePikchrRenderer } from './pikchrRendering';
 
   interface Props {
     open: boolean;
@@ -57,10 +58,12 @@
   let showChatInfo = $derived(canOpenSession && assistantMessagesAfterNote > 0);
   let noteMarkdown = $derived(noteMarkdownWithTitle(title, content));
   let noteHasPikchr = $derived(
-    extractNoteDiagramFences(noteMarkdown).some((diagram) => diagram.language === 'pikchr')
+    extractMarkdownDiagramFences(noteMarkdown).some((diagram) => diagram.language === 'pikchr')
   );
-  let pikchrRenderer = $state<NotePikchrRenderer | null>(null);
-  let pikchrRendererLoadFailed = $state(false);
+  let pikchrRenderer = $state<PikchrRenderer | null>(null);
+  let pikchrRendererLoadKey = $derived(noteMarkdown);
+  let pikchrRendererLoadFailedKey = $state<string | null>(null);
+  let pikchrRendererLoadFailed = $derived(pikchrRendererLoadFailedKey === pikchrRendererLoadKey);
   let renderedNoteHtml = $derived(renderNoteMarkdown(noteMarkdown, { pikchrRenderer }));
 
   // Search state
@@ -92,13 +95,14 @@
   $effect(() => {
     if (!open || !noteHasPikchr || pikchrRenderer || pikchrRendererLoadFailed) return;
 
+    const loadKey = pikchrRendererLoadKey;
     let stale = false;
-    loadNotePikchrRenderer()
+    loadPikchrRenderer()
       .then((renderer) => {
-        if (!stale) pikchrRenderer = renderer;
+        if (!stale && pikchrRendererLoadKey === loadKey) pikchrRenderer = renderer;
       })
       .catch(() => {
-        if (!stale) pikchrRendererLoadFailed = true;
+        if (!stale && pikchrRendererLoadKey === loadKey) pikchrRendererLoadFailedKey = loadKey;
       });
 
     return () => {
@@ -106,15 +110,9 @@
     };
   });
 
-  $effect(() => {
-    // Keep transient renderer import failures scoped to the note that hit them.
-    noteMarkdown;
-    pikchrRendererLoadFailed = false;
-  });
-
   $effect(() => {
     if (!open) {
-      pikchrRendererLoadFailed = false;
+      pikchrRendererLoadFailedKey = null;
     }
   });
 
@@ -515,32 +513,6 @@
     font-size: 0.85em;
   }
 
-  .markdown-content :global(.note-diagram) {
-    margin: 0.9em 0;
-    border: 1px solid var(--border-subtle);
-    border-radius: 8px;
-    overflow: hidden;
-    background: var(--bg-primary);
-  }
-
-  .markdown-content :global(.note-diagram-preview) {
-    display: flex;
-    justify-content: center;
-    padding: 16px;
-    background: var(--diagram-canvas-bg);
-    overflow-x: auto;
-  }
-
-  .markdown-content :global(.note-diagram-preview svg) {
-    display: block;
-    max-width: 100%;
-    height: auto;
-  }
-
-  .markdown-content :global(.note-diagram-preview-pikchr .note-pikchr-svg) {
-    overflow: visible;
-  }
-
   .markdown-content :global(blockquote) {
     margin: 0.5em 0;
     padding-left: 0.75em;
diff --git a/apps/staged/src/lib/features/notes/diagramFormats.ts b/apps/staged/src/lib/features/notes/diagramFormats.ts
index 04554414..13d9ccb2 100644
--- a/apps/staged/src/lib/features/notes/diagramFormats.ts
+++ b/apps/staged/src/lib/features/notes/diagramFormats.ts
@@ -1,94 +1,12 @@
-export const NOTE_DIAGRAM_FORMATS = [
-  {
-    language: 'pikchr',
-    displayName: 'Pikchr',
-    role: 'general',
-    recommended: true,
-  },
-] as const;
-
-export type NoteDiagramFormat = (typeof NOTE_DIAGRAM_FORMATS)[number];
-export type NoteDiagramLanguage = NoteDiagramFormat['language'];
-
-export interface NoteDiagramFence {
-  format: NoteDiagramFormat;
-  language: NoteDiagramLanguage;
-  infoString: string;
-  source: string;
-  startLine: number;
-  endLine: number | null;
-}
-
-const FORMATS_BY_LANGUAGE = new Map<NoteDiagramLanguage, NoteDiagramFormat>(
-  NOTE_DIAGRAM_FORMATS.map((format) => [format.language, format])
-);
-
-export function normalizeDiagramFenceLanguage(
-  infoString: string | null | undefined
-): string | null {
-  const language = infoString?.trim().split(/\s+/, 1)[0]?.toLowerCase();
-  return language || null;
-}
-
-export function getNoteDiagramFormat(
-  infoString: string | null | undefined
-): NoteDiagramFormat | null {
-  const language = normalizeDiagramFenceLanguage(infoString);
-  if (!language) return null;
-
-  return FORMATS_BY_LANGUAGE.get(language as NoteDiagramLanguage) ?? null;
-}
-
-export function isNoteDiagramFormat(infoString: string | null | undefined): boolean {
-  return getNoteDiagramFormat(infoString) !== null;
-}
-
-export function extractNoteDiagramFences(markdown: string): NoteDiagramFence[] {
-  const lines = markdown.split(/\r\n|\n|\r/);
-  const diagrams: NoteDiagramFence[] = [];
-
-  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
-    const opening = lines[lineIndex].match(/^ {0,3}(`{3,}|~{3,})([^\n]*)$/);
-    if (!opening) continue;
-
-    const openingFence = opening[1];
-    const fenceChar = openingFence[0];
-    const fenceLength = openingFence.length;
-    const infoString = opening[2].trim();
-    const contentStart = lineIndex + 1;
-    let closingLineIndex: number | null = null;
-
-    for (
-      let candidateLineIndex = contentStart;
-      candidateLineIndex < lines.length;
-      candidateLineIndex++
-    ) {
-      if (isClosingFence(lines[candidateLineIndex], fenceChar, fenceLength)) {
-        closingLineIndex = candidateLineIndex;
-        break;
-      }
-    }
-
-    const contentEnd = closingLineIndex ?? lines.length;
-    const format = getNoteDiagramFormat(infoString);
-    if (format) {
-      diagrams.push({
-        format,
-        language: format.language,
-        infoString,
-        source: lines.slice(contentStart, contentEnd).join('\n'),
-        startLine: lineIndex + 1,
-        endLine: closingLineIndex === null ? null : closingLineIndex + 1,
-      });
-    }
-
-    lineIndex = closingLineIndex ?? lines.length;
-  }
-
-  return diagrams;
-}
-
-function isClosingFence(line: string, fenceChar: string, fenceLength: number): boolean {
-  const escapedFenceChar = fenceChar === '`' ? '`' : '\\~';
-  return new RegExp(`^ {0,3}${escapedFenceChar}{${fenceLength},}[ \\t]*$`).test(line);
-}
+export {
+  extractMarkdownDiagramFences as extractNoteDiagramFences,
+  getMarkdownDiagramFormat as getNoteDiagramFormat,
+  isMarkdownDiagramFormat as isNoteDiagramFormat,
+  MARKDOWN_DIAGRAM_FORMATS as NOTE_DIAGRAM_FORMATS,
+  normalizeDiagramFenceLanguage,
+} from '../../shared/markdown/diagramFormats';
+export type {
+  MarkdownDiagramFence as NoteDiagramFence,
+  MarkdownDiagramFormat as NoteDiagramFormat,
+  MarkdownDiagramLanguage as NoteDiagramLanguage,
+} from '../../shared/markdown/diagramFormats';
diff --git a/apps/staged/src/lib/features/notes/diagramRendering.ts b/apps/staged/src/lib/features/notes/diagramRendering.ts
index f1ef1829..33aa304d 100644
--- a/apps/staged/src/lib/features/notes/diagramRendering.ts
+++ b/apps/staged/src/lib/features/notes/diagramRendering.ts
@@ -1,54 +1,5 @@
-import type { Tokens } from 'marked';
-
-import { getNoteDiagramFormat, type NoteDiagramFormat } from './diagramFormats';
-import { sanitizePikchrSvg, type NotePikchrRenderer } from './pikchrRendering';
-
-export interface NoteDiagramRenderingOptions {
-  pikchrRenderer?: NotePikchrRenderer | null;
-}
-
-export interface RenderedNoteDiagramCodeBlock {
-  html: string;
-  trustedHtml: boolean;
-}
-
-export function renderNoteDiagramCodeBlock(
-  token: Tokens.Code,
-  renderedSource: string,
-  options: NoteDiagramRenderingOptions = {}
-): RenderedNoteDiagramCodeBlock | null {
-  const format = getNoteDiagramFormat(token.lang);
-  if (!format) return null;
-
-  const renderedDiagramSource = withDiagramSourceClass(renderedSource, format);
-  const renderedPikchr = options.pikchrRenderer?.(token.text);
-  if (!renderedPikchr || renderedPikchr.kind !== 'svg') {
-    return { html: renderedDiagramSource, trustedHtml: false };
-  }
-  const renderedSvg = sanitizePikchrSvg(renderedPikchr.svg);
-  if (!renderedSvg) {
-    return { html: renderedDiagramSource, trustedHtml: false };
-  }
-
-  return {
-    html: renderPikchrPreview(renderedSvg),
-    trustedHtml: true,
-  };
-}
-
-function withDiagramSourceClass(renderedSource: string, format: NoteDiagramFormat): string {
-  return renderedSource.replace(
-    '<pre>',
-    `<pre class="note-diagram-source note-diagram-source-${format.language}">`
-  );
-}
-
-function renderPikchrPreview(renderedSvg: string): string {
-  return [
-    '<figure class="note-diagram note-diagram-pikchr">',
-    '<div class="note-diagram-preview note-diagram-preview-pikchr">',
-    renderedSvg,
-    '</div>',
-    '</figure>',
-  ].join('');
-}
+export { renderMarkdownDiagramCodeBlock as renderNoteDiagramCodeBlock } from '../../shared/markdown/diagramRendering';
+export type {
+  MarkdownDiagramRenderingOptions as NoteDiagramRenderingOptions,
+  RenderedMarkdownDiagramCodeBlock as RenderedNoteDiagramCodeBlock,
+} from '../../shared/markdown/diagramRendering';
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
index 76f1f716..cee12ef2 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.test.ts
@@ -1,7 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
 import { noteMarkdownWithTitle, renderNoteMarkdown } from './noteMarkdown';
-import type { NotePikchrRenderer } from './pikchrRendering';
 
 describe('noteMarkdownWithTitle', () => {
   it('prepends the note title as a markdown H1', () => {
@@ -26,102 +25,10 @@ describe('noteMarkdownWithTitle', () => {
 });
 
 describe('renderNoteMarkdown', () => {
-  it('renders Pikchr fenced blocks as escaped source while the renderer is unavailable', () => {
+  it('uses the shared markdown renderer', () => {
     const html = renderNoteMarkdown('```pikchr\nbox "Start" fit\n```');
 
-    expect(html).toContain('<pre class="note-diagram-source note-diagram-source-pikchr">');
+    expect(html).toContain('<pre class="markdown-diagram-source markdown-diagram-source-pikchr">');
     expect(html).toContain('box "Start" fit');
-    expect(html).not.toContain('<svg');
-    expect(html).not.toContain('note-diagram-preview');
   });
-
-  it('leaves non-diagram fenced blocks as normal code blocks', () => {
-    const html = renderNoteMarkdown('```ts\nconst value = 1;\n```');
-
-    expect(html).toContain('<pre><code class="language-ts">');
-    expect(html).not.toContain('note-diagram-source');
-  });
-
-  it('leaves Mermaid fenced blocks as normal code blocks', () => {
-    const html = renderNoteMarkdown('```mermaid\nflowchart TD\nA-->B\n```');
-
-    expect(html).toContain('<pre><code class="language-mermaid">');
-    expect(html).toContain('flowchart TD');
-    expect(html).not.toContain('note-diagram-source');
-    expect(html).not.toContain('note-diagram-preview');
-  });
-
-  it('renders Pikchr fenced blocks as sanitized SVG when a renderer is loaded', () => {
-    const html = renderNoteMarkdown('```pikchr\nbox "Start" fit\n```', {
-      pikchrRenderer: safePikchrRenderer,
-    });
-
-    expect(html).toContain('<figure class="note-diagram note-diagram-pikchr">');
-    expect(html).not.toContain('note-diagram-caption');
-    expect(html).toContain('<div class="note-diagram-preview note-diagram-preview-pikchr">');
-    expect(html).toContain('<svg');
-    expect(html).toContain('class="note-pikchr-svg"');
-    expect(html).toContain('<path');
-    expect(html).toContain('stroke:rgb(0,0,0)');
-    expect(html).not.toContain('note-diagram-source-wrap');
-    expect(html).not.toContain('note-diagram-source-pikchr');
-    expect(html).not.toContain('box "Start" fit');
-    expect(html).not.toContain('box &quot;Start&quot; fit');
-    expect(html).not.toContain('STAGED_NOTE_TRUSTED_DIAGRAM_');
-  });
-
-  it('does not allow renderer SVG through the generic Markdown sanitizer', () => {
-    const html = renderNoteMarkdown('<svg><script>alert(1)</script></svg>');
-
-    expect(html).not.toContain('<svg');
-    expect(html).not.toContain('<script>');
-  });
-
-  it('does not allow raw HTML to opt into note diagram classes', () => {
-    const html = renderNoteMarkdown(
-      '<div class="note-diagram-preview"><figcaption class="note-diagram-caption">Pikchr</figcaption></div>'
-    );
-
-    expect(html).not.toContain('class="note-diagram-preview"');
-    expect(html).not.toContain('class="note-diagram-caption"');
-    expect(html).toContain('Pikchr');
-  });
-
-  it('falls back to escaped source when the Pikchr renderer rejects the SVG', () => {
-    const html = renderNoteMarkdown('```pikchr\nbox "Unsafe" fit\n```', {
-      pikchrRenderer: unsafePikchrRenderer,
-    });
-
-    expect(html).toContain('<pre class="note-diagram-source note-diagram-source-pikchr">');
-    expect(html).toContain('box "Unsafe" fit');
-    expect(html).not.toContain('<svg');
-    expect(html).not.toContain('<script>');
-    expect(html).not.toContain('onclick');
-  });
-
-  it('leaves raw SVG fenced blocks as normal escaped code blocks', () => {
-    const html = renderNoteMarkdown('```svg\n<svg><script>alert(1)</script></svg>\n```');
-
-    expect(html).toContain('<pre><code class="language-svg">');
-    expect(html).toContain('&lt;svg&gt;&lt;script&gt;alert(1)&lt;/script&gt;&lt;/svg&gt;');
-    expect(html).not.toContain('note-diagram-source');
-    expect(html).not.toContain('<script>');
-  });
-});
-
-const safePikchrRenderer: NotePikchrRenderer = () => ({
-  kind: 'svg',
-  width: 58,
-  height: 34,
-  svg: [
-    '<svg xmlns="http://www.w3.org/2000/svg" class="note-pikchr-svg" viewBox="0 0 58 34">',
-    '<path d="M2,32L56,32L56,2L2,2Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />',
-    '<text x="29" y="17" text-anchor="middle" fill="rgb(0,0,0)" dominant-baseline="central">Start</text>',
-    '</svg>',
-  ].join(''),
-});
-
-const unsafePikchrRenderer: NotePikchrRenderer = () => ({
-  kind: 'error',
-  message: 'Pikchr rendered unsafe SVG.',
 });
diff --git a/apps/staged/src/lib/features/notes/noteMarkdown.ts b/apps/staged/src/lib/features/notes/noteMarkdown.ts
index 727219ee..32c688c1 100644
--- a/apps/staged/src/lib/features/notes/noteMarkdown.ts
+++ b/apps/staged/src/lib/features/notes/noteMarkdown.ts
@@ -1,14 +1,7 @@
-import { marked, Renderer, type Tokens } from 'marked';
-
-import { sanitize } from '../../shared/sanitize';
-import { renderNoteDiagramCodeBlock, type NoteDiagramRenderingOptions } from './diagramRendering';
-
-interface TrustedHtmlReplacement {
-  placeholder: string;
-  html: string;
-}
-
-let fallbackPlaceholderSequence = 0;
+import {
+  renderMarkdown,
+  type MarkdownRenderingOptions,
+} from '../../shared/markdown/renderMarkdown';
 
 export function noteMarkdownWithTitle(title: string, content: string): string {
   const normalizedTitle = title.trim();
@@ -25,59 +18,6 @@ function startsWithMarkdownH1(content: string): boolean {
   return /^#[ \t]+\S/.test(content);
 }
 
-export function renderNoteMarkdown(
-  text: string,
-  options: NoteDiagramRenderingOptions = {}
-): string {
-  const trustedHtml: TrustedHtmlReplacement[] = [];
-  const renderedMarkdown = sanitize(
-    marked.parse(text, {
-      breaks: true,
-      gfm: true,
-      renderer: createNoteMarkdownRenderer(options, trustedHtml),
-    }) as string
-  );
-
-  return restoreTrustedHtml(renderedMarkdown, trustedHtml);
-}
-
-function createNoteMarkdownRenderer(
-  options: NoteDiagramRenderingOptions,
-  trustedHtml: TrustedHtmlReplacement[]
-): Renderer {
-  const renderer = new Renderer();
-  const renderCode = renderer.code.bind(renderer);
-
-  renderer.code = (token: Tokens.Code) => {
-    const rendered = renderCode(token);
-    const diagram = renderNoteDiagramCodeBlock(token, rendered, options);
-    if (!diagram) return rendered;
-    if (!diagram.trustedHtml) return diagram.html;
-
-    return stashTrustedHtml(diagram.html, trustedHtml);
-  };
-
-  return renderer;
-}
-
-function stashTrustedHtml(html: string, trustedHtml: TrustedHtmlReplacement[]): string {
-  const placeholder = `STAGED_NOTE_TRUSTED_DIAGRAM_${trustedHtml.length}_${createPlaceholderNonce()}`;
-  trustedHtml.push({ placeholder, html });
-  return placeholder;
-}
-
-function restoreTrustedHtml(
-  renderedMarkdown: string,
-  trustedHtml: TrustedHtmlReplacement[]
-): string {
-  return trustedHtml.reduce((html, replacement) => {
-    return html.replaceAll(replacement.placeholder, replacement.html);
-  }, renderedMarkdown);
-}
-
-function createPlaceholderNonce(): string {
-  const randomUuid = globalThis.crypto?.randomUUID?.();
-  if (randomUuid) return randomUuid.replaceAll('-', '_');
-
-  return `${Date.now().toString(36)}_${fallbackPlaceholderSequence++}`;
+export function renderNoteMarkdown(text: string, options: MarkdownRenderingOptions = {}): string {
+  return renderMarkdown(text, options);
 }
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.ts b/apps/staged/src/lib/features/notes/pikchrRendering.ts
index 0be0216b..50f86349 100644
--- a/apps/staged/src/lib/features/notes/pikchrRendering.ts
+++ b/apps/staged/src/lib/features/notes/pikchrRendering.ts
@@ -1,185 +1,9 @@
-import type { Pikchr } from 'pikchr-js';
-import sanitizeHtml from 'sanitize-html';
-
-const PIKCHR_SVG_CLASS = 'note-pikchr-svg';
-const MAX_PIKCHR_SOURCE_LENGTH = 20_000;
-const MAX_PIKCHR_SVG_LENGTH = 250_000;
-const PIKCHR_SVG_ROOT = /^\s*<svg[\s>]/i;
-const PIKCHR_SIDE_LABEL_GAP = '0.35em';
-
-const CSS_NUMBER = String.raw`[-+]?(?:\d+(?:\.\d+)?|\.\d+)(?:e[-+]?\d+)?`;
-const CSS_LENGTH = new RegExp(`^(?:${CSS_NUMBER})(?:px|pt|pc|mm|cm|in|em|rem|%)?$`);
-const CSS_COLOR =
-  /^(?:none|transparent|currentColor|[a-zA-Z]+|#[0-9a-fA-F]{3,8}|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}(?:\s*,\s*(?:0|1|0?\.\d+))?\s*\))$/;
-const CSS_DASH_ARRAY = new RegExp(`^(?:${CSS_NUMBER})(?:\\s*,\\s*(?:${CSS_NUMBER}))*$`);
-const DIRECT_COLOR_ATTRIBUTES = ['fill', 'stroke'] as const;
-const DIRECT_COLOR_ATTRIBUTE_TAGS = new Set([
-  'path',
-  'text',
-  'rect',
-  'circle',
-  'ellipse',
-  'line',
-  'polyline',
-  'polygon',
-]);
-
-export type RenderedPikchrDiagram =
-  | {
-      kind: 'svg';
-      svg: string;
-      width: number;
-      height: number;
-    }
-  | {
-      kind: 'error';
-      message: string;
-    };
-
-export type NotePikchrRenderer = (source: string) => RenderedPikchrDiagram;
-
-let rendererPromise: Promise<NotePikchrRenderer> | null = null;
-
-export function loadNotePikchrRenderer(): Promise<NotePikchrRenderer> {
-  rendererPromise ??= import('pikchr-js')
-    .then(({ default: loadPikchr }) => loadPikchr())
-    .then((pikchr) => {
-      return (source: string) => renderPikchrSource(pikchr, source);
-    })
-    .catch((error) => {
-      rendererPromise = null;
-      throw error;
-    });
-  return rendererPromise;
-}
-
-export function renderPikchrSource(pikchr: Pikchr, source: string): RenderedPikchrDiagram {
-  if (source.length > MAX_PIKCHR_SOURCE_LENGTH) {
-    return { kind: 'error', message: 'Pikchr source is too large to render safely.' };
-  }
-
-  try {
-    const rendered = pikchr.render(source, PIKCHR_SVG_CLASS);
-    if (rendered.width < 0 || rendered.height < 0 || !PIKCHR_SVG_ROOT.test(rendered.svg)) {
-      return { kind: 'error', message: 'Pikchr could not render this diagram.' };
-    }
-
-    const svg = sanitizePikchrSvg(rendered.svg);
-    if (!svg) {
-      return { kind: 'error', message: 'Pikchr rendered unsafe SVG.' };
-    }
-
-    return {
-      kind: 'svg',
-      svg,
-      width: rendered.width,
-      height: rendered.height,
-    };
-  } catch {
-    return { kind: 'error', message: 'Pikchr could not render this diagram.' };
-  }
-}
-
-export function sanitizePikchrSvg(svg: string): string | null {
-  if (svg.length > MAX_PIKCHR_SVG_LENGTH || !PIKCHR_SVG_ROOT.test(svg)) {
-    return null;
-  }
-
-  const sanitized = sanitizeHtml(svg, {
-    allowedTags: [
-      'svg',
-      'g',
-      'path',
-      'text',
-      'rect',
-      'circle',
-      'ellipse',
-      'line',
-      'polyline',
-      'polygon',
-    ],
-    allowedAttributes: {
-      svg: ['xmlns', 'viewBox', 'viewbox', 'class', 'style', 'width', 'height'],
-      g: ['class', 'transform', 'style'],
-      path: ['class', 'd', 'fill', 'stroke', 'style'],
-      text: [
-        'class',
-        'x',
-        'y',
-        'dx',
-        'dy',
-        'text-anchor',
-        'dominant-baseline',
-        'fill',
-        'stroke',
-        'style',
-      ],
-      rect: ['class', 'x', 'y', 'width', 'height', 'rx', 'ry', 'fill', 'stroke', 'style'],
-      circle: ['class', 'cx', 'cy', 'r', 'fill', 'stroke', 'style'],
-      ellipse: ['class', 'cx', 'cy', 'rx', 'ry', 'fill', 'stroke', 'style'],
-      line: ['class', 'x1', 'y1', 'x2', 'y2', 'fill', 'stroke', 'style'],
-      polyline: ['class', 'points', 'fill', 'stroke', 'style'],
-      polygon: ['class', 'points', 'fill', 'stroke', 'style'],
-    },
-    allowedStyles: {
-      '*': {
-        fill: [CSS_COLOR],
-        stroke: [CSS_COLOR],
-        'stroke-width': [CSS_LENGTH],
-        'stroke-dasharray': [CSS_DASH_ARRAY],
-        'font-size': [/^initial$/, CSS_LENGTH],
-      },
-    },
-    allowedSchemes: [],
-    transformTags: {
-      '*': normalizePikchrSvgAttributes,
-    },
-  });
-
-  const normalized = sanitized.replace(/\sviewbox=/g, ' viewBox=');
-  if (!PIKCHR_SVG_ROOT.test(normalized)) return null;
-  return normalized;
-}
-
-function normalizePikchrSvgAttributes(tagName: string, attribs: Record<string, string>) {
-  const colorNormalized = stripUnsafeDirectColorAttributes(tagName, attribs);
-  if (tagName.toLowerCase() !== 'text') return colorNormalized;
-
-  return {
-    tagName,
-    attribs: addSideLabelGap(colorNormalized.attribs),
-  };
-}
-
-function addSideLabelGap(attribs: Record<string, string>) {
-  if (attribs.dx !== undefined) return attribs;
-
-  const anchor = attribs['text-anchor']?.trim().toLowerCase();
-  if (anchor !== 'start' && anchor !== 'end') return attribs;
-
-  return {
-    ...attribs,
-    dx: anchor === 'start' ? PIKCHR_SIDE_LABEL_GAP : `-${PIKCHR_SIDE_LABEL_GAP}`,
-  };
-}
-
-function stripUnsafeDirectColorAttributes(tagName: string, attribs: Record<string, string>) {
-  const nextAttribs = { ...attribs };
-  if (!DIRECT_COLOR_ATTRIBUTE_TAGS.has(tagName.toLowerCase())) {
-    return { tagName, attribs: nextAttribs };
-  }
-
-  for (const attribute of DIRECT_COLOR_ATTRIBUTES) {
-    const value = nextAttribs[attribute];
-    if (value === undefined) continue;
-
-    const trimmedValue = value.trim();
-    if (CSS_COLOR.test(trimmedValue)) {
-      nextAttribs[attribute] = trimmedValue;
-    } else {
-      delete nextAttribs[attribute];
-    }
-  }
-
-  return { tagName, attribs: nextAttribs };
-}
+export {
+  loadPikchrRenderer as loadNotePikchrRenderer,
+  renderPikchrSource,
+  sanitizePikchrSvg,
+} from '../../shared/markdown/pikchrRendering';
+export type {
+  PikchrRenderer as NotePikchrRenderer,
+  RenderedPikchrDiagram,
+} from '../../shared/markdown/pikchrRendering';
diff --git a/apps/staged/src/lib/features/sessions/SessionModal.svelte b/apps/staged/src/lib/features/sessions/SessionModal.svelte
index 2b6d789f..d22e0615 100644
--- a/apps/staged/src/lib/features/sessions/SessionModal.svelte
+++ b/apps/staged/src/lib/features/sessions/SessionModal.svelte
@@ -42,8 +42,6 @@
   import ImagePlus from '@lucide/svelte/icons/image-plus';
   import Plus from '@lucide/svelte/icons/plus';
   import Spinner from '../../shared/Spinner.svelte';
-  import { marked } from 'marked';
-  import { sanitize } from '../../shared/sanitize';
   import { isResumableReason } from '../../types';
   import type { Session, SessionMessage, HashtagItem, ProjectRepo } from '../../types';
   import {
@@ -92,15 +90,16 @@
   import { highlightMatches, clearHighlights, scrollToMatch } from '../../shared/textHighlight';
   import { registerSearchShortcutTarget } from '../keyboard/searchTargets';
   import { viewport } from '../../shared/viewport.svelte';
+  import '../../shared/markdown/diagramStyles.css';
+  import { extractMarkdownDiagramFences } from '../../shared/markdown/diagramFormats';
+  import { renderMarkdown as renderSharedMarkdown } from '../../shared/markdown/renderMarkdown';
+  import { loadPikchrRenderer, type PikchrRenderer } from '../../shared/markdown/pikchrRendering';
   import {
     buildNoteFollowupMessage,
     getNoteFollowupLabel,
     type LinkedNoteContext,
   } from './noteFreshness';
 
-  // Configure marked
-  marked.setOptions({ breaks: true, gfm: true });
-
   interface Props {
     open: boolean;
     sessionId: string;
@@ -156,6 +155,21 @@
   let isLive = $derived(session?.status === 'running');
   let hasQueuedMessages = $derived(messageQueue.length > 0);
   let noteFollowupLabel = $derived(getNoteFollowupLabel(session, messages, noteInfo));
+  let assistantMarkdownContent = $derived(
+    messages
+      .filter((message) => message.role === 'assistant')
+      .map((message) => message.content)
+      .join('\n\n')
+  );
+  let sessionHasPikchr = $derived(
+    extractMarkdownDiagramFences(assistantMarkdownContent).some(
+      (diagram) => diagram.language === 'pikchr'
+    )
+  );
+  let pikchrRenderer = $state<PikchrRenderer | null>(null);
+  let pikchrRendererLoadKey = $derived(`${sessionId}\0${assistantMarkdownContent}`);
+  let pikchrRendererLoadFailedKey = $state<string | null>(null);
+  let pikchrRendererLoadFailed = $derived(pikchrRendererLoadFailedKey === pikchrRendererLoadKey);
 
   const SLIDE_DURATION = 150;
 
@@ -721,7 +735,7 @@
   }
 
   function renderMarkdown(content: string): string {
-    return sanitize(marked.parse(content) as string);
+    return renderSharedMarkdown(content, { pikchrRenderer });
   }
 
   /** Memoized wrapper around the shared renderHashtagTokens. */
@@ -903,6 +917,30 @@
     }
   });
 
+  $effect(() => {
+    if (!open || !sessionHasPikchr || pikchrRenderer || pikchrRendererLoadFailed) return;
+
+    const loadKey = pikchrRendererLoadKey;
+    let stale = false;
+    loadPikchrRenderer()
+      .then((renderer) => {
+        if (!stale && pikchrRendererLoadKey === loadKey) pikchrRenderer = renderer;
+      })
+      .catch(() => {
+        if (!stale && pikchrRendererLoadKey === loadKey) pikchrRendererLoadFailedKey = loadKey;
+      });
+
+    return () => {
+      stale = true;
+    };
+  });
+
+  $effect(() => {
+    if (!open) {
+      pikchrRendererLoadFailedKey = null;
+    }
+  });
+
   function requestClose() {
     if (closed) return;
     closed = true;
diff --git a/apps/staged/src/lib/features/notes/diagramFormats.test.ts b/apps/staged/src/lib/shared/markdown/diagramFormats.test.ts
similarity index 66%
rename from apps/staged/src/lib/features/notes/diagramFormats.test.ts
rename to apps/staged/src/lib/shared/markdown/diagramFormats.test.ts
index 41aebfa8..387f069e 100644
--- a/apps/staged/src/lib/features/notes/diagramFormats.test.ts
+++ b/apps/staged/src/lib/shared/markdown/diagramFormats.test.ts
@@ -1,16 +1,16 @@
 import { describe, expect, it } from 'vitest';
 
 import {
-  extractNoteDiagramFences,
-  getNoteDiagramFormat,
-  isNoteDiagramFormat,
-  NOTE_DIAGRAM_FORMATS,
+  extractMarkdownDiagramFences,
+  getMarkdownDiagramFormat,
+  isMarkdownDiagramFormat,
+  MARKDOWN_DIAGRAM_FORMATS,
   normalizeDiagramFenceLanguage,
 } from './diagramFormats';
 
-describe('note diagram format registry', () => {
+describe('markdown diagram format registry', () => {
   it('registers only Pikchr as the recommended general diagram format', () => {
-    expect(NOTE_DIAGRAM_FORMATS).toEqual([
+    expect(MARKDOWN_DIAGRAM_FORMATS).toEqual([
       {
         language: 'pikchr',
         displayName: 'Pikchr',
@@ -21,10 +21,10 @@ describe('note diagram format registry', () => {
   });
 
   it('recognizes Pikchr fence languages case-insensitively', () => {
-    expect(getNoteDiagramFormat('PIKCHR')?.language).toBe('pikchr');
-    expect(getNoteDiagramFormat('mermaid')).toBeNull();
-    expect(getNoteDiagramFormat('svg')).toBeNull();
-    expect(getNoteDiagramFormat('typescript')).toBeNull();
+    expect(getMarkdownDiagramFormat('PIKCHR')?.language).toBe('pikchr');
+    expect(getMarkdownDiagramFormat('mermaid')).toBeNull();
+    expect(getMarkdownDiagramFormat('svg')).toBeNull();
+    expect(getMarkdownDiagramFormat('typescript')).toBeNull();
   });
 
   it('normalizes the first token from a fence info string', () => {
@@ -32,15 +32,15 @@ describe('note diagram format registry', () => {
     expect(normalizeDiagramFenceLanguage('')).toBeNull();
   });
 
-  it('reports whether a fence language is a known note diagram format', () => {
-    expect(isNoteDiagramFormat('pikchr')).toBe(true);
-    expect(isNoteDiagramFormat('rust')).toBe(false);
+  it('reports whether a fence language is a known markdown diagram format', () => {
+    expect(isMarkdownDiagramFormat('pikchr')).toBe(true);
+    expect(isMarkdownDiagramFormat('rust')).toBe(false);
   });
 });
 
-describe('extractNoteDiagramFences', () => {
+describe('extractMarkdownDiagramFences', () => {
   it('extracts Pikchr fence metadata and source', () => {
-    const diagrams = extractNoteDiagramFences(
+    const diagrams = extractMarkdownDiagramFences(
       [
         '# Note',
         '',
@@ -64,7 +64,7 @@ describe('extractNoteDiagramFences', () => {
   });
 
   it('ignores Mermaid and SVG fences as ordinary code fences', () => {
-    const diagrams = extractNoteDiagramFences(
+    const diagrams = extractMarkdownDiagramFences(
       ['```mermaid', 'flowchart TD', '```', '~~~svg', '<svg></svg>', '~~~'].join('\n')
     );
 
@@ -72,7 +72,7 @@ describe('extractNoteDiagramFences', () => {
   });
 
   it('ignores non-diagram fences while skipping their contents', () => {
-    const diagrams = extractNoteDiagramFences(
+    const diagrams = extractMarkdownDiagramFences(
       ['```ts', 'const sample = "```pikchr";', '```', '```pikchr', 'box "Done" fit', '```'].join(
         '\n'
       )
@@ -82,8 +82,8 @@ describe('extractNoteDiagramFences', () => {
     expect(diagrams[0].source).toBe('box "Done" fit');
   });
 
-  it('handles an unclosed diagram fence through the end of the note', () => {
-    const diagrams = extractNoteDiagramFences(
+  it('handles an unclosed diagram fence through the end of markdown', () => {
+    const diagrams = extractMarkdownDiagramFences(
       ['Before', '```pikchr', 'box "Draft" fit'].join('\n')
     );
 
diff --git a/apps/staged/src/lib/shared/markdown/diagramFormats.ts b/apps/staged/src/lib/shared/markdown/diagramFormats.ts
new file mode 100644
index 00000000..844a0ffb
--- /dev/null
+++ b/apps/staged/src/lib/shared/markdown/diagramFormats.ts
@@ -0,0 +1,94 @@
+export const MARKDOWN_DIAGRAM_FORMATS = [
+  {
+    language: 'pikchr',
+    displayName: 'Pikchr',
+    role: 'general',
+    recommended: true,
+  },
+] as const;
+
+export type MarkdownDiagramFormat = (typeof MARKDOWN_DIAGRAM_FORMATS)[number];
+export type MarkdownDiagramLanguage = MarkdownDiagramFormat['language'];
+
+export interface MarkdownDiagramFence {
+  format: MarkdownDiagramFormat;
+  language: MarkdownDiagramLanguage;
+  infoString: string;
+  source: string;
+  startLine: number;
+  endLine: number | null;
+}
+
+const FORMATS_BY_LANGUAGE = new Map<MarkdownDiagramLanguage, MarkdownDiagramFormat>(
+  MARKDOWN_DIAGRAM_FORMATS.map((format) => [format.language, format])
+);
+
+export function normalizeDiagramFenceLanguage(
+  infoString: string | null | undefined
+): string | null {
+  const language = infoString?.trim().split(/\s+/, 1)[0]?.toLowerCase();
+  return language || null;
+}
+
+export function getMarkdownDiagramFormat(
+  infoString: string | null | undefined
+): MarkdownDiagramFormat | null {
+  const language = normalizeDiagramFenceLanguage(infoString);
+  if (!language) return null;
+
+  return FORMATS_BY_LANGUAGE.get(language as MarkdownDiagramLanguage) ?? null;
+}
+
+export function isMarkdownDiagramFormat(infoString: string | null | undefined): boolean {
+  return getMarkdownDiagramFormat(infoString) !== null;
+}
+
+export function extractMarkdownDiagramFences(markdown: string): MarkdownDiagramFence[] {
+  const lines = markdown.split(/\r\n|\n|\r/);
+  const diagrams: MarkdownDiagramFence[] = [];
+
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const opening = lines[lineIndex].match(/^ {0,3}(`{3,}|~{3,})([^\n]*)$/);
+    if (!opening) continue;
+
+    const openingFence = opening[1];
+    const fenceChar = openingFence[0];
+    const fenceLength = openingFence.length;
+    const infoString = opening[2].trim();
+    const contentStart = lineIndex + 1;
+    let closingLineIndex: number | null = null;
+
+    for (
+      let candidateLineIndex = contentStart;
+      candidateLineIndex < lines.length;
+      candidateLineIndex++
+    ) {
+      if (isClosingFence(lines[candidateLineIndex], fenceChar, fenceLength)) {
+        closingLineIndex = candidateLineIndex;
+        break;
+      }
+    }
+
+    const contentEnd = closingLineIndex ?? lines.length;
+    const format = getMarkdownDiagramFormat(infoString);
+    if (format) {
+      diagrams.push({
+        format,
+        language: format.language,
+        infoString,
+        source: lines.slice(contentStart, contentEnd).join('\n'),
+        startLine: lineIndex + 1,
+        endLine: closingLineIndex === null ? null : closingLineIndex + 1,
+      });
+    }
+
+    lineIndex = closingLineIndex ?? lines.length;
+  }
+
+  return diagrams;
+}
+
+function isClosingFence(line: string, fenceChar: string, fenceLength: number): boolean {
+  const escapedFenceChar = fenceChar === '`' ? '`' : '\\~';
+  return new RegExp(`^ {0,3}${escapedFenceChar}{${fenceLength},}[ \\t]*$`).test(line);
+}
diff --git a/apps/staged/src/lib/shared/markdown/diagramRendering.ts b/apps/staged/src/lib/shared/markdown/diagramRendering.ts
new file mode 100644
index 00000000..58e25953
--- /dev/null
+++ b/apps/staged/src/lib/shared/markdown/diagramRendering.ts
@@ -0,0 +1,54 @@
+import type { Tokens } from 'marked';
+
+import { getMarkdownDiagramFormat, type MarkdownDiagramFormat } from './diagramFormats';
+import { sanitizePikchrSvg, type PikchrRenderer } from './pikchrRendering';
+
+export interface MarkdownDiagramRenderingOptions {
+  pikchrRenderer?: PikchrRenderer | null;
+}
+
+export interface RenderedMarkdownDiagramCodeBlock {
+  html: string;
+  trustedHtml: boolean;
+}
+
+export function renderMarkdownDiagramCodeBlock(
+  token: Tokens.Code,
+  renderedSource: string,
+  options: MarkdownDiagramRenderingOptions = {}
+): RenderedMarkdownDiagramCodeBlock | null {
+  const format = getMarkdownDiagramFormat(token.lang);
+  if (!format) return null;
+
+  const renderedDiagramSource = withDiagramSourceClass(renderedSource, format);
+  const renderedPikchr = options.pikchrRenderer?.(token.text);
+  if (!renderedPikchr || renderedPikchr.kind !== 'svg') {
+    return { html: renderedDiagramSource, trustedHtml: false };
+  }
+  const renderedSvg = sanitizePikchrSvg(renderedPikchr.svg);
+  if (!renderedSvg) {
+    return { html: renderedDiagramSource, trustedHtml: false };
+  }
+
+  return {
+    html: renderPikchrPreview(renderedSvg),
+    trustedHtml: true,
+  };
+}
+
+function withDiagramSourceClass(renderedSource: string, format: MarkdownDiagramFormat): string {
+  return renderedSource.replace(
+    '<pre>',
+    `<pre class="markdown-diagram-source markdown-diagram-source-${format.language}">`
+  );
+}
+
+function renderPikchrPreview(renderedSvg: string): string {
+  return [
+    '<figure class="markdown-diagram markdown-diagram-pikchr">',
+    '<div class="markdown-diagram-preview markdown-diagram-preview-pikchr">',
+    renderedSvg,
+    '</div>',
+    '</figure>',
+  ].join('');
+}
diff --git a/apps/staged/src/lib/shared/markdown/diagramStyles.css b/apps/staged/src/lib/shared/markdown/diagramStyles.css
new file mode 100644
index 00000000..de4c6772
--- /dev/null
+++ b/apps/staged/src/lib/shared/markdown/diagramStyles.css
@@ -0,0 +1,25 @@
+.markdown-content .markdown-diagram {
+  margin: 0.9em 0;
+  border: 1px solid var(--border-subtle);
+  border-radius: 8px;
+  overflow: hidden;
+  background: var(--bg-primary);
+}
+
+.markdown-content .markdown-diagram-preview {
+  display: flex;
+  justify-content: center;
+  padding: 16px;
+  background: var(--diagram-canvas-bg);
+  overflow-x: auto;
+}
+
+.markdown-content .markdown-diagram-preview svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+.markdown-content .markdown-diagram-preview-pikchr .markdown-pikchr-svg {
+  overflow: visible;
+}
diff --git a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts b/apps/staged/src/lib/shared/markdown/pikchrRendering.test.ts
similarity index 86%
rename from apps/staged/src/lib/features/notes/pikchrRendering.test.ts
rename to apps/staged/src/lib/shared/markdown/pikchrRendering.test.ts
index 55d843ba..4c56dcec 100644
--- a/apps/staged/src/lib/features/notes/pikchrRendering.test.ts
+++ b/apps/staged/src/lib/shared/markdown/pikchrRendering.test.ts
@@ -1,12 +1,12 @@
 import { describe, expect, it, vi } from 'vitest';
 
-import { loadNotePikchrRenderer, sanitizePikchrSvg } from './pikchrRendering';
+import { loadPikchrRenderer, sanitizePikchrSvg } from './pikchrRendering';
 
 describe('sanitizePikchrSvg', () => {
   it('keeps static Pikchr geometry and path styles', () => {
     const svg = sanitizePikchrSvg(
       [
-        '<svg xmlns="http://www.w3.org/2000/svg" class="note-pikchr-svg" viewBox="0 0 58 34" data-pikchr-date="20260403102956">',
+        '<svg xmlns="http://www.w3.org/2000/svg" class="markdown-pikchr-svg" viewBox="0 0 58 34" data-pikchr-date="20260403102956">',
         '<path d="M2,32L56,32L56,2L2,2Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />',
         '<text x="29" y="17" text-anchor="middle" fill="rgb(0,0,0)" dominant-baseline="central">Start</text>',
         '</svg>',
@@ -92,9 +92,9 @@ describe('sanitizePikchrSvg', () => {
   });
 });
 
-describe('loadNotePikchrRenderer', () => {
+describe('loadPikchrRenderer', () => {
   it('loads the bundled renderer and returns sanitized SVG', async () => {
-    const renderPikchr = await loadNotePikchrRenderer();
+    const renderPikchr = await loadPikchrRenderer();
     const rendered = renderPikchr('box "Start" fit');
 
     expect(rendered.kind).toBe('svg');
@@ -103,7 +103,7 @@ describe('loadNotePikchrRenderer', () => {
     expect(rendered.width).toBeGreaterThan(0);
     expect(rendered.height).toBeGreaterThan(0);
     expect(rendered.svg).toContain('<svg');
-    expect(rendered.svg).toContain('class="note-pikchr-svg"');
+    expect(rendered.svg).toContain('class="markdown-pikchr-svg"');
     expect(rendered.svg).toContain('<path');
     expect(rendered.svg).toContain('Start');
     expect(rendered.svg).not.toContain('<script');
@@ -118,7 +118,7 @@ describe('loadNotePikchrRenderer', () => {
         render: () => ({
           width: 10,
           height: 10,
-          svg: '<svg xmlns="http://www.w3.org/2000/svg" class="note-pikchr-svg" viewBox="0 0 10 10"><path d="M0,0L10,10" /></svg>',
+          svg: '<svg xmlns="http://www.w3.org/2000/svg" class="markdown-pikchr-svg" viewBox="0 0 10 10"><path d="M0,0L10,10" /></svg>',
         }),
       });
 
@@ -126,11 +126,11 @@ describe('loadNotePikchrRenderer', () => {
     vi.doMock('pikchr-js', () => ({ default: loadPikchr }));
 
     try {
-      const { loadNotePikchrRenderer } = await import('./pikchrRendering');
+      const { loadPikchrRenderer } = await import('./pikchrRendering');
 
-      await expect(loadNotePikchrRenderer()).rejects.toThrow('initialization failed');
+      await expect(loadPikchrRenderer()).rejects.toThrow('initialization failed');
 
-      const renderPikchr = await loadNotePikchrRenderer();
+      const renderPikchr = await loadPikchrRenderer();
       const rendered = renderPikchr('box "Retry" fit');
 
       expect(loadPikchr).toHaveBeenCalledTimes(2);
diff --git a/apps/staged/src/lib/shared/markdown/pikchrRendering.ts b/apps/staged/src/lib/shared/markdown/pikchrRendering.ts
new file mode 100644
index 00000000..ee52a80c
--- /dev/null
+++ b/apps/staged/src/lib/shared/markdown/pikchrRendering.ts
@@ -0,0 +1,185 @@
+import type { Pikchr } from 'pikchr-js';
+import sanitizeHtml from 'sanitize-html';
+
+const PIKCHR_SVG_CLASS = 'markdown-pikchr-svg';
+const MAX_PIKCHR_SOURCE_LENGTH = 20_000;
+const MAX_PIKCHR_SVG_LENGTH = 250_000;
+const PIKCHR_SVG_ROOT = /^\s*<svg[\s>]/i;
+const PIKCHR_SIDE_LABEL_GAP = '0.35em';
+
+const CSS_NUMBER = String.raw`[-+]?(?:\d+(?:\.\d+)?|\.\d+)(?:e[-+]?\d+)?`;
+const CSS_LENGTH = new RegExp(`^(?:${CSS_NUMBER})(?:px|pt|pc|mm|cm|in|em|rem|%)?$`);
+const CSS_COLOR =
+  /^(?:none|transparent|currentColor|[a-zA-Z]+|#[0-9a-fA-F]{3,8}|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}(?:\s*,\s*(?:0|1|0?\.\d+))?\s*\))$/;
+const CSS_DASH_ARRAY = new RegExp(`^(?:${CSS_NUMBER})(?:\\s*,\\s*(?:${CSS_NUMBER}))*$`);
+const DIRECT_COLOR_ATTRIBUTES = ['fill', 'stroke'] as const;
+const DIRECT_COLOR_ATTRIBUTE_TAGS = new Set([
+  'path',
+  'text',
+  'rect',
+  'circle',
+  'ellipse',
+  'line',
+  'polyline',
+  'polygon',
+]);
+
+export type RenderedPikchrDiagram =
+  | {
+      kind: 'svg';
+      svg: string;
+      width: number;
+      height: number;
+    }
+  | {
+      kind: 'error';
+      message: string;
+    };
+
+export type PikchrRenderer = (source: string) => RenderedPikchrDiagram;
+
+let rendererPromise: Promise<PikchrRenderer> | null = null;
+
+export function loadPikchrRenderer(): Promise<PikchrRenderer> {
+  rendererPromise ??= import('pikchr-js')
+    .then(({ default: loadPikchr }) => loadPikchr())
+    .then((pikchr) => {
+      return (source: string) => renderPikchrSource(pikchr, source);
+    })
+    .catch((error) => {
+      rendererPromise = null;
+      throw error;
+    });
+  return rendererPromise;
+}
+
+export function renderPikchrSource(pikchr: Pikchr, source: string): RenderedPikchrDiagram {
+  if (source.length > MAX_PIKCHR_SOURCE_LENGTH) {
+    return { kind: 'error', message: 'Pikchr source is too large to render safely.' };
+  }
+
+  try {
+    const rendered = pikchr.render(source, PIKCHR_SVG_CLASS);
+    if (rendered.width < 0 || rendered.height < 0 || !PIKCHR_SVG_ROOT.test(rendered.svg)) {
+      return { kind: 'error', message: 'Pikchr could not render this diagram.' };
+    }
+
+    const svg = sanitizePikchrSvg(rendered.svg);
+    if (!svg) {
+      return { kind: 'error', message: 'Pikchr rendered unsafe SVG.' };
+    }
+
+    return {
+      kind: 'svg',
+      svg,
+      width: rendered.width,
+      height: rendered.height,
+    };
+  } catch {
+    return { kind: 'error', message: 'Pikchr could not render this diagram.' };
+  }
+}
+
+export function sanitizePikchrSvg(svg: string): string | null {
+  if (svg.length > MAX_PIKCHR_SVG_LENGTH || !PIKCHR_SVG_ROOT.test(svg)) {
+    return null;
+  }
+
+  const sanitized = sanitizeHtml(svg, {
+    allowedTags: [
+      'svg',
+      'g',
+      'path',
+      'text',
+      'rect',
+      'circle',
+      'ellipse',
+      'line',
+      'polyline',
+      'polygon',
+    ],
+    allowedAttributes: {
+      svg: ['xmlns', 'viewBox', 'viewbox', 'class', 'style', 'width', 'height'],
+      g: ['class', 'transform', 'style'],
+      path: ['class', 'd', 'fill', 'stroke', 'style'],
+      text: [
+        'class',
+        'x',
+        'y',
+        'dx',
+        'dy',
+        'text-anchor',
+        'dominant-baseline',
+        'fill',
+        'stroke',
+        'style',
+      ],
+      rect: ['class', 'x', 'y', 'width', 'height', 'rx', 'ry', 'fill', 'stroke', 'style'],
+      circle: ['class', 'cx', 'cy', 'r', 'fill', 'stroke', 'style'],
+      ellipse: ['class', 'cx', 'cy', 'rx', 'ry', 'fill', 'stroke', 'style'],
+      line: ['class', 'x1', 'y1', 'x2', 'y2', 'fill', 'stroke', 'style'],
+      polyline: ['class', 'points', 'fill', 'stroke', 'style'],
+      polygon: ['class', 'points', 'fill', 'stroke', 'style'],
+    },
+    allowedStyles: {
+      '*': {
+        fill: [CSS_COLOR],
+        stroke: [CSS_COLOR],
+        'stroke-width': [CSS_LENGTH],
+        'stroke-dasharray': [CSS_DASH_ARRAY],
+        'font-size': [/^initial$/, CSS_LENGTH],
+      },
+    },
+    allowedSchemes: [],
+    transformTags: {
+      '*': normalizePikchrSvgAttributes,
+    },
+  });
+
+  const normalized = sanitized.replace(/\sviewbox=/g, ' viewBox=');
+  if (!PIKCHR_SVG_ROOT.test(normalized)) return null;
+  return normalized;
+}
+
+function normalizePikchrSvgAttributes(tagName: string, attribs: Record<string, string>) {
+  const colorNormalized = stripUnsafeDirectColorAttributes(tagName, attribs);
+  if (tagName.toLowerCase() !== 'text') return colorNormalized;
+
+  return {
+    tagName,
+    attribs: addSideLabelGap(colorNormalized.attribs),
+  };
+}
+
+function addSideLabelGap(attribs: Record<string, string>) {
+  if (attribs.dx !== undefined) return attribs;
+
+  const anchor = attribs['text-anchor']?.trim().toLowerCase();
+  if (anchor !== 'start' && anchor !== 'end') return attribs;
+
+  return {
+    ...attribs,
+    dx: anchor === 'start' ? PIKCHR_SIDE_LABEL_GAP : `-${PIKCHR_SIDE_LABEL_GAP}`,
+  };
+}
+
+function stripUnsafeDirectColorAttributes(tagName: string, attribs: Record<string, string>) {
+  const nextAttribs = { ...attribs };
+  if (!DIRECT_COLOR_ATTRIBUTE_TAGS.has(tagName.toLowerCase())) {
+    return { tagName, attribs: nextAttribs };
+  }
+
+  for (const attribute of DIRECT_COLOR_ATTRIBUTES) {
+    const value = nextAttribs[attribute];
+    if (value === undefined) continue;
+
+    const trimmedValue = value.trim();
+    if (CSS_COLOR.test(trimmedValue)) {
+      nextAttribs[attribute] = trimmedValue;
+    } else {
+      delete nextAttribs[attribute];
+    }
+  }
+
+  return { tagName, attribs: nextAttribs };
+}
diff --git a/apps/staged/src/lib/shared/markdown/renderMarkdown.test.ts b/apps/staged/src/lib/shared/markdown/renderMarkdown.test.ts
new file mode 100644
index 00000000..0e203072
--- /dev/null
+++ b/apps/staged/src/lib/shared/markdown/renderMarkdown.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+
+import { renderMarkdown } from './renderMarkdown';
+import type { PikchrRenderer } from './pikchrRendering';
+
+describe('renderMarkdown', () => {
+  it('renders Pikchr fenced blocks as escaped source while the renderer is unavailable', () => {
+    const html = renderMarkdown('```pikchr\nbox "Start" fit\n```');
+
+    expect(html).toContain('<pre class="markdown-diagram-source markdown-diagram-source-pikchr">');
+    expect(html).toContain('box "Start" fit');
+    expect(html).not.toContain('<svg');
+    expect(html).not.toContain('markdown-diagram-preview');
+  });
+
+  it('leaves non-diagram fenced blocks as normal code blocks', () => {
+    const html = renderMarkdown('```ts\nconst value = 1;\n```');
+
+    expect(html).toContain('<pre><code class="language-ts">');
+    expect(html).not.toContain('markdown-diagram-source');
+  });
+
+  it('leaves Mermaid fenced blocks as normal code blocks', () => {
+    const html = renderMarkdown('```mermaid\nflowchart TD\nA-->B\n```');
+
+    expect(html).toContain('<pre><code class="language-mermaid">');
+    expect(html).toContain('flowchart TD');
+    expect(html).not.toContain('markdown-diagram-source');
+    expect(html).not.toContain('markdown-diagram-preview');
+  });
+
+  it('renders Pikchr fenced blocks as sanitized SVG when a renderer is loaded', () => {
+    const html = renderMarkdown('```pikchr\nbox "Start" fit\n```', {
+      pikchrRenderer: safePikchrRenderer,
+    });
+
+    expect(html).toContain('<figure class="markdown-diagram markdown-diagram-pikchr">');
+    expect(html).not.toContain('markdown-diagram-caption');
+    expect(html).toContain(
+      '<div class="markdown-diagram-preview markdown-diagram-preview-pikchr">'
+    );
+    expect(html).toContain('<svg');
+    expect(html).toContain('class="markdown-pikchr-svg"');
+    expect(html).toContain('<path');
+    expect(html).toContain('stroke:rgb(0,0,0)');
+    expect(html).not.toContain('markdown-diagram-source-wrap');
+    expect(html).not.toContain('markdown-diagram-source-pikchr');
+    expect(html).not.toContain('box "Start" fit');
+    expect(html).not.toContain('box &quot;Start&quot; fit');
+    expect(html).not.toContain('STAGED_MARKDOWN_TRUSTED_DIAGRAM_');
+  });
+
+  it('does not allow renderer SVG through the generic Markdown sanitizer', () => {
+    const html = renderMarkdown('<svg><script>alert(1)</script></svg>');
+
+    expect(html).not.toContain('<svg');
+    expect(html).not.toContain('<script>');
+  });
+
+  it('does not allow raw HTML to opt into markdown diagram classes', () => {
+    const html = renderMarkdown(
+      '<div class="markdown-diagram-preview"><figcaption class="markdown-diagram-caption">Pikchr</figcaption></div>'
+    );
+
+    expect(html).not.toContain('class="markdown-diagram-preview"');
+    expect(html).not.toContain('class="markdown-diagram-caption"');
+    expect(html).toContain('Pikchr');
+  });
+
+  it('falls back to escaped source when the Pikchr renderer rejects the SVG', () => {
+    const html = renderMarkdown('```pikchr\nbox "Unsafe" fit\n```', {
+      pikchrRenderer: unsafePikchrRenderer,
+    });
+
+    expect(html).toContain('<pre class="markdown-diagram-source markdown-diagram-source-pikchr">');
+    expect(html).toContain('box "Unsafe" fit');
+    expect(html).not.toContain('<svg');
+    expect(html).not.toContain('<script>');
+    expect(html).not.toContain('onclick');
+  });
+
+  it('leaves raw SVG fenced blocks as normal escaped code blocks', () => {
+    const html = renderMarkdown('```svg\n<svg><script>alert(1)</script></svg>\n```');
+
+    expect(html).toContain('<pre><code class="language-svg">');
+    expect(html).toContain('&lt;svg&gt;&lt;script&gt;alert(1)&lt;/script&gt;&lt;/svg&gt;');
+    expect(html).not.toContain('markdown-diagram-source');
+    expect(html).not.toContain('<script>');
+  });
+});
+
+const safePikchrRenderer: PikchrRenderer = () => ({
+  kind: 'svg',
+  width: 58,
+  height: 34,
+  svg: [
+    '<svg xmlns="http://www.w3.org/2000/svg" class="markdown-pikchr-svg" viewBox="0 0 58 34">',
+    '<path d="M2,32L56,32L56,2L2,2Z" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" />',
+    '<text x="29" y="17" text-anchor="middle" fill="rgb(0,0,0)" dominant-baseline="central">Start</text>',
+    '</svg>',
+  ].join(''),
+});
+
+const unsafePikchrRenderer: PikchrRenderer = () => ({
+  kind: 'error',
+  message: 'Pikchr rendered unsafe SVG.',
+});
diff --git a/apps/staged/src/lib/shared/markdown/renderMarkdown.ts b/apps/staged/src/lib/shared/markdown/renderMarkdown.ts
new file mode 100644
index 00000000..d41e9234
--- /dev/null
+++ b/apps/staged/src/lib/shared/markdown/renderMarkdown.ts
@@ -0,0 +1,70 @@
+import { marked, Renderer, type Tokens } from 'marked';
+
+import { sanitize } from '../sanitize';
+import {
+  renderMarkdownDiagramCodeBlock,
+  type MarkdownDiagramRenderingOptions,
+} from './diagramRendering';
+
+export type MarkdownRenderingOptions = MarkdownDiagramRenderingOptions;
+
+interface TrustedHtmlReplacement {
+  placeholder: string;
+  html: string;
+}
+
+let fallbackPlaceholderSequence = 0;
+
+export function renderMarkdown(text: string, options: MarkdownRenderingOptions = {}): string {
+  const trustedHtml: TrustedHtmlReplacement[] = [];
+  const renderedMarkdown = sanitize(
+    marked.parse(text, {
+      breaks: true,
+      gfm: true,
+      renderer: createMarkdownRenderer(options, trustedHtml),
+    }) as string
+  );
+
+  return restoreTrustedHtml(renderedMarkdown, trustedHtml);
+}
+
+function createMarkdownRenderer(
+  options: MarkdownRenderingOptions,
+  trustedHtml: TrustedHtmlReplacement[]
+): Renderer {
+  const renderer = new Renderer();
+  const renderCode = renderer.code.bind(renderer);
+
+  renderer.code = (token: Tokens.Code) => {
+    const rendered = renderCode(token);
+    const diagram = renderMarkdownDiagramCodeBlock(token, rendered, options);
+    if (!diagram) return rendered;
+    if (!diagram.trustedHtml) return diagram.html;
+
+    return stashTrustedHtml(diagram.html, trustedHtml);
+  };
+
+  return renderer;
+}
+
+function stashTrustedHtml(html: string, trustedHtml: TrustedHtmlReplacement[]): string {
+  const placeholder = `STAGED_MARKDOWN_TRUSTED_DIAGRAM_${trustedHtml.length}_${createPlaceholderNonce()}`;
+  trustedHtml.push({ placeholder, html });
+  return placeholder;
+}
+
+function restoreTrustedHtml(
+  renderedMarkdown: string,
+  trustedHtml: TrustedHtmlReplacement[]
+): string {
+  return trustedHtml.reduce((html, replacement) => {
+    return html.replaceAll(replacement.placeholder, replacement.html);
+  }, renderedMarkdown);
+}
+
+function createPlaceholderNonce(): string {
+  const randomUuid = globalThis.crypto?.randomUUID?.();
+  if (randomUuid) return randomUuid.replaceAll('-', '_');
+
+  return `${Date.now().toString(36)}_${fallbackPlaceholderSequence++}`;
+}

From 618270244e6a0e1d249bf12f2e618277bc722478 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 16:51:43 +1000
Subject: [PATCH 15/20] fix(notes): localize Pikchr grammar guidance

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src-tauri/src/lib.rs              |   1 +
 apps/staged/src-tauri/src/session_commands.rs | 185 ++++++++++++++++--
 apps/staged/src-tauri/src/web_server.rs       |   2 +-
 apps/staged/src/lib/commands.test.ts          |  20 ++
 apps/staged/src/lib/commands.ts               |  12 ++
 .../lib/features/sessions/SessionModal.svelte |  31 +--
 .../features/sessions/noteFreshness.test.ts   |  25 ++-
 .../lib/features/sessions/noteFreshness.ts    |  40 ----
 8 files changed, 233 insertions(+), 83 deletions(-)

diff --git a/apps/staged/src-tauri/src/lib.rs b/apps/staged/src-tauri/src/lib.rs
index 7eef6aed..669fd479 100644
--- a/apps/staged/src-tauri/src/lib.rs
+++ b/apps/staged/src-tauri/src/lib.rs
@@ -2277,6 +2277,7 @@ pub fn run() {
             session_commands::count_assistant_messages_after,
             session_commands::start_session,
             session_commands::resume_session,
+            session_commands::build_note_followup_message,
             session_commands::cancel_session,
             session_commands::delete_session,
             session_commands::start_branch_session,
diff --git a/apps/staged/src-tauri/src/session_commands.rs b/apps/staged/src-tauri/src/session_commands.rs
index 3fa7ded9..399a0cf4 100644
--- a/apps/staged/src-tauri/src/session_commands.rs
+++ b/apps/staged/src-tauri/src/session_commands.rs
@@ -32,6 +32,7 @@ use crate::session_runner::{self, SessionConfig};
 use crate::store::{self, Store};
 
 const PIKCHR_GRAMMAR_RESOURCE: &str = "resources/pikchr/grammar.md";
+const PIKCHR_GRAMMAR_REMOTE_PATH: &str = "/tmp/staged-pikchr-grammar.md";
 pub(crate) const PIKCHR_GRAMMAR_URL: &str = "https://pikchr.org/home/doc/trunk/doc/grammar.md";
 
 // =============================================================================
@@ -71,27 +72,55 @@ where
         .map_err(|e| e.to_string())
 }
 
+fn bundled_pikchr_grammar_path(app_handle: &tauri::AppHandle) -> Option<PathBuf> {
+    if let Ok(path) = app_handle
+        .path()
+        .resolve(PIKCHR_GRAMMAR_RESOURCE, BaseDirectory::Resource)
+    {
+        if path.is_file() {
+            return Some(path);
+        }
+    }
+
+    let source_path = Path::new(env!("CARGO_MANIFEST_DIR")).join(PIKCHR_GRAMMAR_RESOURCE);
+    if source_path.is_file() {
+        return Some(source_path);
+    }
+
+    None
+}
+
 pub(crate) fn resolve_pikchr_grammar_reference(
     app_handle: &tauri::AppHandle,
-    is_remote: bool,
+    workspace_name: Option<&str>,
 ) -> String {
-    if !is_remote {
-        if let Ok(path) = app_handle
-            .path()
-            .resolve(PIKCHR_GRAMMAR_RESOURCE, BaseDirectory::Resource)
-        {
-            if path.is_file() {
-                return path.to_string_lossy().into_owned();
+    let Some(grammar_path) = bundled_pikchr_grammar_path(app_handle) else {
+        log::warn!("Bundled Pikchr grammar resource not found; falling back to public URL");
+        return PIKCHR_GRAMMAR_URL.to_string();
+    };
+
+    if let Some(workspace_name) = workspace_name {
+        match std::fs::read(&grammar_path) {
+            Ok(bytes) => {
+                match write_bytes_to_remote(workspace_name, &bytes, PIKCHR_GRAMMAR_REMOTE_PATH) {
+                    Ok(()) => return PIKCHR_GRAMMAR_REMOTE_PATH.to_string(),
+                    Err(e) => log::warn!(
+                        "Failed to copy Pikchr grammar to remote workspace {workspace_name}: {e}"
+                    ),
+                }
+            }
+            Err(e) => {
+                log::warn!(
+                    "Failed to read bundled Pikchr grammar at {}: {e}",
+                    grammar_path.display()
+                );
             }
         }
 
-        let source_path = Path::new(env!("CARGO_MANIFEST_DIR")).join(PIKCHR_GRAMMAR_RESOURCE);
-        if source_path.is_file() {
-            return source_path.to_string_lossy().into_owned();
-        }
+        return PIKCHR_GRAMMAR_URL.to_string();
     }
 
-    PIKCHR_GRAMMAR_URL.to_string()
+    grammar_path.to_string_lossy().into_owned()
 }
 
 fn pikchr_note_guidance(reference: &str) -> String {
@@ -101,6 +130,55 @@ If you need the Pikchr grammar while writing a diagram, read the reference at: {
     )
 }
 
+pub(crate) fn build_note_followup_message_with_pikchr_reference(
+    has_parsed_note: bool,
+    pikchr_grammar_reference: &str,
+) -> String {
+    let visible_request = if has_parsed_note {
+        "Please update the note to reflect the latest chat."
+    } else {
+        "Please write the note for this session."
+    };
+    let linked_note_action = if has_parsed_note {
+        "update the linked note"
+    } else {
+        "write the linked note"
+    };
+    let pikchr_guidance = pikchr_note_guidance(pikchr_grammar_reference);
+
+    format!(
+        "<action>\n\
+The user is asking you to {linked_note_action} from the latest chat history.\n\
+\n\
+Use the existing conversation context. Do not create commits.\n\
+\n\
+{pikchr_guidance}\n\
+\n\
+Your final response must include a suggested-next-steps fenced block followed by the note content after a horizontal rule:\n\
+\n\
+```suggested-next-steps\n\
+{{\"suggestedNextCommitStep\": null, \"suggestedNextNoteStep\": null}}\n\
+```\n\
+\n\
+---\n\
+# <Title>\n\
+<Body>\n\
+\n\
+Formatting requirements:\n\
+- The opening fence line for suggested-next-steps must be exactly: ```suggested-next-steps\n\
+- The closing fence line must be exactly: ```\n\
+- Put only a JSON object inside the suggested-next-steps block.\n\
+- Include both nullable string fields: suggestedNextCommitStep and suggestedNextNoteStep.\n\
+- Keep suggested next steps concise; use null when there is no clear next action.\n\
+- The `---` separator must be on its own line.\n\
+- The note content must start immediately after `---` with a markdown H1.\n\
+- Do not wrap the note in code fences.\n\
+</action>\n\
+\n\
+{visible_request}"
+    )
+}
+
 // =============================================================================
 // Provider discovery
 // =============================================================================
@@ -441,6 +519,54 @@ pub(crate) fn infer_branch_resume_session_type(prompt: &str) -> Option<&'static
     }
 }
 
+#[tauri::command]
+pub fn build_note_followup_message(
+    store: tauri::State<'_, Mutex<Option<Arc<Store>>>>,
+    app_handle: tauri::AppHandle,
+    session_id: String,
+    branch_id: Option<String>,
+    has_parsed_note: bool,
+) -> Result<String, String> {
+    let store = get_store(&store)?;
+
+    store
+        .get_session(&session_id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| format!("Session not found: {session_id}"))?;
+
+    let linked_commit = store.get_commit_by_session(&session_id).ok().flatten();
+    let linked_note = store.get_note_by_session(&session_id).ok().flatten();
+    let linked_review = store.get_review_by_session(&session_id).ok().flatten();
+
+    let branch_from_id = branch_id
+        .as_deref()
+        .and_then(|bid| store.get_branch(bid).ok().flatten());
+
+    let linked_branch = if branch_from_id.is_some() {
+        branch_from_id
+    } else if let Some(commit) = &linked_commit {
+        store.get_branch(&commit.branch_id).ok().flatten()
+    } else if let Some(note) = &linked_note {
+        store.get_branch(&note.branch_id).ok().flatten()
+    } else if let Some(review) = &linked_review {
+        store.get_branch(&review.branch_id).ok().flatten()
+    } else {
+        None
+    };
+
+    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(
+        &app_handle,
+        linked_branch
+            .as_ref()
+            .and_then(|branch| branch.workspace_name.as_deref()),
+    );
+
+    Ok(build_note_followup_message_with_pikchr_reference(
+        has_parsed_note,
+        &pikchr_grammar_reference,
+    ))
+}
+
 #[tauri::command]
 pub fn cancel_session(
     registry: tauri::State<'_, Arc<session_runner::SessionRegistry>>,
@@ -926,7 +1052,7 @@ pub async fn start_project_session(
     let project_context = build_project_session_context(&store, &project, None);
 
     let is_remote = project.location == store::ProjectLocation::Remote;
-    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(&app_handle, is_remote);
+    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(&app_handle, None);
     let action_instructions = build_project_session_action_instructions_with_pikchr_reference(
         is_remote,
         &pikchr_grammar_reference,
@@ -1147,7 +1273,8 @@ async fn prepare_branch_session_start(
 
     // Build the full prompt with action instructions + project information + branch context.
     let project_information = build_project_context(store, &project, &branch);
-    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(app_handle, is_remote);
+    let pikchr_grammar_reference =
+        resolve_pikchr_grammar_reference(app_handle, branch.workspace_name.as_deref());
     let full_prompt = build_full_prompt_with_pikchr_reference(
         prompt,
         &project_information,
@@ -1716,7 +1843,8 @@ async fn start_queued_session_for_branch(
 
     // Build the full prompt with context.
     let project_information = build_project_context(&store, &project, &branch);
-    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(&app_handle, is_remote);
+    let pikchr_grammar_reference =
+        resolve_pikchr_grammar_reference(&app_handle, branch.workspace_name.as_deref());
     let full_prompt = build_full_prompt_with_pikchr_reference(
         &prompt,
         &project_information,
@@ -4245,6 +4373,31 @@ mod tests {
         assert_pikchr_note_guidance(&prompt, "/tmp/staged/pikchr/grammar.md");
     }
 
+    #[test]
+    fn note_followup_prompt_uses_supplied_local_pikchr_reference() {
+        let prompt = build_note_followup_message_with_pikchr_reference(
+            true,
+            "/Applications/Staged.app/Contents/Resources/resources/pikchr/grammar.md",
+        );
+
+        assert!(prompt.contains("The user is asking you to update the linked note"));
+        assert!(prompt.contains("Please update the note to reflect the latest chat."));
+        assert_pikchr_note_guidance(
+            &prompt,
+            "/Applications/Staged.app/Contents/Resources/resources/pikchr/grammar.md",
+        );
+    }
+
+    #[test]
+    fn note_followup_prompt_uses_supplied_remote_pikchr_reference() {
+        let prompt =
+            build_note_followup_message_with_pikchr_reference(false, PIKCHR_GRAMMAR_REMOTE_PATH);
+
+        assert!(prompt.contains("The user is asking you to write the linked note"));
+        assert!(prompt.contains("Please write the note for this session."));
+        assert_pikchr_note_guidance(&prompt, PIKCHR_GRAMMAR_REMOTE_PATH);
+    }
+
     #[test]
     fn review_prompt_requires_strict_fence_lines() {
         let prompt = build_full_prompt(
diff --git a/apps/staged/src-tauri/src/web_server.rs b/apps/staged/src-tauri/src/web_server.rs
index 779da3f3..f6bd92c6 100644
--- a/apps/staged/src-tauri/src/web_server.rs
+++ b/apps/staged/src-tauri/src/web_server.rs
@@ -2909,7 +2909,7 @@ async fn dispatch(command: &str, args: Value, state: &WebAppState) -> Result<Val
 
             let is_remote = project.location == store::ProjectLocation::Remote;
             let pikchr_grammar_reference =
-                session_commands::resolve_pikchr_grammar_reference(&app_handle, is_remote);
+                session_commands::resolve_pikchr_grammar_reference(&app_handle, None);
             let action_instructions =
                 session_commands::build_project_session_action_instructions_with_pikchr_reference(
                     is_remote,
diff --git a/apps/staged/src/lib/commands.test.ts b/apps/staged/src/lib/commands.test.ts
index 7789947c..44259f10 100644
--- a/apps/staged/src/lib/commands.test.ts
+++ b/apps/staged/src/lib/commands.test.ts
@@ -6,6 +6,7 @@ describe('browser-native command wrappers', () => {
   });
 
   afterEach(() => {
+    vi.doUnmock('./transport');
     vi.unstubAllGlobals();
   });
 
@@ -60,4 +61,23 @@ describe('browser-native command wrappers', () => {
     await expect(openInApp('/tmp/repo', 'finder')).rejects.toThrow('web mode');
     expect(fetch).not.toHaveBeenCalled();
   });
+
+  it('builds note follow-up prompts through the backend command', async () => {
+    const invokeCommand = vi.fn().mockResolvedValue('backend prompt');
+    vi.doMock('./transport', () => ({
+      invokeCommand,
+      isTauri: true,
+    }));
+
+    const { buildNoteFollowupMessage } = await import('./commands');
+
+    await expect(buildNoteFollowupMessage('session-1', 'branch-1', true)).resolves.toBe(
+      'backend prompt'
+    );
+    expect(invokeCommand).toHaveBeenCalledWith('build_note_followup_message', {
+      sessionId: 'session-1',
+      branchId: 'branch-1',
+      hasParsedNote: true,
+    });
+  });
 });
diff --git a/apps/staged/src/lib/commands.ts b/apps/staged/src/lib/commands.ts
index f6218eb5..72e92f09 100644
--- a/apps/staged/src/lib/commands.ts
+++ b/apps/staged/src/lib/commands.ts
@@ -639,6 +639,18 @@ export function resumeSession(
   });
 }
 
+export function buildNoteFollowupMessage(
+  sessionId: string,
+  branchId: string | null | undefined,
+  hasParsedNote: boolean
+): Promise<string> {
+  return invokeCommand('build_note_followup_message', {
+    sessionId,
+    branchId: branchId ?? null,
+    hasParsedNote,
+  });
+}
+
 export function cancelSession(sessionId: string): Promise<void> {
   return invokeCommand('cancel_session', { sessionId });
 }
diff --git a/apps/staged/src/lib/features/sessions/SessionModal.svelte b/apps/staged/src/lib/features/sessions/SessionModal.svelte
index d22e0615..d0fea57b 100644
--- a/apps/staged/src/lib/features/sessions/SessionModal.svelte
+++ b/apps/staged/src/lib/features/sessions/SessionModal.svelte
@@ -45,6 +45,7 @@
   import { isResumableReason } from '../../types';
   import type { Session, SessionMessage, HashtagItem, ProjectRepo } from '../../types';
   import {
+    buildNoteFollowupMessage,
     cancelSession,
     createImage,
     createImageFromData,
@@ -94,11 +95,7 @@
   import { extractMarkdownDiagramFences } from '../../shared/markdown/diagramFormats';
   import { renderMarkdown as renderSharedMarkdown } from '../../shared/markdown/renderMarkdown';
   import { loadPikchrRenderer, type PikchrRenderer } from '../../shared/markdown/pikchrRendering';
-  import {
-    buildNoteFollowupMessage,
-    getNoteFollowupLabel,
-    type LinkedNoteContext,
-  } from './noteFreshness';
+  import { getNoteFollowupLabel, type LinkedNoteContext } from './noteFreshness';
 
   interface Props {
     open: boolean;
@@ -575,9 +572,9 @@
   }
 
   /** Actually send a message to the backend and start the agent. */
-  async function sendMessage(text: string, imageIds?: string[]) {
-    if (!session || sending) return;
-    sending = true;
+  async function sendMessage(text: string, imageIds?: string[], sendingLocked = false) {
+    if (!session || (!sendingLocked && sending)) return;
+    if (!sendingLocked) sending = true;
     error = null;
     try {
       await resumeSession(session.id, text, imageIds, branchId);
@@ -591,13 +588,23 @@
       // Clear the queue — don't keep trying to send if the session is broken
       messageQueue = [];
     } finally {
-      sending = false;
+      if (!sendingLocked) sending = false;
     }
   }
 
-  function handleNoteFollowupClick() {
-    if (!noteInfo || sending) return;
-    void sendMessage(buildNoteFollowupMessage(noteInfo.hasParsedNote));
+  async function handleNoteFollowupClick() {
+    if (!session || !noteInfo || sending) return;
+    sending = true;
+    error = null;
+    try {
+      const prompt = await buildNoteFollowupMessage(session.id, branchId, noteInfo.hasParsedNote);
+      await sendMessage(prompt, undefined, true);
+    } catch (e) {
+      error = `Failed to send: ${e instanceof Error ? e.message : String(e)}`;
+      messageQueue = [];
+    } finally {
+      sending = false;
+    }
   }
 
   /** Process the next queued message when the session becomes idle. */
diff --git a/apps/staged/src/lib/features/sessions/noteFreshness.test.ts b/apps/staged/src/lib/features/sessions/noteFreshness.test.ts
index b3001840..26b506eb 100644
--- a/apps/staged/src/lib/features/sessions/noteFreshness.test.ts
+++ b/apps/staged/src/lib/features/sessions/noteFreshness.test.ts
@@ -1,7 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import type { Session, SessionMessage, SessionStatus, CompletionReason } from '../../types';
 import {
-  buildNoteFollowupMessage,
   countAssistantMessagesAfterNote,
   formatChatButtonLabel,
   getNoteFollowupLabel,
@@ -125,21 +124,18 @@ describe('note freshness', () => {
     expect(latestAssistantMessage(messages)?.id).toBe(3);
   });
 
-  it('builds a structured follow-up prompt with a readable visible request', () => {
-    const updateMessage = buildNoteFollowupMessage(true);
-    const writeMessage = buildNoteFollowupMessage(false);
-
-    expect(updateMessage.startsWith('<action>')).toBe(true);
-    expect(updateMessage).toContain('```suggested-next-steps');
-    expect(updateMessage).toContain('\n---\n# <Title>');
-    expect(updateMessage).toContain('Please update the note to reflect the latest chat.');
-    expect(updateMessage).toContain('fenced `pikchr` code blocks');
-    expect(updateMessage).toContain('https://pikchr.org/home/doc/trunk/doc/grammar.md');
-    expect(writeMessage).toContain('Please write the note for this session.');
+  it('recognizes a backend-built follow-up prompt by marker text', () => {
+    const backendBuiltFollowup =
+      '<action>\nThe user is asking you to update the linked note from the latest chat history.\n</action>';
+
+    expect(hasNoteFollowupBeenSent([message(1, 'user', 2500, backendBuiltFollowup)], 2000)).toBe(
+      true
+    );
   });
 
   it('suppresses note followup CTA when a followup was already sent after note updatedAt', () => {
-    const followupContent = buildNoteFollowupMessage(true);
+    const followupContent =
+      '<action>\nThe user is asking you to update the linked note from the latest chat history.\n</action>';
     const messages = [
       message(1, 'assistant', 1500),
       message(2, 'user', 2500, followupContent),
@@ -162,7 +158,8 @@ describe('note freshness', () => {
   it('does not suppress CTA when followup was sent before note was updated', () => {
     // A followup was sent at t=1500, but the note was updated at t=2000 (after the followup).
     // New assistant messages at t=3000 should still trigger the CTA.
-    const followupContent = buildNoteFollowupMessage(true);
+    const followupContent =
+      '<action>\nThe user is asking you to update the linked note from the latest chat history.\n</action>';
     const messages = [
       message(1, 'assistant', 1000),
       message(2, 'user', 1500, followupContent),
diff --git a/apps/staged/src/lib/features/sessions/noteFreshness.ts b/apps/staged/src/lib/features/sessions/noteFreshness.ts
index eccf0b04..88851801 100644
--- a/apps/staged/src/lib/features/sessions/noteFreshness.ts
+++ b/apps/staged/src/lib/features/sessions/noteFreshness.ts
@@ -1,9 +1,5 @@
 import type { Session, SessionMessage } from '../../types';
 
-const PIKCHR_GRAMMAR_URL = 'https://pikchr.org/home/doc/trunk/doc/grammar.md';
-
-const PIKCHR_NOTE_GUIDANCE = `Staged notes support rendered diagrams in fenced \`pikchr\` code blocks. If you need the Pikchr grammar while writing a diagram, read the reference at: ${PIKCHR_GRAMMAR_URL}`;
-
 export interface LinkedNoteContext {
   id: string;
   title: string;
@@ -98,39 +94,3 @@ export function getNoteFollowupLabel(
     ? 'Ask for the note to be updated'
     : 'Ask for a note to be written';
 }
-
-export function buildNoteFollowupMessage(hasParsedNote: boolean): string {
-  const visibleRequest = hasParsedNote
-    ? 'Please update the note to reflect the latest chat.'
-    : 'Please write the note for this session.';
-
-  return `<action>
-The user is asking you to ${hasParsedNote ? 'update the linked note' : 'write the linked note'} from the latest chat history.
-
-Use the existing conversation context. Do not create commits.
-
-${PIKCHR_NOTE_GUIDANCE}
-
-Your final response must include a suggested-next-steps fenced block followed by the note content after a horizontal rule:
-
-\`\`\`suggested-next-steps
-{"suggestedNextCommitStep": null, "suggestedNextNoteStep": null}
-\`\`\`
-
----
-# <Title>
-<Body>
-
-Formatting requirements:
-- The opening fence line for suggested-next-steps must be exactly: \`\`\`suggested-next-steps
-- The closing fence line must be exactly: \`\`\`
-- Put only a JSON object inside the suggested-next-steps block.
-- Include both nullable string fields: suggestedNextCommitStep and suggestedNextNoteStep.
-- Keep suggested next steps concise; use null when there is no clear next action.
-- The \`---\` separator must be on its own line.
-- The note content must start immediately after \`---\` with a markdown H1.
-- Do not wrap the note in code fences.
-</action>
-
-${visibleRequest}`;
-}

From 9c5d8b356f764f7ed81aa2a5e11dca5589324f1e Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 17:16:22 +1000
Subject: [PATCH 16/20] fix(notes): batch Pikchr grammar upload

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src-tauri/src/session_commands.rs | 197 +++++++++++++++---
 1 file changed, 166 insertions(+), 31 deletions(-)

diff --git a/apps/staged/src-tauri/src/session_commands.rs b/apps/staged/src-tauri/src/session_commands.rs
index 399a0cf4..45c00e06 100644
--- a/apps/staged/src-tauri/src/session_commands.rs
+++ b/apps/staged/src-tauri/src/session_commands.rs
@@ -35,6 +35,13 @@ const PIKCHR_GRAMMAR_RESOURCE: &str = "resources/pikchr/grammar.md";
 const PIKCHR_GRAMMAR_REMOTE_PATH: &str = "/tmp/staged-pikchr-grammar.md";
 pub(crate) const PIKCHR_GRAMMAR_URL: &str = "https://pikchr.org/home/doc/trunk/doc/grammar.md";
 
+enum RemotePikchrGrammarStaging {
+    NotNeeded,
+    UseRemotePath,
+    Upload(Vec<u8>),
+    FallbackUrl,
+}
+
 // =============================================================================
 // Helper — duplicated from lib.rs to avoid circular deps. If this grows,
 // consider extracting a shared `state.rs`.
@@ -90,34 +97,116 @@ fn bundled_pikchr_grammar_path(app_handle: &tauri::AppHandle) -> Option<PathBuf>
     None
 }
 
+fn pikchr_grammar_remote_uploads() -> &'static Mutex<HashSet<String>> {
+    static UPLOADS: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();
+    UPLOADS.get_or_init(|| Mutex::new(HashSet::new()))
+}
+
+fn has_uploaded_pikchr_grammar(workspace_name: &str) -> bool {
+    pikchr_grammar_remote_uploads()
+        .lock()
+        .unwrap()
+        .contains(workspace_name)
+}
+
+fn mark_pikchr_grammar_uploaded(workspace_name: &str) {
+    pikchr_grammar_remote_uploads()
+        .lock()
+        .unwrap()
+        .insert(workspace_name.to_string());
+}
+
+fn bundled_pikchr_grammar_bytes(app_handle: &tauri::AppHandle) -> Option<Vec<u8>> {
+    let Some(grammar_path) = bundled_pikchr_grammar_path(app_handle) else {
+        log::warn!("Bundled Pikchr grammar resource not found; falling back to public URL");
+        return None;
+    };
+
+    match std::fs::read(&grammar_path) {
+        Ok(bytes) => Some(bytes),
+        Err(e) => {
+            log::warn!(
+                "Failed to read bundled Pikchr grammar at {}: {e}",
+                grammar_path.display()
+            );
+            None
+        }
+    }
+}
+
+fn remote_pikchr_grammar_staging(
+    app_handle: &tauri::AppHandle,
+    workspace_name: &str,
+    session_type: &BranchSessionType,
+) -> RemotePikchrGrammarStaging {
+    if !matches!(session_type, BranchSessionType::Note) {
+        return RemotePikchrGrammarStaging::NotNeeded;
+    }
+
+    if has_uploaded_pikchr_grammar(workspace_name) {
+        return RemotePikchrGrammarStaging::UseRemotePath;
+    }
+
+    match bundled_pikchr_grammar_bytes(app_handle) {
+        Some(bytes) => RemotePikchrGrammarStaging::Upload(bytes),
+        None => RemotePikchrGrammarStaging::FallbackUrl,
+    }
+}
+
+fn local_pikchr_grammar_reference_for_session(
+    app_handle: &tauri::AppHandle,
+    session_type: &BranchSessionType,
+) -> String {
+    if matches!(session_type, BranchSessionType::Note) {
+        resolve_pikchr_grammar_reference(app_handle, None)
+    } else {
+        PIKCHR_GRAMMAR_URL.to_string()
+    }
+}
+
+fn upload_pikchr_grammar_to_remote(workspace_name: &str, bytes: &[u8]) -> String {
+    if has_uploaded_pikchr_grammar(workspace_name) {
+        return PIKCHR_GRAMMAR_REMOTE_PATH.to_string();
+    }
+
+    match write_bytes_to_remote(workspace_name, bytes, PIKCHR_GRAMMAR_REMOTE_PATH) {
+        Ok(()) => {
+            mark_pikchr_grammar_uploaded(workspace_name);
+            PIKCHR_GRAMMAR_REMOTE_PATH.to_string()
+        }
+        Err(e) => {
+            log::warn!("Failed to copy Pikchr grammar to remote workspace {workspace_name}: {e}");
+            PIKCHR_GRAMMAR_URL.to_string()
+        }
+    }
+}
+
 pub(crate) fn resolve_pikchr_grammar_reference(
     app_handle: &tauri::AppHandle,
     workspace_name: Option<&str>,
 ) -> String {
+    if let Some(workspace_name) = workspace_name {
+        if has_uploaded_pikchr_grammar(workspace_name) {
+            return PIKCHR_GRAMMAR_REMOTE_PATH.to_string();
+        }
+    }
+
     let Some(grammar_path) = bundled_pikchr_grammar_path(app_handle) else {
         log::warn!("Bundled Pikchr grammar resource not found; falling back to public URL");
         return PIKCHR_GRAMMAR_URL.to_string();
     };
 
     if let Some(workspace_name) = workspace_name {
-        match std::fs::read(&grammar_path) {
-            Ok(bytes) => {
-                match write_bytes_to_remote(workspace_name, &bytes, PIKCHR_GRAMMAR_REMOTE_PATH) {
-                    Ok(()) => return PIKCHR_GRAMMAR_REMOTE_PATH.to_string(),
-                    Err(e) => log::warn!(
-                        "Failed to copy Pikchr grammar to remote workspace {workspace_name}: {e}"
-                    ),
-                }
-            }
+        return match std::fs::read(&grammar_path) {
+            Ok(bytes) => upload_pikchr_grammar_to_remote(workspace_name, &bytes),
             Err(e) => {
                 log::warn!(
                     "Failed to read bundled Pikchr grammar at {}: {e}",
                     grammar_path.display()
                 );
+                PIKCHR_GRAMMAR_URL.to_string()
             }
-        }
-
-        return PIKCHR_GRAMMAR_URL.to_string();
+        };
     }
 
     grammar_path.to_string_lossy().into_owned()
@@ -1176,29 +1265,36 @@ async fn prepare_branch_session_start(
 
     // Resolve working directory and branch context.
     // Remote branches use ws_exec for git operations; local branches use the worktree directly.
-    let (working_dir, branch_context) = if is_remote {
+    let (working_dir, branch_context, pikchr_grammar_reference) = if is_remote {
         // For remote branches, use the derived clone path as a fallback working dir.
         // The actual work happens via ws_exec, not local filesystem.
         let fallback_dir = resolve_branch_repo_slug(store, &project, &branch)
             .and_then(|repo| crate::paths::repos_dir().map(|d| d.join(repo)))
             .unwrap_or_else(|| PathBuf::from("/tmp"));
         let workspace_name = branch.workspace_name.as_deref().unwrap().to_string();
+        let pikchr_grammar_staging =
+            remote_pikchr_grammar_staging(app_handle, &workspace_name, &session_type);
         let base_branch = branch.base_branch.clone();
         let store_for_context = Arc::clone(store);
         let branch_id_for_context = branch_id.to_string();
         let project_id_for_context = branch.project_id.clone();
-        let ctx = tauri::async_runtime::spawn_blocking(move || {
+        let remote_context = tauri::async_runtime::spawn_blocking(move || {
             build_remote_branch_context(
                 &workspace_name,
                 &base_branch,
                 &store_for_context,
                 &branch_id_for_context,
                 &project_id_for_context,
+                pikchr_grammar_staging,
             )
         })
         .await
         .map_err(|e| format!("Failed to build remote branch context: {e}"))?;
-        (fallback_dir, ctx)
+        (
+            fallback_dir,
+            remote_context.branch_context,
+            remote_context.pikchr_grammar_reference,
+        )
     } else {
         let workdir = store
             .get_workdir_for_branch(branch_id)
@@ -1229,7 +1325,9 @@ async fn prepare_branch_session_start(
             branch_id,
             &branch.project_id,
         );
-        (worktree_path, ctx)
+        let pikchr_grammar_reference =
+            local_pikchr_grammar_reference_for_session(app_handle, &session_type);
+        (worktree_path, ctx, pikchr_grammar_reference)
     };
 
     let pre_head_sha = if matches!(session_type, BranchSessionType::Commit) {
@@ -1273,8 +1371,6 @@ async fn prepare_branch_session_start(
 
     // Build the full prompt with action instructions + project information + branch context.
     let project_information = build_project_context(store, &project, &branch);
-    let pikchr_grammar_reference =
-        resolve_pikchr_grammar_reference(app_handle, branch.workspace_name.as_deref());
     let full_prompt = build_full_prompt_with_pikchr_reference(
         prompt,
         &project_information,
@@ -1790,27 +1886,34 @@ async fn start_queued_session_for_branch(
     };
 
     // Resolve working directory and branch context.
-    let (working_dir, branch_context) = if is_remote {
+    let (working_dir, branch_context, pikchr_grammar_reference) = if is_remote {
         let fallback_dir = resolve_branch_repo_slug(&store, &project, &branch)
             .and_then(|repo| crate::paths::repos_dir().map(|d| d.join(repo)))
             .unwrap_or_else(|| PathBuf::from("/tmp"));
         let workspace_name = branch.workspace_name.as_deref().unwrap().to_string();
+        let pikchr_grammar_staging =
+            remote_pikchr_grammar_staging(&app_handle, &workspace_name, &session_type);
         let base_branch = branch.base_branch.clone();
         let store_for_context = Arc::clone(&store);
         let branch_id_for_context = branch_id.clone();
         let project_id_for_context = branch.project_id.clone();
-        let ctx = tauri::async_runtime::spawn_blocking(move || {
+        let remote_context = tauri::async_runtime::spawn_blocking(move || {
             build_remote_branch_context(
                 &workspace_name,
                 &base_branch,
                 &store_for_context,
                 &branch_id_for_context,
                 &project_id_for_context,
+                pikchr_grammar_staging,
             )
         })
         .await
         .map_err(|e| format!("Failed to build remote branch context: {e}"))?;
-        (fallback_dir, ctx)
+        (
+            fallback_dir,
+            remote_context.branch_context,
+            remote_context.pikchr_grammar_reference,
+        )
     } else {
         let workdir = store
             .get_workdir_for_branch(&branch_id)
@@ -1838,13 +1941,13 @@ async fn start_queued_session_for_branch(
             &branch_id,
             &branch.project_id,
         );
-        (worktree_path, ctx)
+        let pikchr_grammar_reference =
+            local_pikchr_grammar_reference_for_session(&app_handle, &session_type);
+        (worktree_path, ctx, pikchr_grammar_reference)
     };
 
     // Build the full prompt with context.
     let project_information = build_project_context(&store, &project, &branch);
-    let pikchr_grammar_reference =
-        resolve_pikchr_grammar_reference(&app_handle, branch.workspace_name.as_deref());
     let full_prompt = build_full_prompt_with_pikchr_reference(
         &prompt,
         &project_information,
@@ -2138,18 +2241,19 @@ pub async fn trigger_auto_review(
         let store_for_context = Arc::clone(&store);
         let branch_id_for_context = branch_id.clone();
         let project_id_for_context = branch.project_id.clone();
-        let ctx = tauri::async_runtime::spawn_blocking(move || {
+        let remote_context = tauri::async_runtime::spawn_blocking(move || {
             build_remote_branch_context(
                 &workspace_name,
                 &base_branch,
                 &store_for_context,
                 &branch_id_for_context,
                 &project_id_for_context,
+                RemotePikchrGrammarStaging::NotNeeded,
             )
         })
         .await
         .map_err(|e| format!("Failed to build remote branch context: {e}"))?;
-        (fallback_dir, ctx)
+        (fallback_dir, remote_context.branch_context)
     } else {
         let workdir = store
             .get_workdir_for_branch(&branch_id)
@@ -2445,13 +2549,19 @@ pub(crate) fn build_branch_context(
 ///
 /// Uses `blox ws_exec` to run git commands inside the remote workspace,
 /// and reads notes from the DB (which works regardless of worktree location).
-pub(crate) fn build_remote_branch_context(
+struct RemoteBranchContext {
+    branch_context: String,
+    pikchr_grammar_reference: String,
+}
+
+fn build_remote_branch_context(
     workspace_name: &str,
     base_branch: &str,
     store: &Arc<Store>,
     branch_id: &str,
     project_id: &str,
-) -> String {
+    pikchr_grammar_staging: RemotePikchrGrammarStaging,
+) -> RemoteBranchContext {
     let mut parts = vec![context_preamble()];
     let mut timeline: Vec<TimelineEntry> = Vec::new();
     let mut visible_shas: HashSet<String> = HashSet::new();
@@ -2489,9 +2599,16 @@ pub(crate) fn build_remote_branch_context(
         }
     }
 
-    // Notes, reviews, images, and project notes written to temp files inside
-    // the remote workspace via ws_exec — run in parallel to reduce round trips.
+    // Notes, reviews, images, project notes, and optional Pikchr grammar are
+    // written to remote temp files in parallel to reduce ws_exec round trips.
     let max_commit_ts = timeline.iter().map(|e| e.timestamp).max();
+    let mut pikchr_grammar_reference = match &pikchr_grammar_staging {
+        RemotePikchrGrammarStaging::UseRemotePath => PIKCHR_GRAMMAR_REMOTE_PATH.to_string(),
+        RemotePikchrGrammarStaging::NotNeeded
+        | RemotePikchrGrammarStaging::Upload(_)
+        | RemotePikchrGrammarStaging::FallbackUrl => PIKCHR_GRAMMAR_URL.to_string(),
+    };
+
     std::thread::scope(|s| {
         let note_handle = s.spawn(|| note_timeline_entries(store, branch_id, Some(workspace_name)));
         let visible_shas = &visible_shas;
@@ -2508,6 +2625,15 @@ pub(crate) fn build_remote_branch_context(
             s.spawn(|| image_timeline_entries(store, branch_id, Some(workspace_name), project_id));
         let project_note_handle =
             s.spawn(|| project_note_timeline_entries(store, project_id, Some(workspace_name)));
+        let pikchr_grammar_handle =
+            match &pikchr_grammar_staging {
+                RemotePikchrGrammarStaging::Upload(bytes) => Some(s.spawn(move || {
+                    upload_pikchr_grammar_to_remote(workspace_name, bytes.as_slice())
+                })),
+                RemotePikchrGrammarStaging::NotNeeded
+                | RemotePikchrGrammarStaging::UseRemotePath
+                | RemotePikchrGrammarStaging::FallbackUrl => None,
+            };
 
         match note_handle.join() {
             Ok(entries) => timeline.extend(entries),
@@ -2525,10 +2651,19 @@ pub(crate) fn build_remote_branch_context(
             Ok(entries) => timeline.extend(entries),
             Err(_) => log::error!("project_note_timeline_entries thread panicked"),
         }
+        if let Some(handle) = pikchr_grammar_handle {
+            match handle.join() {
+                Ok(reference) => pikchr_grammar_reference = reference,
+                Err(_) => log::error!("Pikchr grammar upload thread panicked"),
+            }
+        }
     });
 
     parts.push(render_timeline(timeline, None));
-    parts.join("\n\n")
+    RemoteBranchContext {
+        branch_context: parts.join("\n\n"),
+        pikchr_grammar_reference,
+    }
 }
 
 /// Shared preamble for branch context blocks.

From 7d4f363e7485ed398159fe8c4e0e27c8542f4621 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 18:13:35 +1000
Subject: [PATCH 17/20] fix(notes): use unique remote Pikchr grammar paths

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src-tauri/src/session_commands.rs | 174 +++++++++++-------
 1 file changed, 107 insertions(+), 67 deletions(-)

diff --git a/apps/staged/src-tauri/src/session_commands.rs b/apps/staged/src-tauri/src/session_commands.rs
index 45c00e06..9cff3599 100644
--- a/apps/staged/src-tauri/src/session_commands.rs
+++ b/apps/staged/src-tauri/src/session_commands.rs
@@ -32,13 +32,13 @@ use crate::session_runner::{self, SessionConfig};
 use crate::store::{self, Store};
 
 const PIKCHR_GRAMMAR_RESOURCE: &str = "resources/pikchr/grammar.md";
-const PIKCHR_GRAMMAR_REMOTE_PATH: &str = "/tmp/staged-pikchr-grammar.md";
+const PIKCHR_GRAMMAR_REMOTE_PATH_PREFIX: &str = "/tmp/staged-pikchr-grammar-";
+const PIKCHR_GRAMMAR_REMOTE_PATH_SUFFIX: &str = ".md";
 pub(crate) const PIKCHR_GRAMMAR_URL: &str = "https://pikchr.org/home/doc/trunk/doc/grammar.md";
 
 enum RemotePikchrGrammarStaging {
     NotNeeded,
-    UseRemotePath,
-    Upload(Vec<u8>),
+    Upload { bytes: Vec<u8>, remote_path: String },
     FallbackUrl,
 }
 
@@ -97,25 +97,6 @@ fn bundled_pikchr_grammar_path(app_handle: &tauri::AppHandle) -> Option<PathBuf>
     None
 }
 
-fn pikchr_grammar_remote_uploads() -> &'static Mutex<HashSet<String>> {
-    static UPLOADS: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();
-    UPLOADS.get_or_init(|| Mutex::new(HashSet::new()))
-}
-
-fn has_uploaded_pikchr_grammar(workspace_name: &str) -> bool {
-    pikchr_grammar_remote_uploads()
-        .lock()
-        .unwrap()
-        .contains(workspace_name)
-}
-
-fn mark_pikchr_grammar_uploaded(workspace_name: &str) {
-    pikchr_grammar_remote_uploads()
-        .lock()
-        .unwrap()
-        .insert(workspace_name.to_string());
-}
-
 fn bundled_pikchr_grammar_bytes(app_handle: &tauri::AppHandle) -> Option<Vec<u8>> {
     let Some(grammar_path) = bundled_pikchr_grammar_path(app_handle) else {
         log::warn!("Bundled Pikchr grammar resource not found; falling back to public URL");
@@ -134,21 +115,26 @@ fn bundled_pikchr_grammar_bytes(app_handle: &tauri::AppHandle) -> Option<Vec<u8>
     }
 }
 
+fn generated_pikchr_grammar_remote_path() -> String {
+    format!(
+        "{PIKCHR_GRAMMAR_REMOTE_PATH_PREFIX}{}{PIKCHR_GRAMMAR_REMOTE_PATH_SUFFIX}",
+        uuid::Uuid::new_v4()
+    )
+}
+
 fn remote_pikchr_grammar_staging(
     app_handle: &tauri::AppHandle,
-    workspace_name: &str,
     session_type: &BranchSessionType,
 ) -> RemotePikchrGrammarStaging {
     if !matches!(session_type, BranchSessionType::Note) {
         return RemotePikchrGrammarStaging::NotNeeded;
     }
 
-    if has_uploaded_pikchr_grammar(workspace_name) {
-        return RemotePikchrGrammarStaging::UseRemotePath;
-    }
-
     match bundled_pikchr_grammar_bytes(app_handle) {
-        Some(bytes) => RemotePikchrGrammarStaging::Upload(bytes),
+        Some(bytes) => RemotePikchrGrammarStaging::Upload {
+            bytes,
+            remote_path: generated_pikchr_grammar_remote_path(),
+        },
         None => RemotePikchrGrammarStaging::FallbackUrl,
     }
 }
@@ -164,16 +150,17 @@ fn local_pikchr_grammar_reference_for_session(
     }
 }
 
-fn upload_pikchr_grammar_to_remote(workspace_name: &str, bytes: &[u8]) -> String {
-    if has_uploaded_pikchr_grammar(workspace_name) {
-        return PIKCHR_GRAMMAR_REMOTE_PATH.to_string();
-    }
-
-    match write_bytes_to_remote(workspace_name, bytes, PIKCHR_GRAMMAR_REMOTE_PATH) {
-        Ok(()) => {
-            mark_pikchr_grammar_uploaded(workspace_name);
-            PIKCHR_GRAMMAR_REMOTE_PATH.to_string()
-        }
+fn upload_pikchr_grammar_to_remote_with_writer<F>(
+    workspace_name: &str,
+    bytes: &[u8],
+    remote_path: String,
+    write: F,
+) -> String
+where
+    F: FnOnce(&str, &[u8], &str) -> Result<(), String>,
+{
+    match write(workspace_name, bytes, &remote_path) {
+        Ok(()) => remote_path,
         Err(e) => {
             log::warn!("Failed to copy Pikchr grammar to remote workspace {workspace_name}: {e}");
             PIKCHR_GRAMMAR_URL.to_string()
@@ -181,16 +168,23 @@ fn upload_pikchr_grammar_to_remote(workspace_name: &str, bytes: &[u8]) -> String
     }
 }
 
+fn upload_pikchr_grammar_to_remote(
+    workspace_name: &str,
+    bytes: &[u8],
+    remote_path: String,
+) -> String {
+    upload_pikchr_grammar_to_remote_with_writer(
+        workspace_name,
+        bytes,
+        remote_path,
+        write_bytes_to_remote,
+    )
+}
+
 pub(crate) fn resolve_pikchr_grammar_reference(
     app_handle: &tauri::AppHandle,
     workspace_name: Option<&str>,
 ) -> String {
-    if let Some(workspace_name) = workspace_name {
-        if has_uploaded_pikchr_grammar(workspace_name) {
-            return PIKCHR_GRAMMAR_REMOTE_PATH.to_string();
-        }
-    }
-
     let Some(grammar_path) = bundled_pikchr_grammar_path(app_handle) else {
         log::warn!("Bundled Pikchr grammar resource not found; falling back to public URL");
         return PIKCHR_GRAMMAR_URL.to_string();
@@ -198,7 +192,11 @@ pub(crate) fn resolve_pikchr_grammar_reference(
 
     if let Some(workspace_name) = workspace_name {
         return match std::fs::read(&grammar_path) {
-            Ok(bytes) => upload_pikchr_grammar_to_remote(workspace_name, &bytes),
+            Ok(bytes) => upload_pikchr_grammar_to_remote(
+                workspace_name,
+                &bytes,
+                generated_pikchr_grammar_remote_path(),
+            ),
             Err(e) => {
                 log::warn!(
                     "Failed to read bundled Pikchr grammar at {}: {e}",
@@ -1272,8 +1270,7 @@ async fn prepare_branch_session_start(
             .and_then(|repo| crate::paths::repos_dir().map(|d| d.join(repo)))
             .unwrap_or_else(|| PathBuf::from("/tmp"));
         let workspace_name = branch.workspace_name.as_deref().unwrap().to_string();
-        let pikchr_grammar_staging =
-            remote_pikchr_grammar_staging(app_handle, &workspace_name, &session_type);
+        let pikchr_grammar_staging = remote_pikchr_grammar_staging(app_handle, &session_type);
         let base_branch = branch.base_branch.clone();
         let store_for_context = Arc::clone(store);
         let branch_id_for_context = branch_id.to_string();
@@ -1891,8 +1888,7 @@ async fn start_queued_session_for_branch(
             .and_then(|repo| crate::paths::repos_dir().map(|d| d.join(repo)))
             .unwrap_or_else(|| PathBuf::from("/tmp"));
         let workspace_name = branch.workspace_name.as_deref().unwrap().to_string();
-        let pikchr_grammar_staging =
-            remote_pikchr_grammar_staging(&app_handle, &workspace_name, &session_type);
+        let pikchr_grammar_staging = remote_pikchr_grammar_staging(&app_handle, &session_type);
         let base_branch = branch.base_branch.clone();
         let store_for_context = Arc::clone(&store);
         let branch_id_for_context = branch_id.clone();
@@ -2602,12 +2598,7 @@ fn build_remote_branch_context(
     // Notes, reviews, images, project notes, and optional Pikchr grammar are
     // written to remote temp files in parallel to reduce ws_exec round trips.
     let max_commit_ts = timeline.iter().map(|e| e.timestamp).max();
-    let mut pikchr_grammar_reference = match &pikchr_grammar_staging {
-        RemotePikchrGrammarStaging::UseRemotePath => PIKCHR_GRAMMAR_REMOTE_PATH.to_string(),
-        RemotePikchrGrammarStaging::NotNeeded
-        | RemotePikchrGrammarStaging::Upload(_)
-        | RemotePikchrGrammarStaging::FallbackUrl => PIKCHR_GRAMMAR_URL.to_string(),
-    };
+    let mut pikchr_grammar_reference = PIKCHR_GRAMMAR_URL.to_string();
 
     std::thread::scope(|s| {
         let note_handle = s.spawn(|| note_timeline_entries(store, branch_id, Some(workspace_name)));
@@ -2625,15 +2616,15 @@ fn build_remote_branch_context(
             s.spawn(|| image_timeline_entries(store, branch_id, Some(workspace_name), project_id));
         let project_note_handle =
             s.spawn(|| project_note_timeline_entries(store, project_id, Some(workspace_name)));
-        let pikchr_grammar_handle =
-            match &pikchr_grammar_staging {
-                RemotePikchrGrammarStaging::Upload(bytes) => Some(s.spawn(move || {
-                    upload_pikchr_grammar_to_remote(workspace_name, bytes.as_slice())
-                })),
-                RemotePikchrGrammarStaging::NotNeeded
-                | RemotePikchrGrammarStaging::UseRemotePath
-                | RemotePikchrGrammarStaging::FallbackUrl => None,
-            };
+        let pikchr_grammar_handle = match &pikchr_grammar_staging {
+            RemotePikchrGrammarStaging::Upload { bytes, remote_path } => {
+                let remote_path = remote_path.clone();
+                Some(s.spawn(move || {
+                    upload_pikchr_grammar_to_remote(workspace_name, bytes.as_slice(), remote_path)
+                }))
+            }
+            RemotePikchrGrammarStaging::NotNeeded | RemotePikchrGrammarStaging::FallbackUrl => None,
+        };
 
         match note_handle.join() {
             Ok(entries) => timeline.extend(entries),
@@ -4459,6 +4450,55 @@ mod tests {
         assert!(prompt.contains(reference));
     }
 
+    #[test]
+    fn generated_remote_pikchr_grammar_paths_are_unique_temp_markdown_files() {
+        let first = generated_pikchr_grammar_remote_path();
+        let second = generated_pikchr_grammar_remote_path();
+
+        assert_ne!(first, second);
+        for path in [first, second] {
+            assert!(path.starts_with(PIKCHR_GRAMMAR_REMOTE_PATH_PREFIX));
+            assert!(path.ends_with(PIKCHR_GRAMMAR_REMOTE_PATH_SUFFIX));
+
+            let uuid_part = path
+                .strip_prefix(PIKCHR_GRAMMAR_REMOTE_PATH_PREFIX)
+                .and_then(|path| path.strip_suffix(PIKCHR_GRAMMAR_REMOTE_PATH_SUFFIX))
+                .expect("generated path should contain a UUID between prefix and suffix");
+            uuid::Uuid::parse_str(uuid_part).expect("generated path should include a UUID");
+        }
+    }
+
+    #[test]
+    fn successful_remote_pikchr_grammar_upload_returns_generated_path() {
+        let expected_path = generated_pikchr_grammar_remote_path();
+        let returned_path = upload_pikchr_grammar_to_remote_with_writer(
+            "test-workspace",
+            b"grammar bytes",
+            expected_path.clone(),
+            |workspace_name, bytes, remote_path| {
+                assert_eq!(workspace_name, "test-workspace");
+                assert_eq!(bytes, b"grammar bytes");
+                assert_eq!(remote_path, expected_path);
+                Ok(())
+            },
+        );
+
+        assert_eq!(returned_path, expected_path);
+    }
+
+    #[test]
+    fn failed_remote_pikchr_grammar_upload_falls_back_to_public_url() {
+        let generated_path = generated_pikchr_grammar_remote_path();
+        let returned_path = upload_pikchr_grammar_to_remote_with_writer(
+            "test-workspace",
+            b"grammar bytes",
+            generated_path,
+            |_workspace_name, _bytes, _remote_path| Err("remote unavailable".to_string()),
+        );
+
+        assert_eq!(returned_path, PIKCHR_GRAMMAR_URL);
+    }
+
     #[test]
     fn local_project_session_prompt_includes_timeline_reference_guidance() {
         let prompt = build_project_session_action_instructions_with_pikchr_reference(
@@ -4525,12 +4565,12 @@ mod tests {
 
     #[test]
     fn note_followup_prompt_uses_supplied_remote_pikchr_reference() {
-        let prompt =
-            build_note_followup_message_with_pikchr_reference(false, PIKCHR_GRAMMAR_REMOTE_PATH);
+        let remote_path = generated_pikchr_grammar_remote_path();
+        let prompt = build_note_followup_message_with_pikchr_reference(false, &remote_path);
 
         assert!(prompt.contains("The user is asking you to write the linked note"));
         assert!(prompt.contains("Please write the note for this session."));
-        assert_pikchr_note_guidance(&prompt, PIKCHR_GRAMMAR_REMOTE_PATH);
+        assert_pikchr_note_guidance(&prompt, &remote_path);
     }
 
     #[test]

From 04f44eb9b9d7c02db52fb03ab1c913f0f964a6d7 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 18:56:05 +1000
Subject: [PATCH 18/20] fix(notes): avoid blocking note follow-up prompts

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 apps/staged/src-tauri/src/session_commands.rs | 74 ++++++++++---------
 1 file changed, 39 insertions(+), 35 deletions(-)

diff --git a/apps/staged/src-tauri/src/session_commands.rs b/apps/staged/src-tauri/src/session_commands.rs
index 9cff3599..98b0a660 100644
--- a/apps/staged/src-tauri/src/session_commands.rs
+++ b/apps/staged/src-tauri/src/session_commands.rs
@@ -607,7 +607,7 @@ pub(crate) fn infer_branch_resume_session_type(prompt: &str) -> Option<&'static
 }
 
 #[tauri::command]
-pub fn build_note_followup_message(
+pub async fn build_note_followup_message(
     store: tauri::State<'_, Mutex<Option<Arc<Store>>>>,
     app_handle: tauri::AppHandle,
     session_id: String,
@@ -616,42 +616,46 @@ pub fn build_note_followup_message(
 ) -> Result<String, String> {
     let store = get_store(&store)?;
 
-    store
-        .get_session(&session_id)
-        .map_err(|e| e.to_string())?
-        .ok_or_else(|| format!("Session not found: {session_id}"))?;
-
-    let linked_commit = store.get_commit_by_session(&session_id).ok().flatten();
-    let linked_note = store.get_note_by_session(&session_id).ok().flatten();
-    let linked_review = store.get_review_by_session(&session_id).ok().flatten();
-
-    let branch_from_id = branch_id
-        .as_deref()
-        .and_then(|bid| store.get_branch(bid).ok().flatten());
-
-    let linked_branch = if branch_from_id.is_some() {
-        branch_from_id
-    } else if let Some(commit) = &linked_commit {
-        store.get_branch(&commit.branch_id).ok().flatten()
-    } else if let Some(note) = &linked_note {
-        store.get_branch(&note.branch_id).ok().flatten()
-    } else if let Some(review) = &linked_review {
-        store.get_branch(&review.branch_id).ok().flatten()
-    } else {
-        None
-    };
+    tauri::async_runtime::spawn_blocking(move || {
+        store
+            .get_session(&session_id)
+            .map_err(|e| e.to_string())?
+            .ok_or_else(|| format!("Session not found: {session_id}"))?;
+
+        let linked_commit = store.get_commit_by_session(&session_id).ok().flatten();
+        let linked_note = store.get_note_by_session(&session_id).ok().flatten();
+        let linked_review = store.get_review_by_session(&session_id).ok().flatten();
+
+        let branch_from_id = branch_id
+            .as_deref()
+            .and_then(|bid| store.get_branch(bid).ok().flatten());
+
+        let linked_branch = if branch_from_id.is_some() {
+            branch_from_id
+        } else if let Some(commit) = &linked_commit {
+            store.get_branch(&commit.branch_id).ok().flatten()
+        } else if let Some(note) = &linked_note {
+            store.get_branch(&note.branch_id).ok().flatten()
+        } else if let Some(review) = &linked_review {
+            store.get_branch(&review.branch_id).ok().flatten()
+        } else {
+            None
+        };
 
-    let pikchr_grammar_reference = resolve_pikchr_grammar_reference(
-        &app_handle,
-        linked_branch
-            .as_ref()
-            .and_then(|branch| branch.workspace_name.as_deref()),
-    );
+        let pikchr_grammar_reference = resolve_pikchr_grammar_reference(
+            &app_handle,
+            linked_branch
+                .as_ref()
+                .and_then(|branch| branch.workspace_name.as_deref()),
+        );
 
-    Ok(build_note_followup_message_with_pikchr_reference(
-        has_parsed_note,
-        &pikchr_grammar_reference,
-    ))
+        Ok(build_note_followup_message_with_pikchr_reference(
+            has_parsed_note,
+            &pikchr_grammar_reference,
+        ))
+    })
+    .await
+    .map_err(|e| format!("Failed to build note follow-up message: {e}"))?
 }
 
 #[tauri::command]

From 92cc1926086f1560b211415fb0d6284f39324093 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 19:11:57 +1000
Subject: [PATCH 19/20] fix(notes): guard note follow-up session sends

Signed-off-by: Matt Toohey <contact@matttoohey.com>
---
 .../lib/features/sessions/SessionModal.svelte | 30 +++++++++++++++----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/apps/staged/src/lib/features/sessions/SessionModal.svelte b/apps/staged/src/lib/features/sessions/SessionModal.svelte
index d0fea57b..4f219a09 100644
--- a/apps/staged/src/lib/features/sessions/SessionModal.svelte
+++ b/apps/staged/src/lib/features/sessions/SessionModal.svelte
@@ -114,6 +114,11 @@
     onOpenNote?: (note: LinkedNoteContext) => void;
   }
 
+  type SendMessageTarget = {
+    sessionId: string;
+    branchId: string | null;
+  };
+
   let {
     open,
     sessionId,
@@ -572,12 +577,20 @@
   }
 
   /** Actually send a message to the backend and start the agent. */
-  async function sendMessage(text: string, imageIds?: string[], sendingLocked = false) {
-    if (!session || (!sendingLocked && sending)) return;
+  async function sendMessage(
+    text: string,
+    imageIds?: string[],
+    sendingLocked = false,
+    target: SendMessageTarget | null = null
+  ) {
+    const targetSessionId = target?.sessionId ?? session?.id;
+    const targetBranchId = target ? target.branchId : (branchId ?? null);
+    if (!targetSessionId || session?.id !== targetSessionId || (!sendingLocked && sending)) return;
     if (!sendingLocked) sending = true;
     error = null;
     try {
-      await resumeSession(session.id, text, imageIds, branchId);
+      await resumeSession(targetSessionId, text, imageIds, targetBranchId);
+      if (session?.id !== targetSessionId) return;
       // Backend sets status to running and emits an event.
       // Force an immediate poll to pick up the new user message + status.
       session = { ...session, status: 'running' };
@@ -594,11 +607,18 @@
 
   async function handleNoteFollowupClick() {
     if (!session || !noteInfo || sending) return;
+    const target: SendMessageTarget = { sessionId: session.id, branchId: branchId ?? null };
+    const hasParsedNote = noteInfo.hasParsedNote;
     sending = true;
     error = null;
     try {
-      const prompt = await buildNoteFollowupMessage(session.id, branchId, noteInfo.hasParsedNote);
-      await sendMessage(prompt, undefined, true);
+      const prompt = await buildNoteFollowupMessage(
+        target.sessionId,
+        target.branchId,
+        hasParsedNote
+      );
+      if (session?.id !== target.sessionId || (branchId ?? null) !== target.branchId) return;
+      await sendMessage(prompt, undefined, true, target);
     } catch (e) {
       error = `Failed to send: ${e instanceof Error ? e.message : String(e)}`;
       messageQueue = [];

From ef9ab9d1259610455b65e622b377e091889c0418 Mon Sep 17 00:00:00 2001
From: Matt Toohey <contact@matttoohey.com>
Date: Thu, 25 Jun 2026 20:27:36 +1000
Subject: [PATCH 20/20] fix(notes): avoid needless Pikchr grammar borrow

---
 apps/staged/src-tauri/src/web_server.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/staged/src-tauri/src/web_server.rs b/apps/staged/src-tauri/src/web_server.rs
index f6bd92c6..7841e82d 100644
--- a/apps/staged/src-tauri/src/web_server.rs
+++ b/apps/staged/src-tauri/src/web_server.rs
@@ -2909,7 +2909,7 @@ async fn dispatch(command: &str, args: Value, state: &WebAppState) -> Result<Val
 
             let is_remote = project.location == store::ProjectLocation::Remote;
             let pikchr_grammar_reference =
-                session_commands::resolve_pikchr_grammar_reference(&app_handle, None);
+                session_commands::resolve_pikchr_grammar_reference(app_handle, None);
             let action_instructions =
                 session_commands::build_project_session_action_instructions_with_pikchr_reference(
                     is_remote,