From 0bedbaa7114f798843e8db19464f9132c1044fd5 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Thu, 26 Feb 2026 11:15:50 +0100
Subject: [PATCH 01/12] =?UTF-8?q?=E2=9C=A8=20feat(frontend):=20add=20Story?=
 =?UTF-8?q?book=20configuration=20with=20UnifiedMarkdownViewer=20story?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add Storybook setup for frontend app with dedicated Vite config to avoid React Router plugin conflicts. Includes example story for UnifiedMarkdownViewer component demonstrating markdown diff highlighting.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 apps/frontend/.storybook/main.ts              | 17 ++++
 apps/frontend/.storybook/preview.tsx          | 35 ++++++++
 apps/frontend/.storybook/vite.config.ts       | 35 ++++++++
 apps/frontend/project.json                    | 17 ++++
 .../UnifiedMarkdownViewer.stories.tsx         | 79 +++++++++++++++++++
 5 files changed, 183 insertions(+)
 create mode 100644 apps/frontend/.storybook/main.ts
 create mode 100644 apps/frontend/.storybook/preview.tsx
 create mode 100644 apps/frontend/.storybook/vite.config.ts
 create mode 100644 apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx

diff --git a/apps/frontend/.storybook/main.ts b/apps/frontend/.storybook/main.ts
new file mode 100644
index 000000000..af123abf2
--- /dev/null
+++ b/apps/frontend/.storybook/main.ts
@@ -0,0 +1,17 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+import path from 'path';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
+  addons: [],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {
+      builder: {
+        viteConfigPath: path.resolve(__dirname, 'vite.config.ts'),
+      },
+    },
+  },
+};
+
+export default config;
diff --git a/apps/frontend/.storybook/preview.tsx b/apps/frontend/.storybook/preview.tsx
new file mode 100644
index 000000000..969f3026d
--- /dev/null
+++ b/apps/frontend/.storybook/preview.tsx
@@ -0,0 +1,35 @@
+import type { Preview } from '@storybook/react';
+import React from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UIProvider } from '@packmind/ui';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: false,
+      staleTime: Infinity,
+    },
+  },
+});
+
+const preview: Preview = {
+  decorators: [
+    (Story) => (
+      <QueryClientProvider client={queryClient}>
+        <UIProvider>
+          <Story />
+        </UIProvider>
+      </QueryClientProvider>
+    ),
+  ],
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+  },
+};
+
+export default preview;
diff --git a/apps/frontend/.storybook/vite.config.ts b/apps/frontend/.storybook/vite.config.ts
new file mode 100644
index 000000000..9b6086c95
--- /dev/null
+++ b/apps/frontend/.storybook/vite.config.ts
@@ -0,0 +1,35 @@
+import { defineConfig } from 'vite';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+import path from 'path';
+
+export default defineConfig(() => {
+  // Determine edition mode (defaults to OSS if not explicitly set to 'proprietary')
+  const isOssMode = process.env.PACKMIND_EDITION !== 'proprietary';
+
+  // Configure resolve aliases based on edition
+  const resolveAliases = isOssMode
+    ? {
+        '@packmind/proprietary/frontend': path.resolve(
+          __dirname,
+          '../src/domain/editions/stubs',
+        ),
+      }
+    : {
+        '@packmind/proprietary/frontend': path.resolve(__dirname, '../src'),
+      };
+
+  return {
+    root: path.resolve(__dirname, '..'),
+    cacheDir: '../../../node_modules/.vite/apps/frontend-storybook',
+    assetsInclude: ['**/*.svg', '**/*.png'],
+    define: {
+      __PACKMIND_EDITION__: JSON.stringify(
+        process.env.PACKMIND_EDITION || 'oss',
+      ),
+    },
+    resolve: {
+      alias: resolveAliases,
+    },
+    plugins: [nxViteTsPaths()],
+  };
+});
diff --git a/apps/frontend/project.json b/apps/frontend/project.json
index 5f462e0ee..791cf0943 100644
--- a/apps/frontend/project.json
+++ b/apps/frontend/project.json
@@ -26,6 +26,23 @@
       "options": {
         "command": "nx dev frontend"
       }
+    },
+    "storybook": {
+      "executor": "nx:run-commands",
+      "continuous": true,
+      "options": {
+        "cwd": "apps/frontend",
+        "command": "storybook dev -p 6006"
+      }
+    },
+    "build-storybook": {
+      "executor": "nx:run-commands",
+      "cache": true,
+      "outputs": ["{projectRoot}/storybook-static"],
+      "options": {
+        "cwd": "apps/frontend",
+        "command": "storybook build"
+      }
     }
   }
 }
diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
new file mode 100644
index 000000000..26746593f
--- /dev/null
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { UnifiedMarkdownViewer } from './UnifiedMarkdownViewer';
+
+const meta: Meta<typeof UnifiedMarkdownViewer> = {
+  title: 'ChangeProposals/UnifiedMarkdownViewer',
+  component: UnifiedMarkdownViewer,
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const SimpleTextChange: Story = {
+  args: {
+    oldValue: 'This was my content',
+    newValue: 'This is my updated content',
+    proposalNumbers: [1],
+  },
+};
+
+export const MultipleProposals: Story = {
+  args: {
+    oldValue: 'This is my content',
+    newValue: 'This is my updated content',
+    proposalNumbers: [1, 2, 3],
+  },
+};
+
+export const MarkdownFormatting: Story = {
+  args: {
+    oldValue: `# Heading
+
+This is a paragraph with bold text.`,
+    newValue: `# Updated Heading
+
+This is a paragraph with **bold** text.`,
+    proposalNumbers: [1],
+  },
+};
+
+export const CodeBlock: Story = {
+  args: {
+    oldValue: `# Example
+
+\`\`\`javascript
+function hello() {
+  console.log('Hello');
+}
+\`\`\``,
+    newValue: `# Example
+
+\`\`\`javascript
+function hello(name) {
+  console.log('Hello, ' + name);
+}
+\`\`\``,
+    proposalNumbers: [1],
+  },
+};
+
+export const ListChanges: Story = {
+  args: {
+    oldValue: `# Todo List
+
+- Item 1
+- Item 2
+- Item 3`,
+    newValue: `# Todo List
+
+- Item 1
+- Updated Item 2
+- Item 3
+- Item 4`,
+    proposalNumbers: [1],
+  },
+};

From dd0edc9bcb4b685dbded11a643bd58a4f0d4760e Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Thu, 26 Feb 2026 12:00:20 +0100
Subject: [PATCH 02/12] WIP: use a single markdown viewer to show diff/unified
 views

---
 .../UnifiedMarkdownViewer.stories.tsx         |  10 +-
 .../components/UnifiedMarkdownViewer.tsx      |   8 +-
 .../utils/buildInlineDiffMarkdown.ts          |  13 ++
 .../change-proposals/utils/markdownDiff.ts    | 129 +++++++++++++++++-
 .../components/editor/DiffMarkdownEditor.tsx  |  45 +++++-
 5 files changed, 194 insertions(+), 11 deletions(-)
 create mode 100644 apps/frontend/src/domain/change-proposals/utils/buildInlineDiffMarkdown.ts

diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
index 26746593f..633a4c25a 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
@@ -8,6 +8,14 @@ const meta: Meta<typeof UnifiedMarkdownViewer> = {
     layout: 'padded',
   },
   tags: ['autodocs'],
+  argTypes: {
+    displayMode: {
+      control: 'radio',
+      options: ['unified', 'diff'],
+      description: 'Display mode for the markdown viewer',
+      value: 'unified',
+    },
+  },
 };
 
 export default meta;
@@ -33,7 +41,7 @@ export const MarkdownFormatting: Story = {
   args: {
     oldValue: `# Heading
 
-This is a paragraph with bold text.`,
+This is a paragraph with plain text.`,
     newValue: `# Updated Heading
 
 This is a paragraph with **bold** text.`,
diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.tsx
index 915eb0146..e4e6defbb 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.tsx
@@ -1,12 +1,16 @@
 import React from 'react';
 import { PMBox } from '@packmind/ui';
 import { MilkdownProvider } from '@milkdown/react';
-import { DiffMarkdownEditor } from '../../../shared/components/editor/DiffMarkdownEditor';
+import {
+  DiffMarkdownEditor,
+  IDiffMarkdownEditorProps,
+} from '../../../shared/components/editor/DiffMarkdownEditor';
 
 interface UnifiedMarkdownViewerProps {
   oldValue: string;
   newValue: string;
   proposalNumbers: number[];
+  displayMode?: IDiffMarkdownEditorProps['displayMode'];
 }
 
 /**
@@ -18,6 +22,7 @@ export function UnifiedMarkdownViewer({
   oldValue,
   newValue,
   proposalNumbers,
+  displayMode,
 }: UnifiedMarkdownViewerProps) {
   return (
     <PMBox data-diff-section>
@@ -26,6 +31,7 @@ export function UnifiedMarkdownViewer({
           oldValue={oldValue}
           newValue={newValue}
           proposalNumbers={proposalNumbers}
+          displayMode={displayMode ?? 'unified'}
           paddingVariant="none"
         />
       </MilkdownProvider>
diff --git a/apps/frontend/src/domain/change-proposals/utils/buildInlineDiffMarkdown.ts b/apps/frontend/src/domain/change-proposals/utils/buildInlineDiffMarkdown.ts
new file mode 100644
index 000000000..85688573d
--- /dev/null
+++ b/apps/frontend/src/domain/change-proposals/utils/buildInlineDiffMarkdown.ts
@@ -0,0 +1,13 @@
+import { buildDiffHtml } from './markdownDiff';
+
+/**
+ * Builds inline diff markdown content for the "diff" display mode.
+ * Uses buildDiffHtml to generate HTML with <ins> and <del> tags
+ * showing additions and deletions inline.
+ */
+export function buildInlineDiffMarkdown(
+  oldValue: string,
+  newValue: string,
+): string {
+  return buildDiffHtml(oldValue, newValue);
+}
diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownDiff.ts b/apps/frontend/src/domain/change-proposals/utils/markdownDiff.ts
index 1fc0cc683..53255e44b 100644
--- a/apps/frontend/src/domain/change-proposals/utils/markdownDiff.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownDiff.ts
@@ -1,5 +1,5 @@
 import { marked, Token, Tokens, TokensList } from 'marked';
-import { diffArrays, diffWords } from 'diff';
+import { diffArrays, diffWords, Change } from 'diff';
 
 function toTokensList(tokens: Token[]): TokensList {
   const list = tokens as TokensList;
@@ -15,6 +15,67 @@ function renderInlineContent(text: string): string {
   return marked.parseInline(text) as string;
 }
 
+/**
+ * Merge adjacent diff changes that are markdown syntax markers with their words.
+ * For example: [added: '**'], [unchanged: 'word'], [added: '**']
+ * becomes: [added: '**word**']
+ */
+function mergeMarkdownSyntax(changes: Change[]): Change[] {
+  const merged: Change[] = [];
+  let i = 0;
+
+  while (i < changes.length) {
+    const current = changes[i];
+
+    // Check if this looks like a markdown marker start
+    if (
+      (current.added || current.removed) &&
+      /^[*_`~]+$/.test(current.value.trim())
+    ) {
+      // Look ahead to find the matching closing marker
+      let j = i + 1;
+      let accumulatedValue = current.value;
+      let foundClosing = false;
+
+      while (j < changes.length) {
+        const next = changes[j];
+        accumulatedValue += next.value;
+
+        // Check if this is the closing marker
+        if (
+          (next.added || next.removed) &&
+          next.added === current.added &&
+          next.removed === current.removed &&
+          /^[*_`~]+$/.test(next.value.trim())
+        ) {
+          foundClosing = true;
+          // Merge all changes from i to j into one
+          merged.push({
+            added: current.added,
+            removed: current.removed,
+            value: accumulatedValue,
+            count: 1,
+          });
+          i = j + 1;
+          break;
+        }
+        j++;
+      }
+
+      if (!foundClosing) {
+        // No closing marker found, keep original
+        merged.push(current);
+        i++;
+      }
+    } else {
+      merged.push(current);
+      i++;
+    }
+  }
+
+  return merged;
+}
+
 function renderListAllMarked(list: Tokens.List, tag: 'del' | 'ins'): string {
   const listTag = list.ordered ? 'ol' : 'ul';
   const items = list.items
@@ -108,7 +169,9 @@ function renderWordDiffInBlock(
   blockTag: string,
 ): string {
   const changes = diffWords(oldToken.text, newToken.text);
-  const inlineHtml = changes
+  // Merge markdown syntax markers with their words
+  const mergedChanges = mergeMarkdownSyntax(changes);
+  const inlineHtml = mergedChanges
     .map((change) => {
       if (change.added)
         return `<ins>${renderInlineContent(change.value)}</ins>`;
@@ -193,6 +256,7 @@ function renderModifiedPair(oldToken: Token, newToken: Token): string {
 }
 
 export const markdownDiffCss = {
+  // Diff highlighting
   '& ins, & .diff-ins': {
     backgroundColor: 'var(--Palette-Semantic-Green800)',
     padding: '0 2px',
@@ -204,6 +268,52 @@ export const markdownDiffCss = {
     padding: '0 2px',
     borderRadius: '2px',
   },
+  // Markdown typography
+  '& h1': {
+    fontSize: '2em',
+    fontWeight: 'bold',
+    marginTop: '0.67em',
+    marginBottom: '0.67em',
+  },
+  '& h2': {
+    fontSize: '1.5em',
+    fontWeight: 'bold',
+    marginTop: '0.83em',
+    marginBottom: '0.83em',
+  },
+  '& h3': {
+    fontSize: '1.17em',
+    fontWeight: 'bold',
+    marginTop: '1em',
+    marginBottom: '1em',
+  },
+  '& strong': {
+    fontWeight: 'bold',
+  },
+  '& em': {
+    fontStyle: 'italic',
+  },
+  '& p': {
+    marginTop: '1em',
+    marginBottom: '1em',
+  },
+  '& code': {
+    fontFamily: 'monospace',
+    backgroundColor: 'var(--Palette-Neutral-300)',
+    padding: '2px 4px',
+    borderRadius: '3px',
+  },
+  '& pre': {
+    backgroundColor: 'var(--Palette-Neutral-200)',
+    padding: '1em',
+    borderRadius: '4px',
+    overflow: 'auto',
+  },
+  '& ul, & ol': {
+    marginTop: '1em',
+    marginBottom: '1em',
+    paddingLeft: '2em',
+  },
 };
 
 export function buildDiffHtml(oldValue: string, newValue: string): string {
@@ -237,7 +347,22 @@ export function buildDiffHtml(oldValue: string, newValue: string): string {
           parts.push(
             renderModifiedPair(oldTokens[oldIdx++], newTokens[newIdx++]),
           );
+        } else if (count === nextCount) {
+          // Same number of tokens changed - try to pair them up for word-level diffs
+          for (let i = 0; i < count; i++) {
+            const oldToken = oldTokens[oldIdx++];
+            const newToken = newTokens[newIdx++];
+            // If both tokens are the same type, do word-level diff
+            if (oldToken.type === newToken.type) {
+              parts.push(renderModifiedPair(oldToken, newToken));
+            } else {
+              // Different types - render as complete replacement
+              parts.push(renderDeletedToken(oldToken));
+              parts.push(renderAddedToken(newToken));
+            }
+          }
         } else {
+          // Different number of tokens - render all deletions then all additions
           for (let i = 0; i < count; i++) {
             parts.push(renderDeletedToken(oldTokens[oldIdx++]));
           }
diff --git a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
index 9641a32a6..dff7dc030 100644
--- a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
+++ b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
@@ -4,8 +4,10 @@ import '@packmind/assets/milkdown.theme';
 import { PMBox } from '@packmind/ui';
 import React, { useEffect, useRef, useMemo, useState } from 'react';
 import { buildUnifiedMarkdownDiff } from '../../../domain/change-proposals/utils/buildUnifiedMarkdownDiff';
+import { buildInlineDiffMarkdown } from '../../../domain/change-proposals/utils/buildInlineDiffMarkdown';
+import { markdownDiffCss } from '../../../domain/change-proposals/utils/markdownDiff';
 
-interface IDiffMarkdownEditorProps {
+export interface IDiffMarkdownEditorProps {
   /** Original markdown content before changes */
   oldValue: string;
   /** New markdown content after changes */
@@ -14,6 +16,7 @@ interface IDiffMarkdownEditorProps {
   proposalNumbers: number[];
   /** Padding variant for the editor */
   paddingVariant?: 'default' | 'none';
+  displayMode: 'unified' | 'diff';
 }
 
 /**
@@ -28,22 +31,32 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
   oldValue,
   newValue,
   proposalNumbers,
+  displayMode,
   paddingVariant = 'default',
 }) => {
   const editorRef = useRef<HTMLDivElement | null>(null);
   const [isEditorReady, setIsEditorReady] = useState(false);
 
+  // Build blocks for unified mode (for highlighting)
   const blocks = useMemo(
     () => buildUnifiedMarkdownDiff(oldValue, newValue),
     [oldValue, newValue],
   );
 
+  // Compute editor content based on display mode
+  const editorContent = useMemo(() => {
+    if (displayMode === 'diff') {
+      return buildInlineDiffMarkdown(oldValue, newValue);
+    }
+    return newValue;
+  }, [displayMode, oldValue, newValue]);
+
   useEditor((root) => {
     editorRef.current = root as HTMLDivElement;
 
     const crepe = new Crepe({
       root,
-      defaultValue: newValue,
+      defaultValue: editorContent,
       features: {
         [Crepe.Feature.ImageBlock]: false,
         [Crepe.Feature.Latex]: false,
@@ -60,8 +73,9 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
     return crepe;
   });
 
-  // Apply highlights to changed content after editor renders
+  // Apply highlights to changed content after editor renders (unified mode only)
   useEffect(() => {
+    if (displayMode !== 'unified') return; // Skip for diff mode
     if (!isEditorReady || !editorRef.current || blocks.length === 0) return;
 
     const changedBlocks = blocks.filter((b) => b.isChanged);
@@ -176,10 +190,11 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
         waitForProseMirror.disconnect();
       };
     }
-  }, [blocks, proposalNumbers, isEditorReady]);
+  }, [blocks, proposalNumbers, isEditorReady, displayMode]);
 
-  // Add hover handlers for tooltips
+  // Add hover handlers for tooltips (unified mode only)
   useEffect(() => {
+    if (displayMode !== 'unified') return; // Skip for diff mode
     if (!isEditorReady || !editorRef.current) return;
 
     const handleMouseEnter = (e: MouseEvent) => {
@@ -276,8 +291,24 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
       editor.removeEventListener('mouseout', handleMouseLeave);
       document.querySelectorAll('.diff-tooltip').forEach((el) => el.remove());
     };
-  }, [isEditorReady]);
-
+  }, [isEditorReady, displayMode, proposalNumbers]);
+
+  // For diff mode, render HTML directly without Milkdown
+  if (displayMode === 'diff') {
+    return (
+      <PMBox
+        data-milkdown-padding-variant={paddingVariant}
+        css={markdownDiffCss}
+        dangerouslySetInnerHTML={{ __html: editorContent }}
+        style={{
+          padding: paddingVariant === 'default' ? '16px' : '0',
+          minHeight: '100px',
+        }}
+      />
+    );
+  }
+
+  // For unified mode, use Milkdown with highlights
   return (
     <PMBox data-milkdown-padding-variant={paddingVariant}>
       <Milkdown />

From 4618219774ef9cd2850c92e37793b2e0463ec600 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Thu, 26 Feb 2026 14:56:11 +0100
Subject: [PATCH 03/12] Add plain mode in markdown viewer to simply show the
 new value

---
 .../UnifiedMarkdownViewer.stories.tsx         |  6 ++-
 .../components/editor/DiffMarkdownEditor.tsx  | 43 +++++++++++++++----
 2 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
index 633a4c25a..68a9ec235 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
@@ -11,7 +11,7 @@ const meta: Meta<typeof UnifiedMarkdownViewer> = {
   argTypes: {
     displayMode: {
       control: 'radio',
-      options: ['unified', 'diff'],
+      options: ['unified', 'diff', 'plain'],
       description: 'Display mode for the markdown viewer',
       value: 'unified',
     },
@@ -41,7 +41,9 @@ export const MarkdownFormatting: Story = {
   args: {
     oldValue: `# Heading
 
-This is a paragraph with plain text.`,
+This is a paragraph with plain text.
+
+This used to be a line.`,
     newValue: `# Updated Heading
 
 This is a paragraph with **bold** text.`,
diff --git a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
index dff7dc030..5096d056e 100644
--- a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
+++ b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
@@ -16,16 +16,17 @@ export interface IDiffMarkdownEditorProps {
   proposalNumbers: number[];
   /** Padding variant for the editor */
   paddingVariant?: 'default' | 'none';
-  displayMode: 'unified' | 'diff';
+  /** Display mode: 'unified' (highlights with tooltips), 'diff' (inline +/-), 'plain' (clean view) */
+  displayMode: 'unified' | 'diff' | 'plain';
 }
 
 /**
- * A specialized MarkdownEditor that displays diff highlighting and tooltips
- * for changed content. Uses a single Milkdown editor with highlights applied
- * via DOM manipulation after render.
+ * A specialized MarkdownEditor that supports three display modes:
+ * - 'unified': Displays the new content with highlights and tooltips showing what changed
+ * - 'diff': Displays inline diff with additions and deletions using HTML rendering
+ * - 'plain': Displays the new content without any diff highlighting (clean view)
  *
- * This component is read-only and designed for viewing unified diff views
- * of change proposals.
+ * This component is read-only and designed for viewing change proposals.
  */
 export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
   oldValue,
@@ -48,6 +49,7 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
     if (displayMode === 'diff') {
       return buildInlineDiffMarkdown(oldValue, newValue);
     }
+    // For 'unified' and 'plain' modes, use newValue
     return newValue;
   }, [displayMode, oldValue, newValue]);
 
@@ -75,7 +77,28 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
 
   // Apply highlights to changed content after editor renders (unified mode only)
   useEffect(() => {
-    if (displayMode !== 'unified') return; // Skip for diff mode
+    // Helper function to remove all highlights
+    const removeHighlights = () => {
+      if (!editorRef.current) return;
+      const proseMirrorEditor = editorRef.current.querySelector('.ProseMirror');
+      if (!proseMirrorEditor) return;
+
+      const highlightedElements = proseMirrorEditor.querySelectorAll(
+        '.milkdown-diff-highlight',
+      );
+      highlightedElements.forEach((element) => {
+        (element as HTMLElement).classList.remove('milkdown-diff-highlight');
+        (element as HTMLElement).removeAttribute('data-diff-html');
+        (element as HTMLElement).removeAttribute('data-proposal-numbers');
+      });
+    };
+
+    // If not in unified mode, remove any existing highlights and return
+    if (displayMode !== 'unified') {
+      removeHighlights();
+      return;
+    }
+
     if (!isEditorReady || !editorRef.current || blocks.length === 0) return;
 
     const changedBlocks = blocks.filter((b) => b.isChanged);
@@ -166,6 +189,7 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
       return () => {
         clearTimeout(initialCheck);
         observer.disconnect();
+        removeHighlights();
       };
     } else {
       // ProseMirror element not found yet - wait for it to be added
@@ -188,13 +212,14 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
 
       return () => {
         waitForProseMirror.disconnect();
+        removeHighlights();
       };
     }
   }, [blocks, proposalNumbers, isEditorReady, displayMode]);
 
   // Add hover handlers for tooltips (unified mode only)
   useEffect(() => {
-    if (displayMode !== 'unified') return; // Skip for diff mode
+    if (displayMode !== 'unified') return; // Skip for diff and plain modes
     if (!isEditorReady || !editorRef.current) return;
 
     const handleMouseEnter = (e: MouseEvent) => {
@@ -308,7 +333,7 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
     );
   }
 
-  // For unified mode, use Milkdown with highlights
+  // For unified and plain modes, use Milkdown with highlights (unified) or without (plain)
   return (
     <PMBox data-milkdown-padding-variant={paddingVariant}>
       <Milkdown />

From 1eb2ccc32826b34af4108a2588517b78fce0a431 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Thu, 26 Feb 2026 16:59:12 +0100
Subject: [PATCH 04/12] =?UTF-8?q?=E2=9C=A8=20feat(frontend):=20implement?=
 =?UTF-8?q?=20block-based=20markdown=20diff=20with=20similarity=20matching?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refactored markdown diffing system to use structured block parsing with intelligent
similarity matching for improved word-level diffs and better list item handling.

Key improvements:
- Parse markdown into typed blocks (heading, paragraph, list, code) with status tracking
- Match similar blocks using word overlap algorithm for accurate word-level diffs
- Rebuild markdown/HTML from blocks for unified, diff, and plain display modes
- Highlight changed list items individually in unified view with tooltips
- Comprehensive test coverage (26 tests) with single-assertion pattern

Technical changes:
- Add markdownBlockDiff.ts: Block parser with similarity-based matching (30% threshold)
- Add rebuildMarkdownFromBlocks.ts: Rebuild logic for different display modes
- Update DiffMarkdownEditor: Collect highlight targets from blocks and list items
- Add ComplexChanges story demonstrating the full user story example

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .../UnifiedMarkdownViewer.stories.tsx         |  50 +-
 .../utils/markdownBlockDiff.spec.ts           | 355 ++++++++++++++
 .../utils/markdownBlockDiff.ts                | 437 ++++++++++++++++++
 .../utils/rebuildMarkdownFromBlocks.spec.ts   | 217 +++++++++
 .../utils/rebuildMarkdownFromBlocks.ts        | 130 ++++++
 .../components/editor/DiffMarkdownEditor.tsx  |  74 ++-
 6 files changed, 1238 insertions(+), 25 deletions(-)
 create mode 100644 apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
 create mode 100644 apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
 create mode 100644 apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
 create mode 100644 apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts

diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
index 68a9ec235..e28f6307d 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
@@ -39,14 +39,27 @@ export const MultipleProposals: Story = {
 
 export const MarkdownFormatting: Story = {
   args: {
-    oldValue: `# Heading
+    oldValue: `# My title
 
-This is a paragraph with plain text.
+This was my content
 
-This used to be a line.`,
-    newValue: `# Updated Heading
+There was a line here.
 
-This is a paragraph with **bold** text.`,
+## My sub-heading
+
+My list:
+ - one item
+ - another item`,
+    newValue: `# My title
+
+This is my updated content
+
+## My sub-heading
+
+My list:
+ - first item
+ - a new item
+ - another item`,
     proposalNumbers: [1],
   },
 };
@@ -87,3 +100,30 @@ export const ListChanges: Story = {
     proposalNumbers: [1],
   },
 };
+
+export const ComplexChanges: Story = {
+  args: {
+    oldValue: `# My title
+
+This was my content
+
+There was a line here.
+
+## My sub-heading
+
+My list:
+ - one item
+ - another item`,
+    newValue: `# My title
+
+This is my updated content
+
+## My sub-heading
+
+My list:
+ - first item
+ - a new item
+ - another item`,
+    proposalNumbers: [1, 2],
+  },
+};
diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
new file mode 100644
index 000000000..91408af4e
--- /dev/null
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
@@ -0,0 +1,355 @@
+import { parseAndDiffMarkdown } from './markdownBlockDiff';
+
+describe('markdownBlockDiff', () => {
+  describe('parseAndDiffMarkdown', () => {
+    it('parses and diffs a simple text change', () => {
+      const oldValue = 'This was my content';
+      const newValue = 'This is my updated content';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'paragraph',
+          content: 'This is my updated content',
+          status: 'updated',
+          diffContent: expect.stringMatching(
+            /This <del>was<\/del><ins>is<\/ins> my <ins>updated <\/ins>content/,
+          ),
+        }),
+      ]);
+    });
+
+    it('handles heading blocks with level tracking', () => {
+      const oldValue = '# My title';
+      const newValue = '# My updated title';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'heading',
+          level: '#',
+          content: 'My updated title',
+          status: 'updated',
+          diffContent: expect.stringContaining('<ins>updated </ins>'),
+        }),
+      ]);
+    });
+
+    it('preserves unchanged blocks', () => {
+      const markdown = '# My title\n\nSome content that stays the same';
+
+      const result = parseAndDiffMarkdown(markdown, markdown);
+
+      expect(result).toEqual([
+        expect.objectContaining({ status: 'unchanged' }),
+        expect.objectContaining({ status: 'unchanged' }),
+      ]);
+    });
+
+    it('marks added blocks correctly', () => {
+      const oldValue = '# Title';
+      const newValue = '# Title\n\nNew paragraph';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            type: 'heading',
+            status: 'unchanged',
+          }),
+          expect.objectContaining({
+            type: 'paragraph',
+            content: 'New paragraph',
+            status: 'added',
+            diffContent: '<ins>New paragraph</ins>',
+          }),
+        ]),
+      );
+    });
+
+    it('marks deleted blocks correctly', () => {
+      const oldValue = '# Title\n\nParagraph to delete';
+      const newValue = '# Title';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            type: 'heading',
+            status: 'unchanged',
+          }),
+          expect.objectContaining({
+            type: 'paragraph',
+            content: 'Paragraph to delete',
+            status: 'deleted',
+            diffContent: '<del>Paragraph to delete</del>',
+          }),
+        ]),
+      );
+    });
+
+    it('handles the complex user story example correctly', () => {
+      const oldValue = `# My title
+
+This was my content
+
+There was a line here.
+
+## My sub-heading
+
+My list:
+ - one item
+ - another item`;
+
+      const newValue = `# My title
+
+This is my updated content
+
+## My sub-heading
+
+My list:
+ - first item
+ - a new item
+ - another item`;
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            type: 'heading',
+            level: '#',
+            content: 'My title',
+            status: 'unchanged',
+          }),
+          expect.objectContaining({
+            type: 'heading',
+            level: '##',
+            content: 'My sub-heading',
+            status: 'unchanged',
+          }),
+          expect.objectContaining({
+            type: 'paragraph',
+            content: 'This is my updated content',
+            status: 'updated',
+            diffContent: expect.stringMatching(
+              /<del>was<\/del>.*<ins>is<\/ins>/,
+            ),
+          }),
+          expect.objectContaining({
+            type: 'paragraph',
+            content: 'There was a line here.',
+            status: 'deleted',
+            diffContent: '<del>There was a line here.</del>',
+          }),
+          expect.objectContaining({
+            type: 'list',
+            status: 'updated',
+            items: expect.arrayContaining([
+              expect.objectContaining({
+                content: 'one item',
+                status: 'deleted',
+              }),
+              expect.objectContaining({
+                content: 'first item',
+                status: 'added',
+              }),
+              expect.objectContaining({
+                content: 'a new item',
+                status: 'added',
+              }),
+              expect.objectContaining({
+                content: 'another item',
+                status: 'unchanged',
+              }),
+            ]),
+          }),
+        ]),
+      );
+    });
+
+    it('handles multiple heading levels', () => {
+      const oldValue = '# H1\n## H2\n### H3';
+      const newValue = '# H1\n## Updated H2\n### H3';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'heading',
+          level: '#',
+          status: 'unchanged',
+        }),
+        expect.objectContaining({
+          type: 'heading',
+          level: '##',
+          content: 'Updated H2',
+          status: 'updated',
+        }),
+        expect.objectContaining({
+          type: 'heading',
+          level: '###',
+          status: 'unchanged',
+        }),
+      ]);
+    });
+
+    it('computes word-level diffs for code blocks', () => {
+      const oldValue = '```js\nconst x = 1;\n```';
+      const newValue = '```js\nconst x = 2;\n```';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'code',
+          status: 'updated',
+          diffContent: expect.stringMatching(/<del>1<\/del>.*<ins>2<\/ins>/),
+        }),
+      ]);
+    });
+
+    it('tracks list item additions', () => {
+      const oldValue = '- item 1\n- item 2';
+      const newValue = '- item 1\n- item 2\n- item 3';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'list',
+          status: 'updated',
+          items: [
+            expect.objectContaining({ status: 'unchanged' }),
+            expect.objectContaining({ status: 'unchanged' }),
+            expect.objectContaining({
+              status: 'added',
+              diffContent: '<ins>item 3</ins>',
+            }),
+          ],
+        }),
+      ]);
+    });
+
+    it('tracks list item deletions', () => {
+      const oldValue = '- item 1\n- item 2\n- item 3';
+      const newValue = '- item 1\n- item 3';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'list',
+          status: 'updated',
+          items: [
+            expect.objectContaining({ status: 'unchanged' }),
+            expect.objectContaining({
+              status: 'deleted',
+              diffContent: '<del>item 2</del>',
+            }),
+            expect.objectContaining({ status: 'unchanged' }),
+          ],
+        }),
+      ]);
+    });
+
+    it('returns empty array for empty markdown', () => {
+      const result = parseAndDiffMarkdown('', '');
+
+      expect(result).toEqual([]);
+    });
+
+    it('handles transition from empty to content', () => {
+      const result = parseAndDiffMarkdown('', '# New heading');
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'heading',
+          status: 'added',
+        }),
+      ]);
+    });
+
+    it('escapes HTML to prevent XSS', () => {
+      const oldValue = 'Content with <script>alert("xss")</script>';
+      const newValue = 'Content with <div>safe</div>';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result[0].diffContent).toEqual(
+        expect.not.stringContaining('<script>'),
+      );
+    });
+
+    it('matches similar paragraphs by content for word-level diffing', () => {
+      const oldValue = `This was my content
+
+There was a line here.`;
+      const newValue = `This is my updated content`;
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            type: 'paragraph',
+            content: 'This is my updated content',
+            status: 'updated',
+            diffContent: expect.stringMatching(
+              /<del>was<\/del>.*<ins>is<\/ins>.*<ins>updated <\/ins>/,
+            ),
+          }),
+          expect.objectContaining({
+            type: 'paragraph',
+            content: 'There was a line here.',
+            status: 'deleted',
+          }),
+        ]),
+      );
+    });
+
+    it('handles complex markdown with mixed changes', () => {
+      const oldValue = `# Title
+
+Paragraph 1
+
+Paragraph 2
+
+- List item 1
+- List item 2`;
+
+      const newValue = `# Title
+
+Paragraph 1 updated
+
+New paragraph
+
+- List item 1
+- List item 2 updated
+- List item 3`;
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            type: 'heading',
+            status: 'unchanged',
+          }),
+          expect.objectContaining({
+            type: 'paragraph',
+            status: expect.not.stringMatching('unchanged'),
+          }),
+          expect.objectContaining({
+            type: 'list',
+            status: expect.not.stringMatching('unchanged'),
+          }),
+        ]),
+      );
+    });
+  });
+});
diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
new file mode 100644
index 000000000..00c8ab6ee
--- /dev/null
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
@@ -0,0 +1,437 @@
+import { marked, Token, Tokens } from 'marked';
+import { diffArrays, diffWords } from 'diff';
+
+/**
+ * Status of a markdown block after diff computation
+ */
+export type BlockStatus = 'unchanged' | 'added' | 'deleted' | 'updated';
+
+/**
+ * Type of markdown block
+ */
+export type BlockType =
+  | 'heading'
+  | 'paragraph'
+  | 'list'
+  | 'code'
+  | 'text'
+  | 'other';
+
+/**
+ * Represents a parsed markdown block with diff information
+ */
+export interface MarkdownBlock {
+  /** Type of the block */
+  type: BlockType;
+  /** Clean content (for unified/plain views) */
+  content: string;
+  /** Diff HTML content with <ins>/<del> tags (for tooltips and diff view) */
+  diffContent: string;
+  /** Status after diff computation */
+  status: BlockStatus;
+  /** Heading level (e.g., '#', '##') - only for heading blocks */
+  level?: string;
+  /** List items - only for list blocks */
+  items?: MarkdownBlock[];
+  /** Original markdown raw text */
+  raw: string;
+}
+
+/**
+ * Parse markdown string into structured blocks
+ */
+function parseMarkdownBlocks(markdown: string): MarkdownBlock[] {
+  marked.setOptions({ breaks: true, gfm: true });
+  const tokens = marked.lexer(markdown).filter((t) => t.type !== 'space');
+
+  return tokens.map((token) => {
+    const block: MarkdownBlock = {
+      type: getBlockType(token),
+      content: extractCleanContent(token),
+      diffContent: '',
+      status: 'unchanged',
+      raw: token.raw,
+    };
+
+    // Add heading level if it's a heading
+    if (token.type === 'heading') {
+      const heading = token as Tokens.Heading;
+      block.level = '#'.repeat(heading.depth);
+    }
+
+    // Parse list items if it's a list
+    if (token.type === 'list') {
+      const list = token as Tokens.List;
+      block.items = list.items.map((item) => ({
+        type: 'text',
+        content: item.text,
+        diffContent: '',
+        status: 'unchanged',
+        raw: item.raw,
+      }));
+    }
+
+    return block;
+  });
+}
+
+/**
+ * Get block type from marked token
+ */
+function getBlockType(token: Token): BlockType {
+  if (token.type === 'heading') return 'heading';
+  if (token.type === 'paragraph') return 'paragraph';
+  if (token.type === 'list') return 'list';
+  if (token.type === 'code') return 'code';
+  if (token.type === 'text') return 'text';
+  return 'other';
+}
+
+/**
+ * Extract clean text content from a token
+ */
+function extractCleanContent(token: Token): string {
+  if (token.type === 'heading') {
+    return (token as Tokens.Heading).text;
+  }
+  if (token.type === 'paragraph') {
+    return (token as Tokens.Paragraph).text;
+  }
+  if (token.type === 'code') {
+    return (token as Tokens.Code).text;
+  }
+  if (token.type === 'text') {
+    return (token as Tokens.Text).text;
+  }
+  if (token.type === 'list') {
+    const list = token as Tokens.List;
+    return list.items.map((item) => item.text).join('\n');
+  }
+  return token.raw;
+}
+
+/**
+ * Build diff HTML from two text strings using word-level diffing
+ */
+function buildWordDiffHtml(oldText: string, newText: string): string {
+  const changes = diffWords(oldText, newText);
+  return changes
+    .map((change) => {
+      if (change.added) return `<ins>${escapeHtml(change.value)}</ins>`;
+      if (change.removed) return `<del>${escapeHtml(change.value)}</del>`;
+      return escapeHtml(change.value);
+    })
+    .join('');
+}
+
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Calculate similarity between two strings (0-1, higher is more similar)
+ * Uses a simple word overlap metric
+ */
+function calculateSimilarity(str1: string, str2: string): number {
+  const words1 = str1.toLowerCase().split(/\s+/);
+  const words2 = str2.toLowerCase().split(/\s+/);
+
+  const set1 = new Set(words1);
+  const set2 = new Set(words2);
+
+  const intersection = new Set([...set1].filter((x) => set2.has(x)));
+  const union = new Set([...set1, ...set2]);
+
+  if (union.size === 0) return 0;
+  return intersection.size / union.size;
+}
+
+/**
+ * Try to match deleted and added blocks based on similarity
+ * Returns pairs of [oldBlock, newBlock] and unpaired blocks
+ */
+function matchBlocksBySimilarity(
+  oldBlocks: MarkdownBlock[],
+  newBlocks: MarkdownBlock[],
+): {
+  matched: Array<[MarkdownBlock, MarkdownBlock]>;
+  unmatchedOld: MarkdownBlock[];
+  unmatchedNew: MarkdownBlock[];
+} {
+  const matched: Array<[MarkdownBlock, MarkdownBlock]> = [];
+  const usedOld = new Set<number>();
+  const usedNew = new Set<number>();
+
+  // For each old block, find the best matching new block
+  for (let i = 0; i < oldBlocks.length; i++) {
+    const oldBlock = oldBlocks[i];
+    let bestMatch = -1;
+    let bestSimilarity = 0.3; // Minimum threshold for matching
+
+    for (let j = 0; j < newBlocks.length; j++) {
+      if (usedNew.has(j)) continue;
+
+      const newBlock = newBlocks[j];
+
+      // Only match blocks of the same type
+      if (oldBlock.type !== newBlock.type) continue;
+
+      const similarity = calculateSimilarity(
+        oldBlock.content,
+        newBlock.content,
+      );
+
+      if (similarity > bestSimilarity) {
+        bestSimilarity = similarity;
+        bestMatch = j;
+      }
+    }
+
+    if (bestMatch !== -1) {
+      matched.push([oldBlock, newBlocks[bestMatch]]);
+      usedOld.add(i);
+      usedNew.add(bestMatch);
+    }
+  }
+
+  const unmatchedOld = oldBlocks.filter((_, i) => !usedOld.has(i));
+  const unmatchedNew = newBlocks.filter((_, i) => !usedNew.has(i));
+
+  return { matched, unmatchedOld, unmatchedNew };
+}
+
+/**
+ * Compare two list blocks and return diff information for items
+ */
+function diffListItems(
+  oldItems: MarkdownBlock[],
+  newItems: MarkdownBlock[],
+): MarkdownBlock[] {
+  const oldTexts = oldItems.map((item) => item.content.trim());
+  const newTexts = newItems.map((item) => item.content.trim());
+  const changes = diffArrays(oldTexts, newTexts);
+
+  let oldIdx = 0;
+  let newIdx = 0;
+  const result: MarkdownBlock[] = [];
+
+  for (const change of changes) {
+    const count = change.count ?? change.value.length;
+
+    if (!change.added && !change.removed) {
+      // Unchanged items
+      for (let i = 0; i < count; i++) {
+        result.push({
+          ...newItems[newIdx++],
+          status: 'unchanged',
+        });
+        oldIdx++;
+      }
+    } else if (change.removed) {
+      // Deleted items - mark for deletion
+      for (let i = 0; i < count; i++) {
+        const oldItem = oldItems[oldIdx++];
+        result.push({
+          ...oldItem,
+          status: 'deleted',
+          diffContent: `<del>${escapeHtml(oldItem.content)}</del>`,
+        });
+      }
+    } else {
+      // Added items
+      for (let i = 0; i < count; i++) {
+        const newItem = newItems[newIdx++];
+        result.push({
+          ...newItem,
+          status: 'added',
+          diffContent: `<ins>${escapeHtml(newItem.content)}</ins>`,
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Normalize raw markdown for comparison by trimming whitespace
+ */
+function normalizeRaw(raw: string): string {
+  return raw.trim();
+}
+
+/**
+ * Create a comparison key for a block (type + content)
+ */
+function createBlockKey(block: MarkdownBlock): string {
+  return `${block.type}:${normalizeRaw(block.raw)}`;
+}
+
+/**
+ * Parse markdown and compute diffs between old and new versions.
+ * Returns structured blocks with both clean content and diff information.
+ *
+ * @param oldValue - Original markdown content
+ * @param newValue - New markdown content
+ * @returns Array of MarkdownBlock with diff information
+ */
+export function parseAndDiffMarkdown(
+  oldValue: string,
+  newValue: string,
+): MarkdownBlock[] {
+  const oldBlocks = parseMarkdownBlocks(oldValue);
+  const newBlocks = parseMarkdownBlocks(newValue);
+
+  // Use normalized keys for block-level diffing to avoid whitespace issues
+  const oldKeys = oldBlocks.map(createBlockKey);
+  const newKeys = newBlocks.map(createBlockKey);
+  const changes = diffArrays(oldKeys, newKeys);
+
+  let oldIdx = 0;
+  let newIdx = 0;
+  const result: MarkdownBlock[] = [];
+
+  for (let ci = 0; ci < changes.length; ci++) {
+    const change = changes[ci];
+    const count = change.count ?? change.value.length;
+
+    if (!change.added && !change.removed) {
+      // Unchanged blocks
+      for (let i = 0; i < count; i++) {
+        result.push({
+          ...newBlocks[newIdx++],
+          status: 'unchanged',
+        });
+        oldIdx++;
+      }
+    } else if (change.removed) {
+      const next = changes[ci + 1];
+
+      if (next && next.added) {
+        // Modified blocks - check if we can do word-level diff
+        const nextCount = next.count ?? next.value.length;
+
+        if (count === 1 && nextCount === 1) {
+          // Single block modified - do word-level diff
+          const oldBlock = oldBlocks[oldIdx++];
+          const newBlock = newBlocks[newIdx++];
+
+          if (oldBlock.type === newBlock.type) {
+            // Same block type - compute word-level diff
+            if (newBlock.type === 'list' && oldBlock.items && newBlock.items) {
+              // Special handling for lists
+              result.push({
+                ...newBlock,
+                status: 'updated',
+                items: diffListItems(oldBlock.items, newBlock.items),
+              });
+            } else {
+              // Text blocks (heading, paragraph, code)
+              const diffHtml = buildWordDiffHtml(
+                oldBlock.content,
+                newBlock.content,
+              );
+              result.push({
+                ...newBlock,
+                status: 'updated',
+                diffContent: diffHtml,
+              });
+            }
+          } else {
+            // Different block types - mark as deleted and added
+            result.push({
+              ...oldBlock,
+              status: 'deleted',
+              diffContent: `<del>${escapeHtml(oldBlock.content)}</del>`,
+            });
+            result.push({
+              ...newBlock,
+              status: 'added',
+              diffContent: `<ins>${escapeHtml(newBlock.content)}</ins>`,
+            });
+          }
+        } else {
+          // Multiple blocks changed - try to match them by similarity
+          const deletedBlocks = oldBlocks.slice(oldIdx, oldIdx + count);
+          const addedBlocks = newBlocks.slice(newIdx, newIdx + nextCount);
+
+          const { matched, unmatchedOld, unmatchedNew } =
+            matchBlocksBySimilarity(deletedBlocks, addedBlocks);
+
+          // Process matched pairs with word-level diff
+          for (const [oldBlock, newBlock] of matched) {
+            if (newBlock.type === 'list' && oldBlock.items && newBlock.items) {
+              result.push({
+                ...newBlock,
+                status: 'updated',
+                items: diffListItems(oldBlock.items, newBlock.items),
+              });
+            } else {
+              const diffHtml = buildWordDiffHtml(
+                oldBlock.content,
+                newBlock.content,
+              );
+              result.push({
+                ...newBlock,
+                status: 'updated',
+                diffContent: diffHtml,
+              });
+            }
+          }
+
+          // Process unmatched deletions
+          for (const oldBlock of unmatchedOld) {
+            result.push({
+              ...oldBlock,
+              status: 'deleted',
+              diffContent: `<del>${escapeHtml(oldBlock.content)}</del>`,
+            });
+          }
+
+          // Process unmatched additions
+          for (const newBlock of unmatchedNew) {
+            result.push({
+              ...newBlock,
+              status: 'added',
+              diffContent: `<ins>${escapeHtml(newBlock.content)}</ins>`,
+            });
+          }
+
+          oldIdx += count;
+          newIdx += nextCount;
+        }
+        ci++; // Skip the next (added) change
+      } else {
+        // Pure deletion
+        for (let i = 0; i < count; i++) {
+          const oldBlock = oldBlocks[oldIdx++];
+          result.push({
+            ...oldBlock,
+            status: 'deleted',
+            diffContent: `<del>${escapeHtml(oldBlock.content)}</del>`,
+          });
+        }
+      }
+    } else {
+      // Pure additions
+      for (let i = 0; i < count; i++) {
+        const newBlock = newBlocks[newIdx++];
+        result.push({
+          ...newBlock,
+          status: 'added',
+          diffContent: `<ins>${escapeHtml(newBlock.content)}</ins>`,
+        });
+      }
+    }
+  }
+
+  return result;
+}
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
new file mode 100644
index 000000000..1023cf10f
--- /dev/null
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
@@ -0,0 +1,217 @@
+import { rebuildMarkdownFromBlocks } from './rebuildMarkdownFromBlocks';
+import { parseAndDiffMarkdown } from './markdownBlockDiff';
+
+describe('rebuildMarkdownFromBlocks', () => {
+  describe('unified mode (markdown output)', () => {
+    it('rebuilds markdown with clean content, excluding deleted blocks', () => {
+      const oldValue = '# Title\n\nOld paragraph\n\nAnother paragraph';
+      const newValue = '# Title\n\nNew paragraph';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: false,
+        useDiffContent: false,
+      });
+
+      expect(result).toEqual(
+        expect.stringMatching(
+          /# Title[\s\S]*New paragraph(?![\s\S]*Old paragraph)(?![\s\S]*Another paragraph)/,
+        ),
+      );
+    });
+
+    it('rebuilds list markdown preserving structure', () => {
+      const oldValue = '- item 1\n- item 2';
+      const newValue = '- item 1\n- item 2\n- item 3';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: false,
+        useDiffContent: false,
+      });
+
+      expect(result).toMatch(/- item 1[\s\S]*- item 2[\s\S]*- item 3/);
+    });
+
+    it('excludes deleted list items from output', () => {
+      const oldValue = '- item 1\n- item 2\n- item 3';
+      const newValue = '- item 1\n- item 3';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: false,
+        useDiffContent: false,
+      });
+
+      expect(result).toEqual(
+        expect.stringMatching(/- item 1[\s\S]*- item 3(?![\s\S]*- item 2)/),
+      );
+    });
+
+    it('preserves code block formatting', () => {
+      const oldValue = '```js\nconst x = 1;\n```';
+      const newValue = '```js\nconst x = 2;\n```';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: false,
+        useDiffContent: false,
+      });
+
+      expect(result).toMatch(/```[\s\S]*const x = 2;[\s\S]*```/);
+    });
+  });
+
+  describe('diff mode (HTML output)', () => {
+    it('generates HTML with inline diff markers', () => {
+      const oldValue = 'Old text';
+      const newValue = 'New text';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: true,
+        useDiffContent: true,
+      });
+
+      expect(result).toMatch(
+        /<p>.*<del>Old<\/del>.*<ins>New<\/ins>.*text.*<\/p>/,
+      );
+    });
+
+    it('renders list items with diff HTML markers', () => {
+      const oldValue = '- item 1\n- item 2';
+      const newValue = '- item 1\n- item 2\n- item 3';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: true,
+        useDiffContent: true,
+      });
+
+      expect(result).toMatch(
+        /<ul>[\s\S]*<li>.*item 1.*<\/li>[\s\S]*<li>.*item 2.*<\/li>[\s\S]*<li>.*<ins>item 3<\/ins>.*<\/li>[\s\S]*<\/ul>/,
+      );
+    });
+
+    it('renders headings with proper HTML structure', () => {
+      const oldValue = '# Old Title';
+      const newValue = '# New Title';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: true,
+        useDiffContent: true,
+      });
+
+      expect(result).toMatch(/<h1>.*<del>Old<\/del>.*<ins>New<\/ins>.*<\/h1>/);
+    });
+
+    it('includes deleted blocks in output', () => {
+      const oldValue = '# Title\n\nParagraph to delete';
+      const newValue = '# Title';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: true,
+        useDiffContent: true,
+      });
+
+      expect(result).toMatch(/<del>Paragraph to delete<\/del>/);
+    });
+  });
+
+  describe('plain mode', () => {
+    it('produces clean markdown without diff markers', () => {
+      const oldValue = 'Old content';
+      const newValue = 'New content';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: false,
+        useDiffContent: false,
+      });
+
+      expect(result).toEqual(
+        expect.stringMatching(
+          /New content(?![\s\S]*Old content)(?![\s\S]*<ins>)(?![\s\S]*<del>)/,
+        ),
+      );
+    });
+  });
+
+  describe('complex scenarios', () => {
+    it('handles the user story example in unified mode', () => {
+      const oldValue = `# My title
+
+This was my content
+
+There was a line here.
+
+## My sub-heading
+
+My list:
+ - one item
+ - another item`;
+
+      const newValue = `# My title
+
+This is my updated content
+
+## My sub-heading
+
+My list:
+ - first item
+ - a new item
+ - another item`;
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: false,
+        useDiffContent: false,
+      });
+
+      expect(result).toEqual(
+        expect.stringMatching(
+          /# My title[\s\S]*This is my updated content[\s\S]*## My sub-heading[\s\S]*- another item(?![\s\S]*There was a line here)/,
+        ),
+      );
+    });
+
+    it('handles the user story example in diff mode', () => {
+      const oldValue = `# My title
+
+This was my content
+
+There was a line here.
+
+## My sub-heading
+
+My list:
+ - one item
+ - another item`;
+
+      const newValue = `# My title
+
+This is my updated content
+
+## My sub-heading
+
+My list:
+ - first item
+ - a new item
+ - another item`;
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: true,
+        useDiffContent: true,
+      });
+
+      expect(result).toEqual(
+        expect.stringMatching(
+          /<h1>My title<\/h1>[\s\S]*<del>There was a line here\.<\/del>[\s\S]*<ul>[\s\S]*<li>/,
+        ),
+      );
+    });
+  });
+});
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
new file mode 100644
index 000000000..24e1ea796
--- /dev/null
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
@@ -0,0 +1,130 @@
+import { MarkdownBlock } from './markdownBlockDiff';
+
+/**
+ * Rebuilds markdown content from structured blocks.
+ * Used to generate content for different display modes.
+ */
+export interface RebuildOptions {
+  /** Whether to include deleted blocks */
+  includeDeleted: boolean;
+  /** Whether to use diffContent (with <ins>/<del> tags) or clean content */
+  useDiffContent: boolean;
+}
+
+/**
+ * Rebuild markdown from structured blocks for rendering in different modes.
+ *
+ * @param blocks - Array of MarkdownBlock from parseAndDiffMarkdown
+ * @param options - Options controlling what to include
+ * @returns Markdown or HTML string ready for rendering
+ */
+export function rebuildMarkdownFromBlocks(
+  blocks: MarkdownBlock[],
+  options: RebuildOptions,
+): string {
+  const parts: string[] = [];
+
+  for (const block of blocks) {
+    // Skip deleted blocks unless includeDeleted is true
+    if (block.status === 'deleted' && !options.includeDeleted) {
+      continue;
+    }
+
+    // Use diffContent if available and requested, otherwise use content
+    const content =
+      options.useDiffContent && block.diffContent
+        ? block.diffContent
+        : block.content;
+
+    switch (block.type) {
+      case 'heading':
+        if (options.useDiffContent) {
+          // For diff mode, render as HTML heading
+          const level = block.level?.length || 1;
+          parts.push(`<h${level}>${content}</h${level}>\n`);
+        } else {
+          // For unified/plain mode, use markdown syntax
+          parts.push(`${block.level || '#'} ${content}\n`);
+        }
+        break;
+
+      case 'paragraph':
+        if (options.useDiffContent) {
+          // For diff mode, render as HTML paragraph
+          parts.push(`<p>${content}</p>\n`);
+        } else {
+          // For unified/plain mode, use plain text with blank line separator
+          parts.push(`${content}\n`);
+        }
+        break;
+
+      case 'list':
+        if (options.useDiffContent) {
+          // For diff mode, render as HTML list
+          parts.push(renderListAsDiffHtml(block));
+        } else {
+          // For unified/plain mode, use markdown list syntax
+          parts.push(renderListAsMarkdown(block, options.includeDeleted));
+        }
+        break;
+
+      case 'code':
+        if (options.useDiffContent) {
+          // For diff mode, render as HTML code block
+          parts.push(`<pre><code>${content}</code></pre>\n`);
+        } else {
+          // For unified/plain mode, use markdown code block
+          parts.push(`\`\`\`\n${content}\n\`\`\`\n`);
+        }
+        break;
+
+      default:
+        // For other types, just add the raw content
+        parts.push(block.raw);
+    }
+
+    // Add blank line between blocks for markdown mode
+    if (!options.useDiffContent && block.type !== 'heading') {
+      parts.push('\n');
+    }
+  }
+
+  return parts.join('');
+}
+
+/**
+ * Render a list block as markdown
+ */
+function renderListAsMarkdown(
+  block: MarkdownBlock,
+  includeDeleted: boolean,
+): string {
+  if (!block.items || block.items.length === 0) {
+    return '';
+  }
+
+  const items = block.items
+    .filter((item) => includeDeleted || item.status !== 'deleted')
+    .map((item) => `- ${item.content}`)
+    .join('\n');
+
+  return items + '\n';
+}
+
+/**
+ * Render a list block as HTML with diff tags
+ */
+function renderListAsDiffHtml(block: MarkdownBlock): string {
+  if (!block.items || block.items.length === 0) {
+    return '';
+  }
+
+  const items = block.items
+    .map((item) => {
+      const content = item.diffContent || item.content;
+      return `<li>${content}</li>`;
+    })
+    .join('\n');
+
+  return `<ul>\n${items}\n</ul>\n`;
+}
diff --git a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
index 5096d056e..6f338e751 100644
--- a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
+++ b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
@@ -3,8 +3,8 @@ import { Milkdown, useEditor } from '@milkdown/react';
 import '@packmind/assets/milkdown.theme';
 import { PMBox } from '@packmind/ui';
 import React, { useEffect, useRef, useMemo, useState } from 'react';
-import { buildUnifiedMarkdownDiff } from '../../../domain/change-proposals/utils/buildUnifiedMarkdownDiff';
-import { buildInlineDiffMarkdown } from '../../../domain/change-proposals/utils/buildInlineDiffMarkdown';
+import { parseAndDiffMarkdown } from '../../../domain/change-proposals/utils/markdownBlockDiff';
+import { rebuildMarkdownFromBlocks } from '../../../domain/change-proposals/utils/rebuildMarkdownFromBlocks';
 import { markdownDiffCss } from '../../../domain/change-proposals/utils/markdownDiff';
 
 export interface IDiffMarkdownEditorProps {
@@ -38,20 +38,24 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
   const editorRef = useRef<HTMLDivElement | null>(null);
   const [isEditorReady, setIsEditorReady] = useState(false);
 
-  // Build blocks for unified mode (for highlighting)
+  // Parse and diff markdown blocks
   const blocks = useMemo(
-    () => buildUnifiedMarkdownDiff(oldValue, newValue),
+    () => parseAndDiffMarkdown(oldValue, newValue),
     [oldValue, newValue],
   );
 
   // Compute editor content based on display mode
   const editorContent = useMemo(() => {
     if (displayMode === 'diff') {
-      return buildInlineDiffMarkdown(oldValue, newValue);
+      // For diff mode, rebuild with HTML and include deleted blocks
+      return rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: true,
+        useDiffContent: true,
+      });
     }
-    // For 'unified' and 'plain' modes, use newValue
+    // For 'unified' and 'plain' modes, use clean newValue
     return newValue;
-  }, [displayMode, oldValue, newValue]);
+  }, [displayMode, blocks, newValue]);
 
   useEditor((root) => {
     editorRef.current = root as HTMLDivElement;
@@ -101,8 +105,41 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
 
     if (!isEditorReady || !editorRef.current || blocks.length === 0) return;
 
-    const changedBlocks = blocks.filter((b) => b.isChanged);
-    if (changedBlocks.length === 0) return;
+    // Collect all changed blocks and list items for highlighting
+    interface HighlightTarget {
+      content: string;
+      diffContent: string;
+    }
+
+    const highlightTargets: HighlightTarget[] = [];
+
+    for (const block of blocks) {
+      // Add changed blocks (non-list blocks)
+      if (
+        block.status !== 'unchanged' &&
+        block.diffContent &&
+        block.type !== 'list'
+      ) {
+        highlightTargets.push({
+          content: block.content,
+          diffContent: block.diffContent,
+        });
+      }
+
+      // Add changed list items
+      if (block.type === 'list' && block.items) {
+        for (const item of block.items) {
+          if (item.status !== 'unchanged' && item.diffContent) {
+            highlightTargets.push({
+              content: item.content,
+              diffContent: item.diffContent,
+            });
+          }
+        }
+      }
+    }
+
+    if (highlightTargets.length === 0) return;
 
     const applyHighlights = () => {
       const proseMirrorEditor =
@@ -127,26 +164,23 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
         const elementText = element.textContent?.trim() || '';
         if (!elementText) return;
 
-        // Check if this element's text matches any changed block
-        for (const block of changedBlocks) {
-          const blockText = block.html
-            .replace(/<[^>]+>/g, ' ')
+        // Check if this element's text matches any changed block or list item
+        for (const target of highlightTargets) {
+          const normalizedElementText = elementText.replace(/\s+/g, ' ').trim();
+          const normalizedTargetText = target.content
             .replace(/\s+/g, ' ')
             .trim();
 
-          const normalizedElementText = elementText.replace(/\s+/g, ' ').trim();
-          const normalizedBlockText = blockText.replace(/\s+/g, ' ').trim();
-
           // Match if texts are similar (handle minor whitespace differences)
           if (
-            normalizedElementText === normalizedBlockText ||
-            normalizedElementText.includes(normalizedBlockText) ||
-            normalizedBlockText.includes(normalizedElementText)
+            normalizedElementText === normalizedTargetText ||
+            normalizedElementText.includes(normalizedTargetText) ||
+            normalizedTargetText.includes(normalizedElementText)
           ) {
             (element as HTMLElement).classList.add('milkdown-diff-highlight');
             (element as HTMLElement).setAttribute(
               'data-diff-html',
-              block.diffHtml || '',
+              target.diffContent || '',
             );
             (element as HTMLElement).setAttribute(
               'data-proposal-numbers',

From 45e4cbdd8467343d4f984357cceba879c51c7c91 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Fri, 27 Feb 2026 09:46:35 +0100
Subject: [PATCH 05/12] WIP: support code block changes

---
 .../UnifiedMarkdownViewer.stories.tsx         |  21 +-
 .../utils/markdownBlockDiff.spec.ts           |  36 ++++
 .../utils/markdownBlockDiff.ts                |  69 ++++++-
 .../utils/rebuildMarkdownFromBlocks.spec.ts   |  83 ++++++--
 .../utils/rebuildMarkdownFromBlocks.ts        |  62 +++---
 .../components/editor/DiffMarkdownEditor.tsx  | 189 ++++++++++++++++--
 6 files changed, 396 insertions(+), 64 deletions(-)

diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
index e28f6307d..3e1e6621f 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
@@ -49,7 +49,16 @@ There was a line here.
 
 My list:
  - one item
- - another item`,
+ - another item
+ 
+# Code example
+
+\`\`\`javascript
+function hello() {
+  console.log('Hello');
+}
+\`\`\` 
+`,
     newValue: `# My title
 
 This is my updated content
@@ -59,7 +68,15 @@ This is my updated content
 My list:
  - first item
  - a new item
- - another item`,
+ - another item
+ 
+ # Example
+
+\`\`\`javascript
+function hello() {
+  console.log('Hello, ' + name);
+}
+\`\`\``,
     proposalNumbers: [1],
   },
 };
diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
index 91408af4e..6125324b1 100644
--- a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
@@ -208,7 +208,43 @@ My list:
         expect.objectContaining({
           type: 'code',
           status: 'updated',
+          language: 'js',
           diffContent: expect.stringMatching(/<del>1<\/del>.*<ins>2<\/ins>/),
+          lineDiff: expect.stringContaining('-const x = 1;'),
+        }),
+      ]);
+    });
+
+    it('includes additions in line diff for code blocks', () => {
+      const oldValue = '```js\nconst x = 1;\n```';
+      const newValue = '```js\nconst x = 2;\n```';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result[0].lineDiff).toContain('+const x = 2;');
+    });
+
+    it('computes line-level diffs for multi-line code blocks', () => {
+      const oldValue = `\`\`\`javascript
+function hello() {
+  console.log('Hello');
+}
+\`\`\``;
+
+      const newValue = `\`\`\`javascript
+function hello(name) {
+  console.log('Hello, ' + name);
+}
+\`\`\``;
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'code',
+          status: 'updated',
+          language: 'javascript',
+          lineDiff: expect.stringContaining('-function hello() {'),
         }),
       ]);
     });
diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
index 00c8ab6ee..6734ead60 100644
--- a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
@@ -1,5 +1,5 @@
 import { marked, Token, Tokens } from 'marked';
-import { diffArrays, diffWords } from 'diff';
+import { diffArrays, diffWords, diffLines } from 'diff';
 
 /**
  * Status of a markdown block after diff computation
@@ -27,10 +27,14 @@ export interface MarkdownBlock {
   content: string;
   /** Diff HTML content with <ins>/<del> tags (for tooltips and diff view) */
   diffContent: string;
+  /** Line-level diff with +/- prefixes for code blocks (for diff mode rendering) */
+  lineDiff?: string;
   /** Status after diff computation */
   status: BlockStatus;
   /** Heading level (e.g., '#', '##') - only for heading blocks */
   level?: string;
+  /** Code block language (e.g., 'js', 'typescript') - only for code blocks */
+  language?: string;
   /** List items - only for list blocks */
   items?: MarkdownBlock[];
   /** Original markdown raw text */
@@ -59,6 +63,12 @@ function parseMarkdownBlocks(markdown: string): MarkdownBlock[] {
       block.level = '#'.repeat(heading.depth);
     }
 
+    // Add language if it's a code block
+    if (token.type === 'code') {
+      const code = token as Tokens.Code;
+      block.language = code.lang || '';
+    }
+
     // Parse list items if it's a list
     if (token.type === 'list') {
       const list = token as Tokens.List;
@@ -124,6 +134,33 @@ function buildWordDiffHtml(oldText: string, newText: string): string {
     .join('');
 }
 
+/**
+ * Build line-level diff string for code blocks with +/- prefixes
+ */
+function buildLineDiff(oldText: string, newText: string): string {
+  const changes = diffLines(oldText, newText);
+  const lines: string[] = [];
+
+  for (const change of changes) {
+    const value = change.value;
+    // Remove trailing newline to avoid empty lines
+    const text = value.endsWith('\n') ? value.slice(0, -1) : value;
+    const codeLines = text.split('\n');
+
+    for (const line of codeLines) {
+      if (change.added) {
+        lines.push(`+${line}`);
+      } else if (change.removed) {
+        lines.push(`-${line}`);
+      } else {
+        lines.push(` ${line}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Escape HTML special characters
  */
@@ -339,11 +376,22 @@ export function parseAndDiffMarkdown(
                 oldBlock.content,
                 newBlock.content,
               );
-              result.push({
+
+              // For code blocks, also compute line-level diff
+              const updatedBlock: MarkdownBlock = {
                 ...newBlock,
                 status: 'updated',
                 diffContent: diffHtml,
-              });
+              };
+
+              if (newBlock.type === 'code') {
+                updatedBlock.lineDiff = buildLineDiff(
+                  oldBlock.content,
+                  newBlock.content,
+                );
+              }
+
+              result.push(updatedBlock);
             }
           } else {
             // Different block types - mark as deleted and added
@@ -379,11 +427,22 @@ export function parseAndDiffMarkdown(
                 oldBlock.content,
                 newBlock.content,
               );
-              result.push({
+
+              // For code blocks, also compute line-level diff
+              const updatedBlock: MarkdownBlock = {
                 ...newBlock,
                 status: 'updated',
                 diffContent: diffHtml,
-              });
+              };
+
+              if (newBlock.type === 'code') {
+                updatedBlock.lineDiff = buildLineDiff(
+                  oldBlock.content,
+                  newBlock.content,
+                );
+              }
+
+              result.push(updatedBlock);
             }
           }
 
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
index 1023cf10f..33c836ae0 100644
--- a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
@@ -11,6 +11,7 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: false,
         useDiffContent: false,
+        mode: 'unified',
       });
 
       expect(result).toEqual(
@@ -20,6 +21,29 @@ describe('rebuildMarkdownFromBlocks', () => {
       );
     });
 
+    it('adds "Show code changes" trigger for updated code blocks', () => {
+      const oldValue = `\`\`\`javascript
+function hello() {
+  console.log('Hello');
+}
+\`\`\``;
+
+      const newValue = `\`\`\`javascript
+function hello(name) {
+  console.log('Hello, ' + name);
+}
+\`\`\``;
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: false,
+        useDiffContent: false,
+        mode: 'unified',
+      });
+
+      expect(result).toContain('Show code changes');
+    });
+
     it('rebuilds list markdown preserving structure', () => {
       const oldValue = '- item 1\n- item 2';
       const newValue = '- item 1\n- item 2\n- item 3';
@@ -28,6 +52,7 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: false,
         useDiffContent: false,
+        mode: 'unified',
       });
 
       expect(result).toMatch(/- item 1[\s\S]*- item 2[\s\S]*- item 3/);
@@ -41,6 +66,7 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: false,
         useDiffContent: false,
+        mode: 'unified',
       });
 
       expect(result).toEqual(
@@ -56,14 +82,15 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: false,
         useDiffContent: false,
+        mode: 'unified',
       });
 
-      expect(result).toMatch(/```[\s\S]*const x = 2;[\s\S]*```/);
+      expect(result).toMatch(/```js[\s\S]*const x = 2;[\s\S]*```/);
     });
   });
 
-  describe('diff mode (HTML output)', () => {
-    it('generates HTML with inline diff markers', () => {
+  describe('diff mode (markdown output with diff tags)', () => {
+    it('generates markdown with inline diff markers', () => {
       const oldValue = 'Old text';
       const newValue = 'New text';
 
@@ -71,14 +98,15 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: true,
         useDiffContent: true,
+        mode: 'diff',
       });
 
       expect(result).toMatch(
-        /<p>.*<del>Old<\/del>.*<ins>New<\/ins>.*text.*<\/p>/,
+        /<del>Old<\/del>[\s\S]*<ins>New<\/ins>[\s\S]*text(?![\s\S]*<p>)/,
       );
     });
 
-    it('renders list items with diff HTML markers', () => {
+    it('renders list items with diff markdown markers', () => {
       const oldValue = '- item 1\n- item 2';
       const newValue = '- item 1\n- item 2\n- item 3';
 
@@ -86,14 +114,15 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: true,
         useDiffContent: true,
+        mode: 'diff',
       });
 
       expect(result).toMatch(
-        /<ul>[\s\S]*<li>.*item 1.*<\/li>[\s\S]*<li>.*item 2.*<\/li>[\s\S]*<li>.*<ins>item 3<\/ins>.*<\/li>[\s\S]*<\/ul>/,
+        /- item 1[\s\S]*- item 2[\s\S]*- <ins>item 3<\/ins>(?![\s\S]*<ul>)(?![\s\S]*<li>)/,
       );
     });
 
-    it('renders headings with proper HTML structure', () => {
+    it('renders headings with markdown syntax', () => {
       const oldValue = '# Old Title';
       const newValue = '# New Title';
 
@@ -101,9 +130,12 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: true,
         useDiffContent: true,
+        mode: 'diff',
       });
 
-      expect(result).toMatch(/<h1>.*<del>Old<\/del>.*<ins>New<\/ins>.*<\/h1>/);
+      expect(result).toMatch(
+        /# .*<del>Old<\/del>.*<ins>New<\/ins>(?![\s\S]*<h1>)/,
+      );
     });
 
     it('includes deleted blocks in output', () => {
@@ -114,9 +146,33 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: true,
         useDiffContent: true,
+        mode: 'diff',
+      });
+
+      expect(result).toMatch(/<del>Paragraph to delete<\/del>(?![\s\S]*<p>)/);
+    });
+
+    it('renders code blocks with line-level diff syntax', () => {
+      const oldValue = `\`\`\`javascript
+function hello() {
+  console.log('Hello');
+}
+\`\`\``;
+
+      const newValue = `\`\`\`javascript
+function hello(name) {
+  console.log('Hello, ' + name);
+}
+\`\`\``;
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: true,
+        useDiffContent: true,
+        mode: 'diff',
       });
 
-      expect(result).toMatch(/<del>Paragraph to delete<\/del>/);
+      expect(result).toContain('```diff');
     });
   });
 
@@ -129,6 +185,7 @@ describe('rebuildMarkdownFromBlocks', () => {
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: false,
         useDiffContent: false,
+        mode: 'plain',
       });
 
       expect(result).toEqual(
@@ -168,6 +225,7 @@ My list:
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: false,
         useDiffContent: false,
+        mode: 'unified',
       });
 
       expect(result).toEqual(
@@ -205,12 +263,11 @@ My list:
       const result = rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: true,
         useDiffContent: true,
+        mode: 'diff',
       });
 
-      expect(result).toEqual(
-        expect.stringMatching(
-          /<h1>My title<\/h1>[\s\S]*<del>There was a line here\.<\/del>[\s\S]*<ul>[\s\S]*<li>/,
-        ),
+      expect(result).toMatch(
+        /# My title[\s\S]*<del>There was a line here\.<\/del>[\s\S]*- (?![\s\S]*<h1>)(?![\s\S]*<ul>)(?![\s\S]*<li>)/,
       );
     });
   });
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
index 24e1ea796..2903fc3b1 100644
--- a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
@@ -9,6 +9,8 @@ export interface RebuildOptions {
   includeDeleted: boolean;
   /** Whether to use diffContent (with <ins>/<del> tags) or clean content */
   useDiffContent: boolean;
+  /** Display mode: 'unified', 'diff', or 'plain' */
+  mode?: 'unified' | 'diff' | 'plain';
 }
 
 /**
@@ -38,30 +40,19 @@ export function rebuildMarkdownFromBlocks(
 
     switch (block.type) {
       case 'heading':
-        if (options.useDiffContent) {
-          // For diff mode, render as HTML heading
-          const level = block.level?.length || 1;
-          parts.push(`<h${level}>${content}</h${level}>\n`);
-        } else {
-          // For unified/plain mode, use markdown syntax
-          parts.push(`${block.level || '#'} ${content}\n`);
-        }
+        // Always use markdown syntax for headings
+        parts.push(`${block.level || '#'} ${content}\n`);
         break;
 
       case 'paragraph':
-        if (options.useDiffContent) {
-          // For diff mode, render as HTML paragraph
-          parts.push(`<p>${content}</p>\n`);
-        } else {
-          // For unified/plain mode, use plain text with blank line separator
-          parts.push(`${content}\n`);
-        }
+        // Always use plain text for paragraphs
+        parts.push(`${content}\n`);
         break;
 
       case 'list':
         if (options.useDiffContent) {
-          // For diff mode, render as HTML list
-          parts.push(renderListAsDiffHtml(block));
+          // For diff mode, use markdown list with diff content
+          parts.push(renderListAsMarkdownWithDiff(block));
         } else {
           // For unified/plain mode, use markdown list syntax
           parts.push(renderListAsMarkdown(block, options.includeDeleted));
@@ -70,11 +61,30 @@ export function rebuildMarkdownFromBlocks(
 
       case 'code':
         if (options.useDiffContent) {
-          // For diff mode, render as HTML code block
-          parts.push(`<pre><code>${content}</code></pre>\n`);
+          // For diff mode, render as ```diff code block with line-level changes
+          const diffLines = block.lineDiff || content;
+          parts.push(`\`\`\`diff\n${diffLines}\n\`\`\`\n`);
         } else {
           // For unified/plain mode, use markdown code block
-          parts.push(`\`\`\`\n${content}\n\`\`\`\n`);
+          const lang = block.language || '';
+          parts.push(`\`\`\`${lang}\n${content}\n\`\`\`\n`);
+
+          // In unified mode, add a marker for changed code blocks
+          if (
+            options.mode === 'unified' &&
+            block.status === 'updated' &&
+            block.lineDiff
+          ) {
+            // Add a special HTML comment that will be detected by the editor
+            // The lineDiff is base64 encoded to avoid breaking the HTML
+            const encodedDiff =
+              typeof btoa !== 'undefined'
+                ? btoa(block.lineDiff)
+                : Buffer.from(block.lineDiff).toString('base64');
+            parts.push(
+              `<!-- CODE_DIFF:${encodedDiff} -->\n<span class="code-diff-trigger" data-line-diff="${encodedDiff}">Show code changes</span>\n`,
+            );
+          }
         }
         break;
 
@@ -83,8 +93,8 @@ export function rebuildMarkdownFromBlocks(
         parts.push(block.raw);
     }
 
-    // Add blank line between blocks for markdown mode
-    if (!options.useDiffContent && block.type !== 'heading') {
+    // Add blank line between blocks (except after headings)
+    if (block.type !== 'heading') {
       parts.push('\n');
     }
   }
@@ -112,9 +122,9 @@ function renderListAsMarkdown(
 }
 
 /**
- * Render a list block as HTML with diff tags
+ * Render a list block as markdown with diff tags
  */
-function renderListAsDiffHtml(block: MarkdownBlock): string {
+function renderListAsMarkdownWithDiff(block: MarkdownBlock): string {
   if (!block.items || block.items.length === 0) {
     return '';
   }
@@ -122,9 +132,9 @@ function renderListAsDiffHtml(block: MarkdownBlock): string {
   const items = block.items
     .map((item) => {
       const content = item.diffContent || item.content;
-      return `<li>${content}</li>`;
+      return `- ${content}`;
     })
     .join('\n');
 
-  return `<ul>\n${items}\n</ul>\n`;
+  return items + '\n';
 }
diff --git a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
index 6f338e751..a9ac5f4b1 100644
--- a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
+++ b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
@@ -51,9 +51,18 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
       return rebuildMarkdownFromBlocks(blocks, {
         includeDeleted: true,
         useDiffContent: true,
+        mode: 'diff',
       });
     }
-    // For 'unified' and 'plain' modes, use clean newValue
+    if (displayMode === 'unified') {
+      // For unified mode, rebuild with markers for changed code blocks
+      return rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: false,
+        useDiffContent: false,
+        mode: 'unified',
+      });
+    }
+    // For 'plain' mode, use clean newValue
     return newValue;
   }, [displayMode, blocks, newValue]);
 
@@ -352,25 +361,169 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
     };
   }, [isEditorReady, displayMode, proposalNumbers]);
 
-  // For diff mode, render HTML directly without Milkdown
-  if (displayMode === 'diff') {
-    return (
-      <PMBox
-        data-milkdown-padding-variant={paddingVariant}
-        css={markdownDiffCss}
-        dangerouslySetInnerHTML={{ __html: editorContent }}
-        style={{
-          padding: paddingVariant === 'default' ? '16px' : '0',
-          minHeight: '100px',
-        }}
-      />
-    );
-  }
-
-  // For unified and plain modes, use Milkdown with highlights (unified) or without (plain)
+  // Add special handling for code diff triggers in unified mode
+  useEffect(() => {
+    if (displayMode !== 'unified') return;
+    if (!isEditorReady || !editorRef.current) return;
+
+    const handleCodeDiffMouseEnter = (e: MouseEvent) => {
+      const target = e.target as HTMLElement;
+      if (target.classList.contains('code-diff-trigger')) {
+        const encodedDiff = target.getAttribute('data-line-diff') || '';
+        let lineDiff = '';
+
+        try {
+          lineDiff =
+            typeof atob !== 'undefined'
+              ? atob(encodedDiff)
+              : Buffer.from(encodedDiff, 'base64').toString('utf-8');
+        } catch (error) {
+          console.error('Failed to decode line diff:', error);
+          return;
+        }
+
+        // Create tooltip element
+        const tooltip = document.createElement('div');
+        tooltip.className = 'code-diff-tooltip';
+        tooltip.style.cssText = `
+          position: fixed;
+          z-index: 10000;
+          background: #1f2937;
+          color: #f9fafb;
+          padding: 12px;
+          border-radius: 6px;
+          max-width: 600px;
+          font-size: 12px;
+          box-shadow: 0 4px 12px rgba(0,0,0,0.5);
+          pointer-events: none;
+          font-family: monospace;
+          white-space: pre;
+          overflow-x: auto;
+        `;
+
+        const header = document.createElement('div');
+        header.style.cssText =
+          'font-weight: bold; margin-bottom: 8px; font-family: sans-serif;';
+        header.textContent = 'Code changes';
+
+        const content = document.createElement('div');
+        content.style.cssText = 'font-size: 13px;';
+
+        // Format diff lines with colors
+        const lines = lineDiff.split('\n');
+        const formattedLines = lines
+          .map((line) => {
+            if (line.startsWith('+')) {
+              return `<span style="color: #86efac; background-color: rgba(34, 197, 94, 0.2);">${escapeHtmlInComponent(line)}</span>`;
+            } else if (line.startsWith('-')) {
+              return `<span style="color: #fca5a5; background-color: rgba(239, 68, 68, 0.2);">${escapeHtmlInComponent(line)}</span>`;
+            } else {
+              return `<span style="color: #d1d5db;">${escapeHtmlInComponent(line)}</span>`;
+            }
+          })
+          .join('\n');
+
+        content.innerHTML = formattedLines;
+
+        tooltip.appendChild(header);
+        tooltip.appendChild(content);
+
+        document.body.appendChild(tooltip);
+        target.setAttribute('data-code-tooltip-id', 'active');
+
+        // Position tooltip after append
+        requestAnimationFrame(() => {
+          const rect = target.getBoundingClientRect();
+          const tooltipRect = tooltip.getBoundingClientRect();
+
+          // Position above the element
+          let top = rect.top - tooltipRect.height - 8;
+          let left = rect.left + rect.width / 2 - tooltipRect.width / 2;
+
+          // Keep tooltip within viewport
+          if (top < 0) {
+            top = rect.bottom + 8;
+          }
+          if (left < 8) {
+            left = 8;
+          }
+          if (left + tooltipRect.width > window.innerWidth - 8) {
+            left = window.innerWidth - tooltipRect.width - 8;
+          }
+
+          tooltip.style.top = `${top}px`;
+          tooltip.style.left = `${left}px`;
+        });
+      }
+    };
+
+    const handleCodeDiffMouseLeave = (e: MouseEvent) => {
+      const target = e.target as HTMLElement;
+      if (target.getAttribute('data-code-tooltip-id') === 'active') {
+        target.removeAttribute('data-code-tooltip-id');
+        document
+          .querySelectorAll('.code-diff-tooltip')
+          .forEach((el) => el.remove());
+      }
+    };
+
+    // Helper function to escape HTML in component
+    const escapeHtmlInComponent = (text: string): string => {
+      return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+    };
+
+    // Apply styling to code-diff-trigger elements
+    const applyCodeDiffStyling = () => {
+      const proseMirrorEditor =
+        editorRef.current?.querySelector('.ProseMirror');
+      if (!proseMirrorEditor) return;
+
+      const triggers = proseMirrorEditor.querySelectorAll('.code-diff-trigger');
+      triggers.forEach((trigger) => {
+        const element = trigger as HTMLElement;
+        element.style.cssText = `
+          display: inline-block;
+          margin-top: 8px;
+          padding: 4px 8px;
+          background: rgba(251, 191, 36, 0.2);
+          color: #f59e0b;
+          border-radius: 4px;
+          font-size: 12px;
+          cursor: pointer;
+          border: 1px solid rgba(251, 191, 36, 0.4);
+        `;
+      });
+    };
+
+    // Wait for content to render
+    const timer = setTimeout(() => {
+      applyCodeDiffStyling();
+    }, 500);
+
+    const editor = editorRef.current;
+    editor.addEventListener('mouseover', handleCodeDiffMouseEnter);
+    editor.addEventListener('mouseout', handleCodeDiffMouseLeave);
+
+    return () => {
+      clearTimeout(timer);
+      editor.removeEventListener('mouseover', handleCodeDiffMouseEnter);
+      editor.removeEventListener('mouseout', handleCodeDiffMouseLeave);
+      document
+        .querySelectorAll('.code-diff-tooltip')
+        .forEach((el) => el.remove());
+    };
+  }, [isEditorReady, displayMode]);
+
+  // For all modes, use Milkdown to render markdown
   return (
-    <PMBox data-milkdown-padding-variant={paddingVariant}>
+    <PMBox data-milkdown-padding-variant={paddingVariant} css={markdownDiffCss}>
       <Milkdown />
+      <pre>{editorContent}</pre>
     </PMBox>
   );
 };

From 43ca83d3763db95d9c0649809c10d86c3410883f Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Fri, 27 Feb 2026 10:09:16 +0100
Subject: [PATCH 06/12] Show all possible mode in unified viewer in stories

---
 .../UnifiedMarkdownViewer.stories.tsx         | 34 +++++++++++++------
 .../components/UnifiedMarkdownViewer.tsx      |  2 +-
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
index 3e1e6621f..33638d268 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
@@ -1,21 +1,33 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import { UnifiedMarkdownViewer } from './UnifiedMarkdownViewer';
+import {
+  UnifiedMarkdownViewer,
+  UnifiedMarkdownViewerProps,
+} from './UnifiedMarkdownViewer';
+
+const MultiViewer: React.FunctionComponent<
+  Omit<UnifiedMarkdownViewerProps, 'displayMode'>
+> = (props) => {
+  return (
+    <>
+      <h1>Unified view</h1>
+      <UnifiedMarkdownViewer {...props} displayMode={'unified'} />
+
+      <h1>Diff view</h1>
+      <UnifiedMarkdownViewer {...props} displayMode={'diff'} />
+
+      <h1>Plain view</h1>
+      <UnifiedMarkdownViewer {...props} displayMode={'plain'} />
+    </>
+  );
+};
 
-const meta: Meta<typeof UnifiedMarkdownViewer> = {
+const meta: Meta<typeof MultiViewer> = {
   title: 'ChangeProposals/UnifiedMarkdownViewer',
-  component: UnifiedMarkdownViewer,
+  component: MultiViewer,
   parameters: {
     layout: 'padded',
   },
   tags: ['autodocs'],
-  argTypes: {
-    displayMode: {
-      control: 'radio',
-      options: ['unified', 'diff', 'plain'],
-      description: 'Display mode for the markdown viewer',
-      value: 'unified',
-    },
-  },
 };
 
 export default meta;
diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.tsx
index e4e6defbb..380635493 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.tsx
@@ -6,7 +6,7 @@ import {
   IDiffMarkdownEditorProps,
 } from '../../../shared/components/editor/DiffMarkdownEditor';
 
-interface UnifiedMarkdownViewerProps {
+export interface UnifiedMarkdownViewerProps {
   oldValue: string;
   newValue: string;
   proposalNumbers: number[];

From 93a2aa6d03ed8868b37072b19c673becb40c35a5 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Fri, 27 Feb 2026 11:10:28 +0100
Subject: [PATCH 07/12] Use fake markdown syntax to handle ins/del tags in
 crepe

---
 .../UnifiedMarkdownViewer.stories.tsx         | 32 +++----
 .../utils/markdownBlockDiff.spec.ts           | 22 +++--
 .../utils/markdownBlockDiff.ts                | 27 +++---
 .../utils/rebuildMarkdownFromBlocks.spec.ts   | 14 ++-
 .../components/editor/DiffMarkdownEditor.tsx  | 90 ++++++++++++++++++-
 5 files changed, 135 insertions(+), 50 deletions(-)

diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
index 33638d268..a894a4ce5 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
@@ -33,22 +33,6 @@ const meta: Meta<typeof MultiViewer> = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const SimpleTextChange: Story = {
-  args: {
-    oldValue: 'This was my content',
-    newValue: 'This is my updated content',
-    proposalNumbers: [1],
-  },
-};
-
-export const MultipleProposals: Story = {
-  args: {
-    oldValue: 'This is my content',
-    newValue: 'This is my updated content',
-    proposalNumbers: [1, 2, 3],
-  },
-};
-
 export const MarkdownFormatting: Story = {
   args: {
     oldValue: `# My title
@@ -93,6 +77,22 @@ function hello() {
   },
 };
 
+export const TagChanges: Story = {
+  args: {
+    oldValue: '# My title\n\nThis was my content',
+    newValue: '## My title\n\nThis is my **content**',
+    proposalNumbers: [1],
+  },
+};
+
+export const MultipleProposals: Story = {
+  args: {
+    oldValue: 'This is my content',
+    newValue: 'This is my updated content',
+    proposalNumbers: [1, 2, 3],
+  },
+};
+
 export const CodeBlock: Story = {
   args: {
     oldValue: `# Example
diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
index 6125324b1..fe8e03bda 100644
--- a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
@@ -14,7 +14,7 @@ describe('markdownBlockDiff', () => {
           content: 'This is my updated content',
           status: 'updated',
           diffContent: expect.stringMatching(
-            /This <del>was<\/del><ins>is<\/ins> my <ins>updated <\/ins>content/,
+            /This --was--\+\+is\+\+ my \+\+updated \+\+content/,
           ),
         }),
       ]);
@@ -32,7 +32,7 @@ describe('markdownBlockDiff', () => {
           level: '#',
           content: 'My updated title',
           status: 'updated',
-          diffContent: expect.stringContaining('<ins>updated </ins>'),
+          diffContent: expect.stringContaining('++updated ++'),
         }),
       ]);
     });
@@ -64,7 +64,7 @@ describe('markdownBlockDiff', () => {
             type: 'paragraph',
             content: 'New paragraph',
             status: 'added',
-            diffContent: '<ins>New paragraph</ins>',
+            diffContent: '++New paragraph++',
           }),
         ]),
       );
@@ -86,7 +86,7 @@ describe('markdownBlockDiff', () => {
             type: 'paragraph',
             content: 'Paragraph to delete',
             status: 'deleted',
-            diffContent: '<del>Paragraph to delete</del>',
+            diffContent: '--Paragraph to delete--',
           }),
         ]),
       );
@@ -136,15 +136,13 @@ My list:
             type: 'paragraph',
             content: 'This is my updated content',
             status: 'updated',
-            diffContent: expect.stringMatching(
-              /<del>was<\/del>.*<ins>is<\/ins>/,
-            ),
+            diffContent: expect.stringMatching(/--was--.*\+\+is\+\+/),
           }),
           expect.objectContaining({
             type: 'paragraph',
             content: 'There was a line here.',
             status: 'deleted',
-            diffContent: '<del>There was a line here.</del>',
+            diffContent: '--There was a line here.--',
           }),
           expect.objectContaining({
             type: 'list',
@@ -209,7 +207,7 @@ My list:
           type: 'code',
           status: 'updated',
           language: 'js',
-          diffContent: expect.stringMatching(/<del>1<\/del>.*<ins>2<\/ins>/),
+          diffContent: expect.stringMatching(/--1--.*\+\+2\+\+/),
           lineDiff: expect.stringContaining('-const x = 1;'),
         }),
       ]);
@@ -264,7 +262,7 @@ function hello(name) {
             expect.objectContaining({ status: 'unchanged' }),
             expect.objectContaining({
               status: 'added',
-              diffContent: '<ins>item 3</ins>',
+              diffContent: '++item 3++',
             }),
           ],
         }),
@@ -285,7 +283,7 @@ function hello(name) {
             expect.objectContaining({ status: 'unchanged' }),
             expect.objectContaining({
               status: 'deleted',
-              diffContent: '<del>item 2</del>',
+              diffContent: '--item 2--',
             }),
             expect.objectContaining({ status: 'unchanged' }),
           ],
@@ -336,7 +334,7 @@ There was a line here.`;
             content: 'This is my updated content',
             status: 'updated',
             diffContent: expect.stringMatching(
-              /<del>was<\/del>.*<ins>is<\/ins>.*<ins>updated <\/ins>/,
+              /--was--.*\+\+is\+\+.*\+\+updated \+\+/,
             ),
           }),
           expect.objectContaining({
diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
index 6734ead60..44e7778c9 100644
--- a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
@@ -25,7 +25,7 @@ export interface MarkdownBlock {
   type: BlockType;
   /** Clean content (for unified/plain views) */
   content: string;
-  /** Diff HTML content with <ins>/<del> tags (for tooltips and diff view) */
+  /** Diff content with ++/-- markers (for tooltips and diff view) */
   diffContent: string;
   /** Line-level diff with +/- prefixes for code blocks (for diff mode rendering) */
   lineDiff?: string;
@@ -121,15 +121,16 @@ function extractCleanContent(token: Token): string {
 }
 
 /**
- * Build diff HTML from two text strings using word-level diffing
+ * Build diff markup from two text strings using word-level diffing
+ * Uses custom markdown-style syntax: ++ for additions, -- for deletions
  */
 function buildWordDiffHtml(oldText: string, newText: string): string {
   const changes = diffWords(oldText, newText);
   return changes
     .map((change) => {
-      if (change.added) return `<ins>${escapeHtml(change.value)}</ins>`;
-      if (change.removed) return `<del>${escapeHtml(change.value)}</del>`;
-      return escapeHtml(change.value);
+      if (change.added) return `++${change.value}++`;
+      if (change.removed) return `--${change.value}--`;
+      return change.value;
     })
     .join('');
 }
@@ -279,7 +280,7 @@ function diffListItems(
         result.push({
           ...oldItem,
           status: 'deleted',
-          diffContent: `<del>${escapeHtml(oldItem.content)}</del>`,
+          diffContent: `--${oldItem.content}--`,
         });
       }
     } else {
@@ -289,7 +290,7 @@ function diffListItems(
         result.push({
           ...newItem,
           status: 'added',
-          diffContent: `<ins>${escapeHtml(newItem.content)}</ins>`,
+          diffContent: `++${newItem.content}++`,
         });
       }
     }
@@ -398,12 +399,12 @@ export function parseAndDiffMarkdown(
             result.push({
               ...oldBlock,
               status: 'deleted',
-              diffContent: `<del>${escapeHtml(oldBlock.content)}</del>`,
+              diffContent: `--${oldBlock.content}--`,
             });
             result.push({
               ...newBlock,
               status: 'added',
-              diffContent: `<ins>${escapeHtml(newBlock.content)}</ins>`,
+              diffContent: `++${newBlock.content}++`,
             });
           }
         } else {
@@ -451,7 +452,7 @@ export function parseAndDiffMarkdown(
             result.push({
               ...oldBlock,
               status: 'deleted',
-              diffContent: `<del>${escapeHtml(oldBlock.content)}</del>`,
+              diffContent: `--${oldBlock.content}--`,
             });
           }
 
@@ -460,7 +461,7 @@ export function parseAndDiffMarkdown(
             result.push({
               ...newBlock,
               status: 'added',
-              diffContent: `<ins>${escapeHtml(newBlock.content)}</ins>`,
+              diffContent: `++${newBlock.content}++`,
             });
           }
 
@@ -475,7 +476,7 @@ export function parseAndDiffMarkdown(
           result.push({
             ...oldBlock,
             status: 'deleted',
-            diffContent: `<del>${escapeHtml(oldBlock.content)}</del>`,
+            diffContent: `--${oldBlock.content}--`,
           });
         }
       }
@@ -486,7 +487,7 @@ export function parseAndDiffMarkdown(
         result.push({
           ...newBlock,
           status: 'added',
-          diffContent: `<ins>${escapeHtml(newBlock.content)}</ins>`,
+          diffContent: `++${newBlock.content}++`,
         });
       }
     }
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
index 33c836ae0..bb32265d5 100644
--- a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
@@ -102,7 +102,7 @@ function hello(name) {
       });
 
       expect(result).toMatch(
-        /<del>Old<\/del>[\s\S]*<ins>New<\/ins>[\s\S]*text(?![\s\S]*<p>)/,
+        /--Old--[\s\S]*\+\+New\+\+[\s\S]*text(?![\s\S]*<p>)/,
       );
     });
 
@@ -118,7 +118,7 @@ function hello(name) {
       });
 
       expect(result).toMatch(
-        /- item 1[\s\S]*- item 2[\s\S]*- <ins>item 3<\/ins>(?![\s\S]*<ul>)(?![\s\S]*<li>)/,
+        /- item 1[\s\S]*- item 2[\s\S]*- \+\+item 3\+\+(?![\s\S]*<ul>)(?![\s\S]*<li>)/,
       );
     });
 
@@ -133,9 +133,7 @@ function hello(name) {
         mode: 'diff',
       });
 
-      expect(result).toMatch(
-        /# .*<del>Old<\/del>.*<ins>New<\/ins>(?![\s\S]*<h1>)/,
-      );
+      expect(result).toMatch(/# .*--Old--.*\+\+New\+\+(?![\s\S]*<h1>)/);
     });
 
     it('includes deleted blocks in output', () => {
@@ -149,7 +147,7 @@ function hello(name) {
         mode: 'diff',
       });
 
-      expect(result).toMatch(/<del>Paragraph to delete<\/del>(?![\s\S]*<p>)/);
+      expect(result).toMatch(/--Paragraph to delete--(?![\s\S]*<p>)/);
     });
 
     it('renders code blocks with line-level diff syntax', () => {
@@ -190,7 +188,7 @@ function hello(name) {
 
       expect(result).toEqual(
         expect.stringMatching(
-          /New content(?![\s\S]*Old content)(?![\s\S]*<ins>)(?![\s\S]*<del>)/,
+          /New content(?![\s\S]*Old content)(?![\s\S]*\+\+)(?![\s\S]*--)/,
         ),
       );
     });
@@ -267,7 +265,7 @@ My list:
       });
 
       expect(result).toMatch(
-        /# My title[\s\S]*<del>There was a line here\.<\/del>[\s\S]*- (?![\s\S]*<h1>)(?![\s\S]*<ul>)(?![\s\S]*<li>)/,
+        /# My title[\s\S]*--There was a line here\.--[\s\S]*- (?![\s\S]*<h1>)(?![\s\S]*<ul>)(?![\s\S]*<li>)/,
       );
     });
   });
diff --git a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
index a9ac5f4b1..8dd634e05 100644
--- a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
+++ b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
@@ -296,7 +296,11 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
         header.textContent = proposalText;
 
         const content = document.createElement('div');
-        content.innerHTML = diffHtml;
+        // Convert ++ and -- markers to HTML tags
+        const convertedDiffHtml = diffHtml
+          .replace(/\+\+([^+]+)\+\+/g, '<ins>$1</ins>')
+          .replace(/--([^-]+)--/g, '<del>$1</del>');
+        content.innerHTML = convertedDiffHtml;
         content.style.cssText = 'font-size: 14px;';
 
         // Apply diff styling
@@ -519,6 +523,90 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
     };
   }, [isEditorReady, displayMode]);
 
+  // Convert ++ and -- markers to HTML tags in diff mode
+  useEffect(() => {
+    if (displayMode !== 'diff') return;
+    if (!isEditorReady || !editorRef.current) return;
+
+    const convertMarkersToHtml = () => {
+      const proseMirrorEditor =
+        editorRef.current?.querySelector('.ProseMirror');
+      if (!proseMirrorEditor) return;
+
+      // Get all text nodes
+      const walker = document.createTreeWalker(
+        proseMirrorEditor,
+        NodeFilter.SHOW_TEXT,
+        null,
+      );
+
+      const nodesToProcess: { node: Text; newContent: string }[] = [];
+
+      let node: Node | null;
+      while ((node = walker.nextNode())) {
+        const textNode = node as Text;
+        const text = textNode.textContent || '';
+
+        // Check if the text contains our markers
+        if (text.includes('++') || text.includes('--')) {
+          // Replace ++text++ with <ins>text</ins> and --text-- with <del>text</del>
+          const newContent = text
+            .replace(/\+\+([^+]+)\+\+/g, '<ins>$1</ins>')
+            .replace(/--([^-]+)--/g, '<del>$1</del>');
+
+          if (newContent !== text) {
+            nodesToProcess.push({ node: textNode, newContent });
+          }
+        }
+      }
+
+      // Process all nodes that need updating
+      nodesToProcess.forEach(({ node, newContent }) => {
+        const parent = node.parentElement;
+        if (parent) {
+          // Create a temporary container to parse the HTML
+          const temp = document.createElement('span');
+          temp.innerHTML = newContent;
+
+          // Replace the text node with the parsed HTML nodes
+          const fragment = document.createDocumentFragment();
+          while (temp.firstChild) {
+            fragment.appendChild(temp.firstChild);
+          }
+
+          parent.replaceChild(fragment, node);
+        }
+      });
+    };
+
+    // Wait for content to render, then convert markers
+    const timer = setTimeout(() => {
+      convertMarkersToHtml();
+    }, 600);
+
+    // Set up observer to handle dynamic content changes
+    const proseMirrorEditor = editorRef.current.querySelector('.ProseMirror');
+    if (proseMirrorEditor) {
+      const observer = new MutationObserver(() => {
+        convertMarkersToHtml();
+      });
+
+      observer.observe(proseMirrorEditor, {
+        childList: true,
+        subtree: true,
+      });
+
+      return () => {
+        clearTimeout(timer);
+        observer.disconnect();
+      };
+    }
+
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [isEditorReady, displayMode]);
+
   // For all modes, use Milkdown to render markdown
   return (
     <PMBox data-milkdown-padding-variant={paddingVariant} css={markdownDiffCss}>

From 6debdb14f129b3191f29ad5ec32175fc55639231 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Fri, 27 Feb 2026 11:37:17 +0100
Subject: [PATCH 08/12] handle heading level change

---
 .../utils/markdownBlockDiff.spec.ts           |  34 +++++
 .../utils/markdownBlockDiff.ts                | 118 ++++++++++++------
 .../utils/rebuildMarkdownFromBlocks.spec.ts   |  14 +++
 .../utils/rebuildMarkdownFromBlocks.ts        |  11 +-
 4 files changed, 137 insertions(+), 40 deletions(-)

diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
index fe8e03bda..3502b7a7a 100644
--- a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.spec.ts
@@ -385,5 +385,39 @@ New paragraph
         ]),
       );
     });
+
+    it('detects heading level changes', () => {
+      const oldValue = '# My title';
+      const newValue = '## My title';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'heading',
+          level: '##',
+          content: 'My title',
+          status: 'updated',
+          diffContent: '# --My title--\n## ++My title++',
+        }),
+      ]);
+    });
+
+    it('detects heading level and content changes', () => {
+      const oldValue = '# Old title';
+      const newValue = '## New title';
+
+      const result = parseAndDiffMarkdown(oldValue, newValue);
+
+      expect(result).toEqual([
+        expect.objectContaining({
+          type: 'heading',
+          level: '##',
+          content: 'New title',
+          status: 'updated',
+          diffContent: '# --Old title--\n## ++New title++',
+        }),
+      ]);
+    });
   });
 });
diff --git a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
index 44e7778c9..ed4e366e4 100644
--- a/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/markdownBlockDiff.ts
@@ -373,26 +373,47 @@ export function parseAndDiffMarkdown(
               });
             } else {
               // Text blocks (heading, paragraph, code)
-              const diffHtml = buildWordDiffHtml(
-                oldBlock.content,
-                newBlock.content,
-              );
-
-              // For code blocks, also compute line-level diff
-              const updatedBlock: MarkdownBlock = {
-                ...newBlock,
-                status: 'updated',
-                diffContent: diffHtml,
-              };
-
-              if (newBlock.type === 'code') {
-                updatedBlock.lineDiff = buildLineDiff(
-                  oldBlock.content,
-                  newBlock.content,
-                );
+              // For headings with different levels, mark as complete replacement
+              if (
+                oldBlock.type === 'heading' &&
+                newBlock.type === 'heading' &&
+                oldBlock.level !== newBlock.level
+              ) {
+                result.push({
+                  ...newBlock,
+                  status: 'updated',
+                  diffContent: `${oldBlock.level || '#'} --${oldBlock.content}--\n${newBlock.level || '#'} ++${newBlock.content}++`,
+                });
+              } else {
+                // For headings with same level, include level markers in diff
+                // For other blocks, just use content
+                const oldText =
+                  oldBlock.type === 'heading'
+                    ? `${oldBlock.level || '#'} ${oldBlock.content}`
+                    : oldBlock.content;
+                const newText =
+                  newBlock.type === 'heading'
+                    ? `${newBlock.level || '#'} ${newBlock.content}`
+                    : newBlock.content;
+
+                const diffHtml = buildWordDiffHtml(oldText, newText);
+
+                // For code blocks, also compute line-level diff
+                const updatedBlock: MarkdownBlock = {
+                  ...newBlock,
+                  status: 'updated',
+                  diffContent: diffHtml,
+                };
+
+                if (newBlock.type === 'code') {
+                  updatedBlock.lineDiff = buildLineDiff(
+                    oldBlock.content,
+                    newBlock.content,
+                  );
+                }
+
+                result.push(updatedBlock);
               }
-
-              result.push(updatedBlock);
             }
           } else {
             // Different block types - mark as deleted and added
@@ -424,26 +445,47 @@ export function parseAndDiffMarkdown(
                 items: diffListItems(oldBlock.items, newBlock.items),
               });
             } else {
-              const diffHtml = buildWordDiffHtml(
-                oldBlock.content,
-                newBlock.content,
-              );
-
-              // For code blocks, also compute line-level diff
-              const updatedBlock: MarkdownBlock = {
-                ...newBlock,
-                status: 'updated',
-                diffContent: diffHtml,
-              };
-
-              if (newBlock.type === 'code') {
-                updatedBlock.lineDiff = buildLineDiff(
-                  oldBlock.content,
-                  newBlock.content,
-                );
+              // For headings with different levels, mark as complete replacement
+              if (
+                oldBlock.type === 'heading' &&
+                newBlock.type === 'heading' &&
+                oldBlock.level !== newBlock.level
+              ) {
+                result.push({
+                  ...newBlock,
+                  status: 'updated',
+                  diffContent: `${oldBlock.level || '#'} --${oldBlock.content}--\n${newBlock.level || '#'} ++${newBlock.content}++`,
+                });
+              } else {
+                // For headings with same level, include level markers in diff
+                // For other blocks, just use content
+                const oldText =
+                  oldBlock.type === 'heading'
+                    ? `${oldBlock.level || '#'} ${oldBlock.content}`
+                    : oldBlock.content;
+                const newText =
+                  newBlock.type === 'heading'
+                    ? `${newBlock.level || '#'} ${newBlock.content}`
+                    : newBlock.content;
+
+                const diffHtml = buildWordDiffHtml(oldText, newText);
+
+                // For code blocks, also compute line-level diff
+                const updatedBlock: MarkdownBlock = {
+                  ...newBlock,
+                  status: 'updated',
+                  diffContent: diffHtml,
+                };
+
+                if (newBlock.type === 'code') {
+                  updatedBlock.lineDiff = buildLineDiff(
+                    oldBlock.content,
+                    newBlock.content,
+                  );
+                }
+
+                result.push(updatedBlock);
               }
-
-              result.push(updatedBlock);
             }
           }
 
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
index bb32265d5..2471fafe3 100644
--- a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
@@ -136,6 +136,20 @@ function hello(name) {
       expect(result).toMatch(/# .*--Old--.*\+\+New\+\+(?![\s\S]*<h1>)/);
     });
 
+    it('renders heading level changes without duplicating level markers', () => {
+      const oldValue = '# My title';
+      const newValue = '## My title';
+
+      const blocks = parseAndDiffMarkdown(oldValue, newValue);
+      const result = rebuildMarkdownFromBlocks(blocks, {
+        includeDeleted: true,
+        useDiffContent: true,
+        mode: 'diff',
+      });
+
+      expect(result).toBe('# --My title--\n## ++My title++\n');
+    });
+
     it('includes deleted blocks in output', () => {
       const oldValue = '# Title\n\nParagraph to delete';
       const newValue = '# Title';
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
index 2903fc3b1..e31d6e268 100644
--- a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
@@ -40,8 +40,15 @@ export function rebuildMarkdownFromBlocks(
 
     switch (block.type) {
       case 'heading':
-        // Always use markdown syntax for headings
-        parts.push(`${block.level || '#'} ${content}\n`);
+        // For headings, check if diffContent already includes level markers
+        // (happens when heading level changes, e.g., "#--text--\n##++text++")
+        if (options.useDiffContent && content.startsWith('#')) {
+          // diffContent already includes heading levels, use as-is
+          parts.push(`${content}\n`);
+        } else {
+          // Normal heading or unified mode, prepend level
+          parts.push(`${block.level || '#'} ${content}\n`);
+        }
         break;
 
       case 'paragraph':

From a8ea7f870a34d2104965a48af1c9bcb68011525e Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Fri, 27 Feb 2026 12:00:10 +0100
Subject: [PATCH 09/12] Properly show code changes in unified view

---
 .../UnifiedMarkdownViewer.stories.tsx         |  21 ++-
 .../utils/rebuildMarkdownFromBlocks.spec.ts   |   4 +-
 .../utils/rebuildMarkdownFromBlocks.ts        |   7 +-
 .../components/editor/DiffMarkdownEditor.tsx  | 175 +++++++++---------
 4 files changed, 107 insertions(+), 100 deletions(-)

diff --git a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
index a894a4ce5..2622f78e0 100644
--- a/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/UnifiedMarkdownViewer.stories.tsx
@@ -8,16 +8,17 @@ const MultiViewer: React.FunctionComponent<
   Omit<UnifiedMarkdownViewerProps, 'displayMode'>
 > = (props) => {
   return (
-    <>
-      <h1>Unified view</h1>
-      <UnifiedMarkdownViewer {...props} displayMode={'unified'} />
-
-      <h1>Diff view</h1>
-      <UnifiedMarkdownViewer {...props} displayMode={'diff'} />
-
-      <h1>Plain view</h1>
-      <UnifiedMarkdownViewer {...props} displayMode={'plain'} />
-    </>
+    <div style={{ display: 'flex', flexDirection: 'row', gap: '2em' }}>
+      <div style={{ width: '50%' }}>
+        <h1>Unified view</h1>
+        <UnifiedMarkdownViewer {...props} displayMode={'unified'} />
+      </div>
+
+      <div style={{ flex: '1 1 0px' }}>
+        <h1>Diff view</h1>
+        <UnifiedMarkdownViewer {...props} displayMode={'diff'} />
+      </div>
+    </div>
   );
 };
 
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
index 2471fafe3..16a857783 100644
--- a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.spec.ts
@@ -21,7 +21,7 @@ describe('rebuildMarkdownFromBlocks', () => {
       );
     });
 
-    it('adds "Show code changes" trigger for updated code blocks', () => {
+    it('adds "[See code change]" marker for updated code blocks', () => {
       const oldValue = `\`\`\`javascript
 function hello() {
   console.log('Hello');
@@ -41,7 +41,7 @@ function hello(name) {
         mode: 'unified',
       });
 
-      expect(result).toContain('Show code changes');
+      expect(result).toMatch(/\[See code change\]\(#CODE_DIFF:.*\)/);
     });
 
     it('rebuilds list markdown preserving structure', () => {
diff --git a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
index e31d6e268..78561382c 100644
--- a/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
+++ b/apps/frontend/src/domain/change-proposals/utils/rebuildMarkdownFromBlocks.ts
@@ -82,15 +82,12 @@ export function rebuildMarkdownFromBlocks(
             block.status === 'updated' &&
             block.lineDiff
           ) {
-            // Add a special HTML comment that will be detected by the editor
-            // The lineDiff is base64 encoded to avoid breaking the HTML
+            // Add plain markdown with diff markers and encoded diff data in link
             const encodedDiff =
               typeof btoa !== 'undefined'
                 ? btoa(block.lineDiff)
                 : Buffer.from(block.lineDiff).toString('base64');
-            parts.push(
-              `<!-- CODE_DIFF:${encodedDiff} -->\n<span class="code-diff-trigger" data-line-diff="${encodedDiff}">Show code changes</span>\n`,
-            );
+            parts.push(`[See code change](#CODE_DIFF:${encodedDiff})\n`);
           }
         }
         break;
diff --git a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
index 8dd634e05..ca5638d59 100644
--- a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
+++ b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
@@ -372,24 +372,27 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
 
     const handleCodeDiffMouseEnter = (e: MouseEvent) => {
       const target = e.target as HTMLElement;
-      if (target.classList.contains('code-diff-trigger')) {
-        const encodedDiff = target.getAttribute('data-line-diff') || '';
-        let lineDiff = '';
-
-        try {
-          lineDiff =
-            typeof atob !== 'undefined'
-              ? atob(encodedDiff)
-              : Buffer.from(encodedDiff, 'base64').toString('utf-8');
-        } catch (error) {
-          console.error('Failed to decode line diff:', error);
-          return;
-        }
+      // Check if it's a link with #CODE_DIFF: href
+      if (target.tagName === 'A') {
+        const href = target.getAttribute('href') || '';
+        if (href.startsWith('#CODE_DIFF:')) {
+          const encodedDiff = href.substring('#CODE_DIFF:'.length);
+          let lineDiff = '';
+
+          try {
+            lineDiff =
+              typeof atob !== 'undefined'
+                ? atob(encodedDiff)
+                : Buffer.from(encodedDiff, 'base64').toString('utf-8');
+          } catch (error) {
+            console.error('Failed to decode line diff:', error);
+            return;
+          }
 
-        // Create tooltip element
-        const tooltip = document.createElement('div');
-        tooltip.className = 'code-diff-tooltip';
-        tooltip.style.cssText = `
+          // Create tooltip element
+          const tooltip = document.createElement('div');
+          tooltip.className = 'code-diff-tooltip';
+          tooltip.style.cssText = `
           position: fixed;
           z-index: 10000;
           background: #1f2937;
@@ -405,59 +408,60 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
           overflow-x: auto;
         `;
 
-        const header = document.createElement('div');
-        header.style.cssText =
-          'font-weight: bold; margin-bottom: 8px; font-family: sans-serif;';
-        header.textContent = 'Code changes';
-
-        const content = document.createElement('div');
-        content.style.cssText = 'font-size: 13px;';
-
-        // Format diff lines with colors
-        const lines = lineDiff.split('\n');
-        const formattedLines = lines
-          .map((line) => {
-            if (line.startsWith('+')) {
-              return `<span style="color: #86efac; background-color: rgba(34, 197, 94, 0.2);">${escapeHtmlInComponent(line)}</span>`;
-            } else if (line.startsWith('-')) {
-              return `<span style="color: #fca5a5; background-color: rgba(239, 68, 68, 0.2);">${escapeHtmlInComponent(line)}</span>`;
-            } else {
-              return `<span style="color: #d1d5db;">${escapeHtmlInComponent(line)}</span>`;
+          const header = document.createElement('div');
+          header.style.cssText =
+            'font-weight: bold; margin-bottom: 8px; font-family: sans-serif;';
+          header.textContent = 'Code changes';
+
+          const content = document.createElement('div');
+          content.style.cssText = 'font-size: 13px;';
+
+          // Format diff lines with colors
+          const lines = lineDiff.split('\n');
+          const formattedLines = lines
+            .map((line) => {
+              if (line.startsWith('+')) {
+                return `<span style="color: #86efac; background-color: rgba(34, 197, 94, 0.2);">${escapeHtmlInComponent(line)}</span>`;
+              } else if (line.startsWith('-')) {
+                return `<span style="color: #fca5a5; background-color: rgba(239, 68, 68, 0.2);">${escapeHtmlInComponent(line)}</span>`;
+              } else {
+                return `<span style="color: #d1d5db;">${escapeHtmlInComponent(line)}</span>`;
+              }
+            })
+            .join('\n');
+
+          content.innerHTML = formattedLines;
+
+          tooltip.appendChild(header);
+          tooltip.appendChild(content);
+
+          document.body.appendChild(tooltip);
+          target.setAttribute('data-code-tooltip-id', 'active');
+
+          // Position tooltip after append
+          requestAnimationFrame(() => {
+            const rect = target.getBoundingClientRect();
+            const tooltipRect = tooltip.getBoundingClientRect();
+
+            // Position above the element
+            let top = rect.top - tooltipRect.height - 8;
+            let left = rect.left + rect.width / 2 - tooltipRect.width / 2;
+
+            // Keep tooltip within viewport
+            if (top < 0) {
+              top = rect.bottom + 8;
+            }
+            if (left < 8) {
+              left = 8;
+            }
+            if (left + tooltipRect.width > window.innerWidth - 8) {
+              left = window.innerWidth - tooltipRect.width - 8;
             }
-          })
-          .join('\n');
-
-        content.innerHTML = formattedLines;
-
-        tooltip.appendChild(header);
-        tooltip.appendChild(content);
-
-        document.body.appendChild(tooltip);
-        target.setAttribute('data-code-tooltip-id', 'active');
-
-        // Position tooltip after append
-        requestAnimationFrame(() => {
-          const rect = target.getBoundingClientRect();
-          const tooltipRect = tooltip.getBoundingClientRect();
-
-          // Position above the element
-          let top = rect.top - tooltipRect.height - 8;
-          let left = rect.left + rect.width / 2 - tooltipRect.width / 2;
-
-          // Keep tooltip within viewport
-          if (top < 0) {
-            top = rect.bottom + 8;
-          }
-          if (left < 8) {
-            left = 8;
-          }
-          if (left + tooltipRect.width > window.innerWidth - 8) {
-            left = window.innerWidth - tooltipRect.width - 8;
-          }
 
-          tooltip.style.top = `${top}px`;
-          tooltip.style.left = `${left}px`;
-        });
+            tooltip.style.top = `${top}px`;
+            tooltip.style.left = `${left}px`;
+          });
+        }
       }
     };
 
@@ -481,26 +485,25 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
         .replace(/'/g, '&#039;');
     };
 
-    // Apply styling to code-diff-trigger elements
+    // Apply styling to code diff links
     const applyCodeDiffStyling = () => {
       const proseMirrorEditor =
         editorRef.current?.querySelector('.ProseMirror');
       if (!proseMirrorEditor) return;
 
-      const triggers = proseMirrorEditor.querySelectorAll('.code-diff-trigger');
-      triggers.forEach((trigger) => {
-        const element = trigger as HTMLElement;
-        element.style.cssText = `
-          display: inline-block;
-          margin-top: 8px;
-          padding: 4px 8px;
-          background: rgba(251, 191, 36, 0.2);
-          color: #f59e0b;
-          border-radius: 4px;
-          font-size: 12px;
-          cursor: pointer;
-          border: 1px solid rgba(251, 191, 36, 0.4);
-        `;
+      const links = proseMirrorEditor.querySelectorAll(
+        'a[href^="#CODE_DIFF:"]',
+      );
+      links.forEach((link) => {
+        const element = link as HTMLElement;
+        // The link will already have styling from the <ins> wrapper
+        // Just ensure it's clickable and has cursor pointer
+        element.style.cursor = 'pointer';
+        element.style.textDecoration = 'none';
+        // Prevent default link behavior
+        element.addEventListener('click', (e) => {
+          e.preventDefault();
+        });
       });
     };
 
@@ -510,6 +513,12 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
     }, 500);
 
     const editor = editorRef.current;
+    if (!editor) {
+      return () => {
+        clearTimeout(timer);
+      };
+    }
+
     editor.addEventListener('mouseover', handleCodeDiffMouseEnter);
     editor.addEventListener('mouseout', handleCodeDiffMouseLeave);
 

From fe55ded5ff9b33ff29f026fd689e33e9f7fbbb82 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Fri, 27 Feb 2026 12:01:18 +0100
Subject: [PATCH 10/12] Drop debug pre in markdown viewer

---
 .../frontend/src/shared/components/editor/DiffMarkdownEditor.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
index ca5638d59..8f9cabd78 100644
--- a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
+++ b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
@@ -620,7 +620,6 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
   return (
     <PMBox data-milkdown-padding-variant={paddingVariant} css={markdownDiffCss}>
       <Milkdown />
-      <pre>{editorContent}</pre>
     </PMBox>
   );
 };

From 7ea5addb1e58e46e6bbb211ce9268f63eeda59c0 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Fri, 27 Feb 2026 12:07:20 +0100
Subject: [PATCH 11/12] Do not duplicate highlights on li items

---
 .../src/shared/components/editor/DiffMarkdownEditor.tsx       | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
index 8f9cabd78..431e00b03 100644
--- a/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
+++ b/apps/frontend/src/shared/components/editor/DiffMarkdownEditor.tsx
@@ -155,9 +155,9 @@ export const DiffMarkdownEditor: React.FC<IDiffMarkdownEditorProps> = ({
         editorRef.current?.querySelector('.ProseMirror');
       if (!proseMirrorEditor) return;
 
-      // Get all text-containing elements
+      // Get all text-containing elements (exclude li since content is in p inside)
       const contentElements = proseMirrorEditor.querySelectorAll(
-        'p, h1, h2, h3, h4, h5, h6, li, code',
+        'p, h1, h2, h3, h4, h5, h6, code',
       );
 
       if (contentElements.length === 0) return;

From fc61d30ed08bc5a5077011a29a47bb0559216c19 Mon Sep 17 00:00:00 2001
From: Vincent Pretre <vincent.pretre@gmail.com>
Date: Fri, 27 Feb 2026 12:58:05 +0100
Subject: [PATCH 12/12] Enable new editor in standard preview

---
 .../ProposalReviewPanel.tsx                   | 28 ++++++++++++-------
 1 file changed, 18 insertions(+), 10 deletions(-)

diff --git a/apps/frontend/src/domain/change-proposals/components/StandardReviewDetail/ProposalReviewPanel.tsx b/apps/frontend/src/domain/change-proposals/components/StandardReviewDetail/ProposalReviewPanel.tsx
index 1084a8a5b..8a3d6ffc2 100644
--- a/apps/frontend/src/domain/change-proposals/components/StandardReviewDetail/ProposalReviewPanel.tsx
+++ b/apps/frontend/src/domain/change-proposals/components/StandardReviewDetail/ProposalReviewPanel.tsx
@@ -31,7 +31,6 @@ import {
 import { HighlightedText, HighlightedRuleBox } from '../HighlightedContent';
 import { UnifiedMarkdownViewer } from '../UnifiedMarkdownViewer';
 import { useDiffNavigation } from '../../hooks/useDiffNavigation';
-import { renderMarkdownDiffOrPreview } from '../SkillReviewDetail/SkillContent/renderMarkdownDiffOrPreview';
 
 interface ProposalReviewPanelProps {
   selectedStandard: Standard | undefined;
@@ -244,15 +243,24 @@ export function ProposalReviewPanel({
                 ? renderDiffText(payload.oldValue, payload.newValue)
                 : selectedStandard.name}
             </PMText>
-            {renderMarkdownDiffOrPreview(
-              isDescriptionDiff,
-              showPreview,
-              payload,
-              selectedStandard.description,
-              {
-                previewPaddingVariant: 'none',
-                defaultPaddingVariant: 'none',
-              },
+            {isDescriptionDiff ? (
+              <UnifiedMarkdownViewer
+                key={showPreview ? 'preview' : 'diff'}
+                oldValue={payload.oldValue}
+                newValue={payload.newValue}
+                proposalNumbers={[
+                  proposalNumberMap.get(reviewingProposal.id) ?? 0,
+                ]}
+                displayMode={showPreview ? 'unified' : 'diff'}
+              />
+            ) : (
+              <MarkdownEditorProvider>
+                <MarkdownEditor
+                  defaultValue={selectedStandard.description}
+                  readOnly
+                  paddingVariant="none"
+                />
+              </MarkdownEditorProvider>
             )}
 
             {/* Rules Section */}