From 04c755da5d4fd9cb66992655567b362bafaa302b Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:05:21 -0400
Subject: [PATCH 01/26] fix(core): improve mermaid cache race handling and
 renderer robustness

---
 src/core/render-pipeline.ts                   |  41 ++-
 src/renderers/mermaid-renderer.ts             |  20 +-
 tests/unit/core/mermaid-cache-race.test.ts    | 281 +++++++++++++++
 tests/unit/renderers/mermaid-renderer.test.ts | 322 ++++++++++++++++++
 4 files changed, 645 insertions(+), 19 deletions(-)
 create mode 100644 tests/unit/core/mermaid-cache-race.test.ts
 create mode 100644 tests/unit/renderers/mermaid-renderer.test.ts

diff --git a/src/core/render-pipeline.ts b/src/core/render-pipeline.ts
index 5925b5f..3635a26 100644
--- a/src/core/render-pipeline.ts
+++ b/src/core/render-pipeline.ts
@@ -347,13 +347,22 @@ export class RenderPipeline {
     // Re-setup image lazy loading
     this.setupImageLazyLoading(container);
 
-    // Re-initialize Mermaid diagrams (they may need panzoom reinitialization)
-    const mermaidContainers = container.querySelectorAll('.mermaid-container.mermaid-ready');
-    if (mermaidContainers.length > 0) {
+    // Re-initialize Mermaid diagrams
+    const pendingMermaid = container.querySelectorAll('.mermaid-container.mermaid-pending');
+    const readyMermaid = container.querySelectorAll('.mermaid-container.mermaid-ready');
+
+    if (pendingMermaid.length > 0 || readyMermaid.length > 0) {
       try {
-        // Mermaid diagrams should already have SVG from cache
-        // Controls will be re-added automatically when mermaid module loads
-        await import('../renderers/mermaid-renderer');
+        const { mermaidRenderer } = await import('../renderers/mermaid-renderer');
+
+        // Re-render any pending diagrams that were cached before rendering completed
+        if (pendingMermaid.length > 0) {
+          debug.info(
+            'RenderPipeline',
+            `Re-rendering ${pendingMermaid.length} pending mermaid diagram(s) from stale cache`
+          );
+          await mermaidRenderer.renderAll(container);
+        }
       } catch (error) {
         debug.error('RenderPipeline', 'Failed to reinitialize mermaid:', error);
       }
@@ -378,11 +387,11 @@ export class RenderPipeline {
       await this.applySyntaxHighlighting(container);
     }
 
-    // CRITICAL: Mark Mermaid blocks (actual rendering happens lazily on intersection)
-    debug.debug('RenderPipeline', 'Marking Mermaid blocks...');
-    this.markMermaidBlocks(container);
+    // CRITICAL: Mark and render Mermaid blocks (awaited so cache captures rendered state)
+    debug.debug('RenderPipeline', 'Rendering Mermaid blocks...');
+    await this.markAndRenderMermaidBlocks(container);
 
-    debug.debug('RenderPipeline', 'Syntax highlighting complete');
+    debug.debug('RenderPipeline', 'Enhancement complete');
 
     // NON-CRITICAL: Schedule remaining enhancements during idle time
     // This improves perceived performance by not blocking the main render
@@ -914,18 +923,18 @@ export class RenderPipeline {
   }
 
   /**
-   * Mark Mermaid blocks for rendering
+   * Mark Mermaid blocks for rendering and await completion
    */
-  private markMermaidBlocks(container: HTMLElement): void {
+  private async markAndRenderMermaidBlocks(container: HTMLElement): Promise<void> {
     const mermaidBlocks = container.querySelectorAll('.mermaid-container');
     mermaidBlocks.forEach((block) => {
       block.classList.add('mermaid-pending');
     });
 
-    // Initialize Mermaid renderer
-    this.renderMermaidDiagrams(container).catch((error) => {
-      debug.error('RenderPipeline', 'Mermaid rendering catch error:', error);
-    });
+    // Await mermaid rendering so cache captures the rendered state
+    if (mermaidBlocks.length > 0) {
+      await this.renderMermaidDiagrams(container);
+    }
   }
 
   /**
diff --git a/src/renderers/mermaid-renderer.ts b/src/renderers/mermaid-renderer.ts
index 013a944..25f811a 100644
--- a/src/renderers/mermaid-renderer.ts
+++ b/src/renderers/mermaid-renderer.ts
@@ -278,13 +278,27 @@ export class MermaidRenderer {
       // Generate unique ID for SVG
       const svgId = `mermaid-svg-${containerId}`;
 
-      // Render with timeout
+      // Render with timeout and proper cleanup
+      let timeoutId: ReturnType<typeof setTimeout>;
       const renderPromise = mermaid.render(svgId, code);
       const timeoutPromise = new Promise<never>((_, reject) => {
-        setTimeout(() => reject(new Error('Render timeout')), 5000);
+        timeoutId = setTimeout(() => reject(new Error('Render timeout')), 5000);
       });
 
-      const result = await Promise.race([renderPromise, timeoutPromise]);
+      let result: { svg: string };
+      try {
+        result = await Promise.race([renderPromise, timeoutPromise]);
+        clearTimeout(timeoutId!);
+      } catch (error) {
+        clearTimeout(timeoutId!);
+        // Clean up any orphaned DOM elements that mermaid.render() may have created
+        // mermaid creates temporary SVG elements with the svgId during rendering
+        const orphanedSvg = document.getElementById(svgId);
+        if (orphanedSvg) {
+          orphanedSvg.remove();
+        }
+        throw error;
+      }
 
       // Clear loading state
       container.innerHTML = '';
diff --git a/tests/unit/core/mermaid-cache-race.test.ts b/tests/unit/core/mermaid-cache-race.test.ts
new file mode 100644
index 0000000..d9602c3
--- /dev/null
+++ b/tests/unit/core/mermaid-cache-race.test.ts
@@ -0,0 +1,281 @@
+/**
+ * Tests for mermaid rendering / cache race condition fix
+ *
+ * Verifies that:
+ * 1. Mermaid rendering completes BEFORE cache is written
+ * 2. Cache restore re-renders any pending mermaid diagrams
+ * 3. Timeout properly cleans up orphaned mermaid DOM elements
+ */
+
+import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import { RenderPipeline } from '../../../src/core/render-pipeline';
+import { createTestContainer, cleanupTestContainer, mockConsole } from '../../helpers/test-utils';
+import { mockChromeRuntime, waitFor } from '../../helpers/mocks';
+
+// The mock renderAll should simulate what the real one does: change classes on containers
+const mockRenderAll = vi.fn().mockImplementation(async (container: HTMLElement) => {
+  // Simulate successful rendering: remove pending, add ready
+  const pending = container.querySelectorAll('.mermaid-container.mermaid-pending');
+  pending.forEach((el) => {
+    el.classList.remove('mermaid-pending');
+    el.classList.add('mermaid-ready');
+    el.innerHTML = '<div class="mermaid-rendered"><svg>rendered</svg></div>';
+  });
+});
+
+vi.mock('../../../src/renderers/mermaid-renderer', () => ({
+  mermaidRenderer: {
+    renderAll: mockRenderAll,
+    renderAllImmediate: vi.fn().mockResolvedValue(undefined),
+    updateTheme: vi.fn(),
+    cleanup: vi.fn(),
+  },
+}));
+
+vi.mock('../../../src/renderers/syntax-highlighter', () => ({
+  syntaxHighlighter: {
+    highlightVisible: vi.fn(),
+    highlightAll: vi.fn(),
+    setTheme: vi.fn(),
+  },
+}));
+
+vi.mock('../../../src/workers/worker-pool', () => ({
+  workerPool: {
+    initialize: vi.fn().mockRejectedValue(new Error('file:// not supported')),
+    execute: vi.fn(),
+    terminate: vi.fn(),
+  },
+}));
+
+describe('Mermaid Cache Race Condition', () => {
+  let pipeline: RenderPipeline;
+  let container: HTMLElement;
+  let consoleMock: { restore: () => void };
+  let sendMessageMock: ReturnType<typeof vi.fn>;
+
+  // Markdown that produces mermaid containers
+  const mermaidMarkdown = '# Test\n\n```mermaid\ngraph TD\n  A-->B\n```\n\nSome text.';
+
+  beforeEach(() => {
+    consoleMock = mockConsole();
+    container = createTestContainer();
+    vi.clearAllMocks();
+
+    // Re-apply the mock implementation after clearAllMocks
+    mockRenderAll.mockImplementation(async (cont: HTMLElement) => {
+      const pending = cont.querySelectorAll('.mermaid-container.mermaid-pending');
+      pending.forEach((el) => {
+        el.classList.remove('mermaid-pending');
+        el.classList.add('mermaid-ready');
+        el.innerHTML = '<div class="mermaid-rendered"><svg>rendered</svg></div>';
+      });
+    });
+
+    const mocks = mockChromeRuntime();
+    sendMessageMock = mocks.sendMessage;
+
+    pipeline = new RenderPipeline();
+  });
+
+  afterEach(() => {
+    cleanupTestContainer(container);
+    consoleMock.restore();
+  });
+
+  describe('Cache write timing', () => {
+    test('should await mermaid rendering before writing cache', async () => {
+      // Track the order of operations
+      const operationOrder: string[] = [];
+
+      mockRenderAll.mockImplementation(async (cont: HTMLElement) => {
+        operationOrder.push('mermaid-render-start');
+        // Simulate mermaid rendering taking some time
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        // Simulate DOM update
+        const pending = cont.querySelectorAll('.mermaid-container.mermaid-pending');
+        pending.forEach((el) => {
+          el.classList.remove('mermaid-pending');
+          el.classList.add('mermaid-ready');
+          el.innerHTML = '<div class="mermaid-rendered"><svg>rendered</svg></div>';
+        });
+        operationOrder.push('mermaid-render-complete');
+      });
+
+      sendMessageMock.mockImplementation((message: { type: string }) => {
+        if (message.type === 'CACHE_SET') {
+          operationOrder.push('cache-set');
+        }
+        if (message.type === 'CACHE_GENERATE_KEY') {
+          return Promise.resolve({ key: 'test-key' });
+        }
+        if (message.type === 'CACHE_GET') {
+          return Promise.resolve({ result: null });
+        }
+        return Promise.resolve({ success: true });
+      });
+
+      await pipeline.render({
+        container,
+        markdown: mermaidMarkdown,
+        useCache: true,
+        useWorkers: false,
+        filePath: '/test/file.md',
+        theme: 'github-light',
+      });
+
+      // Wait for any async operations
+      await waitFor(100);
+
+      // Mermaid render should complete BEFORE cache write
+      const mermaidCompleteIdx = operationOrder.indexOf('mermaid-render-complete');
+      const cacheSetIdx = operationOrder.indexOf('cache-set');
+
+      expect(operationOrder).toContain('mermaid-render-start');
+      expect(operationOrder).toContain('mermaid-render-complete');
+
+      // If caching happened, mermaid should have completed first
+      if (cacheSetIdx >= 0) {
+        expect(mermaidCompleteIdx).toBeLessThan(cacheSetIdx);
+      }
+    });
+
+    test('should not cache HTML with mermaid-pending containers', async () => {
+      let cachedHtml = '';
+
+      sendMessageMock.mockImplementation((message: { type: string; payload?: any }) => {
+        if (message.type === 'CACHE_SET') {
+          cachedHtml = message.payload?.result?.html || '';
+          return Promise.resolve({ success: true });
+        }
+        if (message.type === 'CACHE_GENERATE_KEY') {
+          return Promise.resolve({ key: 'test-key' });
+        }
+        if (message.type === 'CACHE_GET') {
+          return Promise.resolve({ result: null });
+        }
+        return Promise.resolve({ success: true });
+      });
+
+      await pipeline.render({
+        container,
+        markdown: mermaidMarkdown,
+        useCache: true,
+        useWorkers: false,
+        filePath: '/test/file.md',
+        theme: 'github-light',
+      });
+
+      await waitFor(100);
+
+      // Cache should have been written
+      expect(cachedHtml).not.toBe('');
+      // Cache should NOT contain mermaid-pending (rendering was awaited)
+      expect(cachedHtml).not.toContain('mermaid-pending');
+    });
+  });
+
+  describe('Cache restore with mermaid', () => {
+    test('should re-render pending mermaid diagrams from stale cache', async () => {
+      // Simulate a stale cache hit that has mermaid-pending containers
+      const staleHtml = `
+        <h1>Test</h1>
+        <div class="mermaid-container mermaid-pending" id="mermaid-abc123" data-mermaid-code="graph TD\n  A-->B">
+          <div class="mermaid-loading">Rendering diagram...</div>
+        </div>
+        <p>Some text.</p>
+      `;
+
+      sendMessageMock.mockImplementation((message: { type: string }) => {
+        if (message.type === 'CACHE_GENERATE_KEY') {
+          return Promise.resolve({ key: 'cached-key' });
+        }
+        if (message.type === 'CACHE_GET') {
+          return Promise.resolve({
+            result: {
+              html: staleHtml,
+              metadata: {
+                wordCount: 5,
+                headings: [],
+                codeBlocks: [],
+                mermaidBlocks: [],
+                images: [],
+                links: [],
+                frontmatter: null,
+              },
+              highlightedBlocks: new Map(),
+              mermaidSVGs: new Map(),
+              timestamp: Date.now(),
+              cacheKey: 'cached-key',
+            },
+          });
+        }
+        return Promise.resolve({ success: true });
+      });
+
+      await pipeline.render({
+        container,
+        markdown: mermaidMarkdown,
+        useCache: true,
+        useWorkers: false,
+        filePath: '/test/file.md',
+        theme: 'github-light',
+      });
+
+      await waitFor(100);
+
+      // Should have triggered mermaid renderAll for the pending diagrams
+      expect(mockRenderAll).toHaveBeenCalled();
+    });
+
+    test('should not re-render when cache only has mermaid-ready containers', async () => {
+      const goodCacheHtml = `
+        <h1>Test</h1>
+        <div class="mermaid-container mermaid-ready" id="mermaid-def456">
+          <div class="mermaid-rendered"><svg>cached svg</svg></div>
+        </div>
+      `;
+
+      sendMessageMock.mockImplementation((message: { type: string }) => {
+        if (message.type === 'CACHE_GENERATE_KEY') {
+          return Promise.resolve({ key: 'good-cached-key' });
+        }
+        if (message.type === 'CACHE_GET') {
+          return Promise.resolve({
+            result: {
+              html: goodCacheHtml,
+              metadata: {
+                wordCount: 2,
+                headings: [],
+                codeBlocks: [],
+                mermaidBlocks: [],
+                images: [],
+                links: [],
+                frontmatter: null,
+              },
+              highlightedBlocks: new Map(),
+              mermaidSVGs: new Map(),
+              timestamp: Date.now(),
+              cacheKey: 'good-cached-key',
+            },
+          });
+        }
+        return Promise.resolve({ success: true });
+      });
+
+      await pipeline.render({
+        container,
+        markdown: '# Test\n\n```mermaid\ngraph TD\n  A-->B\n```',
+        useCache: true,
+        useWorkers: false,
+        filePath: '/test/ready.md',
+        theme: 'github-light',
+      });
+
+      await waitFor(100);
+
+      // renderAll should NOT be called - no pending diagrams
+      expect(mockRenderAll).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/tests/unit/renderers/mermaid-renderer.test.ts b/tests/unit/renderers/mermaid-renderer.test.ts
new file mode 100644
index 0000000..8db61c0
--- /dev/null
+++ b/tests/unit/renderers/mermaid-renderer.test.ts
@@ -0,0 +1,322 @@
+/**
+ * Unit tests for Mermaid Renderer
+ * Covers: render queue, timeout cleanup, and state management
+ */
+
+import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createTestContainer, cleanupTestContainer, mockConsole } from '../../helpers/test-utils';
+import { waitFor } from '../../helpers/mocks';
+
+// vi.mock factories are hoisted - cannot reference outer variables
+vi.mock('mermaid', () => ({
+  default: {
+    initialize: vi.fn(),
+    parse: vi.fn().mockResolvedValue({ diagramType: 'flowchart-v2', config: {} }),
+    render: vi.fn().mockResolvedValue({ svg: '<svg id="test">mock</svg>', diagramType: 'flowchart-v2' }),
+  },
+}));
+
+vi.mock('panzoom', () => ({
+  default: vi.fn().mockReturnValue({
+    dispose: vi.fn(),
+    getTransform: vi.fn().mockReturnValue({ scale: 1, x: 0, y: 0 }),
+    moveTo: vi.fn(),
+    zoomAbs: vi.fn(),
+    zoomTo: vi.fn(),
+    smoothZoomAbs: vi.fn(),
+  }),
+}));
+
+// Import after mocks are set up
+import mermaid from 'mermaid';
+import Panzoom from 'panzoom';
+import { MermaidRenderer } from '../../../src/renderers/mermaid-renderer';
+
+describe('MermaidRenderer', () => {
+  let renderer: MermaidRenderer;
+  let container: HTMLElement;
+  let consoleMock: { restore: () => void };
+
+  beforeEach(() => {
+    consoleMock = mockConsole();
+    container = createTestContainer();
+    vi.clearAllMocks();
+
+    // Reset mermaid mocks to success state
+    vi.mocked(mermaid.parse).mockResolvedValue({ diagramType: 'flowchart-v2', config: {} });
+    vi.mocked(mermaid.render).mockResolvedValue({ svg: '<svg id="test">mock diagram</svg>', diagramType: 'flowchart-v2' });
+
+    renderer = new MermaidRenderer();
+  });
+
+  afterEach(() => {
+    renderer.cleanup();
+    cleanupTestContainer(container);
+    consoleMock.restore();
+  });
+
+  /**
+   * Helper: create a mermaid container element in the DOM with code registered
+   */
+  function createMermaidContainer(id: string, code: string): HTMLElement {
+    const el = document.createElement('div');
+    el.id = id;
+    el.className = 'mermaid-container mermaid-pending';
+    el.innerHTML = '<div class="mermaid-loading">Rendering diagram...</div>';
+    el.setAttribute('data-mermaid-code', code);
+    container.appendChild(el);
+
+    // Register in global registry
+    const win = window as { __MDVIEW_MERMAID_CODE__?: Map<string, string> };
+    if (!win.__MDVIEW_MERMAID_CODE__) {
+      win.__MDVIEW_MERMAID_CODE__ = new Map();
+    }
+    win.__MDVIEW_MERMAID_CODE__.set(id, code);
+
+    return el;
+  }
+
+  describe('renderDiagram', () => {
+    test('should render a valid mermaid diagram', async () => {
+      const el = createMermaidContainer('mermaid-test1', 'graph TD\n  A-->B');
+
+      await renderer.renderDiagram('mermaid-test1');
+
+      expect(mermaid.parse).toHaveBeenCalledWith('graph TD\n  A-->B');
+      expect(mermaid.render).toHaveBeenCalled();
+      expect(el.classList.contains('mermaid-ready')).toBe(true);
+      expect(el.classList.contains('mermaid-pending')).toBe(false);
+      expect(el.querySelector('.mermaid-rendered')).not.toBeNull();
+    });
+
+    test('should show error for invalid syntax', async () => {
+      vi.mocked(mermaid.parse).mockRejectedValue(new Error('Parse error: invalid syntax'));
+      const el = createMermaidContainer('mermaid-bad', 'not valid mermaid');
+
+      await renderer.renderDiagram('mermaid-bad');
+
+      expect(el.classList.contains('mermaid-error')).toBe(true);
+      expect(el.innerHTML).toContain('Mermaid Diagram Error');
+    });
+
+    test('should skip already-rendered containers', async () => {
+      const el = createMermaidContainer('mermaid-done', 'graph TD\n  A-->B');
+      // Simulate already rendered by adding SVG
+      const wrapper = document.createElement('div');
+      wrapper.className = 'mermaid-rendered';
+      wrapper.innerHTML = '<svg>already rendered</svg>';
+      el.innerHTML = '';
+      el.appendChild(wrapper);
+
+      await renderer.renderDiagram('mermaid-done');
+
+      // Should not call mermaid.render again
+      expect(mermaid.render).not.toHaveBeenCalled();
+    });
+
+    test('should handle missing container gracefully', async () => {
+      await renderer.renderDiagram('nonexistent-id');
+      expect(mermaid.render).not.toHaveBeenCalled();
+    });
+
+    test('should handle missing code gracefully', async () => {
+      const el = document.createElement('div');
+      el.id = 'mermaid-nocode';
+      el.className = 'mermaid-container mermaid-pending';
+      container.appendChild(el);
+
+      await renderer.renderDiagram('mermaid-nocode');
+
+      expect(mermaid.render).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('render queue serialization', () => {
+    test('should serialize concurrent renders through the queue', async () => {
+      createMermaidContainer('mermaid-q1', 'graph TD\n  A-->B');
+      createMermaidContainer('mermaid-q2', 'graph TD\n  C-->D');
+
+      // Make the first render slow - resolves only when we call resolveFirst()
+      let resolveFirst!: (value: { svg: string; diagramType: string }) => void;
+      vi.mocked(mermaid.render)
+        .mockImplementationOnce(
+          () => new Promise((resolve) => { resolveFirst = resolve; })
+        )
+        .mockResolvedValueOnce({ svg: '<svg>second</svg>', diagramType: 'flowchart-v2' });
+
+      // Start first render - it will proceed through validateSyntax, then block on mermaid.render
+      const p1 = renderer.renderDiagram('mermaid-q1');
+
+      // Wait for validateSyntax (mermaid.parse) to resolve so mermaid.render gets called
+      await waitFor(10);
+
+      // Now start second render - isRendering should be true, so it gets queued
+      void renderer.renderDiagram('mermaid-q2');
+
+      // First render's mermaid.render should have been called once
+      expect(mermaid.render).toHaveBeenCalledTimes(1);
+
+      // Complete first render
+      resolveFirst({ svg: '<svg>first</svg>', diagramType: 'flowchart-v2' });
+      await p1;
+
+      // Wait for queue processing
+      await waitFor(50);
+
+      // Second render should have been processed from queue
+      expect(mermaid.render).toHaveBeenCalledTimes(2);
+    });
+
+    test('should reset isRendering flag even on error', async () => {
+      createMermaidContainer('mermaid-err', 'graph TD\n  A-->B');
+      createMermaidContainer('mermaid-after', 'graph TD\n  C-->D');
+
+      // First render fails at mermaid.render
+      vi.mocked(mermaid.render)
+        .mockRejectedValueOnce(new Error('Render failed'))
+        .mockResolvedValueOnce({ svg: '<svg>recovered</svg>', diagramType: 'flowchart-v2' });
+
+      // First render - will fail
+      await renderer.renderDiagram('mermaid-err');
+
+      const errEl = document.getElementById('mermaid-err');
+      expect(errEl?.classList.contains('mermaid-error')).toBe(true);
+
+      // Second render should work since isRendering was reset in finally
+      await renderer.renderDiagram('mermaid-after');
+
+      const afterEl = document.getElementById('mermaid-after');
+      expect(afterEl?.classList.contains('mermaid-ready')).toBe(true);
+    });
+  });
+
+  describe('render timeout', () => {
+    test('should timeout after 5 seconds and show error', async () => {
+      vi.useFakeTimers();
+
+      createMermaidContainer('mermaid-slow', 'graph TD\n  A-->B');
+
+      // parse resolves immediately, but render never resolves
+      vi.mocked(mermaid.render).mockImplementation(() => new Promise(() => {}));
+
+      const renderPromise = renderer.renderDiagram('mermaid-slow');
+
+      // Allow microtasks (validateSyntax) to run
+      await vi.advanceTimersByTimeAsync(0);
+
+      // Advance past the 5-second timeout
+      await vi.advanceTimersByTimeAsync(5100);
+
+      await renderPromise;
+
+      const el = document.getElementById('mermaid-slow');
+      expect(el?.classList.contains('mermaid-error')).toBe(true);
+      expect(el?.innerHTML).toContain('Render timeout');
+
+      vi.useRealTimers();
+    });
+
+    test('should reset isRendering after timeout so queue continues', async () => {
+      vi.useFakeTimers();
+
+      createMermaidContainer('mermaid-timeout1', 'graph TD\n  A-->B');
+      createMermaidContainer('mermaid-timeout2', 'graph TD\n  C-->D');
+
+      // First render hangs, second succeeds
+      vi.mocked(mermaid.render)
+        .mockImplementationOnce(() => new Promise(() => {}))
+        .mockResolvedValueOnce({ svg: '<svg>recovered</svg>', diagramType: 'flowchart-v2' });
+
+      const p1 = renderer.renderDiagram('mermaid-timeout1');
+
+      // Let validateSyntax complete and mermaid.render start
+      await vi.advanceTimersByTimeAsync(0);
+
+      // Queue second render
+      renderer.renderDiagram('mermaid-timeout2');
+
+      // Trigger timeout for first render
+      await vi.advanceTimersByTimeAsync(5100);
+
+      await p1;
+
+      // Wait for queue to process second render
+      await vi.advanceTimersByTimeAsync(100);
+
+      const el1 = document.getElementById('mermaid-timeout1');
+      expect(el1?.classList.contains('mermaid-error')).toBe(true);
+
+      const el2 = document.getElementById('mermaid-timeout2');
+      expect(el2?.classList.contains('mermaid-ready')).toBe(true);
+
+      vi.useRealTimers();
+    });
+
+    test('should clean up orphaned mermaid DOM elements after timeout', async () => {
+      vi.useFakeTimers();
+
+      createMermaidContainer('mermaid-orphan', 'graph TD\n  A-->B');
+
+      // Simulate mermaid leaving orphaned SVG elements during rendering
+      vi.mocked(mermaid.render).mockImplementation(async (svgId: string) => {
+        const orphan = document.createElement('svg');
+        orphan.id = svgId;
+        document.body.appendChild(orphan);
+        // Hang forever
+        return new Promise(() => {});
+      });
+
+      const renderPromise = renderer.renderDiagram('mermaid-orphan');
+
+      // Let validateSyntax + mermaid.render start
+      await vi.advanceTimersByTimeAsync(0);
+
+      // Trigger timeout
+      await vi.advanceTimersByTimeAsync(5100);
+
+      await renderPromise;
+
+      // Orphaned SVG should have been cleaned up
+      const orphanedSvg = document.getElementById('mermaid-svg-mermaid-orphan');
+      expect(orphanedSvg).toBeNull();
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('renderAll', () => {
+    test('should render all pending diagrams in a container', async () => {
+      createMermaidContainer('mermaid-all1', 'graph TD\n  A-->B');
+      createMermaidContainer('mermaid-all2', 'graph TD\n  C-->D');
+
+      // Force no observer for immediate rendering
+      renderer.cleanup();
+      renderer = new MermaidRenderer();
+      (renderer as any).observer = null;
+
+      await renderer.renderAll(container);
+
+      // Both should be rendered (queue processes sequentially)
+      await waitFor(100);
+
+      expect(mermaid.render).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('cleanup', () => {
+    test('should dispose all panzoom instances', async () => {
+      createMermaidContainer('mermaid-cleanup1', 'graph TD\n  A-->B');
+      await renderer.renderDiagram('mermaid-cleanup1');
+
+      const panzoomInstance = vi.mocked(Panzoom).mock.results[0]?.value;
+      renderer.cleanup();
+
+      expect(panzoomInstance.dispose).toHaveBeenCalled();
+    });
+
+    test('should not throw on double cleanup', () => {
+      renderer.cleanup();
+      expect(() => renderer.cleanup()).not.toThrow();
+    });
+  });
+});

From 5fd8135b7c4b4bd8eb4c43de7e68785a174b04f9 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:09:06 -0400
Subject: [PATCH 02/26] chore: add workspace structure and @mdview/core package
 skeleton

---
 package-lock.json                         | 127 ++++++++++++++++------
 package.json                              |   3 +
 packages/core/package.json                |  15 +++
 packages/core/src/__tests__/smoke.test.ts |   7 ++
 packages/core/src/index.ts                |   3 +
 packages/core/tsconfig.json               |  12 ++
 packages/core/vitest.config.ts            |   9 ++
 7 files changed, 143 insertions(+), 33 deletions(-)
 create mode 100644 packages/core/package.json
 create mode 100644 packages/core/src/__tests__/smoke.test.ts
 create mode 100644 packages/core/src/index.ts
 create mode 100644 packages/core/tsconfig.json
 create mode 100644 packages/core/vitest.config.ts

diff --git a/package-lock.json b/package-lock.json
index 84b35be..74f53af 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,6 +8,9 @@
       "name": "mdview",
       "version": "0.3.4",
       "license": "MIT",
+      "workspaces": [
+        "packages/*"
+      ],
       "dependencies": {
         "@jamesainslie/docx": "^9.5.1-svg.1",
         "dompurify": "^3.0.6",
@@ -139,6 +142,7 @@
       "integrity": "sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/helper-validator-identifier": "^7.27.1",
         "js-tokens": "^4.0.0",
@@ -154,6 +158,7 @@
       "integrity": "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=6.9.0"
       }
@@ -322,7 +327,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=18"
       },
@@ -366,7 +370,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -1679,6 +1682,10 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@mdview/core": {
+      "resolved": "packages/core",
+      "link": true
+    },
     "node_modules/@mermaid-js/mermaid-cli": {
       "version": "11.12.0",
       "resolved": "https://registry.npmjs.org/@mermaid-js/mermaid-cli/-/mermaid-cli-11.12.0.tgz",
@@ -1792,6 +1799,7 @@
       "integrity": "sha512-aBSREisdsGH890S2rQqK82qmQYU3uFpSH8wcZWHgHzl3LfzsxAKbLNiAG9mO8v1Y0UICBeClICxPJvyr0rcuxg==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "debug": "^4.4.0",
         "extract-zip": "^2.0.1",
@@ -2286,7 +2294,8 @@
       "resolved": "https://registry.npmjs.org/@tootallnate/quickjs-emscripten/-/quickjs-emscripten-0.23.0.tgz",
       "integrity": "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@types/chai": {
       "version": "5.2.3",
@@ -2679,7 +2688,6 @@
       "resolved": "https://registry.npmjs.org/@types/markdown-it/-/markdown-it-13.0.9.tgz",
       "integrity": "sha512-1XPwR0+MgXLWfTn9gCsZ55AHOKW1WN+P9vr0PaQh5aerR9LLQXUbjfEAFhjmEmyoYFWAyuN2Mqkn40MZ4ukjBw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/linkify-it": "^3",
         "@types/mdurl": "^1"
@@ -2729,6 +2737,7 @@
       "dev": true,
       "license": "MIT",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "@types/node": "*"
       }
@@ -2775,7 +2784,6 @@
       "integrity": "sha512-tbsV1jPne5CkFQCgPBcDOt30ItF7aJoZL997JSF7MhGQqOeT3svWRYxiqlfA5RUdlHN6Fi+EI9bxqbdyAUZjYQ==",
       "dev": true,
       "license": "BSD-2-Clause",
-      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "6.21.0",
         "@typescript-eslint/types": "6.21.0",
@@ -3150,7 +3158,6 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -3329,6 +3336,7 @@
       "integrity": "sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "tslib": "^2.0.1"
       },
@@ -3352,6 +3360,7 @@
       "integrity": "sha512-5Q2mfq2WfGuFp3uS//0s6baOJLMoVduPYVeNmDYxu5OUA1/cBfvr2RIS7vi62LdNj/urk1hfmj867I3qt6uZ7Q==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "peerDependencies": {
         "react-native-b4a": "*"
       },
@@ -3374,6 +3383,7 @@
       "integrity": "sha512-riJjyv1/mHLIPX4RwiK+oW9/4c3TEUeORHKefKAKnZ5kyslbN+HXowtbaVEqt4IMUB7OXlfixcs6gsFeo/jhiQ==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "peerDependencies": {
         "bare-abort-controller": "*"
       },
@@ -3390,6 +3400,7 @@
       "dev": true,
       "license": "Apache-2.0",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "bare-events": "^2.5.4",
         "bare-path": "^3.0.0",
@@ -3416,6 +3427,7 @@
       "dev": true,
       "license": "Apache-2.0",
       "optional": true,
+      "peer": true,
       "engines": {
         "bare": ">=1.14.0"
       }
@@ -3427,6 +3439,7 @@
       "dev": true,
       "license": "Apache-2.0",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "bare-os": "^3.0.1"
       }
@@ -3438,6 +3451,7 @@
       "dev": true,
       "license": "Apache-2.0",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "streamx": "^2.21.0"
       },
@@ -3461,6 +3475,7 @@
       "dev": true,
       "license": "Apache-2.0",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "bare-path": "^3.0.0"
       }
@@ -3492,6 +3507,7 @@
       "integrity": "sha512-4Bcg1P8xhUuqcii/S0Z9wiHIrQVPMermM1any+MX5GeGD7faD3/msQUDGLol9wOcz4/jbg/WJnGqoJF6LiBdtg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=10.0.0"
       }
@@ -3575,6 +3591,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "base64-js": "^1.3.1",
         "ieee754": "^1.1.13"
@@ -3586,6 +3603,7 @@
       "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": "*"
       }
@@ -3687,7 +3705,6 @@
       "integrity": "sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "@chevrotain/cst-dts-gen": "11.0.3",
         "@chevrotain/gast": "11.0.3",
@@ -3754,6 +3771,7 @@
       "integrity": "sha512-6CJWHkNRoyZyjV9Rwv2lYONZf1Xm0IuDyNq97nwSsxxP3wf5Bwy15K5rOvVKMtJ127jJBmxFUanSAOjgFRxgrA==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "mitt": "3.0.1",
         "zod": "3.23.8"
@@ -3860,6 +3878,7 @@
       "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
       "dev": true,
       "license": "ISC",
+      "peer": true,
       "dependencies": {
         "string-width": "^4.2.0",
         "strip-ansi": "^6.0.1",
@@ -3982,6 +4001,7 @@
       "integrity": "sha512-itvL5h8RETACmOTFc4UfIyB2RfEHi71Ax6E/PivVxq9NseKbOWpeyHEOIbmAw1rs8Ak0VursQNww7lf7YtUwzg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "env-paths": "^2.2.1",
         "import-fresh": "^3.3.0",
@@ -4096,7 +4116,6 @@
       "integrity": "sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10"
       }
@@ -4531,7 +4550,6 @@
       "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
       "dev": true,
       "license": "ISC",
-      "peer": true,
       "engines": {
         "node": ">=12"
       }
@@ -4639,6 +4657,7 @@
       "integrity": "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">= 14"
       }
@@ -4702,6 +4721,7 @@
       "integrity": "sha512-TllpMR/t0M5sqCXfj85i4XaAzxmS5tVA16dqvdkMwGmzI+dXLXnw3J+3Vdv7VKw+ThlTMboK6i9rnZ6Nntj5CQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "ast-types": "^0.13.4",
         "escodegen": "^2.1.0",
@@ -4852,7 +4872,8 @@
       "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
       "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/encoding-sniffer": {
       "version": "0.2.1",
@@ -4874,6 +4895,7 @@
       "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "once": "^1.4.0"
       }
@@ -4896,6 +4918,7 @@
       "integrity": "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=6"
       }
@@ -4919,6 +4942,7 @@
       "integrity": "sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "is-arrayish": "^0.2.1"
       }
@@ -5029,6 +5053,7 @@
       "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=6"
       }
@@ -5052,6 +5077,7 @@
       "integrity": "sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w==",
       "dev": true,
       "license": "BSD-2-Clause",
+      "peer": true,
       "dependencies": {
         "esprima": "^4.0.1",
         "estraverse": "^5.2.0",
@@ -5075,7 +5101,6 @@
       "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.6.1",
@@ -5204,6 +5229,7 @@
       "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
       "dev": true,
       "license": "BSD-2-Clause",
+      "peer": true,
       "bin": {
         "esparse": "bin/esparse.js",
         "esvalidate": "bin/esvalidate.js"
@@ -5298,6 +5324,7 @@
       "integrity": "sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "bare-events": "^2.7.0"
       }
@@ -5318,6 +5345,7 @@
       "integrity": "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg==",
       "dev": true,
       "license": "BSD-2-Clause",
+      "peer": true,
       "dependencies": {
         "debug": "^4.1.1",
         "get-stream": "^5.1.0",
@@ -5345,7 +5373,8 @@
       "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz",
       "integrity": "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/fast-glob": {
       "version": "3.3.3",
@@ -5417,6 +5446,7 @@
       "integrity": "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "pend": "~1.2.0"
       }
@@ -5539,6 +5569,7 @@
       "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
       "dev": true,
       "license": "ISC",
+      "peer": true,
       "engines": {
         "node": "6.* || 8.* || >= 10.*"
       }
@@ -5562,6 +5593,7 @@
       "integrity": "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "pump": "^3.0.0"
       },
@@ -5591,6 +5623,7 @@
       "integrity": "sha512-b1O07XYq8eRuVzBNgJLstU6FYc1tS6wnMtF1I1D9lE8LxZSOGZ7LhxN54yPP6mGw5f2CkXY2BQUL9Fx41qvcIg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "basic-ftp": "^5.0.2",
         "data-uri-to-buffer": "^6.0.2",
@@ -5989,6 +6022,7 @@
       "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">= 12"
       }
@@ -5998,7 +6032,8 @@
       "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz",
       "integrity": "sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/is-binary-path": {
       "version": "2.1.0",
@@ -6045,6 +6080,7 @@
       "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=8"
       }
@@ -6108,7 +6144,6 @@
       "integrity": "sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "jiti": "bin/jiti.js"
       }
@@ -6148,7 +6183,8 @@
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
       "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/js-yaml": {
       "version": "4.1.1",
@@ -6254,7 +6290,8 @@
       "resolved": "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz",
       "integrity": "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/json-schema-traverse": {
       "version": "0.4.1",
@@ -6700,6 +6737,7 @@
       "integrity": "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==",
       "dev": true,
       "license": "ISC",
+      "peer": true,
       "engines": {
         "node": ">=12"
       }
@@ -6719,7 +6757,6 @@
       "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz",
       "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "argparse": "^2.0.1",
         "entities": "^4.4.0",
@@ -6814,7 +6851,6 @@
       "integrity": "sha512-UlIZrRariB11TY1RtTgUWp65tphtBv4CSq7vyS2ZZ2TgoMjs2nloq+wFqxiwcxlhHUvs7DPGgMjs2aeQxz5h9g==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@braintree/sanitize-url": "^7.1.1",
         "@iconify/utils": "^3.0.1",
@@ -6892,7 +6928,8 @@
       "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz",
       "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/mlly": {
       "version": "1.8.0",
@@ -6971,6 +7008,7 @@
       "integrity": "sha512-dBpDMdxv9Irdq66304OLfEmQ9tbNRFnFTuZiLo+bD+r332bBmMJ8GBLXklIXXgxd3+v9+KUnZaUR5PJMa75Gsg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">= 0.4.0"
       }
@@ -7111,6 +7149,7 @@
       "integrity": "sha512-TEB8ESquiLMc0lV8vcd5Ql/JAKAoyzHFXaStwjkzpOpC5Yv+pIzLfHvjTSdf3vpa2bMiUQrg9i6276yn8666aA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@tootallnate/quickjs-emscripten": "^0.23.0",
         "agent-base": "^7.1.2",
@@ -7131,6 +7170,7 @@
       "integrity": "sha512-5NPgf87AT2STgwa2ntRMr45jTKrYBGkVU36yT0ig/n/GMAa3oPqhZfIQ2kMEimReg0+t9kZViDVZ83qfVUlckg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "degenerator": "^5.0.0",
         "netmask": "^2.0.2"
@@ -7182,6 +7222,7 @@
       "integrity": "sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.0.0",
         "error-ex": "^1.3.1",
@@ -7314,7 +7355,8 @@
       "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz",
       "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/picocolors": {
       "version": "1.1.1",
@@ -7565,7 +7607,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -7764,6 +7805,7 @@
       "integrity": "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=0.4.0"
       }
@@ -7774,6 +7816,7 @@
       "integrity": "sha512-TmatMXdr2KlRiA2CyDu8GqR8EjahTG3aY3nXjdzFyoZbmB8hrBsTyMezhULIXKnC0jpfjlmiZ3+EaCzoInSu/A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "agent-base": "^7.1.2",
         "debug": "^4.3.4",
@@ -7793,7 +7836,8 @@
       "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz",
       "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/pump": {
       "version": "3.0.3",
@@ -7801,6 +7845,7 @@
       "integrity": "sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "end-of-stream": "^1.1.0",
         "once": "^1.3.1"
@@ -7855,6 +7900,7 @@
       "integrity": "sha512-3HZ2/7hdDKZvZQ7dhhITOUg4/wOrDRjyK2ZBllRB0ZCOi9u0cwq1ACHDjBB+nX+7+kltHjQvBRdeY7+W0T+7Gg==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "@puppeteer/browsers": "2.6.1",
         "chromium-bidi": "0.11.0",
@@ -7922,7 +7968,6 @@
       "integrity": "sha512-DGrYcCWK7tvYMnWh79yrPHt+vdx9tY+1gPZa7nJQtO/p8bLTDaHp4dzwEhQB7pZ4Xe3ok4XKuEPrVuc+wlpkmw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -7933,7 +7978,6 @@
       "integrity": "sha512-ibrK8llX2a4eOskq1mXKu/TGZj9qzomO+sNfO98M6d9zIPOEhlBkMkBUBLd1vgS0gQsLDBzA+8jJBVXDnfHmJg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },
@@ -8005,6 +8049,7 @@
       "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -8423,6 +8468,7 @@
       "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">= 6.0.0",
         "npm": ">= 3.0.0"
@@ -8434,6 +8480,7 @@
       "integrity": "sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "ip-address": "^10.0.1",
         "smart-buffer": "^4.2.0"
@@ -8449,6 +8496,7 @@
       "integrity": "sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "agent-base": "^7.1.2",
         "debug": "^4.3.4",
@@ -8475,6 +8523,7 @@
       "dev": true,
       "license": "BSD-3-Clause",
       "optional": true,
+      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -8519,6 +8568,7 @@
       "integrity": "sha512-kn+e44esVfn2Fa/O0CPFcex27fjIL6MkVae0Mm6q+E6f0hWv578YCERbv+4m02cjxvDsPKLnmxral/rR6lBMAg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "events-universal": "^1.0.0",
         "fast-fifo": "^1.3.2",
@@ -8550,6 +8600,7 @@
       "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "emoji-regex": "^8.0.0",
         "is-fullwidth-code-point": "^3.0.0",
@@ -8682,7 +8733,6 @@
       "integrity": "sha512-6A2rnmW5xZMdw11LYjhcI5846rt9pbLSabY5XPxo+XWdxwZaFEn47Go4NzFiHu9sNNmr/kXivP1vStfvMaK1GQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@alloc/quick-lru": "^5.2.0",
         "arg": "^5.0.2",
@@ -8721,6 +8771,7 @@
       "integrity": "sha512-LZA0oaPOc2fVo82Txf3gw+AkEd38szODlptMYejQUhndHMLQ9M059uXR+AfS7DNo0NpINvSqDsvyaCrBVkptWg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "pump": "^3.0.0",
         "tar-stream": "^3.1.5"
@@ -8736,6 +8787,7 @@
       "integrity": "sha512-qJj60CXt7IU1Ffyc3NJMjh6EkuCFej46zUqJ4J7pqYlThyd9bO0XBTmcOIhSzZJVWfsLks0+nle/j538YAW9RQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "b4a": "^1.6.4",
         "fast-fifo": "^1.2.0",
@@ -8748,6 +8800,7 @@
       "integrity": "sha512-3/o9z3X0X0fTupwsYvR03pJ/DjWuqqrfwBgTQzdWDiQSm9KitAyz/9WqsT2JQW7KV2m+bC2ol/zqpW37NHxLaA==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "b4a": "^1.6.4"
       }
@@ -8797,7 +8850,8 @@
       "resolved": "https://registry.npmjs.org/through/-/through-2.3.8.tgz",
       "integrity": "sha512-w89qg7PI8wAdvX60bMDP+bFoD5Dvhm9oLheFp5O4a2QF0cSBGsBX4qZmadPMvVqlLJBBci+WqGGOAPvcDeNSVg==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/tinybench": {
       "version": "2.9.0",
@@ -8857,7 +8911,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -8977,7 +9030,6 @@
       "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "~0.27.0",
         "get-tsconfig": "^4.7.5"
@@ -9471,7 +9523,8 @@
       "resolved": "https://registry.npmjs.org/typed-query-selector/-/typed-query-selector-2.12.0.tgz",
       "integrity": "sha512-SbklCd1F0EiZOyPiW192rrHZzZ5sBijB6xM+cpmrwDqObvdtunOHHIk9fCGsoK5JVIYXoyEp4iEdE3upFH3PAg==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/typescript": {
       "version": "5.9.3",
@@ -9479,7 +9532,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -9507,6 +9559,7 @@
       "integrity": "sha512-mlExGW4w71ebDJviH16lQLtZS32VKqsSfk80GCfUlwT/4/hNRFsoscrF/c++9xinkMzECL1uL9DDwXqFWkruPg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "buffer": "^5.2.1",
         "through": "^2.3.8"
@@ -9585,7 +9638,6 @@
       "integrity": "sha512-tI2l/nFHC5rLh7+5+o7QjKjSR04ivXDF4jcgV0f/bTQ+OJiITy5S6gaynVsEM+7RqzufMnVbIon6Sr5x1SDYaQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.25.0",
         "fdir": "^6.5.0",
@@ -9694,7 +9746,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -10012,6 +10063,7 @@
       "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "ansi-styles": "^4.0.0",
         "string-width": "^4.1.0",
@@ -10094,6 +10146,7 @@
       "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
       "dev": true,
       "license": "ISC",
+      "peer": true,
       "engines": {
         "node": ">=10"
       }
@@ -10104,7 +10157,6 @@
       "integrity": "sha512-lcYcMxX2PO9XMGvAJkJ3OsNMw+/7FKes7/hgerGUYWIoWu5j/+YQqcZr5JnPZWzOsEBgMbSbiSTn/dv/69Mkpw==",
       "dev": true,
       "license": "ISC",
-      "peer": true,
       "bin": {
         "yaml": "bin.mjs"
       },
@@ -10118,6 +10170,7 @@
       "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "cliui": "^8.0.1",
         "escalade": "^3.1.1",
@@ -10137,6 +10190,7 @@
       "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
       "dev": true,
       "license": "ISC",
+      "peer": true,
       "engines": {
         "node": ">=12"
       }
@@ -10147,6 +10201,7 @@
       "integrity": "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "buffer-crc32": "~0.2.3",
         "fd-slicer": "~1.1.0"
@@ -10171,9 +10226,15 @@
       "integrity": "sha512-XBx9AXhXktjUqnepgTiE5flcKIYWi/rme0Eaj+5Y0lftuGBq+jyRu/md4WnuxqgP1ubdpNCsYEYPxrzVHD8d6g==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }
+    },
+    "packages/core": {
+      "name": "@mdview/core",
+      "version": "0.0.1",
+      "license": "MIT"
     }
   }
 }
diff --git a/package.json b/package.json
index 8371654..7305cda 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,9 @@
   "version": "0.3.4",
   "description": "Beautiful Chrome extension for viewing Markdown files with themes, syntax highlighting, and interactive Mermaid diagrams",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "scripts": {
     "dev": "vite build --watch",
     "build": "node scripts/update-manifest-version.js && tsc && vite build && node scripts/fix-manifest.js",
diff --git a/packages/core/package.json b/packages/core/package.json
new file mode 100644
index 0000000..8f21f63
--- /dev/null
+++ b/packages/core/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "@mdview/core",
+  "version": "0.0.1",
+  "description": "Core rendering engine for mdview",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:ci": "vitest --run"
+  },
+  "author": "James Ainslie",
+  "license": "MIT"
+}
diff --git a/packages/core/src/__tests__/smoke.test.ts b/packages/core/src/__tests__/smoke.test.ts
new file mode 100644
index 0000000..41f6435
--- /dev/null
+++ b/packages/core/src/__tests__/smoke.test.ts
@@ -0,0 +1,7 @@
+import { VERSION } from '../index';
+
+describe('@mdview/core', () => {
+  it('should export VERSION', () => {
+    expect(VERSION).toBe('0.0.1');
+  });
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
new file mode 100644
index 0000000..1da5182
--- /dev/null
+++ b/packages/core/src/index.ts
@@ -0,0 +1,3 @@
+// @mdview/core - shared rendering engine
+// Modules will be exported here as they are extracted from the Chrome extension.
+export const VERSION = '0.0.1';
diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json
new file mode 100644
index 0000000..06014a2
--- /dev/null
+++ b/packages/core/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "baseUrl": ".",
+    "paths": {},
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/core/vitest.config.ts b/packages/core/vitest.config.ts
new file mode 100644
index 0000000..c30a1fe
--- /dev/null
+++ b/packages/core/vitest.config.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    testTimeout: 10000,
+  },
+});

From e299cdee14fc9ee147acf6719311aac95a4c0c80 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:10:36 -0400
Subject: [PATCH 03/26] chore: configure vitest workspace for monorepo

---
 vitest.workspace.ts | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 vitest.workspace.ts

diff --git a/vitest.workspace.ts b/vitest.workspace.ts
new file mode 100644
index 0000000..ee916e3
--- /dev/null
+++ b/vitest.workspace.ts
@@ -0,0 +1,19 @@
+import { defineWorkspace } from 'vitest/config';
+
+export default defineWorkspace([
+  {
+    extends: './vitest.config.ts',
+    test: {
+      name: 'chrome-ext',
+      include: ['tests/**/*.test.ts'],
+    },
+  },
+  {
+    extends: './packages/core/vitest.config.ts',
+    test: {
+      name: 'core',
+      root: './packages/core',
+      include: ['src/**/*.test.ts'],
+    },
+  },
+]);

From 31fe07e3c9645018e71262c5ae0623b9bcd693b3 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:14:36 -0400
Subject: [PATCH 04/26] refactor(core): move type definitions to @mdview/core

---
 packages/core/src/__tests__/types.test.ts     | 140 +++++
 packages/core/src/types/index.d.ts            | 584 +++++++++++++++++
 .../core/src/types/markdown-it-plugins.d.ts   |  29 +
 src/types/index.d.ts                          | 587 +-----------------
 4 files changed, 756 insertions(+), 584 deletions(-)
 create mode 100644 packages/core/src/__tests__/types.test.ts
 create mode 100644 packages/core/src/types/index.d.ts
 create mode 100644 packages/core/src/types/markdown-it-plugins.d.ts

diff --git a/packages/core/src/__tests__/types.test.ts b/packages/core/src/__tests__/types.test.ts
new file mode 100644
index 0000000..907d131
--- /dev/null
+++ b/packages/core/src/__tests__/types.test.ts
@@ -0,0 +1,140 @@
+import type {
+  Theme,
+  ThemeName,
+  AppState,
+  ConversionResult,
+  Comment,
+  CommentParseResult,
+  ExportFormat,
+  PaperSize,
+  ContentNode,
+  CachedResult,
+  WorkerTask,
+} from '../types/index';
+
+describe('@mdview/core types', () => {
+  it('should allow creating a Theme object', () => {
+    const theme: Theme = {
+      name: 'github-light',
+      displayName: 'GitHub Light',
+      variant: 'light',
+      author: 'test',
+      version: '1.0.0',
+      colors: {
+        background: '#fff',
+        backgroundSecondary: '#f6f8fa',
+        backgroundTertiary: '#eee',
+        foreground: '#24292e',
+        foregroundSecondary: '#586069',
+        foregroundMuted: '#6a737d',
+        primary: '#0366d6',
+        secondary: '#6f42c1',
+        accent: '#e36209',
+        heading: '#24292e',
+        link: '#0366d6',
+        linkHover: '#0366d6',
+        linkVisited: '#6f42c1',
+        codeBackground: '#f6f8fa',
+        codeText: '#24292e',
+        codeKeyword: '#d73a49',
+        codeString: '#032f62',
+        codeComment: '#6a737d',
+        codeFunction: '#6f42c1',
+        border: '#e1e4e8',
+        borderLight: '#eaecef',
+        borderHeavy: '#d1d5da',
+        selection: '#0366d633',
+        highlight: '#fff3cd',
+        shadow: 'rgba(27,31,35,0.15)',
+        success: '#28a745',
+        warning: '#ffd33d',
+        error: '#d73a49',
+        info: '#0366d6',
+        commentHighlight: '#fff3cd',
+        commentHighlightResolved: '#dcffe4',
+        commentCardBg: '#ffffff',
+      },
+      typography: {
+        fontFamily: 'system-ui',
+        codeFontFamily: 'monospace',
+        baseFontSize: '16px',
+        baseLineHeight: 1.6,
+        h1Size: '2em',
+        h2Size: '1.5em',
+        h3Size: '1.25em',
+        h4Size: '1em',
+        h5Size: '0.875em',
+        h6Size: '0.85em',
+        fontWeightNormal: 400,
+        fontWeightBold: 600,
+        headingFontWeight: 600,
+      },
+      spacing: {
+        blockMargin: '16px',
+        paragraphMargin: '16px',
+        listItemMargin: '4px',
+        headingMargin: '24px',
+        codeBlockPadding: '16px',
+        tableCellPadding: '6px 13px',
+      },
+      syntaxTheme: 'github',
+      mermaidTheme: {
+        theme: 'default',
+        themeVariables: {
+          primaryColor: '#0366d6',
+          primaryTextColor: '#24292e',
+          primaryBorderColor: '#e1e4e8',
+          lineColor: '#586069',
+          secondaryColor: '#6f42c1',
+          tertiaryColor: '#e36209',
+          background: '#fff',
+          mainBkg: '#fff',
+        },
+      },
+    };
+    expect(theme.name).toBe('github-light');
+    expect(theme.variant).toBe('light');
+  });
+
+  it('should allow ThemeName literals', () => {
+    const names: ThemeName[] = [
+      'github-light',
+      'github-dark',
+      'catppuccin-latte',
+      'catppuccin-frappe',
+      'catppuccin-macchiato',
+      'catppuccin-mocha',
+      'monokai',
+      'monokai-pro',
+    ];
+    expect(names).toHaveLength(8);
+  });
+
+  it('should allow ExportFormat and PaperSize types', () => {
+    const format: ExportFormat = 'docx';
+    const size: PaperSize = 'A4';
+    expect(format).toBe('docx');
+    expect(size).toBe('A4');
+  });
+
+  it('should allow Comment type with all fields', () => {
+    const comment: Comment = {
+      id: 'comment-1',
+      selectedText: 'test',
+      body: 'a comment',
+      author: 'tester',
+      date: new Date().toISOString(),
+      resolved: false,
+      context: {
+        line: 1,
+        section: 'Introduction',
+        sectionLevel: 1,
+        breadcrumb: ['Introduction'],
+      },
+      tags: ['nit', 'suggestion'],
+      replies: [{ id: 'reply-1', author: 'reviewer', body: 'agreed', date: new Date().toISOString() }],
+      reactions: { '👍': ['tester'] },
+    };
+    expect(comment.id).toBe('comment-1');
+  });
+});
diff --git a/packages/core/src/types/index.d.ts b/packages/core/src/types/index.d.ts
new file mode 100644
index 0000000..1dce0fd
--- /dev/null
+++ b/packages/core/src/types/index.d.ts
@@ -0,0 +1,584 @@
+// Type definitions for MDView
+
+/**
+ * Global window extensions
+ */
+declare global {
+  const __APP_VERSION__: string;
+
+  interface Window {
+    __MDVIEW_MERMAID_CODE__?: Map<string, string>;
+  }
+}
+
+export type ThemeName =
+  | 'github-light'
+  | 'github-dark'
+  | 'catppuccin-latte'
+  | 'catppuccin-frappe'
+  | 'catppuccin-macchiato'
+  | 'catppuccin-mocha'
+  | 'monokai'
+  | 'monokai-pro'
+  | 'test-theme'; // For testing
+
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+
+export interface AppState {
+  preferences: {
+    theme: ThemeName;
+    autoTheme: boolean;
+    lightTheme: ThemeName;
+    darkTheme: ThemeName;
+    syntaxTheme: string;
+    autoReload: boolean;
+    lineNumbers: boolean;
+    enableHtml: boolean; // Enable HTML rendering in markdown
+    syncTabs: boolean;
+    logLevel: LogLevel;
+    debug?: boolean; // Deprecated
+    // Editor / Appearance Overrides
+    fontFamily?: string;
+    codeFontFamily?: string;
+    lineHeight?: number;
+    maxWidth?: number;
+    useMaxWidth?: boolean; // Toggle for full width
+    // Table of Contents
+    showToc?: boolean; // Enable/disable TOC
+    tocMaxDepth?: number; // Max heading depth (1-6)
+    tocAutoCollapse?: boolean; // Auto-collapse nested sections
+    tocPosition?: 'left' | 'right'; // Position of TOC
+    tocStyle?: 'floating' | 'fixed'; // Style of TOC (floating card or fixed sidebar)
+    // Comments
+    commentsEnabled?: boolean; // Enable/disable comments feature
+    commentAuthor?: string; // Author name for new comments
+    // Export settings
+    exportDefaultFormat?: 'docx' | 'pdf';
+    exportDefaultPageSize?: PaperSize;
+    exportIncludeToc?: boolean;
+    exportFilenameTemplate?: string; // e.g., "{title}-{date}"
+    // Site blocklist - URLs/patterns where MDView should not render
+    blockedSites?: string[]; // e.g., ["github.com", "*.gitlab.com/*/blob/*"]
+  };
+  document: {
+    path: string;
+    content: string;
+    scrollPosition: number;
+    renderState: 'pending' | 'rendering' | 'complete' | 'error';
+  };
+  ui: {
+    theme: Theme | null;
+    maximizedDiagram: string | null;
+    visibleDiagrams: Set<string>;
+    tocVisible?: boolean; // Current TOC visibility state
+  };
+}
+
+export interface Theme {
+  name: ThemeName;
+  displayName: string;
+  variant: 'light' | 'dark';
+  author: string;
+  version: string;
+  colors: ThemeColors;
+  typography: ThemeTypography;
+  spacing: ThemeSpacing;
+  syntaxTheme: string;
+  mermaidTheme: MermaidThemeConfig;
+}
+
+export interface ThemeColors {
+  background: string;
+  backgroundSecondary: string;
+  backgroundTertiary: string;
+  foreground: string;
+  foregroundSecondary: string;
+  foregroundMuted: string;
+  primary: string;
+  secondary: string;
+  accent: string;
+  heading: string;
+  link: string;
+  linkHover: string;
+  linkVisited: string;
+  codeBackground: string;
+  codeText: string;
+  codeKeyword: string;
+  codeString: string;
+  codeComment: string;
+  codeFunction: string;
+  border: string;
+  borderLight: string;
+  borderHeavy: string;
+  selection: string;
+  highlight: string;
+  shadow: string;
+  success: string;
+  warning: string;
+  error: string;
+  info: string;
+  // Comment highlighting
+  commentHighlight: string;
+  commentHighlightResolved: string;
+  commentCardBg: string;
+}
+
+export interface ThemeTypography {
+  fontFamily: string;
+  headingFontFamily?: string;
+  codeFontFamily: string;
+  baseFontSize: string;
+  baseLineHeight: number;
+  h1Size: string;
+  h2Size: string;
+  h3Size: string;
+  h4Size: string;
+  h5Size: string;
+  h6Size: string;
+  fontWeightNormal: number;
+  fontWeightBold: number;
+  headingFontWeight: number;
+}
+
+export interface ThemeSpacing {
+  blockMargin: string;
+  paragraphMargin: string;
+  listItemMargin: string;
+  headingMargin: string;
+  codeBlockPadding: string;
+  tableCellPadding: string;
+}
+
+export interface MermaidThemeConfig {
+  theme: 'base' | 'dark' | 'default' | 'forest' | 'neutral';
+  themeVariables: {
+    primaryColor: string;
+    primaryTextColor: string;
+    primaryBorderColor: string;
+    lineColor: string;
+    secondaryColor: string;
+    tertiaryColor: string;
+    background: string;
+    mainBkg: string;
+    [key: string]: string;
+  };
+}
+
+export interface ConversionResult {
+  html: string;
+  metadata: {
+    wordCount: number;
+    headings: HeadingInfo[];
+    codeBlocks: CodeBlockInfo[];
+    mermaidBlocks: MermaidBlockInfo[];
+    images: ImageInfo[];
+    links: LinkInfo[];
+    frontmatter: Record<string, string> | null;
+  };
+  errors: ParseError[];
+}
+
+export interface HeadingInfo {
+  level: number;
+  text: string;
+  id: string;
+  line: number;
+}
+
+export interface CodeBlockInfo {
+  language: string;
+  code: string;
+  line: number;
+  lines: number;
+}
+
+export interface MermaidBlockInfo {
+  code: string;
+  line: number;
+}
+
+export interface ImageInfo {
+  src: string;
+  alt: string;
+  title?: string;
+  line: number;
+}
+
+export interface LinkInfo {
+  href: string;
+  text: string;
+  line: number;
+}
+
+export interface ParseError {
+  message: string;
+  line: number;
+  column: number;
+  severity: 'error' | 'warning';
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ParseError[];
+  warnings: ParseError[];
+}
+
+// Cache types
+export interface CachedResult {
+  html: string;
+  metadata: ConversionResult['metadata'];
+  highlightedBlocks: Map<string, string>;
+  mermaidSVGs: Map<string, string>;
+  timestamp: number;
+  cacheKey: string;
+}
+
+export interface CacheEntry {
+  result: CachedResult;
+  filePath: string;
+  contentHash: string;
+  theme: ThemeName;
+  lastAccessed: number;
+}
+
+// Worker types
+export type WorkerTaskType = 'parse' | 'highlight' | 'mermaid';
+
+export interface WorkerTask {
+  type: WorkerTaskType;
+  id: string;
+  payload: unknown;
+  priority?: number;
+}
+
+// Message types for communication between content script and service worker
+export type MessageType =
+  | 'GET_STATE'
+  | 'UPDATE_PREFERENCES'
+  | 'APPLY_THEME'
+  | 'CACHE_GENERATE_KEY'
+  | 'CACHE_GET'
+  | 'CACHE_SET'
+  | 'CACHE_INVALIDATE'
+  | 'CACHE_INVALIDATE_BY_PATH'
+  | 'CACHE_STATS'
+  | 'REPORT_ERROR'
+  | 'CHECK_FILE_CHANGED' // New message type
+  | 'PREFERENCES_UPDATED'
+  | 'RELOAD_CONTENT';
+
+export interface WorkerResponse {
+  id: string;
+  result?: unknown;
+  error?: string;
+}
+
+export interface ParseTaskPayload {
+  markdown: string;
+  options?: {
+    breaks?: boolean;
+    linkify?: boolean;
+    typographer?: boolean;
+    enableHtml?: boolean;
+  };
+}
+
+export interface ParseTaskResult {
+  html: string;
+  metadata: ConversionResult['metadata'];
+}
+
+export interface HighlightTaskPayload {
+  code: string;
+  language: string;
+}
+
+export interface HighlightTaskResult {
+  html: string;
+  language: string;
+}
+
+export interface MermaidTaskPayload {
+  code: string;
+  theme?: MermaidThemeConfig;
+  id: string;
+}
+
+export interface MermaidTaskResult {
+  svg: string;
+  id: string;
+}
+
+// Export feature types
+
+/**
+ * Supported export formats
+ */
+export type ExportFormat = 'docx' | 'pdf';
+
+/**
+ * Standard paper sizes for PDF export
+ * ISO A-series: A0, A1, A3, A4, A5, A6
+ * North American: Letter, Legal, Tabloid, Executive
+ */
+export type PaperSize =
+  | 'A0'
+  | 'A1'
+  | 'A3'
+  | 'A4'
+  | 'A5'
+  | 'A6'
+  | 'Letter'
+  | 'Legal'
+  | 'Tabloid'
+  | 'Executive';
+
+/**
+ * Content node types for export
+ */
+export type ContentNodeType =
+  | 'heading'
+  | 'paragraph'
+  | 'list'
+  | 'code'
+  | 'table'
+  | 'image'
+  | 'mermaid'
+  | 'blockquote'
+  | 'hr';
+
+/**
+ * Structured content node for export
+ */
+export interface ContentNode {
+  type: ContentNodeType;
+  content: string | ContentNode[];
+  attributes: {
+    level?: number; // For headings (1-6)
+    language?: string; // For code blocks
+    ordered?: boolean; // For lists
+    id?: string; // For headings, images, mermaid
+    src?: string; // For images
+    alt?: string; // For images
+    [key: string]: unknown;
+  };
+  children?: ContentNode[];
+}
+
+/**
+ * Collected content from rendered markdown
+ */
+export interface CollectedContent {
+  title: string;
+  nodes: ContentNode[];
+  metadata: {
+    wordCount: number;
+    imageCount: number;
+    mermaidCount: number;
+    exportedAt: Date;
+  };
+}
+
+/**
+ * SVG conversion options
+ */
+export interface SVGConversionOptions {
+  scale?: number; // Default: 2 (retina) - only used for raster formats
+  format?: 'png' | 'jpeg' | 'svg'; // 'svg' preserves vector format
+  quality?: number; // JPEG quality 0-1
+  backgroundColor?: string;
+}
+
+/**
+ * Converted image data
+ */
+export interface ConvertedImage {
+  id: string;
+  data: string; // base64 encoded
+  width: number;
+  height: number;
+  format: string;
+}
+
+/**
+ * Export options
+ */
+export interface ExportOptions {
+  format: ExportFormat;
+  filename?: string;
+  includeImages?: boolean;
+  includeMermaid?: boolean;
+}
+
+/**
+ * Export progress information
+ */
+export interface ExportProgress {
+  stage: 'collecting' | 'converting' | 'generating' | 'downloading';
+  progress: number; // 0-100
+  message: string;
+}
+
+/**
+ * Progress callback function
+ */
+export type ProgressCallback = (progress: ExportProgress) => void;
+
+/**
+ * DOCX Generator options
+ */
+export interface DOCXGeneratorOptions {
+  title?: string;
+  author?: string;
+  includeTableOfContents?: boolean;
+  pageSize?: PaperSize;
+  margins?: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+  };
+}
+
+/**
+ * Export UI Options
+ */
+export interface ExportUIOptions {
+  position?: 'left' | 'right';
+  formats?: ExportFormat[];
+  defaultPageSize?: PaperSize;
+  defaultFormat?: ExportFormat;
+  includeTableOfContents?: boolean;
+  filenameTemplate?: string;
+}
+
+/**
+ * Export UI State
+ */
+export interface ExportUIState {
+  isMenuOpen: boolean;
+  isExporting: boolean;
+  currentProgress: ExportProgress | null;
+  lastError: Error | null;
+}
+
+/**
+ * PDF Generator options
+ */
+export interface PDFGeneratorOptions {
+  paperSize?: PaperSize;
+  orientation?: 'portrait' | 'landscape';
+  margins?: string; // CSS margin value
+  convertSvgsToImages?: boolean;
+  pageBreakBeforeHeadings?: boolean;
+}
+
+/**
+ * Filename template variables
+ */
+export type FilenameTemplateVar =
+  | '{title}' // Document title
+  | '{date}' // YYYY-MM-DD
+  | '{datetime}' // YYYY-MM-DD_HH-mm
+  | '{timestamp}' // Unix timestamp
+  | '{year}' // YYYY
+  | '{month}' // MM
+  | '{day}'; // DD
+
+// Comment feature types
+
+/**
+ * A reply within a comment thread
+ */
+export interface CommentReply {
+  id: string;        // "reply-1", "reply-2", scoped within parent
+  author: string;
+  body: string;
+  date: string;      // ISO 8601
+}
+
+/**
+ * Emoji reactions on a comment: emoji char → author names
+ */
+export type CommentReactions = Record<string, string[]>;
+
+/**
+ * Tag that can be applied to a comment to signal severity/intent.
+ */
+export type CommentTag =
+  | 'blocking'
+  | 'nit'
+  | 'suggestion'
+  | 'question'
+  | 'praise'
+  | 'todo'
+  | 'fyi';
+
+/**
+ * Positional context for a comment within the document structure.
+ * Computed at comment-creation time from the source offset and document headings.
+ * Stored in the footnote metadata so AI agents can read it directly from the file.
+ */
+export interface CommentContext {
+  /** 1-based line number where the commented text appears */
+  line: number;
+  /** Nearest heading text above the comment (undefined if before any heading) */
+  section?: string;
+  /** Heading level of the nearest heading (1-6, undefined if before any heading) */
+  sectionLevel?: number;
+  /** Heading hierarchy from root to the containing section */
+  breadcrumb: string[];
+}
+
+/**
+ * A single comment attached to text in the markdown
+ */
+export interface Comment {
+  id: string; // e.g. "comment-1"
+  selectedText: string; // The text the comment is anchored to
+  body: string; // The comment content
+  author: string; // From extension settings
+  date: string; // ISO 8601 timestamp
+  resolved: boolean; // Whether the comment has been resolved
+  /** Positional context within the document; undefined for legacy comments */
+  context?: CommentContext;
+  /** Tags for categorizing comment severity/intent */
+  tags?: CommentTag[];
+  /** Threaded replies */
+  replies?: CommentReply[];
+  /** Emoji reactions */
+  reactions?: CommentReactions;
+  /** Prefix context for TextQuoteSelector anchoring */
+  anchorPrefix?: string;
+  /** Suffix context for TextQuoteSelector anchoring */
+  anchorSuffix?: string;
+}
+
+/**
+ * Result of parsing comments from raw markdown
+ */
+export interface CommentParseResult {
+  cleanedMarkdown: string; // Markdown with comment footnotes stripped
+  comments: Comment[]; // Extracted comments
+}
+
+/**
+ * Comment metadata stored in the footnote HTML comment
+ */
+export interface CommentMetadata {
+  author: string;
+  date: string;
+  resolved?: boolean;
+  selectedText?: string;
+  // Positional context fields (optional for backward compatibility)
+  line?: number;
+  section?: string;
+  sectionLevel?: number;
+  breadcrumb?: string[];
+  /** Tags for categorizing comment severity/intent */
+  tags?: CommentTag[];
+  /** Threaded replies */
+  replies?: CommentReply[];
+  /** Emoji reactions */
+  reactions?: CommentReactions;
+}
diff --git a/packages/core/src/types/markdown-it-plugins.d.ts b/packages/core/src/types/markdown-it-plugins.d.ts
new file mode 100644
index 0000000..ea3eddb
--- /dev/null
+++ b/packages/core/src/types/markdown-it-plugins.d.ts
@@ -0,0 +1,29 @@
+/**
+ * Type declarations for markdown-it plugins without official types
+ */
+
+declare module 'markdown-it-attrs' {
+  import type MarkdownIt from 'markdown-it';
+  const markdownItAttrs: MarkdownIt.PluginWithOptions;
+  export default markdownItAttrs;
+}
+
+declare module 'markdown-it-task-lists' {
+  import type MarkdownIt from 'markdown-it';
+  const markdownItTaskLists: MarkdownIt.PluginWithOptions;
+  export default markdownItTaskLists;
+}
+
+declare module 'markdown-it-emoji' {
+  import type MarkdownIt from 'markdown-it';
+  const markdownItEmoji: MarkdownIt.PluginSimple;
+  export default markdownItEmoji;
+}
+
+declare module 'markdown-it-footnote' {
+  import type MarkdownIt from 'markdown-it';
+  const markdownItFootnote: MarkdownIt.PluginSimple;
+  export default markdownItFootnote;
+}
+
+
diff --git a/src/types/index.d.ts b/src/types/index.d.ts
index 1dce0fd..81ebc2c 100644
--- a/src/types/index.d.ts
+++ b/src/types/index.d.ts
@@ -1,584 +1,3 @@
-// Type definitions for MDView
-
-/**
- * Global window extensions
- */
-declare global {
-  const __APP_VERSION__: string;
-
-  interface Window {
-    __MDVIEW_MERMAID_CODE__?: Map<string, string>;
-  }
-}
-
-export type ThemeName =
-  | 'github-light'
-  | 'github-dark'
-  | 'catppuccin-latte'
-  | 'catppuccin-frappe'
-  | 'catppuccin-macchiato'
-  | 'catppuccin-mocha'
-  | 'monokai'
-  | 'monokai-pro'
-  | 'test-theme'; // For testing
-
-export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
-
-export interface AppState {
-  preferences: {
-    theme: ThemeName;
-    autoTheme: boolean;
-    lightTheme: ThemeName;
-    darkTheme: ThemeName;
-    syntaxTheme: string;
-    autoReload: boolean;
-    lineNumbers: boolean;
-    enableHtml: boolean; // Enable HTML rendering in markdown
-    syncTabs: boolean;
-    logLevel: LogLevel;
-    debug?: boolean; // Deprecated
-    // Editor / Appearance Overrides
-    fontFamily?: string;
-    codeFontFamily?: string;
-    lineHeight?: number;
-    maxWidth?: number;
-    useMaxWidth?: boolean; // Toggle for full width
-    // Table of Contents
-    showToc?: boolean; // Enable/disable TOC
-    tocMaxDepth?: number; // Max heading depth (1-6)
-    tocAutoCollapse?: boolean; // Auto-collapse nested sections
-    tocPosition?: 'left' | 'right'; // Position of TOC
-    tocStyle?: 'floating' | 'fixed'; // Style of TOC (floating card or fixed sidebar)
-    // Comments
-    commentsEnabled?: boolean; // Enable/disable comments feature
-    commentAuthor?: string; // Author name for new comments
-    // Export settings
-    exportDefaultFormat?: 'docx' | 'pdf';
-    exportDefaultPageSize?: PaperSize;
-    exportIncludeToc?: boolean;
-    exportFilenameTemplate?: string; // e.g., "{title}-{date}"
-    // Site blocklist - URLs/patterns where MDView should not render
-    blockedSites?: string[]; // e.g., ["github.com", "*.gitlab.com/*/blob/*"]
-  };
-  document: {
-    path: string;
-    content: string;
-    scrollPosition: number;
-    renderState: 'pending' | 'rendering' | 'complete' | 'error';
-  };
-  ui: {
-    theme: Theme | null;
-    maximizedDiagram: string | null;
-    visibleDiagrams: Set<string>;
-    tocVisible?: boolean; // Current TOC visibility state
-  };
-}
-
-export interface Theme {
-  name: ThemeName;
-  displayName: string;
-  variant: 'light' | 'dark';
-  author: string;
-  version: string;
-  colors: ThemeColors;
-  typography: ThemeTypography;
-  spacing: ThemeSpacing;
-  syntaxTheme: string;
-  mermaidTheme: MermaidThemeConfig;
-}
-
-export interface ThemeColors {
-  background: string;
-  backgroundSecondary: string;
-  backgroundTertiary: string;
-  foreground: string;
-  foregroundSecondary: string;
-  foregroundMuted: string;
-  primary: string;
-  secondary: string;
-  accent: string;
-  heading: string;
-  link: string;
-  linkHover: string;
-  linkVisited: string;
-  codeBackground: string;
-  codeText: string;
-  codeKeyword: string;
-  codeString: string;
-  codeComment: string;
-  codeFunction: string;
-  border: string;
-  borderLight: string;
-  borderHeavy: string;
-  selection: string;
-  highlight: string;
-  shadow: string;
-  success: string;
-  warning: string;
-  error: string;
-  info: string;
-  // Comment highlighting
-  commentHighlight: string;
-  commentHighlightResolved: string;
-  commentCardBg: string;
-}
-
-export interface ThemeTypography {
-  fontFamily: string;
-  headingFontFamily?: string;
-  codeFontFamily: string;
-  baseFontSize: string;
-  baseLineHeight: number;
-  h1Size: string;
-  h2Size: string;
-  h3Size: string;
-  h4Size: string;
-  h5Size: string;
-  h6Size: string;
-  fontWeightNormal: number;
-  fontWeightBold: number;
-  headingFontWeight: number;
-}
-
-export interface ThemeSpacing {
-  blockMargin: string;
-  paragraphMargin: string;
-  listItemMargin: string;
-  headingMargin: string;
-  codeBlockPadding: string;
-  tableCellPadding: string;
-}
-
-export interface MermaidThemeConfig {
-  theme: 'base' | 'dark' | 'default' | 'forest' | 'neutral';
-  themeVariables: {
-    primaryColor: string;
-    primaryTextColor: string;
-    primaryBorderColor: string;
-    lineColor: string;
-    secondaryColor: string;
-    tertiaryColor: string;
-    background: string;
-    mainBkg: string;
-    [key: string]: string;
-  };
-}
-
-export interface ConversionResult {
-  html: string;
-  metadata: {
-    wordCount: number;
-    headings: HeadingInfo[];
-    codeBlocks: CodeBlockInfo[];
-    mermaidBlocks: MermaidBlockInfo[];
-    images: ImageInfo[];
-    links: LinkInfo[];
-    frontmatter: Record<string, string> | null;
-  };
-  errors: ParseError[];
-}
-
-export interface HeadingInfo {
-  level: number;
-  text: string;
-  id: string;
-  line: number;
-}
-
-export interface CodeBlockInfo {
-  language: string;
-  code: string;
-  line: number;
-  lines: number;
-}
-
-export interface MermaidBlockInfo {
-  code: string;
-  line: number;
-}
-
-export interface ImageInfo {
-  src: string;
-  alt: string;
-  title?: string;
-  line: number;
-}
-
-export interface LinkInfo {
-  href: string;
-  text: string;
-  line: number;
-}
-
-export interface ParseError {
-  message: string;
-  line: number;
-  column: number;
-  severity: 'error' | 'warning';
-}
-
-export interface ValidationResult {
-  valid: boolean;
-  errors: ParseError[];
-  warnings: ParseError[];
-}
-
-// Cache types
-export interface CachedResult {
-  html: string;
-  metadata: ConversionResult['metadata'];
-  highlightedBlocks: Map<string, string>;
-  mermaidSVGs: Map<string, string>;
-  timestamp: number;
-  cacheKey: string;
-}
-
-export interface CacheEntry {
-  result: CachedResult;
-  filePath: string;
-  contentHash: string;
-  theme: ThemeName;
-  lastAccessed: number;
-}
-
-// Worker types
-export type WorkerTaskType = 'parse' | 'highlight' | 'mermaid';
-
-export interface WorkerTask {
-  type: WorkerTaskType;
-  id: string;
-  payload: unknown;
-  priority?: number;
-}
-
-// Message types for communication between content script and service worker
-export type MessageType =
-  | 'GET_STATE'
-  | 'UPDATE_PREFERENCES'
-  | 'APPLY_THEME'
-  | 'CACHE_GENERATE_KEY'
-  | 'CACHE_GET'
-  | 'CACHE_SET'
-  | 'CACHE_INVALIDATE'
-  | 'CACHE_INVALIDATE_BY_PATH'
-  | 'CACHE_STATS'
-  | 'REPORT_ERROR'
-  | 'CHECK_FILE_CHANGED' // New message type
-  | 'PREFERENCES_UPDATED'
-  | 'RELOAD_CONTENT';
-
-export interface WorkerResponse {
-  id: string;
-  result?: unknown;
-  error?: string;
-}
-
-export interface ParseTaskPayload {
-  markdown: string;
-  options?: {
-    breaks?: boolean;
-    linkify?: boolean;
-    typographer?: boolean;
-    enableHtml?: boolean;
-  };
-}
-
-export interface ParseTaskResult {
-  html: string;
-  metadata: ConversionResult['metadata'];
-}
-
-export interface HighlightTaskPayload {
-  code: string;
-  language: string;
-}
-
-export interface HighlightTaskResult {
-  html: string;
-  language: string;
-}
-
-export interface MermaidTaskPayload {
-  code: string;
-  theme?: MermaidThemeConfig;
-  id: string;
-}
-
-export interface MermaidTaskResult {
-  svg: string;
-  id: string;
-}
-
-// Export feature types
-
-/**
- * Supported export formats
- */
-export type ExportFormat = 'docx' | 'pdf';
-
-/**
- * Standard paper sizes for PDF export
- * ISO A-series: A0, A1, A3, A4, A5, A6
- * North American: Letter, Legal, Tabloid, Executive
- */
-export type PaperSize =
-  | 'A0'
-  | 'A1'
-  | 'A3'
-  | 'A4'
-  | 'A5'
-  | 'A6'
-  | 'Letter'
-  | 'Legal'
-  | 'Tabloid'
-  | 'Executive';
-
-/**
- * Content node types for export
- */
-export type ContentNodeType =
-  | 'heading'
-  | 'paragraph'
-  | 'list'
-  | 'code'
-  | 'table'
-  | 'image'
-  | 'mermaid'
-  | 'blockquote'
-  | 'hr';
-
-/**
- * Structured content node for export
- */
-export interface ContentNode {
-  type: ContentNodeType;
-  content: string | ContentNode[];
-  attributes: {
-    level?: number; // For headings (1-6)
-    language?: string; // For code blocks
-    ordered?: boolean; // For lists
-    id?: string; // For headings, images, mermaid
-    src?: string; // For images
-    alt?: string; // For images
-    [key: string]: unknown;
-  };
-  children?: ContentNode[];
-}
-
-/**
- * Collected content from rendered markdown
- */
-export interface CollectedContent {
-  title: string;
-  nodes: ContentNode[];
-  metadata: {
-    wordCount: number;
-    imageCount: number;
-    mermaidCount: number;
-    exportedAt: Date;
-  };
-}
-
-/**
- * SVG conversion options
- */
-export interface SVGConversionOptions {
-  scale?: number; // Default: 2 (retina) - only used for raster formats
-  format?: 'png' | 'jpeg' | 'svg'; // 'svg' preserves vector format
-  quality?: number; // JPEG quality 0-1
-  backgroundColor?: string;
-}
-
-/**
- * Converted image data
- */
-export interface ConvertedImage {
-  id: string;
-  data: string; // base64 encoded
-  width: number;
-  height: number;
-  format: string;
-}
-
-/**
- * Export options
- */
-export interface ExportOptions {
-  format: ExportFormat;
-  filename?: string;
-  includeImages?: boolean;
-  includeMermaid?: boolean;
-}
-
-/**
- * Export progress information
- */
-export interface ExportProgress {
-  stage: 'collecting' | 'converting' | 'generating' | 'downloading';
-  progress: number; // 0-100
-  message: string;
-}
-
-/**
- * Progress callback function
- */
-export type ProgressCallback = (progress: ExportProgress) => void;
-
-/**
- * DOCX Generator options
- */
-export interface DOCXGeneratorOptions {
-  title?: string;
-  author?: string;
-  includeTableOfContents?: boolean;
-  pageSize?: PaperSize;
-  margins?: {
-    top: number;
-    bottom: number;
-    left: number;
-    right: number;
-  };
-}
-
-/**
- * Export UI Options
- */
-export interface ExportUIOptions {
-  position?: 'left' | 'right';
-  formats?: ExportFormat[];
-  defaultPageSize?: PaperSize;
-  defaultFormat?: ExportFormat;
-  includeTableOfContents?: boolean;
-  filenameTemplate?: string;
-}
-
-/**
- * Export UI State
- */
-export interface ExportUIState {
-  isMenuOpen: boolean;
-  isExporting: boolean;
-  currentProgress: ExportProgress | null;
-  lastError: Error | null;
-}
-
-/**
- * PDF Generator options
- */
-export interface PDFGeneratorOptions {
-  paperSize?: PaperSize;
-  orientation?: 'portrait' | 'landscape';
-  margins?: string; // CSS margin value
-  convertSvgsToImages?: boolean;
-  pageBreakBeforeHeadings?: boolean;
-}
-
-/**
- * Filename template variables
- */
-export type FilenameTemplateVar =
-  | '{title}' // Document title
-  | '{date}' // YYYY-MM-DD
-  | '{datetime}' // YYYY-MM-DD_HH-mm
-  | '{timestamp}' // Unix timestamp
-  | '{year}' // YYYY
-  | '{month}' // MM
-  | '{day}'; // DD
-
-// Comment feature types
-
-/**
- * A reply within a comment thread
- */
-export interface CommentReply {
-  id: string;        // "reply-1", "reply-2", scoped within parent
-  author: string;
-  body: string;
-  date: string;      // ISO 8601
-}
-
-/**
- * Emoji reactions on a comment: emoji char → author names
- */
-export type CommentReactions = Record<string, string[]>;
-
-/**
- * Tag that can be applied to a comment to signal severity/intent.
- */
-export type CommentTag =
-  | 'blocking'
-  | 'nit'
-  | 'suggestion'
-  | 'question'
-  | 'praise'
-  | 'todo'
-  | 'fyi';
-
-/**
- * Positional context for a comment within the document structure.
- * Computed at comment-creation time from the source offset and document headings.
- * Stored in the footnote metadata so AI agents can read it directly from the file.
- */
-export interface CommentContext {
-  /** 1-based line number where the commented text appears */
-  line: number;
-  /** Nearest heading text above the comment (undefined if before any heading) */
-  section?: string;
-  /** Heading level of the nearest heading (1-6, undefined if before any heading) */
-  sectionLevel?: number;
-  /** Heading hierarchy from root to the containing section */
-  breadcrumb: string[];
-}
-
-/**
- * A single comment attached to text in the markdown
- */
-export interface Comment {
-  id: string; // e.g. "comment-1"
-  selectedText: string; // The text the comment is anchored to
-  body: string; // The comment content
-  author: string; // From extension settings
-  date: string; // ISO 8601 timestamp
-  resolved: boolean; // Whether the comment has been resolved
-  /** Positional context within the document; undefined for legacy comments */
-  context?: CommentContext;
-  /** Tags for categorizing comment severity/intent */
-  tags?: CommentTag[];
-  /** Threaded replies */
-  replies?: CommentReply[];
-  /** Emoji reactions */
-  reactions?: CommentReactions;
-  /** Prefix context for TextQuoteSelector anchoring */
-  anchorPrefix?: string;
-  /** Suffix context for TextQuoteSelector anchoring */
-  anchorSuffix?: string;
-}
-
-/**
- * Result of parsing comments from raw markdown
- */
-export interface CommentParseResult {
-  cleanedMarkdown: string; // Markdown with comment footnotes stripped
-  comments: Comment[]; // Extracted comments
-}
-
-/**
- * Comment metadata stored in the footnote HTML comment
- */
-export interface CommentMetadata {
-  author: string;
-  date: string;
-  resolved?: boolean;
-  selectedText?: string;
-  // Positional context fields (optional for backward compatibility)
-  line?: number;
-  section?: string;
-  sectionLevel?: number;
-  breadcrumb?: string[];
-  /** Tags for categorizing comment severity/intent */
-  tags?: CommentTag[];
-  /** Threaded replies */
-  replies?: CommentReply[];
-  /** Emoji reactions */
-  reactions?: CommentReactions;
-}
+// Re-export shim: types have moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/types/index';

From 995c97ff4cd31b506d5a4b5d9d7958e8e2943cee Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:16:57 -0400
Subject: [PATCH 05/26] refactor(core): move theme data modules to @mdview/core

---
 packages/core/src/__tests__/themes.test.ts    |  60 +++++++++
 packages/core/src/themes/catppuccin-frappe.ts | 110 +++++++++++++++
 packages/core/src/themes/catppuccin-latte.ts  | 110 +++++++++++++++
 .../core/src/themes/catppuccin-macchiato.ts   | 110 +++++++++++++++
 packages/core/src/themes/catppuccin-mocha.ts  | 110 +++++++++++++++
 packages/core/src/themes/github-dark.ts       | 126 +++++++++++++++++
 packages/core/src/themes/github-light.ts      | 126 +++++++++++++++++
 packages/core/src/themes/monokai-pro.ts       | 110 +++++++++++++++
 packages/core/src/themes/monokai.ts           | 110 +++++++++++++++
 src/themes/catppuccin-frappe.ts               | 111 +--------------
 src/themes/catppuccin-latte.ts                | 111 +--------------
 src/themes/catppuccin-macchiato.ts            | 111 +--------------
 src/themes/catppuccin-mocha.ts                | 111 +--------------
 src/themes/github-dark.ts                     | 127 +-----------------
 src/themes/github-light.ts                    | 127 +-----------------
 src/themes/monokai-pro.ts                     | 111 +--------------
 src/themes/monokai.ts                         | 111 +--------------
 17 files changed, 980 insertions(+), 912 deletions(-)
 create mode 100644 packages/core/src/__tests__/themes.test.ts
 create mode 100644 packages/core/src/themes/catppuccin-frappe.ts
 create mode 100644 packages/core/src/themes/catppuccin-latte.ts
 create mode 100644 packages/core/src/themes/catppuccin-macchiato.ts
 create mode 100644 packages/core/src/themes/catppuccin-mocha.ts
 create mode 100644 packages/core/src/themes/github-dark.ts
 create mode 100644 packages/core/src/themes/github-light.ts
 create mode 100644 packages/core/src/themes/monokai-pro.ts
 create mode 100644 packages/core/src/themes/monokai.ts

diff --git a/packages/core/src/__tests__/themes.test.ts b/packages/core/src/__tests__/themes.test.ts
new file mode 100644
index 0000000..af105c8
--- /dev/null
+++ b/packages/core/src/__tests__/themes.test.ts
@@ -0,0 +1,60 @@
+import type { Theme } from '../types/index';
+
+import catppuccinFrappe from '../themes/catppuccin-frappe';
+import catppuccinLatte from '../themes/catppuccin-latte';
+import catppuccinMacchiato from '../themes/catppuccin-macchiato';
+import catppuccinMocha from '../themes/catppuccin-mocha';
+import githubDark from '../themes/github-dark';
+import githubLight from '../themes/github-light';
+import monokaiPro from '../themes/monokai-pro';
+import monokai from '../themes/monokai';
+
+const requiredFields: (keyof Theme)[] = [
+  'name',
+  'displayName',
+  'variant',
+  'colors',
+  'typography',
+  'spacing',
+  'syntaxTheme',
+  'mermaidTheme',
+];
+
+const themes: { label: string; theme: Theme }[] = [
+  { label: 'catppuccin-frappe', theme: catppuccinFrappe },
+  { label: 'catppuccin-latte', theme: catppuccinLatte },
+  { label: 'catppuccin-macchiato', theme: catppuccinMacchiato },
+  { label: 'catppuccin-mocha', theme: catppuccinMocha },
+  { label: 'github-dark', theme: githubDark },
+  { label: 'github-light', theme: githubLight },
+  { label: 'monokai-pro', theme: monokaiPro },
+  { label: 'monokai', theme: monokai },
+];
+
+describe('@mdview/core themes', () => {
+  it.each(themes)('$label has all required Theme fields', ({ theme }) => {
+    for (const field of requiredFields) {
+      expect(theme).toHaveProperty(field);
+      expect(theme[field]).toBeDefined();
+    }
+  });
+
+  it.each(themes)('$label has a valid variant', ({ theme }) => {
+    expect(['light', 'dark']).toContain(theme.variant);
+  });
+
+  it.each(themes)('$label has name matching its label', ({ label, theme }) => {
+    expect(theme.name).toBe(label);
+  });
+
+  it.each(themes)('$label has non-empty displayName', ({ theme }) => {
+    expect(theme.displayName.length).toBeGreaterThan(0);
+  });
+
+  it.each(themes)('$label has valid mermaidTheme', ({ theme }) => {
+    expect(theme.mermaidTheme).toHaveProperty('theme');
+    expect(theme.mermaidTheme).toHaveProperty('themeVariables');
+    expect(theme.mermaidTheme.themeVariables).toHaveProperty('primaryColor');
+    expect(theme.mermaidTheme.themeVariables).toHaveProperty('primaryTextColor');
+  });
+});
diff --git a/packages/core/src/themes/catppuccin-frappe.ts b/packages/core/src/themes/catppuccin-frappe.ts
new file mode 100644
index 0000000..f60dfbe
--- /dev/null
+++ b/packages/core/src/themes/catppuccin-frappe.ts
@@ -0,0 +1,110 @@
+/**
+ * Catppuccin Frappé Theme
+ * Light-medium variant of Catppuccin
+ */
+
+import type { Theme } from '../types';
+
+const catppuccinFrappe: Theme = {
+  name: 'catppuccin-frappe',
+  displayName: 'Catppuccin Frappé',
+  variant: 'light',
+  author: 'Catppuccin',
+  version: '1.0.0',
+
+  colors: {
+    background: '#303446',
+    backgroundSecondary: '#292c3c',
+    backgroundTertiary: '#232634',
+    foreground: '#c6d0f5',
+    foregroundSecondary: '#b5bfe2',
+    foregroundMuted: '#a5adce',
+    primary: '#8caaee',
+    secondary: '#85c1dc',
+    accent: '#ca9ee6',
+    heading: '#c6d0f5',
+    link: '#8caaee',
+    linkHover: '#99d1db',
+    linkVisited: '#ca9ee6',
+    codeBackground: '#292c3c',
+    codeText: '#c6d0f5',
+    codeKeyword: '#e78284',
+    codeString: '#a6d189',
+    codeComment: '#737994',
+    codeFunction: '#ca9ee6',
+    border: '#414559',
+    borderLight: '#51576d',
+    borderHeavy: '#626880',
+    selection: 'rgba(140, 170, 238, 0.2)',
+    highlight: '#ef9f76',
+    shadow: 'rgba(0, 0, 0, 0.3)',
+    success: '#a6d189',
+    warning: '#ef9f76',
+    error: '#e78284',
+    info: '#8caaee',
+    commentHighlight: 'rgba(229, 200, 144, 0.25)',
+    commentHighlightResolved: 'rgba(229, 200, 144, 0.08)',
+    commentCardBg: '#292c3c',
+  },
+
+  typography: {
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+    codeFontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    baseFontSize: '16px',
+    baseLineHeight: 1.5,
+    h1Size: '2em',
+    h2Size: '1.5em',
+    h3Size: '1.25em',
+    h4Size: '1em',
+    h5Size: '0.875em',
+    h6Size: '0.85em',
+    fontWeightNormal: 400,
+    fontWeightBold: 600,
+    headingFontWeight: 600,
+  },
+
+  spacing: {
+    blockMargin: '16px 0',
+    paragraphMargin: '16px 0',
+    listItemMargin: '4px 0',
+    headingMargin: '24px 0 16px 0',
+    codeBlockPadding: '16px',
+    tableCellPadding: '6px 13px',
+  },
+
+  syntaxTheme: 'github-dark',
+
+  mermaidTheme: {
+    theme: 'dark',
+    themeVariables: {
+      primaryColor: '#8caaee',
+      primaryTextColor: '#303446',
+      primaryBorderColor: '#8caaee',
+      lineColor: '#c6d0f5',
+      secondaryColor: '#292c3c',
+      tertiaryColor: '#232634',
+      background: '#303446',
+      mainBkg: '#292c3c',
+      secondaryBkg: '#232634',
+      tertiaryBkg: '#303446',
+      textColor: '#c6d0f5',
+      tertiaryTextColor: '#c6d0f5',
+      nodeBkg: '#292c3c',
+      nodeBorder: '#414559',
+      clusterBkg: '#232634',
+      clusterBorder: '#414559',
+      defaultLinkColor: '#8caaee',
+      titleColor: '#c6d0f5',
+      edgeLabelBackground: '#303446',
+      // ER diagram specific
+      relationLabelColor: '#c6d0f5',
+      relationLabelBackground: '#303446',
+      attributeBackgroundColorOdd: '#292c3c',
+      attributeBackgroundColorEven: '#232634',
+    },
+  },
+};
+
+export default catppuccinFrappe;
diff --git a/packages/core/src/themes/catppuccin-latte.ts b/packages/core/src/themes/catppuccin-latte.ts
new file mode 100644
index 0000000..abd63db
--- /dev/null
+++ b/packages/core/src/themes/catppuccin-latte.ts
@@ -0,0 +1,110 @@
+/**
+ * Catppuccin Latte Theme
+ * Light variant of Catppuccin
+ */
+
+import type { Theme } from '../types';
+
+const catppuccinLatte: Theme = {
+  name: 'catppuccin-latte',
+  displayName: 'Catppuccin Latte',
+  variant: 'light',
+  author: 'Catppuccin',
+  version: '1.0.0',
+
+  colors: {
+    background: '#eff1f5',
+    backgroundSecondary: '#e6e9ef',
+    backgroundTertiary: '#dce0e8',
+    foreground: '#4c4f69',
+    foregroundSecondary: '#5c5f77',
+    foregroundMuted: '#6c6f85',
+    primary: '#1e66f5',
+    secondary: '#7287fd',
+    accent: '#8839ef',
+    heading: '#4c4f69',
+    link: '#1e66f5',
+    linkHover: '#04a5e5',
+    linkVisited: '#8839ef',
+    codeBackground: '#e6e9ef',
+    codeText: '#4c4f69',
+    codeKeyword: '#d20f39',
+    codeString: '#40a02b',
+    codeComment: '#7c7f93',
+    codeFunction: '#8839ef',
+    border: '#dce0e8',
+    borderLight: '#e6e9ef',
+    borderHeavy: '#bcc0cc',
+    selection: 'rgba(30, 102, 245, 0.2)',
+    highlight: '#df8e1d',
+    shadow: 'rgba(0, 0, 0, 0.1)',
+    success: '#40a02b',
+    warning: '#df8e1d',
+    error: '#d20f39',
+    info: '#1e66f5',
+    commentHighlight: 'rgba(223, 142, 29, 0.25)',
+    commentHighlightResolved: 'rgba(223, 142, 29, 0.08)',
+    commentCardBg: '#e6e9ef',
+  },
+
+  typography: {
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+    codeFontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    baseFontSize: '16px',
+    baseLineHeight: 1.5,
+    h1Size: '2em',
+    h2Size: '1.5em',
+    h3Size: '1.25em',
+    h4Size: '1em',
+    h5Size: '0.875em',
+    h6Size: '0.85em',
+    fontWeightNormal: 400,
+    fontWeightBold: 600,
+    headingFontWeight: 600,
+  },
+
+  spacing: {
+    blockMargin: '16px 0',
+    paragraphMargin: '16px 0',
+    listItemMargin: '4px 0',
+    headingMargin: '24px 0 16px 0',
+    codeBlockPadding: '16px',
+    tableCellPadding: '6px 13px',
+  },
+
+  syntaxTheme: 'github',
+
+  mermaidTheme: {
+    theme: 'base',
+    themeVariables: {
+      primaryColor: '#1e66f5',
+      primaryTextColor: '#eff1f5',
+      primaryBorderColor: '#1e66f5',
+      lineColor: '#4c4f69',
+      secondaryColor: '#e6e9ef',
+      tertiaryColor: '#dce0e8',
+      background: '#eff1f5',
+      mainBkg: '#e6e9ef',
+      secondaryBkg: '#dce0e8',
+      tertiaryBkg: '#eff1f5',
+      textColor: '#4c4f69',
+      tertiaryTextColor: '#4c4f69',
+      nodeBkg: '#e6e9ef',
+      nodeBorder: '#dce0e8',
+      clusterBkg: '#dce0e8',
+      clusterBorder: '#dce0e8',
+      defaultLinkColor: '#1e66f5',
+      titleColor: '#4c4f69',
+      edgeLabelBackground: '#eff1f5',
+      // ER diagram specific
+      relationLabelColor: '#4c4f69',
+      relationLabelBackground: '#eff1f5',
+      attributeBackgroundColorOdd: '#e6e9ef',
+      attributeBackgroundColorEven: '#dce0e8',
+    },
+  },
+};
+
+export default catppuccinLatte;
diff --git a/packages/core/src/themes/catppuccin-macchiato.ts b/packages/core/src/themes/catppuccin-macchiato.ts
new file mode 100644
index 0000000..3c26e89
--- /dev/null
+++ b/packages/core/src/themes/catppuccin-macchiato.ts
@@ -0,0 +1,110 @@
+/**
+ * Catppuccin Macchiato Theme
+ * Dark-medium variant of Catppuccin
+ */
+
+import type { Theme } from '../types';
+
+const catppuccinMacchiato: Theme = {
+  name: 'catppuccin-macchiato',
+  displayName: 'Catppuccin Macchiato',
+  variant: 'dark',
+  author: 'Catppuccin',
+  version: '1.0.0',
+
+  colors: {
+    background: '#24273a',
+    backgroundSecondary: '#1e2030',
+    backgroundTertiary: '#181926',
+    foreground: '#cad3f5',
+    foregroundSecondary: '#b8c0e0',
+    foregroundMuted: '#a5adcb',
+    primary: '#8aadf4',
+    secondary: '#7dc4e4',
+    accent: '#c6a0f6',
+    heading: '#cad3f5',
+    link: '#8aadf4',
+    linkHover: '#91d7e3',
+    linkVisited: '#c6a0f6',
+    codeBackground: '#1e2030',
+    codeText: '#cad3f5',
+    codeKeyword: '#ed8796',
+    codeString: '#a6da95',
+    codeComment: '#6e738d',
+    codeFunction: '#c6a0f6',
+    border: '#363a4f',
+    borderLight: '#494d64',
+    borderHeavy: '#5b6078',
+    selection: 'rgba(138, 173, 244, 0.2)',
+    highlight: '#f5a97f',
+    shadow: 'rgba(0, 0, 0, 0.4)',
+    success: '#a6da95',
+    warning: '#eed49f',
+    error: '#ed8796',
+    info: '#8aadf4',
+    commentHighlight: 'rgba(238, 212, 159, 0.25)',
+    commentHighlightResolved: 'rgba(238, 212, 159, 0.08)',
+    commentCardBg: '#1e2030',
+  },
+
+  typography: {
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+    codeFontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    baseFontSize: '16px',
+    baseLineHeight: 1.5,
+    h1Size: '2em',
+    h2Size: '1.5em',
+    h3Size: '1.25em',
+    h4Size: '1em',
+    h5Size: '0.875em',
+    h6Size: '0.85em',
+    fontWeightNormal: 400,
+    fontWeightBold: 600,
+    headingFontWeight: 600,
+  },
+
+  spacing: {
+    blockMargin: '16px 0',
+    paragraphMargin: '16px 0',
+    listItemMargin: '4px 0',
+    headingMargin: '24px 0 16px 0',
+    codeBlockPadding: '16px',
+    tableCellPadding: '6px 13px',
+  },
+
+  syntaxTheme: 'github-dark',
+
+  mermaidTheme: {
+    theme: 'dark',
+    themeVariables: {
+      primaryColor: '#8aadf4',
+      primaryTextColor: '#24273a',
+      primaryBorderColor: '#8aadf4',
+      lineColor: '#cad3f5',
+      secondaryColor: '#1e2030',
+      tertiaryColor: '#181926',
+      background: '#24273a',
+      mainBkg: '#1e2030',
+      secondaryBkg: '#181926',
+      tertiaryBkg: '#24273a',
+      textColor: '#cad3f5',
+      tertiaryTextColor: '#cad3f5',
+      nodeBkg: '#1e2030',
+      nodeBorder: '#363a4f',
+      clusterBkg: '#181926',
+      clusterBorder: '#363a4f',
+      defaultLinkColor: '#8aadf4',
+      titleColor: '#cad3f5',
+      edgeLabelBackground: '#24273a',
+      // ER diagram specific
+      relationLabelColor: '#cad3f5',
+      relationLabelBackground: '#24273a',
+      attributeBackgroundColorOdd: '#1e2030',
+      attributeBackgroundColorEven: '#181926',
+    },
+  },
+};
+
+export default catppuccinMacchiato;
diff --git a/packages/core/src/themes/catppuccin-mocha.ts b/packages/core/src/themes/catppuccin-mocha.ts
new file mode 100644
index 0000000..1c69a97
--- /dev/null
+++ b/packages/core/src/themes/catppuccin-mocha.ts
@@ -0,0 +1,110 @@
+/**
+ * Catppuccin Mocha Theme
+ * Dark variant of Catppuccin
+ */
+
+import type { Theme } from '../types';
+
+const catppuccinMocha: Theme = {
+  name: 'catppuccin-mocha',
+  displayName: 'Catppuccin Mocha',
+  variant: 'dark',
+  author: 'Catppuccin',
+  version: '1.0.0',
+
+  colors: {
+    background: '#1e1e2e',
+    backgroundSecondary: '#181825',
+    backgroundTertiary: '#11111b',
+    foreground: '#cdd6f4',
+    foregroundSecondary: '#bac2de',
+    foregroundMuted: '#a6adc8',
+    primary: '#89b4fa',
+    secondary: '#74c7ec',
+    accent: '#cba6f7',
+    heading: '#cdd6f4',
+    link: '#89b4fa',
+    linkHover: '#89dceb',
+    linkVisited: '#cba6f7',
+    codeBackground: '#181825',
+    codeText: '#cdd6f4',
+    codeKeyword: '#f38ba8',
+    codeString: '#a6e3a1',
+    codeComment: '#6c7086',
+    codeFunction: '#cba6f7',
+    border: '#313244',
+    borderLight: '#45475a',
+    borderHeavy: '#585b70',
+    selection: 'rgba(137, 180, 250, 0.2)',
+    highlight: '#f9e2af',
+    shadow: 'rgba(0, 0, 0, 0.5)',
+    success: '#a6e3a1',
+    warning: '#f9e2af',
+    error: '#f38ba8',
+    info: '#89b4fa',
+    commentHighlight: 'rgba(249, 226, 175, 0.25)',
+    commentHighlightResolved: 'rgba(249, 226, 175, 0.08)',
+    commentCardBg: '#1e1e2e',
+  },
+
+  typography: {
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+    codeFontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    baseFontSize: '16px',
+    baseLineHeight: 1.5,
+    h1Size: '2em',
+    h2Size: '1.5em',
+    h3Size: '1.25em',
+    h4Size: '1em',
+    h5Size: '0.875em',
+    h6Size: '0.85em',
+    fontWeightNormal: 400,
+    fontWeightBold: 600,
+    headingFontWeight: 600,
+  },
+
+  spacing: {
+    blockMargin: '16px 0',
+    paragraphMargin: '16px 0',
+    listItemMargin: '4px 0',
+    headingMargin: '24px 0 16px 0',
+    codeBlockPadding: '16px',
+    tableCellPadding: '6px 13px',
+  },
+
+  syntaxTheme: 'github-dark',
+
+  mermaidTheme: {
+    theme: 'dark',
+    themeVariables: {
+      primaryColor: '#89b4fa',
+      primaryTextColor: '#1e1e2e',
+      primaryBorderColor: '#89b4fa',
+      lineColor: '#cdd6f4',
+      secondaryColor: '#181825',
+      tertiaryColor: '#11111b',
+      background: '#1e1e2e',
+      mainBkg: '#181825',
+      secondaryBkg: '#11111b',
+      tertiaryBkg: '#1e1e2e',
+      textColor: '#cdd6f4',
+      tertiaryTextColor: '#cdd6f4',
+      nodeBkg: '#181825',
+      nodeBorder: '#313244',
+      clusterBkg: '#11111b',
+      clusterBorder: '#313244',
+      defaultLinkColor: '#89b4fa',
+      titleColor: '#cdd6f4',
+      edgeLabelBackground: '#1e1e2e',
+      // ER diagram specific
+      relationLabelColor: '#cdd6f4',
+      relationLabelBackground: '#1e1e2e',
+      attributeBackgroundColorOdd: '#181825',
+      attributeBackgroundColorEven: '#11111b',
+    },
+  },
+};
+
+export default catppuccinMocha;
diff --git a/packages/core/src/themes/github-dark.ts b/packages/core/src/themes/github-dark.ts
new file mode 100644
index 0000000..9c940b7
--- /dev/null
+++ b/packages/core/src/themes/github-dark.ts
@@ -0,0 +1,126 @@
+/**
+ * GitHub Dark Theme
+ * Based on GitHub's dark mode styles
+ */
+
+import type { Theme } from '../types';
+
+const githubDark: Theme = {
+  name: 'github-dark',
+  displayName: 'GitHub Dark',
+  variant: 'dark',
+  author: 'GitHub',
+  version: '1.0.0',
+
+  colors: {
+    background: '#0d1117',
+    backgroundSecondary: '#161b22',
+    backgroundTertiary: '#21262d',
+    foreground: '#c9d1d9',
+    foregroundSecondary: '#8b949e',
+    foregroundMuted: '#6e7681',
+    primary: '#58a6ff',
+    secondary: '#8b949e',
+    accent: '#58a6ff',
+    heading: '#c9d1d9',
+    link: '#58a6ff',
+    linkHover: '#79c0ff',
+    linkVisited: '#a371f7',
+    codeBackground: '#161b22',
+    codeText: '#c9d1d9',
+    codeKeyword: '#ff7b72',
+    codeString: '#a5d6ff',
+    codeComment: '#8b949e',
+    codeFunction: '#d2a8ff',
+    border: '#30363d',
+    borderLight: '#21262d',
+    borderHeavy: '#6e7681',
+    selection: 'rgba(88, 166, 255, 0.2)',
+    highlight: 'rgba(187, 128, 9, 0.3)',
+    shadow: 'rgba(0, 0, 0, 0.4)',
+    success: '#3fb950',
+    warning: '#d29922',
+    error: '#f85149',
+    info: '#58a6ff',
+    commentHighlight: 'rgba(255, 183, 77, 0.25)',
+    commentHighlightResolved: 'rgba(255, 183, 77, 0.08)',
+    commentCardBg: '#161b22',
+  },
+
+  typography: {
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"',
+    codeFontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    baseFontSize: '16px',
+    baseLineHeight: 1.5,
+    h1Size: '2em',
+    h2Size: '1.5em',
+    h3Size: '1.25em',
+    h4Size: '1em',
+    h5Size: '0.875em',
+    h6Size: '0.85em',
+    fontWeightNormal: 400,
+    fontWeightBold: 600,
+    headingFontWeight: 600,
+  },
+
+  spacing: {
+    blockMargin: '16px 0',
+    paragraphMargin: '16px 0',
+    listItemMargin: '4px 0',
+    headingMargin: '24px 0 16px 0',
+    codeBlockPadding: '16px',
+    tableCellPadding: '6px 13px',
+  },
+
+  syntaxTheme: 'github-dark',
+
+  mermaidTheme: {
+    theme: 'dark',
+    themeVariables: {
+      primaryColor: '#58a6ff',
+      primaryTextColor: '#0d1117',
+      primaryBorderColor: '#58a6ff',
+      lineColor: '#c9d1d9',
+      secondaryColor: '#161b22',
+      tertiaryColor: '#21262d',
+      background: '#0d1117',
+      mainBkg: '#161b22',
+      secondaryBkg: '#21262d',
+      tertiaryBkg: '#0d1117',
+      textColor: '#c9d1d9',
+      tertiaryTextColor: '#c9d1d9',
+      nodeBkg: '#161b22',
+      nodeBorder: '#30363d',
+      clusterBkg: '#21262d',
+      clusterBorder: '#30363d',
+      defaultLinkColor: '#58a6ff',
+      titleColor: '#c9d1d9',
+      edgeLabelBackground: '#0d1117',
+      // ER diagram specific
+      relationLabelColor: '#c9d1d9',
+      relationLabelBackground: '#0d1117',
+      attributeBackgroundColorOdd: '#161b22',
+      attributeBackgroundColorEven: '#21262d',
+      actorBorder: '#30363d',
+      actorBkg: '#161b22',
+      actorTextColor: '#c9d1d9',
+      actorLineColor: '#30363d',
+      signalColor: '#c9d1d9',
+      signalTextColor: '#0d1117',
+      labelBoxBkgColor: '#161b22',
+      labelBoxBorderColor: '#30363d',
+      labelTextColor: '#c9d1d9',
+      loopTextColor: '#c9d1d9',
+      noteBorderColor: '#30363d',
+      noteBkgColor: 'rgba(187, 128, 9, 0.3)',
+      noteTextColor: '#c9d1d9',
+      activationBorderColor: '#30363d',
+      activationBkgColor: '#21262d',
+      sequenceNumberColor: '#0d1117',
+    },
+  },
+};
+
+export default githubDark;
diff --git a/packages/core/src/themes/github-light.ts b/packages/core/src/themes/github-light.ts
new file mode 100644
index 0000000..5a79ae0
--- /dev/null
+++ b/packages/core/src/themes/github-light.ts
@@ -0,0 +1,126 @@
+/**
+ * GitHub Light Theme
+ * Based on GitHub's markdown styles
+ */
+
+import type { Theme } from '../types';
+
+const githubLight: Theme = {
+  name: 'github-light',
+  displayName: 'GitHub Light',
+  variant: 'light',
+  author: 'GitHub',
+  version: '1.0.0',
+
+  colors: {
+    background: '#ffffff',
+    backgroundSecondary: '#f6f8fa',
+    backgroundTertiary: '#eaeef2',
+    foreground: '#24292f',
+    foregroundSecondary: '#57606a',
+    foregroundMuted: '#6e7781',
+    primary: '#0969da',
+    secondary: '#6e7781',
+    accent: '#0969da',
+    heading: '#1f2328',
+    link: '#0969da',
+    linkHover: '#0550ae',
+    linkVisited: '#8250df',
+    codeBackground: '#f6f8fa',
+    codeText: '#24292f',
+    codeKeyword: '#cf222e',
+    codeString: '#0a3069',
+    codeComment: '#6e7781',
+    codeFunction: '#8250df',
+    border: '#d0d7de',
+    borderLight: '#d8dee4',
+    borderHeavy: '#8c959f',
+    selection: 'rgba(9, 105, 218, 0.2)',
+    highlight: '#fff8c5',
+    shadow: 'rgba(0, 0, 0, 0.1)',
+    success: '#1a7f37',
+    warning: '#9a6700',
+    error: '#cf222e',
+    info: '#0969da',
+    commentHighlight: 'rgba(255, 212, 59, 0.3)',
+    commentHighlightResolved: 'rgba(255, 212, 59, 0.1)',
+    commentCardBg: '#f6f8fa',
+  },
+
+  typography: {
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"',
+    codeFontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    baseFontSize: '16px',
+    baseLineHeight: 1.5,
+    h1Size: '2em',
+    h2Size: '1.5em',
+    h3Size: '1.25em',
+    h4Size: '1em',
+    h5Size: '0.875em',
+    h6Size: '0.85em',
+    fontWeightNormal: 400,
+    fontWeightBold: 600,
+    headingFontWeight: 600,
+  },
+
+  spacing: {
+    blockMargin: '16px 0',
+    paragraphMargin: '16px 0',
+    listItemMargin: '4px 0',
+    headingMargin: '24px 0 16px 0',
+    codeBlockPadding: '16px',
+    tableCellPadding: '6px 13px',
+  },
+
+  syntaxTheme: 'github',
+
+  mermaidTheme: {
+    theme: 'base',
+    themeVariables: {
+      primaryColor: '#0969da',
+      primaryTextColor: '#000000',
+      primaryBorderColor: '#0969da',
+      lineColor: '#24292f',
+      secondaryColor: '#f6f8fa',
+      tertiaryColor: '#eaeef2',
+      background: '#ffffff',
+      mainBkg: '#f6f8fa',
+      secondaryBkg: '#eaeef2',
+      tertiaryBkg: '#ffffff',
+      textColor: '#24292f',
+      tertiaryTextColor: '#24292f',
+      nodeBkg: '#f6f8fa',
+      nodeBorder: '#d0d7de',
+      clusterBkg: '#eaeef2',
+      clusterBorder: '#d0d7de',
+      defaultLinkColor: '#0969da',
+      titleColor: '#1f2328',
+      edgeLabelBackground: '#ffffff',
+      // ER diagram specific
+      relationLabelColor: '#24292f',
+      relationLabelBackground: '#ffffff',
+      attributeBackgroundColorOdd: '#f6f8fa',
+      attributeBackgroundColorEven: '#ffffff',
+      actorBorder: '#d0d7de',
+      actorBkg: '#f6f8fa',
+      actorTextColor: '#24292f',
+      actorLineColor: '#d0d7de',
+      signalColor: '#24292f',
+      signalTextColor: '#24292f',
+      labelBoxBkgColor: '#f6f8fa',
+      labelBoxBorderColor: '#d0d7de',
+      labelTextColor: '#24292f',
+      loopTextColor: '#24292f',
+      noteBorderColor: '#d0d7de',
+      noteBkgColor: '#fff8c5',
+      noteTextColor: '#24292f',
+      activationBorderColor: '#d0d7de',
+      activationBkgColor: '#eaeef2',
+      sequenceNumberColor: '#ffffff',
+    },
+  },
+};
+
+export default githubLight;
diff --git a/packages/core/src/themes/monokai-pro.ts b/packages/core/src/themes/monokai-pro.ts
new file mode 100644
index 0000000..bb2c5c9
--- /dev/null
+++ b/packages/core/src/themes/monokai-pro.ts
@@ -0,0 +1,110 @@
+/**
+ * Monokai Pro Theme
+ * Enhanced version of Monokai with refined colors
+ */
+
+import type { Theme } from '../types';
+
+const monokaiPro: Theme = {
+  name: 'monokai-pro',
+  displayName: 'Monokai Pro',
+  variant: 'dark',
+  author: 'Monokai',
+  version: '1.0.0',
+
+  colors: {
+    background: '#2d2a2e',
+    backgroundSecondary: '#403e41',
+    backgroundTertiary: '#5b595c',
+    foreground: '#fcfcfa',
+    foregroundSecondary: '#d9d9d7',
+    foregroundMuted: '#939293',
+    primary: '#78dce8',
+    secondary: '#a9dc76',
+    accent: '#ab9df2',
+    heading: '#fcfcfa',
+    link: '#78dce8',
+    linkHover: '#a9dc76',
+    linkVisited: '#ab9df2',
+    codeBackground: '#403e41',
+    codeText: '#fcfcfa',
+    codeKeyword: '#ff6188',
+    codeString: '#ffd866',
+    codeComment: '#727072',
+    codeFunction: '#a9dc76',
+    border: '#5b595c',
+    borderLight: '#6e6c6f',
+    borderHeavy: '#939293',
+    selection: 'rgba(120, 220, 232, 0.2)',
+    highlight: '#ffd866',
+    shadow: 'rgba(0, 0, 0, 0.5)',
+    success: '#a9dc76',
+    warning: '#ffd866',
+    error: '#ff6188',
+    info: '#78dce8',
+    commentHighlight: 'rgba(255, 216, 102, 0.25)',
+    commentHighlightResolved: 'rgba(255, 216, 102, 0.08)',
+    commentCardBg: '#363537',
+  },
+
+  typography: {
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+    codeFontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    baseFontSize: '16px',
+    baseLineHeight: 1.5,
+    h1Size: '2em',
+    h2Size: '1.5em',
+    h3Size: '1.25em',
+    h4Size: '1em',
+    h5Size: '0.875em',
+    h6Size: '0.85em',
+    fontWeightNormal: 400,
+    fontWeightBold: 600,
+    headingFontWeight: 600,
+  },
+
+  spacing: {
+    blockMargin: '16px 0',
+    paragraphMargin: '16px 0',
+    listItemMargin: '4px 0',
+    headingMargin: '24px 0 16px 0',
+    codeBlockPadding: '16px',
+    tableCellPadding: '6px 13px',
+  },
+
+  syntaxTheme: 'monokai',
+
+  mermaidTheme: {
+    theme: 'dark',
+    themeVariables: {
+      primaryColor: '#78dce8',
+      primaryTextColor: '#2d2a2e',
+      primaryBorderColor: '#78dce8',
+      lineColor: '#fcfcfa',
+      secondaryColor: '#403e41',
+      tertiaryColor: '#5b595c',
+      background: '#2d2a2e',
+      mainBkg: '#403e41',
+      secondaryBkg: '#5b595c',
+      tertiaryBkg: '#2d2a2e',
+      textColor: '#fcfcfa',
+      tertiaryTextColor: '#fcfcfa',
+      nodeBkg: '#403e41',
+      nodeBorder: '#5b595c',
+      clusterBkg: '#5b595c',
+      clusterBorder: '#5b595c',
+      defaultLinkColor: '#78dce8',
+      titleColor: '#fcfcfa',
+      edgeLabelBackground: '#2d2a2e',
+      // ER diagram specific
+      relationLabelColor: '#fcfcfa',
+      relationLabelBackground: '#2d2a2e',
+      attributeBackgroundColorOdd: '#403e41',
+      attributeBackgroundColorEven: '#5b595c',
+    },
+  },
+};
+
+export default monokaiPro;
diff --git a/packages/core/src/themes/monokai.ts b/packages/core/src/themes/monokai.ts
new file mode 100644
index 0000000..d770edb
--- /dev/null
+++ b/packages/core/src/themes/monokai.ts
@@ -0,0 +1,110 @@
+/**
+ * Monokai Theme
+ * Classic Monokai color scheme
+ */
+
+import type { Theme } from '../types';
+
+const monokai: Theme = {
+  name: 'monokai',
+  displayName: 'Monokai',
+  variant: 'dark',
+  author: 'Wimer Hazenberg',
+  version: '1.0.0',
+
+  colors: {
+    background: '#272822',
+    backgroundSecondary: '#3e3d32',
+    backgroundTertiary: '#49483e',
+    foreground: '#f8f8f2',
+    foregroundSecondary: '#cfcfc2',
+    foregroundMuted: '#75715e',
+    primary: '#66d9ef',
+    secondary: '#a1efe4',
+    accent: '#ae81ff',
+    heading: '#f8f8f2',
+    link: '#66d9ef',
+    linkHover: '#a1efe4',
+    linkVisited: '#ae81ff',
+    codeBackground: '#3e3d32',
+    codeText: '#f8f8f2',
+    codeKeyword: '#f92672',
+    codeString: '#e6db74',
+    codeComment: '#75715e',
+    codeFunction: '#a6e22e',
+    border: '#49483e',
+    borderLight: '#5e5d52',
+    borderHeavy: '#75715e',
+    selection: 'rgba(102, 217, 239, 0.2)',
+    highlight: '#e6db74',
+    shadow: 'rgba(0, 0, 0, 0.5)',
+    success: '#a6e22e',
+    warning: '#e6db74',
+    error: '#f92672',
+    info: '#66d9ef',
+    commentHighlight: 'rgba(230, 219, 116, 0.25)',
+    commentHighlightResolved: 'rgba(230, 219, 116, 0.08)',
+    commentCardBg: '#3e3d32',
+  },
+
+  typography: {
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+    codeFontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    baseFontSize: '16px',
+    baseLineHeight: 1.5,
+    h1Size: '2em',
+    h2Size: '1.5em',
+    h3Size: '1.25em',
+    h4Size: '1em',
+    h5Size: '0.875em',
+    h6Size: '0.85em',
+    fontWeightNormal: 400,
+    fontWeightBold: 600,
+    headingFontWeight: 600,
+  },
+
+  spacing: {
+    blockMargin: '16px 0',
+    paragraphMargin: '16px 0',
+    listItemMargin: '4px 0',
+    headingMargin: '24px 0 16px 0',
+    codeBlockPadding: '16px',
+    tableCellPadding: '6px 13px',
+  },
+
+  syntaxTheme: 'monokai',
+
+  mermaidTheme: {
+    theme: 'dark',
+    themeVariables: {
+      primaryColor: '#66d9ef',
+      primaryTextColor: '#272822',
+      primaryBorderColor: '#66d9ef',
+      lineColor: '#f8f8f2',
+      secondaryColor: '#3e3d32',
+      tertiaryColor: '#49483e',
+      background: '#272822',
+      mainBkg: '#3e3d32',
+      secondaryBkg: '#49483e',
+      tertiaryBkg: '#272822',
+      textColor: '#f8f8f2',
+      tertiaryTextColor: '#f8f8f2',
+      nodeBkg: '#3e3d32',
+      nodeBorder: '#49483e',
+      clusterBkg: '#49483e',
+      clusterBorder: '#49483e',
+      defaultLinkColor: '#66d9ef',
+      titleColor: '#f8f8f2',
+      edgeLabelBackground: '#272822',
+      // ER diagram specific
+      relationLabelColor: '#f8f8f2',
+      relationLabelBackground: '#272822',
+      attributeBackgroundColorOdd: '#3e3d32',
+      attributeBackgroundColorEven: '#49483e',
+    },
+  },
+};
+
+export default monokai;
diff --git a/src/themes/catppuccin-frappe.ts b/src/themes/catppuccin-frappe.ts
index f60dfbe..b4efbed 100644
--- a/src/themes/catppuccin-frappe.ts
+++ b/src/themes/catppuccin-frappe.ts
@@ -1,110 +1 @@
-/**
- * Catppuccin Frappé Theme
- * Light-medium variant of Catppuccin
- */
-
-import type { Theme } from '../types';
-
-const catppuccinFrappe: Theme = {
-  name: 'catppuccin-frappe',
-  displayName: 'Catppuccin Frappé',
-  variant: 'light',
-  author: 'Catppuccin',
-  version: '1.0.0',
-
-  colors: {
-    background: '#303446',
-    backgroundSecondary: '#292c3c',
-    backgroundTertiary: '#232634',
-    foreground: '#c6d0f5',
-    foregroundSecondary: '#b5bfe2',
-    foregroundMuted: '#a5adce',
-    primary: '#8caaee',
-    secondary: '#85c1dc',
-    accent: '#ca9ee6',
-    heading: '#c6d0f5',
-    link: '#8caaee',
-    linkHover: '#99d1db',
-    linkVisited: '#ca9ee6',
-    codeBackground: '#292c3c',
-    codeText: '#c6d0f5',
-    codeKeyword: '#e78284',
-    codeString: '#a6d189',
-    codeComment: '#737994',
-    codeFunction: '#ca9ee6',
-    border: '#414559',
-    borderLight: '#51576d',
-    borderHeavy: '#626880',
-    selection: 'rgba(140, 170, 238, 0.2)',
-    highlight: '#ef9f76',
-    shadow: 'rgba(0, 0, 0, 0.3)',
-    success: '#a6d189',
-    warning: '#ef9f76',
-    error: '#e78284',
-    info: '#8caaee',
-    commentHighlight: 'rgba(229, 200, 144, 0.25)',
-    commentHighlightResolved: 'rgba(229, 200, 144, 0.08)',
-    commentCardBg: '#292c3c',
-  },
-
-  typography: {
-    fontFamily:
-      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
-    codeFontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    baseFontSize: '16px',
-    baseLineHeight: 1.5,
-    h1Size: '2em',
-    h2Size: '1.5em',
-    h3Size: '1.25em',
-    h4Size: '1em',
-    h5Size: '0.875em',
-    h6Size: '0.85em',
-    fontWeightNormal: 400,
-    fontWeightBold: 600,
-    headingFontWeight: 600,
-  },
-
-  spacing: {
-    blockMargin: '16px 0',
-    paragraphMargin: '16px 0',
-    listItemMargin: '4px 0',
-    headingMargin: '24px 0 16px 0',
-    codeBlockPadding: '16px',
-    tableCellPadding: '6px 13px',
-  },
-
-  syntaxTheme: 'github-dark',
-
-  mermaidTheme: {
-    theme: 'dark',
-    themeVariables: {
-      primaryColor: '#8caaee',
-      primaryTextColor: '#303446',
-      primaryBorderColor: '#8caaee',
-      lineColor: '#c6d0f5',
-      secondaryColor: '#292c3c',
-      tertiaryColor: '#232634',
-      background: '#303446',
-      mainBkg: '#292c3c',
-      secondaryBkg: '#232634',
-      tertiaryBkg: '#303446',
-      textColor: '#c6d0f5',
-      tertiaryTextColor: '#c6d0f5',
-      nodeBkg: '#292c3c',
-      nodeBorder: '#414559',
-      clusterBkg: '#232634',
-      clusterBorder: '#414559',
-      defaultLinkColor: '#8caaee',
-      titleColor: '#c6d0f5',
-      edgeLabelBackground: '#303446',
-      // ER diagram specific
-      relationLabelColor: '#c6d0f5',
-      relationLabelBackground: '#303446',
-      attributeBackgroundColorOdd: '#292c3c',
-      attributeBackgroundColorEven: '#232634',
-    },
-  },
-};
-
-export default catppuccinFrappe;
+export { default } from '../../packages/core/src/themes/catppuccin-frappe';
diff --git a/src/themes/catppuccin-latte.ts b/src/themes/catppuccin-latte.ts
index abd63db..0b868f9 100644
--- a/src/themes/catppuccin-latte.ts
+++ b/src/themes/catppuccin-latte.ts
@@ -1,110 +1 @@
-/**
- * Catppuccin Latte Theme
- * Light variant of Catppuccin
- */
-
-import type { Theme } from '../types';
-
-const catppuccinLatte: Theme = {
-  name: 'catppuccin-latte',
-  displayName: 'Catppuccin Latte',
-  variant: 'light',
-  author: 'Catppuccin',
-  version: '1.0.0',
-
-  colors: {
-    background: '#eff1f5',
-    backgroundSecondary: '#e6e9ef',
-    backgroundTertiary: '#dce0e8',
-    foreground: '#4c4f69',
-    foregroundSecondary: '#5c5f77',
-    foregroundMuted: '#6c6f85',
-    primary: '#1e66f5',
-    secondary: '#7287fd',
-    accent: '#8839ef',
-    heading: '#4c4f69',
-    link: '#1e66f5',
-    linkHover: '#04a5e5',
-    linkVisited: '#8839ef',
-    codeBackground: '#e6e9ef',
-    codeText: '#4c4f69',
-    codeKeyword: '#d20f39',
-    codeString: '#40a02b',
-    codeComment: '#7c7f93',
-    codeFunction: '#8839ef',
-    border: '#dce0e8',
-    borderLight: '#e6e9ef',
-    borderHeavy: '#bcc0cc',
-    selection: 'rgba(30, 102, 245, 0.2)',
-    highlight: '#df8e1d',
-    shadow: 'rgba(0, 0, 0, 0.1)',
-    success: '#40a02b',
-    warning: '#df8e1d',
-    error: '#d20f39',
-    info: '#1e66f5',
-    commentHighlight: 'rgba(223, 142, 29, 0.25)',
-    commentHighlightResolved: 'rgba(223, 142, 29, 0.08)',
-    commentCardBg: '#e6e9ef',
-  },
-
-  typography: {
-    fontFamily:
-      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
-    codeFontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    baseFontSize: '16px',
-    baseLineHeight: 1.5,
-    h1Size: '2em',
-    h2Size: '1.5em',
-    h3Size: '1.25em',
-    h4Size: '1em',
-    h5Size: '0.875em',
-    h6Size: '0.85em',
-    fontWeightNormal: 400,
-    fontWeightBold: 600,
-    headingFontWeight: 600,
-  },
-
-  spacing: {
-    blockMargin: '16px 0',
-    paragraphMargin: '16px 0',
-    listItemMargin: '4px 0',
-    headingMargin: '24px 0 16px 0',
-    codeBlockPadding: '16px',
-    tableCellPadding: '6px 13px',
-  },
-
-  syntaxTheme: 'github',
-
-  mermaidTheme: {
-    theme: 'base',
-    themeVariables: {
-      primaryColor: '#1e66f5',
-      primaryTextColor: '#eff1f5',
-      primaryBorderColor: '#1e66f5',
-      lineColor: '#4c4f69',
-      secondaryColor: '#e6e9ef',
-      tertiaryColor: '#dce0e8',
-      background: '#eff1f5',
-      mainBkg: '#e6e9ef',
-      secondaryBkg: '#dce0e8',
-      tertiaryBkg: '#eff1f5',
-      textColor: '#4c4f69',
-      tertiaryTextColor: '#4c4f69',
-      nodeBkg: '#e6e9ef',
-      nodeBorder: '#dce0e8',
-      clusterBkg: '#dce0e8',
-      clusterBorder: '#dce0e8',
-      defaultLinkColor: '#1e66f5',
-      titleColor: '#4c4f69',
-      edgeLabelBackground: '#eff1f5',
-      // ER diagram specific
-      relationLabelColor: '#4c4f69',
-      relationLabelBackground: '#eff1f5',
-      attributeBackgroundColorOdd: '#e6e9ef',
-      attributeBackgroundColorEven: '#dce0e8',
-    },
-  },
-};
-
-export default catppuccinLatte;
+export { default } from '../../packages/core/src/themes/catppuccin-latte';
diff --git a/src/themes/catppuccin-macchiato.ts b/src/themes/catppuccin-macchiato.ts
index 3c26e89..c48eba1 100644
--- a/src/themes/catppuccin-macchiato.ts
+++ b/src/themes/catppuccin-macchiato.ts
@@ -1,110 +1 @@
-/**
- * Catppuccin Macchiato Theme
- * Dark-medium variant of Catppuccin
- */
-
-import type { Theme } from '../types';
-
-const catppuccinMacchiato: Theme = {
-  name: 'catppuccin-macchiato',
-  displayName: 'Catppuccin Macchiato',
-  variant: 'dark',
-  author: 'Catppuccin',
-  version: '1.0.0',
-
-  colors: {
-    background: '#24273a',
-    backgroundSecondary: '#1e2030',
-    backgroundTertiary: '#181926',
-    foreground: '#cad3f5',
-    foregroundSecondary: '#b8c0e0',
-    foregroundMuted: '#a5adcb',
-    primary: '#8aadf4',
-    secondary: '#7dc4e4',
-    accent: '#c6a0f6',
-    heading: '#cad3f5',
-    link: '#8aadf4',
-    linkHover: '#91d7e3',
-    linkVisited: '#c6a0f6',
-    codeBackground: '#1e2030',
-    codeText: '#cad3f5',
-    codeKeyword: '#ed8796',
-    codeString: '#a6da95',
-    codeComment: '#6e738d',
-    codeFunction: '#c6a0f6',
-    border: '#363a4f',
-    borderLight: '#494d64',
-    borderHeavy: '#5b6078',
-    selection: 'rgba(138, 173, 244, 0.2)',
-    highlight: '#f5a97f',
-    shadow: 'rgba(0, 0, 0, 0.4)',
-    success: '#a6da95',
-    warning: '#eed49f',
-    error: '#ed8796',
-    info: '#8aadf4',
-    commentHighlight: 'rgba(238, 212, 159, 0.25)',
-    commentHighlightResolved: 'rgba(238, 212, 159, 0.08)',
-    commentCardBg: '#1e2030',
-  },
-
-  typography: {
-    fontFamily:
-      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
-    codeFontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    baseFontSize: '16px',
-    baseLineHeight: 1.5,
-    h1Size: '2em',
-    h2Size: '1.5em',
-    h3Size: '1.25em',
-    h4Size: '1em',
-    h5Size: '0.875em',
-    h6Size: '0.85em',
-    fontWeightNormal: 400,
-    fontWeightBold: 600,
-    headingFontWeight: 600,
-  },
-
-  spacing: {
-    blockMargin: '16px 0',
-    paragraphMargin: '16px 0',
-    listItemMargin: '4px 0',
-    headingMargin: '24px 0 16px 0',
-    codeBlockPadding: '16px',
-    tableCellPadding: '6px 13px',
-  },
-
-  syntaxTheme: 'github-dark',
-
-  mermaidTheme: {
-    theme: 'dark',
-    themeVariables: {
-      primaryColor: '#8aadf4',
-      primaryTextColor: '#24273a',
-      primaryBorderColor: '#8aadf4',
-      lineColor: '#cad3f5',
-      secondaryColor: '#1e2030',
-      tertiaryColor: '#181926',
-      background: '#24273a',
-      mainBkg: '#1e2030',
-      secondaryBkg: '#181926',
-      tertiaryBkg: '#24273a',
-      textColor: '#cad3f5',
-      tertiaryTextColor: '#cad3f5',
-      nodeBkg: '#1e2030',
-      nodeBorder: '#363a4f',
-      clusterBkg: '#181926',
-      clusterBorder: '#363a4f',
-      defaultLinkColor: '#8aadf4',
-      titleColor: '#cad3f5',
-      edgeLabelBackground: '#24273a',
-      // ER diagram specific
-      relationLabelColor: '#cad3f5',
-      relationLabelBackground: '#24273a',
-      attributeBackgroundColorOdd: '#1e2030',
-      attributeBackgroundColorEven: '#181926',
-    },
-  },
-};
-
-export default catppuccinMacchiato;
+export { default } from '../../packages/core/src/themes/catppuccin-macchiato';
diff --git a/src/themes/catppuccin-mocha.ts b/src/themes/catppuccin-mocha.ts
index 1c69a97..2202138 100644
--- a/src/themes/catppuccin-mocha.ts
+++ b/src/themes/catppuccin-mocha.ts
@@ -1,110 +1 @@
-/**
- * Catppuccin Mocha Theme
- * Dark variant of Catppuccin
- */
-
-import type { Theme } from '../types';
-
-const catppuccinMocha: Theme = {
-  name: 'catppuccin-mocha',
-  displayName: 'Catppuccin Mocha',
-  variant: 'dark',
-  author: 'Catppuccin',
-  version: '1.0.0',
-
-  colors: {
-    background: '#1e1e2e',
-    backgroundSecondary: '#181825',
-    backgroundTertiary: '#11111b',
-    foreground: '#cdd6f4',
-    foregroundSecondary: '#bac2de',
-    foregroundMuted: '#a6adc8',
-    primary: '#89b4fa',
-    secondary: '#74c7ec',
-    accent: '#cba6f7',
-    heading: '#cdd6f4',
-    link: '#89b4fa',
-    linkHover: '#89dceb',
-    linkVisited: '#cba6f7',
-    codeBackground: '#181825',
-    codeText: '#cdd6f4',
-    codeKeyword: '#f38ba8',
-    codeString: '#a6e3a1',
-    codeComment: '#6c7086',
-    codeFunction: '#cba6f7',
-    border: '#313244',
-    borderLight: '#45475a',
-    borderHeavy: '#585b70',
-    selection: 'rgba(137, 180, 250, 0.2)',
-    highlight: '#f9e2af',
-    shadow: 'rgba(0, 0, 0, 0.5)',
-    success: '#a6e3a1',
-    warning: '#f9e2af',
-    error: '#f38ba8',
-    info: '#89b4fa',
-    commentHighlight: 'rgba(249, 226, 175, 0.25)',
-    commentHighlightResolved: 'rgba(249, 226, 175, 0.08)',
-    commentCardBg: '#1e1e2e',
-  },
-
-  typography: {
-    fontFamily:
-      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
-    codeFontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    baseFontSize: '16px',
-    baseLineHeight: 1.5,
-    h1Size: '2em',
-    h2Size: '1.5em',
-    h3Size: '1.25em',
-    h4Size: '1em',
-    h5Size: '0.875em',
-    h6Size: '0.85em',
-    fontWeightNormal: 400,
-    fontWeightBold: 600,
-    headingFontWeight: 600,
-  },
-
-  spacing: {
-    blockMargin: '16px 0',
-    paragraphMargin: '16px 0',
-    listItemMargin: '4px 0',
-    headingMargin: '24px 0 16px 0',
-    codeBlockPadding: '16px',
-    tableCellPadding: '6px 13px',
-  },
-
-  syntaxTheme: 'github-dark',
-
-  mermaidTheme: {
-    theme: 'dark',
-    themeVariables: {
-      primaryColor: '#89b4fa',
-      primaryTextColor: '#1e1e2e',
-      primaryBorderColor: '#89b4fa',
-      lineColor: '#cdd6f4',
-      secondaryColor: '#181825',
-      tertiaryColor: '#11111b',
-      background: '#1e1e2e',
-      mainBkg: '#181825',
-      secondaryBkg: '#11111b',
-      tertiaryBkg: '#1e1e2e',
-      textColor: '#cdd6f4',
-      tertiaryTextColor: '#cdd6f4',
-      nodeBkg: '#181825',
-      nodeBorder: '#313244',
-      clusterBkg: '#11111b',
-      clusterBorder: '#313244',
-      defaultLinkColor: '#89b4fa',
-      titleColor: '#cdd6f4',
-      edgeLabelBackground: '#1e1e2e',
-      // ER diagram specific
-      relationLabelColor: '#cdd6f4',
-      relationLabelBackground: '#1e1e2e',
-      attributeBackgroundColorOdd: '#181825',
-      attributeBackgroundColorEven: '#11111b',
-    },
-  },
-};
-
-export default catppuccinMocha;
+export { default } from '../../packages/core/src/themes/catppuccin-mocha';
diff --git a/src/themes/github-dark.ts b/src/themes/github-dark.ts
index 9c940b7..50edacf 100644
--- a/src/themes/github-dark.ts
+++ b/src/themes/github-dark.ts
@@ -1,126 +1 @@
-/**
- * GitHub Dark Theme
- * Based on GitHub's dark mode styles
- */
-
-import type { Theme } from '../types';
-
-const githubDark: Theme = {
-  name: 'github-dark',
-  displayName: 'GitHub Dark',
-  variant: 'dark',
-  author: 'GitHub',
-  version: '1.0.0',
-
-  colors: {
-    background: '#0d1117',
-    backgroundSecondary: '#161b22',
-    backgroundTertiary: '#21262d',
-    foreground: '#c9d1d9',
-    foregroundSecondary: '#8b949e',
-    foregroundMuted: '#6e7681',
-    primary: '#58a6ff',
-    secondary: '#8b949e',
-    accent: '#58a6ff',
-    heading: '#c9d1d9',
-    link: '#58a6ff',
-    linkHover: '#79c0ff',
-    linkVisited: '#a371f7',
-    codeBackground: '#161b22',
-    codeText: '#c9d1d9',
-    codeKeyword: '#ff7b72',
-    codeString: '#a5d6ff',
-    codeComment: '#8b949e',
-    codeFunction: '#d2a8ff',
-    border: '#30363d',
-    borderLight: '#21262d',
-    borderHeavy: '#6e7681',
-    selection: 'rgba(88, 166, 255, 0.2)',
-    highlight: 'rgba(187, 128, 9, 0.3)',
-    shadow: 'rgba(0, 0, 0, 0.4)',
-    success: '#3fb950',
-    warning: '#d29922',
-    error: '#f85149',
-    info: '#58a6ff',
-    commentHighlight: 'rgba(255, 183, 77, 0.25)',
-    commentHighlightResolved: 'rgba(255, 183, 77, 0.08)',
-    commentCardBg: '#161b22',
-  },
-
-  typography: {
-    fontFamily:
-      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"',
-    codeFontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    baseFontSize: '16px',
-    baseLineHeight: 1.5,
-    h1Size: '2em',
-    h2Size: '1.5em',
-    h3Size: '1.25em',
-    h4Size: '1em',
-    h5Size: '0.875em',
-    h6Size: '0.85em',
-    fontWeightNormal: 400,
-    fontWeightBold: 600,
-    headingFontWeight: 600,
-  },
-
-  spacing: {
-    blockMargin: '16px 0',
-    paragraphMargin: '16px 0',
-    listItemMargin: '4px 0',
-    headingMargin: '24px 0 16px 0',
-    codeBlockPadding: '16px',
-    tableCellPadding: '6px 13px',
-  },
-
-  syntaxTheme: 'github-dark',
-
-  mermaidTheme: {
-    theme: 'dark',
-    themeVariables: {
-      primaryColor: '#58a6ff',
-      primaryTextColor: '#0d1117',
-      primaryBorderColor: '#58a6ff',
-      lineColor: '#c9d1d9',
-      secondaryColor: '#161b22',
-      tertiaryColor: '#21262d',
-      background: '#0d1117',
-      mainBkg: '#161b22',
-      secondaryBkg: '#21262d',
-      tertiaryBkg: '#0d1117',
-      textColor: '#c9d1d9',
-      tertiaryTextColor: '#c9d1d9',
-      nodeBkg: '#161b22',
-      nodeBorder: '#30363d',
-      clusterBkg: '#21262d',
-      clusterBorder: '#30363d',
-      defaultLinkColor: '#58a6ff',
-      titleColor: '#c9d1d9',
-      edgeLabelBackground: '#0d1117',
-      // ER diagram specific
-      relationLabelColor: '#c9d1d9',
-      relationLabelBackground: '#0d1117',
-      attributeBackgroundColorOdd: '#161b22',
-      attributeBackgroundColorEven: '#21262d',
-      actorBorder: '#30363d',
-      actorBkg: '#161b22',
-      actorTextColor: '#c9d1d9',
-      actorLineColor: '#30363d',
-      signalColor: '#c9d1d9',
-      signalTextColor: '#0d1117',
-      labelBoxBkgColor: '#161b22',
-      labelBoxBorderColor: '#30363d',
-      labelTextColor: '#c9d1d9',
-      loopTextColor: '#c9d1d9',
-      noteBorderColor: '#30363d',
-      noteBkgColor: 'rgba(187, 128, 9, 0.3)',
-      noteTextColor: '#c9d1d9',
-      activationBorderColor: '#30363d',
-      activationBkgColor: '#21262d',
-      sequenceNumberColor: '#0d1117',
-    },
-  },
-};
-
-export default githubDark;
+export { default } from '../../packages/core/src/themes/github-dark';
diff --git a/src/themes/github-light.ts b/src/themes/github-light.ts
index 5a79ae0..aaf8959 100644
--- a/src/themes/github-light.ts
+++ b/src/themes/github-light.ts
@@ -1,126 +1 @@
-/**
- * GitHub Light Theme
- * Based on GitHub's markdown styles
- */
-
-import type { Theme } from '../types';
-
-const githubLight: Theme = {
-  name: 'github-light',
-  displayName: 'GitHub Light',
-  variant: 'light',
-  author: 'GitHub',
-  version: '1.0.0',
-
-  colors: {
-    background: '#ffffff',
-    backgroundSecondary: '#f6f8fa',
-    backgroundTertiary: '#eaeef2',
-    foreground: '#24292f',
-    foregroundSecondary: '#57606a',
-    foregroundMuted: '#6e7781',
-    primary: '#0969da',
-    secondary: '#6e7781',
-    accent: '#0969da',
-    heading: '#1f2328',
-    link: '#0969da',
-    linkHover: '#0550ae',
-    linkVisited: '#8250df',
-    codeBackground: '#f6f8fa',
-    codeText: '#24292f',
-    codeKeyword: '#cf222e',
-    codeString: '#0a3069',
-    codeComment: '#6e7781',
-    codeFunction: '#8250df',
-    border: '#d0d7de',
-    borderLight: '#d8dee4',
-    borderHeavy: '#8c959f',
-    selection: 'rgba(9, 105, 218, 0.2)',
-    highlight: '#fff8c5',
-    shadow: 'rgba(0, 0, 0, 0.1)',
-    success: '#1a7f37',
-    warning: '#9a6700',
-    error: '#cf222e',
-    info: '#0969da',
-    commentHighlight: 'rgba(255, 212, 59, 0.3)',
-    commentHighlightResolved: 'rgba(255, 212, 59, 0.1)',
-    commentCardBg: '#f6f8fa',
-  },
-
-  typography: {
-    fontFamily:
-      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"',
-    codeFontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    baseFontSize: '16px',
-    baseLineHeight: 1.5,
-    h1Size: '2em',
-    h2Size: '1.5em',
-    h3Size: '1.25em',
-    h4Size: '1em',
-    h5Size: '0.875em',
-    h6Size: '0.85em',
-    fontWeightNormal: 400,
-    fontWeightBold: 600,
-    headingFontWeight: 600,
-  },
-
-  spacing: {
-    blockMargin: '16px 0',
-    paragraphMargin: '16px 0',
-    listItemMargin: '4px 0',
-    headingMargin: '24px 0 16px 0',
-    codeBlockPadding: '16px',
-    tableCellPadding: '6px 13px',
-  },
-
-  syntaxTheme: 'github',
-
-  mermaidTheme: {
-    theme: 'base',
-    themeVariables: {
-      primaryColor: '#0969da',
-      primaryTextColor: '#000000',
-      primaryBorderColor: '#0969da',
-      lineColor: '#24292f',
-      secondaryColor: '#f6f8fa',
-      tertiaryColor: '#eaeef2',
-      background: '#ffffff',
-      mainBkg: '#f6f8fa',
-      secondaryBkg: '#eaeef2',
-      tertiaryBkg: '#ffffff',
-      textColor: '#24292f',
-      tertiaryTextColor: '#24292f',
-      nodeBkg: '#f6f8fa',
-      nodeBorder: '#d0d7de',
-      clusterBkg: '#eaeef2',
-      clusterBorder: '#d0d7de',
-      defaultLinkColor: '#0969da',
-      titleColor: '#1f2328',
-      edgeLabelBackground: '#ffffff',
-      // ER diagram specific
-      relationLabelColor: '#24292f',
-      relationLabelBackground: '#ffffff',
-      attributeBackgroundColorOdd: '#f6f8fa',
-      attributeBackgroundColorEven: '#ffffff',
-      actorBorder: '#d0d7de',
-      actorBkg: '#f6f8fa',
-      actorTextColor: '#24292f',
-      actorLineColor: '#d0d7de',
-      signalColor: '#24292f',
-      signalTextColor: '#24292f',
-      labelBoxBkgColor: '#f6f8fa',
-      labelBoxBorderColor: '#d0d7de',
-      labelTextColor: '#24292f',
-      loopTextColor: '#24292f',
-      noteBorderColor: '#d0d7de',
-      noteBkgColor: '#fff8c5',
-      noteTextColor: '#24292f',
-      activationBorderColor: '#d0d7de',
-      activationBkgColor: '#eaeef2',
-      sequenceNumberColor: '#ffffff',
-    },
-  },
-};
-
-export default githubLight;
+export { default } from '../../packages/core/src/themes/github-light';
diff --git a/src/themes/monokai-pro.ts b/src/themes/monokai-pro.ts
index bb2c5c9..d56cfe2 100644
--- a/src/themes/monokai-pro.ts
+++ b/src/themes/monokai-pro.ts
@@ -1,110 +1 @@
-/**
- * Monokai Pro Theme
- * Enhanced version of Monokai with refined colors
- */
-
-import type { Theme } from '../types';
-
-const monokaiPro: Theme = {
-  name: 'monokai-pro',
-  displayName: 'Monokai Pro',
-  variant: 'dark',
-  author: 'Monokai',
-  version: '1.0.0',
-
-  colors: {
-    background: '#2d2a2e',
-    backgroundSecondary: '#403e41',
-    backgroundTertiary: '#5b595c',
-    foreground: '#fcfcfa',
-    foregroundSecondary: '#d9d9d7',
-    foregroundMuted: '#939293',
-    primary: '#78dce8',
-    secondary: '#a9dc76',
-    accent: '#ab9df2',
-    heading: '#fcfcfa',
-    link: '#78dce8',
-    linkHover: '#a9dc76',
-    linkVisited: '#ab9df2',
-    codeBackground: '#403e41',
-    codeText: '#fcfcfa',
-    codeKeyword: '#ff6188',
-    codeString: '#ffd866',
-    codeComment: '#727072',
-    codeFunction: '#a9dc76',
-    border: '#5b595c',
-    borderLight: '#6e6c6f',
-    borderHeavy: '#939293',
-    selection: 'rgba(120, 220, 232, 0.2)',
-    highlight: '#ffd866',
-    shadow: 'rgba(0, 0, 0, 0.5)',
-    success: '#a9dc76',
-    warning: '#ffd866',
-    error: '#ff6188',
-    info: '#78dce8',
-    commentHighlight: 'rgba(255, 216, 102, 0.25)',
-    commentHighlightResolved: 'rgba(255, 216, 102, 0.08)',
-    commentCardBg: '#363537',
-  },
-
-  typography: {
-    fontFamily:
-      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
-    codeFontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    baseFontSize: '16px',
-    baseLineHeight: 1.5,
-    h1Size: '2em',
-    h2Size: '1.5em',
-    h3Size: '1.25em',
-    h4Size: '1em',
-    h5Size: '0.875em',
-    h6Size: '0.85em',
-    fontWeightNormal: 400,
-    fontWeightBold: 600,
-    headingFontWeight: 600,
-  },
-
-  spacing: {
-    blockMargin: '16px 0',
-    paragraphMargin: '16px 0',
-    listItemMargin: '4px 0',
-    headingMargin: '24px 0 16px 0',
-    codeBlockPadding: '16px',
-    tableCellPadding: '6px 13px',
-  },
-
-  syntaxTheme: 'monokai',
-
-  mermaidTheme: {
-    theme: 'dark',
-    themeVariables: {
-      primaryColor: '#78dce8',
-      primaryTextColor: '#2d2a2e',
-      primaryBorderColor: '#78dce8',
-      lineColor: '#fcfcfa',
-      secondaryColor: '#403e41',
-      tertiaryColor: '#5b595c',
-      background: '#2d2a2e',
-      mainBkg: '#403e41',
-      secondaryBkg: '#5b595c',
-      tertiaryBkg: '#2d2a2e',
-      textColor: '#fcfcfa',
-      tertiaryTextColor: '#fcfcfa',
-      nodeBkg: '#403e41',
-      nodeBorder: '#5b595c',
-      clusterBkg: '#5b595c',
-      clusterBorder: '#5b595c',
-      defaultLinkColor: '#78dce8',
-      titleColor: '#fcfcfa',
-      edgeLabelBackground: '#2d2a2e',
-      // ER diagram specific
-      relationLabelColor: '#fcfcfa',
-      relationLabelBackground: '#2d2a2e',
-      attributeBackgroundColorOdd: '#403e41',
-      attributeBackgroundColorEven: '#5b595c',
-    },
-  },
-};
-
-export default monokaiPro;
+export { default } from '../../packages/core/src/themes/monokai-pro';
diff --git a/src/themes/monokai.ts b/src/themes/monokai.ts
index d770edb..2cf4e24 100644
--- a/src/themes/monokai.ts
+++ b/src/themes/monokai.ts
@@ -1,110 +1 @@
-/**
- * Monokai Theme
- * Classic Monokai color scheme
- */
-
-import type { Theme } from '../types';
-
-const monokai: Theme = {
-  name: 'monokai',
-  displayName: 'Monokai',
-  variant: 'dark',
-  author: 'Wimer Hazenberg',
-  version: '1.0.0',
-
-  colors: {
-    background: '#272822',
-    backgroundSecondary: '#3e3d32',
-    backgroundTertiary: '#49483e',
-    foreground: '#f8f8f2',
-    foregroundSecondary: '#cfcfc2',
-    foregroundMuted: '#75715e',
-    primary: '#66d9ef',
-    secondary: '#a1efe4',
-    accent: '#ae81ff',
-    heading: '#f8f8f2',
-    link: '#66d9ef',
-    linkHover: '#a1efe4',
-    linkVisited: '#ae81ff',
-    codeBackground: '#3e3d32',
-    codeText: '#f8f8f2',
-    codeKeyword: '#f92672',
-    codeString: '#e6db74',
-    codeComment: '#75715e',
-    codeFunction: '#a6e22e',
-    border: '#49483e',
-    borderLight: '#5e5d52',
-    borderHeavy: '#75715e',
-    selection: 'rgba(102, 217, 239, 0.2)',
-    highlight: '#e6db74',
-    shadow: 'rgba(0, 0, 0, 0.5)',
-    success: '#a6e22e',
-    warning: '#e6db74',
-    error: '#f92672',
-    info: '#66d9ef',
-    commentHighlight: 'rgba(230, 219, 116, 0.25)',
-    commentHighlightResolved: 'rgba(230, 219, 116, 0.08)',
-    commentCardBg: '#3e3d32',
-  },
-
-  typography: {
-    fontFamily:
-      '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
-    codeFontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
-    baseFontSize: '16px',
-    baseLineHeight: 1.5,
-    h1Size: '2em',
-    h2Size: '1.5em',
-    h3Size: '1.25em',
-    h4Size: '1em',
-    h5Size: '0.875em',
-    h6Size: '0.85em',
-    fontWeightNormal: 400,
-    fontWeightBold: 600,
-    headingFontWeight: 600,
-  },
-
-  spacing: {
-    blockMargin: '16px 0',
-    paragraphMargin: '16px 0',
-    listItemMargin: '4px 0',
-    headingMargin: '24px 0 16px 0',
-    codeBlockPadding: '16px',
-    tableCellPadding: '6px 13px',
-  },
-
-  syntaxTheme: 'monokai',
-
-  mermaidTheme: {
-    theme: 'dark',
-    themeVariables: {
-      primaryColor: '#66d9ef',
-      primaryTextColor: '#272822',
-      primaryBorderColor: '#66d9ef',
-      lineColor: '#f8f8f2',
-      secondaryColor: '#3e3d32',
-      tertiaryColor: '#49483e',
-      background: '#272822',
-      mainBkg: '#3e3d32',
-      secondaryBkg: '#49483e',
-      tertiaryBkg: '#272822',
-      textColor: '#f8f8f2',
-      tertiaryTextColor: '#f8f8f2',
-      nodeBkg: '#3e3d32',
-      nodeBorder: '#49483e',
-      clusterBkg: '#49483e',
-      clusterBorder: '#49483e',
-      defaultLinkColor: '#66d9ef',
-      titleColor: '#f8f8f2',
-      edgeLabelBackground: '#272822',
-      // ER diagram specific
-      relationLabelColor: '#f8f8f2',
-      relationLabelBackground: '#272822',
-      attributeBackgroundColorOdd: '#3e3d32',
-      attributeBackgroundColorEven: '#49483e',
-    },
-  },
-};
-
-export default monokai;
+export { default } from '../../packages/core/src/themes/monokai';

From a96ec9452f840b31b2997b8f2e6221580a5b2664 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:18:09 -0400
Subject: [PATCH 06/26] refactor(core): move pure utility modules to
 @mdview/core

---
 packages/core/src/__tests__/utils.test.ts     | 183 ++++++++++++++++++
 packages/core/src/utils/filename-generator.ts |  88 +++++++++
 packages/core/src/utils/section-splitter.ts   | 178 +++++++++++++++++
 packages/core/src/utils/toc-stripper.ts       | 163 ++++++++++++++++
 src/utils/filename-generator.ts               |  90 +--------
 src/utils/section-splitter.ts                 | 179 +----------------
 src/utils/toc-stripper.ts                     | 145 +-------------
 7 files changed, 621 insertions(+), 405 deletions(-)
 create mode 100644 packages/core/src/__tests__/utils.test.ts
 create mode 100644 packages/core/src/utils/filename-generator.ts
 create mode 100644 packages/core/src/utils/section-splitter.ts
 create mode 100644 packages/core/src/utils/toc-stripper.ts

diff --git a/packages/core/src/__tests__/utils.test.ts b/packages/core/src/__tests__/utils.test.ts
new file mode 100644
index 0000000..75665b1
--- /dev/null
+++ b/packages/core/src/__tests__/utils.test.ts
@@ -0,0 +1,183 @@
+import {
+  splitIntoSections,
+  splitIntoChunks,
+  getInitialSections,
+  type MarkdownSection,
+} from '../utils/section-splitter';
+import { FilenameGenerator } from '../utils/filename-generator';
+import { stripTableOfContents } from '../utils/toc-stripper';
+
+describe('section-splitter', () => {
+  describe('splitIntoSections', () => {
+    it('should split markdown by headings', () => {
+      const md = '# Heading 1\nContent 1\n## Heading 2\nContent 2';
+      const sections = splitIntoSections(md);
+      expect(sections).toHaveLength(2);
+      expect(sections[0].heading).toBe('Heading 1');
+      expect(sections[1].heading).toBe('Heading 2');
+    });
+
+    it('should return a single section for markdown without headings', () => {
+      const md = 'Just some text\nwith multiple lines';
+      const sections = splitIntoSections(md);
+      expect(sections).toHaveLength(1);
+      expect(sections[0].heading).toBeUndefined();
+    });
+
+    it('should not split on headings inside code fences', () => {
+      const md = '# Real Heading\n```\n# Not a heading\n```\nMore content';
+      const sections = splitIntoSections(md);
+      expect(sections).toHaveLength(1);
+      expect(sections[0].heading).toBe('Real Heading');
+    });
+
+    it('should assign sequential section IDs', () => {
+      const md = '# A\ntext\n## B\ntext\n### C\ntext';
+      const sections = splitIntoSections(md);
+      expect(sections.map((s) => s.id)).toEqual(['section-0', 'section-1', 'section-2']);
+    });
+
+    it('should track line numbers', () => {
+      const md = '# First\nline 1\nline 2\n## Second\nline 3';
+      const sections = splitIntoSections(md);
+      expect(sections[0].startLine).toBe(0);
+      expect(sections[0].endLine).toBe(2);
+      expect(sections[1].startLine).toBe(3);
+      expect(sections[1].endLine).toBe(4);
+    });
+  });
+
+  describe('splitIntoChunks', () => {
+    it('should split large content into chunks', () => {
+      const line = 'x'.repeat(100) + '\n';
+      const md = line.repeat(100);
+      const sections = splitIntoChunks(md, 500);
+      expect(sections.length).toBeGreaterThan(1);
+      sections.forEach((s) => {
+        expect(s.id).toMatch(/^chunk-\d+$/);
+      });
+    });
+
+    it('should return single chunk for small content', () => {
+      const md = 'small text';
+      const sections = splitIntoChunks(md);
+      expect(sections).toHaveLength(1);
+    });
+  });
+
+  describe('getInitialSections', () => {
+    const makeSections = (count: number): MarkdownSection[] =>
+      Array.from({ length: count }, (_, i) => ({
+        markdown: `Section ${i}`,
+        startLine: i * 2,
+        endLine: i * 2 + 1,
+        heading: `Heading ${i}`,
+        level: 1,
+        id: `section-${i}`,
+      }));
+
+    it('should return up to maxSections sections', () => {
+      const sections = makeSections(10);
+      const initial = getInitialSections(sections, { maxSections: 2 });
+      expect(initial).toHaveLength(2);
+    });
+
+    it('should return at least one section even if maxSize is very small', () => {
+      const sections = makeSections(5);
+      const initial = getInitialSections(sections, { maxSize: 1 });
+      expect(initial).toHaveLength(1);
+    });
+
+    it('should return sections up to a specific ID', () => {
+      const sections = makeSections(5);
+      const initial = getInitialSections(sections, { upToSectionId: 'section-2' });
+      // Should include sections 0, 1, 2 plus one more for context
+      expect(initial).toHaveLength(4);
+    });
+  });
+});
+
+describe('filename-generator', () => {
+  it('should generate a filename with default template', () => {
+    const result = FilenameGenerator.generate({ title: 'My Document', extension: 'pdf' });
+    expect(result).toBe('my-document.pdf');
+  });
+
+  it('should sanitize illegal characters', () => {
+    const result = FilenameGenerator.generate({ title: 'file<>:"/\\|?*name', extension: 'txt' });
+    expect(result).toBe('filename.txt');
+  });
+
+  it('should handle empty title', () => {
+    const result = FilenameGenerator.generate({ title: '', extension: 'docx' });
+    expect(result).toBe('document.docx');
+  });
+
+  it('should use a custom template with date vars', () => {
+    const result = FilenameGenerator.generate({
+      title: 'Report',
+      extension: 'pdf',
+      template: '{title}-{year}',
+    });
+    const year = new Date().getFullYear();
+    expect(result).toBe(`report-${year}.pdf`);
+  });
+
+  it('should truncate overly long filenames', () => {
+    const longTitle = 'a'.repeat(300);
+    const result = FilenameGenerator.generate({ title: longTitle, extension: 'pdf' });
+    // 200 char max + '.pdf' = 204
+    expect(result.length).toBeLessThanOrEqual(204);
+  });
+});
+
+describe('toc-stripper', () => {
+  it('should return original markdown when no TOC is found', () => {
+    const md = '# Hello\nSome content';
+    const result = stripTableOfContents(md);
+    expect(result.tocFound).toBe(false);
+    expect(result.markdown).toBe(md);
+  });
+
+  it('should strip a TOC section with anchor links', () => {
+    const md = [
+      '# My Doc',
+      '',
+      '## Table of Contents',
+      '- [Section 1](#section-1)',
+      '- [Section 2](#section-2)',
+      '- [Section 3](#section-3)',
+      '',
+      '## Section 1',
+      'Content 1',
+    ].join('\n');
+    const result = stripTableOfContents(md);
+    expect(result.tocFound).toBe(true);
+    expect(result.markdown).not.toContain('Table of Contents');
+    expect(result.markdown).toContain('Section 1');
+    expect(result.markdown).toContain('Content 1');
+  });
+
+  it('should not strip a heading named Contents without anchor links', () => {
+    const md = [
+      '## Contents',
+      'This is just regular content, not a TOC.',
+      '',
+      '## Other',
+      'More content',
+    ].join('\n');
+    const result = stripTableOfContents(md);
+    expect(result.tocFound).toBe(false);
+  });
+
+  it('should accept an optional logger', () => {
+    const logs: string[] = [];
+    const logger = {
+      debug: (_ctx: string, msg: string) => logs.push(msg),
+      info: (_ctx: string, msg: string) => logs.push(msg),
+    };
+    const md = '# Doc\nNo TOC here';
+    stripTableOfContents(md, logger);
+    expect(logs.length).toBeGreaterThan(0);
+  });
+});
diff --git a/packages/core/src/utils/filename-generator.ts b/packages/core/src/utils/filename-generator.ts
new file mode 100644
index 0000000..b307646
--- /dev/null
+++ b/packages/core/src/utils/filename-generator.ts
@@ -0,0 +1,88 @@
+/**
+ * Filename Generator
+ * Generates filenames from templates with variable substitution
+ */
+
+export interface FilenameGeneratorOptions {
+  title: string;
+  extension: string;
+  template?: string;
+}
+
+export class FilenameGenerator {
+  private static readonly DEFAULT_TEMPLATE = '{title}';
+  private static readonly MAX_FILENAME_LENGTH = 200;
+
+  /**
+   * Generate a filename from a template
+   */
+  static generate(options: FilenameGeneratorOptions): string {
+    const { title, extension, template = this.DEFAULT_TEMPLATE } = options;
+
+    const vars: Record<string, string> = {
+      '{title}': this.sanitizeFilename(title || 'document'),
+      ...this.getDateVars(),
+    };
+
+    let filename = this.parseTemplate(template, vars);
+
+    // Sanitize the final filename (remove any remaining illegal chars, lowercase)
+    filename = filename
+      .replace(/[<>:"/\\|?*]/g, '')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '')
+      .toLowerCase();
+
+    // Ensure filename doesn't exceed max length
+    if (filename.length > this.MAX_FILENAME_LENGTH) {
+      filename = filename.substring(0, this.MAX_FILENAME_LENGTH);
+    }
+
+    return `${filename}.${extension}`;
+  }
+
+  /**
+   * Sanitize filename by removing illegal characters
+   */
+  private static sanitizeFilename(name: string): string {
+    return (
+      name
+        .replace(/[<>:"/\\|?*]/g, '') // Remove illegal chars
+        .replace(/\s+/g, '-') // Replace spaces with dashes
+        .replace(/-+/g, '-') // Collapse multiple dashes
+        .replace(/^-|-$/g, '') // Trim leading/trailing dashes
+        .toLowerCase()
+    );
+  }
+
+  /**
+   * Parse template by replacing variables
+   */
+  private static parseTemplate(template: string, vars: Record<string, string>): string {
+    let result = template;
+
+    // Replace all variables in the template
+    for (const [key, value] of Object.entries(vars)) {
+      result = result.replace(new RegExp(key.replace(/[{}]/g, '\\$&'), 'g'), value);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get date-related template variables
+   */
+  private static getDateVars(): Record<string, string> {
+    const now = new Date();
+    const pad = (n: number) => n.toString().padStart(2, '0');
+
+    return {
+      '{date}': `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`,
+      '{datetime}': `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}_${pad(now.getHours())}-${pad(now.getMinutes())}`,
+      '{timestamp}': now.getTime().toString(),
+      '{year}': now.getFullYear().toString(),
+      '{month}': pad(now.getMonth() + 1),
+      '{day}': pad(now.getDate()),
+    };
+  }
+}
diff --git a/packages/core/src/utils/section-splitter.ts b/packages/core/src/utils/section-splitter.ts
new file mode 100644
index 0000000..a301192
--- /dev/null
+++ b/packages/core/src/utils/section-splitter.ts
@@ -0,0 +1,178 @@
+/**
+ * Section Splitter
+ * Splits markdown into logical sections for lazy rendering
+ */
+
+export interface MarkdownSection {
+  markdown: string;
+  startLine: number;
+  endLine: number;
+  heading?: string;
+  level?: number;
+  id: string;
+}
+
+/**
+ * Split markdown into sections by headings
+ * Each section includes the heading and all content until the next heading
+ */
+export function splitIntoSections(markdown: string): MarkdownSection[] {
+  const lines = markdown.split('\n');
+  const sections: MarkdownSection[] = [];
+
+  let currentSection: string[] = [];
+  let currentHeading: string | undefined;
+  let currentLevel: number | undefined;
+  let sectionStartLine = 0;
+  let sectionId = 0;
+
+  // Track fenced code block state
+  let inCodeFence = false;
+  let codeFenceChar = ''; // '`' or '~'
+  let codeFenceLength = 0; // minimum 3
+
+  lines.forEach((line, index) => {
+    // Check for code fence start/end (``` or ~~~)
+    const fenceMatch = line.match(/^(`{3,}|~{3,})/);
+
+    if (fenceMatch) {
+      const fenceStr = fenceMatch[1];
+      const fenceChar = fenceStr[0];
+      const fenceLen = fenceStr.length;
+
+      if (!inCodeFence) {
+        // Starting a code fence
+        inCodeFence = true;
+        codeFenceChar = fenceChar;
+        codeFenceLength = fenceLen;
+      } else if (fenceChar === codeFenceChar && fenceLen >= codeFenceLength) {
+        // Closing the code fence (must use same char and >= length)
+        inCodeFence = false;
+        codeFenceChar = '';
+        codeFenceLength = 0;
+      }
+      // If different fence char or shorter length, it's content inside the fence
+    }
+
+    // Only check for headings when NOT inside a code fence
+    const headingMatch = !inCodeFence && line.match(/^(#{1,6})\s+(.+)$/);
+
+    if (headingMatch) {
+      // Save previous section if it exists
+      if (currentSection.length > 0) {
+        sections.push({
+          markdown: currentSection.join('\n'),
+          startLine: sectionStartLine,
+          endLine: index - 1,
+          heading: currentHeading,
+          level: currentLevel,
+          id: `section-${sectionId++}`,
+        });
+      }
+
+      // Start new section
+      currentSection = [line];
+      currentHeading = headingMatch[2];
+      currentLevel = headingMatch[1].length;
+      sectionStartLine = index;
+    } else {
+      currentSection.push(line);
+    }
+  });
+
+  // Add final section
+  if (currentSection.length > 0) {
+    sections.push({
+      markdown: currentSection.join('\n'),
+      startLine: sectionStartLine,
+      endLine: lines.length - 1,
+      heading: currentHeading,
+      level: currentLevel,
+      id: `section-${sectionId++}`,
+    });
+  }
+
+  return sections;
+}
+
+/**
+ * Split markdown into chunks by size (for very large files without headings)
+ */
+export function splitIntoChunks(markdown: string, chunkSize = 50000): MarkdownSection[] {
+  const sections: MarkdownSection[] = [];
+  const lines = markdown.split('\n');
+
+  let currentChunk: string[] = [];
+  let currentSize = 0;
+  let chunkStartLine = 0;
+  let chunkId = 0;
+
+  lines.forEach((line, index) => {
+    currentChunk.push(line);
+    currentSize += line.length + 1; // +1 for newline
+
+    // If chunk is large enough, save it
+    if (currentSize >= chunkSize) {
+      sections.push({
+        markdown: currentChunk.join('\n'),
+        startLine: chunkStartLine,
+        endLine: index,
+        id: `chunk-${chunkId++}`,
+      });
+
+      currentChunk = [];
+      currentSize = 0;
+      chunkStartLine = index + 1;
+    }
+  });
+
+  // Add remaining lines
+  if (currentChunk.length > 0) {
+    sections.push({
+      markdown: currentChunk.join('\n'),
+      startLine: chunkStartLine,
+      endLine: lines.length - 1,
+      id: `chunk-${chunkId++}`,
+    });
+  }
+
+  return sections;
+}
+
+/**
+ * Get initial sections to render (above the fold)
+ */
+export function getInitialSections(
+  sections: MarkdownSection[],
+  options: { maxSections?: number; maxSize?: number; upToSectionId?: string } = {}
+): MarkdownSection[] {
+  const { maxSections = 3, maxSize = 30000, upToSectionId } = options;
+
+  // If we need to render up to a specific section (for scroll restoration),
+  // render all sections up to and including that one
+  if (upToSectionId) {
+    const targetIndex = sections.findIndex((s) => s.id === upToSectionId);
+    if (targetIndex !== -1) {
+      // Render all sections up to the target, plus one more for context
+      return sections.slice(0, Math.min(targetIndex + 2, sections.length));
+    }
+  }
+
+  const initial: MarkdownSection[] = [];
+  let totalSize = 0;
+
+  for (const section of sections) {
+    if (initial.length >= maxSections) break;
+    if (totalSize + section.markdown.length > maxSize) break;
+
+    initial.push(section);
+    totalSize += section.markdown.length;
+  }
+
+  // Always include at least one section
+  if (initial.length === 0 && sections.length > 0) {
+    initial.push(sections[0]);
+  }
+
+  return initial;
+}
diff --git a/packages/core/src/utils/toc-stripper.ts b/packages/core/src/utils/toc-stripper.ts
new file mode 100644
index 0000000..f317cdc
--- /dev/null
+++ b/packages/core/src/utils/toc-stripper.ts
@@ -0,0 +1,163 @@
+/**
+ * TOC Stripper
+ * Detects and removes Table of Contents sections from markdown
+ */
+
+export interface TocStripResult {
+  markdown: string;
+  tocFound: boolean;
+  tocRange?: { start: number; end: number };
+}
+
+/**
+ * Optional logger interface for debug output.
+ * When not provided, logging is silently skipped.
+ */
+export interface TocStripperLogger {
+  debug(context: string, ...args: unknown[]): void;
+  info(context: string, ...args: unknown[]): void;
+}
+
+const noopLogger: TocStripperLogger = {
+  debug: () => {},
+  info: () => {},
+};
+
+/**
+ * Strip Table of Contents sections from markdown when custom TOC is enabled
+ * Detects common TOC patterns:
+ * - Headings like "Table of Contents", "Contents", "TOC"
+ * - Followed by list items with anchor links
+ *
+ * @param markdown - The markdown content to strip TOC from
+ * @param logger - Optional logger for debug output (defaults to no-op)
+ */
+export function stripTableOfContents(
+  markdown: string,
+  logger: TocStripperLogger = noopLogger
+): TocStripResult {
+  const lines = markdown.split('\n');
+  const tocRanges: Array<{ start: number; end: number }> = [];
+
+  // Pattern to match TOC headings (case-insensitive)
+  const tocHeadingPattern = /^#{1,6}\s+(table of contents|contents|toc)\s*$/i;
+
+  // Pattern to match list items (with or without anchor links)
+  const listItemPattern = /^\s*[-*+]\s+/;
+  const orderedListPattern = /^\s*\d+\.\s+/;
+  const anchorLinkPattern = /\[.*?\]\(#.*?\)/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Check if this line is a TOC heading
+    if (tocHeadingPattern.test(line.trim())) {
+      logger.debug('TocStripper', `Found TOC heading at line ${i}: "${line}"`);
+
+      const tocStart = i;
+      let tocEnd = i;
+      let anchorLinkCount = 0;
+      let consecutiveNonListLines = 0;
+
+      // Scan forward to find the extent of the TOC
+      for (let j = i + 1; j < lines.length; j++) {
+        const currentLine = lines[j];
+        const trimmedLine = currentLine.trim();
+
+        // Stop at the next heading
+        if (/^#{1,6}\s+/.test(trimmedLine)) {
+          logger.debug('TocStripper', `TOC ends at line ${j - 1} (next heading found)`);
+          break;
+        }
+
+        // Check if this is a list item
+        const isListItem =
+          listItemPattern.test(currentLine) || orderedListPattern.test(currentLine);
+
+        if (isListItem) {
+          tocEnd = j;
+          consecutiveNonListLines = 0;
+
+          // Count anchor links to confirm this is a TOC
+          if (anchorLinkPattern.test(currentLine)) {
+            anchorLinkCount++;
+          }
+        } else if (trimmedLine === '') {
+          // Empty lines are okay within TOC, but track consecutive ones
+          consecutiveNonListLines++;
+
+          // If we have multiple consecutive blank lines, stop
+          if (consecutiveNonListLines > 2) {
+            logger.debug(
+              'TocStripper',
+              `TOC ends at line ${tocEnd} (multiple blank lines after list)`
+            );
+            break;
+          }
+        } else {
+          // Non-list, non-empty line - TOC has ended
+          logger.debug('TocStripper', `TOC ends at line ${tocEnd} (non-list content found)`);
+          break;
+        }
+      }
+
+      // Only consider it a TOC if we found list items with anchor links
+      // OR if we found ordered/unordered lists right after the heading
+      const hasListItems = tocEnd > tocStart;
+      const likelyToc = anchorLinkCount >= 2 || (hasListItems && anchorLinkCount >= 1);
+
+      if (likelyToc) {
+        logger.info(
+          'TocStripper',
+          `Confirmed TOC from line ${tocStart} to ${tocEnd} (${anchorLinkCount} anchor links)`
+        );
+        tocRanges.push({ start: tocStart, end: tocEnd });
+        // Skip ahead to avoid re-processing
+        i = tocEnd;
+      } else {
+        logger.debug(
+          'TocStripper',
+          `Skipping potential TOC at line ${tocStart} (insufficient anchor links: ${anchorLinkCount})`
+        );
+      }
+    }
+  }
+
+  // If no TOC found, return original markdown
+  if (tocRanges.length === 0) {
+    logger.debug('TocStripper', 'No TOC found in markdown');
+    return {
+      markdown,
+      tocFound: false,
+    };
+  }
+
+  // Remove TOC ranges (in reverse order to preserve line numbers)
+  const strippedLines = [...lines];
+  for (let i = tocRanges.length - 1; i >= 0; i--) {
+    const range = tocRanges[i];
+    // Remove lines from start to end (inclusive)
+    strippedLines.splice(range.start, range.end - range.start + 1);
+
+    // Clean up excess blank lines after removal
+    // Remove consecutive blank lines at the splice point
+    while (
+      range.start < strippedLines.length &&
+      range.start > 0 &&
+      strippedLines[range.start]?.trim() === '' &&
+      strippedLines[range.start - 1]?.trim() === ''
+    ) {
+      strippedLines.splice(range.start, 1);
+    }
+  }
+
+  const strippedMarkdown = strippedLines.join('\n');
+
+  logger.info('TocStripper', `Stripped ${tocRanges.length} TOC section(s) from markdown`);
+
+  return {
+    markdown: strippedMarkdown,
+    tocFound: true,
+    tocRange: tocRanges[0], // Return first TOC range for reference
+  };
+}
diff --git a/src/utils/filename-generator.ts b/src/utils/filename-generator.ts
index caccb9f..a33afba 100644
--- a/src/utils/filename-generator.ts
+++ b/src/utils/filename-generator.ts
@@ -1,89 +1 @@
-/**
- * Filename Generator
- * Generates filenames from templates with variable substitution
- */
-
-export interface FilenameGeneratorOptions {
-  title: string;
-  extension: string;
-  template?: string;
-}
-
-export class FilenameGenerator {
-  private static readonly DEFAULT_TEMPLATE = '{title}';
-  private static readonly MAX_FILENAME_LENGTH = 200;
-
-  /**
-   * Generate a filename from a template
-   */
-  static generate(options: FilenameGeneratorOptions): string {
-    const { title, extension, template = this.DEFAULT_TEMPLATE } = options;
-
-    const vars: Record<string, string> = {
-      '{title}': this.sanitizeFilename(title || 'document'),
-      ...this.getDateVars(),
-    };
-
-    let filename = this.parseTemplate(template, vars);
-
-    // Sanitize the final filename (remove any remaining illegal chars, lowercase)
-    filename = filename
-      .replace(/[<>:"/\\|?*]/g, '')
-      .replace(/-+/g, '-')
-      .replace(/^-|-$/g, '')
-      .toLowerCase();
-
-    // Ensure filename doesn't exceed max length
-    if (filename.length > this.MAX_FILENAME_LENGTH) {
-      filename = filename.substring(0, this.MAX_FILENAME_LENGTH);
-    }
-
-    return `${filename}.${extension}`;
-  }
-
-  /**
-   * Sanitize filename by removing illegal characters
-   */
-  private static sanitizeFilename(name: string): string {
-    return (
-      name
-        .replace(/[<>:"/\\|?*]/g, '') // Remove illegal chars
-        .replace(/\s+/g, '-') // Replace spaces with dashes
-        .replace(/-+/g, '-') // Collapse multiple dashes
-        .replace(/^-|-$/g, '') // Trim leading/trailing dashes
-        .toLowerCase()
-    );
-  }
-
-  /**
-   * Parse template by replacing variables
-   */
-  private static parseTemplate(template: string, vars: Record<string, string>): string {
-    let result = template;
-
-    // Replace all variables in the template
-    for (const [key, value] of Object.entries(vars)) {
-      result = result.replace(new RegExp(key.replace(/[{}]/g, '\\$&'), 'g'), value);
-    }
-
-    return result;
-  }
-
-  /**
-   * Get date-related template variables
-   */
-  private static getDateVars(): Record<string, string> {
-    const now = new Date();
-    const pad = (n: number) => n.toString().padStart(2, '0');
-
-    return {
-      '{date}': `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`,
-      '{datetime}': `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}_${pad(now.getHours())}-${pad(now.getMinutes())}`,
-      '{timestamp}': now.getTime().toString(),
-      '{year}': now.getFullYear().toString(),
-      '{month}': pad(now.getMonth() + 1),
-      '{day}': pad(now.getDate()),
-    };
-  }
-}
-
+export * from '../../packages/core/src/utils/filename-generator';
diff --git a/src/utils/section-splitter.ts b/src/utils/section-splitter.ts
index a301192..7fb20df 100644
--- a/src/utils/section-splitter.ts
+++ b/src/utils/section-splitter.ts
@@ -1,178 +1 @@
-/**
- * Section Splitter
- * Splits markdown into logical sections for lazy rendering
- */
-
-export interface MarkdownSection {
-  markdown: string;
-  startLine: number;
-  endLine: number;
-  heading?: string;
-  level?: number;
-  id: string;
-}
-
-/**
- * Split markdown into sections by headings
- * Each section includes the heading and all content until the next heading
- */
-export function splitIntoSections(markdown: string): MarkdownSection[] {
-  const lines = markdown.split('\n');
-  const sections: MarkdownSection[] = [];
-
-  let currentSection: string[] = [];
-  let currentHeading: string | undefined;
-  let currentLevel: number | undefined;
-  let sectionStartLine = 0;
-  let sectionId = 0;
-
-  // Track fenced code block state
-  let inCodeFence = false;
-  let codeFenceChar = ''; // '`' or '~'
-  let codeFenceLength = 0; // minimum 3
-
-  lines.forEach((line, index) => {
-    // Check for code fence start/end (``` or ~~~)
-    const fenceMatch = line.match(/^(`{3,}|~{3,})/);
-
-    if (fenceMatch) {
-      const fenceStr = fenceMatch[1];
-      const fenceChar = fenceStr[0];
-      const fenceLen = fenceStr.length;
-
-      if (!inCodeFence) {
-        // Starting a code fence
-        inCodeFence = true;
-        codeFenceChar = fenceChar;
-        codeFenceLength = fenceLen;
-      } else if (fenceChar === codeFenceChar && fenceLen >= codeFenceLength) {
-        // Closing the code fence (must use same char and >= length)
-        inCodeFence = false;
-        codeFenceChar = '';
-        codeFenceLength = 0;
-      }
-      // If different fence char or shorter length, it's content inside the fence
-    }
-
-    // Only check for headings when NOT inside a code fence
-    const headingMatch = !inCodeFence && line.match(/^(#{1,6})\s+(.+)$/);
-
-    if (headingMatch) {
-      // Save previous section if it exists
-      if (currentSection.length > 0) {
-        sections.push({
-          markdown: currentSection.join('\n'),
-          startLine: sectionStartLine,
-          endLine: index - 1,
-          heading: currentHeading,
-          level: currentLevel,
-          id: `section-${sectionId++}`,
-        });
-      }
-
-      // Start new section
-      currentSection = [line];
-      currentHeading = headingMatch[2];
-      currentLevel = headingMatch[1].length;
-      sectionStartLine = index;
-    } else {
-      currentSection.push(line);
-    }
-  });
-
-  // Add final section
-  if (currentSection.length > 0) {
-    sections.push({
-      markdown: currentSection.join('\n'),
-      startLine: sectionStartLine,
-      endLine: lines.length - 1,
-      heading: currentHeading,
-      level: currentLevel,
-      id: `section-${sectionId++}`,
-    });
-  }
-
-  return sections;
-}
-
-/**
- * Split markdown into chunks by size (for very large files without headings)
- */
-export function splitIntoChunks(markdown: string, chunkSize = 50000): MarkdownSection[] {
-  const sections: MarkdownSection[] = [];
-  const lines = markdown.split('\n');
-
-  let currentChunk: string[] = [];
-  let currentSize = 0;
-  let chunkStartLine = 0;
-  let chunkId = 0;
-
-  lines.forEach((line, index) => {
-    currentChunk.push(line);
-    currentSize += line.length + 1; // +1 for newline
-
-    // If chunk is large enough, save it
-    if (currentSize >= chunkSize) {
-      sections.push({
-        markdown: currentChunk.join('\n'),
-        startLine: chunkStartLine,
-        endLine: index,
-        id: `chunk-${chunkId++}`,
-      });
-
-      currentChunk = [];
-      currentSize = 0;
-      chunkStartLine = index + 1;
-    }
-  });
-
-  // Add remaining lines
-  if (currentChunk.length > 0) {
-    sections.push({
-      markdown: currentChunk.join('\n'),
-      startLine: chunkStartLine,
-      endLine: lines.length - 1,
-      id: `chunk-${chunkId++}`,
-    });
-  }
-
-  return sections;
-}
-
-/**
- * Get initial sections to render (above the fold)
- */
-export function getInitialSections(
-  sections: MarkdownSection[],
-  options: { maxSections?: number; maxSize?: number; upToSectionId?: string } = {}
-): MarkdownSection[] {
-  const { maxSections = 3, maxSize = 30000, upToSectionId } = options;
-
-  // If we need to render up to a specific section (for scroll restoration),
-  // render all sections up to and including that one
-  if (upToSectionId) {
-    const targetIndex = sections.findIndex((s) => s.id === upToSectionId);
-    if (targetIndex !== -1) {
-      // Render all sections up to the target, plus one more for context
-      return sections.slice(0, Math.min(targetIndex + 2, sections.length));
-    }
-  }
-
-  const initial: MarkdownSection[] = [];
-  let totalSize = 0;
-
-  for (const section of sections) {
-    if (initial.length >= maxSections) break;
-    if (totalSize + section.markdown.length > maxSize) break;
-
-    initial.push(section);
-    totalSize += section.markdown.length;
-  }
-
-  // Always include at least one section
-  if (initial.length === 0 && sections.length > 0) {
-    initial.push(sections[0]);
-  }
-
-  return initial;
-}
+export * from '../../packages/core/src/utils/section-splitter';
diff --git a/src/utils/toc-stripper.ts b/src/utils/toc-stripper.ts
index e2838d9..b0b315f 100644
--- a/src/utils/toc-stripper.ts
+++ b/src/utils/toc-stripper.ts
@@ -1,146 +1,15 @@
 /**
- * TOC Stripper
- * Detects and removes Table of Contents sections from markdown
+ * Re-export shim: delegates to @mdview/core and injects the Chrome extension logger.
  */
+export type { TocStripResult, TocStripperLogger } from '../../packages/core/src/utils/toc-stripper';
 
+import { stripTableOfContents as coreStripTableOfContents } from '../../packages/core/src/utils/toc-stripper';
 import { debug } from './debug-logger';
 
-export interface TocStripResult {
-  markdown: string;
-  tocFound: boolean;
-  tocRange?: { start: number; end: number };
-}
-
 /**
- * Strip Table of Contents sections from markdown when custom TOC is enabled
- * Detects common TOC patterns:
- * - Headings like "Table of Contents", "Contents", "TOC"
- * - Followed by list items with anchor links
+ * Strip Table of Contents sections from markdown.
+ * This wrapper injects the extension's debug logger into the core implementation.
  */
-export function stripTableOfContents(markdown: string): TocStripResult {
-  const lines = markdown.split('\n');
-  const tocRanges: Array<{ start: number; end: number }> = [];
-
-  // Pattern to match TOC headings (case-insensitive)
-  const tocHeadingPattern = /^#{1,6}\s+(table of contents|contents|toc)\s*$/i;
-
-  // Pattern to match list items (with or without anchor links)
-  const listItemPattern = /^\s*[-*+]\s+/;
-  const orderedListPattern = /^\s*\d+\.\s+/;
-  const anchorLinkPattern = /\[.*?\]\(#.*?\)/;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-
-    // Check if this line is a TOC heading
-    if (tocHeadingPattern.test(line.trim())) {
-      debug.debug('TocStripper', `Found TOC heading at line ${i}: "${line}"`);
-
-      const tocStart = i;
-      let tocEnd = i;
-      let anchorLinkCount = 0;
-      let consecutiveNonListLines = 0;
-
-      // Scan forward to find the extent of the TOC
-      for (let j = i + 1; j < lines.length; j++) {
-        const currentLine = lines[j];
-        const trimmedLine = currentLine.trim();
-
-        // Stop at the next heading
-        if (/^#{1,6}\s+/.test(trimmedLine)) {
-          debug.debug('TocStripper', `TOC ends at line ${j - 1} (next heading found)`);
-          break;
-        }
-
-        // Check if this is a list item
-        const isListItem =
-          listItemPattern.test(currentLine) || orderedListPattern.test(currentLine);
-
-        if (isListItem) {
-          tocEnd = j;
-          consecutiveNonListLines = 0;
-
-          // Count anchor links to confirm this is a TOC
-          if (anchorLinkPattern.test(currentLine)) {
-            anchorLinkCount++;
-          }
-        } else if (trimmedLine === '') {
-          // Empty lines are okay within TOC, but track consecutive ones
-          consecutiveNonListLines++;
-
-          // If we have multiple consecutive blank lines, stop
-          if (consecutiveNonListLines > 2) {
-            debug.debug(
-              'TocStripper',
-              `TOC ends at line ${tocEnd} (multiple blank lines after list)`
-            );
-            break;
-          }
-        } else {
-          // Non-list, non-empty line - TOC has ended
-          debug.debug('TocStripper', `TOC ends at line ${tocEnd} (non-list content found)`);
-          break;
-        }
-      }
-
-      // Only consider it a TOC if we found list items with anchor links
-      // OR if we found ordered/unordered lists right after the heading
-      const hasListItems = tocEnd > tocStart;
-      const likelyToc = anchorLinkCount >= 2 || (hasListItems && anchorLinkCount >= 1);
-
-      if (likelyToc) {
-        debug.info(
-          'TocStripper',
-          `Confirmed TOC from line ${tocStart} to ${tocEnd} (${anchorLinkCount} anchor links)`
-        );
-        tocRanges.push({ start: tocStart, end: tocEnd });
-        // Skip ahead to avoid re-processing
-        i = tocEnd;
-      } else {
-        debug.debug(
-          'TocStripper',
-          `Skipping potential TOC at line ${tocStart} (insufficient anchor links: ${anchorLinkCount})`
-        );
-      }
-    }
-  }
-
-  // If no TOC found, return original markdown
-  if (tocRanges.length === 0) {
-    debug.debug('TocStripper', 'No TOC found in markdown');
-    return {
-      markdown,
-      tocFound: false,
-    };
-  }
-
-  // Remove TOC ranges (in reverse order to preserve line numbers)
-  const strippedLines = [...lines];
-  for (let i = tocRanges.length - 1; i >= 0; i--) {
-    const range = tocRanges[i];
-    // Remove lines from start to end (inclusive)
-    strippedLines.splice(range.start, range.end - range.start + 1);
-
-    // Clean up excess blank lines after removal
-    // Remove consecutive blank lines at the splice point
-    while (
-      range.start < strippedLines.length &&
-      range.start > 0 &&
-      strippedLines[range.start]?.trim() === '' &&
-      strippedLines[range.start - 1]?.trim() === ''
-    ) {
-      strippedLines.splice(range.start, 1);
-    }
-  }
-
-  const strippedMarkdown = strippedLines.join('\n');
-
-  debug.info('TocStripper', `Stripped ${tocRanges.length} TOC section(s) from markdown`);
-
-  return {
-    markdown: strippedMarkdown,
-    tocFound: true,
-    tocRange: tocRanges[0], // Return first TOC range for reference
-  };
+export function stripTableOfContents(markdown: string) {
+  return coreStripTableOfContents(markdown, debug);
 }
-

From 8c6a3c9d4d83484fb233ad423451cdf92a1595d2 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:20:26 -0400
Subject: [PATCH 07/26] refactor(core): move markdown-converter, cache-manager,
 frontmatter to @mdview/core

---
 package-lock.json                             |  13 +-
 packages/core/package.json                    |  11 +
 packages/core/src/__tests__/converter.test.ts | 232 ++++++++++++
 packages/core/src/cache-manager.ts            | 239 ++++++++++++
 packages/core/src/frontmatter-extractor.ts    |  78 ++++
 packages/core/src/index.ts                    |  15 +
 packages/core/src/markdown-converter.ts       | 353 ++++++++++++++++++
 src/core/cache-manager.ts                     | 237 +-----------
 src/core/frontmatter-extractor.ts             |  81 +---
 src/core/markdown-converter.ts                | 353 +-----------------
 10 files changed, 949 insertions(+), 663 deletions(-)
 create mode 100644 packages/core/src/__tests__/converter.test.ts
 create mode 100644 packages/core/src/cache-manager.ts
 create mode 100644 packages/core/src/frontmatter-extractor.ts
 create mode 100644 packages/core/src/markdown-converter.ts

diff --git a/package-lock.json b/package-lock.json
index 74f53af..4d77690 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10234,7 +10234,18 @@
     "packages/core": {
       "name": "@mdview/core",
       "version": "0.0.1",
-      "license": "MIT"
+      "license": "MIT",
+      "dependencies": {
+        "markdown-it": "^14.1.0",
+        "markdown-it-anchor": "^8.6.7",
+        "markdown-it-attrs": "^4.1.6",
+        "markdown-it-emoji": "^3.0.0",
+        "markdown-it-footnote": "^4.0.0",
+        "markdown-it-task-lists": "^2.1.1"
+      },
+      "devDependencies": {
+        "@types/markdown-it": "^13.0.9"
+      }
     }
   }
 }
diff --git a/packages/core/package.json b/packages/core/package.json
index 8f21f63..66845cc 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -10,6 +10,17 @@
     "test": "vitest",
     "test:ci": "vitest --run"
   },
+  "dependencies": {
+    "markdown-it": "^14.1.0",
+    "markdown-it-anchor": "^8.6.7",
+    "markdown-it-attrs": "^4.1.6",
+    "markdown-it-emoji": "^3.0.0",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-task-lists": "^2.1.1"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^13.0.9"
+  },
   "author": "James Ainslie",
   "license": "MIT"
 }
diff --git a/packages/core/src/__tests__/converter.test.ts b/packages/core/src/__tests__/converter.test.ts
new file mode 100644
index 0000000..a602827
--- /dev/null
+++ b/packages/core/src/__tests__/converter.test.ts
@@ -0,0 +1,232 @@
+import { MarkdownConverter } from '../markdown-converter';
+import { extractFrontmatter, renderFrontmatterHtml } from '../frontmatter-extractor';
+import { CacheManager } from '../cache-manager';
+
+describe('MarkdownConverter', () => {
+  let converter: MarkdownConverter;
+
+  beforeEach(() => {
+    converter = new MarkdownConverter();
+  });
+
+  it('should convert basic markdown to HTML', () => {
+    const result = converter.convert('# Hello World');
+    expect(result.html).toContain('<h1');
+    expect(result.html).toContain('Hello World');
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('should extract heading metadata', () => {
+    const result = converter.convert('# Title\n\n## Subtitle');
+    expect(result.metadata.headings).toHaveLength(2);
+    expect(result.metadata.headings[0].level).toBe(1);
+    // The anchor plugin wraps heading content in <a><span>text</span></a>,
+    // making the inline token's content empty. The heading ID is still generated.
+    expect(result.metadata.headings[0].id).toBe('');
+    expect(result.metadata.headings[1].level).toBe(2);
+  });
+
+  it('should count words', () => {
+    const result = converter.convert('one two three four five');
+    expect(result.metadata.wordCount).toBe(5);
+  });
+
+  it('should detect code blocks', () => {
+    const result = converter.convert('```javascript\nconsole.log("hi");\n```');
+    expect(result.metadata.codeBlocks).toHaveLength(1);
+    expect(result.metadata.codeBlocks[0].language).toBe('javascript');
+  });
+
+  it('should detect mermaid blocks', () => {
+    const result = converter.convert('```mermaid\ngraph TD\n  A --> B\n```');
+    expect(result.metadata.mermaidBlocks).toHaveLength(1);
+    expect(result.metadata.mermaidBlocks[0].code).toContain('graph TD');
+    expect(result.html).toContain('mermaid-container');
+  });
+
+  it('should extract link metadata', () => {
+    const result = converter.convert('[Example](https://example.com)');
+    expect(result.metadata.links).toHaveLength(1);
+    expect(result.metadata.links[0].href).toBe('https://example.com');
+  });
+
+  it('should extract image metadata', () => {
+    const result = converter.convert('![alt text](image.png "title")');
+    expect(result.metadata.images).toHaveLength(1);
+    expect(result.metadata.images[0].src).toBe('image.png');
+    expect(result.metadata.images[0].alt).toBe('alt text');
+  });
+
+  it('should render task lists', () => {
+    const result = converter.convert('- [x] Done\n- [ ] Todo');
+    expect(result.html).toContain('type="checkbox"');
+  });
+
+  it('should validate valid markdown', () => {
+    const result = converter.validateSyntax('# Valid markdown');
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('should handle empty input', () => {
+    const result = converter.convert('');
+    expect(result.html).toBeDefined();
+    expect(result.errors).toHaveLength(0);
+  });
+});
+
+describe('extractFrontmatter', () => {
+  it('should extract frontmatter from markdown', () => {
+    const markdown = '---\ntitle: Hello\nauthor: Test\n---\n# Content';
+    const result = extractFrontmatter(markdown);
+    expect(result.frontmatter).not.toBeNull();
+    expect(result.frontmatter!.title).toBe('Hello');
+    expect(result.frontmatter!.author).toBe('Test');
+    expect(result.cleanedMarkdown).toBe('# Content');
+  });
+
+  it('should return null frontmatter when none present', () => {
+    const result = extractFrontmatter('# No frontmatter');
+    expect(result.frontmatter).toBeNull();
+    expect(result.cleanedMarkdown).toBe('# No frontmatter');
+  });
+
+  it('should handle empty input', () => {
+    const result = extractFrontmatter('');
+    expect(result.frontmatter).toBeNull();
+    expect(result.cleanedMarkdown).toBe('');
+  });
+
+  it('should strip surrounding quotes from values', () => {
+    const markdown = '---\ntitle: "Quoted Title"\n---\n';
+    const result = extractFrontmatter(markdown);
+    expect(result.frontmatter!.title).toBe('Quoted Title');
+  });
+});
+
+describe('renderFrontmatterHtml', () => {
+  it('should render frontmatter as details/table HTML', () => {
+    const html = renderFrontmatterHtml({ title: 'Test', author: 'Author' });
+    expect(html).toContain('<details');
+    expect(html).toContain('frontmatter-card');
+    expect(html).toContain('Test');
+    expect(html).toContain('Author');
+  });
+});
+
+describe('CacheManager', () => {
+  let cache: CacheManager;
+
+  beforeEach(() => {
+    cache = new CacheManager({ maxSize: 3 });
+  });
+
+  it('should return null for missing keys', () => {
+    expect(cache.get('nonexistent')).toBeNull();
+  });
+
+  it('should store and retrieve cache entries', () => {
+    const result = {
+      html: '<p>test</p>',
+      metadata: {
+        wordCount: 1,
+        headings: [],
+        codeBlocks: [],
+        mermaidBlocks: [],
+        images: [],
+        links: [],
+        frontmatter: null,
+      },
+      highlightedBlocks: new Map(),
+      mermaidSVGs: new Map(),
+      timestamp: Date.now(),
+      cacheKey: 'test-key',
+    };
+
+    cache.set('test-key', result, '/test.md', 'hash123', 'github-light');
+    const retrieved = cache.get('test-key');
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.html).toBe('<p>test</p>');
+  });
+
+  it('should evict oldest entry when maxSize is reached', () => {
+    const makeResult = (key: string) => ({
+      html: `<p>${key}</p>`,
+      metadata: {
+        wordCount: 1,
+        headings: [],
+        codeBlocks: [],
+        mermaidBlocks: [],
+        images: [],
+        links: [],
+        frontmatter: null,
+      },
+      highlightedBlocks: new Map<string, string>(),
+      mermaidSVGs: new Map<string, string>(),
+      timestamp: Date.now(),
+      cacheKey: key,
+    });
+
+    cache.set('key1', makeResult('key1'), '/a.md', 'h1', 'github-light');
+    cache.set('key2', makeResult('key2'), '/b.md', 'h2', 'github-light');
+    cache.set('key3', makeResult('key3'), '/c.md', 'h3', 'github-light');
+    // This should evict key1 (oldest)
+    cache.set('key4', makeResult('key4'), '/d.md', 'h4', 'github-light');
+
+    expect(cache.get('key1')).toBeNull();
+    expect(cache.get('key4')).not.toBeNull();
+  });
+
+  it('should invalidate by path', () => {
+    const result = {
+      html: '<p>test</p>',
+      metadata: {
+        wordCount: 1,
+        headings: [],
+        codeBlocks: [],
+        mermaidBlocks: [],
+        images: [],
+        links: [],
+        frontmatter: null,
+      },
+      highlightedBlocks: new Map<string, string>(),
+      mermaidSVGs: new Map<string, string>(),
+      timestamp: Date.now(),
+      cacheKey: 'k',
+    };
+
+    cache.set('k', result, '/file.md', 'hash', 'github-light');
+    cache.invalidateByPath('/file.md');
+    expect(cache.get('k')).toBeNull();
+  });
+
+  it('should clear all entries', () => {
+    const result = {
+      html: '<p>test</p>',
+      metadata: {
+        wordCount: 1,
+        headings: [],
+        codeBlocks: [],
+        mermaidBlocks: [],
+        images: [],
+        links: [],
+        frontmatter: null,
+      },
+      highlightedBlocks: new Map<string, string>(),
+      mermaidSVGs: new Map<string, string>(),
+      timestamp: Date.now(),
+      cacheKey: 'k',
+    };
+
+    cache.set('k', result, '/file.md', 'hash', 'github-light');
+    cache.clear();
+    expect(cache.getStats().size).toBe(0);
+  });
+
+  it('should report stats', () => {
+    const stats = cache.getStats();
+    expect(stats.size).toBe(0);
+    expect(stats.maxSize).toBe(3);
+    expect(stats.oldestEntry).toBeNull();
+  });
+});
diff --git a/packages/core/src/cache-manager.ts b/packages/core/src/cache-manager.ts
new file mode 100644
index 0000000..8b297cb
--- /dev/null
+++ b/packages/core/src/cache-manager.ts
@@ -0,0 +1,239 @@
+/**
+ * Cache Manager
+ * In-memory cache with SHA-256 hash-based keys for rendered markdown content
+ */
+
+import type { CachedResult, CacheEntry, ThemeName } from './types/index';
+
+// Lightweight debug facade — no Chrome dependency
+const debug = {
+  log: (..._args: unknown[]) => {},
+  info: (..._args: unknown[]) => {},
+};
+
+export interface CacheOptions {
+  maxSize?: number; // Max cache entries (default: 50)
+  maxAge?: number; // Max age in ms (default: 1 hour)
+}
+
+export class CacheManager {
+  private cache: Map<string, CacheEntry> = new Map();
+  private fileHashes: Map<string, string> = new Map();
+  private maxSize: number;
+  private maxAge: number;
+
+  constructor(options: CacheOptions = {}) {
+    this.maxSize = options.maxSize || 50;
+    this.maxAge = options.maxAge || 3600000; // 1 hour
+    debug.log('CacheManager', 'Initialized with max size:', this.maxSize);
+  }
+
+  /**
+   * Generate cache key from file path, content, theme, and preferences
+   */
+  async generateKey(
+    filePath: string,
+    content: string,
+    theme: ThemeName,
+    preferences: Record<string, unknown>
+  ): Promise<string> {
+    // Create stable string from inputs
+    const input = JSON.stringify({
+      path: filePath,
+      content,
+      theme,
+      prefs: preferences,
+    });
+
+    // Generate SHA-256 hash
+    const encoder = new TextEncoder();
+    const data = encoder.encode(input);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+
+    return hashHex;
+  }
+
+  /**
+   * Generate content hash for file monitoring
+   */
+  async generateContentHash(content: string): Promise<string> {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(content);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+
+    return hashHex;
+  }
+
+  /**
+   * Get cached result by key
+   */
+  get(key: string): CachedResult | null {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      debug.info('CacheManager', 'Cache miss for key:', key.substring(0, 8));
+      return null;
+    }
+
+    // Check if expired
+    const age = Date.now() - entry.result.timestamp;
+    if (age > this.maxAge) {
+      debug.info('CacheManager', 'Cache expired for key:', key.substring(0, 8));
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Update last accessed time
+    entry.lastAccessed = Date.now();
+    debug.info('CacheManager', 'Cache hit for key:', key.substring(0, 8));
+
+    return entry.result;
+  }
+
+  /**
+   * Set cached result
+   */
+  set(
+    key: string,
+    result: CachedResult,
+    filePath: string,
+    contentHash: string,
+    theme: ThemeName
+  ): void {
+    // Evict old entries if cache is full
+    if (this.cache.size >= this.maxSize) {
+      this.evictOldest();
+    }
+
+    const entry: CacheEntry = {
+      result,
+      filePath,
+      contentHash,
+      theme,
+      lastAccessed: Date.now(),
+    };
+
+    this.cache.set(key, entry);
+    this.fileHashes.set(filePath, contentHash);
+
+    debug.info(
+      'CacheManager',
+      `Cached result for key: ${key.substring(0, 8)}, size: ${this.cache.size}/${this.maxSize}`
+    );
+  }
+
+  /**
+   * Invalidate cache entry by key
+   */
+  invalidate(key: string): void {
+    const entry = this.cache.get(key);
+    if (entry) {
+      this.cache.delete(key);
+      // Remove file hash if this was the last entry for this file
+      const hasOtherEntries = Array.from(this.cache.values()).some(
+        (e) => e.filePath === entry.filePath
+      );
+      if (!hasOtherEntries) {
+        this.fileHashes.delete(entry.filePath);
+      }
+      debug.info('CacheManager', 'Invalidated cache key:', key.substring(0, 8));
+    }
+  }
+
+  /**
+   * Invalidate all cache entries for a file path
+   */
+  invalidateByPath(filePath: string): void {
+    let invalidated = 0;
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.filePath === filePath) {
+        this.cache.delete(key);
+        invalidated++;
+      }
+    }
+    this.fileHashes.delete(filePath);
+    debug.info('CacheManager', `Invalidated ${invalidated} entries for path:`, filePath);
+  }
+
+  /**
+   * Check if file content has changed
+   */
+  async hasFileChanged(filePath: string, currentContent: string): Promise<boolean> {
+    const storedHash = this.fileHashes.get(filePath);
+    if (!storedHash) {
+      return true; // No hash stored, consider it changed
+    }
+
+    const currentHash = await this.generateContentHash(currentContent);
+    return currentHash !== storedHash;
+  }
+
+  /**
+   * Get file hash
+   */
+  getFileHash(filePath: string): string | undefined {
+    return this.fileHashes.get(filePath);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear(): void {
+    const size = this.cache.size;
+    this.cache.clear();
+    this.fileHashes.clear();
+    debug.info('CacheManager', `Cleared ${size} cache entries`);
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    size: number;
+    maxSize: number;
+    hitRate: number;
+    oldestEntry: number | null;
+  } {
+    let oldestTimestamp: number | null = null;
+
+    for (const entry of this.cache.values()) {
+      if (oldestTimestamp === null || entry.result.timestamp < oldestTimestamp) {
+        oldestTimestamp = entry.result.timestamp;
+      }
+    }
+
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      hitRate: 0, // Would need to track hits/misses for real hit rate
+      oldestEntry: oldestTimestamp,
+    };
+  }
+
+  /**
+   * Evict least recently accessed entry
+   */
+  private evictOldest(): void {
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.lastAccessed < oldestTime) {
+        oldestTime = entry.lastAccessed;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey) {
+      this.invalidate(oldestKey);
+      debug.info('CacheManager', 'Evicted oldest entry:', oldestKey.substring(0, 8));
+    }
+  }
+}
+
+// Export singleton
+export const cacheManager = new CacheManager();
diff --git a/packages/core/src/frontmatter-extractor.ts b/packages/core/src/frontmatter-extractor.ts
new file mode 100644
index 0000000..b9d8d49
--- /dev/null
+++ b/packages/core/src/frontmatter-extractor.ts
@@ -0,0 +1,78 @@
+/**
+ * Frontmatter Extractor
+ * Extracts YAML frontmatter from markdown and renders it as an HTML card
+ */
+
+export interface FrontmatterResult {
+  cleanedMarkdown: string;
+  frontmatter: Record<string, string> | null;
+}
+
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+/**
+ * Extract YAML frontmatter from the beginning of a markdown string.
+ * Returns the cleaned markdown (frontmatter stripped) and parsed key-value pairs.
+ */
+export function extractFrontmatter(markdown: string): FrontmatterResult {
+  if (!markdown) {
+    return { cleanedMarkdown: '', frontmatter: null };
+  }
+
+  const match = FRONTMATTER_RE.exec(markdown);
+  if (!match) {
+    return { cleanedMarkdown: markdown, frontmatter: null };
+  }
+
+  const rawBlock = match[1];
+  const frontmatter: Record<string, string> = {};
+
+  for (const line of rawBlock.split(/\r?\n/)) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = line.slice(0, colonIdx).trim();
+    if (!key) continue;
+
+    let value = line.slice(colonIdx + 1).trim();
+
+    // Strip surrounding quotes
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    frontmatter[key] = value;
+  }
+
+  const cleanedMarkdown = markdown.slice(match[0].length);
+
+  return {
+    cleanedMarkdown,
+    frontmatter: Object.keys(frontmatter).length > 0 ? frontmatter : null,
+  };
+}
+
+/**
+ * Render frontmatter data as a collapsible HTML details card.
+ */
+export function renderFrontmatterHtml(frontmatter: Record<string, string>): string {
+  const rows = Object.entries(frontmatter)
+    .map(
+      ([key, value]) =>
+        `<tr><td class="frontmatter-key">${escapeHtml(key)}</td><td class="frontmatter-value">${escapeHtml(value)}</td></tr>`
+    )
+    .join('');
+
+  return `<details class="frontmatter-card"><summary>Frontmatter</summary><table>${rows}</table></details>`;
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 1da5182..1b6448f 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,3 +1,18 @@
 // @mdview/core - shared rendering engine
 // Modules will be exported here as they are extracted from the Chrome extension.
 export const VERSION = '0.0.1';
+
+// Types
+export type * from './types/index';
+
+// Markdown converter
+export { MarkdownConverter, markdownConverter } from './markdown-converter';
+export type { ConvertOptions } from './markdown-converter';
+
+// Cache manager
+export { CacheManager, cacheManager } from './cache-manager';
+export type { CacheOptions } from './cache-manager';
+
+// Frontmatter extractor
+export { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extractor';
+export type { FrontmatterResult } from './frontmatter-extractor';
diff --git a/packages/core/src/markdown-converter.ts b/packages/core/src/markdown-converter.ts
new file mode 100644
index 0000000..31154d6
--- /dev/null
+++ b/packages/core/src/markdown-converter.ts
@@ -0,0 +1,353 @@
+/**
+ * Markdown Converter
+ * Parses markdown to HTML using markdown-it with CommonMark + GFM support
+ */
+
+import MarkdownIt from 'markdown-it';
+import markdownItAttrs from 'markdown-it-attrs';
+import markdownItAnchor from 'markdown-it-anchor';
+import markdownItTaskLists from 'markdown-it-task-lists';
+import * as emojiPlugin from 'markdown-it-emoji';
+import type { ConversionResult, ParseError, ValidationResult } from './types/index';
+
+export interface ConvertOptions {
+  baseUrl?: string;
+  breaks?: boolean;
+  linkify?: boolean;
+  typographer?: boolean;
+  enableHtml?: boolean;
+  highlight?: (code: string, lang: string) => string;
+}
+
+export class MarkdownConverter {
+  private md: MarkdownIt;
+  private metadata: ConversionResult['metadata'] = {
+    wordCount: 0,
+    headings: [],
+    codeBlocks: [],
+    mermaidBlocks: [],
+    images: [],
+    links: [],
+    frontmatter: null,
+  };
+
+  constructor(options?: ConvertOptions) {
+    // Initialize markdown-it
+    this.md = new MarkdownIt({
+      html: options?.enableHtml ?? false, // Security: no raw HTML tags by default
+      breaks: options?.breaks ?? true, // GFM line breaks
+      linkify: options?.linkify ?? true, // Auto-convert URLs to links
+      typographer: options?.typographer ?? true, // Smart quotes and replacements
+      highlight: options?.highlight,
+    });
+
+    // Configure plugins
+    this.configurePlugins();
+  }
+
+  private configurePlugins(): void {
+    // markdown-it-attrs: Add custom attributes to elements
+    this.md.use(markdownItAttrs, {
+      leftDelimiter: '{',
+      rightDelimiter: '}',
+      allowedAttributes: ['id', 'class', 'style'],
+    });
+
+    // markdown-it-anchor: Add anchors to headings
+    this.md.use(markdownItAnchor, {
+      permalink: markdownItAnchor.permalink.headerLink({
+        safariReaderFix: true,
+      }),
+      slugify: (s: string) =>
+        s
+          .toLowerCase()
+          .trim()
+          .replace(/[\s\W-]+/g, '-')
+          .replace(/^-+|-+$/g, ''),
+    });
+
+    // markdown-it-task-lists: GitHub-style task lists
+    this.md.use(markdownItTaskLists, {
+      enabled: true,
+      label: true,
+      labelAfter: true,
+    });
+
+    // markdown-it-emoji: Emoji support
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unnecessary-type-assertion
+    const emojiPluginToUse = ((emojiPlugin as any).full || emojiPlugin) as any;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+    this.md.use(emojiPluginToUse);
+
+    // markdown-it-footnote: Footnotes support
+    // TODO: markdown-it-footnote has ESM export issues, will be fixed in future version
+    // this.md.use(markdownItFootnote);
+
+    // Add custom rule for Mermaid blocks
+    this.addMermaidRule();
+  }
+
+  private addMermaidRule(): void {
+    const defaultFenceRenderer =
+      this.md.renderer.rules.fence ||
+      function (tokens, idx, options, _env, self) {
+        return self.renderToken(tokens, idx, options);
+      };
+
+    this.md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+      const token = tokens[idx];
+      const info = token.info ? token.info.trim() : '';
+      const langName = info.split(/\s+/g)[0];
+
+      // Check if it's a Mermaid diagram
+      if (langName === 'mermaid' || langName === 'mmd') {
+        const code = token.content.trim();
+        const id = `mermaid-${Math.random().toString(36).substr(2, 9)}`;
+
+        // Store in metadata with ID mapping
+        this.metadata.mermaidBlocks.push({
+          code,
+          line: token.map ? token.map[0] : 0,
+        });
+
+        // Store code in global registry (bypasses DOM insertion issues)
+        // Guard for non-browser environments
+        if (typeof window !== 'undefined') {
+          if (!window.__MDVIEW_MERMAID_CODE__) {
+            window.__MDVIEW_MERMAID_CODE__ = new Map();
+          }
+          window.__MDVIEW_MERMAID_CODE__.set(id, code);
+        }
+
+        // Escape the code for safe HTML attribute storage
+        // This allows the code to survive caching and be retrieved later
+        const escapedCode = code
+          .replace(/&/g, '&amp;')
+          .replace(/"/g, '&quot;')
+          .replace(/</g, '&lt;')
+          .replace(/>/g, '&gt;');
+
+        // Return container with code stored in data attribute for cache persistence
+        return `<div class="mermaid-container" id="${id}" data-has-code="true" data-mermaid-code="${escapedCode}">
+          <div class="mermaid-loading">Rendering diagram...</div>
+        </div>\n`;
+      }
+
+      // Check if it's a code block for syntax highlighting
+      if (langName) {
+        this.metadata.codeBlocks.push({
+          language: langName,
+          code: token.content,
+          line: token.map ? token.map[0] : 0,
+          lines: token.content.split('\n').length,
+        });
+      }
+
+      // Use default renderer for code blocks
+      return defaultFenceRenderer(tokens, idx, options, env, self);
+    };
+
+    // Add heading metadata extraction
+    const defaultHeadingOpenRenderer =
+      this.md.renderer.rules.heading_open ||
+      function (tokens, idx, options, _env, self) {
+        return self.renderToken(tokens, idx, options);
+      };
+
+    this.md.renderer.rules.heading_open = (tokens, idx, options, env, self) => {
+      const token = tokens[idx];
+      const level = parseInt(token.tag.substr(1));
+      const nextToken = tokens[idx + 1];
+      const text = nextToken && nextToken.type === 'inline' ? nextToken.content : '';
+
+      // Generate ID
+      const id = text
+        .toLowerCase()
+        .trim()
+        .replace(/[\s\W-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+
+      this.metadata.headings.push({
+        level,
+        text,
+        id,
+        line: token.map ? token.map[0] : 0,
+      });
+
+      return defaultHeadingOpenRenderer(tokens, idx, options, env, self);
+    };
+
+    // Add image metadata extraction
+    const defaultImageRenderer =
+      this.md.renderer.rules.image ||
+      function (tokens, idx, options, _env, self) {
+        return self.renderToken(tokens, idx, options);
+      };
+
+    this.md.renderer.rules.image = (tokens, idx, options, env, self) => {
+      const token = tokens[idx];
+      const srcIndex = token.attrIndex('src');
+      const attrs = token.attrs || [];
+      const src = srcIndex >= 0 ? attrs[srcIndex][1] : '';
+      const alt = token.content;
+      const titleIndex = token.attrIndex('title');
+      const title = titleIndex >= 0 ? attrs[titleIndex][1] : undefined;
+
+      this.metadata.images.push({
+        src,
+        alt,
+        title,
+        line: token.map ? token.map[0] : 0,
+      });
+
+      return defaultImageRenderer(tokens, idx, options, env, self);
+    };
+
+    // Add link metadata extraction
+    const defaultLinkOpenRenderer =
+      this.md.renderer.rules.link_open ||
+      function (tokens, idx, options, _env, self) {
+        return self.renderToken(tokens, idx, options);
+      };
+
+    this.md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
+      const token = tokens[idx];
+      const hrefIndex = token.attrIndex('href');
+      const attrs = token.attrs || [];
+      const href = hrefIndex >= 0 ? attrs[hrefIndex][1] : '';
+      const nextToken = tokens[idx + 1];
+      const text = nextToken && nextToken.type === 'inline' ? nextToken.content : '';
+
+      this.metadata.links.push({
+        href,
+        text,
+        line: token.map ? token.map[0] : 0,
+      });
+
+      return defaultLinkOpenRenderer(tokens, idx, options, env, self);
+    };
+  }
+
+  /**
+   * Convert markdown string to HTML
+   */
+  convert(markdown: string, _options?: ConvertOptions): ConversionResult {
+    // Reset metadata
+    this.metadata = {
+      wordCount: 0,
+      headings: [],
+      codeBlocks: [],
+      mermaidBlocks: [],
+      images: [],
+      links: [],
+      frontmatter: null,
+    };
+
+    const errors: ParseError[] = [];
+
+    try {
+      // Calculate word count
+      this.metadata.wordCount = markdown.trim().split(/\s+/).length;
+
+      // Parse and render
+      const html = this.md.render(markdown);
+
+      return {
+        html,
+        metadata: this.metadata,
+        errors,
+      };
+    } catch (error) {
+      const parseError: ParseError = {
+        message: error instanceof Error ? error.message : String(error),
+        line: 0,
+        column: 0,
+        severity: 'error',
+      };
+      errors.push(parseError);
+
+      return {
+        html: `<div class="markdown-error">
+          <h2>Markdown Parse Error</h2>
+          <p>${this.escapeHtml(parseError.message)}</p>
+        </div>`,
+        metadata: this.metadata,
+        errors,
+      };
+    }
+  }
+
+  /**
+   * Validate markdown syntax
+   */
+  validateSyntax(markdown: string): ValidationResult {
+    const errors: ParseError[] = [];
+    const warnings: ParseError[] = [];
+
+    try {
+      // Try to parse
+      this.md.parse(markdown, {});
+      return { valid: true, errors, warnings };
+    } catch (error) {
+      errors.push({
+        message: error instanceof Error ? error.message : String(error),
+        line: 0,
+        column: 0,
+        severity: 'error',
+      });
+      return { valid: false, errors, warnings };
+    }
+  }
+
+  /**
+   * Register a custom plugin
+   */
+  registerPlugin(
+    plugin: (md: MarkdownIt, options?: Record<string, unknown>) => void,
+    options?: Record<string, unknown>
+  ): void {
+    this.md.use(plugin, options);
+  }
+
+  /**
+   * Escape HTML for safe rendering
+   */
+  private escapeHtml(text: string): string {
+    const map: { [key: string]: string } = {
+      '&': '&amp;',
+      '<': '&lt;',
+      '>': '&gt;',
+      '"': '&quot;',
+      "'": '&#039;',
+    };
+    return text.replace(/[&<>"']/g, (m) => map[m]);
+  }
+
+  /**
+   * Update converter options (e.g., to enable/disable HTML)
+   */
+  updateOptions(options: Partial<ConvertOptions>): void {
+    if (options.enableHtml !== undefined) {
+      this.md.set({ html: options.enableHtml });
+    }
+    if (options.breaks !== undefined) {
+      this.md.set({ breaks: options.breaks });
+    }
+    if (options.linkify !== undefined) {
+      this.md.set({ linkify: options.linkify });
+    }
+    if (options.typographer !== undefined) {
+      this.md.set({ typographer: options.typographer });
+    }
+  }
+
+  /**
+   * Get markdown-it instance for advanced usage
+   */
+  getInstance(): MarkdownIt {
+    return this.md;
+  }
+}
+
+// Export singleton instance
+export const markdownConverter = new MarkdownConverter();
diff --git a/src/core/cache-manager.ts b/src/core/cache-manager.ts
index a4e1cec..cb0d68b 100644
--- a/src/core/cache-manager.ts
+++ b/src/core/cache-manager.ts
@@ -1,234 +1,3 @@
-/**
- * Cache Manager
- * In-memory cache with SHA-256 hash-based keys for rendered markdown content
- */
-
-import type { CachedResult, CacheEntry, ThemeName } from '../types';
-import { debug } from '../utils/debug-logger';
-
-export interface CacheOptions {
-  maxSize?: number; // Max cache entries (default: 50)
-  maxAge?: number; // Max age in ms (default: 1 hour)
-}
-
-export class CacheManager {
-  private cache: Map<string, CacheEntry> = new Map();
-  private fileHashes: Map<string, string> = new Map();
-  private maxSize: number;
-  private maxAge: number;
-
-  constructor(options: CacheOptions = {}) {
-    this.maxSize = options.maxSize || 50;
-    this.maxAge = options.maxAge || 3600000; // 1 hour
-    debug.log('CacheManager', 'Initialized with max size:', this.maxSize);
-  }
-
-  /**
-   * Generate cache key from file path, content, theme, and preferences
-   */
-  async generateKey(
-    filePath: string,
-    content: string,
-    theme: ThemeName,
-    preferences: Record<string, unknown>
-  ): Promise<string> {
-    // Create stable string from inputs
-    const input = JSON.stringify({
-      path: filePath,
-      content,
-      theme,
-      prefs: preferences,
-    });
-
-    // Generate SHA-256 hash
-    const encoder = new TextEncoder();
-    const data = encoder.encode(input);
-    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-    const hashArray = Array.from(new Uint8Array(hashBuffer));
-    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
-
-    return hashHex;
-  }
-
-  /**
-   * Generate content hash for file monitoring
-   */
-  async generateContentHash(content: string): Promise<string> {
-    const encoder = new TextEncoder();
-    const data = encoder.encode(content);
-    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-    const hashArray = Array.from(new Uint8Array(hashBuffer));
-    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
-
-    return hashHex;
-  }
-
-  /**
-   * Get cached result by key
-   */
-  get(key: string): CachedResult | null {
-    const entry = this.cache.get(key);
-
-    if (!entry) {
-      debug.info('CacheManager', 'Cache miss for key:', key.substring(0, 8));
-      return null;
-    }
-
-    // Check if expired
-    const age = Date.now() - entry.result.timestamp;
-    if (age > this.maxAge) {
-      debug.info('CacheManager', 'Cache expired for key:', key.substring(0, 8));
-      this.cache.delete(key);
-      return null;
-    }
-
-    // Update last accessed time
-    entry.lastAccessed = Date.now();
-    debug.info('CacheManager', 'Cache hit for key:', key.substring(0, 8));
-
-    return entry.result;
-  }
-
-  /**
-   * Set cached result
-   */
-  set(
-    key: string,
-    result: CachedResult,
-    filePath: string,
-    contentHash: string,
-    theme: ThemeName
-  ): void {
-    // Evict old entries if cache is full
-    if (this.cache.size >= this.maxSize) {
-      this.evictOldest();
-    }
-
-    const entry: CacheEntry = {
-      result,
-      filePath,
-      contentHash,
-      theme,
-      lastAccessed: Date.now(),
-    };
-
-    this.cache.set(key, entry);
-    this.fileHashes.set(filePath, contentHash);
-
-    debug.info(
-      'CacheManager',
-      `Cached result for key: ${key.substring(0, 8)}, size: ${this.cache.size}/${this.maxSize}`
-    );
-  }
-
-  /**
-   * Invalidate cache entry by key
-   */
-  invalidate(key: string): void {
-    const entry = this.cache.get(key);
-    if (entry) {
-      this.cache.delete(key);
-      // Remove file hash if this was the last entry for this file
-      const hasOtherEntries = Array.from(this.cache.values()).some(
-        (e) => e.filePath === entry.filePath
-      );
-      if (!hasOtherEntries) {
-        this.fileHashes.delete(entry.filePath);
-      }
-      debug.info('CacheManager', 'Invalidated cache key:', key.substring(0, 8));
-    }
-  }
-
-  /**
-   * Invalidate all cache entries for a file path
-   */
-  invalidateByPath(filePath: string): void {
-    let invalidated = 0;
-    for (const [key, entry] of this.cache.entries()) {
-      if (entry.filePath === filePath) {
-        this.cache.delete(key);
-        invalidated++;
-      }
-    }
-    this.fileHashes.delete(filePath);
-    debug.info('CacheManager', `Invalidated ${invalidated} entries for path:`, filePath);
-  }
-
-  /**
-   * Check if file content has changed
-   */
-  async hasFileChanged(filePath: string, currentContent: string): Promise<boolean> {
-    const storedHash = this.fileHashes.get(filePath);
-    if (!storedHash) {
-      return true; // No hash stored, consider it changed
-    }
-
-    const currentHash = await this.generateContentHash(currentContent);
-    return currentHash !== storedHash;
-  }
-
-  /**
-   * Get file hash
-   */
-  getFileHash(filePath: string): string | undefined {
-    return this.fileHashes.get(filePath);
-  }
-
-  /**
-   * Clear all cache entries
-   */
-  clear(): void {
-    const size = this.cache.size;
-    this.cache.clear();
-    this.fileHashes.clear();
-    debug.info('CacheManager', `Cleared ${size} cache entries`);
-  }
-
-  /**
-   * Get cache statistics
-   */
-  getStats(): {
-    size: number;
-    maxSize: number;
-    hitRate: number;
-    oldestEntry: number | null;
-  } {
-    let oldestTimestamp: number | null = null;
-
-    for (const entry of this.cache.values()) {
-      if (oldestTimestamp === null || entry.result.timestamp < oldestTimestamp) {
-        oldestTimestamp = entry.result.timestamp;
-      }
-    }
-
-    return {
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      hitRate: 0, // Would need to track hits/misses for real hit rate
-      oldestEntry: oldestTimestamp,
-    };
-  }
-
-  /**
-   * Evict least recently accessed entry
-   */
-  private evictOldest(): void {
-    let oldestKey: string | null = null;
-    let oldestTime = Infinity;
-
-    for (const [key, entry] of this.cache.entries()) {
-      if (entry.lastAccessed < oldestTime) {
-        oldestTime = entry.lastAccessed;
-        oldestKey = key;
-      }
-    }
-
-    if (oldestKey) {
-      this.invalidate(oldestKey);
-      debug.info('CacheManager', 'Evicted oldest entry:', oldestKey.substring(0, 8));
-    }
-  }
-}
-
-// Export singleton
-export const cacheManager = new CacheManager();
+// Re-export shim: cache-manager has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/cache-manager';
diff --git a/src/core/frontmatter-extractor.ts b/src/core/frontmatter-extractor.ts
index b9d8d49..d73a524 100644
--- a/src/core/frontmatter-extractor.ts
+++ b/src/core/frontmatter-extractor.ts
@@ -1,78 +1,3 @@
-/**
- * Frontmatter Extractor
- * Extracts YAML frontmatter from markdown and renders it as an HTML card
- */
-
-export interface FrontmatterResult {
-  cleanedMarkdown: string;
-  frontmatter: Record<string, string> | null;
-}
-
-const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
-
-/**
- * Extract YAML frontmatter from the beginning of a markdown string.
- * Returns the cleaned markdown (frontmatter stripped) and parsed key-value pairs.
- */
-export function extractFrontmatter(markdown: string): FrontmatterResult {
-  if (!markdown) {
-    return { cleanedMarkdown: '', frontmatter: null };
-  }
-
-  const match = FRONTMATTER_RE.exec(markdown);
-  if (!match) {
-    return { cleanedMarkdown: markdown, frontmatter: null };
-  }
-
-  const rawBlock = match[1];
-  const frontmatter: Record<string, string> = {};
-
-  for (const line of rawBlock.split(/\r?\n/)) {
-    const colonIdx = line.indexOf(':');
-    if (colonIdx === -1) continue;
-
-    const key = line.slice(0, colonIdx).trim();
-    if (!key) continue;
-
-    let value = line.slice(colonIdx + 1).trim();
-
-    // Strip surrounding quotes
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
-
-    frontmatter[key] = value;
-  }
-
-  const cleanedMarkdown = markdown.slice(match[0].length);
-
-  return {
-    cleanedMarkdown,
-    frontmatter: Object.keys(frontmatter).length > 0 ? frontmatter : null,
-  };
-}
-
-/**
- * Render frontmatter data as a collapsible HTML details card.
- */
-export function renderFrontmatterHtml(frontmatter: Record<string, string>): string {
-  const rows = Object.entries(frontmatter)
-    .map(
-      ([key, value]) =>
-        `<tr><td class="frontmatter-key">${escapeHtml(key)}</td><td class="frontmatter-value">${escapeHtml(value)}</td></tr>`
-    )
-    .join('');
-
-  return `<details class="frontmatter-card"><summary>Frontmatter</summary><table>${rows}</table></details>`;
-}
-
-function escapeHtml(text: string): string {
-  return text
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+// Re-export shim: frontmatter-extractor has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/frontmatter-extractor';
diff --git a/src/core/markdown-converter.ts b/src/core/markdown-converter.ts
index 789c970..f673b36 100644
--- a/src/core/markdown-converter.ts
+++ b/src/core/markdown-converter.ts
@@ -1,350 +1,3 @@
-/**
- * Markdown Converter
- * Parses markdown to HTML using markdown-it with CommonMark + GFM support
- */
-
-import MarkdownIt from 'markdown-it';
-import markdownItAttrs from 'markdown-it-attrs';
-import markdownItAnchor from 'markdown-it-anchor';
-import markdownItTaskLists from 'markdown-it-task-lists';
-import * as emojiPlugin from 'markdown-it-emoji';
-import type { ConversionResult, ParseError, ValidationResult } from '../types';
-
-export interface ConvertOptions {
-  baseUrl?: string;
-  breaks?: boolean;
-  linkify?: boolean;
-  typographer?: boolean;
-  enableHtml?: boolean;
-  highlight?: (code: string, lang: string) => string;
-}
-
-export class MarkdownConverter {
-  private md: MarkdownIt;
-  private metadata: ConversionResult['metadata'] = {
-    wordCount: 0,
-    headings: [],
-    codeBlocks: [],
-    mermaidBlocks: [],
-    images: [],
-    links: [],
-    frontmatter: null,
-  };
-
-  constructor(options?: ConvertOptions) {
-    // Initialize markdown-it
-    this.md = new MarkdownIt({
-      html: options?.enableHtml ?? false, // Security: no raw HTML tags by default
-      breaks: options?.breaks ?? true, // GFM line breaks
-      linkify: options?.linkify ?? true, // Auto-convert URLs to links
-      typographer: options?.typographer ?? true, // Smart quotes and replacements
-      highlight: options?.highlight,
-    });
-
-    // Configure plugins
-    this.configurePlugins();
-  }
-
-  private configurePlugins(): void {
-    // markdown-it-attrs: Add custom attributes to elements
-    this.md.use(markdownItAttrs, {
-      leftDelimiter: '{',
-      rightDelimiter: '}',
-      allowedAttributes: ['id', 'class', 'style'],
-    });
-
-    // markdown-it-anchor: Add anchors to headings
-    this.md.use(markdownItAnchor, {
-      permalink: markdownItAnchor.permalink.headerLink({
-        safariReaderFix: true,
-      }),
-      slugify: (s: string) =>
-        s
-          .toLowerCase()
-          .trim()
-          .replace(/[\s\W-]+/g, '-')
-          .replace(/^-+|-+$/g, ''),
-    });
-
-    // markdown-it-task-lists: GitHub-style task lists
-    this.md.use(markdownItTaskLists, {
-      enabled: true,
-      label: true,
-      labelAfter: true,
-    });
-
-    // markdown-it-emoji: Emoji support
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unnecessary-type-assertion
-    const emojiPluginToUse = ((emojiPlugin as any).full || emojiPlugin) as any;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-    this.md.use(emojiPluginToUse);
-
-    // markdown-it-footnote: Footnotes support
-    // TODO: markdown-it-footnote has ESM export issues, will be fixed in future version
-    // this.md.use(markdownItFootnote);
-
-    // Add custom rule for Mermaid blocks
-    this.addMermaidRule();
-  }
-
-  private addMermaidRule(): void {
-    const defaultFenceRenderer =
-      this.md.renderer.rules.fence ||
-      function (tokens, idx, options, _env, self) {
-        return self.renderToken(tokens, idx, options);
-      };
-
-    this.md.renderer.rules.fence = (tokens, idx, options, env, self) => {
-      const token = tokens[idx];
-      const info = token.info ? token.info.trim() : '';
-      const langName = info.split(/\s+/g)[0];
-
-      // Check if it's a Mermaid diagram
-      if (langName === 'mermaid' || langName === 'mmd') {
-        const code = token.content.trim();
-        const id = `mermaid-${Math.random().toString(36).substr(2, 9)}`;
-
-        // Store in metadata with ID mapping
-        this.metadata.mermaidBlocks.push({
-          code,
-          line: token.map ? token.map[0] : 0,
-        });
-
-        // Store code in global registry (bypasses DOM insertion issues)
-        if (!window.__MDVIEW_MERMAID_CODE__) {
-          window.__MDVIEW_MERMAID_CODE__ = new Map();
-        }
-        window.__MDVIEW_MERMAID_CODE__.set(id, code);
-
-        // Escape the code for safe HTML attribute storage
-        // This allows the code to survive caching and be retrieved later
-        const escapedCode = code
-          .replace(/&/g, '&amp;')
-          .replace(/"/g, '&quot;')
-          .replace(/</g, '&lt;')
-          .replace(/>/g, '&gt;');
-
-        // Return container with code stored in data attribute for cache persistence
-        return `<div class="mermaid-container" id="${id}" data-has-code="true" data-mermaid-code="${escapedCode}">
-          <div class="mermaid-loading">Rendering diagram...</div>
-        </div>\n`;
-      }
-
-      // Check if it's a code block for syntax highlighting
-      if (langName) {
-        this.metadata.codeBlocks.push({
-          language: langName,
-          code: token.content,
-          line: token.map ? token.map[0] : 0,
-          lines: token.content.split('\n').length,
-        });
-      }
-
-      // Use default renderer for code blocks
-      return defaultFenceRenderer(tokens, idx, options, env, self);
-    };
-
-    // Add heading metadata extraction
-    const defaultHeadingOpenRenderer =
-      this.md.renderer.rules.heading_open ||
-      function (tokens, idx, options, _env, self) {
-        return self.renderToken(tokens, idx, options);
-      };
-
-    this.md.renderer.rules.heading_open = (tokens, idx, options, env, self) => {
-      const token = tokens[idx];
-      const level = parseInt(token.tag.substr(1));
-      const nextToken = tokens[idx + 1];
-      const text = nextToken && nextToken.type === 'inline' ? nextToken.content : '';
-
-      // Generate ID
-      const id = text
-        .toLowerCase()
-        .trim()
-        .replace(/[\s\W-]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-
-      this.metadata.headings.push({
-        level,
-        text,
-        id,
-        line: token.map ? token.map[0] : 0,
-      });
-
-      return defaultHeadingOpenRenderer(tokens, idx, options, env, self);
-    };
-
-    // Add image metadata extraction
-    const defaultImageRenderer =
-      this.md.renderer.rules.image ||
-      function (tokens, idx, options, _env, self) {
-        return self.renderToken(tokens, idx, options);
-      };
-
-    this.md.renderer.rules.image = (tokens, idx, options, env, self) => {
-      const token = tokens[idx];
-      const srcIndex = token.attrIndex('src');
-      const attrs = token.attrs || [];
-      const src = srcIndex >= 0 ? attrs[srcIndex][1] : '';
-      const alt = token.content;
-      const titleIndex = token.attrIndex('title');
-      const title = titleIndex >= 0 ? attrs[titleIndex][1] : undefined;
-
-      this.metadata.images.push({
-        src,
-        alt,
-        title,
-        line: token.map ? token.map[0] : 0,
-      });
-
-      return defaultImageRenderer(tokens, idx, options, env, self);
-    };
-
-    // Add link metadata extraction
-    const defaultLinkOpenRenderer =
-      this.md.renderer.rules.link_open ||
-      function (tokens, idx, options, _env, self) {
-        return self.renderToken(tokens, idx, options);
-      };
-
-    this.md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
-      const token = tokens[idx];
-      const hrefIndex = token.attrIndex('href');
-      const attrs = token.attrs || [];
-      const href = hrefIndex >= 0 ? attrs[hrefIndex][1] : '';
-      const nextToken = tokens[idx + 1];
-      const text = nextToken && nextToken.type === 'inline' ? nextToken.content : '';
-
-      this.metadata.links.push({
-        href,
-        text,
-        line: token.map ? token.map[0] : 0,
-      });
-
-      return defaultLinkOpenRenderer(tokens, idx, options, env, self);
-    };
-  }
-
-  /**
-   * Convert markdown string to HTML
-   */
-  convert(markdown: string, _options?: ConvertOptions): ConversionResult {
-    // Reset metadata
-    this.metadata = {
-      wordCount: 0,
-      headings: [],
-      codeBlocks: [],
-      mermaidBlocks: [],
-      images: [],
-      links: [],
-      frontmatter: null,
-    };
-
-    const errors: ParseError[] = [];
-
-    try {
-      // Calculate word count
-      this.metadata.wordCount = markdown.trim().split(/\s+/).length;
-
-      // Parse and render
-      const html = this.md.render(markdown);
-
-      return {
-        html,
-        metadata: this.metadata,
-        errors,
-      };
-    } catch (error) {
-      const parseError: ParseError = {
-        message: error instanceof Error ? error.message : String(error),
-        line: 0,
-        column: 0,
-        severity: 'error',
-      };
-      errors.push(parseError);
-
-      return {
-        html: `<div class="markdown-error">
-          <h2>Markdown Parse Error</h2>
-          <p>${this.escapeHtml(parseError.message)}</p>
-        </div>`,
-        metadata: this.metadata,
-        errors,
-      };
-    }
-  }
-
-  /**
-   * Validate markdown syntax
-   */
-  validateSyntax(markdown: string): ValidationResult {
-    const errors: ParseError[] = [];
-    const warnings: ParseError[] = [];
-
-    try {
-      // Try to parse
-      this.md.parse(markdown, {});
-      return { valid: true, errors, warnings };
-    } catch (error) {
-      errors.push({
-        message: error instanceof Error ? error.message : String(error),
-        line: 0,
-        column: 0,
-        severity: 'error',
-      });
-      return { valid: false, errors, warnings };
-    }
-  }
-
-  /**
-   * Register a custom plugin
-   */
-  registerPlugin(
-    plugin: (md: MarkdownIt, options?: Record<string, unknown>) => void,
-    options?: Record<string, unknown>
-  ): void {
-    this.md.use(plugin, options);
-  }
-
-  /**
-   * Escape HTML for safe rendering
-   */
-  private escapeHtml(text: string): string {
-    const map: { [key: string]: string } = {
-      '&': '&amp;',
-      '<': '&lt;',
-      '>': '&gt;',
-      '"': '&quot;',
-      "'": '&#039;',
-    };
-    return text.replace(/[&<>"']/g, (m) => map[m]);
-  }
-
-  /**
-   * Update converter options (e.g., to enable/disable HTML)
-   */
-  updateOptions(options: Partial<ConvertOptions>): void {
-    if (options.enableHtml !== undefined) {
-      this.md.set({ html: options.enableHtml });
-    }
-    if (options.breaks !== undefined) {
-      this.md.set({ breaks: options.breaks });
-    }
-    if (options.linkify !== undefined) {
-      this.md.set({ linkify: options.linkify });
-    }
-    if (options.typographer !== undefined) {
-      this.md.set({ typographer: options.typographer });
-    }
-  }
-
-  /**
-   * Get markdown-it instance for advanced usage
-   */
-  getInstance(): MarkdownIt {
-    return this.md;
-  }
-}
-
-// Export singleton instance
-export const markdownConverter = new MarkdownConverter();
+// Re-export shim: markdown-converter has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/markdown-converter';

From f2db9aba151400b3c649035a79ca9397d626373e Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:24:34 -0400
Subject: [PATCH 08/26] refactor(core): move comment parsers and serializers to
 @mdview/core

---
 .../comments/annotation-parser.test.ts        | 245 +++++++++
 .../comments/annotation-serializer.test.ts    | 197 +++++++
 .../comments/comment-context.test.ts          | 103 ++++
 .../__tests__/comments/comment-parser.test.ts | 107 ++++
 .../comments/comment-serializer.test.ts       | 106 ++++
 .../src/__tests__/comments/emoji-data.test.ts |  61 +++
 .../comments/source-position-map.test.ts      | 107 ++++
 .../core/src/comments/annotation-parser.ts    | 187 +++++++
 .../src/comments/annotation-serializer.ts     | 497 +++++++++++++++++
 packages/core/src/comments/comment-context.ts | 107 ++++
 packages/core/src/comments/comment-parser.ts  | 164 ++++++
 .../core/src/comments/comment-serializer.ts   | 509 +++++++++++++++++
 packages/core/src/comments/emoji-data.ts      | 277 ++++++++++
 .../core/src/comments/source-position-map.ts  | 460 ++++++++++++++++
 src/comments/annotation-parser.ts             | 188 +------
 src/comments/annotation-serializer.ts         | 498 +----------------
 src/comments/comment-context.ts               | 108 +---
 src/comments/comment-parser.ts                | 165 +-----
 src/comments/comment-serializer.ts            | 510 +-----------------
 src/comments/emoji-data.ts                    | 278 +---------
 src/comments/source-position-map.ts           | 461 +---------------
 21 files changed, 3134 insertions(+), 2201 deletions(-)
 create mode 100644 packages/core/src/__tests__/comments/annotation-parser.test.ts
 create mode 100644 packages/core/src/__tests__/comments/annotation-serializer.test.ts
 create mode 100644 packages/core/src/__tests__/comments/comment-context.test.ts
 create mode 100644 packages/core/src/__tests__/comments/comment-parser.test.ts
 create mode 100644 packages/core/src/__tests__/comments/comment-serializer.test.ts
 create mode 100644 packages/core/src/__tests__/comments/emoji-data.test.ts
 create mode 100644 packages/core/src/__tests__/comments/source-position-map.test.ts
 create mode 100644 packages/core/src/comments/annotation-parser.ts
 create mode 100644 packages/core/src/comments/annotation-serializer.ts
 create mode 100644 packages/core/src/comments/comment-context.ts
 create mode 100644 packages/core/src/comments/comment-parser.ts
 create mode 100644 packages/core/src/comments/comment-serializer.ts
 create mode 100644 packages/core/src/comments/emoji-data.ts
 create mode 100644 packages/core/src/comments/source-position-map.ts

diff --git a/packages/core/src/__tests__/comments/annotation-parser.test.ts b/packages/core/src/__tests__/comments/annotation-parser.test.ts
new file mode 100644
index 0000000..38552d4
--- /dev/null
+++ b/packages/core/src/__tests__/comments/annotation-parser.test.ts
@@ -0,0 +1,245 @@
+/**
+ * Tests for annotation parser — v2 format with v1 backward compatibility
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { parseAnnotations, detectFormat } from '../../comments/annotation-parser';
+
+describe('detectFormat', () => {
+  it('should detect v1 format from sentinel', () => {
+    const md = `# Hello\n\n<!-- mdview:comments -->\n[^comment-1]: <!-- mdview:comment {"author":"a","date":"2026-01-01T00:00:00Z"} -->\n    body`;
+    expect(detectFormat(md)).toBe('v1');
+  });
+
+  it('should detect v2 format from sentinel', () => {
+    const md = `# Hello\n\n<!-- mdview:annotations [{"id":1,"anchor":{"text":"Hello"},"body":"note","author":"a","date":"2026-01-01T00:00:00Z"}] -->`;
+    expect(detectFormat(md)).toBe('v2');
+  });
+
+  it('should return none when neither sentinel is present', () => {
+    expect(detectFormat('# Just a document\n\nSome text.')).toBe('none');
+  });
+
+  it('should return v1 when both sentinels present (v1 takes priority)', () => {
+    const md = `# Hello\n\n<!-- mdview:comments -->\n<!-- mdview:annotations [] -->`;
+    expect(detectFormat(md)).toBe('v1');
+  });
+
+  it('should handle empty string', () => {
+    expect(detectFormat('')).toBe('none');
+  });
+});
+
+describe('parseAnnotations', () => {
+  describe('No annotations', () => {
+    it('should return unchanged markdown and empty array when no annotations exist', () => {
+      const markdown = `# Hello World\n\nThis is a paragraph.\n\n## Section Two\n\nMore content here.`;
+      const result = parseAnnotations(markdown);
+      expect(result.cleanedMarkdown).toBe(markdown);
+      expect(result.comments).toEqual([]);
+    });
+
+    it('should handle empty markdown', () => {
+      const result = parseAnnotations('');
+      expect(result.cleanedMarkdown).toBe('');
+      expect(result.comments).toEqual([]);
+    });
+  });
+
+  describe('v2 single annotation', () => {
+    it('should parse a single annotation with all fields', () => {
+      const markdown = `Some highlighted[@1] text in context.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "highlighted", "prefix": "Some ", "suffix": " text" },
+    "body": "This needs attention",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z"
+  }
+] -->`;
+
+      const result = parseAnnotations(markdown);
+
+      expect(result.comments).toHaveLength(1);
+      const comment = result.comments[0];
+      expect(comment.id).toBe('comment-1');
+      expect(comment.selectedText).toBe('highlighted');
+      expect(comment.anchorPrefix).toBe('Some ');
+      expect(comment.anchorSuffix).toBe(' text');
+      expect(comment.body).toBe('This needs attention');
+      expect(comment.author).toBe('reviewer');
+      expect(comment.date).toBe('2026-03-03T14:30:00Z');
+      expect(comment.resolved).toBe(false);
+    });
+
+    it('should remove [@N] markers from cleaned markdown', () => {
+      const markdown = `Some highlighted[@1] text in context.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "highlighted" },
+    "body": "A comment",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z"
+  }
+] -->`;
+
+      const result = parseAnnotations(markdown);
+      expect(result.cleanedMarkdown).toBe('Some highlighted text in context.');
+      expect(result.cleanedMarkdown).not.toContain('[@1]');
+      expect(result.cleanedMarkdown).not.toContain('mdview:annotations');
+    });
+  });
+
+  describe('v2 multiple annotations', () => {
+    it('should parse multiple annotations', () => {
+      const markdown = `First[@1] and second[@2] words.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "First" },
+    "body": "First comment",
+    "author": "alice",
+    "date": "2026-03-01T10:00:00Z"
+  },
+  {
+    "id": 2,
+    "anchor": { "text": "second" },
+    "body": "Second comment",
+    "author": "bob",
+    "date": "2026-03-02T11:00:00Z"
+  }
+] -->`;
+
+      const result = parseAnnotations(markdown);
+      expect(result.comments).toHaveLength(2);
+      expect(result.comments[0].id).toBe('comment-1');
+      expect(result.comments[0].author).toBe('alice');
+      expect(result.comments[0].body).toBe('First comment');
+      expect(result.comments[1].id).toBe('comment-2');
+      expect(result.comments[1].author).toBe('bob');
+      expect(result.comments[1].body).toBe('Second comment');
+    });
+
+    it('should remove all [@N] markers from cleaned markdown', () => {
+      const markdown = `First[@1] and second[@2] words.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "First" },
+    "body": "c1",
+    "author": "a",
+    "date": "2026-01-01T00:00:00Z"
+  },
+  {
+    "id": 2,
+    "anchor": { "text": "second" },
+    "body": "c2",
+    "author": "b",
+    "date": "2026-01-01T00:00:00Z"
+  }
+] -->`;
+
+      const result = parseAnnotations(markdown);
+      expect(result.cleanedMarkdown).toBe('First and second words.');
+    });
+  });
+
+  describe('v2 resolved annotations', () => {
+    it('should parse resolved flag', () => {
+      const markdown = `Some text[@1] here.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "text" },
+    "body": "Resolved",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z",
+    "resolved": true
+  }
+] -->`;
+
+      const result = parseAnnotations(markdown);
+      expect(result.comments[0].resolved).toBe(true);
+    });
+
+    it('should default resolved to false when not specified', () => {
+      const markdown = `Some text[@1] here.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "text" },
+    "body": "Not resolved",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z"
+  }
+] -->`;
+
+      const result = parseAnnotations(markdown);
+      expect(result.comments[0].resolved).toBe(false);
+    });
+  });
+
+  describe('v2 edge cases', () => {
+    it('should handle malformed JSON gracefully (warn, return empty)', () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const markdown = `Text[@1] here.
+
+<!-- mdview:annotations [this is not json] -->`;
+
+      const result = parseAnnotations(markdown);
+      expect(result.comments).toEqual([]);
+      expect(result.cleanedMarkdown).toBe('Text here.');
+      consoleSpy.mockRestore();
+    });
+
+    it('should handle empty annotations array', () => {
+      const markdown = `Some text here.
+
+<!-- mdview:annotations [] -->`;
+
+      const result = parseAnnotations(markdown);
+      expect(result.comments).toEqual([]);
+      expect(result.cleanedMarkdown).toBe('Some text here.');
+    });
+  });
+
+  describe('v1 backward compatibility', () => {
+    it('should parse v1 format comments through delegation', () => {
+      const markdown = `Some highlighted text[^comment-1] in context.
+
+<!-- mdview:comments -->
+[^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->
+    This API endpoint needs error handling
+    for the 404 case.`;
+
+      const result = parseAnnotations(markdown);
+
+      expect(result.comments).toHaveLength(1);
+      expect(result.comments[0].id).toBe('comment-1');
+      expect(result.comments[0].selectedText).toBe('text');
+      expect(result.comments[0].body).toBe('This API endpoint needs error handling\nfor the 404 case.');
+      expect(result.comments[0].author).toBe('reviewer');
+      expect(result.comments[0].date).toBe('2026-03-03T14:30:00Z');
+      expect(result.comments[0].resolved).toBe(false);
+    });
+
+    it('should remove v1 comment references from cleaned markdown', () => {
+      const markdown = `Some highlighted text[^comment-1] in context.
+
+<!-- mdview:comments -->
+[^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->
+    This is a comment.`;
+
+      const result = parseAnnotations(markdown);
+      expect(result.cleanedMarkdown).toBe('Some highlighted text in context.');
+    });
+  });
+});
diff --git a/packages/core/src/__tests__/comments/annotation-serializer.test.ts b/packages/core/src/__tests__/comments/annotation-serializer.test.ts
new file mode 100644
index 0000000..04701d0
--- /dev/null
+++ b/packages/core/src/__tests__/comments/annotation-serializer.test.ts
@@ -0,0 +1,197 @@
+/**
+ * Tests for Annotation Serializer (v2 format)
+ *
+ * Verifies v2 annotation operations: generating IDs, adding, removing,
+ * updating, resolving comments, replies, reactions, and v1 migration.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  generateNextCommentId,
+  addComment,
+  addCommentAtOffset,
+  removeComment,
+  updateComment,
+  resolveComment,
+  updateCommentMetadata,
+  addReply,
+  toggleReaction,
+} from '../../comments/annotation-serializer';
+import { parseAnnotations } from '../../comments/annotation-parser';
+import { buildSourceMap } from '../../comments/source-position-map';
+import type { Comment, CommentContext, CommentReply } from '../../types/index';
+
+function makeComment(overrides: Partial<Comment> = {}): Comment {
+  return {
+    id: 'comment-1',
+    selectedText: 'highlighted text',
+    body: 'This is a comment',
+    author: 'reviewer',
+    date: '2026-03-03T14:30:00Z',
+    resolved: false,
+    ...overrides,
+  };
+}
+
+describe('generateNextCommentId', () => {
+  it('should return "comment-1" for empty markdown', () => {
+    expect(generateNextCommentId('')).toBe('comment-1');
+  });
+
+  it('should return "comment-2" when annotation 1 exists', () => {
+    const md = `Text[@1] here.
+
+<!-- mdview:annotations [{"id":1,"anchor":{"text":"Text"},"body":"note","author":"a","date":"2026-01-01T00:00:00Z"}] -->`;
+    expect(generateNextCommentId(md)).toBe('comment-2');
+  });
+});
+
+describe('addComment', () => {
+  it('should add a [@N] marker and annotation block', () => {
+    const md = 'Some highlighted text in context.\n';
+    const comment = makeComment();
+    const result = addComment(md, comment);
+
+    expect(result).toContain('Some highlighted text[@1] in context.');
+    expect(result).toContain('<!-- mdview:annotations');
+    expect(result).toContain('"id": 1');
+    expect(result).toContain('"text": "highlighted text"');
+    expect(result).toContain('"body": "This is a comment"');
+  });
+});
+
+describe('removeComment', () => {
+  it('should remove the [@N] marker and annotation entry', () => {
+    const md = `Some highlighted text[@1] in context.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "highlighted text" },
+    "body": "This is a comment",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z"
+  }
+] -->`;
+    const result = removeComment(md, 'comment-1');
+
+    expect(result).not.toContain('[@1]');
+    expect(result).not.toContain('This is a comment');
+    expect(result).toContain('Some highlighted text in context.');
+  });
+});
+
+describe('updateComment', () => {
+  it('should replace the body while keeping other fields unchanged', () => {
+    const md = `Some highlighted text[@1] in context.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "highlighted text" },
+    "body": "Original body text",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z"
+  }
+] -->`;
+    const result = updateComment(md, 'comment-1', 'Updated body text');
+
+    expect(result).toContain('"body": "Updated body text"');
+    expect(result).not.toContain('Original body text');
+  });
+});
+
+describe('resolveComment', () => {
+  it('should set resolved:true in annotation JSON', () => {
+    const md = `Some highlighted text[@1] in context.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "highlighted text" },
+    "body": "This is a comment",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z"
+  }
+] -->`;
+    const result = resolveComment(md, 'comment-1');
+
+    expect(result).toContain('"resolved": true');
+  });
+});
+
+describe('addCommentAtOffset', () => {
+  it('should insert marker after bold text using source map', () => {
+    const md = 'This is **important** for the review.\n';
+    const sourceMap = buildSourceMap(md);
+    const comment = makeComment({ selectedText: 'important' });
+    const result = addCommentAtOffset(md, comment, sourceMap);
+
+    expect(result).toContain('**important**[@1]');
+    expect(result).toContain('<!-- mdview:annotations');
+  });
+});
+
+describe('addReply', () => {
+  const v2Md = `Some highlighted text[@1] in context.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "highlighted text" },
+    "body": "This is a comment",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z"
+  }
+] -->`;
+
+  it('should add a reply to annotation thread', () => {
+    const reply: Omit<CommentReply, 'id'> = {
+      author: 'bob',
+      body: 'Good catch',
+      date: '2026-03-04T10:00:00Z',
+    };
+    const { markdown, replyId } = addReply(v2Md, 'comment-1', reply);
+
+    expect(replyId).toBe('reply-1');
+    expect(markdown).toContain('"thread"');
+    expect(markdown).toContain('"author": "bob"');
+  });
+});
+
+describe('toggleReaction', () => {
+  const v2Md = `Some highlighted text[@1] in context.
+
+<!-- mdview:annotations [
+  {
+    "id": 1,
+    "anchor": { "text": "highlighted text" },
+    "body": "This is a comment",
+    "author": "reviewer",
+    "date": "2026-03-03T14:30:00Z"
+  }
+] -->`;
+
+  it('should add a reaction when none exist', () => {
+    const result = toggleReaction(v2Md, 'comment-1', '\u{1F44D}', 'bob');
+
+    expect(result).toContain('"reactions"');
+    const parsed = parseAnnotations(result);
+    expect(parsed.comments[0].reactions).toBeDefined();
+    expect(parsed.comments[0].reactions!['\u{1F44D}']).toContain('bob');
+  });
+});
+
+describe('round-trip: serialize then parse', () => {
+  it('should round-trip a basic comment', () => {
+    const md = 'Some highlighted text in context.\n';
+    const comment = makeComment();
+    const serialized = addComment(md, comment);
+    const parsed = parseAnnotations(serialized);
+
+    expect(parsed.comments).toHaveLength(1);
+    expect(parsed.comments[0].id).toBe('comment-1');
+    expect(parsed.comments[0].selectedText).toBe('highlighted text');
+    expect(parsed.comments[0].body).toBe('This is a comment');
+  });
+});
diff --git a/packages/core/src/__tests__/comments/comment-context.test.ts b/packages/core/src/__tests__/comments/comment-context.test.ts
new file mode 100644
index 0000000..1882eee
--- /dev/null
+++ b/packages/core/src/__tests__/comments/comment-context.test.ts
@@ -0,0 +1,103 @@
+/**
+ * Tests for Comment Context
+ *
+ * Verifies that computeCommentContext correctly derives positional context
+ * (line number, section heading, breadcrumb) from a character offset in
+ * raw markdown content.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { computeCommentContext } from '../../comments/comment-context';
+
+describe('computeCommentContext', () => {
+  it('should return line number and section for offset in a section', () => {
+    const md = [
+      '# Title',
+      '',
+      '## Installation',
+      '',
+      'Run npm install to get started.',
+    ].join('\n');
+
+    const offset = md.indexOf('npm');
+    const ctx = computeCommentContext(md, offset);
+
+    expect(ctx.line).toBe(5);
+    expect(ctx.section).toBe('Installation');
+    expect(ctx.sectionLevel).toBe(2);
+    expect(ctx.breadcrumb).toEqual(['Title', 'Installation']);
+  });
+
+  it('should handle offset before any heading (preamble)', () => {
+    const md = [
+      'Some preamble text here.',
+      '',
+      '# First Heading',
+      '',
+      'Content under heading.',
+    ].join('\n');
+
+    const offset = md.indexOf('preamble');
+    const ctx = computeCommentContext(md, offset);
+
+    expect(ctx.line).toBe(1);
+    expect(ctx.section).toBeUndefined();
+    expect(ctx.sectionLevel).toBeUndefined();
+    expect(ctx.breadcrumb).toEqual([]);
+  });
+
+  it('should build nested breadcrumb (h1 > h2 > h3)', () => {
+    const md = [
+      '# Getting Started',
+      '',
+      '## Installation',
+      '',
+      '### Prerequisites',
+      '',
+      'You need Node.js 18+.',
+    ].join('\n');
+
+    const offset = md.indexOf('Node.js');
+    const ctx = computeCommentContext(md, offset);
+
+    expect(ctx.line).toBe(7);
+    expect(ctx.section).toBe('Prerequisites');
+    expect(ctx.sectionLevel).toBe(3);
+    expect(ctx.breadcrumb).toEqual([
+      'Getting Started',
+      'Installation',
+      'Prerequisites',
+    ]);
+  });
+
+  it('should handle empty string', () => {
+    const ctx = computeCommentContext('', 0);
+
+    expect(ctx.line).toBe(1);
+    expect(ctx.breadcrumb).toEqual([]);
+  });
+
+  it('should reset breadcrumb correctly for peer sections', () => {
+    const md = [
+      '# Guide',
+      '',
+      '## Alpha',
+      '',
+      '### Alpha Sub',
+      '',
+      'Alpha sub content.',
+      '',
+      '## Beta',
+      '',
+      'Beta content here.',
+    ].join('\n');
+
+    const offset = md.indexOf('Beta content');
+    const ctx = computeCommentContext(md, offset);
+
+    expect(ctx.line).toBe(11);
+    expect(ctx.section).toBe('Beta');
+    expect(ctx.sectionLevel).toBe(2);
+    expect(ctx.breadcrumb).toEqual(['Guide', 'Beta']);
+  });
+});
diff --git a/packages/core/src/__tests__/comments/comment-parser.test.ts b/packages/core/src/__tests__/comments/comment-parser.test.ts
new file mode 100644
index 0000000..67fbc6a
--- /dev/null
+++ b/packages/core/src/__tests__/comments/comment-parser.test.ts
@@ -0,0 +1,107 @@
+/**
+ * Tests for comment parser - extracts structured comments from markdown footnotes
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseComments } from '../../comments/comment-parser';
+
+describe('parseComments', () => {
+  describe('No comments', () => {
+    it('should return unchanged markdown and empty array when no comments exist', () => {
+      const markdown = `# Hello World
+
+This is a paragraph.
+
+## Section Two
+
+More content here.`;
+
+      const result = parseComments(markdown);
+
+      expect(result.cleanedMarkdown).toBe(markdown);
+      expect(result.comments).toEqual([]);
+    });
+
+    it('should handle empty markdown', () => {
+      const result = parseComments('');
+
+      expect(result.cleanedMarkdown).toBe('');
+      expect(result.comments).toEqual([]);
+    });
+  });
+
+  describe('Single comment extraction', () => {
+    it('should extract a single comment with all fields', () => {
+      const markdown = `Some highlighted text[^comment-1] in context.
+
+<!-- mdview:comments -->
+[^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->
+    This API endpoint needs error handling
+    for the 404 case.`;
+
+      const result = parseComments(markdown);
+
+      expect(result.comments).toHaveLength(1);
+      const comment = result.comments[0];
+      expect(comment.id).toBe('comment-1');
+      expect(comment.selectedText).toBe('text');
+      expect(comment.body).toBe('This API endpoint needs error handling\nfor the 404 case.');
+      expect(comment.author).toBe('reviewer');
+      expect(comment.date).toBe('2026-03-03T14:30:00Z');
+      expect(comment.resolved).toBe(false);
+    });
+
+    it('should remove comment reference from cleaned markdown', () => {
+      const markdown = `Some highlighted text[^comment-1] in context.
+
+<!-- mdview:comments -->
+[^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->
+    This is a comment.`;
+
+      const result = parseComments(markdown);
+
+      expect(result.cleanedMarkdown).toBe('Some highlighted text in context.');
+      expect(result.cleanedMarkdown).not.toContain('[^comment-1]');
+      expect(result.cleanedMarkdown).not.toContain('mdview:comment');
+    });
+  });
+
+  describe('Multiple comments', () => {
+    it('should extract multiple comments', () => {
+      const markdown = `First text[^comment-1] and second text[^comment-2] in the doc.
+
+<!-- mdview:comments -->
+[^comment-1]: <!-- mdview:comment {"author":"alice","date":"2026-03-01T10:00:00Z"} -->
+    First comment body.
+[^comment-2]: <!-- mdview:comment {"author":"bob","date":"2026-03-02T11:00:00Z"} -->
+    Second comment body.`;
+
+      const result = parseComments(markdown);
+
+      expect(result.comments).toHaveLength(2);
+      expect(result.comments[0].id).toBe('comment-1');
+      expect(result.comments[0].author).toBe('alice');
+      expect(result.comments[0].body).toBe('First comment body.');
+      expect(result.comments[1].id).toBe('comment-2');
+      expect(result.comments[1].author).toBe('bob');
+      expect(result.comments[1].body).toBe('Second comment body.');
+    });
+  });
+
+  describe('Malformed metadata', () => {
+    it('should skip comments with invalid JSON metadata', () => {
+      const markdown = `Text[^comment-1] and more text[^comment-2] here.
+
+<!-- mdview:comments -->
+[^comment-1]: <!-- mdview:comment {bad json} -->
+    This should be skipped.
+[^comment-2]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->
+    This should be parsed.`;
+
+      const result = parseComments(markdown);
+
+      expect(result.comments).toHaveLength(1);
+      expect(result.comments[0].id).toBe('comment-2');
+    });
+  });
+});
diff --git a/packages/core/src/__tests__/comments/comment-serializer.test.ts b/packages/core/src/__tests__/comments/comment-serializer.test.ts
new file mode 100644
index 0000000..3226acc
--- /dev/null
+++ b/packages/core/src/__tests__/comments/comment-serializer.test.ts
@@ -0,0 +1,106 @@
+/**
+ * Tests for Comment Serializer (v1 format)
+ *
+ * Verifies markdown footnote-based comment operations:
+ * generating IDs, adding, removing, updating, and resolving comments.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  generateNextCommentId,
+  addComment,
+  removeComment,
+  updateComment,
+  resolveComment,
+} from '../../comments/comment-serializer';
+import type { Comment } from '../../types/index';
+
+function makeComment(overrides: Partial<Comment> = {}): Comment {
+  return {
+    id: 'comment-1',
+    selectedText: 'highlighted text',
+    body: 'This is a comment',
+    author: 'reviewer',
+    date: '2026-03-03T14:30:00Z',
+    resolved: false,
+    ...overrides,
+  };
+}
+
+describe('generateNextCommentId', () => {
+  it('should return "comment-1" for empty markdown', () => {
+    expect(generateNextCommentId('')).toBe('comment-1');
+  });
+
+  it('should return "comment-2" when comment-1 exists', () => {
+    const md = [
+      'Some highlighted text[^comment-1] in context.',
+      '',
+      '<!-- mdview:comments -->',
+      '[^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->',
+      '    This is a comment',
+    ].join('\n');
+    expect(generateNextCommentId(md)).toBe('comment-2');
+  });
+});
+
+describe('addComment', () => {
+  it('should add a reference after selectedText and a footnote body at the end', () => {
+    const md = 'Some highlighted text in context.\n';
+    const comment = makeComment();
+    const result = addComment(md, comment);
+
+    expect(result).toContain('Some highlighted text[^comment-1] in context.');
+    expect(result).toContain('<!-- mdview:comments -->');
+    expect(result).toContain('[^comment-1]: <!-- mdview:comment');
+    expect(result).toContain('    This is a comment');
+  });
+});
+
+describe('removeComment', () => {
+  it('should remove the reference and footnote body', () => {
+    const md = [
+      'Some highlighted text[^comment-1] in context.',
+      '',
+      '<!-- mdview:comments -->',
+      '[^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->',
+      '    This is a comment',
+    ].join('\n');
+    const result = removeComment(md, 'comment-1');
+
+    expect(result).not.toContain('[^comment-1]');
+    expect(result).not.toContain('This is a comment');
+    expect(result).toContain('Some highlighted text in context.');
+  });
+});
+
+describe('updateComment', () => {
+  it('should replace the body text while keeping metadata unchanged', () => {
+    const md = [
+      'Some highlighted text[^comment-1] in context.',
+      '',
+      '<!-- mdview:comments -->',
+      '[^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->',
+      '    Original body text',
+    ].join('\n');
+    const result = updateComment(md, 'comment-1', 'Updated body text');
+
+    expect(result).toContain('    Updated body text');
+    expect(result).not.toContain('Original body text');
+  });
+});
+
+describe('resolveComment', () => {
+  it('should add "resolved":true to metadata JSON', () => {
+    const md = [
+      'Some highlighted text[^comment-1] in context.',
+      '',
+      '<!-- mdview:comments -->',
+      '[^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->',
+      '    This is a comment',
+    ].join('\n');
+    const result = resolveComment(md, 'comment-1');
+
+    expect(result).toContain('"resolved":true');
+  });
+});
diff --git a/packages/core/src/__tests__/comments/emoji-data.test.ts b/packages/core/src/__tests__/comments/emoji-data.test.ts
new file mode 100644
index 0000000..86ee996
--- /dev/null
+++ b/packages/core/src/__tests__/comments/emoji-data.test.ts
@@ -0,0 +1,61 @@
+/**
+ * Tests for emoji data module
+ */
+
+import { describe, it, expect } from 'vitest';
+import { QUICK_EMOJIS, EMOJI_CATEGORIES, searchEmojis } from '../../comments/emoji-data';
+
+describe('QUICK_EMOJIS', () => {
+  it('should have exactly 12 entries', () => {
+    expect(QUICK_EMOJIS).toHaveLength(12);
+  });
+
+  it('should include common reaction emojis', () => {
+    const chars = QUICK_EMOJIS.map((e) => e.char);
+    expect(chars).toContain('\u{1F44D}'); // thumbs up
+    expect(chars).toContain('\u{1F44E}'); // thumbs down
+    expect(chars).toContain('\u{2764}\u{FE0F}'); // red heart
+    expect(chars).toContain('\u{1F680}'); // rocket
+    expect(chars).toContain('\u{2705}'); // check mark
+    expect(chars).toContain('\u{274C}'); // cross mark
+  });
+});
+
+describe('EMOJI_CATEGORIES', () => {
+  it('should have exactly 8 categories', () => {
+    expect(EMOJI_CATEGORIES).toHaveLength(8);
+  });
+
+  it('should have name and emojis on each category', () => {
+    for (const cat of EMOJI_CATEGORIES) {
+      expect(cat.name).toBeTruthy();
+      expect(cat.emojis.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('searchEmojis', () => {
+  it('should find emojis by name', () => {
+    const results = searchEmojis('thumbs');
+    expect(results.length).toBeGreaterThan(0);
+    const chars = results.map((e) => e.char);
+    expect(chars).toContain('\u{1F44D}');
+  });
+
+  it('should find emojis by keyword', () => {
+    const results = searchEmojis('fire');
+    expect(results.length).toBeGreaterThan(0);
+    const chars = results.map((e) => e.char);
+    expect(chars).toContain('\u{1F525}');
+  });
+
+  it('should return empty array for no match', () => {
+    const results = searchEmojis('zzzznotanemoji');
+    expect(results).toEqual([]);
+  });
+
+  it('should return empty array for empty query', () => {
+    const results = searchEmojis('');
+    expect(results).toEqual([]);
+  });
+});
diff --git a/packages/core/src/__tests__/comments/source-position-map.test.ts b/packages/core/src/__tests__/comments/source-position-map.test.ts
new file mode 100644
index 0000000..512a955
--- /dev/null
+++ b/packages/core/src/__tests__/comments/source-position-map.test.ts
@@ -0,0 +1,107 @@
+/**
+ * Tests for Source Position Map
+ *
+ * Verifies the inline syntax stripping with offset tracking that enables
+ * accurate comment footnote reference insertion into formatted markdown.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  buildSourceMap,
+  findInsertionPoint,
+} from '../../comments/source-position-map';
+
+describe('buildSourceMap', () => {
+  it('should produce identity mapping for plain text', () => {
+    const map = buildSourceMap('Hello world');
+    expect(map.plainText).toBe('Hello world');
+    expect(map.offsets).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+    expect(map.spans).toEqual([]);
+  });
+
+  it('should strip bold markers and track offsets', () => {
+    const map = buildSourceMap('**bold**');
+    expect(map.plainText).toBe('bold');
+    expect(map.offsets).toEqual([2, 3, 4, 5]);
+    expect(map.spans).toHaveLength(1);
+    expect(map.spans[0]).toMatchObject({
+      sourceStart: 0,
+      sourceEnd: 8,
+      plainStart: 0,
+      plainEnd: 4,
+      type: 'bold',
+    });
+  });
+
+  it('should strip link syntax keeping display text', () => {
+    const map = buildSourceMap('[click](https://example.com)');
+    expect(map.plainText).toBe('click');
+    expect(map.spans.some((s) => s.type === 'link')).toBe(true);
+  });
+
+  it('should stop at comment separator', () => {
+    const md = 'Content **here**\n\n<!-- mdview:comments -->\n[^comment-1]: stuff';
+    const map = buildSourceMap(md);
+    expect(map.plainText).toBe('Content here\n\n');
+    expect(map.rawSource).toBe('Content **here**\n\n');
+  });
+
+  it('should handle empty string', () => {
+    const map = buildSourceMap('');
+    expect(map.plainText).toBe('');
+    expect(map.offsets).toEqual([]);
+    expect(map.spans).toEqual([]);
+  });
+});
+
+describe('findInsertionPoint', () => {
+  it('should find insertion point for plain text', () => {
+    const map = buildSourceMap('Hello world');
+    const point = findInsertionPoint(map, 'world');
+    expect(point).toBe(11);
+  });
+
+  it('should find insertion point after bold text', () => {
+    const map = buildSourceMap('Hello **important** text');
+    const point = findInsertionPoint(map, 'important');
+    expect(point).toBe(19);
+  });
+
+  it('should find insertion point after link', () => {
+    const map = buildSourceMap('Click [here](https://example.com) for more');
+    const point = findInsertionPoint(map, 'here');
+    expect(point).toBe(33);
+  });
+
+  it('should return null for text not found', () => {
+    const map = buildSourceMap('Hello world');
+    const point = findInsertionPoint(map, 'missing');
+    expect(point).toBeNull();
+  });
+
+  it('should return null for empty selectedText', () => {
+    const map = buildSourceMap('Hello world');
+    const point = findInsertionPoint(map, '');
+    expect(point).toBeNull();
+  });
+
+  it('should disambiguate using prefix context', () => {
+    const map = buildSourceMap('The word test and another test here');
+    const point = findInsertionPoint(map, 'test', {
+      prefix: 'another ',
+      suffix: ' here',
+    });
+    expect(point).toBe(30);
+  });
+});
+
+describe('source map insertion integration', () => {
+  it('should allow correct footnote insertion after bold text', () => {
+    const md = 'This is **important** for the review.';
+    const map = buildSourceMap(md);
+    const point = findInsertionPoint(map, 'important');
+    expect(point).not.toBeNull();
+    const result = md.slice(0, point!) + '[^comment-1]' + md.slice(point!);
+    expect(result).toBe('This is **important**[^comment-1] for the review.');
+  });
+});
diff --git a/packages/core/src/comments/annotation-parser.ts b/packages/core/src/comments/annotation-parser.ts
new file mode 100644
index 0000000..7789d2b
--- /dev/null
+++ b/packages/core/src/comments/annotation-parser.ts
@@ -0,0 +1,187 @@
+/**
+ * Annotation Parser (v2) — unified entry point for parsing both v1 and v2
+ * comment formats from markdown.
+ *
+ * v2 uses `[@N]` inline markers and a structured JSON annotation block
+ * in `<!-- mdview:annotations [...] -->` at the end of the document.
+ *
+ * v1 uses `[^comment-N]` footnote references and `<!-- mdview:comments -->`
+ * separator with footnote definitions.
+ */
+
+import type { Comment, CommentContext, CommentParseResult, CommentReply } from '../types/index';
+import { parseComments } from './comment-parser';
+
+const V1_SENTINEL = '<!-- mdview:comments -->';
+const V2_SENTINEL_PREFIX = '<!-- mdview:annotations';
+const V2_MARKER_PATTERN = /\[@\d+\]/g;
+const V2_BLOCK_PATTERN = /<!-- mdview:annotations\s+(\[[\s\S]*?\])\s*-->/;
+
+/**
+ * v2 annotation JSON shape (as stored in the markdown file).
+ */
+interface Annotation {
+  id: number;
+  anchor: {
+    text: string;
+    prefix?: string;
+    suffix?: string;
+  };
+  body: string;
+  author: string;
+  date: string;
+  resolved?: boolean;
+  tags?: string[];
+  thread?: Array<{
+    author: string;
+    body: string;
+    date: string;
+  }>;
+  reactions?: Record<string, string[]>;
+  context?: {
+    line?: number;
+    section?: string;
+    sectionLevel?: number;
+    breadcrumb?: string[];
+  };
+}
+
+/**
+ * Detect whether a markdown string uses v1, v2, or no comment format.
+ */
+export function detectFormat(markdown: string): 'v1' | 'v2' | 'none' {
+  const hasV1 = markdown.includes(V1_SENTINEL);
+  const hasV2 = markdown.includes(V2_SENTINEL_PREFIX);
+
+  if (hasV1) return 'v1';
+  if (hasV2) return 'v2';
+  return 'none';
+}
+
+/**
+ * Parse annotations from markdown text.
+ * Detects format automatically: v1 is delegated to comment-parser,
+ * v2 is handled natively.
+ */
+export function parseAnnotations(markdown: string): CommentParseResult {
+  const format = detectFormat(markdown);
+
+  if (format === 'v1') {
+    return parseComments(markdown);
+  }
+
+  if (format === 'v2') {
+    return parseV2(markdown);
+  }
+
+  return { cleanedMarkdown: markdown, comments: [] };
+}
+
+/**
+ * Alias for backward-compatible import as `parseComments`.
+ */
+export { parseAnnotations as parseComments };
+
+/**
+ * Parse v2 annotation format.
+ */
+function parseV2(markdown: string): CommentParseResult {
+  // Find the annotation block
+  const blockMatch = markdown.match(V2_BLOCK_PATTERN);
+  if (!blockMatch) {
+    // Has sentinel prefix but malformed — strip markers and return empty
+    const cleanedMarkdown = stripV2Markers(stripV2Block(markdown));
+    return { cleanedMarkdown, comments: [] };
+  }
+
+  // Parse JSON array
+  let annotations: Annotation[];
+  try {
+    annotations = JSON.parse(blockMatch[1]) as Annotation[];
+  } catch {
+    console.warn('[MDView] Failed to parse v2 annotation JSON');
+    const cleanedMarkdown = stripV2Markers(stripV2Block(markdown));
+    return { cleanedMarkdown, comments: [] };
+  }
+
+  // Build Comment objects
+  const comments = annotations.map(annotationToComment);
+
+  // Remove the annotation block and [@N] markers from content
+  const cleanedMarkdown = stripV2Markers(stripV2Block(markdown));
+
+  return { cleanedMarkdown, comments };
+}
+
+/**
+ * Remove the `<!-- mdview:annotations [...] -->` block from the end of the document.
+ */
+function stripV2Block(markdown: string): string {
+  const idx = markdown.indexOf(V2_SENTINEL_PREFIX);
+  if (idx === -1) return markdown;
+  return markdown.slice(0, idx).trimEnd();
+}
+
+/**
+ * Remove all `[@N]` markers from content.
+ */
+function stripV2Markers(content: string): string {
+  return content.replace(V2_MARKER_PATTERN, '');
+}
+
+/**
+ * Convert a v2 annotation JSON object to an internal Comment.
+ */
+function annotationToComment(annotation: Annotation): Comment {
+  const comment: Comment = {
+    id: `comment-${annotation.id}`,
+    selectedText: annotation.anchor.text,
+    body: annotation.body,
+    author: annotation.author,
+    date: annotation.date,
+    resolved: annotation.resolved ?? false,
+  };
+
+  // Anchor context
+  if (annotation.anchor.prefix) {
+    comment.anchorPrefix = annotation.anchor.prefix;
+  }
+  if (annotation.anchor.suffix) {
+    comment.anchorSuffix = annotation.anchor.suffix;
+  }
+
+  // Positional context
+  if (annotation.context && annotation.context.line !== undefined) {
+    const ctx: CommentContext = {
+      line: annotation.context.line,
+      section: annotation.context.section,
+      sectionLevel: annotation.context.sectionLevel,
+      breadcrumb: annotation.context.breadcrumb ?? [],
+    };
+    comment.context = ctx;
+  }
+
+  // Tags
+  if (annotation.tags && annotation.tags.length > 0) {
+    comment.tags = annotation.tags as Comment['tags'];
+  }
+
+  // Thread → replies
+  if (annotation.thread && annotation.thread.length > 0) {
+    comment.replies = annotation.thread.map(
+      (t, i): CommentReply => ({
+        id: `reply-${i + 1}`,
+        author: t.author,
+        body: t.body,
+        date: t.date,
+      })
+    );
+  }
+
+  // Reactions
+  if (annotation.reactions && Object.keys(annotation.reactions).length > 0) {
+    comment.reactions = annotation.reactions;
+  }
+
+  return comment;
+}
diff --git a/packages/core/src/comments/annotation-serializer.ts b/packages/core/src/comments/annotation-serializer.ts
new file mode 100644
index 0000000..623eec8
--- /dev/null
+++ b/packages/core/src/comments/annotation-serializer.ts
@@ -0,0 +1,497 @@
+/**
+ * Annotation Serializer (v2)
+ *
+ * Generates markdown with `[@N]` inline markers and a structured JSON
+ * annotation block in `<!-- mdview:annotations [...] -->`.
+ *
+ * Drop-in replacement for comment-serializer: same exported function
+ * signatures. On v1 input, automatically migrates to v2 format.
+ */
+
+import type { Comment, CommentReply } from '../types/index';
+import type { SourcePositionMap, SelectionContext } from './source-position-map';
+import { findInsertionPoint } from './source-position-map';
+import { parseComments } from './comment-parser';
+
+const V1_SENTINEL = '<!-- mdview:comments -->';
+const V2_SENTINEL_PREFIX = '<!-- mdview:annotations';
+const V2_BLOCK_PATTERN = /<!-- mdview:annotations\s+(\[[\s\S]*?\])\s*-->/;
+const V2_MARKER_PATTERN = /\[@(\d+)\]/g;
+
+// ─── v2 annotation JSON shape ────────────────────────────────────────
+
+interface Annotation {
+  id: number;
+  anchor: { text: string; prefix?: string; suffix?: string };
+  body: string;
+  author: string;
+  date: string;
+  resolved?: boolean;
+  tags?: string[];
+  thread?: Array<{ author: string; body: string; date: string }>;
+  reactions?: Record<string, string[]>;
+  context?: {
+    line?: number;
+    section?: string;
+    sectionLevel?: number;
+    breadcrumb?: string[];
+  };
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────
+
+/**
+ * Split markdown into content (above annotation block) and annotations array.
+ */
+function splitAtAnnotationBlock(
+  markdown: string
+): [string, Annotation[] | null] {
+  const blockMatch = markdown.match(V2_BLOCK_PATTERN);
+  if (!blockMatch) {
+    return [markdown, null];
+  }
+
+  const blockStart = markdown.indexOf(V2_SENTINEL_PREFIX);
+  const content = markdown.slice(0, blockStart);
+
+  try {
+    const annotations = JSON.parse(blockMatch[1]) as Annotation[];
+    return [content, annotations];
+  } catch {
+    return [content, null];
+  }
+}
+
+/**
+ * Pretty-print the annotation block with 2-space indentation.
+ */
+function serializeAnnotationBlock(annotations: Annotation[]): string {
+  const json = JSON.stringify(annotations, null, 2);
+  return `<!-- mdview:annotations ${json} -->`;
+}
+
+/**
+ * Convert an internal Comment to a v2 annotation JSON object.
+ */
+function commentToAnnotation(comment: Comment): Annotation {
+  const numId = parseInt(comment.id.replace('comment-', ''), 10);
+
+  const anchor: Annotation['anchor'] = { text: comment.selectedText };
+  if (comment.anchorPrefix) anchor.prefix = comment.anchorPrefix;
+  if (comment.anchorSuffix) anchor.suffix = comment.anchorSuffix;
+
+  const annotation: Annotation = {
+    id: numId,
+    anchor,
+    body: comment.body,
+    author: comment.author,
+    date: comment.date,
+  };
+
+  if (comment.resolved) {
+    annotation.resolved = true;
+  }
+
+  if (comment.tags && comment.tags.length > 0) {
+    annotation.tags = comment.tags;
+  }
+
+  if (comment.replies && comment.replies.length > 0) {
+    annotation.thread = comment.replies.map((r) => ({
+      author: r.author,
+      body: r.body,
+      date: r.date,
+    }));
+  }
+
+  if (comment.reactions && Object.keys(comment.reactions).length > 0) {
+    annotation.reactions = comment.reactions;
+  }
+
+  if (comment.context) {
+    const ctx: Annotation['context'] = {};
+    if (comment.context.line !== undefined) ctx.line = comment.context.line;
+    if (comment.context.section !== undefined)
+      ctx.section = comment.context.section;
+    if (comment.context.sectionLevel !== undefined)
+      ctx.sectionLevel = comment.context.sectionLevel;
+    if (comment.context.breadcrumb && comment.context.breadcrumb.length > 0)
+      ctx.breadcrumb = comment.context.breadcrumb;
+    if (Object.keys(ctx).length > 0) annotation.context = ctx;
+  }
+
+  return annotation;
+}
+
+/**
+ * Convert a v2 annotation to an internal Comment.
+ */
+function annotationToComment(annotation: Annotation): Comment {
+  const comment: Comment = {
+    id: `comment-${annotation.id}`,
+    selectedText: annotation.anchor.text,
+    body: annotation.body,
+    author: annotation.author,
+    date: annotation.date,
+    resolved: annotation.resolved ?? false,
+  };
+
+  if (annotation.anchor.prefix) comment.anchorPrefix = annotation.anchor.prefix;
+  if (annotation.anchor.suffix) comment.anchorSuffix = annotation.anchor.suffix;
+
+  if (annotation.tags && annotation.tags.length > 0) {
+    comment.tags = annotation.tags as Comment['tags'];
+  }
+
+  if (annotation.thread && annotation.thread.length > 0) {
+    comment.replies = annotation.thread.map(
+      (t, i): CommentReply => ({
+        id: `reply-${i + 1}`,
+        author: t.author,
+        body: t.body,
+        date: t.date,
+      })
+    );
+  }
+
+  if (annotation.reactions && Object.keys(annotation.reactions).length > 0) {
+    comment.reactions = annotation.reactions;
+  }
+
+  if (annotation.context && annotation.context.line !== undefined) {
+    comment.context = {
+      line: annotation.context.line,
+      section: annotation.context.section,
+      sectionLevel: annotation.context.sectionLevel,
+      breadcrumb: annotation.context.breadcrumb ?? [],
+    };
+  }
+
+  return comment;
+}
+
+/**
+ * Detect v1 sentinel and fully migrate to v2 format.
+ * Returns the markdown with all v1 content replaced by v2.
+ */
+function migrateV1Content(markdown: string): string {
+  const result = parseComments(markdown);
+
+  // Start with cleaned content (v1 refs already stripped by parser)
+  let content = result.cleanedMarkdown;
+
+  // Re-insert markers in v2 format
+  for (const comment of result.comments) {
+    const numId = parseInt(comment.id.replace('comment-', ''), 10);
+    const marker = `[@${numId}]`;
+    const idx = content.indexOf(comment.selectedText);
+    if (idx !== -1) {
+      const insertPos = idx + comment.selectedText.length;
+      content = content.slice(0, insertPos) + marker + content.slice(insertPos);
+    }
+  }
+
+  // Build annotation block
+  const annotations = result.comments.map(commentToAnnotation);
+  const block = serializeAnnotationBlock(annotations);
+
+  return content.trimEnd() + '\n\n' + block + '\n';
+}
+
+/**
+ * If markdown contains v1 sentinel, migrate it. Otherwise return as-is.
+ */
+function ensureV2(markdown: string): string {
+  if (markdown.includes(V1_SENTINEL)) {
+    return migrateV1Content(markdown);
+  }
+  return markdown;
+}
+
+/**
+ * Insert a `[@N]` marker after the first unmatched occurrence of selectedText
+ * in the content section.
+ */
+function insertMarker(
+  contentSection: string,
+  selectedText: string,
+  numId: number
+): string {
+  const marker = `[@${numId}]`;
+  const escapedText = selectedText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Find first occurrence not already followed by [@N]
+  const pattern = new RegExp(`${escapedText}(?!\\[@\\d+\\])`);
+  const match = pattern.exec(contentSection);
+  if (match) {
+    const insertPos = match.index + match[0].length;
+    return (
+      contentSection.slice(0, insertPos) +
+      marker +
+      contentSection.slice(insertPos)
+    );
+  }
+  // Fallback: append to first occurrence
+  const idx = contentSection.indexOf(selectedText);
+  if (idx !== -1) {
+    const insertPos = idx + selectedText.length;
+    return (
+      contentSection.slice(0, insertPos) +
+      marker +
+      contentSection.slice(insertPos)
+    );
+  }
+  return contentSection;
+}
+
+// ─── Exported API (same signatures as v1 serializer) ─────────────────
+
+/**
+ * Scan for `[@N]` markers and annotation `"id": N` to find the next ID.
+ */
+export function generateNextCommentId(markdown: string): string {
+  let max = 0;
+
+  // Check [@N] markers
+  let match: RegExpExecArray | null;
+  const markerPattern = new RegExp(V2_MARKER_PATTERN.source, 'g');
+  while ((match = markerPattern.exec(markdown)) !== null) {
+    const num = parseInt(match[1], 10);
+    if (num > max) max = num;
+  }
+
+  // Check "id": N in annotation block
+  const idPattern = /"id":\s*(\d+)/g;
+  while ((match = idPattern.exec(markdown)) !== null) {
+    const num = parseInt(match[1], 10);
+    if (num > max) max = num;
+  }
+
+  // Also check v1 patterns for migration scenarios
+  const v1Pattern = /\[\^comment-(\d+)\]/g;
+  while ((match = v1Pattern.exec(markdown)) !== null) {
+    const num = parseInt(match[1], 10);
+    if (num > max) max = num;
+  }
+
+  return `comment-${max + 1}`;
+}
+
+/**
+ * Add a comment: insert `[@N]` marker after selectedText, append to annotation block.
+ */
+export function addComment(markdown: string, comment: Comment): string {
+  // Migrate v1 if needed
+  const md = ensureV2(markdown);
+
+  const [contentSection, existingAnnotations] = splitAtAnnotationBlock(md);
+  const numId = parseInt(comment.id.replace('comment-', ''), 10);
+
+  // Insert marker in content
+  const updatedContent = insertMarker(contentSection, comment.selectedText, numId);
+
+  // Build annotation
+  const annotation = commentToAnnotation(comment);
+
+  const annotations = existingAnnotations ? [...existingAnnotations, annotation] : [annotation];
+  const block = serializeAnnotationBlock(annotations);
+
+  return updatedContent.trimEnd() + '\n\n' + block + '\n';
+}
+
+/**
+ * Add a comment using a pre-built source position map for accurate insertion.
+ * Falls back to `addComment()` if the map can't find the position.
+ */
+export function addCommentAtOffset(
+  markdown: string,
+  comment: Comment,
+  sourceMap: SourcePositionMap,
+  context?: SelectionContext
+): string {
+  const offset = findInsertionPoint(sourceMap, comment.selectedText, context);
+
+  if (offset === null) {
+    return addComment(markdown, comment);
+  }
+
+  // Migrate v1 if needed
+  const md = ensureV2(markdown);
+
+  const [contentSection, existingAnnotations] = splitAtAnnotationBlock(md);
+  const numId = parseInt(comment.id.replace('comment-', ''), 10);
+  const marker = `[@${numId}]`;
+
+  // Insert marker at exact offset
+  const updatedContent =
+    contentSection.slice(0, offset) + marker + contentSection.slice(offset);
+
+  const annotation = commentToAnnotation(comment);
+  const annotations = existingAnnotations ? [...existingAnnotations, annotation] : [annotation];
+  const block = serializeAnnotationBlock(annotations);
+
+  return updatedContent.trimEnd() + '\n\n' + block + '\n';
+}
+
+/**
+ * Remove a comment: remove `[@N]` marker and annotation entry.
+ * Removes block entirely if no annotations remain.
+ */
+export function removeComment(markdown: string, commentId: string): string {
+  const md = ensureV2(markdown);
+
+  const [contentSection, annotations] = splitAtAnnotationBlock(md);
+
+  if (!annotations) {
+    // No annotation block — just strip any markers
+    const numId = parseInt(commentId.replace('comment-', ''), 10);
+    return contentSection.split(`[@${numId}]`).join('');
+  }
+
+  const numId = parseInt(commentId.replace('comment-', ''), 10);
+
+  // Remove inline marker
+  const cleanedContent = contentSection.split(`[@${numId}]`).join('');
+
+  // Remove annotation entry
+  const remaining = annotations.filter((a) => a.id !== numId);
+
+  if (remaining.length === 0) {
+    return cleanedContent.trimEnd() + '\n';
+  }
+
+  const block = serializeAnnotationBlock(remaining);
+  return cleanedContent.trimEnd() + '\n\n' + block + '\n';
+}
+
+/**
+ * Update a comment's body in the annotation block.
+ */
+export function updateComment(
+  markdown: string,
+  commentId: string,
+  newBody: string
+): string {
+  const md = ensureV2(markdown);
+
+  const [contentSection, annotations] = splitAtAnnotationBlock(md);
+  if (!annotations) return markdown;
+
+  const numId = parseInt(commentId.replace('comment-', ''), 10);
+  let found = false;
+
+  const updated = annotations.map((a) => {
+    if (a.id === numId) {
+      found = true;
+      return { ...a, body: newBody };
+    }
+    return a;
+  });
+
+  if (!found) return markdown;
+
+  const block = serializeAnnotationBlock(updated);
+  return contentSection.trimEnd() + '\n\n' + block + '\n';
+}
+
+/**
+ * Resolve a comment: set `resolved: true`.
+ */
+export function resolveComment(markdown: string, commentId: string): string {
+  return updateCommentMetadata(markdown, commentId, (c) => {
+    c.resolved = true;
+  });
+}
+
+/**
+ * Generic metadata updater: parse annotation, call updater to mutate
+ * the Comment, then re-serialize.
+ */
+export function updateCommentMetadata(
+  markdown: string,
+  commentId: string,
+  updater: (comment: Comment) => void
+): string {
+  const md = ensureV2(markdown);
+
+  const [contentSection, annotations] = splitAtAnnotationBlock(md);
+  if (!annotations) return markdown;
+
+  const numId = parseInt(commentId.replace('comment-', ''), 10);
+  let found = false;
+
+  const updated = annotations.map((a) => {
+    if (a.id === numId) {
+      found = true;
+      const comment = annotationToComment(a);
+      updater(comment);
+      return commentToAnnotation(comment);
+    }
+    return a;
+  });
+
+  if (!found) return markdown;
+
+  const block = serializeAnnotationBlock(updated);
+  return contentSection.trimEnd() + '\n\n' + block + '\n';
+}
+
+/**
+ * Add a reply to a comment's thread.
+ */
+export function addReply(
+  markdown: string,
+  commentId: string,
+  reply: Omit<CommentReply, 'id'>
+): { markdown: string; replyId: string } {
+  let replyId = '';
+
+  const updated = updateCommentMetadata(markdown, commentId, (comment) => {
+    const replies = comment.replies ?? [];
+    let maxNum = 0;
+    for (const r of replies) {
+      const match = /^reply-(\d+)$/.exec(r.id);
+      if (match) {
+        const num = parseInt(match[1], 10);
+        if (num > maxNum) maxNum = num;
+      }
+    }
+    replyId = `reply-${maxNum + 1}`;
+    replies.push({ id: replyId, ...reply });
+    comment.replies = replies;
+  });
+
+  return { markdown: updated, replyId };
+}
+
+/**
+ * Toggle an emoji reaction for an author on a comment.
+ */
+export function toggleReaction(
+  markdown: string,
+  commentId: string,
+  emoji: string,
+  author: string
+): string {
+  return updateCommentMetadata(markdown, commentId, (comment) => {
+    const reactions = comment.reactions ?? {};
+    const authors = reactions[emoji] ?? [];
+
+    const idx = authors.indexOf(author);
+    if (idx >= 0) {
+      authors.splice(idx, 1);
+      if (authors.length === 0) {
+        delete reactions[emoji];
+      } else {
+        reactions[emoji] = authors;
+      }
+    } else {
+      reactions[emoji] = [...authors, author];
+    }
+
+    if (Object.keys(reactions).length > 0) {
+      comment.reactions = reactions;
+    } else {
+      delete comment.reactions;
+    }
+  });
+}
diff --git a/packages/core/src/comments/comment-context.ts b/packages/core/src/comments/comment-context.ts
new file mode 100644
index 0000000..1622442
--- /dev/null
+++ b/packages/core/src/comments/comment-context.ts
@@ -0,0 +1,107 @@
+/**
+ * Comment Context Builder
+ *
+ * Computes positional context (line number, section heading, breadcrumb)
+ * for a comment at a given character offset in markdown content. This
+ * metadata is stored in the footnote definition so AI agents reading
+ * the raw file can immediately understand where each comment is anchored.
+ */
+
+import type { CommentContext } from '../types/index';
+import { splitIntoSections, type MarkdownSection } from '../../../../src/utils/section-splitter';
+
+/**
+ * Compute positional context for a comment at a given character offset
+ * in the content section of markdown (above the comment separator).
+ */
+export function computeCommentContext(
+  contentMarkdown: string,
+  charOffset: number
+): CommentContext {
+  const line = offsetToLine(contentMarkdown, charOffset);
+  const sections = splitIntoSections(contentMarkdown);
+  const { section, sectionLevel, breadcrumb } = findSectionContext(sections, line);
+
+  return {
+    line,
+    section,
+    sectionLevel,
+    breadcrumb,
+  };
+}
+
+/**
+ * Convert a 0-based character offset to a 1-based line number.
+ */
+function offsetToLine(text: string, offset: number): number {
+  const clamped = Math.min(offset, text.length);
+  let line = 1;
+  for (let i = 0; i < clamped; i++) {
+    if (text[i] === '\n') {
+      line++;
+    }
+  }
+  return line;
+}
+
+/**
+ * Given sections from splitIntoSections() and a 1-based line number,
+ * find the containing section and build the heading breadcrumb.
+ */
+function findSectionContext(
+  sections: MarkdownSection[],
+  line: number
+): { section?: string; sectionLevel?: number; breadcrumb: string[] } {
+  // splitIntoSections uses 0-based line indices; our line is 1-based
+  const zeroLine = line - 1;
+
+  let containingSection: MarkdownSection | undefined;
+  for (const s of sections) {
+    if (zeroLine >= s.startLine && zeroLine <= s.endLine) {
+      containingSection = s;
+      break;
+    }
+  }
+
+  if (!containingSection || !containingSection.heading) {
+    return { breadcrumb: [] };
+  }
+
+  const breadcrumb = buildBreadcrumb(sections, containingSection);
+
+  return {
+    section: containingSection.heading,
+    sectionLevel: containingSection.level,
+    breadcrumb,
+  };
+}
+
+/**
+ * Build a heading breadcrumb from the document start to the target section.
+ *
+ * Walk all sections up to and including the target. Maintain a stack:
+ * when encountering a heading at level N, pop all headings at level >= N,
+ * then push. The final stack is the breadcrumb.
+ */
+function buildBreadcrumb(
+  sections: MarkdownSection[],
+  target: MarkdownSection
+): string[] {
+  const stack: Array<{ heading: string; level: number }> = [];
+
+  for (const s of sections) {
+    if (s.heading && s.level !== undefined) {
+      // Pop headings at same or deeper level
+      while (stack.length > 0 && stack[stack.length - 1].level >= s.level) {
+        stack.pop();
+      }
+      stack.push({ heading: s.heading, level: s.level });
+    }
+
+    if (s === target) {
+      break;
+    }
+  }
+
+  return stack.map((entry) => entry.heading);
+}
diff --git a/packages/core/src/comments/comment-parser.ts b/packages/core/src/comments/comment-parser.ts
new file mode 100644
index 0000000..58ab9c5
--- /dev/null
+++ b/packages/core/src/comments/comment-parser.ts
@@ -0,0 +1,164 @@
+/**
+ * Comment parser for extracting structured comments from markdown footnotes.
+ *
+ * Comments are stored as footnotes with `[^comment-*]` references in the markdown
+ * content, with metadata embedded in HTML comments following the `<!-- mdview:comment {...} -->`
+ * pattern. A `<!-- mdview:comments -->` separator divides the document content from
+ * the comment section.
+ *
+ * @deprecated Use `annotation-parser.ts` instead. This module is kept only for
+ * v1 backward compatibility delegation from the annotation parser.
+ */
+
+import type { Comment, CommentContext, CommentMetadata, CommentParseResult } from '../types/index';
+
+const COMMENT_SEPARATOR = '<!-- mdview:comments -->';
+const COMMENT_REF_PATTERN = /\[\^comment-(\w+)\]/g;
+const FOOTNOTE_DEF_PATTERN = /^\[\^comment-(\w+)\]:\s*<!-- mdview:comment\s+(.+?)\s*-->\s*$/;
+const BODY_CONTINUATION_PATTERN = /^    (.*)$/;
+
+/**
+ * Parse comments from markdown text.
+ *
+ * Splits markdown at the `<!-- mdview:comments -->` separator, parses footnote
+ * definitions from the comments section, extracts the selected text from the
+ * content section, and returns cleaned markdown with comment references removed.
+ */
+export function parseComments(markdown: string): CommentParseResult {
+  const separatorIndex = markdown.indexOf(COMMENT_SEPARATOR);
+
+  if (separatorIndex === -1) {
+    return { cleanedMarkdown: markdown, comments: [] };
+  }
+
+  const contentPortion = markdown.substring(0, separatorIndex);
+  const commentsPortion = markdown.substring(separatorIndex + COMMENT_SEPARATOR.length);
+
+  const comments = parseCommentFootnotes(commentsPortion, contentPortion);
+  const cleanedMarkdown = removeCommentReferences(contentPortion.trimEnd());
+
+  return { cleanedMarkdown, comments };
+}
+
+/**
+ * Parse comment footnote definitions from the comments section of the markdown.
+ */
+function parseCommentFootnotes(commentSection: string, contentSection: string): Comment[] {
+  const lines = commentSection.split('\n');
+  const comments: Comment[] = [];
+
+  let currentId: string | null = null;
+  let currentMetadata: CommentMetadata | null = null;
+  let currentBodyLines: string[] = [];
+
+  for (const line of lines) {
+    // Try to match a footnote definition line
+    const defMatch = line.match(FOOTNOTE_DEF_PATTERN);
+
+    if (defMatch) {
+      // Flush previous comment if any
+      if (currentId !== null && currentMetadata !== null) {
+        comments.push(buildComment(currentId, currentMetadata, currentBodyLines, contentSection));
+      }
+
+      currentId = defMatch[1];
+      currentBodyLines = [];
+
+      // Parse the JSON metadata
+      try {
+        currentMetadata = JSON.parse(defMatch[2]) as CommentMetadata;
+      } catch {
+        // Malformed JSON - skip this comment
+        currentId = null;
+        currentMetadata = null;
+        currentBodyLines = [];
+      }
+      continue;
+    }
+
+    // Try to match a continuation line (indented with 4 spaces)
+    if (currentId !== null && currentMetadata !== null) {
+      const bodyMatch = line.match(BODY_CONTINUATION_PATTERN);
+      if (bodyMatch) {
+        currentBodyLines.push(bodyMatch[1]);
+      }
+    }
+  }
+
+  // Flush the last comment
+  if (currentId !== null && currentMetadata !== null) {
+    comments.push(buildComment(currentId, currentMetadata, currentBodyLines, contentSection));
+  }
+
+  return comments;
+}
+
+/**
+ * Build a Comment object from parsed footnote data.
+ */
+function buildComment(
+  id: string,
+  metadata: CommentMetadata,
+  bodyLines: string[],
+  contentSection: string,
+): Comment {
+  const comment: Comment = {
+    id: `comment-${id}`,
+    selectedText: metadata.selectedText || extractSelectedText(id, contentSection),
+    body: bodyLines.join('\n'),
+    author: metadata.author,
+    date: metadata.date,
+    resolved: metadata.resolved ?? false,
+  };
+
+  // Reconstruct positional context if fields are present in metadata
+  if (metadata.line !== undefined) {
+    const context: CommentContext = {
+      line: metadata.line,
+      section: metadata.section,
+      sectionLevel: metadata.sectionLevel,
+      breadcrumb: metadata.breadcrumb ?? [],
+    };
+    comment.context = context;
+  }
+
+  // Reconstruct tags if present and non-empty
+  if (metadata.tags !== undefined && metadata.tags.length > 0) {
+    comment.tags = metadata.tags;
+  }
+
+  // Reconstruct replies if present and non-empty
+  if (metadata.replies !== undefined && metadata.replies.length > 0) {
+    comment.replies = metadata.replies;
+  }
+
+  // Reconstruct reactions if present and non-empty
+  if (metadata.reactions !== undefined && Object.keys(metadata.reactions).length > 0) {
+    comment.reactions = metadata.reactions;
+  }
+
+  return comment;
+}
+
+/**
+ * Extract the word immediately before a `[^comment-N]` reference in the content.
+ */
+function extractSelectedText(id: string, content: string): string {
+  const refPattern = new RegExp(`(\\S+)\\[\\^comment-${escapeRegExp(id)}\\]`);
+  const match = content.match(refPattern);
+  return match ? match[1] : '';
+}
+
+/**
+ * Remove all `[^comment-*]` references from the content section.
+ */
+function removeCommentReferences(content: string): string {
+  return content.replace(COMMENT_REF_PATTERN, '');
+}
+
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
diff --git a/packages/core/src/comments/comment-serializer.ts b/packages/core/src/comments/comment-serializer.ts
new file mode 100644
index 0000000..d2cc399
--- /dev/null
+++ b/packages/core/src/comments/comment-serializer.ts
@@ -0,0 +1,509 @@
+/**
+ * Comment Serializer (v1)
+ *
+ * Generates markdown with footnote references injected and footnote bodies appended.
+ * Handles add, update, delete, and resolve operations on raw markdown strings.
+ *
+ * Markdown format:
+ *   Some highlighted text[^comment-1] in context.
+ *
+ *   <!-- mdview:comments -->
+ *   [^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->
+ *       This API endpoint needs error handling
+ *       for the 404 case.
+ *
+ * @deprecated Use `annotation-serializer.ts` instead. This module is no longer
+ * imported by production code.
+ */
+
+import type { Comment, CommentMetadata, CommentReply } from '../types/index';
+import type { SourcePositionMap, SelectionContext } from './source-position-map';
+import { findInsertionPoint } from './source-position-map';
+
+const COMMENT_SEPARATOR = '<!-- mdview:comments -->';
+const COMMENT_ID_PATTERN = /\[\^comment-(\d+)\]/g;
+const FOOTNOTE_DEF_PATTERN =
+  /^\[\^(comment-\d+)\]: <!-- mdview:comment (.+?) -->/;
+
+/**
+ * Scan the markdown for `[^comment-N]` patterns and return `comment-(max+1)`.
+ */
+export function generateNextCommentId(markdown: string): string {
+  let max = 0;
+  let match: RegExpExecArray | null;
+  const pattern = new RegExp(COMMENT_ID_PATTERN.source, 'g');
+  while ((match = pattern.exec(markdown)) !== null) {
+    const num = parseInt(match[1], 10);
+    if (num > max) {
+      max = num;
+    }
+  }
+  return `comment-${max + 1}`;
+}
+
+/**
+ * Build the metadata JSON string for a comment footnote.
+ * Omits the `resolved` key when it is false/undefined to keep the format clean.
+ */
+function buildMetadataJson(meta: CommentMetadata): string {
+  const obj: Record<string, unknown> = {
+    author: meta.author,
+    date: meta.date,
+  };
+  if (meta.resolved) {
+    obj.resolved = true;
+  }
+  if (meta.selectedText) {
+    obj.selectedText = meta.selectedText;
+  }
+  // Positional context fields
+  if (meta.line !== undefined) {
+    obj.line = meta.line;
+  }
+  if (meta.section !== undefined) {
+    obj.section = meta.section;
+  }
+  if (meta.sectionLevel !== undefined) {
+    obj.sectionLevel = meta.sectionLevel;
+  }
+  if (meta.breadcrumb !== undefined && meta.breadcrumb.length > 0) {
+    obj.breadcrumb = meta.breadcrumb;
+  }
+  if (meta.tags !== undefined && meta.tags.length > 0) {
+    obj.tags = meta.tags;
+  }
+  if (meta.replies !== undefined && meta.replies.length > 0) {
+    obj.replies = meta.replies;
+  }
+  if (meta.reactions !== undefined && Object.keys(meta.reactions).length > 0) {
+    obj.reactions = meta.reactions;
+  }
+  return JSON.stringify(obj);
+}
+
+/**
+ * Format the footnote body lines, each indented with 4 spaces.
+ */
+function formatFootnoteBody(body: string): string {
+  return body
+    .split('\n')
+    .map((line) => `    ${line}`)
+    .join('\n');
+}
+
+/**
+ * Build a complete footnote definition block.
+ */
+function buildFootnoteBlock(comment: Comment): string {
+  const meta: CommentMetadata = {
+    author: comment.author,
+    date: comment.date,
+  };
+  if (comment.resolved) {
+    meta.resolved = true;
+  }
+  if (comment.selectedText) {
+    meta.selectedText = comment.selectedText;
+  }
+  if (comment.context) {
+    meta.line = comment.context.line;
+    meta.section = comment.context.section;
+    meta.sectionLevel = comment.context.sectionLevel;
+    meta.breadcrumb = comment.context.breadcrumb;
+  }
+  if (comment.tags && comment.tags.length > 0) {
+    meta.tags = comment.tags;
+  }
+  if (comment.replies && comment.replies.length > 0) {
+    meta.replies = comment.replies;
+  }
+  if (comment.reactions && Object.keys(comment.reactions).length > 0) {
+    meta.reactions = comment.reactions;
+  }
+  const metaJson = buildMetadataJson(meta);
+  const header = `[^${comment.id}]: <!-- mdview:comment ${metaJson} -->`;
+  const body = formatFootnoteBody(comment.body);
+  return `${header}\n${body}`;
+}
+
+/**
+ * Find the selectedText in the content portion of the markdown (above the
+ * comments separator) and insert the footnote reference after the first
+ * unmatched occurrence.
+ *
+ * "Unmatched" means the occurrence is not already immediately followed by
+ * a `[^comment-N]` reference.
+ */
+function insertReference(
+  contentSection: string,
+  selectedText: string,
+  commentId: string
+): string {
+  const ref = `[^${commentId}]`;
+  // We need to find the first occurrence of selectedText that is NOT
+  // already followed by [^comment-...]
+  const escapedText = selectedText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(
+    `${escapedText}(?!\\[\\^comment-\\d+\\])`,
+  );
+  const match = pattern.exec(contentSection);
+  if (match) {
+    const insertPos = match.index + match[0].length;
+    return (
+      contentSection.slice(0, insertPos) +
+      ref +
+      contentSection.slice(insertPos)
+    );
+  }
+  // Fallback: if no unmatched occurrence, just append to first occurrence
+  const idx = contentSection.indexOf(selectedText);
+  if (idx !== -1) {
+    const insertPos = idx + selectedText.length;
+    return (
+      contentSection.slice(0, insertPos) +
+      ref +
+      contentSection.slice(insertPos)
+    );
+  }
+  return contentSection;
+}
+
+/**
+ * Split markdown into content (above separator) and comments section (below).
+ * Returns [contentSection, commentsSection | null].
+ */
+function splitAtSeparator(markdown: string): [string, string | null] {
+  const sepIdx = markdown.indexOf(COMMENT_SEPARATOR);
+  if (sepIdx === -1) {
+    return [markdown, null];
+  }
+  const content = markdown.slice(0, sepIdx);
+  const comments = markdown.slice(sepIdx + COMMENT_SEPARATOR.length);
+  return [content, comments];
+}
+
+/**
+ * Add a comment: insert reference after selectedText, append footnote body
+ * after separator.
+ */
+export function addComment(markdown: string, comment: Comment): string {
+  const [contentSection, existingComments] = splitAtSeparator(markdown);
+
+  // Insert reference in content
+  const updatedContent = insertReference(
+    contentSection,
+    comment.selectedText,
+    comment.id
+  );
+
+  // Build footnote block
+  const footnoteBlock = buildFootnoteBlock(comment);
+
+  if (existingComments !== null) {
+    // Separator already exists; append the new footnote
+    const trimmedComments = existingComments.trimEnd();
+    return (
+      updatedContent +
+      COMMENT_SEPARATOR +
+      (trimmedComments ? trimmedComments + '\n\n' : '\n') +
+      footnoteBlock + '\n'
+    );
+  } else {
+    // No separator yet; add it
+    const trimmedContent = updatedContent.trimEnd();
+    return (
+      trimmedContent +
+      '\n\n' +
+      COMMENT_SEPARATOR +
+      '\n' +
+      footnoteBlock + '\n'
+    );
+  }
+}
+
+/**
+ * Add a comment using a pre-built source position map for accurate insertion.
+ * Falls back to `addComment()` (text-search based) if the map can't find the position.
+ */
+export function addCommentAtOffset(
+  markdown: string,
+  comment: Comment,
+  sourceMap: SourcePositionMap,
+  context?: SelectionContext
+): string {
+  const offset = findInsertionPoint(sourceMap, comment.selectedText, context);
+
+  if (offset === null) {
+    // Fallback to text-search based insertion
+    return addComment(markdown, comment);
+  }
+
+  const [contentSection, existingComments] = splitAtSeparator(markdown);
+
+  // Insert the reference at the exact offset in the content section
+  const ref = `[^${comment.id}]`;
+  const updatedContent =
+    contentSection.slice(0, offset) + ref + contentSection.slice(offset);
+
+  // Build footnote block
+  const footnoteBlock = buildFootnoteBlock(comment);
+
+  if (existingComments !== null) {
+    const trimmedComments = existingComments.trimEnd();
+    return (
+      updatedContent +
+      COMMENT_SEPARATOR +
+      (trimmedComments ? trimmedComments + '\n\n' : '\n') +
+      footnoteBlock + '\n'
+    );
+  } else {
+    const trimmedContent = updatedContent.trimEnd();
+    return (
+      trimmedContent +
+      '\n\n' +
+      COMMENT_SEPARATOR +
+      '\n' +
+      footnoteBlock + '\n'
+    );
+  }
+}
+
+/**
+ * Parse the comments section into individual footnote blocks.
+ * Each block is: { id, headerLine, bodyLines[] }.
+ */
+interface FootnoteBlock {
+  id: string;
+  headerLine: string;
+  bodyLines: string[];
+}
+
+function parseFootnoteBlocks(commentsSection: string): FootnoteBlock[] {
+  const lines = commentsSection.split('\n');
+  const blocks: FootnoteBlock[] = [];
+  let current: FootnoteBlock | null = null;
+
+  for (const line of lines) {
+    const defMatch = FOOTNOTE_DEF_PATTERN.exec(line);
+    if (defMatch) {
+      if (current) {
+        blocks.push(current);
+      }
+      current = {
+        id: defMatch[1],
+        headerLine: line,
+        bodyLines: [],
+      };
+    } else if (current && line.startsWith('    ')) {
+      current.bodyLines.push(line);
+    } else if (current && line.trim() === '') {
+      // Blank line between blocks -- finalize current
+      blocks.push(current);
+      current = null;
+    }
+  }
+  if (current) {
+    blocks.push(current);
+  }
+  return blocks;
+}
+
+/**
+ * Serialize footnote blocks back to a comments section string.
+ */
+function serializeFootnoteBlocks(blocks: FootnoteBlock[]): string {
+  return blocks
+    .map((b) => [b.headerLine, ...b.bodyLines].join('\n'))
+    .join('\n\n');
+}
+
+/**
+ * Remove a comment: remove the inline reference and the footnote body.
+ * Remove the separator if no comments remain.
+ */
+export function removeComment(markdown: string, commentId: string): string {
+  const [contentSection, commentsSection] = splitAtSeparator(markdown);
+
+  // Remove inline reference [^commentId]
+  const ref = `[^${commentId}]`;
+  const cleanedContent = contentSection.split(ref).join('');
+
+  if (commentsSection === null) {
+    return cleanedContent;
+  }
+
+  // Parse and filter footnote blocks
+  const blocks = parseFootnoteBlocks(commentsSection);
+  const remaining = blocks.filter((b) => b.id !== commentId);
+
+  if (remaining.length === 0) {
+    // No comments remain; remove separator and trailing whitespace
+    return cleanedContent.trimEnd() + '\n';
+  }
+
+  // Rebuild with separator and remaining blocks
+  const serialized = serializeFootnoteBlocks(remaining);
+  return (
+    cleanedContent +
+    COMMENT_SEPARATOR +
+    '\n' +
+    serialized + '\n'
+  );
+}
+
+/**
+ * Update a comment's body: replace the body lines under the matching footnote
+ * while keeping the metadata header unchanged.
+ */
+export function updateComment(
+  markdown: string,
+  commentId: string,
+  newBody: string
+): string {
+  const [contentSection, commentsSection] = splitAtSeparator(markdown);
+
+  if (commentsSection === null) {
+    return markdown;
+  }
+
+  const blocks = parseFootnoteBlocks(commentsSection);
+  const updatedBlocks = blocks.map((b) => {
+    if (b.id === commentId) {
+      return {
+        ...b,
+        bodyLines: newBody.split('\n').map((line) => `    ${line}`),
+      };
+    }
+    return b;
+  });
+
+  const serialized = serializeFootnoteBlocks(updatedBlocks);
+  return (
+    contentSection +
+    COMMENT_SEPARATOR +
+    '\n' +
+    serialized + '\n'
+  );
+}
+
+/**
+ * Resolve a comment: parse the metadata JSON, set resolved:true, re-serialize.
+ */
+export function resolveComment(markdown: string, commentId: string): string {
+  return updateCommentMetadata(markdown, commentId, (meta) => {
+    meta.resolved = true;
+  });
+}
+
+/**
+ * Generic metadata updater: parse a comment's metadata JSON, call the updater
+ * function to mutate it, then rebuild the header line. Preserves body and
+ * other comments.
+ */
+export function updateCommentMetadata(
+  markdown: string,
+  commentId: string,
+  updater: (meta: CommentMetadata) => void
+): string {
+  const [contentSection, commentsSection] = splitAtSeparator(markdown);
+
+  if (commentsSection === null) {
+    return markdown;
+  }
+
+  const blocks = parseFootnoteBlocks(commentsSection);
+  let found = false;
+
+  const updatedBlocks = blocks.map((b) => {
+    if (b.id === commentId) {
+      const defMatch = FOOTNOTE_DEF_PATTERN.exec(b.headerLine);
+      if (defMatch) {
+        found = true;
+        const meta: CommentMetadata = JSON.parse(defMatch[2]);
+        updater(meta);
+        const metaJson = buildMetadataJson(meta);
+        const newHeader = `[^${b.id}]: <!-- mdview:comment ${metaJson} -->`;
+        return { ...b, headerLine: newHeader };
+      }
+    }
+    return b;
+  });
+
+  if (!found) {
+    return markdown;
+  }
+
+  const serialized = serializeFootnoteBlocks(updatedBlocks);
+  return (
+    contentSection +
+    COMMENT_SEPARATOR +
+    '\n' +
+    serialized + '\n'
+  );
+}
+
+/**
+ * Add a reply to a comment. Generates a sequential reply ID scoped to the
+ * parent comment. Returns the updated markdown and the generated reply ID.
+ */
+export function addReply(
+  markdown: string,
+  commentId: string,
+  reply: Omit<CommentReply, 'id'>
+): { markdown: string; replyId: string } {
+  let replyId = '';
+
+  const updated = updateCommentMetadata(markdown, commentId, (meta) => {
+    const replies = meta.replies ?? [];
+    // Generate sequential ID: reply-1, reply-2, ...
+    let maxNum = 0;
+    for (const r of replies) {
+      const match = /^reply-(\d+)$/.exec(r.id);
+      if (match) {
+        const num = parseInt(match[1], 10);
+        if (num > maxNum) maxNum = num;
+      }
+    }
+    replyId = `reply-${maxNum + 1}`;
+    replies.push({ id: replyId, ...reply });
+    meta.replies = replies;
+  });
+
+  return { markdown: updated, replyId };
+}
+
+/**
+ * Toggle an emoji reaction for an author on a comment.
+ * Adds the author if not present; removes if already present.
+ * Removes the emoji key entirely when no authors remain.
+ */
+export function toggleReaction(
+  markdown: string,
+  commentId: string,
+  emoji: string,
+  author: string
+): string {
+  return updateCommentMetadata(markdown, commentId, (meta) => {
+    const reactions = meta.reactions ?? {};
+    const authors = reactions[emoji] ?? [];
+
+    const idx = authors.indexOf(author);
+    if (idx >= 0) {
+      authors.splice(idx, 1);
+      if (authors.length === 0) {
+        delete reactions[emoji];
+      } else {
+        reactions[emoji] = authors;
+      }
+    } else {
+      reactions[emoji] = [...authors, author];
+    }
+
+    // Only set reactions if non-empty
+    if (Object.keys(reactions).length > 0) {
+      meta.reactions = reactions;
+    } else {
+      delete meta.reactions;
+    }
+  });
+}
diff --git a/packages/core/src/comments/emoji-data.ts b/packages/core/src/comments/emoji-data.ts
new file mode 100644
index 0000000..8699757
--- /dev/null
+++ b/packages/core/src/comments/emoji-data.ts
@@ -0,0 +1,277 @@
+/**
+ * Static emoji data for the comment reaction picker.
+ * Native emoji rendering — no npm dependencies.
+ */
+
+export interface EmojiEntry {
+  char: string;
+  name: string;
+  keywords?: string[];
+}
+
+export interface EmojiCategory {
+  name: string;
+  emojis: EmojiEntry[];
+}
+
+/**
+ * 12 quick-access emojis shown in the top row of the picker.
+ */
+export const QUICK_EMOJIS: EmojiEntry[] = [
+  { char: '\u{1F44D}', name: 'thumbs up', keywords: ['like', 'approve', 'yes'] },
+  { char: '\u{1F44E}', name: 'thumbs down', keywords: ['dislike', 'disapprove', 'no'] },
+  { char: '\u{1F604}', name: 'grinning face', keywords: ['happy', 'smile', 'laugh'] },
+  { char: '\u{1F389}', name: 'party popper', keywords: ['celebrate', 'tada', 'hooray'] },
+  { char: '\u{1F615}', name: 'confused face', keywords: ['confused', 'unsure'] },
+  { char: '\u{2764}\u{FE0F}', name: 'red heart', keywords: ['love', 'heart'] },
+  { char: '\u{1F680}', name: 'rocket', keywords: ['launch', 'ship', 'fast'] },
+  { char: '\u{1F440}', name: 'eyes', keywords: ['look', 'see', 'watching'] },
+  { char: '\u{2705}', name: 'check mark', keywords: ['done', 'complete', 'yes', 'approve'] },
+  { char: '\u{274C}', name: 'cross mark', keywords: ['no', 'wrong', 'reject'] },
+  { char: '\u{1F525}', name: 'fire', keywords: ['hot', 'lit', 'amazing'] },
+  { char: '\u{2B50}', name: 'star', keywords: ['favorite', 'excellent', 'great'] },
+];
+
+/**
+ * 8 emoji categories with ~200 emojis total.
+ */
+export const EMOJI_CATEGORIES: EmojiCategory[] = [
+  {
+    name: 'Smileys & People',
+    emojis: [
+      { char: '\u{1F600}', name: 'grinning face', keywords: ['happy', 'smile'] },
+      { char: '\u{1F604}', name: 'grinning face with smiling eyes', keywords: ['happy', 'smile'] },
+      { char: '\u{1F601}', name: 'beaming face', keywords: ['happy', 'grin'] },
+      { char: '\u{1F606}', name: 'squinting face', keywords: ['laugh', 'happy'] },
+      { char: '\u{1F605}', name: 'grinning face with sweat', keywords: ['relief'] },
+      { char: '\u{1F602}', name: 'face with tears of joy', keywords: ['laugh', 'crying'] },
+      { char: '\u{1F923}', name: 'rolling on the floor laughing', keywords: ['laugh', 'rofl'] },
+      { char: '\u{1F60A}', name: 'smiling face with smiling eyes', keywords: ['blush', 'happy'] },
+      { char: '\u{1F607}', name: 'smiling face with halo', keywords: ['angel', 'innocent'] },
+      { char: '\u{1F609}', name: 'winking face', keywords: ['wink'] },
+      { char: '\u{1F60C}', name: 'relieved face', keywords: ['calm', 'peaceful'] },
+      { char: '\u{1F60D}', name: 'smiling face with heart-eyes', keywords: ['love', 'crush'] },
+      { char: '\u{1F618}', name: 'face blowing a kiss', keywords: ['kiss', 'love'] },
+      { char: '\u{1F914}', name: 'thinking face', keywords: ['think', 'hmm'] },
+      { char: '\u{1F928}', name: 'face with raised eyebrow', keywords: ['skeptical', 'doubt'] },
+      { char: '\u{1F610}', name: 'neutral face', keywords: ['meh', 'blank'] },
+      { char: '\u{1F611}', name: 'expressionless face', keywords: ['blank'] },
+      { char: '\u{1F636}', name: 'face without mouth', keywords: ['speechless', 'silence'] },
+      { char: '\u{1F644}', name: 'face with rolling eyes', keywords: ['eyeroll'] },
+      { char: '\u{1F615}', name: 'confused face', keywords: ['confused', 'unsure'] },
+      { char: '\u{1F61F}', name: 'worried face', keywords: ['worried', 'nervous'] },
+      { char: '\u{1F622}', name: 'crying face', keywords: ['sad', 'cry'] },
+      { char: '\u{1F62D}', name: 'loudly crying face', keywords: ['sob', 'cry'] },
+      { char: '\u{1F621}', name: 'pouting face', keywords: ['angry', 'rage'] },
+      { char: '\u{1F631}', name: 'face screaming in fear', keywords: ['scream', 'horror'] },
+      { char: '\u{1F4AA}', name: 'flexed biceps', keywords: ['strong', 'muscle'] },
+      { char: '\u{1F44F}', name: 'clapping hands', keywords: ['clap', 'applause'] },
+      { char: '\u{1F64F}', name: 'folded hands', keywords: ['pray', 'please', 'thanks'] },
+      { char: '\u{1F91D}', name: 'handshake', keywords: ['agree', 'deal'] },
+      { char: '\u{270C}\u{FE0F}', name: 'victory hand', keywords: ['peace'] },
+    ],
+  },
+  {
+    name: 'Nature',
+    emojis: [
+      { char: '\u{1F436}', name: 'dog face', keywords: ['puppy', 'pet'] },
+      { char: '\u{1F431}', name: 'cat face', keywords: ['kitty', 'pet'] },
+      { char: '\u{1F42D}', name: 'mouse face', keywords: ['mouse'] },
+      { char: '\u{1F43B}', name: 'bear', keywords: ['bear'] },
+      { char: '\u{1F98A}', name: 'fox', keywords: ['fox'] },
+      { char: '\u{1F427}', name: 'penguin', keywords: ['penguin', 'linux'] },
+      { char: '\u{1F41B}', name: 'bug', keywords: ['bug', 'insect'] },
+      { char: '\u{1F40D}', name: 'snake', keywords: ['snake', 'python'] },
+      { char: '\u{1F422}', name: 'turtle', keywords: ['slow', 'turtle'] },
+      { char: '\u{1F419}', name: 'octopus', keywords: ['octopus'] },
+      { char: '\u{1F332}', name: 'evergreen tree', keywords: ['tree', 'nature'] },
+      { char: '\u{1F33B}', name: 'sunflower', keywords: ['flower'] },
+      { char: '\u{1F340}', name: 'four leaf clover', keywords: ['luck', 'clover'] },
+      { char: '\u{1F335}', name: 'cactus', keywords: ['desert', 'plant'] },
+      { char: '\u{1F30A}', name: 'water wave', keywords: ['ocean', 'wave'] },
+      { char: '\u{2600}\u{FE0F}', name: 'sun', keywords: ['sunny', 'weather'] },
+      { char: '\u{1F319}', name: 'crescent moon', keywords: ['moon', 'night'] },
+      { char: '\u{2B50}', name: 'star', keywords: ['favorite', 'excellent'] },
+      { char: '\u{26A1}', name: 'lightning', keywords: ['electric', 'zap', 'thunder'] },
+      { char: '\u{1F525}', name: 'fire', keywords: ['hot', 'lit', 'flame'] },
+      { char: '\u{1F4A7}', name: 'droplet', keywords: ['water', 'drop'] },
+      { char: '\u{2744}\u{FE0F}', name: 'snowflake', keywords: ['cold', 'winter'] },
+      { char: '\u{1F308}', name: 'rainbow', keywords: ['rainbow'] },
+    ],
+  },
+  {
+    name: 'Food & Drink',
+    emojis: [
+      { char: '\u{1F34E}', name: 'red apple', keywords: ['apple', 'fruit'] },
+      { char: '\u{1F34A}', name: 'tangerine', keywords: ['orange', 'fruit'] },
+      { char: '\u{1F34B}', name: 'lemon', keywords: ['citrus'] },
+      { char: '\u{1F34C}', name: 'banana', keywords: ['fruit'] },
+      { char: '\u{1F353}', name: 'strawberry', keywords: ['fruit', 'berry'] },
+      { char: '\u{1F349}', name: 'watermelon', keywords: ['fruit', 'summer'] },
+      { char: '\u{1F355}', name: 'pizza', keywords: ['food'] },
+      { char: '\u{1F354}', name: 'hamburger', keywords: ['burger', 'food'] },
+      { char: '\u{1F37F}', name: 'popcorn', keywords: ['movie', 'snack'] },
+      { char: '\u{2615}', name: 'hot beverage', keywords: ['coffee', 'tea'] },
+      { char: '\u{1F37A}', name: 'beer mug', keywords: ['beer', 'drink'] },
+      { char: '\u{1F377}', name: 'wine glass', keywords: ['wine', 'drink'] },
+      { char: '\u{1F375}', name: 'teacup', keywords: ['tea', 'drink'] },
+      { char: '\u{1F382}', name: 'birthday cake', keywords: ['cake', 'celebration'] },
+      { char: '\u{1F369}', name: 'donut', keywords: ['doughnut', 'sweet'] },
+      { char: '\u{1F36B}', name: 'chocolate bar', keywords: ['chocolate', 'sweet'] },
+      { char: '\u{1F950}', name: 'croissant', keywords: ['bread', 'pastry'] },
+      { char: '\u{1F96A}', name: 'sandwich', keywords: ['food'] },
+      { char: '\u{1F32E}', name: 'taco', keywords: ['mexican', 'food'] },
+      { char: '\u{1F363}', name: 'sushi', keywords: ['japanese', 'food'] },
+    ],
+  },
+  {
+    name: 'Activities',
+    emojis: [
+      { char: '\u{26BD}', name: 'soccer ball', keywords: ['football', 'sport'] },
+      { char: '\u{1F3C0}', name: 'basketball', keywords: ['sport'] },
+      { char: '\u{1F3C8}', name: 'american football', keywords: ['sport'] },
+      { char: '\u{26BE}', name: 'baseball', keywords: ['sport'] },
+      { char: '\u{1F3BE}', name: 'tennis', keywords: ['sport'] },
+      { char: '\u{1F3AF}', name: 'bullseye', keywords: ['target', 'dart'] },
+      { char: '\u{1F3AE}', name: 'video game', keywords: ['game', 'controller'] },
+      { char: '\u{265F}\u{FE0F}', name: 'chess pawn', keywords: ['chess', 'game', 'strategy'] },
+      { char: '\u{1F3B2}', name: 'game die', keywords: ['dice', 'game', 'random'] },
+      { char: '\u{1F3B5}', name: 'musical note', keywords: ['music', 'note'] },
+      { char: '\u{1F3B6}', name: 'musical notes', keywords: ['music'] },
+      { char: '\u{1F3A4}', name: 'microphone', keywords: ['sing', 'karaoke'] },
+      { char: '\u{1F3AC}', name: 'clapper board', keywords: ['movie', 'film'] },
+      { char: '\u{1F3A8}', name: 'artist palette', keywords: ['art', 'paint'] },
+      { char: '\u{1F3AD}', name: 'performing arts', keywords: ['theater', 'drama'] },
+      { char: '\u{1F3C6}', name: 'trophy', keywords: ['winner', 'award', 'prize'] },
+      { char: '\u{1F3C5}', name: 'sports medal', keywords: ['medal', 'award'] },
+      { char: '\u{1F947}', name: 'first place medal', keywords: ['gold', 'winner'] },
+      { char: '\u{1F948}', name: 'second place medal', keywords: ['silver'] },
+      { char: '\u{1F949}', name: 'third place medal', keywords: ['bronze'] },
+    ],
+  },
+  {
+    name: 'Travel & Places',
+    emojis: [
+      { char: '\u{1F697}', name: 'automobile', keywords: ['car'] },
+      { char: '\u{1F680}', name: 'rocket', keywords: ['launch', 'ship', 'space'] },
+      { char: '\u{2708}\u{FE0F}', name: 'airplane', keywords: ['travel', 'flight'] },
+      { char: '\u{1F6A2}', name: 'ship', keywords: ['boat', 'cruise'] },
+      { char: '\u{1F682}', name: 'locomotive', keywords: ['train'] },
+      { char: '\u{1F6B2}', name: 'bicycle', keywords: ['bike', 'cycling'] },
+      { char: '\u{1F3E0}', name: 'house', keywords: ['home'] },
+      { char: '\u{1F3D7}\u{FE0F}', name: 'building construction', keywords: ['construction'] },
+      { char: '\u{1F3D4}\u{FE0F}', name: 'snow-capped mountain', keywords: ['mountain'] },
+      { char: '\u{1F3D6}\u{FE0F}', name: 'beach', keywords: ['beach', 'vacation'] },
+      { char: '\u{1F30D}', name: 'globe europe-africa', keywords: ['world', 'earth'] },
+      { char: '\u{1F30E}', name: 'globe americas', keywords: ['world', 'earth'] },
+      { char: '\u{1F5FA}\u{FE0F}', name: 'world map', keywords: ['map', 'travel'] },
+      { char: '\u{26F0}\u{FE0F}', name: 'mountain', keywords: ['mountain'] },
+      { char: '\u{1F30B}', name: 'volcano', keywords: ['eruption'] },
+    ],
+  },
+  {
+    name: 'Objects',
+    emojis: [
+      { char: '\u{1F4BB}', name: 'laptop', keywords: ['computer', 'code'] },
+      { char: '\u{1F4F1}', name: 'mobile phone', keywords: ['phone', 'cell'] },
+      { char: '\u{2328}\u{FE0F}', name: 'keyboard', keywords: ['type', 'computer'] },
+      { char: '\u{1F4A1}', name: 'light bulb', keywords: ['idea', 'bright'] },
+      { char: '\u{1F50D}', name: 'magnifying glass', keywords: ['search', 'find'] },
+      { char: '\u{1F512}', name: 'locked', keywords: ['lock', 'security'] },
+      { char: '\u{1F513}', name: 'unlocked', keywords: ['unlock', 'open'] },
+      { char: '\u{1F527}', name: 'wrench', keywords: ['tool', 'fix'] },
+      { char: '\u{1F528}', name: 'hammer', keywords: ['tool', 'build'] },
+      { char: '\u{2699}\u{FE0F}', name: 'gear', keywords: ['settings', 'config'] },
+      { char: '\u{1F4E6}', name: 'package', keywords: ['box', 'delivery'] },
+      { char: '\u{1F4CB}', name: 'clipboard', keywords: ['paste', 'list'] },
+      { char: '\u{1F4DD}', name: 'memo', keywords: ['note', 'write'] },
+      { char: '\u{1F4DA}', name: 'books', keywords: ['library', 'read'] },
+      { char: '\u{1F4D6}', name: 'open book', keywords: ['read', 'study'] },
+      { char: '\u{2709}\u{FE0F}', name: 'envelope', keywords: ['email', 'mail'] },
+      { char: '\u{1F4CE}', name: 'paperclip', keywords: ['attach'] },
+      { char: '\u{270F}\u{FE0F}', name: 'pencil', keywords: ['write', 'edit'] },
+      { char: '\u{1F4CC}', name: 'pushpin', keywords: ['pin', 'location'] },
+      { char: '\u{1F5D1}\u{FE0F}', name: 'wastebasket', keywords: ['trash', 'delete'] },
+      { char: '\u{1F3F7}\u{FE0F}', name: 'label', keywords: ['tag'] },
+      { char: '\u{1F4CA}', name: 'bar chart', keywords: ['chart', 'graph', 'stats'] },
+      { char: '\u{1F4C8}', name: 'chart increasing', keywords: ['growth', 'up'] },
+      { char: '\u{1F4C9}', name: 'chart decreasing', keywords: ['decline', 'down'] },
+      { char: '\u{23F0}', name: 'alarm clock', keywords: ['time', 'clock'] },
+    ],
+  },
+  {
+    name: 'Symbols',
+    emojis: [
+      { char: '\u{2764}\u{FE0F}', name: 'red heart', keywords: ['love'] },
+      { char: '\u{1F49B}', name: 'yellow heart', keywords: ['love'] },
+      { char: '\u{1F49A}', name: 'green heart', keywords: ['love'] },
+      { char: '\u{1F499}', name: 'blue heart', keywords: ['love'] },
+      { char: '\u{1F49C}', name: 'purple heart', keywords: ['love'] },
+      { char: '\u{2705}', name: 'check mark', keywords: ['done', 'complete', 'yes'] },
+      { char: '\u{274C}', name: 'cross mark', keywords: ['no', 'wrong', 'reject'] },
+      { char: '\u{2757}', name: 'exclamation mark', keywords: ['important', 'alert'] },
+      { char: '\u{2753}', name: 'question mark', keywords: ['question', 'help'] },
+      { char: '\u{1F4AF}', name: 'hundred points', keywords: ['perfect', '100'] },
+      { char: '\u{267B}\u{FE0F}', name: 'recycling symbol', keywords: ['recycle', 'green'] },
+      { char: '\u{26A0}\u{FE0F}', name: 'warning', keywords: ['caution', 'alert'] },
+      { char: '\u{1F6AB}', name: 'prohibited', keywords: ['banned', 'forbidden'] },
+      { char: '\u{2139}\u{FE0F}', name: 'information', keywords: ['info', 'help'] },
+      { char: '\u{1F503}', name: 'clockwise arrows', keywords: ['refresh', 'reload'] },
+      { char: '\u{1F504}', name: 'counterclockwise arrows', keywords: ['undo', 'back'] },
+      { char: '\u{2B06}\u{FE0F}', name: 'up arrow', keywords: ['up'] },
+      { char: '\u{2B07}\u{FE0F}', name: 'down arrow', keywords: ['down'] },
+      { char: '\u{27A1}\u{FE0F}', name: 'right arrow', keywords: ['right', 'next'] },
+      { char: '\u{2B05}\u{FE0F}', name: 'left arrow', keywords: ['left', 'back'] },
+    ],
+  },
+  {
+    name: 'Flags',
+    emojis: [
+      { char: '\u{1F3C1}', name: 'chequered flag', keywords: ['finish', 'race'] },
+      { char: '\u{1F6A9}', name: 'triangular flag', keywords: ['flag', 'alert'] },
+      { char: '\u{1F3F4}', name: 'black flag', keywords: ['flag'] },
+      { char: '\u{1F3F3}\u{FE0F}', name: 'white flag', keywords: ['surrender', 'peace'] },
+      { char: '\u{1F3F3}\u{FE0F}\u{200D}\u{1F308}', name: 'rainbow flag', keywords: ['pride', 'lgbtq'] },
+    ],
+  },
+];
+
+/**
+ * Search emojis across all categories by name or keyword.
+ * Returns matching EmojiEntry items, deduplicated by char.
+ */
+export function searchEmojis(query: string): EmojiEntry[] {
+  if (!query) return [];
+
+  const lowerQuery = query.toLowerCase();
+  const seen = new Set<string>();
+  const results: EmojiEntry[] = [];
+
+  // Search quick emojis first
+  for (const emoji of QUICK_EMOJIS) {
+    if (matchesQuery(emoji, lowerQuery) && !seen.has(emoji.char)) {
+      seen.add(emoji.char);
+      results.push(emoji);
+    }
+  }
+
+  // Then search all categories
+  for (const cat of EMOJI_CATEGORIES) {
+    for (const emoji of cat.emojis) {
+      if (matchesQuery(emoji, lowerQuery) && !seen.has(emoji.char)) {
+        seen.add(emoji.char);
+        results.push(emoji);
+      }
+    }
+  }
+
+  return results;
+}
+
+function matchesQuery(emoji: EmojiEntry, lowerQuery: string): boolean {
+  if (emoji.name.toLowerCase().includes(lowerQuery)) return true;
+  if (emoji.keywords) {
+    return emoji.keywords.some((kw) => kw.toLowerCase().includes(lowerQuery));
+  }
+  return false;
+}
diff --git a/packages/core/src/comments/source-position-map.ts b/packages/core/src/comments/source-position-map.ts
new file mode 100644
index 0000000..511c2c0
--- /dev/null
+++ b/packages/core/src/comments/source-position-map.ts
@@ -0,0 +1,460 @@
+/**
+ * Source Position Map for Comment Anchoring
+ *
+ * Strips markdown inline formatting from source while maintaining a parallel
+ * array mapping each plain-text character back to its source offset. This gives
+ * exact insertion points for comment footnote references without needing
+ * markdown-it's inline token positions.
+ */
+
+export interface SourcePositionMap {
+  rawSource: string;
+  plainText: string;
+  offsets: number[];
+  spans: FormattingSpan[];
+}
+
+export interface FormattingSpan {
+  sourceStart: number;
+  sourceEnd: number;
+  plainStart: number;
+  plainEnd: number;
+  type: 'bold' | 'italic' | 'strikethrough' | 'code' | 'link' | 'image' | 'escape';
+}
+
+export interface SelectionContext {
+  prefix: string;
+  suffix: string;
+}
+
+const V1_SENTINEL = '<!-- mdview:comments -->';
+const V2_SENTINEL_PREFIX = '<!-- mdview:annotations';
+
+/**
+ * Find the annotation/comment boundary in the markdown.
+ * Returns the index of the earlier of v1 or v2 sentinel, or -1 if neither.
+ */
+function findAnnotationBoundary(markdown: string): number {
+  const v1 = markdown.indexOf(V1_SENTINEL);
+  const v2 = markdown.indexOf(V2_SENTINEL_PREFIX);
+  if (v1 === -1 && v2 === -1) return -1;
+  if (v1 === -1) return v2;
+  if (v2 === -1) return v1;
+  return Math.min(v1, v2);
+}
+
+/**
+ * Build a source position map from raw markdown.
+ * Processes only the content section (above annotation/comment boundary).
+ */
+export function buildSourceMap(rawMarkdown: string): SourcePositionMap {
+  const sepIdx = findAnnotationBoundary(rawMarkdown);
+  const rawSource = sepIdx === -1 ? rawMarkdown : rawMarkdown.slice(0, sepIdx);
+
+  const result = buildSourceMapRange(rawSource, 0, rawSource.length, 0);
+
+  return {
+    rawSource,
+    plainText: result.chars.join(''),
+    offsets: result.offsets,
+    spans: result.spans,
+  };
+}
+
+/**
+ * Find the correct insertion point in the raw source for a comment reference.
+ */
+export function findInsertionPoint(
+  map: SourcePositionMap,
+  selectedText: string,
+  context?: SelectionContext
+): number | null {
+  if (!selectedText) return null;
+
+  // Find all occurrences of selectedText in plainText
+  const matches: number[] = [];
+  let searchFrom = 0;
+  while (true) {
+    const idx = map.plainText.indexOf(selectedText, searchFrom);
+    if (idx === -1) break;
+    matches.push(idx);
+    searchFrom = idx + 1;
+  }
+
+  if (matches.length === 0) return null;
+
+  let bestMatch = matches[0];
+
+  // Disambiguate using context if multiple matches and context provided
+  if (matches.length > 1 && context) {
+    let bestScore = -1;
+    for (const matchIdx of matches) {
+      let score = 0;
+      // Score by prefix match
+      if (context.prefix) {
+        const plainBefore = map.plainText.slice(
+          Math.max(0, matchIdx - context.prefix.length),
+          matchIdx
+        );
+        score += commonSuffixLength(context.prefix, plainBefore);
+      }
+      // Score by suffix match
+      if (context.suffix) {
+        const plainAfter = map.plainText.slice(
+          matchIdx + selectedText.length,
+          matchIdx + selectedText.length + context.suffix.length
+        );
+        score += commonPrefixLength(context.suffix, plainAfter);
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        bestMatch = matchIdx;
+      }
+    }
+  }
+
+  // Map the match end position back to source
+  const plainEndIdx = bestMatch + selectedText.length - 1;
+  if (plainEndIdx >= map.offsets.length) return null;
+
+  const sourcePos = map.offsets[plainEndIdx] + 1;
+
+  // Check if the position falls inside any formatting spans.
+  // Use the outermost span's sourceEnd to avoid inserting inside nested constructs.
+  let insertAt = sourcePos;
+  for (const span of map.spans) {
+    if (
+      bestMatch >= span.plainStart &&
+      bestMatch + selectedText.length <= span.plainEnd &&
+      span.type !== 'escape' &&
+      sourcePos < span.sourceEnd
+    ) {
+      insertAt = Math.max(insertAt, span.sourceEnd);
+    }
+  }
+
+  return insertAt;
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────
+
+function isEscapable(ch: string): boolean {
+  return '\\`*_{}[]()#+-.!~>|'.includes(ch);
+}
+
+interface ParseResult {
+  span: FormattingSpan;
+  text: string;
+  contentStart: number;
+  contentEnd: number;
+}
+
+function parseInlineCode(src: string, start: number, plainPos: number): ParseResult | null {
+  // Count opening backticks
+  let ticks = 0;
+  let i = start;
+  while (i < src.length && src[i] === '`') {
+    ticks++;
+    i++;
+  }
+
+  // Find matching closing backticks
+  const closer = '`'.repeat(ticks);
+  const closeIdx = src.indexOf(closer, i);
+  if (closeIdx === -1) return null;
+
+  // Verify exact match (no extra backticks)
+  if (closeIdx + ticks < src.length && src[closeIdx + ticks] === '`') return null;
+
+  const contentStart = i;
+  const contentEnd = closeIdx;
+  const content = src.slice(contentStart, contentEnd);
+
+  return {
+    span: {
+      sourceStart: start,
+      sourceEnd: closeIdx + ticks,
+      plainStart: plainPos,
+      plainEnd: plainPos + content.length,
+      type: 'code',
+    },
+    text: content,
+    contentStart,
+    contentEnd,
+  };
+}
+
+function parseLinkOrImage(
+  src: string,
+  start: number,
+  plainPos: number,
+  isImage: boolean
+): ParseResult | null {
+  const bracketStart = isImage ? start + 2 : start + 1; // skip `![` or `[`
+  let depth = 1;
+  let i = bracketStart;
+
+  // Find the matching `]`
+  while (i < src.length && depth > 0) {
+    if (src[i] === '\\' && i + 1 < src.length) {
+      i += 2;
+      continue;
+    }
+    if (src[i] === '[') depth++;
+    if (src[i] === ']') depth--;
+    if (depth > 0) i++;
+  }
+
+  if (depth !== 0) return null;
+  const bracketEnd = i; // position of `]`
+
+  // Expect `(` immediately after `]`
+  if (bracketEnd + 1 >= src.length || src[bracketEnd + 1] !== '(') return null;
+
+  // Find matching `)`
+  let parenDepth = 1;
+  let j = bracketEnd + 2;
+  while (j < src.length && parenDepth > 0) {
+    if (src[j] === '\\' && j + 1 < src.length) {
+      j += 2;
+      continue;
+    }
+    if (src[j] === '(') parenDepth++;
+    if (src[j] === ')') parenDepth--;
+    if (parenDepth > 0) j++;
+  }
+
+  if (parenDepth !== 0) return null;
+
+  return {
+    span: {
+      sourceStart: start,
+      sourceEnd: j + 1, // after `)`
+      plainStart: plainPos,
+      plainEnd: plainPos, // will be updated by caller
+      type: isImage ? 'image' : 'link',
+    },
+    text: src.slice(bracketStart, bracketEnd),
+    contentStart: bracketStart,
+    contentEnd: bracketEnd,
+  };
+}
+
+interface DelimitedResult {
+  span: FormattingSpan;
+  contentStart: number;
+  contentEnd: number;
+}
+
+function parseDelimited(
+  src: string,
+  start: number,
+  marker: string,
+  plainPos: number,
+  type: FormattingSpan['type'],
+  searchEnd: number = src.length
+): DelimitedResult | null {
+  const mLen = marker.length;
+  const contentStart = start + mLen;
+
+  // Don't match if there's a space right after the opening marker
+  if (contentStart >= searchEnd || src[contentStart] === ' ') return null;
+
+  // Find the closing marker (not preceded by space, not escaped)
+  let i = contentStart;
+  while (i < searchEnd) {
+    if (src[i] === '\\' && i + 1 < searchEnd) {
+      i += 2;
+      continue;
+    }
+    if (src.startsWith(marker, i) && src[i - 1] !== ' ') {
+      // For ** or __, make sure we don't match a longer run
+      if (mLen === 2) {
+        // Make sure we don't have a third marker char within search range
+        if (i + mLen < searchEnd && src[i + mLen] === marker[0]) {
+          i++;
+          continue;
+        }
+      }
+      if (mLen === 1) {
+        // For single marker, make sure there's no second marker char within search range
+        if (i + 1 < searchEnd && src[i + 1] === marker[0]) {
+          i++;
+          continue;
+        }
+      }
+      return {
+        span: {
+          sourceStart: start,
+          sourceEnd: i + mLen,
+          plainStart: plainPos,
+          plainEnd: plainPos, // will be updated
+          type,
+        },
+        contentStart,
+        contentEnd: i,
+      };
+    }
+    i++;
+  }
+
+  return null;
+}
+
+function buildSourceMapRange(
+  src: string,
+  start: number,
+  end: number,
+  basePlainPos: number
+): { chars: string[]; offsets: number[]; spans: FormattingSpan[] } {
+  const chars: string[] = [];
+  const offsets: number[] = [];
+  const spans: FormattingSpan[] = [];
+  let i = start;
+
+  while (i < end) {
+    // Escape sequences
+    if (src[i] === '\\' && i + 1 < end && isEscapable(src[i + 1])) {
+      const plainPos = basePlainPos + chars.length;
+      spans.push({
+        sourceStart: i,
+        sourceEnd: i + 2,
+        plainStart: plainPos,
+        plainEnd: plainPos + 1,
+        type: 'escape',
+      });
+      chars.push(src[i + 1]);
+      offsets.push(i + 1);
+      i += 2;
+      continue;
+    }
+
+    // Inline code
+    if (src[i] === '`') {
+      const plainPos = basePlainPos + chars.length;
+      const result = parseInlineCode(src, i, plainPos);
+      if (result && result.span.sourceEnd <= end) {
+        spans.push(result.span);
+        for (let j = 0; j < result.text.length; j++) {
+          chars.push(result.text[j]);
+          offsets.push(result.contentStart + j);
+        }
+        i = result.span.sourceEnd;
+        continue;
+      }
+    }
+
+    // Images
+    if (src[i] === '!' && i + 1 < end && src[i + 1] === '[') {
+      const plainPos = basePlainPos + chars.length;
+      const result = parseLinkOrImage(src, i, plainPos, true);
+      if (result && result.span.sourceEnd <= end) {
+        spans.push(result.span);
+        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
+        for (const ch of inner.chars) chars.push(ch);
+        for (const off of inner.offsets) offsets.push(off);
+        for (const sp of inner.spans) spans.push(sp);
+        result.span.plainEnd = basePlainPos + chars.length;
+        i = result.span.sourceEnd;
+        continue;
+      }
+    }
+
+    // Links
+    if (src[i] === '[') {
+      const plainPos = basePlainPos + chars.length;
+      const result = parseLinkOrImage(src, i, plainPos, false);
+      if (result && result.span.sourceEnd <= end) {
+        spans.push(result.span);
+        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
+        for (const ch of inner.chars) chars.push(ch);
+        for (const off of inner.offsets) offsets.push(off);
+        for (const sp of inner.spans) spans.push(sp);
+        result.span.plainEnd = basePlainPos + chars.length;
+        i = result.span.sourceEnd;
+        continue;
+      }
+    }
+
+    // Bold
+    if (
+      (src[i] === '*' && i + 1 < end && src[i + 1] === '*') ||
+      (src[i] === '_' && i + 1 < end && src[i + 1] === '_')
+    ) {
+      const marker = src.slice(i, i + 2);
+      const plainPos = basePlainPos + chars.length;
+      const result = parseDelimited(src, i, marker, plainPos, 'bold', end);
+      if (result && result.span.sourceEnd <= end) {
+        spans.push(result.span);
+        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
+        for (const ch of inner.chars) chars.push(ch);
+        for (const off of inner.offsets) offsets.push(off);
+        for (const sp of inner.spans) spans.push(sp);
+        result.span.plainEnd = basePlainPos + chars.length;
+        i = result.span.sourceEnd;
+        continue;
+      }
+    }
+
+    // Strikethrough
+    if (src[i] === '~' && i + 1 < end && src[i + 1] === '~') {
+      const plainPos = basePlainPos + chars.length;
+      const result = parseDelimited(src, i, '~~', plainPos, 'strikethrough', end);
+      if (result && result.span.sourceEnd <= end) {
+        spans.push(result.span);
+        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
+        for (const ch of inner.chars) chars.push(ch);
+        for (const off of inner.offsets) offsets.push(off);
+        for (const sp of inner.spans) spans.push(sp);
+        result.span.plainEnd = basePlainPos + chars.length;
+        i = result.span.sourceEnd;
+        continue;
+      }
+    }
+
+    // Italic (single marker)
+    if (src[i] === '*' || src[i] === '_') {
+      const marker = src[i];
+      const plainPos = basePlainPos + chars.length;
+      const result = parseDelimited(src, i, marker, plainPos, 'italic', end);
+      if (result && result.span.sourceEnd <= end) {
+        spans.push(result.span);
+        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
+        for (const ch of inner.chars) chars.push(ch);
+        for (const off of inner.offsets) offsets.push(off);
+        for (const sp of inner.spans) spans.push(sp);
+        result.span.plainEnd = basePlainPos + chars.length;
+        i = result.span.sourceEnd;
+        continue;
+      }
+    }
+
+    // Plain character
+    chars.push(src[i]);
+    offsets.push(i);
+    i++;
+  }
+
+  return { chars, offsets, spans };
+}
+
+function commonSuffixLength(a: string, b: string): number {
+  let count = 0;
+  let ai = a.length - 1;
+  let bi = b.length - 1;
+  while (ai >= 0 && bi >= 0 && a[ai] === b[bi]) {
+    count++;
+    ai--;
+    bi--;
+  }
+  return count;
+}
+
+function commonPrefixLength(a: string, b: string): number {
+  let count = 0;
+  const limit = Math.min(a.length, b.length);
+  while (count < limit && a[count] === b[count]) {
+    count++;
+  }
+  return count;
+}
diff --git a/src/comments/annotation-parser.ts b/src/comments/annotation-parser.ts
index d3a0fb2..4397b68 100644
--- a/src/comments/annotation-parser.ts
+++ b/src/comments/annotation-parser.ts
@@ -1,187 +1 @@
-/**
- * Annotation Parser (v2) — unified entry point for parsing both v1 and v2
- * comment formats from markdown.
- *
- * v2 uses `[@N]` inline markers and a structured JSON annotation block
- * in `<!-- mdview:annotations [...] -->` at the end of the document.
- *
- * v1 uses `[^comment-N]` footnote references and `<!-- mdview:comments -->`
- * separator with footnote definitions.
- */
-
-import type { Comment, CommentContext, CommentParseResult, CommentReply } from '../types';
-import { parseComments } from './comment-parser';
-
-const V1_SENTINEL = '<!-- mdview:comments -->';
-const V2_SENTINEL_PREFIX = '<!-- mdview:annotations';
-const V2_MARKER_PATTERN = /\[@\d+\]/g;
-const V2_BLOCK_PATTERN = /<!-- mdview:annotations\s+(\[[\s\S]*?\])\s*-->/;
-
-/**
- * v2 annotation JSON shape (as stored in the markdown file).
- */
-interface Annotation {
-  id: number;
-  anchor: {
-    text: string;
-    prefix?: string;
-    suffix?: string;
-  };
-  body: string;
-  author: string;
-  date: string;
-  resolved?: boolean;
-  tags?: string[];
-  thread?: Array<{
-    author: string;
-    body: string;
-    date: string;
-  }>;
-  reactions?: Record<string, string[]>;
-  context?: {
-    line?: number;
-    section?: string;
-    sectionLevel?: number;
-    breadcrumb?: string[];
-  };
-}
-
-/**
- * Detect whether a markdown string uses v1, v2, or no comment format.
- */
-export function detectFormat(markdown: string): 'v1' | 'v2' | 'none' {
-  const hasV1 = markdown.includes(V1_SENTINEL);
-  const hasV2 = markdown.includes(V2_SENTINEL_PREFIX);
-
-  if (hasV1) return 'v1';
-  if (hasV2) return 'v2';
-  return 'none';
-}
-
-/**
- * Parse annotations from markdown text.
- * Detects format automatically: v1 is delegated to comment-parser,
- * v2 is handled natively.
- */
-export function parseAnnotations(markdown: string): CommentParseResult {
-  const format = detectFormat(markdown);
-
-  if (format === 'v1') {
-    return parseComments(markdown);
-  }
-
-  if (format === 'v2') {
-    return parseV2(markdown);
-  }
-
-  return { cleanedMarkdown: markdown, comments: [] };
-}
-
-/**
- * Alias for backward-compatible import as `parseComments`.
- */
-export { parseAnnotations as parseComments };
-
-/**
- * Parse v2 annotation format.
- */
-function parseV2(markdown: string): CommentParseResult {
-  // Find the annotation block
-  const blockMatch = markdown.match(V2_BLOCK_PATTERN);
-  if (!blockMatch) {
-    // Has sentinel prefix but malformed — strip markers and return empty
-    const cleanedMarkdown = stripV2Markers(stripV2Block(markdown));
-    return { cleanedMarkdown, comments: [] };
-  }
-
-  // Parse JSON array
-  let annotations: Annotation[];
-  try {
-    annotations = JSON.parse(blockMatch[1]) as Annotation[];
-  } catch {
-    console.warn('[MDView] Failed to parse v2 annotation JSON');
-    const cleanedMarkdown = stripV2Markers(stripV2Block(markdown));
-    return { cleanedMarkdown, comments: [] };
-  }
-
-  // Build Comment objects
-  const comments = annotations.map(annotationToComment);
-
-  // Remove the annotation block and [@N] markers from content
-  const cleanedMarkdown = stripV2Markers(stripV2Block(markdown));
-
-  return { cleanedMarkdown, comments };
-}
-
-/**
- * Remove the `<!-- mdview:annotations [...] -->` block from the end of the document.
- */
-function stripV2Block(markdown: string): string {
-  const idx = markdown.indexOf(V2_SENTINEL_PREFIX);
-  if (idx === -1) return markdown;
-  return markdown.slice(0, idx).trimEnd();
-}
-
-/**
- * Remove all `[@N]` markers from content.
- */
-function stripV2Markers(content: string): string {
-  return content.replace(V2_MARKER_PATTERN, '');
-}
-
-/**
- * Convert a v2 annotation JSON object to an internal Comment.
- */
-function annotationToComment(annotation: Annotation): Comment {
-  const comment: Comment = {
-    id: `comment-${annotation.id}`,
-    selectedText: annotation.anchor.text,
-    body: annotation.body,
-    author: annotation.author,
-    date: annotation.date,
-    resolved: annotation.resolved ?? false,
-  };
-
-  // Anchor context
-  if (annotation.anchor.prefix) {
-    comment.anchorPrefix = annotation.anchor.prefix;
-  }
-  if (annotation.anchor.suffix) {
-    comment.anchorSuffix = annotation.anchor.suffix;
-  }
-
-  // Positional context
-  if (annotation.context && annotation.context.line !== undefined) {
-    const ctx: CommentContext = {
-      line: annotation.context.line,
-      section: annotation.context.section,
-      sectionLevel: annotation.context.sectionLevel,
-      breadcrumb: annotation.context.breadcrumb ?? [],
-    };
-    comment.context = ctx;
-  }
-
-  // Tags
-  if (annotation.tags && annotation.tags.length > 0) {
-    comment.tags = annotation.tags as Comment['tags'];
-  }
-
-  // Thread → replies
-  if (annotation.thread && annotation.thread.length > 0) {
-    comment.replies = annotation.thread.map(
-      (t, i): CommentReply => ({
-        id: `reply-${i + 1}`,
-        author: t.author,
-        body: t.body,
-        date: t.date,
-      })
-    );
-  }
-
-  // Reactions
-  if (annotation.reactions && Object.keys(annotation.reactions).length > 0) {
-    comment.reactions = annotation.reactions;
-  }
-
-  return comment;
-}
+export * from '../../packages/core/src/comments/annotation-parser';
diff --git a/src/comments/annotation-serializer.ts b/src/comments/annotation-serializer.ts
index cbc563f..8159fb0 100644
--- a/src/comments/annotation-serializer.ts
+++ b/src/comments/annotation-serializer.ts
@@ -1,497 +1 @@
-/**
- * Annotation Serializer (v2)
- *
- * Generates markdown with `[@N]` inline markers and a structured JSON
- * annotation block in `<!-- mdview:annotations [...] -->`.
- *
- * Drop-in replacement for comment-serializer: same exported function
- * signatures. On v1 input, automatically migrates to v2 format.
- */
-
-import type { Comment, CommentReply } from '../types';
-import type { SourcePositionMap, SelectionContext } from './source-position-map';
-import { findInsertionPoint } from './source-position-map';
-import { parseComments } from './comment-parser';
-
-const V1_SENTINEL = '<!-- mdview:comments -->';
-const V2_SENTINEL_PREFIX = '<!-- mdview:annotations';
-const V2_BLOCK_PATTERN = /<!-- mdview:annotations\s+(\[[\s\S]*?\])\s*-->/;
-const V2_MARKER_PATTERN = /\[@(\d+)\]/g;
-
-// ─── v2 annotation JSON shape ────────────────────────────────────────
-
-interface Annotation {
-  id: number;
-  anchor: { text: string; prefix?: string; suffix?: string };
-  body: string;
-  author: string;
-  date: string;
-  resolved?: boolean;
-  tags?: string[];
-  thread?: Array<{ author: string; body: string; date: string }>;
-  reactions?: Record<string, string[]>;
-  context?: {
-    line?: number;
-    section?: string;
-    sectionLevel?: number;
-    breadcrumb?: string[];
-  };
-}
-
-// ─── Internal helpers ────────────────────────────────────────────────
-
-/**
- * Split markdown into content (above annotation block) and annotations array.
- */
-function splitAtAnnotationBlock(
-  markdown: string
-): [string, Annotation[] | null] {
-  const blockMatch = markdown.match(V2_BLOCK_PATTERN);
-  if (!blockMatch) {
-    return [markdown, null];
-  }
-
-  const blockStart = markdown.indexOf(V2_SENTINEL_PREFIX);
-  const content = markdown.slice(0, blockStart);
-
-  try {
-    const annotations = JSON.parse(blockMatch[1]) as Annotation[];
-    return [content, annotations];
-  } catch {
-    return [content, null];
-  }
-}
-
-/**
- * Pretty-print the annotation block with 2-space indentation.
- */
-function serializeAnnotationBlock(annotations: Annotation[]): string {
-  const json = JSON.stringify(annotations, null, 2);
-  return `<!-- mdview:annotations ${json} -->`;
-}
-
-/**
- * Convert an internal Comment to a v2 annotation JSON object.
- */
-function commentToAnnotation(comment: Comment): Annotation {
-  const numId = parseInt(comment.id.replace('comment-', ''), 10);
-
-  const anchor: Annotation['anchor'] = { text: comment.selectedText };
-  if (comment.anchorPrefix) anchor.prefix = comment.anchorPrefix;
-  if (comment.anchorSuffix) anchor.suffix = comment.anchorSuffix;
-
-  const annotation: Annotation = {
-    id: numId,
-    anchor,
-    body: comment.body,
-    author: comment.author,
-    date: comment.date,
-  };
-
-  if (comment.resolved) {
-    annotation.resolved = true;
-  }
-
-  if (comment.tags && comment.tags.length > 0) {
-    annotation.tags = comment.tags;
-  }
-
-  if (comment.replies && comment.replies.length > 0) {
-    annotation.thread = comment.replies.map((r) => ({
-      author: r.author,
-      body: r.body,
-      date: r.date,
-    }));
-  }
-
-  if (comment.reactions && Object.keys(comment.reactions).length > 0) {
-    annotation.reactions = comment.reactions;
-  }
-
-  if (comment.context) {
-    const ctx: Annotation['context'] = {};
-    if (comment.context.line !== undefined) ctx.line = comment.context.line;
-    if (comment.context.section !== undefined)
-      ctx.section = comment.context.section;
-    if (comment.context.sectionLevel !== undefined)
-      ctx.sectionLevel = comment.context.sectionLevel;
-    if (comment.context.breadcrumb && comment.context.breadcrumb.length > 0)
-      ctx.breadcrumb = comment.context.breadcrumb;
-    if (Object.keys(ctx).length > 0) annotation.context = ctx;
-  }
-
-  return annotation;
-}
-
-/**
- * Convert a v2 annotation to an internal Comment.
- */
-function annotationToComment(annotation: Annotation): Comment {
-  const comment: Comment = {
-    id: `comment-${annotation.id}`,
-    selectedText: annotation.anchor.text,
-    body: annotation.body,
-    author: annotation.author,
-    date: annotation.date,
-    resolved: annotation.resolved ?? false,
-  };
-
-  if (annotation.anchor.prefix) comment.anchorPrefix = annotation.anchor.prefix;
-  if (annotation.anchor.suffix) comment.anchorSuffix = annotation.anchor.suffix;
-
-  if (annotation.tags && annotation.tags.length > 0) {
-    comment.tags = annotation.tags as Comment['tags'];
-  }
-
-  if (annotation.thread && annotation.thread.length > 0) {
-    comment.replies = annotation.thread.map(
-      (t, i): CommentReply => ({
-        id: `reply-${i + 1}`,
-        author: t.author,
-        body: t.body,
-        date: t.date,
-      })
-    );
-  }
-
-  if (annotation.reactions && Object.keys(annotation.reactions).length > 0) {
-    comment.reactions = annotation.reactions;
-  }
-
-  if (annotation.context && annotation.context.line !== undefined) {
-    comment.context = {
-      line: annotation.context.line,
-      section: annotation.context.section,
-      sectionLevel: annotation.context.sectionLevel,
-      breadcrumb: annotation.context.breadcrumb ?? [],
-    };
-  }
-
-  return comment;
-}
-
-/**
- * Detect v1 sentinel and fully migrate to v2 format.
- * Returns the markdown with all v1 content replaced by v2.
- */
-function migrateV1Content(markdown: string): string {
-  const result = parseComments(markdown);
-
-  // Start with cleaned content (v1 refs already stripped by parser)
-  let content = result.cleanedMarkdown;
-
-  // Re-insert markers in v2 format
-  for (const comment of result.comments) {
-    const numId = parseInt(comment.id.replace('comment-', ''), 10);
-    const marker = `[@${numId}]`;
-    const idx = content.indexOf(comment.selectedText);
-    if (idx !== -1) {
-      const insertPos = idx + comment.selectedText.length;
-      content = content.slice(0, insertPos) + marker + content.slice(insertPos);
-    }
-  }
-
-  // Build annotation block
-  const annotations = result.comments.map(commentToAnnotation);
-  const block = serializeAnnotationBlock(annotations);
-
-  return content.trimEnd() + '\n\n' + block + '\n';
-}
-
-/**
- * If markdown contains v1 sentinel, migrate it. Otherwise return as-is.
- */
-function ensureV2(markdown: string): string {
-  if (markdown.includes(V1_SENTINEL)) {
-    return migrateV1Content(markdown);
-  }
-  return markdown;
-}
-
-/**
- * Insert a `[@N]` marker after the first unmatched occurrence of selectedText
- * in the content section.
- */
-function insertMarker(
-  contentSection: string,
-  selectedText: string,
-  numId: number
-): string {
-  const marker = `[@${numId}]`;
-  const escapedText = selectedText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  // Find first occurrence not already followed by [@N]
-  const pattern = new RegExp(`${escapedText}(?!\\[@\\d+\\])`);
-  const match = pattern.exec(contentSection);
-  if (match) {
-    const insertPos = match.index + match[0].length;
-    return (
-      contentSection.slice(0, insertPos) +
-      marker +
-      contentSection.slice(insertPos)
-    );
-  }
-  // Fallback: append to first occurrence
-  const idx = contentSection.indexOf(selectedText);
-  if (idx !== -1) {
-    const insertPos = idx + selectedText.length;
-    return (
-      contentSection.slice(0, insertPos) +
-      marker +
-      contentSection.slice(insertPos)
-    );
-  }
-  return contentSection;
-}
-
-// ─── Exported API (same signatures as v1 serializer) ─────────────────
-
-/**
- * Scan for `[@N]` markers and annotation `"id": N` to find the next ID.
- */
-export function generateNextCommentId(markdown: string): string {
-  let max = 0;
-
-  // Check [@N] markers
-  let match: RegExpExecArray | null;
-  const markerPattern = new RegExp(V2_MARKER_PATTERN.source, 'g');
-  while ((match = markerPattern.exec(markdown)) !== null) {
-    const num = parseInt(match[1], 10);
-    if (num > max) max = num;
-  }
-
-  // Check "id": N in annotation block
-  const idPattern = /"id":\s*(\d+)/g;
-  while ((match = idPattern.exec(markdown)) !== null) {
-    const num = parseInt(match[1], 10);
-    if (num > max) max = num;
-  }
-
-  // Also check v1 patterns for migration scenarios
-  const v1Pattern = /\[\^comment-(\d+)\]/g;
-  while ((match = v1Pattern.exec(markdown)) !== null) {
-    const num = parseInt(match[1], 10);
-    if (num > max) max = num;
-  }
-
-  return `comment-${max + 1}`;
-}
-
-/**
- * Add a comment: insert `[@N]` marker after selectedText, append to annotation block.
- */
-export function addComment(markdown: string, comment: Comment): string {
-  // Migrate v1 if needed
-  const md = ensureV2(markdown);
-
-  const [contentSection, existingAnnotations] = splitAtAnnotationBlock(md);
-  const numId = parseInt(comment.id.replace('comment-', ''), 10);
-
-  // Insert marker in content
-  const updatedContent = insertMarker(contentSection, comment.selectedText, numId);
-
-  // Build annotation
-  const annotation = commentToAnnotation(comment);
-
-  const annotations = existingAnnotations ? [...existingAnnotations, annotation] : [annotation];
-  const block = serializeAnnotationBlock(annotations);
-
-  return updatedContent.trimEnd() + '\n\n' + block + '\n';
-}
-
-/**
- * Add a comment using a pre-built source position map for accurate insertion.
- * Falls back to `addComment()` if the map can't find the position.
- */
-export function addCommentAtOffset(
-  markdown: string,
-  comment: Comment,
-  sourceMap: SourcePositionMap,
-  context?: SelectionContext
-): string {
-  const offset = findInsertionPoint(sourceMap, comment.selectedText, context);
-
-  if (offset === null) {
-    return addComment(markdown, comment);
-  }
-
-  // Migrate v1 if needed
-  const md = ensureV2(markdown);
-
-  const [contentSection, existingAnnotations] = splitAtAnnotationBlock(md);
-  const numId = parseInt(comment.id.replace('comment-', ''), 10);
-  const marker = `[@${numId}]`;
-
-  // Insert marker at exact offset
-  const updatedContent =
-    contentSection.slice(0, offset) + marker + contentSection.slice(offset);
-
-  const annotation = commentToAnnotation(comment);
-  const annotations = existingAnnotations ? [...existingAnnotations, annotation] : [annotation];
-  const block = serializeAnnotationBlock(annotations);
-
-  return updatedContent.trimEnd() + '\n\n' + block + '\n';
-}
-
-/**
- * Remove a comment: remove `[@N]` marker and annotation entry.
- * Removes block entirely if no annotations remain.
- */
-export function removeComment(markdown: string, commentId: string): string {
-  const md = ensureV2(markdown);
-
-  const [contentSection, annotations] = splitAtAnnotationBlock(md);
-
-  if (!annotations) {
-    // No annotation block — just strip any markers
-    const numId = parseInt(commentId.replace('comment-', ''), 10);
-    return contentSection.split(`[@${numId}]`).join('');
-  }
-
-  const numId = parseInt(commentId.replace('comment-', ''), 10);
-
-  // Remove inline marker
-  const cleanedContent = contentSection.split(`[@${numId}]`).join('');
-
-  // Remove annotation entry
-  const remaining = annotations.filter((a) => a.id !== numId);
-
-  if (remaining.length === 0) {
-    return cleanedContent.trimEnd() + '\n';
-  }
-
-  const block = serializeAnnotationBlock(remaining);
-  return cleanedContent.trimEnd() + '\n\n' + block + '\n';
-}
-
-/**
- * Update a comment's body in the annotation block.
- */
-export function updateComment(
-  markdown: string,
-  commentId: string,
-  newBody: string
-): string {
-  const md = ensureV2(markdown);
-
-  const [contentSection, annotations] = splitAtAnnotationBlock(md);
-  if (!annotations) return markdown;
-
-  const numId = parseInt(commentId.replace('comment-', ''), 10);
-  let found = false;
-
-  const updated = annotations.map((a) => {
-    if (a.id === numId) {
-      found = true;
-      return { ...a, body: newBody };
-    }
-    return a;
-  });
-
-  if (!found) return markdown;
-
-  const block = serializeAnnotationBlock(updated);
-  return contentSection.trimEnd() + '\n\n' + block + '\n';
-}
-
-/**
- * Resolve a comment: set `resolved: true`.
- */
-export function resolveComment(markdown: string, commentId: string): string {
-  return updateCommentMetadata(markdown, commentId, (c) => {
-    c.resolved = true;
-  });
-}
-
-/**
- * Generic metadata updater: parse annotation, call updater to mutate
- * the Comment, then re-serialize.
- */
-export function updateCommentMetadata(
-  markdown: string,
-  commentId: string,
-  updater: (comment: Comment) => void
-): string {
-  const md = ensureV2(markdown);
-
-  const [contentSection, annotations] = splitAtAnnotationBlock(md);
-  if (!annotations) return markdown;
-
-  const numId = parseInt(commentId.replace('comment-', ''), 10);
-  let found = false;
-
-  const updated = annotations.map((a) => {
-    if (a.id === numId) {
-      found = true;
-      const comment = annotationToComment(a);
-      updater(comment);
-      return commentToAnnotation(comment);
-    }
-    return a;
-  });
-
-  if (!found) return markdown;
-
-  const block = serializeAnnotationBlock(updated);
-  return contentSection.trimEnd() + '\n\n' + block + '\n';
-}
-
-/**
- * Add a reply to a comment's thread.
- */
-export function addReply(
-  markdown: string,
-  commentId: string,
-  reply: Omit<CommentReply, 'id'>
-): { markdown: string; replyId: string } {
-  let replyId = '';
-
-  const updated = updateCommentMetadata(markdown, commentId, (comment) => {
-    const replies = comment.replies ?? [];
-    let maxNum = 0;
-    for (const r of replies) {
-      const match = /^reply-(\d+)$/.exec(r.id);
-      if (match) {
-        const num = parseInt(match[1], 10);
-        if (num > maxNum) maxNum = num;
-      }
-    }
-    replyId = `reply-${maxNum + 1}`;
-    replies.push({ id: replyId, ...reply });
-    comment.replies = replies;
-  });
-
-  return { markdown: updated, replyId };
-}
-
-/**
- * Toggle an emoji reaction for an author on a comment.
- */
-export function toggleReaction(
-  markdown: string,
-  commentId: string,
-  emoji: string,
-  author: string
-): string {
-  return updateCommentMetadata(markdown, commentId, (comment) => {
-    const reactions = comment.reactions ?? {};
-    const authors = reactions[emoji] ?? [];
-
-    const idx = authors.indexOf(author);
-    if (idx >= 0) {
-      authors.splice(idx, 1);
-      if (authors.length === 0) {
-        delete reactions[emoji];
-      } else {
-        reactions[emoji] = authors;
-      }
-    } else {
-      reactions[emoji] = [...authors, author];
-    }
-
-    if (Object.keys(reactions).length > 0) {
-      comment.reactions = reactions;
-    } else {
-      delete comment.reactions;
-    }
-  });
-}
+export * from '../../packages/core/src/comments/annotation-serializer';
diff --git a/src/comments/comment-context.ts b/src/comments/comment-context.ts
index 901fd8e..295e89e 100644
--- a/src/comments/comment-context.ts
+++ b/src/comments/comment-context.ts
@@ -1,107 +1 @@
-/**
- * Comment Context Builder
- *
- * Computes positional context (line number, section heading, breadcrumb)
- * for a comment at a given character offset in markdown content. This
- * metadata is stored in the footnote definition so AI agents reading
- * the raw file can immediately understand where each comment is anchored.
- */
-
-import type { CommentContext } from '../types';
-import { splitIntoSections, type MarkdownSection } from '../utils/section-splitter';
-
-/**
- * Compute positional context for a comment at a given character offset
- * in the content section of markdown (above the comment separator).
- */
-export function computeCommentContext(
-  contentMarkdown: string,
-  charOffset: number
-): CommentContext {
-  const line = offsetToLine(contentMarkdown, charOffset);
-  const sections = splitIntoSections(contentMarkdown);
-  const { section, sectionLevel, breadcrumb } = findSectionContext(sections, line);
-
-  return {
-    line,
-    section,
-    sectionLevel,
-    breadcrumb,
-  };
-}
-
-/**
- * Convert a 0-based character offset to a 1-based line number.
- */
-function offsetToLine(text: string, offset: number): number {
-  const clamped = Math.min(offset, text.length);
-  let line = 1;
-  for (let i = 0; i < clamped; i++) {
-    if (text[i] === '\n') {
-      line++;
-    }
-  }
-  return line;
-}
-
-/**
- * Given sections from splitIntoSections() and a 1-based line number,
- * find the containing section and build the heading breadcrumb.
- */
-function findSectionContext(
-  sections: MarkdownSection[],
-  line: number
-): { section?: string; sectionLevel?: number; breadcrumb: string[] } {
-  // splitIntoSections uses 0-based line indices; our line is 1-based
-  const zeroLine = line - 1;
-
-  let containingSection: MarkdownSection | undefined;
-  for (const s of sections) {
-    if (zeroLine >= s.startLine && zeroLine <= s.endLine) {
-      containingSection = s;
-      break;
-    }
-  }
-
-  if (!containingSection || !containingSection.heading) {
-    return { breadcrumb: [] };
-  }
-
-  const breadcrumb = buildBreadcrumb(sections, containingSection);
-
-  return {
-    section: containingSection.heading,
-    sectionLevel: containingSection.level,
-    breadcrumb,
-  };
-}
-
-/**
- * Build a heading breadcrumb from the document start to the target section.
- *
- * Walk all sections up to and including the target. Maintain a stack:
- * when encountering a heading at level N, pop all headings at level >= N,
- * then push. The final stack is the breadcrumb.
- */
-function buildBreadcrumb(
-  sections: MarkdownSection[],
-  target: MarkdownSection
-): string[] {
-  const stack: Array<{ heading: string; level: number }> = [];
-
-  for (const s of sections) {
-    if (s.heading && s.level !== undefined) {
-      // Pop headings at same or deeper level
-      while (stack.length > 0 && stack[stack.length - 1].level >= s.level) {
-        stack.pop();
-      }
-      stack.push({ heading: s.heading, level: s.level });
-    }
-
-    if (s === target) {
-      break;
-    }
-  }
-
-  return stack.map((entry) => entry.heading);
-}
+export * from '../../packages/core/src/comments/comment-context';
diff --git a/src/comments/comment-parser.ts b/src/comments/comment-parser.ts
index e6c2b95..f379fa6 100644
--- a/src/comments/comment-parser.ts
+++ b/src/comments/comment-parser.ts
@@ -1,164 +1 @@
-/**
- * Comment parser for extracting structured comments from markdown footnotes.
- *
- * Comments are stored as footnotes with `[^comment-*]` references in the markdown
- * content, with metadata embedded in HTML comments following the `<!-- mdview:comment {...} -->`
- * pattern. A `<!-- mdview:comments -->` separator divides the document content from
- * the comment section.
- *
- * @deprecated Use `annotation-parser.ts` instead. This module is kept only for
- * v1 backward compatibility delegation from the annotation parser.
- */
-
-import type { Comment, CommentContext, CommentMetadata, CommentParseResult } from '../types';
-
-const COMMENT_SEPARATOR = '<!-- mdview:comments -->';
-const COMMENT_REF_PATTERN = /\[\^comment-(\w+)\]/g;
-const FOOTNOTE_DEF_PATTERN = /^\[\^comment-(\w+)\]:\s*<!-- mdview:comment\s+(.+?)\s*-->\s*$/;
-const BODY_CONTINUATION_PATTERN = /^    (.*)$/;
-
-/**
- * Parse comments from markdown text.
- *
- * Splits markdown at the `<!-- mdview:comments -->` separator, parses footnote
- * definitions from the comments section, extracts the selected text from the
- * content section, and returns cleaned markdown with comment references removed.
- */
-export function parseComments(markdown: string): CommentParseResult {
-  const separatorIndex = markdown.indexOf(COMMENT_SEPARATOR);
-
-  if (separatorIndex === -1) {
-    return { cleanedMarkdown: markdown, comments: [] };
-  }
-
-  const contentPortion = markdown.substring(0, separatorIndex);
-  const commentsPortion = markdown.substring(separatorIndex + COMMENT_SEPARATOR.length);
-
-  const comments = parseCommentFootnotes(commentsPortion, contentPortion);
-  const cleanedMarkdown = removeCommentReferences(contentPortion.trimEnd());
-
-  return { cleanedMarkdown, comments };
-}
-
-/**
- * Parse comment footnote definitions from the comments section of the markdown.
- */
-function parseCommentFootnotes(commentSection: string, contentSection: string): Comment[] {
-  const lines = commentSection.split('\n');
-  const comments: Comment[] = [];
-
-  let currentId: string | null = null;
-  let currentMetadata: CommentMetadata | null = null;
-  let currentBodyLines: string[] = [];
-
-  for (const line of lines) {
-    // Try to match a footnote definition line
-    const defMatch = line.match(FOOTNOTE_DEF_PATTERN);
-
-    if (defMatch) {
-      // Flush previous comment if any
-      if (currentId !== null && currentMetadata !== null) {
-        comments.push(buildComment(currentId, currentMetadata, currentBodyLines, contentSection));
-      }
-
-      currentId = defMatch[1];
-      currentBodyLines = [];
-
-      // Parse the JSON metadata
-      try {
-        currentMetadata = JSON.parse(defMatch[2]) as CommentMetadata;
-      } catch {
-        // Malformed JSON - skip this comment
-        currentId = null;
-        currentMetadata = null;
-        currentBodyLines = [];
-      }
-      continue;
-    }
-
-    // Try to match a continuation line (indented with 4 spaces)
-    if (currentId !== null && currentMetadata !== null) {
-      const bodyMatch = line.match(BODY_CONTINUATION_PATTERN);
-      if (bodyMatch) {
-        currentBodyLines.push(bodyMatch[1]);
-      }
-    }
-  }
-
-  // Flush the last comment
-  if (currentId !== null && currentMetadata !== null) {
-    comments.push(buildComment(currentId, currentMetadata, currentBodyLines, contentSection));
-  }
-
-  return comments;
-}
-
-/**
- * Build a Comment object from parsed footnote data.
- */
-function buildComment(
-  id: string,
-  metadata: CommentMetadata,
-  bodyLines: string[],
-  contentSection: string,
-): Comment {
-  const comment: Comment = {
-    id: `comment-${id}`,
-    selectedText: metadata.selectedText || extractSelectedText(id, contentSection),
-    body: bodyLines.join('\n'),
-    author: metadata.author,
-    date: metadata.date,
-    resolved: metadata.resolved ?? false,
-  };
-
-  // Reconstruct positional context if fields are present in metadata
-  if (metadata.line !== undefined) {
-    const context: CommentContext = {
-      line: metadata.line,
-      section: metadata.section,
-      sectionLevel: metadata.sectionLevel,
-      breadcrumb: metadata.breadcrumb ?? [],
-    };
-    comment.context = context;
-  }
-
-  // Reconstruct tags if present and non-empty
-  if (metadata.tags !== undefined && metadata.tags.length > 0) {
-    comment.tags = metadata.tags;
-  }
-
-  // Reconstruct replies if present and non-empty
-  if (metadata.replies !== undefined && metadata.replies.length > 0) {
-    comment.replies = metadata.replies;
-  }
-
-  // Reconstruct reactions if present and non-empty
-  if (metadata.reactions !== undefined && Object.keys(metadata.reactions).length > 0) {
-    comment.reactions = metadata.reactions;
-  }
-
-  return comment;
-}
-
-/**
- * Extract the word immediately before a `[^comment-N]` reference in the content.
- */
-function extractSelectedText(id: string, content: string): string {
-  const refPattern = new RegExp(`(\\S+)\\[\\^comment-${escapeRegExp(id)}\\]`);
-  const match = content.match(refPattern);
-  return match ? match[1] : '';
-}
-
-/**
- * Remove all `[^comment-*]` references from the content section.
- */
-function removeCommentReferences(content: string): string {
-  return content.replace(COMMENT_REF_PATTERN, '');
-}
-
-/**
- * Escape special regex characters in a string.
- */
-function escapeRegExp(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
+export * from '../../packages/core/src/comments/comment-parser';
diff --git a/src/comments/comment-serializer.ts b/src/comments/comment-serializer.ts
index 96a6a54..9c262f2 100644
--- a/src/comments/comment-serializer.ts
+++ b/src/comments/comment-serializer.ts
@@ -1,509 +1 @@
-/**
- * Comment Serializer (v1)
- *
- * Generates markdown with footnote references injected and footnote bodies appended.
- * Handles add, update, delete, and resolve operations on raw markdown strings.
- *
- * Markdown format:
- *   Some highlighted text[^comment-1] in context.
- *
- *   <!-- mdview:comments -->
- *   [^comment-1]: <!-- mdview:comment {"author":"reviewer","date":"2026-03-03T14:30:00Z"} -->
- *       This API endpoint needs error handling
- *       for the 404 case.
- *
- * @deprecated Use `annotation-serializer.ts` instead. This module is no longer
- * imported by production code.
- */
-
-import type { Comment, CommentMetadata, CommentReply } from '../types';
-import type { SourcePositionMap, SelectionContext } from './source-position-map';
-import { findInsertionPoint } from './source-position-map';
-
-const COMMENT_SEPARATOR = '<!-- mdview:comments -->';
-const COMMENT_ID_PATTERN = /\[\^comment-(\d+)\]/g;
-const FOOTNOTE_DEF_PATTERN =
-  /^\[\^(comment-\d+)\]: <!-- mdview:comment (.+?) -->/;
-
-/**
- * Scan the markdown for `[^comment-N]` patterns and return `comment-(max+1)`.
- */
-export function generateNextCommentId(markdown: string): string {
-  let max = 0;
-  let match: RegExpExecArray | null;
-  const pattern = new RegExp(COMMENT_ID_PATTERN.source, 'g');
-  while ((match = pattern.exec(markdown)) !== null) {
-    const num = parseInt(match[1], 10);
-    if (num > max) {
-      max = num;
-    }
-  }
-  return `comment-${max + 1}`;
-}
-
-/**
- * Build the metadata JSON string for a comment footnote.
- * Omits the `resolved` key when it is false/undefined to keep the format clean.
- */
-function buildMetadataJson(meta: CommentMetadata): string {
-  const obj: Record<string, unknown> = {
-    author: meta.author,
-    date: meta.date,
-  };
-  if (meta.resolved) {
-    obj.resolved = true;
-  }
-  if (meta.selectedText) {
-    obj.selectedText = meta.selectedText;
-  }
-  // Positional context fields
-  if (meta.line !== undefined) {
-    obj.line = meta.line;
-  }
-  if (meta.section !== undefined) {
-    obj.section = meta.section;
-  }
-  if (meta.sectionLevel !== undefined) {
-    obj.sectionLevel = meta.sectionLevel;
-  }
-  if (meta.breadcrumb !== undefined && meta.breadcrumb.length > 0) {
-    obj.breadcrumb = meta.breadcrumb;
-  }
-  if (meta.tags !== undefined && meta.tags.length > 0) {
-    obj.tags = meta.tags;
-  }
-  if (meta.replies !== undefined && meta.replies.length > 0) {
-    obj.replies = meta.replies;
-  }
-  if (meta.reactions !== undefined && Object.keys(meta.reactions).length > 0) {
-    obj.reactions = meta.reactions;
-  }
-  return JSON.stringify(obj);
-}
-
-/**
- * Format the footnote body lines, each indented with 4 spaces.
- */
-function formatFootnoteBody(body: string): string {
-  return body
-    .split('\n')
-    .map((line) => `    ${line}`)
-    .join('\n');
-}
-
-/**
- * Build a complete footnote definition block.
- */
-function buildFootnoteBlock(comment: Comment): string {
-  const meta: CommentMetadata = {
-    author: comment.author,
-    date: comment.date,
-  };
-  if (comment.resolved) {
-    meta.resolved = true;
-  }
-  if (comment.selectedText) {
-    meta.selectedText = comment.selectedText;
-  }
-  if (comment.context) {
-    meta.line = comment.context.line;
-    meta.section = comment.context.section;
-    meta.sectionLevel = comment.context.sectionLevel;
-    meta.breadcrumb = comment.context.breadcrumb;
-  }
-  if (comment.tags && comment.tags.length > 0) {
-    meta.tags = comment.tags;
-  }
-  if (comment.replies && comment.replies.length > 0) {
-    meta.replies = comment.replies;
-  }
-  if (comment.reactions && Object.keys(comment.reactions).length > 0) {
-    meta.reactions = comment.reactions;
-  }
-  const metaJson = buildMetadataJson(meta);
-  const header = `[^${comment.id}]: <!-- mdview:comment ${metaJson} -->`;
-  const body = formatFootnoteBody(comment.body);
-  return `${header}\n${body}`;
-}
-
-/**
- * Find the selectedText in the content portion of the markdown (above the
- * comments separator) and insert the footnote reference after the first
- * unmatched occurrence.
- *
- * "Unmatched" means the occurrence is not already immediately followed by
- * a `[^comment-N]` reference.
- */
-function insertReference(
-  contentSection: string,
-  selectedText: string,
-  commentId: string
-): string {
-  const ref = `[^${commentId}]`;
-  // We need to find the first occurrence of selectedText that is NOT
-  // already followed by [^comment-...]
-  const escapedText = selectedText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const pattern = new RegExp(
-    `${escapedText}(?!\\[\\^comment-\\d+\\])`,
-  );
-  const match = pattern.exec(contentSection);
-  if (match) {
-    const insertPos = match.index + match[0].length;
-    return (
-      contentSection.slice(0, insertPos) +
-      ref +
-      contentSection.slice(insertPos)
-    );
-  }
-  // Fallback: if no unmatched occurrence, just append to first occurrence
-  const idx = contentSection.indexOf(selectedText);
-  if (idx !== -1) {
-    const insertPos = idx + selectedText.length;
-    return (
-      contentSection.slice(0, insertPos) +
-      ref +
-      contentSection.slice(insertPos)
-    );
-  }
-  return contentSection;
-}
-
-/**
- * Split markdown into content (above separator) and comments section (below).
- * Returns [contentSection, commentsSection | null].
- */
-function splitAtSeparator(markdown: string): [string, string | null] {
-  const sepIdx = markdown.indexOf(COMMENT_SEPARATOR);
-  if (sepIdx === -1) {
-    return [markdown, null];
-  }
-  const content = markdown.slice(0, sepIdx);
-  const comments = markdown.slice(sepIdx + COMMENT_SEPARATOR.length);
-  return [content, comments];
-}
-
-/**
- * Add a comment: insert reference after selectedText, append footnote body
- * after separator.
- */
-export function addComment(markdown: string, comment: Comment): string {
-  const [contentSection, existingComments] = splitAtSeparator(markdown);
-
-  // Insert reference in content
-  const updatedContent = insertReference(
-    contentSection,
-    comment.selectedText,
-    comment.id
-  );
-
-  // Build footnote block
-  const footnoteBlock = buildFootnoteBlock(comment);
-
-  if (existingComments !== null) {
-    // Separator already exists; append the new footnote
-    const trimmedComments = existingComments.trimEnd();
-    return (
-      updatedContent +
-      COMMENT_SEPARATOR +
-      (trimmedComments ? trimmedComments + '\n\n' : '\n') +
-      footnoteBlock + '\n'
-    );
-  } else {
-    // No separator yet; add it
-    const trimmedContent = updatedContent.trimEnd();
-    return (
-      trimmedContent +
-      '\n\n' +
-      COMMENT_SEPARATOR +
-      '\n' +
-      footnoteBlock + '\n'
-    );
-  }
-}
-
-/**
- * Add a comment using a pre-built source position map for accurate insertion.
- * Falls back to `addComment()` (text-search based) if the map can't find the position.
- */
-export function addCommentAtOffset(
-  markdown: string,
-  comment: Comment,
-  sourceMap: SourcePositionMap,
-  context?: SelectionContext
-): string {
-  const offset = findInsertionPoint(sourceMap, comment.selectedText, context);
-
-  if (offset === null) {
-    // Fallback to text-search based insertion
-    return addComment(markdown, comment);
-  }
-
-  const [contentSection, existingComments] = splitAtSeparator(markdown);
-
-  // Insert the reference at the exact offset in the content section
-  const ref = `[^${comment.id}]`;
-  const updatedContent =
-    contentSection.slice(0, offset) + ref + contentSection.slice(offset);
-
-  // Build footnote block
-  const footnoteBlock = buildFootnoteBlock(comment);
-
-  if (existingComments !== null) {
-    const trimmedComments = existingComments.trimEnd();
-    return (
-      updatedContent +
-      COMMENT_SEPARATOR +
-      (trimmedComments ? trimmedComments + '\n\n' : '\n') +
-      footnoteBlock + '\n'
-    );
-  } else {
-    const trimmedContent = updatedContent.trimEnd();
-    return (
-      trimmedContent +
-      '\n\n' +
-      COMMENT_SEPARATOR +
-      '\n' +
-      footnoteBlock + '\n'
-    );
-  }
-}
-
-/**
- * Parse the comments section into individual footnote blocks.
- * Each block is: { id, headerLine, bodyLines[] }.
- */
-interface FootnoteBlock {
-  id: string;
-  headerLine: string;
-  bodyLines: string[];
-}
-
-function parseFootnoteBlocks(commentsSection: string): FootnoteBlock[] {
-  const lines = commentsSection.split('\n');
-  const blocks: FootnoteBlock[] = [];
-  let current: FootnoteBlock | null = null;
-
-  for (const line of lines) {
-    const defMatch = FOOTNOTE_DEF_PATTERN.exec(line);
-    if (defMatch) {
-      if (current) {
-        blocks.push(current);
-      }
-      current = {
-        id: defMatch[1],
-        headerLine: line,
-        bodyLines: [],
-      };
-    } else if (current && line.startsWith('    ')) {
-      current.bodyLines.push(line);
-    } else if (current && line.trim() === '') {
-      // Blank line between blocks -- finalize current
-      blocks.push(current);
-      current = null;
-    }
-  }
-  if (current) {
-    blocks.push(current);
-  }
-  return blocks;
-}
-
-/**
- * Serialize footnote blocks back to a comments section string.
- */
-function serializeFootnoteBlocks(blocks: FootnoteBlock[]): string {
-  return blocks
-    .map((b) => [b.headerLine, ...b.bodyLines].join('\n'))
-    .join('\n\n');
-}
-
-/**
- * Remove a comment: remove the inline reference and the footnote body.
- * Remove the separator if no comments remain.
- */
-export function removeComment(markdown: string, commentId: string): string {
-  const [contentSection, commentsSection] = splitAtSeparator(markdown);
-
-  // Remove inline reference [^commentId]
-  const ref = `[^${commentId}]`;
-  const cleanedContent = contentSection.split(ref).join('');
-
-  if (commentsSection === null) {
-    return cleanedContent;
-  }
-
-  // Parse and filter footnote blocks
-  const blocks = parseFootnoteBlocks(commentsSection);
-  const remaining = blocks.filter((b) => b.id !== commentId);
-
-  if (remaining.length === 0) {
-    // No comments remain; remove separator and trailing whitespace
-    return cleanedContent.trimEnd() + '\n';
-  }
-
-  // Rebuild with separator and remaining blocks
-  const serialized = serializeFootnoteBlocks(remaining);
-  return (
-    cleanedContent +
-    COMMENT_SEPARATOR +
-    '\n' +
-    serialized + '\n'
-  );
-}
-
-/**
- * Update a comment's body: replace the body lines under the matching footnote
- * while keeping the metadata header unchanged.
- */
-export function updateComment(
-  markdown: string,
-  commentId: string,
-  newBody: string
-): string {
-  const [contentSection, commentsSection] = splitAtSeparator(markdown);
-
-  if (commentsSection === null) {
-    return markdown;
-  }
-
-  const blocks = parseFootnoteBlocks(commentsSection);
-  const updatedBlocks = blocks.map((b) => {
-    if (b.id === commentId) {
-      return {
-        ...b,
-        bodyLines: newBody.split('\n').map((line) => `    ${line}`),
-      };
-    }
-    return b;
-  });
-
-  const serialized = serializeFootnoteBlocks(updatedBlocks);
-  return (
-    contentSection +
-    COMMENT_SEPARATOR +
-    '\n' +
-    serialized + '\n'
-  );
-}
-
-/**
- * Resolve a comment: parse the metadata JSON, set resolved:true, re-serialize.
- */
-export function resolveComment(markdown: string, commentId: string): string {
-  return updateCommentMetadata(markdown, commentId, (meta) => {
-    meta.resolved = true;
-  });
-}
-
-/**
- * Generic metadata updater: parse a comment's metadata JSON, call the updater
- * function to mutate it, then rebuild the header line. Preserves body and
- * other comments.
- */
-export function updateCommentMetadata(
-  markdown: string,
-  commentId: string,
-  updater: (meta: CommentMetadata) => void
-): string {
-  const [contentSection, commentsSection] = splitAtSeparator(markdown);
-
-  if (commentsSection === null) {
-    return markdown;
-  }
-
-  const blocks = parseFootnoteBlocks(commentsSection);
-  let found = false;
-
-  const updatedBlocks = blocks.map((b) => {
-    if (b.id === commentId) {
-      const defMatch = FOOTNOTE_DEF_PATTERN.exec(b.headerLine);
-      if (defMatch) {
-        found = true;
-        const meta: CommentMetadata = JSON.parse(defMatch[2]);
-        updater(meta);
-        const metaJson = buildMetadataJson(meta);
-        const newHeader = `[^${b.id}]: <!-- mdview:comment ${metaJson} -->`;
-        return { ...b, headerLine: newHeader };
-      }
-    }
-    return b;
-  });
-
-  if (!found) {
-    return markdown;
-  }
-
-  const serialized = serializeFootnoteBlocks(updatedBlocks);
-  return (
-    contentSection +
-    COMMENT_SEPARATOR +
-    '\n' +
-    serialized + '\n'
-  );
-}
-
-/**
- * Add a reply to a comment. Generates a sequential reply ID scoped to the
- * parent comment. Returns the updated markdown and the generated reply ID.
- */
-export function addReply(
-  markdown: string,
-  commentId: string,
-  reply: Omit<CommentReply, 'id'>
-): { markdown: string; replyId: string } {
-  let replyId = '';
-
-  const updated = updateCommentMetadata(markdown, commentId, (meta) => {
-    const replies = meta.replies ?? [];
-    // Generate sequential ID: reply-1, reply-2, ...
-    let maxNum = 0;
-    for (const r of replies) {
-      const match = /^reply-(\d+)$/.exec(r.id);
-      if (match) {
-        const num = parseInt(match[1], 10);
-        if (num > maxNum) maxNum = num;
-      }
-    }
-    replyId = `reply-${maxNum + 1}`;
-    replies.push({ id: replyId, ...reply });
-    meta.replies = replies;
-  });
-
-  return { markdown: updated, replyId };
-}
-
-/**
- * Toggle an emoji reaction for an author on a comment.
- * Adds the author if not present; removes if already present.
- * Removes the emoji key entirely when no authors remain.
- */
-export function toggleReaction(
-  markdown: string,
-  commentId: string,
-  emoji: string,
-  author: string
-): string {
-  return updateCommentMetadata(markdown, commentId, (meta) => {
-    const reactions = meta.reactions ?? {};
-    const authors = reactions[emoji] ?? [];
-
-    const idx = authors.indexOf(author);
-    if (idx >= 0) {
-      authors.splice(idx, 1);
-      if (authors.length === 0) {
-        delete reactions[emoji];
-      } else {
-        reactions[emoji] = authors;
-      }
-    } else {
-      reactions[emoji] = [...authors, author];
-    }
-
-    // Only set reactions if non-empty
-    if (Object.keys(reactions).length > 0) {
-      meta.reactions = reactions;
-    } else {
-      delete meta.reactions;
-    }
-  });
-}
+export * from '../../packages/core/src/comments/comment-serializer';
diff --git a/src/comments/emoji-data.ts b/src/comments/emoji-data.ts
index 8699757..b3e14d6 100644
--- a/src/comments/emoji-data.ts
+++ b/src/comments/emoji-data.ts
@@ -1,277 +1 @@
-/**
- * Static emoji data for the comment reaction picker.
- * Native emoji rendering — no npm dependencies.
- */
-
-export interface EmojiEntry {
-  char: string;
-  name: string;
-  keywords?: string[];
-}
-
-export interface EmojiCategory {
-  name: string;
-  emojis: EmojiEntry[];
-}
-
-/**
- * 12 quick-access emojis shown in the top row of the picker.
- */
-export const QUICK_EMOJIS: EmojiEntry[] = [
-  { char: '\u{1F44D}', name: 'thumbs up', keywords: ['like', 'approve', 'yes'] },
-  { char: '\u{1F44E}', name: 'thumbs down', keywords: ['dislike', 'disapprove', 'no'] },
-  { char: '\u{1F604}', name: 'grinning face', keywords: ['happy', 'smile', 'laugh'] },
-  { char: '\u{1F389}', name: 'party popper', keywords: ['celebrate', 'tada', 'hooray'] },
-  { char: '\u{1F615}', name: 'confused face', keywords: ['confused', 'unsure'] },
-  { char: '\u{2764}\u{FE0F}', name: 'red heart', keywords: ['love', 'heart'] },
-  { char: '\u{1F680}', name: 'rocket', keywords: ['launch', 'ship', 'fast'] },
-  { char: '\u{1F440}', name: 'eyes', keywords: ['look', 'see', 'watching'] },
-  { char: '\u{2705}', name: 'check mark', keywords: ['done', 'complete', 'yes', 'approve'] },
-  { char: '\u{274C}', name: 'cross mark', keywords: ['no', 'wrong', 'reject'] },
-  { char: '\u{1F525}', name: 'fire', keywords: ['hot', 'lit', 'amazing'] },
-  { char: '\u{2B50}', name: 'star', keywords: ['favorite', 'excellent', 'great'] },
-];
-
-/**
- * 8 emoji categories with ~200 emojis total.
- */
-export const EMOJI_CATEGORIES: EmojiCategory[] = [
-  {
-    name: 'Smileys & People',
-    emojis: [
-      { char: '\u{1F600}', name: 'grinning face', keywords: ['happy', 'smile'] },
-      { char: '\u{1F604}', name: 'grinning face with smiling eyes', keywords: ['happy', 'smile'] },
-      { char: '\u{1F601}', name: 'beaming face', keywords: ['happy', 'grin'] },
-      { char: '\u{1F606}', name: 'squinting face', keywords: ['laugh', 'happy'] },
-      { char: '\u{1F605}', name: 'grinning face with sweat', keywords: ['relief'] },
-      { char: '\u{1F602}', name: 'face with tears of joy', keywords: ['laugh', 'crying'] },
-      { char: '\u{1F923}', name: 'rolling on the floor laughing', keywords: ['laugh', 'rofl'] },
-      { char: '\u{1F60A}', name: 'smiling face with smiling eyes', keywords: ['blush', 'happy'] },
-      { char: '\u{1F607}', name: 'smiling face with halo', keywords: ['angel', 'innocent'] },
-      { char: '\u{1F609}', name: 'winking face', keywords: ['wink'] },
-      { char: '\u{1F60C}', name: 'relieved face', keywords: ['calm', 'peaceful'] },
-      { char: '\u{1F60D}', name: 'smiling face with heart-eyes', keywords: ['love', 'crush'] },
-      { char: '\u{1F618}', name: 'face blowing a kiss', keywords: ['kiss', 'love'] },
-      { char: '\u{1F914}', name: 'thinking face', keywords: ['think', 'hmm'] },
-      { char: '\u{1F928}', name: 'face with raised eyebrow', keywords: ['skeptical', 'doubt'] },
-      { char: '\u{1F610}', name: 'neutral face', keywords: ['meh', 'blank'] },
-      { char: '\u{1F611}', name: 'expressionless face', keywords: ['blank'] },
-      { char: '\u{1F636}', name: 'face without mouth', keywords: ['speechless', 'silence'] },
-      { char: '\u{1F644}', name: 'face with rolling eyes', keywords: ['eyeroll'] },
-      { char: '\u{1F615}', name: 'confused face', keywords: ['confused', 'unsure'] },
-      { char: '\u{1F61F}', name: 'worried face', keywords: ['worried', 'nervous'] },
-      { char: '\u{1F622}', name: 'crying face', keywords: ['sad', 'cry'] },
-      { char: '\u{1F62D}', name: 'loudly crying face', keywords: ['sob', 'cry'] },
-      { char: '\u{1F621}', name: 'pouting face', keywords: ['angry', 'rage'] },
-      { char: '\u{1F631}', name: 'face screaming in fear', keywords: ['scream', 'horror'] },
-      { char: '\u{1F4AA}', name: 'flexed biceps', keywords: ['strong', 'muscle'] },
-      { char: '\u{1F44F}', name: 'clapping hands', keywords: ['clap', 'applause'] },
-      { char: '\u{1F64F}', name: 'folded hands', keywords: ['pray', 'please', 'thanks'] },
-      { char: '\u{1F91D}', name: 'handshake', keywords: ['agree', 'deal'] },
-      { char: '\u{270C}\u{FE0F}', name: 'victory hand', keywords: ['peace'] },
-    ],
-  },
-  {
-    name: 'Nature',
-    emojis: [
-      { char: '\u{1F436}', name: 'dog face', keywords: ['puppy', 'pet'] },
-      { char: '\u{1F431}', name: 'cat face', keywords: ['kitty', 'pet'] },
-      { char: '\u{1F42D}', name: 'mouse face', keywords: ['mouse'] },
-      { char: '\u{1F43B}', name: 'bear', keywords: ['bear'] },
-      { char: '\u{1F98A}', name: 'fox', keywords: ['fox'] },
-      { char: '\u{1F427}', name: 'penguin', keywords: ['penguin', 'linux'] },
-      { char: '\u{1F41B}', name: 'bug', keywords: ['bug', 'insect'] },
-      { char: '\u{1F40D}', name: 'snake', keywords: ['snake', 'python'] },
-      { char: '\u{1F422}', name: 'turtle', keywords: ['slow', 'turtle'] },
-      { char: '\u{1F419}', name: 'octopus', keywords: ['octopus'] },
-      { char: '\u{1F332}', name: 'evergreen tree', keywords: ['tree', 'nature'] },
-      { char: '\u{1F33B}', name: 'sunflower', keywords: ['flower'] },
-      { char: '\u{1F340}', name: 'four leaf clover', keywords: ['luck', 'clover'] },
-      { char: '\u{1F335}', name: 'cactus', keywords: ['desert', 'plant'] },
-      { char: '\u{1F30A}', name: 'water wave', keywords: ['ocean', 'wave'] },
-      { char: '\u{2600}\u{FE0F}', name: 'sun', keywords: ['sunny', 'weather'] },
-      { char: '\u{1F319}', name: 'crescent moon', keywords: ['moon', 'night'] },
-      { char: '\u{2B50}', name: 'star', keywords: ['favorite', 'excellent'] },
-      { char: '\u{26A1}', name: 'lightning', keywords: ['electric', 'zap', 'thunder'] },
-      { char: '\u{1F525}', name: 'fire', keywords: ['hot', 'lit', 'flame'] },
-      { char: '\u{1F4A7}', name: 'droplet', keywords: ['water', 'drop'] },
-      { char: '\u{2744}\u{FE0F}', name: 'snowflake', keywords: ['cold', 'winter'] },
-      { char: '\u{1F308}', name: 'rainbow', keywords: ['rainbow'] },
-    ],
-  },
-  {
-    name: 'Food & Drink',
-    emojis: [
-      { char: '\u{1F34E}', name: 'red apple', keywords: ['apple', 'fruit'] },
-      { char: '\u{1F34A}', name: 'tangerine', keywords: ['orange', 'fruit'] },
-      { char: '\u{1F34B}', name: 'lemon', keywords: ['citrus'] },
-      { char: '\u{1F34C}', name: 'banana', keywords: ['fruit'] },
-      { char: '\u{1F353}', name: 'strawberry', keywords: ['fruit', 'berry'] },
-      { char: '\u{1F349}', name: 'watermelon', keywords: ['fruit', 'summer'] },
-      { char: '\u{1F355}', name: 'pizza', keywords: ['food'] },
-      { char: '\u{1F354}', name: 'hamburger', keywords: ['burger', 'food'] },
-      { char: '\u{1F37F}', name: 'popcorn', keywords: ['movie', 'snack'] },
-      { char: '\u{2615}', name: 'hot beverage', keywords: ['coffee', 'tea'] },
-      { char: '\u{1F37A}', name: 'beer mug', keywords: ['beer', 'drink'] },
-      { char: '\u{1F377}', name: 'wine glass', keywords: ['wine', 'drink'] },
-      { char: '\u{1F375}', name: 'teacup', keywords: ['tea', 'drink'] },
-      { char: '\u{1F382}', name: 'birthday cake', keywords: ['cake', 'celebration'] },
-      { char: '\u{1F369}', name: 'donut', keywords: ['doughnut', 'sweet'] },
-      { char: '\u{1F36B}', name: 'chocolate bar', keywords: ['chocolate', 'sweet'] },
-      { char: '\u{1F950}', name: 'croissant', keywords: ['bread', 'pastry'] },
-      { char: '\u{1F96A}', name: 'sandwich', keywords: ['food'] },
-      { char: '\u{1F32E}', name: 'taco', keywords: ['mexican', 'food'] },
-      { char: '\u{1F363}', name: 'sushi', keywords: ['japanese', 'food'] },
-    ],
-  },
-  {
-    name: 'Activities',
-    emojis: [
-      { char: '\u{26BD}', name: 'soccer ball', keywords: ['football', 'sport'] },
-      { char: '\u{1F3C0}', name: 'basketball', keywords: ['sport'] },
-      { char: '\u{1F3C8}', name: 'american football', keywords: ['sport'] },
-      { char: '\u{26BE}', name: 'baseball', keywords: ['sport'] },
-      { char: '\u{1F3BE}', name: 'tennis', keywords: ['sport'] },
-      { char: '\u{1F3AF}', name: 'bullseye', keywords: ['target', 'dart'] },
-      { char: '\u{1F3AE}', name: 'video game', keywords: ['game', 'controller'] },
-      { char: '\u{265F}\u{FE0F}', name: 'chess pawn', keywords: ['chess', 'game', 'strategy'] },
-      { char: '\u{1F3B2}', name: 'game die', keywords: ['dice', 'game', 'random'] },
-      { char: '\u{1F3B5}', name: 'musical note', keywords: ['music', 'note'] },
-      { char: '\u{1F3B6}', name: 'musical notes', keywords: ['music'] },
-      { char: '\u{1F3A4}', name: 'microphone', keywords: ['sing', 'karaoke'] },
-      { char: '\u{1F3AC}', name: 'clapper board', keywords: ['movie', 'film'] },
-      { char: '\u{1F3A8}', name: 'artist palette', keywords: ['art', 'paint'] },
-      { char: '\u{1F3AD}', name: 'performing arts', keywords: ['theater', 'drama'] },
-      { char: '\u{1F3C6}', name: 'trophy', keywords: ['winner', 'award', 'prize'] },
-      { char: '\u{1F3C5}', name: 'sports medal', keywords: ['medal', 'award'] },
-      { char: '\u{1F947}', name: 'first place medal', keywords: ['gold', 'winner'] },
-      { char: '\u{1F948}', name: 'second place medal', keywords: ['silver'] },
-      { char: '\u{1F949}', name: 'third place medal', keywords: ['bronze'] },
-    ],
-  },
-  {
-    name: 'Travel & Places',
-    emojis: [
-      { char: '\u{1F697}', name: 'automobile', keywords: ['car'] },
-      { char: '\u{1F680}', name: 'rocket', keywords: ['launch', 'ship', 'space'] },
-      { char: '\u{2708}\u{FE0F}', name: 'airplane', keywords: ['travel', 'flight'] },
-      { char: '\u{1F6A2}', name: 'ship', keywords: ['boat', 'cruise'] },
-      { char: '\u{1F682}', name: 'locomotive', keywords: ['train'] },
-      { char: '\u{1F6B2}', name: 'bicycle', keywords: ['bike', 'cycling'] },
-      { char: '\u{1F3E0}', name: 'house', keywords: ['home'] },
-      { char: '\u{1F3D7}\u{FE0F}', name: 'building construction', keywords: ['construction'] },
-      { char: '\u{1F3D4}\u{FE0F}', name: 'snow-capped mountain', keywords: ['mountain'] },
-      { char: '\u{1F3D6}\u{FE0F}', name: 'beach', keywords: ['beach', 'vacation'] },
-      { char: '\u{1F30D}', name: 'globe europe-africa', keywords: ['world', 'earth'] },
-      { char: '\u{1F30E}', name: 'globe americas', keywords: ['world', 'earth'] },
-      { char: '\u{1F5FA}\u{FE0F}', name: 'world map', keywords: ['map', 'travel'] },
-      { char: '\u{26F0}\u{FE0F}', name: 'mountain', keywords: ['mountain'] },
-      { char: '\u{1F30B}', name: 'volcano', keywords: ['eruption'] },
-    ],
-  },
-  {
-    name: 'Objects',
-    emojis: [
-      { char: '\u{1F4BB}', name: 'laptop', keywords: ['computer', 'code'] },
-      { char: '\u{1F4F1}', name: 'mobile phone', keywords: ['phone', 'cell'] },
-      { char: '\u{2328}\u{FE0F}', name: 'keyboard', keywords: ['type', 'computer'] },
-      { char: '\u{1F4A1}', name: 'light bulb', keywords: ['idea', 'bright'] },
-      { char: '\u{1F50D}', name: 'magnifying glass', keywords: ['search', 'find'] },
-      { char: '\u{1F512}', name: 'locked', keywords: ['lock', 'security'] },
-      { char: '\u{1F513}', name: 'unlocked', keywords: ['unlock', 'open'] },
-      { char: '\u{1F527}', name: 'wrench', keywords: ['tool', 'fix'] },
-      { char: '\u{1F528}', name: 'hammer', keywords: ['tool', 'build'] },
-      { char: '\u{2699}\u{FE0F}', name: 'gear', keywords: ['settings', 'config'] },
-      { char: '\u{1F4E6}', name: 'package', keywords: ['box', 'delivery'] },
-      { char: '\u{1F4CB}', name: 'clipboard', keywords: ['paste', 'list'] },
-      { char: '\u{1F4DD}', name: 'memo', keywords: ['note', 'write'] },
-      { char: '\u{1F4DA}', name: 'books', keywords: ['library', 'read'] },
-      { char: '\u{1F4D6}', name: 'open book', keywords: ['read', 'study'] },
-      { char: '\u{2709}\u{FE0F}', name: 'envelope', keywords: ['email', 'mail'] },
-      { char: '\u{1F4CE}', name: 'paperclip', keywords: ['attach'] },
-      { char: '\u{270F}\u{FE0F}', name: 'pencil', keywords: ['write', 'edit'] },
-      { char: '\u{1F4CC}', name: 'pushpin', keywords: ['pin', 'location'] },
-      { char: '\u{1F5D1}\u{FE0F}', name: 'wastebasket', keywords: ['trash', 'delete'] },
-      { char: '\u{1F3F7}\u{FE0F}', name: 'label', keywords: ['tag'] },
-      { char: '\u{1F4CA}', name: 'bar chart', keywords: ['chart', 'graph', 'stats'] },
-      { char: '\u{1F4C8}', name: 'chart increasing', keywords: ['growth', 'up'] },
-      { char: '\u{1F4C9}', name: 'chart decreasing', keywords: ['decline', 'down'] },
-      { char: '\u{23F0}', name: 'alarm clock', keywords: ['time', 'clock'] },
-    ],
-  },
-  {
-    name: 'Symbols',
-    emojis: [
-      { char: '\u{2764}\u{FE0F}', name: 'red heart', keywords: ['love'] },
-      { char: '\u{1F49B}', name: 'yellow heart', keywords: ['love'] },
-      { char: '\u{1F49A}', name: 'green heart', keywords: ['love'] },
-      { char: '\u{1F499}', name: 'blue heart', keywords: ['love'] },
-      { char: '\u{1F49C}', name: 'purple heart', keywords: ['love'] },
-      { char: '\u{2705}', name: 'check mark', keywords: ['done', 'complete', 'yes'] },
-      { char: '\u{274C}', name: 'cross mark', keywords: ['no', 'wrong', 'reject'] },
-      { char: '\u{2757}', name: 'exclamation mark', keywords: ['important', 'alert'] },
-      { char: '\u{2753}', name: 'question mark', keywords: ['question', 'help'] },
-      { char: '\u{1F4AF}', name: 'hundred points', keywords: ['perfect', '100'] },
-      { char: '\u{267B}\u{FE0F}', name: 'recycling symbol', keywords: ['recycle', 'green'] },
-      { char: '\u{26A0}\u{FE0F}', name: 'warning', keywords: ['caution', 'alert'] },
-      { char: '\u{1F6AB}', name: 'prohibited', keywords: ['banned', 'forbidden'] },
-      { char: '\u{2139}\u{FE0F}', name: 'information', keywords: ['info', 'help'] },
-      { char: '\u{1F503}', name: 'clockwise arrows', keywords: ['refresh', 'reload'] },
-      { char: '\u{1F504}', name: 'counterclockwise arrows', keywords: ['undo', 'back'] },
-      { char: '\u{2B06}\u{FE0F}', name: 'up arrow', keywords: ['up'] },
-      { char: '\u{2B07}\u{FE0F}', name: 'down arrow', keywords: ['down'] },
-      { char: '\u{27A1}\u{FE0F}', name: 'right arrow', keywords: ['right', 'next'] },
-      { char: '\u{2B05}\u{FE0F}', name: 'left arrow', keywords: ['left', 'back'] },
-    ],
-  },
-  {
-    name: 'Flags',
-    emojis: [
-      { char: '\u{1F3C1}', name: 'chequered flag', keywords: ['finish', 'race'] },
-      { char: '\u{1F6A9}', name: 'triangular flag', keywords: ['flag', 'alert'] },
-      { char: '\u{1F3F4}', name: 'black flag', keywords: ['flag'] },
-      { char: '\u{1F3F3}\u{FE0F}', name: 'white flag', keywords: ['surrender', 'peace'] },
-      { char: '\u{1F3F3}\u{FE0F}\u{200D}\u{1F308}', name: 'rainbow flag', keywords: ['pride', 'lgbtq'] },
-    ],
-  },
-];
-
-/**
- * Search emojis across all categories by name or keyword.
- * Returns matching EmojiEntry items, deduplicated by char.
- */
-export function searchEmojis(query: string): EmojiEntry[] {
-  if (!query) return [];
-
-  const lowerQuery = query.toLowerCase();
-  const seen = new Set<string>();
-  const results: EmojiEntry[] = [];
-
-  // Search quick emojis first
-  for (const emoji of QUICK_EMOJIS) {
-    if (matchesQuery(emoji, lowerQuery) && !seen.has(emoji.char)) {
-      seen.add(emoji.char);
-      results.push(emoji);
-    }
-  }
-
-  // Then search all categories
-  for (const cat of EMOJI_CATEGORIES) {
-    for (const emoji of cat.emojis) {
-      if (matchesQuery(emoji, lowerQuery) && !seen.has(emoji.char)) {
-        seen.add(emoji.char);
-        results.push(emoji);
-      }
-    }
-  }
-
-  return results;
-}
-
-function matchesQuery(emoji: EmojiEntry, lowerQuery: string): boolean {
-  if (emoji.name.toLowerCase().includes(lowerQuery)) return true;
-  if (emoji.keywords) {
-    return emoji.keywords.some((kw) => kw.toLowerCase().includes(lowerQuery));
-  }
-  return false;
-}
+export * from '../../packages/core/src/comments/emoji-data';
diff --git a/src/comments/source-position-map.ts b/src/comments/source-position-map.ts
index 511c2c0..0fd532e 100644
--- a/src/comments/source-position-map.ts
+++ b/src/comments/source-position-map.ts
@@ -1,460 +1 @@
-/**
- * Source Position Map for Comment Anchoring
- *
- * Strips markdown inline formatting from source while maintaining a parallel
- * array mapping each plain-text character back to its source offset. This gives
- * exact insertion points for comment footnote references without needing
- * markdown-it's inline token positions.
- */
-
-export interface SourcePositionMap {
-  rawSource: string;
-  plainText: string;
-  offsets: number[];
-  spans: FormattingSpan[];
-}
-
-export interface FormattingSpan {
-  sourceStart: number;
-  sourceEnd: number;
-  plainStart: number;
-  plainEnd: number;
-  type: 'bold' | 'italic' | 'strikethrough' | 'code' | 'link' | 'image' | 'escape';
-}
-
-export interface SelectionContext {
-  prefix: string;
-  suffix: string;
-}
-
-const V1_SENTINEL = '<!-- mdview:comments -->';
-const V2_SENTINEL_PREFIX = '<!-- mdview:annotations';
-
-/**
- * Find the annotation/comment boundary in the markdown.
- * Returns the index of the earlier of v1 or v2 sentinel, or -1 if neither.
- */
-function findAnnotationBoundary(markdown: string): number {
-  const v1 = markdown.indexOf(V1_SENTINEL);
-  const v2 = markdown.indexOf(V2_SENTINEL_PREFIX);
-  if (v1 === -1 && v2 === -1) return -1;
-  if (v1 === -1) return v2;
-  if (v2 === -1) return v1;
-  return Math.min(v1, v2);
-}
-
-/**
- * Build a source position map from raw markdown.
- * Processes only the content section (above annotation/comment boundary).
- */
-export function buildSourceMap(rawMarkdown: string): SourcePositionMap {
-  const sepIdx = findAnnotationBoundary(rawMarkdown);
-  const rawSource = sepIdx === -1 ? rawMarkdown : rawMarkdown.slice(0, sepIdx);
-
-  const result = buildSourceMapRange(rawSource, 0, rawSource.length, 0);
-
-  return {
-    rawSource,
-    plainText: result.chars.join(''),
-    offsets: result.offsets,
-    spans: result.spans,
-  };
-}
-
-/**
- * Find the correct insertion point in the raw source for a comment reference.
- */
-export function findInsertionPoint(
-  map: SourcePositionMap,
-  selectedText: string,
-  context?: SelectionContext
-): number | null {
-  if (!selectedText) return null;
-
-  // Find all occurrences of selectedText in plainText
-  const matches: number[] = [];
-  let searchFrom = 0;
-  while (true) {
-    const idx = map.plainText.indexOf(selectedText, searchFrom);
-    if (idx === -1) break;
-    matches.push(idx);
-    searchFrom = idx + 1;
-  }
-
-  if (matches.length === 0) return null;
-
-  let bestMatch = matches[0];
-
-  // Disambiguate using context if multiple matches and context provided
-  if (matches.length > 1 && context) {
-    let bestScore = -1;
-    for (const matchIdx of matches) {
-      let score = 0;
-      // Score by prefix match
-      if (context.prefix) {
-        const plainBefore = map.plainText.slice(
-          Math.max(0, matchIdx - context.prefix.length),
-          matchIdx
-        );
-        score += commonSuffixLength(context.prefix, plainBefore);
-      }
-      // Score by suffix match
-      if (context.suffix) {
-        const plainAfter = map.plainText.slice(
-          matchIdx + selectedText.length,
-          matchIdx + selectedText.length + context.suffix.length
-        );
-        score += commonPrefixLength(context.suffix, plainAfter);
-      }
-      if (score > bestScore) {
-        bestScore = score;
-        bestMatch = matchIdx;
-      }
-    }
-  }
-
-  // Map the match end position back to source
-  const plainEndIdx = bestMatch + selectedText.length - 1;
-  if (plainEndIdx >= map.offsets.length) return null;
-
-  const sourcePos = map.offsets[plainEndIdx] + 1;
-
-  // Check if the position falls inside any formatting spans.
-  // Use the outermost span's sourceEnd to avoid inserting inside nested constructs.
-  let insertAt = sourcePos;
-  for (const span of map.spans) {
-    if (
-      bestMatch >= span.plainStart &&
-      bestMatch + selectedText.length <= span.plainEnd &&
-      span.type !== 'escape' &&
-      sourcePos < span.sourceEnd
-    ) {
-      insertAt = Math.max(insertAt, span.sourceEnd);
-    }
-  }
-
-  return insertAt;
-}
-
-// ─── Internal helpers ────────────────────────────────────────────────
-
-function isEscapable(ch: string): boolean {
-  return '\\`*_{}[]()#+-.!~>|'.includes(ch);
-}
-
-interface ParseResult {
-  span: FormattingSpan;
-  text: string;
-  contentStart: number;
-  contentEnd: number;
-}
-
-function parseInlineCode(src: string, start: number, plainPos: number): ParseResult | null {
-  // Count opening backticks
-  let ticks = 0;
-  let i = start;
-  while (i < src.length && src[i] === '`') {
-    ticks++;
-    i++;
-  }
-
-  // Find matching closing backticks
-  const closer = '`'.repeat(ticks);
-  const closeIdx = src.indexOf(closer, i);
-  if (closeIdx === -1) return null;
-
-  // Verify exact match (no extra backticks)
-  if (closeIdx + ticks < src.length && src[closeIdx + ticks] === '`') return null;
-
-  const contentStart = i;
-  const contentEnd = closeIdx;
-  const content = src.slice(contentStart, contentEnd);
-
-  return {
-    span: {
-      sourceStart: start,
-      sourceEnd: closeIdx + ticks,
-      plainStart: plainPos,
-      plainEnd: plainPos + content.length,
-      type: 'code',
-    },
-    text: content,
-    contentStart,
-    contentEnd,
-  };
-}
-
-function parseLinkOrImage(
-  src: string,
-  start: number,
-  plainPos: number,
-  isImage: boolean
-): ParseResult | null {
-  const bracketStart = isImage ? start + 2 : start + 1; // skip `![` or `[`
-  let depth = 1;
-  let i = bracketStart;
-
-  // Find the matching `]`
-  while (i < src.length && depth > 0) {
-    if (src[i] === '\\' && i + 1 < src.length) {
-      i += 2;
-      continue;
-    }
-    if (src[i] === '[') depth++;
-    if (src[i] === ']') depth--;
-    if (depth > 0) i++;
-  }
-
-  if (depth !== 0) return null;
-  const bracketEnd = i; // position of `]`
-
-  // Expect `(` immediately after `]`
-  if (bracketEnd + 1 >= src.length || src[bracketEnd + 1] !== '(') return null;
-
-  // Find matching `)`
-  let parenDepth = 1;
-  let j = bracketEnd + 2;
-  while (j < src.length && parenDepth > 0) {
-    if (src[j] === '\\' && j + 1 < src.length) {
-      j += 2;
-      continue;
-    }
-    if (src[j] === '(') parenDepth++;
-    if (src[j] === ')') parenDepth--;
-    if (parenDepth > 0) j++;
-  }
-
-  if (parenDepth !== 0) return null;
-
-  return {
-    span: {
-      sourceStart: start,
-      sourceEnd: j + 1, // after `)`
-      plainStart: plainPos,
-      plainEnd: plainPos, // will be updated by caller
-      type: isImage ? 'image' : 'link',
-    },
-    text: src.slice(bracketStart, bracketEnd),
-    contentStart: bracketStart,
-    contentEnd: bracketEnd,
-  };
-}
-
-interface DelimitedResult {
-  span: FormattingSpan;
-  contentStart: number;
-  contentEnd: number;
-}
-
-function parseDelimited(
-  src: string,
-  start: number,
-  marker: string,
-  plainPos: number,
-  type: FormattingSpan['type'],
-  searchEnd: number = src.length
-): DelimitedResult | null {
-  const mLen = marker.length;
-  const contentStart = start + mLen;
-
-  // Don't match if there's a space right after the opening marker
-  if (contentStart >= searchEnd || src[contentStart] === ' ') return null;
-
-  // Find the closing marker (not preceded by space, not escaped)
-  let i = contentStart;
-  while (i < searchEnd) {
-    if (src[i] === '\\' && i + 1 < searchEnd) {
-      i += 2;
-      continue;
-    }
-    if (src.startsWith(marker, i) && src[i - 1] !== ' ') {
-      // For ** or __, make sure we don't match a longer run
-      if (mLen === 2) {
-        // Make sure we don't have a third marker char within search range
-        if (i + mLen < searchEnd && src[i + mLen] === marker[0]) {
-          i++;
-          continue;
-        }
-      }
-      if (mLen === 1) {
-        // For single marker, make sure there's no second marker char within search range
-        if (i + 1 < searchEnd && src[i + 1] === marker[0]) {
-          i++;
-          continue;
-        }
-      }
-      return {
-        span: {
-          sourceStart: start,
-          sourceEnd: i + mLen,
-          plainStart: plainPos,
-          plainEnd: plainPos, // will be updated
-          type,
-        },
-        contentStart,
-        contentEnd: i,
-      };
-    }
-    i++;
-  }
-
-  return null;
-}
-
-function buildSourceMapRange(
-  src: string,
-  start: number,
-  end: number,
-  basePlainPos: number
-): { chars: string[]; offsets: number[]; spans: FormattingSpan[] } {
-  const chars: string[] = [];
-  const offsets: number[] = [];
-  const spans: FormattingSpan[] = [];
-  let i = start;
-
-  while (i < end) {
-    // Escape sequences
-    if (src[i] === '\\' && i + 1 < end && isEscapable(src[i + 1])) {
-      const plainPos = basePlainPos + chars.length;
-      spans.push({
-        sourceStart: i,
-        sourceEnd: i + 2,
-        plainStart: plainPos,
-        plainEnd: plainPos + 1,
-        type: 'escape',
-      });
-      chars.push(src[i + 1]);
-      offsets.push(i + 1);
-      i += 2;
-      continue;
-    }
-
-    // Inline code
-    if (src[i] === '`') {
-      const plainPos = basePlainPos + chars.length;
-      const result = parseInlineCode(src, i, plainPos);
-      if (result && result.span.sourceEnd <= end) {
-        spans.push(result.span);
-        for (let j = 0; j < result.text.length; j++) {
-          chars.push(result.text[j]);
-          offsets.push(result.contentStart + j);
-        }
-        i = result.span.sourceEnd;
-        continue;
-      }
-    }
-
-    // Images
-    if (src[i] === '!' && i + 1 < end && src[i + 1] === '[') {
-      const plainPos = basePlainPos + chars.length;
-      const result = parseLinkOrImage(src, i, plainPos, true);
-      if (result && result.span.sourceEnd <= end) {
-        spans.push(result.span);
-        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
-        for (const ch of inner.chars) chars.push(ch);
-        for (const off of inner.offsets) offsets.push(off);
-        for (const sp of inner.spans) spans.push(sp);
-        result.span.plainEnd = basePlainPos + chars.length;
-        i = result.span.sourceEnd;
-        continue;
-      }
-    }
-
-    // Links
-    if (src[i] === '[') {
-      const plainPos = basePlainPos + chars.length;
-      const result = parseLinkOrImage(src, i, plainPos, false);
-      if (result && result.span.sourceEnd <= end) {
-        spans.push(result.span);
-        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
-        for (const ch of inner.chars) chars.push(ch);
-        for (const off of inner.offsets) offsets.push(off);
-        for (const sp of inner.spans) spans.push(sp);
-        result.span.plainEnd = basePlainPos + chars.length;
-        i = result.span.sourceEnd;
-        continue;
-      }
-    }
-
-    // Bold
-    if (
-      (src[i] === '*' && i + 1 < end && src[i + 1] === '*') ||
-      (src[i] === '_' && i + 1 < end && src[i + 1] === '_')
-    ) {
-      const marker = src.slice(i, i + 2);
-      const plainPos = basePlainPos + chars.length;
-      const result = parseDelimited(src, i, marker, plainPos, 'bold', end);
-      if (result && result.span.sourceEnd <= end) {
-        spans.push(result.span);
-        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
-        for (const ch of inner.chars) chars.push(ch);
-        for (const off of inner.offsets) offsets.push(off);
-        for (const sp of inner.spans) spans.push(sp);
-        result.span.plainEnd = basePlainPos + chars.length;
-        i = result.span.sourceEnd;
-        continue;
-      }
-    }
-
-    // Strikethrough
-    if (src[i] === '~' && i + 1 < end && src[i + 1] === '~') {
-      const plainPos = basePlainPos + chars.length;
-      const result = parseDelimited(src, i, '~~', plainPos, 'strikethrough', end);
-      if (result && result.span.sourceEnd <= end) {
-        spans.push(result.span);
-        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
-        for (const ch of inner.chars) chars.push(ch);
-        for (const off of inner.offsets) offsets.push(off);
-        for (const sp of inner.spans) spans.push(sp);
-        result.span.plainEnd = basePlainPos + chars.length;
-        i = result.span.sourceEnd;
-        continue;
-      }
-    }
-
-    // Italic (single marker)
-    if (src[i] === '*' || src[i] === '_') {
-      const marker = src[i];
-      const plainPos = basePlainPos + chars.length;
-      const result = parseDelimited(src, i, marker, plainPos, 'italic', end);
-      if (result && result.span.sourceEnd <= end) {
-        spans.push(result.span);
-        const inner = buildSourceMapRange(src, result.contentStart, result.contentEnd, basePlainPos + chars.length);
-        for (const ch of inner.chars) chars.push(ch);
-        for (const off of inner.offsets) offsets.push(off);
-        for (const sp of inner.spans) spans.push(sp);
-        result.span.plainEnd = basePlainPos + chars.length;
-        i = result.span.sourceEnd;
-        continue;
-      }
-    }
-
-    // Plain character
-    chars.push(src[i]);
-    offsets.push(i);
-    i++;
-  }
-
-  return { chars, offsets, spans };
-}
-
-function commonSuffixLength(a: string, b: string): number {
-  let count = 0;
-  let ai = a.length - 1;
-  let bi = b.length - 1;
-  while (ai >= 0 && bi >= 0 && a[ai] === b[bi]) {
-    count++;
-    ai--;
-    bi--;
-  }
-  return count;
-}
-
-function commonPrefixLength(a: string, b: string): number {
-  let count = 0;
-  const limit = Math.min(a.length, b.length);
-  while (count < limit && a[count] === b[count]) {
-    count++;
-  }
-  return count;
-}
+export * from '../../packages/core/src/comments/source-position-map';

From 6b2e88ba9d7310ed457f9db9045a126a5635ca4b Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:29:54 -0400
Subject: [PATCH 09/26] refactor(core): add barrel export for @mdview/core

---
 .../core/src/__tests__/barrel-export.test.ts  | 128 ++++++++++++++++++
 packages/core/src/index.ts                    |  37 ++++-
 2 files changed, 164 insertions(+), 1 deletion(-)
 create mode 100644 packages/core/src/__tests__/barrel-export.test.ts

diff --git a/packages/core/src/__tests__/barrel-export.test.ts b/packages/core/src/__tests__/barrel-export.test.ts
new file mode 100644
index 0000000..21ccad3
--- /dev/null
+++ b/packages/core/src/__tests__/barrel-export.test.ts
@@ -0,0 +1,128 @@
+/**
+ * Test that all public APIs are accessible via the @mdview/core barrel export.
+ */
+import {
+  // Version
+  VERSION,
+  // Themes
+  githubLight,
+  githubDark,
+  catppuccinLatte,
+  catppuccinFrappe,
+  catppuccinMacchiato,
+  catppuccinMocha,
+  monokai,
+  monokaiPro,
+  // Comment parsers (v2 annotation format)
+  detectFormat,
+  parseAnnotations,
+  // Comment serializers (v2 annotation format)
+  generateNextCommentId,
+  addComment,
+  addCommentAtOffset,
+  removeComment,
+  updateComment,
+  resolveComment,
+  updateCommentMetadata,
+  addReply,
+  toggleReaction,
+  // Comment parsers (v1 legacy)
+  parseComments,
+  // Comment context & utilities
+  computeCommentContext,
+  buildSourceMap,
+  findInsertionPoint,
+  QUICK_EMOJIS,
+  EMOJI_CATEGORIES,
+  searchEmojis,
+  // Utilities
+  splitIntoSections,
+  splitIntoChunks,
+  FilenameGenerator,
+  stripTableOfContents,
+  // Markdown converter
+  MarkdownConverter,
+  markdownConverter,
+  // Cache manager
+  CacheManager,
+  cacheManager,
+  // Frontmatter
+  extractFrontmatter,
+  renderFrontmatterHtml,
+} from '../index';
+
+describe('@mdview/core barrel export', () => {
+  it('exports VERSION', () => {
+    expect(VERSION).toBe('0.0.1');
+  });
+
+  it('exports all 8 themes', () => {
+    const themes = [
+      githubLight,
+      githubDark,
+      catppuccinLatte,
+      catppuccinFrappe,
+      catppuccinMacchiato,
+      catppuccinMocha,
+      monokai,
+      monokaiPro,
+    ];
+    for (const theme of themes) {
+      expect(theme).toHaveProperty('name');
+      expect(theme).toHaveProperty('colors');
+      expect(theme).toHaveProperty('variant');
+    }
+  });
+
+  it('exports v2 annotation parsers', () => {
+    expect(typeof detectFormat).toBe('function');
+    expect(typeof parseAnnotations).toBe('function');
+  });
+
+  it('exports v2 annotation serializer functions', () => {
+    expect(typeof generateNextCommentId).toBe('function');
+    expect(typeof addComment).toBe('function');
+    expect(typeof addCommentAtOffset).toBe('function');
+    expect(typeof removeComment).toBe('function');
+    expect(typeof updateComment).toBe('function');
+    expect(typeof resolveComment).toBe('function');
+    expect(typeof updateCommentMetadata).toBe('function');
+    expect(typeof addReply).toBe('function');
+    expect(typeof toggleReaction).toBe('function');
+  });
+
+  it('exports v1 legacy parser', () => {
+    expect(typeof parseComments).toBe('function');
+  });
+
+  it('exports comment context and utilities', () => {
+    expect(typeof computeCommentContext).toBe('function');
+    expect(typeof buildSourceMap).toBe('function');
+    expect(typeof findInsertionPoint).toBe('function');
+    expect(QUICK_EMOJIS).toBeDefined();
+    expect(EMOJI_CATEGORIES).toBeDefined();
+    expect(typeof searchEmojis).toBe('function');
+  });
+
+  it('exports utility functions', () => {
+    expect(typeof splitIntoSections).toBe('function');
+    expect(typeof splitIntoChunks).toBe('function');
+    expect(FilenameGenerator).toBeDefined();
+    expect(typeof stripTableOfContents).toBe('function');
+  });
+
+  it('exports markdown converter', () => {
+    expect(MarkdownConverter).toBeDefined();
+    expect(markdownConverter).toBeInstanceOf(MarkdownConverter);
+  });
+
+  it('exports cache manager', () => {
+    expect(CacheManager).toBeDefined();
+    expect(cacheManager).toBeInstanceOf(CacheManager);
+  });
+
+  it('exports frontmatter functions', () => {
+    expect(typeof extractFrontmatter).toBe('function');
+    expect(typeof renderFrontmatterHtml).toBe('function');
+  });
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 1b6448f..18b5b34 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,10 +1,45 @@
 // @mdview/core - shared rendering engine
-// Modules will be exported here as they are extracted from the Chrome extension.
 export const VERSION = '0.0.1';
 
 // Types
 export type * from './types/index';
 
+// Themes
+export { default as catppuccinFrappe } from './themes/catppuccin-frappe';
+export { default as catppuccinLatte } from './themes/catppuccin-latte';
+export { default as catppuccinMacchiato } from './themes/catppuccin-macchiato';
+export { default as catppuccinMocha } from './themes/catppuccin-mocha';
+export { default as githubDark } from './themes/github-dark';
+export { default as githubLight } from './themes/github-light';
+export { default as monokaiPro } from './themes/monokai-pro';
+export { default as monokai } from './themes/monokai';
+
+// Comment parsers & serializers
+// v2 annotation format (current)
+export { detectFormat, parseAnnotations } from './comments/annotation-parser';
+export {
+  generateNextCommentId,
+  addComment,
+  addCommentAtOffset,
+  removeComment,
+  updateComment,
+  resolveComment,
+  updateCommentMetadata,
+  addReply,
+  toggleReaction,
+} from './comments/annotation-serializer';
+// v1 comment format (legacy)
+export { parseComments } from './comments/comment-parser';
+// Context & utilities
+export * from './comments/comment-context';
+export * from './comments/source-position-map';
+export * from './comments/emoji-data';
+
+// Utilities
+export * from './utils/section-splitter';
+export * from './utils/filename-generator';
+export * from './utils/toc-stripper';
+
 // Markdown converter
 export { MarkdownConverter, markdownConverter } from './markdown-converter';
 export type { ConvertOptions } from './markdown-converter';

From 994190f7ae3f117ac7fa7ac8ead2e52d768029fa Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:33:56 -0400
Subject: [PATCH 10/26] feat(core): define platform adapter interfaces

---
 packages/core/src/__tests__/adapters.test.ts | 205 ++++++++++++++++++
 packages/core/src/adapters.ts                | 208 +++++++++++++++++++
 packages/core/src/index.ts                   |   3 +
 3 files changed, 416 insertions(+)
 create mode 100644 packages/core/src/__tests__/adapters.test.ts
 create mode 100644 packages/core/src/adapters.ts

diff --git a/packages/core/src/__tests__/adapters.test.ts b/packages/core/src/__tests__/adapters.test.ts
new file mode 100644
index 0000000..6798c74
--- /dev/null
+++ b/packages/core/src/__tests__/adapters.test.ts
@@ -0,0 +1,205 @@
+import {
+  NoopStorageAdapter,
+  NoopMessagingAdapter,
+  NoopFileAdapter,
+  NoopIdentityAdapter,
+  NoopExportAdapter,
+  createNoopAdapters,
+} from '../adapters';
+import type {
+  StorageAdapter,
+  MessagingAdapter,
+  FileAdapter,
+  IdentityAdapter,
+  ExportAdapter,
+  PlatformAdapters,
+} from '../adapters';
+
+describe('Platform Adapters', () => {
+  describe('StorageAdapter (NoopStorageAdapter)', () => {
+    let storage: StorageAdapter;
+
+    beforeEach(() => {
+      storage = new NoopStorageAdapter();
+    });
+
+    it('returns empty object for unknown sync keys', async () => {
+      const result = await storage.getSync('nonexistent');
+      expect(result).toEqual({});
+    });
+
+    it('stores and retrieves sync values', async () => {
+      await storage.setSync({ theme: 'github-dark', fontSize: 14 });
+      const result = await storage.getSync(['theme', 'fontSize']);
+      expect(result).toEqual({ theme: 'github-dark', fontSize: 14 });
+    });
+
+    it('returns empty object for unknown local keys', async () => {
+      const result = await storage.getLocal(['missing']);
+      expect(result).toEqual({});
+    });
+
+    it('stores and retrieves local values', async () => {
+      await storage.setLocal({ scrollPos: 500 });
+      const result = await storage.getLocal('scrollPos');
+      expect(result).toEqual({ scrollPos: 500 });
+    });
+
+    it('handles string key argument for getSync', async () => {
+      await storage.setSync({ preferences: { logLevel: 'debug' } });
+      const result = await storage.getSync('preferences');
+      expect(result).toEqual({ preferences: { logLevel: 'debug' } });
+    });
+  });
+
+  describe('MessagingAdapter (NoopMessagingAdapter)', () => {
+    let messaging: MessagingAdapter;
+
+    beforeEach(() => {
+      messaging = new NoopMessagingAdapter();
+    });
+
+    it('returns empty object for any message', async () => {
+      const result = await messaging.send({ type: 'GET_STATE' });
+      expect(result).toEqual({});
+    });
+
+    it('handles messages with payloads', async () => {
+      const result = await messaging.send({
+        type: 'CACHE_GET',
+        payload: { key: 'test-key' },
+      });
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('FileAdapter (NoopFileAdapter)', () => {
+    let file: FileAdapter;
+
+    beforeEach(() => {
+      file = new NoopFileAdapter();
+    });
+
+    it('writeFile returns failure', async () => {
+      const result = await file.writeFile('/tmp/test.md', '# Hello');
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+
+    it('readFile throws', async () => {
+      await expect(file.readFile('/tmp/test.md')).rejects.toThrow(
+        'No file adapter configured'
+      );
+    });
+
+    it('checkChanged returns unchanged', async () => {
+      const result = await file.checkChanged('file:///test.md', 'abc123');
+      expect(result.changed).toBe(false);
+    });
+
+    it('watch returns a no-op unsubscribe function', () => {
+      const unsubscribe = file.watch('/tmp', () => {});
+      expect(typeof unsubscribe).toBe('function');
+      unsubscribe(); // should not throw
+    });
+  });
+
+  describe('IdentityAdapter (NoopIdentityAdapter)', () => {
+    let identity: IdentityAdapter;
+
+    beforeEach(() => {
+      identity = new NoopIdentityAdapter();
+    });
+
+    it('returns empty string username', async () => {
+      const username = await identity.getUsername();
+      expect(username).toBe('');
+    });
+  });
+
+  describe('ExportAdapter (NoopExportAdapter)', () => {
+    let exporter: ExportAdapter;
+
+    beforeEach(() => {
+      exporter = new NoopExportAdapter();
+    });
+
+    it('saveFile completes without error', async () => {
+      await expect(
+        exporter.saveFile({
+          filename: 'test.docx',
+          mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+          data: new Blob(['test']),
+        })
+      ).resolves.toBeUndefined();
+    });
+
+    it('printToPDF is not defined on noop adapter', () => {
+      expect(exporter.printToPDF).toBeUndefined();
+    });
+  });
+
+  describe('createNoopAdapters()', () => {
+    it('returns a complete PlatformAdapters bundle', () => {
+      const adapters: PlatformAdapters = createNoopAdapters();
+      expect(adapters.storage).toBeInstanceOf(NoopStorageAdapter);
+      expect(adapters.messaging).toBeInstanceOf(NoopMessagingAdapter);
+      expect(adapters.file).toBeInstanceOf(NoopFileAdapter);
+      expect(adapters.identity).toBeInstanceOf(NoopIdentityAdapter);
+      expect(adapters.export).toBeInstanceOf(NoopExportAdapter);
+    });
+  });
+
+  describe('Custom mock adapters satisfy interfaces', () => {
+    it('custom StorageAdapter implementation works', async () => {
+      const store = new Map<string, unknown>();
+      const custom: StorageAdapter = {
+        async getSync(keys) {
+          const keyList = Array.isArray(keys) ? keys : [keys];
+          const result: Record<string, unknown> = {};
+          for (const k of keyList) {
+            if (store.has(k)) result[k] = store.get(k);
+          }
+          return result;
+        },
+        async setSync(data) {
+          for (const [k, v] of Object.entries(data)) store.set(k, v);
+        },
+        async getLocal(keys) {
+          return this.getSync(keys);
+        },
+        async setLocal(data) {
+          return this.setSync(data);
+        },
+      };
+
+      await custom.setSync({ key1: 'value1' });
+      expect(await custom.getSync('key1')).toEqual({ key1: 'value1' });
+    });
+
+    it('custom FileAdapter with in-memory fs works', async () => {
+      const files = new Map<string, string>();
+      const custom: FileAdapter = {
+        async writeFile(path, content) {
+          files.set(path, content);
+          return { success: true };
+        },
+        async readFile(path) {
+          const content = files.get(path);
+          if (!content) throw new Error(`File not found: ${path}`);
+          return content;
+        },
+        async checkChanged(_url, _lastHash) {
+          return { changed: true, newHash: 'new-hash' };
+        },
+        watch(_path, _callback) {
+          return () => {};
+        },
+      };
+
+      await custom.writeFile('/test.md', '# Hello');
+      const content = await custom.readFile('/test.md');
+      expect(content).toBe('# Hello');
+    });
+  });
+});
diff --git a/packages/core/src/adapters.ts b/packages/core/src/adapters.ts
new file mode 100644
index 0000000..5c1c40f
--- /dev/null
+++ b/packages/core/src/adapters.ts
@@ -0,0 +1,208 @@
+/**
+ * Platform adapter interfaces for @mdview/core.
+ *
+ * These abstractions replace direct Chrome extension API calls,
+ * allowing the core rendering engine to run in any environment
+ * (Chrome extension, Electron, Node.js, tests).
+ */
+
+import type { AppState, ThemeName, CachedResult } from './types/index';
+
+// ---------------------------------------------------------------------------
+// StorageAdapter — replaces chrome.storage.sync/local
+// ---------------------------------------------------------------------------
+
+export interface StorageAdapter {
+  /** Read values by key from persistent (synced) storage */
+  getSync(keys: string | string[]): Promise<Record<string, unknown>>;
+  /** Write values to persistent (synced) storage */
+  setSync(data: Record<string, unknown>): Promise<void>;
+  /** Read values by key from local-only storage */
+  getLocal(keys: string | string[]): Promise<Record<string, unknown>>;
+  /** Write values to local-only storage */
+  setLocal(data: Record<string, unknown>): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// MessagingAdapter — replaces chrome.runtime.sendMessage
+// ---------------------------------------------------------------------------
+
+/** Message envelope used for cross-context IPC */
+export interface IPCMessage {
+  type: string;
+  payload?: unknown;
+}
+
+export interface MessagingAdapter {
+  /** Send a message and await a response */
+  send(message: IPCMessage): Promise<unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// FileAdapter — replaces native host file I/O and file watching
+// ---------------------------------------------------------------------------
+
+export interface FileWriteResult {
+  success: boolean;
+  error?: string;
+}
+
+export interface FileChangeInfo {
+  changed: boolean;
+  newHash?: string;
+  error?: string;
+}
+
+export interface FileAdapter {
+  /** Write content to a file at the given path */
+  writeFile(path: string, content: string): Promise<FileWriteResult>;
+  /** Read content from a file at the given path */
+  readFile(path: string): Promise<string>;
+  /** Check if a file has changed since the last known hash */
+  checkChanged(url: string, lastHash: string): Promise<FileChangeInfo>;
+  /** Watch a file/directory for changes, returns an unsubscribe function */
+  watch(path: string, callback: () => void): () => void;
+}
+
+// ---------------------------------------------------------------------------
+// IdentityAdapter — replaces GET_USERNAME native host message
+// ---------------------------------------------------------------------------
+
+export interface IdentityAdapter {
+  /** Get the current user's display name or system username */
+  getUsername(): Promise<string>;
+}
+
+// ---------------------------------------------------------------------------
+// ExportAdapter — replaces browser download / printToPDF
+// ---------------------------------------------------------------------------
+
+export interface ExportSaveOptions {
+  /** Suggested filename */
+  filename: string;
+  /** MIME type of the content */
+  mimeType: string;
+  /** File content as Blob or ArrayBuffer */
+  data: Blob | ArrayBuffer;
+}
+
+export interface ExportAdapter {
+  /** Save/download a file (browser download or native save dialog) */
+  saveFile(options: ExportSaveOptions): Promise<void>;
+  /** Print the current view to PDF (Electron: webContents.printToPDF) */
+  printToPDF?(options?: {
+    pageSize?: string;
+    margins?: string;
+    landscape?: boolean;
+  }): Promise<ArrayBuffer>;
+}
+
+// ---------------------------------------------------------------------------
+// PlatformAdapters — combined context for dependency injection
+// ---------------------------------------------------------------------------
+
+export interface PlatformAdapters {
+  storage: StorageAdapter;
+  messaging: MessagingAdapter;
+  file: FileAdapter;
+  identity: IdentityAdapter;
+  export: ExportAdapter;
+}
+
+// ---------------------------------------------------------------------------
+// No-op defaults for graceful degradation
+// ---------------------------------------------------------------------------
+
+/** Storage adapter that stores nothing (in-memory, ephemeral) */
+export class NoopStorageAdapter implements StorageAdapter {
+  private syncStore = new Map<string, unknown>();
+  private localStore = new Map<string, unknown>();
+
+  async getSync(keys: string | string[]): Promise<Record<string, unknown>> {
+    const keyList = Array.isArray(keys) ? keys : [keys];
+    const result: Record<string, unknown> = {};
+    for (const key of keyList) {
+      if (this.syncStore.has(key)) {
+        result[key] = this.syncStore.get(key);
+      }
+    }
+    return result;
+  }
+
+  async setSync(data: Record<string, unknown>): Promise<void> {
+    for (const [key, value] of Object.entries(data)) {
+      this.syncStore.set(key, value);
+    }
+  }
+
+  async getLocal(keys: string | string[]): Promise<Record<string, unknown>> {
+    const keyList = Array.isArray(keys) ? keys : [keys];
+    const result: Record<string, unknown> = {};
+    for (const key of keyList) {
+      if (this.localStore.has(key)) {
+        result[key] = this.localStore.get(key);
+      }
+    }
+    return result;
+  }
+
+  async setLocal(data: Record<string, unknown>): Promise<void> {
+    for (const [key, value] of Object.entries(data)) {
+      this.localStore.set(key, value);
+    }
+  }
+}
+
+/** Messaging adapter that returns empty responses */
+export class NoopMessagingAdapter implements MessagingAdapter {
+  async send(_message: IPCMessage): Promise<unknown> {
+    return {};
+  }
+}
+
+/** File adapter that rejects all operations */
+export class NoopFileAdapter implements FileAdapter {
+  async writeFile(_path: string, _content: string): Promise<FileWriteResult> {
+    return { success: false, error: 'No file adapter configured' };
+  }
+
+  async readFile(_path: string): Promise<string> {
+    throw new Error('No file adapter configured');
+  }
+
+  async checkChanged(
+    _url: string,
+    _lastHash: string
+  ): Promise<FileChangeInfo> {
+    return { changed: false };
+  }
+
+  watch(_path: string, _callback: () => void): () => void {
+    return () => {};
+  }
+}
+
+/** Identity adapter that returns empty username */
+export class NoopIdentityAdapter implements IdentityAdapter {
+  async getUsername(): Promise<string> {
+    return '';
+  }
+}
+
+/** Export adapter that does nothing */
+export class NoopExportAdapter implements ExportAdapter {
+  async saveFile(_options: ExportSaveOptions): Promise<void> {
+    // No-op in environments without export capability
+  }
+}
+
+/** Create a PlatformAdapters bundle with all no-op defaults */
+export function createNoopAdapters(): PlatformAdapters {
+  return {
+    storage: new NoopStorageAdapter(),
+    messaging: new NoopMessagingAdapter(),
+    file: new NoopFileAdapter(),
+    identity: new NoopIdentityAdapter(),
+    export: new NoopExportAdapter(),
+  };
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 18b5b34..02e5205 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -51,3 +51,6 @@ export type { CacheOptions } from './cache-manager';
 // Frontmatter extractor
 export { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extractor';
 export type { FrontmatterResult } from './frontmatter-extractor';
+
+// Platform adapters
+export * from './adapters';

From 76eb366c43288d1ea693d493cacec589b95a32c4 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:43:36 -0400
Subject: [PATCH 11/26] refactor(core): extract file-scanner with
 MessagingAdapter


From 055c462cfc0684fb01d38991d2e93debdf8ff7a7 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:46:23 -0400
Subject: [PATCH 12/26] refactor(core): extract file-scanner with
 MessagingAdapter

---
 .../core/src/__tests__/file-scanner.test.ts   | 380 ++++++++++++++++++
 packages/core/src/utils/file-scanner.ts       | 262 ++++++++++++
 src/utils/file-scanner.ts                     | 292 +++-----------
 3 files changed, 704 insertions(+), 230 deletions(-)
 create mode 100644 packages/core/src/__tests__/file-scanner.test.ts
 create mode 100644 packages/core/src/utils/file-scanner.ts

diff --git a/packages/core/src/__tests__/file-scanner.test.ts b/packages/core/src/__tests__/file-scanner.test.ts
new file mode 100644
index 0000000..5427109
--- /dev/null
+++ b/packages/core/src/__tests__/file-scanner.test.ts
@@ -0,0 +1,380 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { FileScanner } from '../utils/file-scanner';
+import type { FileAdapter, FileChangeInfo } from '../adapters';
+import { NoopFileAdapter } from '../adapters';
+
+describe('FileScanner (core)', () => {
+  describe('hasMarkdownExtension', () => {
+    it('recognizes .md files', () => {
+      expect(FileScanner.hasMarkdownExtension('/path/to/file.md')).toBe(true);
+    });
+
+    it('recognizes .markdown files', () => {
+      expect(FileScanner.hasMarkdownExtension('/path/to/file.markdown')).toBe(true);
+    });
+
+    it('is case-insensitive', () => {
+      expect(FileScanner.hasMarkdownExtension('/path/to/FILE.MD')).toBe(true);
+      expect(FileScanner.hasMarkdownExtension('/path/to/README.Markdown')).toBe(true);
+    });
+
+    it('rejects non-markdown extensions', () => {
+      expect(FileScanner.hasMarkdownExtension('/path/to/file.txt')).toBe(false);
+      expect(FileScanner.hasMarkdownExtension('/path/to/file.html')).toBe(false);
+      expect(FileScanner.hasMarkdownExtension('/path/to/file.js')).toBe(false);
+    });
+  });
+
+  describe('matchesPattern (blocklist)', () => {
+    it('matches exact hostname', () => {
+      expect(
+        FileScanner.matchesBlocklistPattern('github.com', 'https://github.com/repo', 'github.com', '/repo')
+      ).toBe(true);
+    });
+
+    it('does not match different hostname', () => {
+      expect(
+        FileScanner.matchesBlocklistPattern('gitlab.com', 'https://github.com/repo', 'github.com', '/repo')
+      ).toBe(false);
+    });
+
+    it('matches wildcard subdomain', () => {
+      expect(
+        FileScanner.matchesBlocklistPattern('*.github.com', 'https://raw.github.com/file', 'raw.github.com', '/file')
+      ).toBe(true);
+    });
+
+    it('matches wildcard subdomain against base domain', () => {
+      expect(
+        FileScanner.matchesBlocklistPattern('*.github.com', 'https://github.com/file', 'github.com', '/file')
+      ).toBe(true);
+    });
+
+    it('matches path pattern', () => {
+      expect(
+        FileScanner.matchesBlocklistPattern('github.com/*/blob/*', 'https://github.com/user/blob/main', 'github.com', '/user/blob/main')
+      ).toBe(true);
+    });
+
+    it('matches full URL pattern', () => {
+      expect(
+        FileScanner.matchesBlocklistPattern('https://raw.githubusercontent.com/*', 'https://raw.githubusercontent.com/file.md', 'raw.githubusercontent.com', '/file.md')
+      ).toBe(true);
+    });
+
+    it('rejects empty pattern', () => {
+      expect(
+        FileScanner.matchesBlocklistPattern('', 'https://github.com', 'github.com', '/')
+      ).toBe(false);
+    });
+
+    it('rejects whitespace-only pattern', () => {
+      expect(
+        FileScanner.matchesBlocklistPattern('   ', 'https://github.com', 'github.com', '/')
+      ).toBe(false);
+    });
+  });
+
+  describe('isSiteBlockedFromList', () => {
+    it('returns false for empty blocklist', () => {
+      expect(FileScanner.isSiteBlockedFromList([], 'https://github.com', 'github.com', '/')).toBe(false);
+    });
+
+    it('returns true when URL matches a pattern', () => {
+      expect(
+        FileScanner.isSiteBlockedFromList(
+          ['github.com', '*.gitlab.com'],
+          'https://github.com/repo/file.md',
+          'github.com',
+          '/repo/file.md'
+        )
+      ).toBe(true);
+    });
+
+    it('returns false when URL does not match any pattern', () => {
+      expect(
+        FileScanner.isSiteBlockedFromList(
+          ['github.com', '*.gitlab.com'],
+          'https://example.com/file.md',
+          'example.com',
+          '/file.md'
+        )
+      ).toBe(false);
+    });
+  });
+
+  describe('generateHash', () => {
+    it('produces consistent hash for same content', async () => {
+      const hash1 = await FileScanner.generateHash('hello world');
+      const hash2 = await FileScanner.generateHash('hello world');
+      expect(hash1).toBe(hash2);
+    });
+
+    it('produces different hashes for different content', async () => {
+      // The global test setup mocks crypto.subtle.digest to always return
+      // zeroed ArrayBuffer(32). Override it to return content-dependent results.
+      let callCount = 0;
+      const originalDigest = crypto.subtle.digest;
+      crypto.subtle.digest = vi.fn(async () => {
+        callCount++;
+        const buf = new ArrayBuffer(32);
+        const view = new Uint8Array(buf);
+        view[0] = callCount; // Make each call return a unique hash
+        return buf;
+      });
+
+      try {
+        const hash1 = await FileScanner.generateHash('hello world');
+        const hash2 = await FileScanner.generateHash('goodbye world');
+        expect(hash1).not.toBe(hash2);
+      } finally {
+        crypto.subtle.digest = originalDigest;
+      }
+    });
+
+    it('returns a hex string', async () => {
+      const hash = await FileScanner.generateHash('test');
+      // The global mock returns zeroed ArrayBuffer(32), which yields 64 hex '0' chars
+      expect(hash).toMatch(/^[0-9a-f]+$/);
+      expect(hash).toHaveLength(64);
+    });
+  });
+
+  describe('validateFileSize', () => {
+    it('accepts content within size limit', () => {
+      expect(FileScanner.validateFileSize('small content')).toBe(true);
+    });
+
+    it('accepts content at exact limit', () => {
+      const content = 'x'.repeat(100);
+      expect(FileScanner.validateFileSize(content, 100)).toBe(true);
+    });
+
+    it('rejects content exceeding limit', () => {
+      const content = 'x'.repeat(200);
+      expect(FileScanner.validateFileSize(content, 100)).toBe(false);
+    });
+  });
+
+  describe('formatFileSize', () => {
+    it('formats bytes', () => {
+      expect(FileScanner.formatFileSize(500)).toBe('500 B');
+    });
+
+    it('formats kilobytes', () => {
+      expect(FileScanner.formatFileSize(2048)).toBe('2.0 KB');
+    });
+
+    it('formats megabytes', () => {
+      expect(FileScanner.formatFileSize(3 * 1024 * 1024)).toBe('3.0 MB');
+    });
+  });
+
+  describe('getFileSize', () => {
+    it('returns byte length of content', () => {
+      const size = FileScanner.getFileSize('abc');
+      expect(size).toBe(3);
+    });
+  });
+
+  describe('watchFile with FileAdapter', () => {
+    let mockAdapter: FileAdapter;
+
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('calls callback when file has changed', async () => {
+      mockAdapter = {
+        writeFile: vi.fn(),
+        readFile: vi.fn(),
+        checkChanged: vi.fn().mockResolvedValue({ changed: true, newHash: 'new-hash-123' } as FileChangeInfo),
+        watch: vi.fn().mockReturnValue(() => {}),
+      };
+
+      const callback = vi.fn();
+      const cleanup = FileScanner.watchFile(
+        'file:///test.md',
+        'initial-hash',
+        callback,
+        { fileAdapter: mockAdapter, interval: 1000 }
+      );
+
+      // Advance timer to trigger the check
+      await vi.advanceTimersByTimeAsync(1000);
+
+      expect(mockAdapter.checkChanged).toHaveBeenCalledWith('file:///test.md', 'initial-hash');
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      cleanup();
+    });
+
+    it('does not call callback when file has not changed', async () => {
+      mockAdapter = {
+        writeFile: vi.fn(),
+        readFile: vi.fn(),
+        checkChanged: vi.fn().mockResolvedValue({ changed: false } as FileChangeInfo),
+        watch: vi.fn().mockReturnValue(() => {}),
+      };
+
+      const callback = vi.fn();
+      const cleanup = FileScanner.watchFile(
+        'file:///test.md',
+        'initial-hash',
+        callback,
+        { fileAdapter: mockAdapter, interval: 1000 }
+      );
+
+      await vi.advanceTimersByTimeAsync(1000);
+
+      expect(mockAdapter.checkChanged).toHaveBeenCalled();
+      expect(callback).not.toHaveBeenCalled();
+
+      cleanup();
+    });
+
+    it('updates lastHash after change is detected', async () => {
+      mockAdapter = {
+        writeFile: vi.fn(),
+        readFile: vi.fn(),
+        checkChanged: vi.fn()
+          .mockResolvedValueOnce({ changed: true, newHash: 'second-hash' } as FileChangeInfo)
+          .mockResolvedValueOnce({ changed: false } as FileChangeInfo),
+        watch: vi.fn().mockReturnValue(() => {}),
+      };
+
+      const callback = vi.fn();
+      const cleanup = FileScanner.watchFile(
+        'file:///test.md',
+        'first-hash',
+        callback,
+        { fileAdapter: mockAdapter, interval: 1000 }
+      );
+
+      // First check — file changed
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(mockAdapter.checkChanged).toHaveBeenCalledWith('file:///test.md', 'first-hash');
+
+      // Second check — should use the updated hash
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(mockAdapter.checkChanged).toHaveBeenCalledWith('file:///test.md', 'second-hash');
+
+      cleanup();
+    });
+
+    it('handles adapter errors gracefully', async () => {
+      mockAdapter = {
+        writeFile: vi.fn(),
+        readFile: vi.fn(),
+        checkChanged: vi.fn().mockRejectedValue(new Error('Network error')),
+        watch: vi.fn().mockReturnValue(() => {}),
+      };
+
+      const callback = vi.fn();
+      const cleanup = FileScanner.watchFile(
+        'file:///test.md',
+        'initial-hash',
+        callback,
+        { fileAdapter: mockAdapter, interval: 1000 }
+      );
+
+      // Should not throw
+      await vi.advanceTimersByTimeAsync(1000);
+
+      expect(callback).not.toHaveBeenCalled();
+
+      cleanup();
+    });
+
+    it('handles adapter error response gracefully', async () => {
+      mockAdapter = {
+        writeFile: vi.fn(),
+        readFile: vi.fn(),
+        checkChanged: vi.fn().mockResolvedValue({ changed: false, error: 'File not found' } as FileChangeInfo),
+        watch: vi.fn().mockReturnValue(() => {}),
+      };
+
+      const callback = vi.fn();
+      const cleanup = FileScanner.watchFile(
+        'file:///test.md',
+        'initial-hash',
+        callback,
+        { fileAdapter: mockAdapter, interval: 1000 }
+      );
+
+      await vi.advanceTimersByTimeAsync(1000);
+
+      expect(callback).not.toHaveBeenCalled();
+
+      cleanup();
+    });
+
+    it('cleanup function stops polling', async () => {
+      mockAdapter = {
+        writeFile: vi.fn(),
+        readFile: vi.fn(),
+        checkChanged: vi.fn().mockResolvedValue({ changed: true, newHash: 'new' } as FileChangeInfo),
+        watch: vi.fn().mockReturnValue(() => {}),
+      };
+
+      const callback = vi.fn();
+      const cleanup = FileScanner.watchFile(
+        'file:///test.md',
+        'initial-hash',
+        callback,
+        { fileAdapter: mockAdapter, interval: 1000 }
+      );
+
+      // Stop before any tick
+      cleanup();
+
+      await vi.advanceTimersByTimeAsync(5000);
+
+      expect(mockAdapter.checkChanged).not.toHaveBeenCalled();
+      expect(callback).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('watchFile without adapter (graceful degradation)', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('returns a cleanup function without an adapter', () => {
+      const callback = vi.fn();
+      const cleanup = FileScanner.watchFile(
+        'file:///test.md',
+        'initial-hash',
+        callback,
+        {}
+      );
+
+      expect(typeof cleanup).toBe('function');
+      cleanup(); // should not throw
+    });
+
+    it('never calls callback without an adapter', async () => {
+      const callback = vi.fn();
+      const cleanup = FileScanner.watchFile(
+        'file:///test.md',
+        'initial-hash',
+        callback,
+        {}
+      );
+
+      await vi.advanceTimersByTimeAsync(5000);
+
+      expect(callback).not.toHaveBeenCalled();
+
+      cleanup();
+    });
+  });
+});
diff --git a/packages/core/src/utils/file-scanner.ts b/packages/core/src/utils/file-scanner.ts
new file mode 100644
index 0000000..d46a844
--- /dev/null
+++ b/packages/core/src/utils/file-scanner.ts
@@ -0,0 +1,262 @@
+/**
+ * File Scanner Utility (platform-independent)
+ * Detects and validates markdown files by extension and MIME type.
+ *
+ * This is the core version: it has NO Chrome or browser-specific imports.
+ * File-change watching uses an optional FileAdapter for cross-platform support.
+ */
+
+import type { FileAdapter } from '../adapters';
+
+// Lightweight debug facade — no Chrome dependency
+const debug = {
+  log: (..._args: unknown[]) => {},
+  info: (..._args: unknown[]) => {},
+  warn: (..._args: unknown[]) => {},
+  error: (..._args: unknown[]) => {},
+  debug: (..._args: unknown[]) => {},
+};
+
+/** Options for the watchFile polling loop */
+export interface WatchFileOptions {
+  /** File adapter for checking changes. If omitted, watching is a no-op. */
+  fileAdapter?: FileAdapter;
+  /** Polling interval in ms (default: 1000) */
+  interval?: number;
+}
+
+export class FileScanner {
+  private static readonly MARKDOWN_EXTENSIONS = ['.md', '.markdown'];
+  private static readonly MARKDOWN_MIME_TYPES = ['text/markdown', 'text/x-markdown'];
+
+  // ---------------------------------------------------------------------------
+  // Blocklist helpers (platform-independent — callers pass URL parts)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Check if a site is blocked given explicit URL components.
+   * This avoids direct `window.location` access so the method works anywhere.
+   */
+  static isSiteBlockedFromList(
+    blocklist: string[],
+    url: string,
+    hostname: string,
+    pathname: string
+  ): boolean {
+    if (!blocklist || blocklist.length === 0) {
+      return false;
+    }
+
+    for (const pattern of blocklist) {
+      if (this.matchesBlocklistPattern(pattern, url, hostname, pathname)) {
+        debug.info('FileScanner', `Site blocked by pattern: ${pattern}`);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Match a URL against a blocklist pattern.
+   * Pattern formats:
+   * - "example.com"              — matches hostname exactly
+   * - "*.example.com"            — matches any subdomain of example.com
+   * - "example.com/path/*"       — matches hostname + path pattern
+   * - "https://example.com/*"    — matches full URL pattern
+   */
+  static matchesBlocklistPattern(
+    pattern: string,
+    url: string,
+    hostname: string,
+    pathname: string
+  ): boolean {
+    // Normalize pattern (trim whitespace)
+    pattern = pattern.trim().toLowerCase();
+
+    if (!pattern) {
+      return false;
+    }
+
+    // Full URL pattern (starts with http:// or https://)
+    if (pattern.startsWith('http://') || pattern.startsWith('https://')) {
+      return this.matchesGlobPattern(pattern, url.toLowerCase());
+    }
+
+    // Check if pattern includes a path
+    const slashIndex = pattern.indexOf('/');
+    if (slashIndex > 0) {
+      // Pattern has path component: "example.com/path/*"
+      const patternHost = pattern.substring(0, slashIndex);
+      const patternPath = pattern.substring(slashIndex);
+
+      if (!this.matchesHostPattern(patternHost, hostname.toLowerCase())) {
+        return false;
+      }
+
+      return this.matchesGlobPattern(patternPath, pathname.toLowerCase());
+    }
+
+    // Domain-only pattern
+    return this.matchesHostPattern(pattern, hostname.toLowerCase());
+  }
+
+  /**
+   * Match hostname against a host pattern.
+   * Supports wildcard subdomain: "*.example.com"
+   */
+  private static matchesHostPattern(pattern: string, hostname: string): boolean {
+    // Exact match
+    if (pattern === hostname) {
+      return true;
+    }
+
+    // Wildcard subdomain: "*.example.com"
+    if (pattern.startsWith('*.')) {
+      const baseDomain = pattern.substring(2); // Remove "*."
+      // Match the base domain itself or any subdomain
+      return hostname === baseDomain || hostname.endsWith('.' + baseDomain);
+    }
+
+    return false;
+  }
+
+  /**
+   * Match a string against a glob pattern with * wildcards.
+   * * matches any sequence of characters (including empty).
+   */
+  private static matchesGlobPattern(pattern: string, str: string): boolean {
+    // Convert glob pattern to regex
+    // Escape regex special chars except *, then convert * to .*
+    const regexPattern = pattern
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape special chars
+      .replace(/\*/g, '.*'); // Convert * to .*
+
+    const regex = new RegExp('^' + regexPattern + '$');
+    return regex.test(str);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Extension / MIME detection
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Check if a path has a markdown extension
+   */
+  static hasMarkdownExtension(path: string): boolean {
+    const lowerPath = path.toLowerCase();
+    return this.MARKDOWN_EXTENSIONS.some((ext) => lowerPath.endsWith(ext));
+  }
+
+  /**
+   * Check if a MIME type is a markdown type
+   */
+  static isMarkdownMimeType(mimeType: string): boolean {
+    return this.MARKDOWN_MIME_TYPES.includes(mimeType);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Hash / size utilities
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Generate SHA-256 hash for content comparison
+   */
+  static async generateHash(content: string): Promise<string> {
+    const msgBuffer = new TextEncoder().encode(content);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+  }
+
+  /**
+   * Validate file size
+   */
+  static validateFileSize(content: string, maxSize = 10 * 1024 * 1024): boolean {
+    const size = new Blob([content]).size;
+    return size <= maxSize;
+  }
+
+  /**
+   * Get file size in bytes
+   */
+  static getFileSize(content: string): number {
+    return new Blob([content]).size;
+  }
+
+  /**
+   * Format file size for display
+   */
+  static formatFileSize(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+
+  // ---------------------------------------------------------------------------
+  // File watching via FileAdapter (no chrome.* dependency)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Monitor file changes by polling via a FileAdapter.
+   * If no adapter is provided, returns a no-op cleanup function
+   * (graceful degradation — file watching simply does not happen).
+   */
+  static watchFile(
+    fileUrl: string,
+    initialHash: string,
+    callback: () => void,
+    options: WatchFileOptions
+  ): () => void {
+    const { fileAdapter, interval = 1000 } = options;
+
+    // Graceful degradation: no adapter means no watching
+    if (!fileAdapter) {
+      debug.info('FileScanner', 'No file adapter provided — file watching disabled');
+      return () => {};
+    }
+
+    let lastHash = initialHash;
+    let intervalId: ReturnType<typeof setInterval> | null = null;
+
+    debug.info('FileScanner', `Starting file watcher for ${fileUrl}`);
+
+    const checkForChanges = () => {
+      void (async () => {
+        try {
+          debug.log('FileScanner', 'Checking for file changes via adapter...');
+
+          const result = await fileAdapter.checkChanged(fileUrl, lastHash);
+
+          if (result.error) {
+            debug.warn('FileScanner', 'Adapter check error:', result.error);
+            return;
+          }
+
+          if (result.changed) {
+            debug.info('FileScanner', 'File change detected (hash mismatch)');
+            if (result.newHash) {
+              lastHash = result.newHash;
+            }
+            callback();
+          } else {
+            debug.log('FileScanner', 'No change detected');
+          }
+        } catch (error) {
+          debug.error('FileScanner', 'Error checking for file changes:', error);
+        }
+      })();
+    };
+
+    // Start polling
+    intervalId = setInterval(checkForChanges, interval);
+
+    // Return cleanup function
+    return () => {
+      if (intervalId !== null) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+    };
+  }
+}
diff --git a/src/utils/file-scanner.ts b/src/utils/file-scanner.ts
index e305709..1f74f68 100644
--- a/src/utils/file-scanner.ts
+++ b/src/utils/file-scanner.ts
@@ -1,24 +1,27 @@
+/**
+ * Re-export shim: delegates to @mdview/core FileScanner and adds
+ * Chrome extension-specific methods (window.location, chrome.runtime).
+ */
+
+import { FileScanner as CoreFileScanner } from '../../packages/core/src/utils/file-scanner';
+import type { FileAdapter, FileChangeInfo } from '../../packages/core/src/adapters';
 import { debug } from './debug-logger';
 
 /**
- * File Scanner Utility
- * Detects and validates markdown files by extension and MIME type
+ * Browser-aware FileScanner that extends core with Chrome-specific functionality.
+ *
+ * Pure utility methods (hasMarkdownExtension, generateHash, validateFileSize,
+ * formatFileSize, getFileSize) are inherited from the core class.
+ *
+ * Browser-specific methods (isSiteBlocked, isMarkdownFile, getCurrentSiteIdentifier,
+ * getFilePath, readFileContent, watchFile) are defined here.
  */
-
-export class FileScanner {
-  private static readonly MARKDOWN_EXTENSIONS = ['.md', '.markdown'];
-  private static readonly MARKDOWN_MIME_TYPES = ['text/markdown', 'text/x-markdown'];
+export class FileScanner extends CoreFileScanner {
+  private static readonly MARKDOWN_MIME_TYPES_BROWSER = ['text/markdown', 'text/x-markdown'];
 
   /**
    * Check if the current site is in the blocklist.
-   * Supports various pattern formats:
-   * - Domain only: "github.com" (blocks all pages on github.com)
-   * - Wildcard subdomain: "*.github.com" (blocks subdomains)
-   * - Path pattern: "github.com/star/blob/star" (blocks specific paths)
-   * - Full URL pattern: "https://raw.githubusercontent.com/star"
-   *
-   * Note: Use "star" in docs above to avoid JSDoc parsing issues with asterisks.
-   * Actual patterns use * as wildcard.
+   * Uses window.location for URL detection (Chrome extension only).
    */
   static isSiteBlocked(blocklist: string[]): boolean {
     if (!blocklist || blocklist.length === 0) {
@@ -29,93 +32,7 @@ export class FileScanner {
     const hostname = window.location.hostname;
     const pathname = window.location.pathname;
 
-    for (const pattern of blocklist) {
-      if (this.matchesPattern(pattern, url, hostname, pathname)) {
-        debug.info('FileScanner', `Site blocked by pattern: ${pattern}`);
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Match a URL against a blocklist pattern.
-   * Pattern formats:
-   * - "example.com" - matches hostname exactly
-   * - "*.example.com" - matches any subdomain of example.com
-   * - "example.com/path/*" - matches hostname + path pattern
-   * - "https://example.com/*" - matches full URL pattern
-   */
-  private static matchesPattern(
-    pattern: string,
-    url: string,
-    hostname: string,
-    pathname: string
-  ): boolean {
-    // Normalize pattern (trim whitespace)
-    pattern = pattern.trim().toLowerCase();
-
-    if (!pattern) {
-      return false;
-    }
-
-    // Full URL pattern (starts with http:// or https://)
-    if (pattern.startsWith('http://') || pattern.startsWith('https://')) {
-      return this.matchesGlobPattern(pattern, url.toLowerCase());
-    }
-
-    // Check if pattern includes a path
-    const slashIndex = pattern.indexOf('/');
-    if (slashIndex > 0) {
-      // Pattern has path component: "example.com/path/*"
-      const patternHost = pattern.substring(0, slashIndex);
-      const patternPath = pattern.substring(slashIndex);
-
-      if (!this.matchesHostPattern(patternHost, hostname.toLowerCase())) {
-        return false;
-      }
-
-      return this.matchesGlobPattern(patternPath, pathname.toLowerCase());
-    }
-
-    // Domain-only pattern
-    return this.matchesHostPattern(pattern, hostname.toLowerCase());
-  }
-
-  /**
-   * Match hostname against a host pattern.
-   * Supports wildcard subdomain: "*.example.com"
-   */
-  private static matchesHostPattern(pattern: string, hostname: string): boolean {
-    // Exact match
-    if (pattern === hostname) {
-      return true;
-    }
-
-    // Wildcard subdomain: "*.example.com"
-    if (pattern.startsWith('*.')) {
-      const baseDomain = pattern.substring(2); // Remove "*."
-      // Match the base domain itself or any subdomain
-      return hostname === baseDomain || hostname.endsWith('.' + baseDomain);
-    }
-
-    return false;
-  }
-
-  /**
-   * Match a string against a glob pattern with * wildcards.
-   * * matches any sequence of characters (including empty).
-   */
-  private static matchesGlobPattern(pattern: string, str: string): boolean {
-    // Convert glob pattern to regex
-    // Escape regex special chars except *, then convert * to .*
-    const regexPattern = pattern
-      .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape special chars
-      .replace(/\*/g, '.*'); // Convert * to .*
-
-    const regex = new RegExp('^' + regexPattern + '$');
-    return regex.test(str);
+    return this.isSiteBlockedFromList(blocklist, url, hostname, pathname);
   }
 
   /**
@@ -155,7 +72,7 @@ export class FileScanner {
 
     // Check by MIME type first if available (authoritative for web)
     const contentType = document.contentType;
-    if (contentType && this.MARKDOWN_MIME_TYPES.includes(contentType)) {
+    if (contentType && this.MARKDOWN_MIME_TYPES_BROWSER.includes(contentType)) {
       return true;
     }
 
@@ -173,14 +90,6 @@ export class FileScanner {
     return false;
   }
 
-  /**
-   * Check if a path has a markdown extension
-   */
-  static hasMarkdownExtension(path: string): boolean {
-    const lowerPath = path.toLowerCase();
-    return this.MARKDOWN_EXTENSIONS.some((ext) => lowerPath.endsWith(ext));
-  }
-
   /**
    * Get the current file path
    */
@@ -189,10 +98,8 @@ export class FileScanner {
   }
 
   /**
-   * Read file content from the page or source
-   * For file:// URLs, the content is in the DOM as plain text initially.
-   * After rendering (or for updates), we use a hidden iframe hack to read local files
-   * because direct fetch() is blocked by CORS for file:// URLs.
+   * Read file content from the page or source.
+   * For file:// URLs, Chrome displays the content in a <pre> tag initially.
    */
   static readFileContent(forceFetch = false): string {
     // For file:// URLs, Chrome displays the content in a <pre> tag
@@ -208,146 +115,71 @@ export class FileScanner {
       }
     }
 
-    // If we need to force fetch (watch mode) or if main DOM is overwritten,
-    // we can't use fetch() due to CORS on file://.
-    // This method is only called by watchFile which handles the iframe logic separately.
-    // But if we need a one-off read... we can't easily do it without the iframe.
-
-    // Fallback: if this is called unexpectedly with forceFetch outside of watchFile context,
-    // we try to read whatever is in the DOM, which might be stale/rendered.
-    // Ideally, watchFile should handle the source reading itself via iframe.
     return document.body.textContent || '';
   }
 
   /**
-   * Generate hash for content comparison
-   */
-  static async generateHash(content: string): Promise<string> {
-    const msgBuffer = new TextEncoder().encode(content);
-    const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
-    const hashArray = Array.from(new Uint8Array(hashBuffer));
-    return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
-  }
-
-  /**
-   * Monitor file changes using polling via background script delegation
-   * This avoids CORS issues with fetching file:// URLs from content scripts.
+   * Monitor file changes using polling via background script delegation.
+   * This preserves the original Chrome extension signature while delegating
+   * to the core FileScanner with a Chrome FileAdapter.
    */
   static watchFile(initialHash: string, callback: () => void, interval = 1000): () => void {
-    let lastHash = initialHash;
-    let intervalId: number | null = null;
     const fileUrl = window.location.href;
 
     debug.info('FileScanner', `Starting background-delegated file watcher for ${fileUrl}`);
 
-    const checkForChanges = () => {
-      void (async () => {
+    // Create a Chrome-specific file adapter that wraps chrome.runtime.sendMessage
+    // and also handles extension context invalidation errors
+    const chromeAdapter: FileAdapter = {
+      writeFile() {
+        return Promise.resolve({ success: false, error: 'Not supported via Chrome messaging' });
+      },
+      readFile() {
+        return Promise.reject(new Error('Not supported via Chrome messaging'));
+      },
+      async checkChanged(url: string, lastHash: string): Promise<FileChangeInfo> {
         try {
-          debug.log('FileScanner', 'Checking for file changes via background...');
-
           const response: unknown = await chrome.runtime.sendMessage({
             type: 'CHECK_FILE_CHANGED',
-            payload: {
-              url: fileUrl,
-              lastHash,
-            },
+            payload: { url, lastHash },
           });
-          const typedResponse = response as { error?: string; changed?: boolean; newHash?: string };
-
-          if (typedResponse.error) {
-            debug.warn('FileScanner', 'Background check error:', typedResponse.error);
-            return;
-          }
-
-          if (typedResponse.changed) {
-            debug.info('FileScanner', 'File change detected (hash mismatch)');
-            if (typedResponse.newHash) {
-              lastHash = typedResponse.newHash;
-            }
-            callback();
-          } else {
-            debug.log('FileScanner', 'No change detected');
-          }
+          const typed = response as {
+            error?: string;
+            changed?: boolean;
+            newHash?: string;
+          };
+          return {
+            changed: typed.changed ?? false,
+            newHash: typed.newHash,
+            error: typed.error,
+          };
         } catch (error) {
-          // Debug: Log error details for troubleshooting
-          debug.debug('FileScanner', '=== Error Analysis ===');
-          debug.debug('FileScanner', 'Error type:', typeof error);
-          debug.debug('FileScanner', 'Error instanceof Error:', error instanceof Error);
-          debug.debug('FileScanner', 'Error toString():', String(error));
-          debug.debug(
-            'FileScanner',
-            'Error message:',
-            error instanceof Error ? error.message : 'N/A'
-          );
-          debug.debug('FileScanner', 'Error name:', error instanceof Error ? error.name : 'N/A');
-
-          // Improved error handling with case-insensitive check
+          // Handle extension context invalidation
           const errorStr = String(error).toLowerCase();
           const errorMessage = error instanceof Error ? error.message.toLowerCase() : '';
 
-          debug.debug('FileScanner', 'errorStr (lowercase):', errorStr);
-          debug.debug('FileScanner', 'errorMessage (lowercase):', errorMessage);
-
-          const check1 = errorStr.includes('context invalidated');
-          const check2 = errorStr.includes('extension context');
-          const check3 = errorMessage.includes('context invalidated');
+          const isContextInvalid =
+            errorStr.includes('context invalidated') ||
+            errorStr.includes('extension context') ||
+            errorMessage.includes('context invalidated');
 
-          debug.debug('FileScanner', 'Check results:');
-          debug.debug('FileScanner', '  - errorStr.includes("context invalidated"):', check1);
-          debug.debug('FileScanner', '  - errorStr.includes("extension context"):', check2);
-          debug.debug('FileScanner', '  - errorMessage.includes("context invalidated"):', check3);
-
-          const isContextInvalid = check1 || check2 || check3;
-          debug.debug('FileScanner', 'isContextInvalid:', isContextInvalid);
-          debug.debug('FileScanner', '=== End Error Analysis ===');
-
-          // Handle extension context invalidation (e.g. after extension update/reload)
           if (isContextInvalid) {
-            debug.warn('FileScanner', 'Extension context invalidated. Stopping file watcher.');
-            if (intervalId !== null) {
-              clearInterval(intervalId);
-              intervalId = null;
-            }
-            return;
+            debug.warn('FileScanner', 'Extension context invalidated.');
+          } else {
+            debug.error('FileScanner', 'Error communicating with background:', error);
           }
 
-          debug.error('FileScanner', 'Error communicating with background:', error);
+          throw error;
         }
-      })();
+      },
+      watch() {
+        return () => {};
+      },
     };
 
-    // Start polling
-    intervalId = window.setInterval(checkForChanges, interval);
-
-    // Return cleanup function
-    return () => {
-      if (intervalId !== null) {
-        clearInterval(intervalId);
-      }
-    };
-  }
-
-  /**
-   * Validate file size
-   */
-  static validateFileSize(content: string, maxSize = 10 * 1024 * 1024): boolean {
-    const size = new Blob([content]).size;
-    return size <= maxSize;
-  }
-
-  /**
-   * Get file size in bytes
-   */
-  static getFileSize(content: string): number {
-    return new Blob([content]).size;
-  }
-
-  /**
-   * Format file size for display
-   */
-  static formatFileSize(bytes: number): string {
-    if (bytes < 1024) return `${bytes} B`;
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return CoreFileScanner.watchFile(fileUrl, initialHash, callback, {
+      fileAdapter: chromeAdapter,
+      interval,
+    });
   }
 }

From 4610406d2d755b756e30608750ba94a4a423e71d Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:47:03 -0400
Subject: [PATCH 13/26] refactor(core): add FileScanner to barrel export

---
 packages/core/src/index.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 02e5205..5dfa6d6 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -39,6 +39,8 @@ export * from './comments/emoji-data';
 export * from './utils/section-splitter';
 export * from './utils/filename-generator';
 export * from './utils/toc-stripper';
+export { FileScanner } from './utils/file-scanner';
+export type { WatchFileOptions } from './utils/file-scanner';
 
 // Markdown converter
 export { MarkdownConverter, markdownConverter } from './markdown-converter';

From 34d7c8e751ee4b231645595e41ffc9160f60a9cd Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:47:24 -0400
Subject: [PATCH 14/26] refactor(core): extract theme-engine with
 StorageAdapter

---
 packages/core/src/__tests__/export-ui.test.ts | 218 +++++
 .../core/src/__tests__/theme-engine.test.ts   | 179 ++++
 packages/core/src/index.ts                    |   4 +
 packages/core/src/theme-engine.ts             | 213 +++++
 packages/core/src/ui/export-ui.ts             | 806 ++++++++++++++++++
 src/core/theme-engine.ts                      | 222 ++---
 src/ui/export-ui.ts                           | 769 +----------------
 7 files changed, 1530 insertions(+), 881 deletions(-)
 create mode 100644 packages/core/src/__tests__/export-ui.test.ts
 create mode 100644 packages/core/src/__tests__/theme-engine.test.ts
 create mode 100644 packages/core/src/theme-engine.ts
 create mode 100644 packages/core/src/ui/export-ui.ts

diff --git a/packages/core/src/__tests__/export-ui.test.ts b/packages/core/src/__tests__/export-ui.test.ts
new file mode 100644
index 0000000..1c2884a
--- /dev/null
+++ b/packages/core/src/__tests__/export-ui.test.ts
@@ -0,0 +1,218 @@
+/**
+ * Tests for core ExportUI with MessagingAdapter
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { MessagingAdapter, IPCMessage } from '../adapters';
+import { NoopMessagingAdapter } from '../adapters';
+
+// We need to mock the DOM for ExportUI
+function setupDOM(): void {
+  document.body.innerHTML = '';
+}
+
+describe('ExportUI (core)', () => {
+  beforeEach(() => {
+    setupDOM();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  describe('constructor with MessagingAdapter', () => {
+    it('accepts an optional MessagingAdapter and loads preferences via it', async () => {
+      const mockMessaging: MessagingAdapter = {
+        send: vi.fn().mockResolvedValue({
+          state: {
+            preferences: {
+              exportDefaultPageSize: 'Letter',
+              exportDefaultFormat: 'pdf',
+              exportIncludeToc: false,
+              exportFilenameTemplate: '{title}-{date}',
+            },
+          },
+        }),
+      };
+
+      const { ExportUI } = await import('../ui/export-ui');
+      const ui = new ExportUI({ messaging: mockMessaging });
+
+      // Give loadPreferences time to run (it's async in constructor)
+      await vi.waitFor(() => {
+        expect(mockMessaging.send).toHaveBeenCalledWith({ type: 'GET_STATE' });
+      });
+
+      // Verify the adapter was called with the right message
+      expect(mockMessaging.send).toHaveBeenCalledTimes(1);
+
+      ui.destroy();
+    });
+
+    it('applies loaded preferences to options', async () => {
+      const mockMessaging: MessagingAdapter = {
+        send: vi.fn().mockResolvedValue({
+          state: {
+            preferences: {
+              exportDefaultPageSize: 'Letter',
+              exportDefaultFormat: 'pdf',
+            },
+          },
+        }),
+      };
+
+      const { ExportUI } = await import('../ui/export-ui');
+      const ui = new ExportUI({ messaging: mockMessaging });
+
+      // Wait for preferences to load
+      await vi.waitFor(() => {
+        expect(mockMessaging.send).toHaveBeenCalled();
+      });
+
+      // The ExportUI should have updated its internal options
+      // We can verify by creating the button and checking it works
+      const button = ui.createExportButton();
+      expect(button).toBeTruthy();
+      expect(button.className).toContain('mdview-export-btn');
+
+      ui.destroy();
+    });
+  });
+
+  describe('graceful degradation without adapter', () => {
+    it('creates ExportUI without a messaging adapter', async () => {
+      const { ExportUI } = await import('../ui/export-ui');
+      const ui = new ExportUI();
+
+      // Should not throw
+      expect(ui).toBeTruthy();
+
+      const button = ui.createExportButton();
+      expect(button).toBeTruthy();
+      expect(button.className).toContain('mdview-export-btn');
+
+      ui.destroy();
+    });
+
+    it('works with NoopMessagingAdapter', async () => {
+      const noopMessaging = new NoopMessagingAdapter();
+      const sendSpy = vi.spyOn(noopMessaging, 'send');
+
+      const { ExportUI } = await import('../ui/export-ui');
+      const ui = new ExportUI({ messaging: noopMessaging });
+
+      // Wait for the async loadPreferences to complete
+      await vi.waitFor(() => {
+        expect(sendSpy).toHaveBeenCalled();
+      });
+
+      // NoopMessagingAdapter returns {} which has no state.preferences
+      // So options should remain at defaults
+      const button = ui.createExportButton();
+      expect(button).toBeTruthy();
+
+      ui.destroy();
+    });
+
+    it('handles messaging adapter that rejects', async () => {
+      const failingMessaging: MessagingAdapter = {
+        send: vi.fn().mockRejectedValue(new Error('Connection failed')),
+      };
+
+      const { ExportUI } = await import('../ui/export-ui');
+      // Should not throw even if messaging fails
+      const ui = new ExportUI({ messaging: failingMessaging });
+
+      await vi.waitFor(() => {
+        expect(failingMessaging.send).toHaveBeenCalled();
+      });
+
+      // Should still work - graceful degradation
+      const button = ui.createExportButton();
+      expect(button).toBeTruthy();
+
+      ui.destroy();
+    });
+
+    it('handles messaging adapter that returns empty response', async () => {
+      const emptyMessaging: MessagingAdapter = {
+        send: vi.fn().mockResolvedValue(null),
+      };
+
+      const { ExportUI } = await import('../ui/export-ui');
+      const ui = new ExportUI({ messaging: emptyMessaging });
+
+      await vi.waitFor(() => {
+        expect(emptyMessaging.send).toHaveBeenCalled();
+      });
+
+      // Should work fine with null response
+      const button = ui.createExportButton();
+      expect(button).toBeTruthy();
+
+      ui.destroy();
+    });
+  });
+
+  describe('UI functionality', () => {
+    it('creates export button with correct attributes', async () => {
+      const { ExportUI } = await import('../ui/export-ui');
+      const ui = new ExportUI();
+
+      const button = ui.createExportButton();
+
+      expect(button.getAttribute('aria-label')).toBe('Export document');
+      expect(button.getAttribute('aria-haspopup')).toBe('menu');
+      expect(button.getAttribute('aria-expanded')).toBe('false');
+
+      ui.destroy();
+    });
+
+    it('toggles menu visibility', async () => {
+      const { ExportUI } = await import('../ui/export-ui');
+      const ui = new ExportUI();
+      ui.createExportButton();
+
+      // Show menu
+      ui.showMenu();
+      // There should be a menu in the DOM
+      const menu = document.querySelector('.mdview-export-menu');
+      expect(menu).toBeTruthy();
+
+      // Hide menu
+      ui.hideMenu();
+
+      ui.destroy();
+    });
+
+    it('destroys cleanly', async () => {
+      const { ExportUI } = await import('../ui/export-ui');
+      const ui = new ExportUI();
+      const button = ui.createExportButton();
+      document.body.appendChild(button);
+
+      ui.showMenu();
+
+      // Should not throw
+      ui.destroy();
+    });
+  });
+
+  describe('does NOT import chrome APIs', () => {
+    it('module source does not reference chrome.runtime', async () => {
+      // This is a static analysis check - import the module and verify
+      // it loaded without chrome global
+      const originalChrome = (globalThis as Record<string, unknown>).chrome;
+      delete (globalThis as Record<string, unknown>).chrome;
+
+      try {
+        // Re-import to ensure it works without chrome global
+        const mod = await import('../ui/export-ui');
+        expect(mod.ExportUI).toBeDefined();
+      } finally {
+        if (originalChrome !== undefined) {
+          (globalThis as Record<string, unknown>).chrome = originalChrome;
+        }
+      }
+    });
+  });
+});
diff --git a/packages/core/src/__tests__/theme-engine.test.ts b/packages/core/src/__tests__/theme-engine.test.ts
new file mode 100644
index 0000000..97afbb1
--- /dev/null
+++ b/packages/core/src/__tests__/theme-engine.test.ts
@@ -0,0 +1,179 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { Theme } from '../types/index';
+import type { StorageAdapter } from '../adapters';
+import { NoopStorageAdapter } from '../adapters';
+import githubLight from '../themes/github-light';
+import githubDark from '../themes/github-dark';
+
+// Import the class under test
+import { ThemeEngine } from '../theme-engine';
+
+describe('ThemeEngine', () => {
+  let engine: ThemeEngine;
+
+  beforeEach(() => {
+    engine = new ThemeEngine();
+  });
+
+  describe('loadTheme', () => {
+    it('loads a theme by name', async () => {
+      const theme = await engine.loadTheme('github-light');
+      expect(theme.name).toBe('github-light');
+      expect(theme.variant).toBe('light');
+    });
+
+    it('caches loaded themes', async () => {
+      const first = await engine.loadTheme('github-dark');
+      const second = await engine.loadTheme('github-dark');
+      expect(first).toBe(second); // same reference
+    });
+
+    it('falls back to github-light for unknown themes', async () => {
+      // 'test-theme' is listed in ThemeName type but has no module
+      const theme = await engine.loadTheme('test-theme');
+      expect(theme.name).toBe('github-light');
+    });
+  });
+
+  describe('compileToCSSVariables', () => {
+    it('compiles theme colors to CSS variables', () => {
+      const vars = engine.compileToCSSVariables(githubLight);
+      expect(vars['--md-bg']).toBe(githubLight.colors.background);
+      expect(vars['--md-fg']).toBe(githubLight.colors.foreground);
+      expect(vars['--md-primary']).toBe(githubLight.colors.primary);
+    });
+
+    it('compiles typography to CSS variables', () => {
+      const vars = engine.compileToCSSVariables(githubLight);
+      expect(vars['--md-font-family']).toBe(githubLight.typography.fontFamily);
+      expect(vars['--md-font-family-code']).toBe(githubLight.typography.codeFontFamily);
+      expect(vars['--md-line-height']).toBe(githubLight.typography.baseLineHeight.toString());
+    });
+
+    it('compiles spacing to CSS variables', () => {
+      const vars = engine.compileToCSSVariables(githubLight);
+      expect(vars['--md-block-margin']).toBe(githubLight.spacing.blockMargin);
+      expect(vars['--md-paragraph-margin']).toBe(githubLight.spacing.paragraphMargin);
+    });
+
+    it('applies typography overrides', () => {
+      const vars = engine.compileToCSSVariables(githubLight, {
+        fontFamily: 'Custom Sans',
+        codeFontFamily: 'Custom Mono',
+        baseLineHeight: 2.0,
+      });
+      expect(vars['--md-font-family']).toBe('Custom Sans');
+      expect(vars['--md-font-family-code']).toBe('Custom Mono');
+      expect(vars['--md-line-height']).toBe('2');
+    });
+  });
+
+  describe('with StorageAdapter', () => {
+    it('applies theme correctly with mock StorageAdapter providing overrides', async () => {
+      const storage = new NoopStorageAdapter();
+      await storage.setSync({
+        preferences: {
+          fontFamily: 'Inter',
+          codeFontFamily: 'Fira Code',
+          lineHeight: 1.8,
+          maxWidth: 1200,
+        },
+      });
+
+      const engineWithStorage = new ThemeEngine(storage);
+      const overrides = await engineWithStorage.getStorageOverrides();
+
+      expect(overrides.fontFamily).toBe('Inter');
+      expect(overrides.codeFontFamily).toBe('Fira Code');
+      expect(overrides.baseLineHeight).toBe(1.8);
+      expect(overrides.maxWidth).toBe(1200);
+    });
+
+    it('applies useMaxWidth override from storage', async () => {
+      const storage = new NoopStorageAdapter();
+      await storage.setSync({
+        preferences: {
+          useMaxWidth: true,
+        },
+      });
+
+      const engineWithStorage = new ThemeEngine(storage);
+      const overrides = await engineWithStorage.getStorageOverrides();
+
+      expect(overrides.useMaxWidth).toBe(true);
+    });
+  });
+
+  describe('without StorageAdapter (graceful degradation)', () => {
+    it('works without adapter — uses theme defaults only', () => {
+      const engineNoAdapter = new ThemeEngine();
+      const vars = engineNoAdapter.compileToCSSVariables(githubLight);
+
+      // Should use theme defaults, not any overrides
+      expect(vars['--md-font-family']).toBe(githubLight.typography.fontFamily);
+      expect(vars['--md-font-family-code']).toBe(githubLight.typography.codeFontFamily);
+      expect(vars['--md-line-height']).toBe(githubLight.typography.baseLineHeight.toString());
+    });
+
+    it('getStorageOverrides returns empty object without adapter', async () => {
+      const engineNoAdapter = new ThemeEngine();
+      const overrides = await engineNoAdapter.getStorageOverrides();
+
+      expect(overrides).toEqual({});
+    });
+  });
+
+  describe('font overrides from storage are applied', () => {
+    it('produces CSS variables with storage font overrides', async () => {
+      const storage = new NoopStorageAdapter();
+      await storage.setSync({
+        preferences: {
+          fontFamily: 'Georgia',
+          codeFontFamily: 'JetBrains Mono',
+          lineHeight: 1.6,
+        },
+      });
+
+      const engineWithStorage = new ThemeEngine(storage);
+      const overrides = await engineWithStorage.getStorageOverrides();
+      const vars = engineWithStorage.compileToCSSVariables(githubDark, overrides);
+
+      expect(vars['--md-font-family']).toBe('Georgia');
+      expect(vars['--md-font-family-code']).toBe('JetBrains Mono');
+      expect(vars['--md-line-height']).toBe('1.6');
+      // Non-overridden values should still come from theme
+      expect(vars['--md-bg']).toBe(githubDark.colors.background);
+    });
+  });
+
+  describe('getAvailableThemes', () => {
+    it('returns list of available themes', () => {
+      const themes = engine.getAvailableThemes();
+      expect(themes.length).toBe(8);
+      const names = themes.map((t) => t.name);
+      expect(names).toContain('github-light');
+      expect(names).toContain('github-dark');
+      expect(names).toContain('catppuccin-mocha');
+    });
+
+    it('each theme has name, displayName, and variant', () => {
+      const themes = engine.getAvailableThemes();
+      for (const t of themes) {
+        expect(t.name).toBeTruthy();
+        expect(t.displayName).toBeTruthy();
+        expect(['light', 'dark']).toContain(t.variant);
+      }
+    });
+  });
+
+  describe('getCurrentTheme', () => {
+    it('returns null before any theme is set', () => {
+      expect(engine.getCurrentTheme()).toBeNull();
+    });
+
+    it('returns the theme after setCurrentTheme', () => {
+      engine.setCurrentTheme(githubLight);
+      expect(engine.getCurrentTheme()).toBe(githubLight);
+    });
+  });
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 5dfa6d6..982e9a4 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -54,5 +54,9 @@ export type { CacheOptions } from './cache-manager';
 export { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extractor';
 export type { FrontmatterResult } from './frontmatter-extractor';
 
+// Theme engine
+export { ThemeEngine } from './theme-engine';
+export type { ThemeInfo, ThemeOverrides } from './theme-engine';
+
 // Platform adapters
 export * from './adapters';
diff --git a/packages/core/src/theme-engine.ts b/packages/core/src/theme-engine.ts
new file mode 100644
index 0000000..3c7f84e
--- /dev/null
+++ b/packages/core/src/theme-engine.ts
@@ -0,0 +1,213 @@
+/**
+ * Theme Engine (platform-agnostic)
+ * Manages theme loading, switching, and customization.
+ *
+ * Accepts an optional StorageAdapter for preference overrides.
+ * Works without an adapter (graceful degradation — theme defaults only).
+ */
+
+import type { Theme, ThemeName, AppState } from './types/index';
+import type { StorageAdapter } from './adapters';
+
+export interface ThemeInfo {
+  name: ThemeName;
+  displayName: string;
+  variant: 'light' | 'dark';
+  preview?: string;
+}
+
+export interface ThemeOverrides extends Partial<Theme['typography']> {
+  maxWidth?: number;
+  useMaxWidth?: boolean;
+}
+
+// Static theme registry — avoids dynamic imports that need bundler support.
+// Lazily loaded to avoid circular dependency issues.
+let themeRegistry: Map<ThemeName, () => Promise<Theme>> | null = null;
+
+function getThemeRegistry(): Map<ThemeName, () => Promise<Theme>> {
+  if (!themeRegistry) {
+    themeRegistry = new Map<ThemeName, () => Promise<Theme>>([
+      ['github-light', () => import('./themes/github-light').then((m) => m.default)],
+      ['github-dark', () => import('./themes/github-dark').then((m) => m.default)],
+      ['catppuccin-latte', () => import('./themes/catppuccin-latte').then((m) => m.default)],
+      ['catppuccin-frappe', () => import('./themes/catppuccin-frappe').then((m) => m.default)],
+      [
+        'catppuccin-macchiato',
+        () => import('./themes/catppuccin-macchiato').then((m) => m.default),
+      ],
+      ['catppuccin-mocha', () => import('./themes/catppuccin-mocha').then((m) => m.default)],
+      ['monokai', () => import('./themes/monokai').then((m) => m.default)],
+      ['monokai-pro', () => import('./themes/monokai-pro').then((m) => m.default)],
+    ]);
+  }
+  return themeRegistry;
+}
+
+export class ThemeEngine {
+  private currentTheme: Theme | null = null;
+  private cache: Map<ThemeName, Theme> = new Map();
+  private storage: StorageAdapter | undefined;
+
+  constructor(storage?: StorageAdapter) {
+    this.storage = storage;
+  }
+
+  /**
+   * Load theme by name
+   */
+  async loadTheme(themeName: ThemeName): Promise<Theme> {
+    // Check cache
+    const cached = this.cache.get(themeName);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      const registry = getThemeRegistry();
+      const loader = registry.get(themeName);
+      if (!loader) {
+        throw new Error(`Unknown theme: ${themeName}`);
+      }
+      const theme = await loader();
+
+      // Cache theme
+      this.cache.set(themeName, theme);
+      return theme;
+    } catch (error) {
+      // Fallback to github-light
+      if (themeName !== 'github-light') {
+        return this.loadTheme('github-light');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Fetch preference overrides from storage adapter.
+   * Returns an empty object when no adapter is configured.
+   */
+  async getStorageOverrides(): Promise<ThemeOverrides> {
+    if (!this.storage) {
+      return {};
+    }
+
+    const overrides: ThemeOverrides = {};
+    try {
+      const storage = (await this.storage.getSync('preferences')) as {
+        preferences?: Partial<AppState['preferences']>;
+      };
+      if (storage.preferences) {
+        const p = storage.preferences;
+        if (p.fontFamily) overrides.fontFamily = p.fontFamily;
+        if (p.codeFontFamily) overrides.codeFontFamily = p.codeFontFamily;
+        if (p.lineHeight) overrides.baseLineHeight = p.lineHeight;
+        if (p.maxWidth) overrides.maxWidth = p.maxWidth;
+        overrides.useMaxWidth = p.useMaxWidth;
+      }
+    } catch {
+      // Graceful degradation — return empty overrides
+    }
+
+    return overrides;
+  }
+
+  /**
+   * Get currently applied theme
+   */
+  getCurrentTheme(): Theme | null {
+    return this.currentTheme;
+  }
+
+  /**
+   * Set the current theme (used after applying a theme in the host environment)
+   */
+  setCurrentTheme(theme: Theme): void {
+    this.currentTheme = theme;
+  }
+
+  /**
+   * Get list of available themes
+   */
+  getAvailableThemes(): ThemeInfo[] {
+    return [
+      { name: 'github-light', displayName: 'GitHub Light', variant: 'light' },
+      { name: 'github-dark', displayName: 'GitHub Dark', variant: 'dark' },
+      { name: 'catppuccin-latte', displayName: 'Catppuccin Latte', variant: 'light' },
+      { name: 'catppuccin-frappe', displayName: 'Catppuccin Frappé', variant: 'light' },
+      { name: 'catppuccin-macchiato', displayName: 'Catppuccin Macchiato', variant: 'dark' },
+      { name: 'catppuccin-mocha', displayName: 'Catppuccin Mocha', variant: 'dark' },
+      { name: 'monokai', displayName: 'Monokai', variant: 'dark' },
+      { name: 'monokai-pro', displayName: 'Monokai Pro', variant: 'dark' },
+    ];
+  }
+
+  /**
+   * Compile theme to CSS variables
+   */
+  compileToCSSVariables(
+    theme: Theme,
+    overrides: Partial<Theme['typography']> = {}
+  ): Record<string, string> {
+    return {
+      // Colors
+      '--md-bg': theme.colors.background,
+      '--md-bg-secondary': theme.colors.backgroundSecondary,
+      '--md-bg-tertiary': theme.colors.backgroundTertiary,
+      '--md-fg': theme.colors.foreground,
+      '--md-fg-secondary': theme.colors.foregroundSecondary,
+      '--md-fg-muted': theme.colors.foregroundMuted,
+      '--md-primary': theme.colors.primary,
+      '--md-secondary': theme.colors.secondary,
+      '--md-accent': theme.colors.accent,
+      '--md-heading': theme.colors.heading,
+      '--md-link': theme.colors.link,
+      '--md-link-hover': theme.colors.linkHover,
+      '--md-link-visited': theme.colors.linkVisited,
+      '--md-code-bg': theme.colors.codeBackground,
+      '--md-code-text': theme.colors.codeText,
+      '--md-code-keyword': theme.colors.codeKeyword,
+      '--md-code-string': theme.colors.codeString,
+      '--md-code-comment': theme.colors.codeComment,
+      '--md-code-function': theme.colors.codeFunction,
+      '--md-border': theme.colors.border,
+      '--md-border-light': theme.colors.borderLight,
+      '--md-border-heavy': theme.colors.borderHeavy,
+      '--md-selection': theme.colors.selection,
+      '--md-highlight': theme.colors.highlight,
+      '--md-shadow': theme.colors.shadow,
+      '--md-success': theme.colors.success,
+      '--md-warning': theme.colors.warning,
+      '--md-error': theme.colors.error,
+      '--md-info': theme.colors.info,
+      '--md-comment-highlight': theme.colors.commentHighlight,
+      '--md-comment-highlight-resolved': theme.colors.commentHighlightResolved,
+      '--md-comment-card-bg': theme.colors.commentCardBg,
+
+      // Typography (with overrides)
+      '--md-font-family': overrides.fontFamily || theme.typography.fontFamily,
+      '--md-font-family-heading':
+        theme.typography.headingFontFamily || overrides.fontFamily || theme.typography.fontFamily,
+      '--md-font-family-code': overrides.codeFontFamily || theme.typography.codeFontFamily,
+      '--md-font-size': theme.typography.baseFontSize,
+      '--md-line-height': (overrides.baseLineHeight || theme.typography.baseLineHeight).toString(),
+      '--md-h1-size': theme.typography.h1Size,
+      '--md-h2-size': theme.typography.h2Size,
+      '--md-h3-size': theme.typography.h3Size,
+      '--md-h4-size': theme.typography.h4Size,
+      '--md-h5-size': theme.typography.h5Size,
+      '--md-h6-size': theme.typography.h6Size,
+      '--md-font-weight': theme.typography.fontWeightNormal.toString(),
+      '--md-font-weight-bold': theme.typography.fontWeightBold.toString(),
+      '--md-heading-font-weight': theme.typography.headingFontWeight.toString(),
+
+      // Spacing
+      '--md-block-margin': theme.spacing.blockMargin,
+      '--md-paragraph-margin': theme.spacing.paragraphMargin,
+      '--md-list-item-margin': theme.spacing.listItemMargin,
+      '--md-heading-margin': theme.spacing.headingMargin,
+      '--md-code-block-padding': theme.spacing.codeBlockPadding,
+      '--md-table-cell-padding': theme.spacing.tableCellPadding,
+    };
+  }
+}
diff --git a/packages/core/src/ui/export-ui.ts b/packages/core/src/ui/export-ui.ts
new file mode 100644
index 0000000..aa63125
--- /dev/null
+++ b/packages/core/src/ui/export-ui.ts
@@ -0,0 +1,806 @@
+/**
+ * Export UI Component (Core)
+ * Provides a user interface for exporting markdown to various formats.
+ *
+ * This is the platform-agnostic version. It uses a MessagingAdapter instead
+ * of chrome.runtime.sendMessage, allowing it to run in any environment
+ * (Chrome extension, Electron, Node.js, tests).
+ *
+ * Platform-specific dependencies (ExportController, PDFGenerator) are injected
+ * via the options object rather than imported directly.
+ */
+
+import type {
+  ExportUIOptions,
+  ExportUIState,
+  ExportFormat,
+  ExportProgress,
+  PaperSize,
+} from '../types/index';
+import type { MessagingAdapter } from '../adapters';
+import { FilenameGenerator } from '../utils/filename-generator';
+
+// Lightweight debug facade — no Chrome dependency
+const debug = {
+  info: (..._args: unknown[]) => {},
+  warn: (..._args: unknown[]) => {},
+  error: (..._args: unknown[]) => {},
+};
+
+/**
+ * Interface for the export controller dependency.
+ * Matches the shape of src/core/export-controller.ts ExportController.
+ */
+export interface ExportControllerLike {
+  export(
+    container: HTMLElement,
+    options: Record<string, unknown>,
+    onProgress?: (progress: ExportProgress) => void
+  ): Promise<void>;
+}
+
+/**
+ * Interface for the PDF generator dependency.
+ * Matches the shape of src/utils/pdf-generator.ts PDFGenerator.
+ */
+export interface PDFGeneratorLike {
+  print(
+    container: HTMLElement,
+    options: Record<string, unknown>,
+    onProgress?: (progress: ExportProgress) => void,
+    signal?: AbortSignal
+  ): Promise<void>;
+}
+
+/** Factory functions for lazy-loading platform-specific modules */
+export interface ExportFactories {
+  createExportController?: () => Promise<ExportControllerLike>;
+  createPDFGenerator?: () => Promise<PDFGeneratorLike>;
+}
+
+/** Extended options that include the optional messaging adapter and factories */
+export interface CoreExportUIOptions extends ExportUIOptions {
+  messaging?: MessagingAdapter;
+  factories?: ExportFactories;
+}
+
+export class ExportUI {
+  private button: HTMLElement | null = null;
+  private menu: HTMLElement | null = null;
+  private progressOverlay: HTMLElement | null = null;
+  private toast: HTMLElement | null = null;
+  private options: ExportUIOptions;
+  private state: ExportUIState;
+  private boundHandlers: Map<string, EventListener>;
+  private exportController: ExportControllerLike | null = null;
+  private toastTimeout: number | null = null;
+  private abortController: AbortController | null = null;
+  private messaging?: MessagingAdapter;
+  private factories: ExportFactories;
+
+  constructor(options?: CoreExportUIOptions) {
+    this.messaging = options?.messaging;
+    this.factories = options?.factories || {};
+
+    this.options = {
+      position: options?.position || 'left',
+      formats: options?.formats || ['docx', 'pdf'],
+      defaultPageSize: options?.defaultPageSize || 'A4',
+    };
+
+    this.state = {
+      isMenuOpen: false,
+      isExporting: false,
+      currentProgress: null,
+      lastError: null,
+    };
+
+    this.boundHandlers = new Map();
+
+    // Load preferences asynchronously
+    void this.loadPreferences();
+
+    debug.info('ExportUI', 'Export UI initialized');
+  }
+
+  /**
+   * Create the export button
+   */
+  createExportButton(): HTMLElement {
+    this.button = document.createElement('button');
+    this.button.className = `mdview-export-btn position-${this.options.position}`;
+    this.button.setAttribute('aria-label', 'Export document');
+    this.button.setAttribute('aria-haspopup', 'menu');
+    this.button.setAttribute('aria-expanded', 'false');
+    this.button.setAttribute('title', 'Export Document');
+
+    // Download icon (SVG for crisp rendering)
+    this.button.innerHTML = `
+      <svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor">
+        <path d="M12 16l-6-6h4V4h4v6h4l-6 6z"/>
+        <path d="M20 18H4v2h16v-2z"/>
+      </svg>
+    `;
+
+    const clickHandler = () => this.toggleMenu();
+    this.button.addEventListener('click', clickHandler);
+    this.boundHandlers.set('button-click', clickHandler);
+
+    debug.info('ExportUI', 'Export button created');
+    return this.button;
+  }
+
+  /**
+   * Create the export menu
+   */
+  private createMenu(): HTMLElement {
+    this.menu = document.createElement('div');
+    this.menu.className = `mdview-export-menu position-${this.options.position}`;
+    this.menu.setAttribute('role', 'menu');
+    this.menu.setAttribute('aria-label', 'Export options');
+
+    // Menu header
+    const header = document.createElement('div');
+    header.className = 'mdview-export-menu-header';
+    header.innerHTML = `
+      <span>Export Document</span>
+      <button class="mdview-export-menu-close" aria-label="Close">\u00d7</button>
+    `;
+    this.menu.appendChild(header);
+
+    // Format section
+    const formatSection = document.createElement('div');
+    formatSection.className = 'mdview-export-menu-section';
+
+    const formatLabel = document.createElement('span');
+    formatLabel.className = 'mdview-export-menu-label';
+    formatLabel.textContent = 'FORMAT';
+    formatSection.appendChild(formatLabel);
+
+    // DOCX option
+    if (this.options.formats?.includes('docx')) {
+      const docxButton = this.createFormatButton('docx', 'W', 'Word Document', '.docx');
+      formatSection.appendChild(docxButton);
+    }
+
+    // PDF option
+    if (this.options.formats?.includes('pdf')) {
+      const pdfButton = this.createFormatButton('pdf', 'P', 'PDF / Print', 'Browser print dialog');
+      formatSection.appendChild(pdfButton);
+    }
+
+    this.menu.appendChild(formatSection);
+
+    // Divider
+    const divider = document.createElement('div');
+    divider.className = 'mdview-export-menu-divider';
+    this.menu.appendChild(divider);
+
+    // Options section
+    const optionsSection = document.createElement('div');
+    optionsSection.className = 'mdview-export-menu-section';
+
+    const optionsLabel = document.createElement('span');
+    optionsLabel.className = 'mdview-export-menu-label';
+    optionsLabel.textContent = 'OPTIONS';
+    optionsSection.appendChild(optionsLabel);
+
+    // Table of Contents checkbox
+    const tocOption = document.createElement('label');
+    tocOption.className = 'mdview-export-option';
+    tocOption.innerHTML = `
+      <input type="checkbox" id="export-toc" checked />
+      <span>Include Table of Contents</span>
+    `;
+    optionsSection.appendChild(tocOption);
+
+    // Page size select
+    const pageSizeOption = document.createElement('div');
+    pageSizeOption.className = 'mdview-export-option';
+    const defaultSize = this.options.defaultPageSize || 'A4';
+    pageSizeOption.innerHTML = `
+      <label for="export-page-size">Page Size:</label>
+      <select id="export-page-size">
+        <optgroup label="ISO A-Series">
+          <option value="A0" ${defaultSize === 'A0' ? 'selected' : ''}>A0</option>
+          <option value="A1" ${defaultSize === 'A1' ? 'selected' : ''}>A1</option>
+          <option value="A3" ${defaultSize === 'A3' ? 'selected' : ''}>A3</option>
+          <option value="A4" ${defaultSize === 'A4' ? 'selected' : ''}>A4</option>
+          <option value="A5" ${defaultSize === 'A5' ? 'selected' : ''}>A5</option>
+          <option value="A6" ${defaultSize === 'A6' ? 'selected' : ''}>A6</option>
+        </optgroup>
+        <optgroup label="North American">
+          <option value="Letter" ${defaultSize === 'Letter' ? 'selected' : ''}>Letter</option>
+          <option value="Legal" ${defaultSize === 'Legal' ? 'selected' : ''}>Legal</option>
+          <option value="Tabloid" ${defaultSize === 'Tabloid' ? 'selected' : ''}>Tabloid</option>
+          <option value="Executive" ${defaultSize === 'Executive' ? 'selected' : ''}>Executive</option>
+        </optgroup>
+      </select>
+    `;
+    optionsSection.appendChild(pageSizeOption);
+
+    this.menu.appendChild(optionsSection);
+
+    // Setup event listeners
+    this.setupMenuListeners();
+
+    debug.info('ExportUI', 'Export menu created');
+    return this.menu;
+  }
+
+  /**
+   * Create a format button
+   */
+  private createFormatButton(
+    format: ExportFormat,
+    icon: string,
+    title: string,
+    description: string
+  ): HTMLElement {
+    const button = document.createElement('button');
+    button.className = 'mdview-export-menu-item';
+    button.setAttribute('role', 'menuitem');
+    button.setAttribute('data-format', format);
+
+    const iconSpan = document.createElement('span');
+    iconSpan.className = 'mdview-export-menu-item-icon';
+    iconSpan.textContent = icon;
+
+    const contentSpan = document.createElement('span');
+    contentSpan.className = 'mdview-export-menu-item-content';
+
+    const titleSpan = document.createElement('span');
+    titleSpan.className = 'mdview-export-menu-item-title';
+    titleSpan.textContent = title;
+
+    const descSpan = document.createElement('span');
+    descSpan.className = 'mdview-export-menu-item-desc';
+    descSpan.textContent = description;
+
+    contentSpan.appendChild(titleSpan);
+    contentSpan.appendChild(descSpan);
+
+    button.appendChild(iconSpan);
+    button.appendChild(contentSpan);
+
+    const clickHandler = () => {
+      void this.handleExport(format);
+    };
+    button.addEventListener('click', clickHandler);
+    this.boundHandlers.set(`format-${format}`, clickHandler);
+
+    return button;
+  }
+
+  /**
+   * Setup menu event listeners
+   */
+  private setupMenuListeners(): void {
+    if (!this.menu) return;
+
+    // Close button
+    const closeButton = this.menu.querySelector('.mdview-export-menu-close');
+    if (closeButton) {
+      const closeHandler = () => this.hideMenu();
+      closeButton.addEventListener('click', closeHandler);
+      this.boundHandlers.set('menu-close', closeHandler as EventListener);
+    }
+
+    // Click outside to close
+    const clickOutsideHandler = (e: MouseEvent) => this.handleClickOutside(e);
+    document.addEventListener('click', clickOutsideHandler);
+    this.boundHandlers.set('click-outside', clickOutsideHandler as EventListener);
+
+    // Keyboard navigation
+    const keyDownHandler = (e: KeyboardEvent) => this.handleKeyDown(e);
+    document.addEventListener('keydown', keyDownHandler);
+    this.boundHandlers.set('keydown', keyDownHandler as EventListener);
+  }
+
+  /**
+   * Handle click outside menu
+   */
+  private handleClickOutside(e: MouseEvent): void {
+    if (!this.state.isMenuOpen) return;
+
+    const target = e.target as Node;
+    if (
+      this.menu &&
+      !this.menu.contains(target) &&
+      this.button &&
+      !this.button.contains(target)
+    ) {
+      this.hideMenu();
+    }
+  }
+
+  /**
+   * Handle keyboard navigation
+   */
+  private handleKeyDown(e: KeyboardEvent): void {
+    if (!this.state.isMenuOpen) return;
+
+    if (e.key === 'Escape') {
+      this.hideMenu();
+      this.button?.focus();
+      return;
+    }
+
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      e.preventDefault();
+      this.navigateMenu(e.key === 'ArrowDown' ? 1 : -1);
+    }
+
+    if (e.key === 'Enter') {
+      const focusedElement = document.activeElement;
+      if (focusedElement instanceof HTMLElement) {
+        focusedElement.click();
+      }
+    }
+  }
+
+  /**
+   * Navigate menu with arrow keys
+   */
+  private navigateMenu(direction: 1 | -1): void {
+    if (!this.menu) return;
+
+    const items = Array.from(
+      this.menu.querySelectorAll<HTMLElement>('.mdview-export-menu-item')
+    );
+
+    if (items.length === 0) return;
+
+    const currentIndex = items.indexOf(document.activeElement as HTMLElement);
+    let nextIndex: number;
+
+    if (currentIndex === -1) {
+      nextIndex = direction === 1 ? 0 : items.length - 1;
+    } else {
+      nextIndex = (currentIndex + direction + items.length) % items.length;
+    }
+
+    items[nextIndex].focus();
+  }
+
+  /**
+   * Show the menu
+   */
+  showMenu(): void {
+    if (!this.menu) {
+      this.createMenu();
+      document.body.appendChild(this.menu!);
+    }
+
+    this.state.isMenuOpen = true;
+    this.menu?.classList.add('visible');
+
+    if (this.button) {
+      this.button.classList.add('menu-open');
+      this.button.setAttribute('aria-expanded', 'true');
+    }
+
+    // Focus first menu item
+    const firstItem = this.menu?.querySelector('.mdview-export-menu-item') as HTMLElement;
+    setTimeout(() => firstItem?.focus(), 100);
+
+    debug.info('ExportUI', 'Menu shown');
+  }
+
+  /**
+   * Hide the menu
+   */
+  hideMenu(): void {
+    this.state.isMenuOpen = false;
+    this.menu?.classList.remove('visible');
+
+    if (this.button) {
+      this.button.classList.remove('menu-open');
+      this.button.setAttribute('aria-expanded', 'false');
+    }
+
+    debug.info('ExportUI', 'Menu hidden');
+  }
+
+  /**
+   * Toggle menu visibility
+   */
+  toggleMenu(): void {
+    if (this.state.isMenuOpen) {
+      this.hideMenu();
+    } else {
+      this.showMenu();
+    }
+  }
+
+  /**
+   * Handle export action
+   */
+  private async handleExport(format: ExportFormat): Promise<void> {
+    debug.info('ExportUI', `Starting export: ${format}`);
+
+    this.hideMenu();
+
+    // Get options from UI
+    const tocCheckbox = document.getElementById('export-toc') as HTMLInputElement;
+    const pageSizeSelect = document.getElementById('export-page-size') as HTMLSelectElement;
+
+    // For PDF, use PDFGenerator
+    if (format === 'pdf') {
+      try {
+        this.state.isExporting = true;
+        this.button?.classList.add('exporting');
+
+        // Create abort controller so Cancel button can stop long-running work
+        this.abortController = new AbortController();
+
+        this.showProgress({
+          stage: 'collecting',
+          progress: 5,
+          message: 'Preparing document for print...',
+        });
+
+        const container = document.getElementById('mdview-container');
+        if (!container) {
+          throw new Error('Content container not found');
+        }
+
+        if (!this.factories.createPDFGenerator) {
+          throw new Error('PDF export not available: no PDFGenerator factory configured');
+        }
+
+        const generator = await this.factories.createPDFGenerator();
+
+        await generator.print(
+          container,
+          {
+            paperSize: (pageSizeSelect?.value as PaperSize) || this.options.defaultPageSize,
+            convertSvgsToImages: true,
+          },
+          (progress: ExportProgress) => {
+            this.updateProgress(progress);
+          },
+          this.abortController.signal
+        );
+
+        this.hideProgress();
+        this.showSuccess('Print dialog opened');
+      } catch (error) {
+        debug.error('ExportUI', 'Print failed:', error);
+        this.hideProgress();
+        if (error instanceof DOMException && error.name === 'AbortError') {
+          this.showError(new Error('PDF export cancelled'));
+        } else {
+          this.showError(error instanceof Error ? error : new Error('Print failed'));
+        }
+      } finally {
+        this.state.isExporting = false;
+        this.button?.classList.remove('exporting');
+        this.abortController = null;
+      }
+      return;
+    }
+
+    // Generate filename from template
+    const filename = FilenameGenerator.generate({
+      title: document.title || 'document',
+      extension: '', // Extension will be added by ExportController
+      template: this.options.filenameTemplate || '{title}',
+    }).replace(/\.(docx|pdf)$/, ''); // Remove extension as it will be added by the controller
+
+    const options = {
+      format,
+      filename,
+      includeTableOfContents: tocCheckbox?.checked !== false,
+      pageSize: (pageSizeSelect?.value as PaperSize) || this.options.defaultPageSize,
+    };
+
+    // Start export
+    this.state.isExporting = true;
+    this.button?.classList.add('exporting');
+
+    // Create abort controller for cancellation
+    this.abortController = new AbortController();
+
+    try {
+      // Get the container to export
+      const container = document.getElementById('mdview-container');
+      if (!container) {
+        throw new Error('Content container not found');
+      }
+
+      // Show progress overlay
+      this.showProgress({
+        stage: 'collecting',
+        progress: 0,
+        message: 'Collecting content...',
+      });
+
+      // Lazy-load ExportController via factory
+      if (!this.exportController) {
+        if (!this.factories.createExportController) {
+          throw new Error('Export not available: no ExportController factory configured');
+        }
+        this.exportController = await this.factories.createExportController();
+      }
+
+      // Perform export with progress callback
+      await this.exportController.export(container, options, (progress: ExportProgress) => {
+        this.updateProgress(progress);
+      });
+
+      // Success
+      this.hideProgress();
+      this.showSuccess(`Document exported successfully`);
+
+      debug.info('ExportUI', 'Export completed successfully');
+    } catch (error) {
+      debug.error('ExportUI', 'Export failed:', error);
+      this.hideProgress();
+      this.showError(error instanceof Error ? error : new Error('Export failed'));
+      this.state.lastError = error instanceof Error ? error : new Error('Export failed');
+    } finally {
+      this.state.isExporting = false;
+      this.button?.classList.remove('exporting');
+      this.abortController = null;
+    }
+  }
+
+  /**
+   * Create progress overlay
+   */
+  private createProgressOverlay(): HTMLElement {
+    this.progressOverlay = document.createElement('div');
+    this.progressOverlay.className = 'mdview-export-progress-overlay';
+
+    const container = document.createElement('div');
+    container.className = 'mdview-export-progress-container';
+
+    const progressBar = document.createElement('div');
+    progressBar.className = 'mdview-export-progress-bar';
+
+    const progressFill = document.createElement('div');
+    progressFill.className = 'mdview-export-progress-fill';
+    progressFill.style.width = '0%';
+    progressBar.appendChild(progressFill);
+
+    const progressText = document.createElement('div');
+    progressText.className = 'mdview-export-progress-text';
+    progressText.textContent = 'Starting export...';
+
+    const cancelButton = document.createElement('button');
+    cancelButton.className = 'mdview-export-progress-cancel';
+    cancelButton.textContent = 'Cancel';
+
+    const cancelHandler = () => {
+      if (this.abortController) {
+        this.abortController.abort();
+        this.hideProgress();
+        this.showError(new Error('Export cancelled'));
+      }
+    };
+    cancelButton.addEventListener('click', cancelHandler);
+    this.boundHandlers.set('progress-cancel', cancelHandler);
+
+    container.appendChild(progressBar);
+    container.appendChild(progressText);
+    container.appendChild(cancelButton);
+
+    this.progressOverlay.appendChild(container);
+
+    return this.progressOverlay;
+  }
+
+  /**
+   * Show progress overlay
+   */
+  showProgress(progress: ExportProgress): void {
+    if (!this.progressOverlay) {
+      this.createProgressOverlay();
+      document.body.appendChild(this.progressOverlay!);
+    }
+
+    this.state.currentProgress = progress;
+    this.progressOverlay?.classList.add('visible');
+    this.updateProgress(progress);
+
+    debug.info('ExportUI', `Progress: ${progress.stage} - ${progress.progress}%`);
+  }
+
+  /**
+   * Update progress display
+   */
+  private updateProgress(progress: ExportProgress): void {
+    if (!this.progressOverlay) return;
+
+    const fill = this.progressOverlay.querySelector(
+      '.mdview-export-progress-fill'
+    ) as HTMLElement;
+    const text = this.progressOverlay.querySelector(
+      '.mdview-export-progress-text'
+    ) as HTMLElement;
+
+    if (fill) {
+      fill.style.width = `${progress.progress}%`;
+    }
+
+    if (text) {
+      text.textContent = progress.message;
+    }
+
+    this.state.currentProgress = progress;
+  }
+
+  /**
+   * Hide progress overlay
+   */
+  hideProgress(): void {
+    this.progressOverlay?.classList.remove('visible');
+    this.state.currentProgress = null;
+
+    debug.info('ExportUI', 'Progress hidden');
+  }
+
+  /**
+   * Create toast notification
+   */
+  private createToast(type: 'success' | 'error', message: string): HTMLElement {
+    this.toast = document.createElement('div');
+    this.toast.className = `mdview-export-toast ${type}`;
+    this.toast.textContent = message;
+
+    return this.toast;
+  }
+
+  /**
+   * Show success toast
+   */
+  showSuccess(filename: string): void {
+    this.createToast('success', filename);
+    document.body.appendChild(this.toast!);
+
+    // Show with animation
+    setTimeout(() => {
+      this.toast?.classList.add('visible');
+    }, 10);
+
+    // Auto-dismiss after 3 seconds
+    this.toastTimeout = window.setTimeout(() => {
+      this.hideToast();
+    }, 3000);
+
+    debug.info('ExportUI', 'Success toast shown');
+  }
+
+  /**
+   * Show error toast
+   */
+  showError(error: Error): void {
+    this.createToast('error', error.message || 'Export failed');
+    document.body.appendChild(this.toast!);
+
+    // Show with animation
+    setTimeout(() => {
+      this.toast?.classList.add('visible');
+    }, 10);
+
+    // Auto-dismiss after 5 seconds (longer for errors)
+    this.toastTimeout = window.setTimeout(() => {
+      this.hideToast();
+    }, 5000);
+
+    debug.error('ExportUI', 'Error toast shown:', error);
+  }
+
+  /**
+   * Hide toast notification
+   */
+  private hideToast(): void {
+    this.toast?.classList.remove('visible');
+
+    setTimeout(() => {
+      this.toast?.remove();
+      this.toast = null;
+    }, 300);
+
+    if (this.toastTimeout !== null) {
+      window.clearTimeout(this.toastTimeout);
+      this.toastTimeout = null;
+    }
+  }
+
+  /**
+   * Load export preferences from storage via messaging adapter
+   */
+  private async loadPreferences(): Promise<void> {
+    // Without a messaging adapter, skip preference loading (graceful degradation)
+    if (!this.messaging) {
+      return;
+    }
+
+    interface StateResponse {
+      state?: {
+        preferences?: {
+          exportDefaultFormat?: ExportFormat;
+          exportDefaultPageSize?: PaperSize;
+          exportIncludeToc?: boolean;
+          exportFilenameTemplate?: string;
+        };
+      };
+    }
+
+    try {
+      const response = (await this.messaging.send({ type: 'GET_STATE' })) as StateResponse;
+      const state = response?.state;
+
+      if (state?.preferences) {
+        const { exportDefaultFormat, exportDefaultPageSize, exportIncludeToc, exportFilenameTemplate } =
+          state.preferences;
+
+        // Update options with saved preferences
+        if (exportDefaultFormat) {
+          this.options.defaultFormat = exportDefaultFormat;
+        }
+        if (exportDefaultPageSize) {
+          this.options.defaultPageSize = exportDefaultPageSize;
+        }
+        if (exportIncludeToc !== undefined) {
+          this.options.includeTableOfContents = exportIncludeToc;
+        }
+        if (exportFilenameTemplate) {
+          this.options.filenameTemplate = exportFilenameTemplate;
+        }
+
+        debug.info('ExportUI', 'Loaded export preferences:', {
+          format: this.options.defaultFormat,
+          pageSize: this.options.defaultPageSize,
+        });
+      }
+    } catch (error) {
+      debug.warn('ExportUI', 'Failed to load export preferences:', error);
+    }
+  }
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void {
+    // Remove event listeners
+    this.boundHandlers.forEach((handler, key) => {
+      if (key === 'button-click' && this.button) {
+        this.button.removeEventListener('click', handler);
+      } else if (key === 'click-outside') {
+        document.removeEventListener('click', handler);
+      } else if (key === 'keydown') {
+        document.removeEventListener('keydown', handler);
+      }
+    });
+    this.boundHandlers.clear();
+
+    // Remove elements
+    this.button?.remove();
+    this.menu?.remove();
+    this.progressOverlay?.remove();
+    this.toast?.remove();
+
+    // Clear timeouts
+    if (this.toastTimeout !== null) {
+      window.clearTimeout(this.toastTimeout);
+    }
+
+    // Abort any ongoing export
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+
+    // Reset state
+    this.button = null;
+    this.menu = null;
+    this.progressOverlay = null;
+    this.toast = null;
+    this.toastTimeout = null;
+    this.abortController = null;
+
+    debug.info('ExportUI', 'Export UI destroyed');
+  }
+}
diff --git a/src/core/theme-engine.ts b/src/core/theme-engine.ts
index 72ba0e4..0090607 100644
--- a/src/core/theme-engine.ts
+++ b/src/core/theme-engine.ts
@@ -1,53 +1,89 @@
 /**
- * Theme Engine
- * Manages theme loading, switching, and customization
+ * Theme Engine — Chrome extension shim
+ *
+ * Wraps the platform-agnostic ThemeEngine from @mdview/core,
+ * wired up with a Chrome StorageAdapter and DOM-specific methods
+ * (applyTheme, watchSystemTheme, updateSyntaxTheme).
  */
 
+/* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument */
+
 import type { Theme, ThemeName } from '../types';
+import type { StorageAdapter } from '@mdview/core';
+import { ThemeEngine as CoreThemeEngine } from '@mdview/core';
+import type { ThemeOverrides } from '@mdview/core';
 import { debug } from '../utils/debug-logger';
 
-export interface ThemeInfo {
-  name: ThemeName;
-  displayName: string;
-  variant: 'light' | 'dark';
-  preview?: string;
-}
+export type { ThemeInfo } from '@mdview/core';
+
+// ---------------------------------------------------------------------------
+// Chrome StorageAdapter
+// ---------------------------------------------------------------------------
+
+const chromeStorageAdapter: StorageAdapter = {
+  async getSync(keys: string | string[]): Promise<Record<string, unknown>> {
+    return chrome.storage.sync.get(keys) as Promise<Record<string, unknown>>;
+  },
+  async setSync(data: Record<string, unknown>): Promise<void> {
+    await chrome.storage.sync.set(data);
+  },
+  async getLocal(keys: string | string[]): Promise<Record<string, unknown>> {
+    return chrome.storage.local.get(keys) as Promise<Record<string, unknown>>;
+  },
+  async setLocal(data: Record<string, unknown>): Promise<void> {
+    await chrome.storage.local.set(data);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Chrome ThemeEngine — composition over the core engine
+// ---------------------------------------------------------------------------
 
 export class ThemeEngine {
-  private currentTheme: Theme | null = null;
-  private cache: Map<ThemeName, Theme> = new Map();
+  private core: InstanceType<typeof CoreThemeEngine>;
+
+  constructor() {
+    this.core = new CoreThemeEngine(chromeStorageAdapter);
+  }
 
   /**
-   * Load theme by name
+   * Load theme by name (delegated to core)
    */
   async loadTheme(themeName: ThemeName): Promise<Theme> {
-    // Check cache
-    const cached = this.cache.get(themeName);
-    if (cached) {
-      return cached;
-    }
+    return this.core.loadTheme(themeName);
+  }
 
-    try {
-      // Dynamically import theme definition
-      const themeModule = (await import(`../themes/${themeName}.ts`)) as { default: Theme };
-      const theme = themeModule.default;
+  /**
+   * Get currently applied theme
+   */
+  getCurrentTheme(): Theme | null {
+    return this.core.getCurrentTheme();
+  }
 
-      // Cache theme
-      this.cache.set(themeName, theme);
+  /**
+   * Get list of available themes
+   */
+  getAvailableThemes(): Array<{
+    name: ThemeName;
+    displayName: string;
+    variant: 'light' | 'dark';
+    preview?: string;
+  }> {
+    return this.core.getAvailableThemes();
+  }
 
-      return theme;
-    } catch (error) {
-      debug.error('ThemeEngine', `Failed to load theme ${themeName}:`, error);
-      // Fallback to github-light
-      if (themeName !== 'github-light') {
-        return this.loadTheme('github-light');
-      }
-      throw error;
-    }
+  /**
+   * Compile theme to CSS variables (delegated to core)
+   */
+  compileToCSSVariables(
+    theme: Theme,
+    overrides: Partial<Theme['typography']> = {}
+  ): Record<string, string> {
+    return this.core.compileToCSSVariables(theme, overrides);
   }
 
   /**
-   * Apply theme to document
+   * Apply theme to document (DOM-specific)
    */
   async applyTheme(theme: Theme | ThemeName): Promise<void> {
     debug.log(
@@ -57,32 +93,11 @@ export class ThemeEngine {
     );
 
     // Load theme if name provided
-    const themeObj = typeof theme === 'string' ? await this.loadTheme(theme) : theme;
+    const themeObj: Theme = typeof theme === 'string' ? await this.loadTheme(theme) : theme;
     debug.log('ThemeEngine', `Theme loaded/resolved:`, themeObj.name);
 
-    // Get user preferences for overrides (from storage, if available)
-    // Since ThemeEngine runs in content script, we need to fetch preferences.
-    // However, for performance, we might rely on preferences being passed or fetched separately.
-    // For this implementation, we'll try to fetch from storage if possible, but ideally applyTheme receives overrides.
-
-    // Fetch overrides from storage
-    const overrides: Partial<Theme['typography']> & { maxWidth?: number; useMaxWidth?: boolean } =
-      {};
-    try {
-      const storage = (await chrome.storage.sync.get('preferences')) as {
-        preferences?: Partial<import('../types').AppState['preferences']>;
-      };
-      if (storage.preferences) {
-        const p = storage.preferences;
-        if (p.fontFamily) overrides.fontFamily = p.fontFamily;
-        if (p.codeFontFamily) overrides.codeFontFamily = p.codeFontFamily;
-        if (p.lineHeight) overrides.baseLineHeight = p.lineHeight;
-        if (p.maxWidth) overrides.maxWidth = p.maxWidth;
-        overrides.useMaxWidth = p.useMaxWidth;
-      }
-    } catch (e) {
-      debug.warn('ThemeEngine', 'Failed to load preference overrides', e);
-    }
+    // Fetch overrides from storage via the core adapter path
+    const overrides: ThemeOverrides = await this.core.getStorageOverrides();
 
     // Compile to CSS variables with overrides
     const cssVars = this.compileToCSSVariables(themeObj, overrides);
@@ -134,7 +149,6 @@ export class ThemeEngine {
     // Update mermaid theme
     try {
       const { mermaidRenderer } = await import('../renderers/mermaid-renderer');
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
       mermaidRenderer.updateTheme(themeObj.mermaidTheme);
     } catch (error) {
       debug.error('ThemeEngine', 'Failed to update mermaid theme:', error);
@@ -148,34 +162,11 @@ export class ThemeEngine {
     });
 
     // Save current theme
-    this.currentTheme = themeObj;
+    this.core.setCurrentTheme(themeObj);
 
     debug.log('ThemeEngine', `Successfully applied theme: ${themeObj.name}`);
   }
 
-  /**
-   * Get currently applied theme
-   */
-  getCurrentTheme(): Theme | null {
-    return this.currentTheme;
-  }
-
-  /**
-   * Get list of available themes
-   */
-  getAvailableThemes(): ThemeInfo[] {
-    return [
-      { name: 'github-light', displayName: 'GitHub Light', variant: 'light' },
-      { name: 'github-dark', displayName: 'GitHub Dark', variant: 'dark' },
-      { name: 'catppuccin-latte', displayName: 'Catppuccin Latte', variant: 'light' },
-      { name: 'catppuccin-frappe', displayName: 'Catppuccin Frappé', variant: 'light' },
-      { name: 'catppuccin-macchiato', displayName: 'Catppuccin Macchiato', variant: 'dark' },
-      { name: 'catppuccin-mocha', displayName: 'Catppuccin Mocha', variant: 'dark' },
-      { name: 'monokai', displayName: 'Monokai', variant: 'dark' },
-      { name: 'monokai-pro', displayName: 'Monokai Pro', variant: 'dark' },
-    ];
-  }
-
   /**
    * Watch system theme preference
    */
@@ -198,75 +189,6 @@ export class ThemeEngine {
     };
   }
 
-  /**
-   * Compile theme to CSS variables
-   */
-  compileToCSSVariables(
-    theme: Theme,
-    overrides: Partial<Theme['typography']> = {}
-  ): Record<string, string> {
-    return {
-      // Colors
-      '--md-bg': theme.colors.background,
-      '--md-bg-secondary': theme.colors.backgroundSecondary,
-      '--md-bg-tertiary': theme.colors.backgroundTertiary,
-      '--md-fg': theme.colors.foreground,
-      '--md-fg-secondary': theme.colors.foregroundSecondary,
-      '--md-fg-muted': theme.colors.foregroundMuted,
-      '--md-primary': theme.colors.primary,
-      '--md-secondary': theme.colors.secondary,
-      '--md-accent': theme.colors.accent,
-      '--md-heading': theme.colors.heading,
-      '--md-link': theme.colors.link,
-      '--md-link-hover': theme.colors.linkHover,
-      '--md-link-visited': theme.colors.linkVisited,
-      '--md-code-bg': theme.colors.codeBackground,
-      '--md-code-text': theme.colors.codeText,
-      '--md-code-keyword': theme.colors.codeKeyword,
-      '--md-code-string': theme.colors.codeString,
-      '--md-code-comment': theme.colors.codeComment,
-      '--md-code-function': theme.colors.codeFunction,
-      '--md-border': theme.colors.border,
-      '--md-border-light': theme.colors.borderLight,
-      '--md-border-heavy': theme.colors.borderHeavy,
-      '--md-selection': theme.colors.selection,
-      '--md-highlight': theme.colors.highlight,
-      '--md-shadow': theme.colors.shadow,
-      '--md-success': theme.colors.success,
-      '--md-warning': theme.colors.warning,
-      '--md-error': theme.colors.error,
-      '--md-info': theme.colors.info,
-      '--md-comment-highlight': theme.colors.commentHighlight,
-      '--md-comment-highlight-resolved': theme.colors.commentHighlightResolved,
-      '--md-comment-card-bg': theme.colors.commentCardBg,
-
-      // Typography (with overrides)
-      '--md-font-family': overrides.fontFamily || theme.typography.fontFamily,
-      '--md-font-family-heading':
-        theme.typography.headingFontFamily || overrides.fontFamily || theme.typography.fontFamily,
-      '--md-font-family-code': overrides.codeFontFamily || theme.typography.codeFontFamily,
-      '--md-font-size': theme.typography.baseFontSize,
-      '--md-line-height': (overrides.baseLineHeight || theme.typography.baseLineHeight).toString(),
-      '--md-h1-size': theme.typography.h1Size,
-      '--md-h2-size': theme.typography.h2Size,
-      '--md-h3-size': theme.typography.h3Size,
-      '--md-h4-size': theme.typography.h4Size,
-      '--md-h5-size': theme.typography.h5Size,
-      '--md-h6-size': theme.typography.h6Size,
-      '--md-font-weight': theme.typography.fontWeightNormal.toString(),
-      '--md-font-weight-bold': theme.typography.fontWeightBold.toString(),
-      '--md-heading-font-weight': theme.typography.headingFontWeight.toString(),
-
-      // Spacing
-      '--md-block-margin': theme.spacing.blockMargin,
-      '--md-paragraph-margin': theme.spacing.paragraphMargin,
-      '--md-list-item-margin': theme.spacing.listItemMargin,
-      '--md-heading-margin': theme.spacing.headingMargin,
-      '--md-code-block-padding': theme.spacing.codeBlockPadding,
-      '--md-table-cell-padding': theme.spacing.tableCellPadding,
-    };
-  }
-
   /**
    * Update syntax highlighting theme
    */
diff --git a/src/ui/export-ui.ts b/src/ui/export-ui.ts
index 40f8ca7..b8e9a8e 100644
--- a/src/ui/export-ui.ts
+++ b/src/ui/export-ui.ts
@@ -1,737 +1,44 @@
+// Re-export shim: export-ui has moved to @mdview/core
+// This shim provides Chrome extension MessagingAdapter and platform-specific factories.
+// It will be removed in Phase 2.9
+
+import type { ExportUIOptions } from '../types';
+import type { MessagingAdapter, IPCMessage } from '../../packages/core/src/adapters';
+import {
+  ExportUI as CoreExportUI,
+  type CoreExportUIOptions,
+} from '../../packages/core/src/ui/export-ui';
+
+/** Chrome extension MessagingAdapter using chrome.runtime.sendMessage */
+class ChromeMessagingAdapter implements MessagingAdapter {
+  async send(message: IPCMessage): Promise<unknown> {
+    return chrome.runtime.sendMessage(message);
+  }
+}
+
 /**
- * Export UI Component
- * Provides a user interface for exporting markdown to various formats
+ * ExportUI wrapper that injects Chrome-specific dependencies.
+ *
+ * Maintains the same constructor signature as the original so that
+ * existing call-sites (e.g. content-script.ts) continue to work
+ * without modification.
  */
-
-import type {
-  ExportUIOptions,
-  ExportUIState,
-  ExportFormat,
-  ExportProgress,
-  PaperSize,
-} from '../types';
-import { debug } from '../utils/debug-logger';
-import { ExportController } from '../core/export-controller';
-
-export class ExportUI {
-  private button: HTMLElement | null = null;
-  private menu: HTMLElement | null = null;
-  private progressOverlay: HTMLElement | null = null;
-  private toast: HTMLElement | null = null;
-  private options: ExportUIOptions;
-  private state: ExportUIState;
-  private boundHandlers: Map<string, EventListener>;
-  private exportController: ExportController;
-  private toastTimeout: number | null = null;
-  private abortController: AbortController | null = null;
-
+export class ExportUI extends CoreExportUI {
   constructor(options?: ExportUIOptions) {
-    this.options = {
-      position: options?.position || 'left',
-      formats: options?.formats || ['docx', 'pdf'],
-      defaultPageSize: options?.defaultPageSize || 'A4',
-    };
-
-    this.state = {
-      isMenuOpen: false,
-      isExporting: false,
-      currentProgress: null,
-      lastError: null,
-    };
-
-    this.boundHandlers = new Map();
-    this.exportController = new ExportController();
-
-    // Load preferences asynchronously
-    void this.loadPreferences();
-
-    debug.info('ExportUI', 'Export UI initialized');
-  }
-
-  /**
-   * Create the export button
-   */
-  createExportButton(): HTMLElement {
-    this.button = document.createElement('button');
-    this.button.className = `mdview-export-btn position-${this.options.position}`;
-    this.button.setAttribute('aria-label', 'Export document');
-    this.button.setAttribute('aria-haspopup', 'menu');
-    this.button.setAttribute('aria-expanded', 'false');
-    this.button.setAttribute('title', 'Export Document');
-
-    // Download icon (SVG for crisp rendering)
-    this.button.innerHTML = `
-      <svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor">
-        <path d="M12 16l-6-6h4V4h4v6h4l-6 6z"/>
-        <path d="M20 18H4v2h16v-2z"/>
-      </svg>
-    `;
-
-    const clickHandler = () => this.toggleMenu();
-    this.button.addEventListener('click', clickHandler);
-    this.boundHandlers.set('button-click', clickHandler);
-
-    debug.info('ExportUI', 'Export button created');
-    return this.button;
-  }
-
-  /**
-   * Create the export menu
-   */
-  private createMenu(): HTMLElement {
-    this.menu = document.createElement('div');
-    this.menu.className = `mdview-export-menu position-${this.options.position}`;
-    this.menu.setAttribute('role', 'menu');
-    this.menu.setAttribute('aria-label', 'Export options');
-
-    // Menu header
-    const header = document.createElement('div');
-    header.className = 'mdview-export-menu-header';
-    header.innerHTML = `
-      <span>Export Document</span>
-      <button class="mdview-export-menu-close" aria-label="Close">×</button>
-    `;
-    this.menu.appendChild(header);
-
-    // Format section
-    const formatSection = document.createElement('div');
-    formatSection.className = 'mdview-export-menu-section';
-
-    const formatLabel = document.createElement('span');
-    formatLabel.className = 'mdview-export-menu-label';
-    formatLabel.textContent = 'FORMAT';
-    formatSection.appendChild(formatLabel);
-
-    // DOCX option
-    if (this.options.formats?.includes('docx')) {
-      const docxButton = this.createFormatButton('docx', 'W', 'Word Document', '.docx');
-      formatSection.appendChild(docxButton);
-    }
-
-    // PDF option
-    if (this.options.formats?.includes('pdf')) {
-      const pdfButton = this.createFormatButton('pdf', 'P', 'PDF / Print', 'Browser print dialog');
-      formatSection.appendChild(pdfButton);
-    }
-
-    this.menu.appendChild(formatSection);
-
-    // Divider
-    const divider = document.createElement('div');
-    divider.className = 'mdview-export-menu-divider';
-    this.menu.appendChild(divider);
-
-    // Options section
-    const optionsSection = document.createElement('div');
-    optionsSection.className = 'mdview-export-menu-section';
-
-    const optionsLabel = document.createElement('span');
-    optionsLabel.className = 'mdview-export-menu-label';
-    optionsLabel.textContent = 'OPTIONS';
-    optionsSection.appendChild(optionsLabel);
-
-    // Table of Contents checkbox
-    const tocOption = document.createElement('label');
-    tocOption.className = 'mdview-export-option';
-    tocOption.innerHTML = `
-      <input type="checkbox" id="export-toc" checked />
-      <span>Include Table of Contents</span>
-    `;
-    optionsSection.appendChild(tocOption);
-
-    // Page size select
-    const pageSizeOption = document.createElement('div');
-    pageSizeOption.className = 'mdview-export-option';
-    const defaultSize = this.options.defaultPageSize || 'A4';
-    pageSizeOption.innerHTML = `
-      <label for="export-page-size">Page Size:</label>
-      <select id="export-page-size">
-        <optgroup label="ISO A-Series">
-          <option value="A0" ${defaultSize === 'A0' ? 'selected' : ''}>A0</option>
-          <option value="A1" ${defaultSize === 'A1' ? 'selected' : ''}>A1</option>
-          <option value="A3" ${defaultSize === 'A3' ? 'selected' : ''}>A3</option>
-          <option value="A4" ${defaultSize === 'A4' ? 'selected' : ''}>A4</option>
-          <option value="A5" ${defaultSize === 'A5' ? 'selected' : ''}>A5</option>
-          <option value="A6" ${defaultSize === 'A6' ? 'selected' : ''}>A6</option>
-        </optgroup>
-        <optgroup label="North American">
-          <option value="Letter" ${defaultSize === 'Letter' ? 'selected' : ''}>Letter</option>
-          <option value="Legal" ${defaultSize === 'Legal' ? 'selected' : ''}>Legal</option>
-          <option value="Tabloid" ${defaultSize === 'Tabloid' ? 'selected' : ''}>Tabloid</option>
-          <option value="Executive" ${defaultSize === 'Executive' ? 'selected' : ''}>Executive</option>
-        </optgroup>
-      </select>
-    `;
-    optionsSection.appendChild(pageSizeOption);
-
-    this.menu.appendChild(optionsSection);
-
-    // Setup event listeners
-    this.setupMenuListeners();
-
-    debug.info('ExportUI', 'Export menu created');
-    return this.menu;
-  }
-
-  /**
-   * Create a format button
-   */
-  private createFormatButton(
-    format: ExportFormat,
-    icon: string,
-    title: string,
-    description: string
-  ): HTMLElement {
-    const button = document.createElement('button');
-    button.className = 'mdview-export-menu-item';
-    button.setAttribute('role', 'menuitem');
-    button.setAttribute('data-format', format);
-
-    const iconSpan = document.createElement('span');
-    iconSpan.className = 'mdview-export-menu-item-icon';
-    iconSpan.textContent = icon;
-
-    const contentSpan = document.createElement('span');
-    contentSpan.className = 'mdview-export-menu-item-content';
-
-    const titleSpan = document.createElement('span');
-    titleSpan.className = 'mdview-export-menu-item-title';
-    titleSpan.textContent = title;
-
-    const descSpan = document.createElement('span');
-    descSpan.className = 'mdview-export-menu-item-desc';
-    descSpan.textContent = description;
-
-    contentSpan.appendChild(titleSpan);
-    contentSpan.appendChild(descSpan);
-
-    button.appendChild(iconSpan);
-    button.appendChild(contentSpan);
-
-    const clickHandler = () => {
-      void this.handleExport(format);
-    };
-    button.addEventListener('click', clickHandler);
-    this.boundHandlers.set(`format-${format}`, clickHandler);
-
-    return button;
-  }
-
-  /**
-   * Setup menu event listeners
-   */
-  private setupMenuListeners(): void {
-    if (!this.menu) return;
-
-    // Close button
-    const closeButton = this.menu.querySelector('.mdview-export-menu-close');
-    if (closeButton) {
-      const closeHandler = () => this.hideMenu();
-      closeButton.addEventListener('click', closeHandler);
-      this.boundHandlers.set('menu-close', closeHandler as EventListener);
-    }
-
-    // Click outside to close
-    const clickOutsideHandler = (e: MouseEvent) => this.handleClickOutside(e);
-    document.addEventListener('click', clickOutsideHandler);
-    this.boundHandlers.set('click-outside', clickOutsideHandler as EventListener);
-
-    // Keyboard navigation
-    const keyDownHandler = (e: KeyboardEvent) => this.handleKeyDown(e);
-    document.addEventListener('keydown', keyDownHandler);
-    this.boundHandlers.set('keydown', keyDownHandler as EventListener);
-  }
-
-  /**
-   * Handle click outside menu
-   */
-  private handleClickOutside(e: MouseEvent): void {
-    if (!this.state.isMenuOpen) return;
-
-    const target = e.target as Node;
-    if (
-      this.menu &&
-      !this.menu.contains(target) &&
-      this.button &&
-      !this.button.contains(target)
-    ) {
-      this.hideMenu();
-    }
-  }
-
-  /**
-   * Handle keyboard navigation
-   */
-  private handleKeyDown(e: KeyboardEvent): void {
-    if (!this.state.isMenuOpen) return;
-
-    if (e.key === 'Escape') {
-      this.hideMenu();
-      this.button?.focus();
-      return;
-    }
-
-    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
-      e.preventDefault();
-      this.navigateMenu(e.key === 'ArrowDown' ? 1 : -1);
-    }
-
-    if (e.key === 'Enter') {
-      const focusedElement = document.activeElement;
-      if (focusedElement instanceof HTMLElement) {
-        focusedElement.click();
-      }
-    }
-  }
-
-  /**
-   * Navigate menu with arrow keys
-   */
-  private navigateMenu(direction: 1 | -1): void {
-    if (!this.menu) return;
-
-    const items = Array.from(
-      this.menu.querySelectorAll<HTMLElement>('.mdview-export-menu-item')
-    );
-
-    if (items.length === 0) return;
-
-    const currentIndex = items.indexOf(document.activeElement as HTMLElement);
-    let nextIndex: number;
-
-    if (currentIndex === -1) {
-      nextIndex = direction === 1 ? 0 : items.length - 1;
-    } else {
-      nextIndex = (currentIndex + direction + items.length) % items.length;
-    }
-
-    items[nextIndex].focus();
-  }
-
-  /**
-   * Show the menu
-   */
-  showMenu(): void {
-    if (!this.menu) {
-      this.createMenu();
-      document.body.appendChild(this.menu!);
-    }
-
-    this.state.isMenuOpen = true;
-    this.menu?.classList.add('visible');
-
-    if (this.button) {
-      this.button.classList.add('menu-open');
-      this.button.setAttribute('aria-expanded', 'true');
-    }
-
-    // Focus first menu item
-    const firstItem = this.menu?.querySelector('.mdview-export-menu-item') as HTMLElement;
-    setTimeout(() => firstItem?.focus(), 100);
-
-    debug.info('ExportUI', 'Menu shown');
-  }
-
-  /**
-   * Hide the menu
-   */
-  hideMenu(): void {
-    this.state.isMenuOpen = false;
-    this.menu?.classList.remove('visible');
-
-    if (this.button) {
-      this.button.classList.remove('menu-open');
-      this.button.setAttribute('aria-expanded', 'false');
-    }
-
-    debug.info('ExportUI', 'Menu hidden');
-  }
-
-  /**
-   * Toggle menu visibility
-   */
-  toggleMenu(): void {
-    if (this.state.isMenuOpen) {
-      this.hideMenu();
-    } else {
-      this.showMenu();
-    }
-  }
-
-  /**
-   * Handle export action
-   */
-  private async handleExport(format: ExportFormat): Promise<void> {
-    debug.info('ExportUI', `Starting export: ${format}`);
-
-    this.hideMenu();
-
-    // Get options from UI
-    const tocCheckbox = document.getElementById('export-toc') as HTMLInputElement;
-    const pageSizeSelect = document.getElementById('export-page-size') as HTMLSelectElement;
-
-    // For PDF, use PDFGenerator
-    if (format === 'pdf') {
-      try {
-        this.state.isExporting = true;
-        this.button?.classList.add('exporting');
-
-        // Create abort controller so Cancel button can stop long-running work
-        this.abortController = new AbortController();
-
-        this.showProgress({
-          stage: 'collecting',
-          progress: 5,
-          message: 'Preparing document for print...',
-        });
-
-        const container = document.getElementById('mdview-container');
-        if (!container) {
-          throw new Error('Content container not found');
-        }
-
-        const { PDFGenerator } = await import('../utils/pdf-generator');
-        const generator = new PDFGenerator();
-
-        await generator.print(
-          container,
-          {
-            paperSize: (pageSizeSelect?.value as PaperSize) || this.options.defaultPageSize,
-            convertSvgsToImages: true,
-          },
-          (progress: ExportProgress) => {
-            this.updateProgress(progress);
-          },
-          this.abortController.signal
-        );
-
-        this.hideProgress();
-        this.showSuccess('Print dialog opened');
-      } catch (error) {
-        debug.error('ExportUI', 'Print failed:', error);
-        this.hideProgress();
-        if (error instanceof DOMException && error.name === 'AbortError') {
-          this.showError(new Error('PDF export cancelled'));
-        } else {
-          this.showError(error instanceof Error ? error : new Error('Print failed'));
-        }
-      } finally {
-        this.state.isExporting = false;
-        this.button?.classList.remove('exporting');
-        this.abortController = null;
-      }
-      return;
-    }
-
-    // Generate filename from template
-    const { FilenameGenerator } = await import('../utils/filename-generator');
-    const filename = FilenameGenerator.generate({
-      title: document.title || 'document',
-      extension: '', // Extension will be added by ExportController
-      template: this.options.filenameTemplate || '{title}',
-    }).replace(/\.(docx|pdf)$/, ''); // Remove extension as it will be added by the controller
-
-    const options = {
-      format,
-      filename,
-      includeTableOfContents: tocCheckbox?.checked !== false,
-      pageSize: (pageSizeSelect?.value as PaperSize) || this.options.defaultPageSize,
-    };
-
-    // Start export
-    this.state.isExporting = true;
-    this.button?.classList.add('exporting');
-
-    // Create abort controller for cancellation
-    this.abortController = new AbortController();
-
-    try {
-      // Get the container to export
-      const container = document.getElementById('mdview-container');
-      if (!container) {
-        throw new Error('Content container not found');
-      }
-
-      // Show progress overlay
-      this.showProgress({
-        stage: 'collecting',
-        progress: 0,
-        message: 'Collecting content...',
-      });
-
-      // Perform export with progress callback
-      await this.exportController.export(container, options, (progress: ExportProgress) => {
-        this.updateProgress(progress);
-      });
-
-      // Success
-      this.hideProgress();
-      this.showSuccess(`Document exported successfully`);
-
-      debug.info('ExportUI', 'Export completed successfully');
-    } catch (error) {
-      debug.error('ExportUI', 'Export failed:', error);
-      this.hideProgress();
-      this.showError(error instanceof Error ? error : new Error('Export failed'));
-      this.state.lastError = error instanceof Error ? error : new Error('Export failed');
-    } finally {
-      this.state.isExporting = false;
-      this.button?.classList.remove('exporting');
-      this.abortController = null;
-    }
-  }
-
-  /**
-   * Create progress overlay
-   */
-  private createProgressOverlay(): HTMLElement {
-    this.progressOverlay = document.createElement('div');
-    this.progressOverlay.className = 'mdview-export-progress-overlay';
-
-    const container = document.createElement('div');
-    container.className = 'mdview-export-progress-container';
-
-    const progressBar = document.createElement('div');
-    progressBar.className = 'mdview-export-progress-bar';
-
-    const progressFill = document.createElement('div');
-    progressFill.className = 'mdview-export-progress-fill';
-    progressFill.style.width = '0%';
-    progressBar.appendChild(progressFill);
-
-    const progressText = document.createElement('div');
-    progressText.className = 'mdview-export-progress-text';
-    progressText.textContent = 'Starting export...';
-
-    const cancelButton = document.createElement('button');
-    cancelButton.className = 'mdview-export-progress-cancel';
-    cancelButton.textContent = 'Cancel';
-
-    const cancelHandler = () => {
-      if (this.abortController) {
-        this.abortController.abort();
-        this.hideProgress();
-        this.showError(new Error('Export cancelled'));
-      }
+    const coreOptions: CoreExportUIOptions = {
+      ...options,
+      messaging: new ChromeMessagingAdapter(),
+      factories: {
+        createExportController: async () => {
+          const { ExportController } = await import('../core/export-controller');
+          return new ExportController();
+        },
+        createPDFGenerator: async () => {
+          const { PDFGenerator } = await import('../utils/pdf-generator');
+          return new PDFGenerator();
+        },
+      },
     };
-    cancelButton.addEventListener('click', cancelHandler);
-    this.boundHandlers.set('progress-cancel', cancelHandler);
-
-    container.appendChild(progressBar);
-    container.appendChild(progressText);
-    container.appendChild(cancelButton);
-
-    this.progressOverlay.appendChild(container);
-
-    return this.progressOverlay;
-  }
-
-  /**
-   * Show progress overlay
-   */
-  showProgress(progress: ExportProgress): void {
-    if (!this.progressOverlay) {
-      this.createProgressOverlay();
-      document.body.appendChild(this.progressOverlay!);
-    }
-
-    this.state.currentProgress = progress;
-    this.progressOverlay?.classList.add('visible');
-    this.updateProgress(progress);
-
-    debug.info('ExportUI', `Progress: ${progress.stage} - ${progress.progress}%`);
-  }
-
-  /**
-   * Update progress display
-   */
-  private updateProgress(progress: ExportProgress): void {
-    if (!this.progressOverlay) return;
-
-    const fill = this.progressOverlay.querySelector(
-      '.mdview-export-progress-fill'
-    ) as HTMLElement;
-    const text = this.progressOverlay.querySelector(
-      '.mdview-export-progress-text'
-    ) as HTMLElement;
-
-    if (fill) {
-      fill.style.width = `${progress.progress}%`;
-    }
-
-    if (text) {
-      text.textContent = progress.message;
-    }
-
-    this.state.currentProgress = progress;
-  }
-
-  /**
-   * Hide progress overlay
-   */
-  hideProgress(): void {
-    this.progressOverlay?.classList.remove('visible');
-    this.state.currentProgress = null;
-
-    debug.info('ExportUI', 'Progress hidden');
-  }
-
-  /**
-   * Create toast notification
-   */
-  private createToast(type: 'success' | 'error', message: string): HTMLElement {
-    this.toast = document.createElement('div');
-    this.toast.className = `mdview-export-toast ${type}`;
-    this.toast.textContent = message;
-
-    return this.toast;
-  }
-
-  /**
-   * Show success toast
-   */
-  showSuccess(filename: string): void {
-    this.createToast('success', filename);
-    document.body.appendChild(this.toast!);
-
-    // Show with animation
-    setTimeout(() => {
-      this.toast?.classList.add('visible');
-    }, 10);
-
-    // Auto-dismiss after 3 seconds
-    this.toastTimeout = window.setTimeout(() => {
-      this.hideToast();
-    }, 3000);
-
-    debug.info('ExportUI', 'Success toast shown');
-  }
-
-  /**
-   * Show error toast
-   */
-  showError(error: Error): void {
-    this.createToast('error', error.message || 'Export failed');
-    document.body.appendChild(this.toast!);
-
-    // Show with animation
-    setTimeout(() => {
-      this.toast?.classList.add('visible');
-    }, 10);
-
-    // Auto-dismiss after 5 seconds (longer for errors)
-    this.toastTimeout = window.setTimeout(() => {
-      this.hideToast();
-    }, 5000);
-
-    debug.error('ExportUI', 'Error toast shown:', error);
-  }
-
-  /**
-   * Hide toast notification
-   */
-  private hideToast(): void {
-    this.toast?.classList.remove('visible');
-
-    setTimeout(() => {
-      this.toast?.remove();
-      this.toast = null;
-    }, 300);
-
-    if (this.toastTimeout !== null) {
-      window.clearTimeout(this.toastTimeout);
-      this.toastTimeout = null;
-    }
-  }
-
-  /**
-   * Load export preferences from storage
-   */
-  private async loadPreferences(): Promise<void> {
-    interface StateResponse {
-      state?: {
-        preferences?: {
-          exportDefaultFormat?: ExportFormat;
-          exportDefaultPageSize?: PaperSize;
-          exportIncludeToc?: boolean;
-          exportFilenameTemplate?: string;
-        };
-      };
-    }
-
-    try {
-      const response: StateResponse = await chrome.runtime.sendMessage({ type: 'GET_STATE' });
-      const state = response?.state;
-
-      if (state?.preferences) {
-        const { exportDefaultFormat, exportDefaultPageSize, exportIncludeToc, exportFilenameTemplate } =
-          state.preferences;
-
-        // Update options with saved preferences
-        if (exportDefaultFormat) {
-          this.options.defaultFormat = exportDefaultFormat;
-        }
-        if (exportDefaultPageSize) {
-          this.options.defaultPageSize = exportDefaultPageSize;
-        }
-        if (exportIncludeToc !== undefined) {
-          this.options.includeTableOfContents = exportIncludeToc;
-        }
-        if (exportFilenameTemplate) {
-          this.options.filenameTemplate = exportFilenameTemplate;
-        }
-
-        debug.info('ExportUI', 'Loaded export preferences:', {
-          format: this.options.defaultFormat,
-          pageSize: this.options.defaultPageSize,
-        });
-      }
-    } catch (error) {
-      debug.warn('ExportUI', 'Failed to load export preferences:', error);
-    }
-  }
-
-  /**
-   * Clean up resources
-   */
-  destroy(): void {
-    // Remove event listeners
-    this.boundHandlers.forEach((handler, key) => {
-      if (key === 'button-click' && this.button) {
-        this.button.removeEventListener('click', handler);
-      } else if (key === 'click-outside') {
-        document.removeEventListener('click', handler);
-      } else if (key === 'keydown') {
-        document.removeEventListener('keydown', handler);
-      }
-    });
-    this.boundHandlers.clear();
-
-    // Remove elements
-    this.button?.remove();
-    this.menu?.remove();
-    this.progressOverlay?.remove();
-    this.toast?.remove();
-
-    // Clear timeouts
-    if (this.toastTimeout !== null) {
-      window.clearTimeout(this.toastTimeout);
-    }
-
-    // Abort any ongoing export
-    if (this.abortController) {
-      this.abortController.abort();
-    }
-
-    // Reset state
-    this.button = null;
-    this.menu = null;
-    this.progressOverlay = null;
-    this.toast = null;
-    this.toastTimeout = null;
-    this.abortController = null;
-
-    debug.info('ExportUI', 'Export UI destroyed');
+    super(coreOptions);
   }
 }
-

From df11f560bc84afddd761913b2b03f4466dfac2cf Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:51:44 -0400
Subject: [PATCH 15/26] refactor(core): extract render-pipeline with
 MessagingAdapter

---
 .../src/__tests__/render-pipeline.test.ts     |  293 +++++
 packages/core/src/index.ts                    |   11 +
 packages/core/src/render-pipeline.ts          | 1061 +++++++++++++++++
 src/core/render-pipeline.ts                   | 1060 +---------------
 4 files changed, 1403 insertions(+), 1022 deletions(-)
 create mode 100644 packages/core/src/__tests__/render-pipeline.test.ts
 create mode 100644 packages/core/src/render-pipeline.ts

diff --git a/packages/core/src/__tests__/render-pipeline.test.ts b/packages/core/src/__tests__/render-pipeline.test.ts
new file mode 100644
index 0000000..79d387e
--- /dev/null
+++ b/packages/core/src/__tests__/render-pipeline.test.ts
@@ -0,0 +1,293 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { MessagingAdapter, IPCMessage } from '../adapters';
+
+// Mock heavy dependencies that live outside @mdview/core
+vi.mock('../../../../src/utils/dom-purifier', () => ({
+  domPurifier: {
+    sanitize: (html: string) => html,
+  },
+}));
+
+vi.mock('../../../../src/workers/worker-pool', () => ({
+  workerPool: {
+    initialize: vi.fn().mockResolvedValue(undefined),
+    execute: vi.fn(),
+  },
+}));
+
+vi.mock('../../../../src/renderers/syntax-highlighter', () => ({
+  syntaxHighlighter: {
+    highlightVisible: vi.fn(),
+  },
+}));
+
+vi.mock('../../../../src/renderers/mermaid-renderer', () => ({
+  mermaidRenderer: {
+    renderAll: vi.fn().mockResolvedValue(undefined),
+  },
+}));
+
+vi.mock('../../../../src/utils/toc-stripper', () => ({
+  stripTableOfContents: vi.fn((md: string) => ({ markdown: md, tocFound: false })),
+}));
+
+vi.mock('../../../../src/comments/annotation-parser', () => ({
+  parseComments: vi.fn((md: string) => ({
+    cleanedMarkdown: md,
+    comments: [],
+  })),
+}));
+
+vi.mock('../../../../src/utils/skeleton-renderer', () => ({
+  SkeletonRenderer: {
+    generateSkeleton: vi.fn(() => '<div>skeleton</div>'),
+    isHydrated: vi.fn(() => false),
+    markHydrated: vi.fn(),
+  },
+}));
+
+import { RenderPipeline } from '../render-pipeline';
+
+describe('RenderPipeline', () => {
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    vi.clearAllMocks();
+  });
+
+  describe('with MessagingAdapter', () => {
+    it('sends CACHE_GENERATE_KEY and CACHE_GET when useCache is true', async () => {
+      const mockMessaging: MessagingAdapter = {
+        send: vi.fn().mockImplementation(async (msg: IPCMessage) => {
+          if (msg.type === 'CACHE_GENERATE_KEY') {
+            return { key: 'test-cache-key' };
+          }
+          if (msg.type === 'CACHE_GET') {
+            return { result: null };
+          }
+          if (msg.type === 'CACHE_SET') {
+            return {};
+          }
+          return {};
+        }),
+      };
+
+      const pipeline = new RenderPipeline({ messaging: mockMessaging });
+
+      await pipeline.render({
+        container,
+        markdown: '# Hello',
+        filePath: '/test.md',
+        useCache: true,
+        useWorkers: false,
+      });
+
+      // Should have called CACHE_GENERATE_KEY
+      expect(mockMessaging.send).toHaveBeenCalledWith(
+        expect.objectContaining({ type: 'CACHE_GENERATE_KEY' })
+      );
+
+      // Should have called CACHE_GET
+      expect(mockMessaging.send).toHaveBeenCalledWith(
+        expect.objectContaining({ type: 'CACHE_GET' })
+      );
+    });
+
+    it('uses cached result when adapter returns a cache hit', async () => {
+      const cachedHtml = '<div class="mdview-rendered"><p>Cached content</p></div>';
+      const mockMessaging: MessagingAdapter = {
+        send: vi.fn().mockImplementation(async (msg: IPCMessage) => {
+          if (msg.type === 'CACHE_GENERATE_KEY') {
+            return { key: 'cached-key' };
+          }
+          if (msg.type === 'CACHE_GET') {
+            return {
+              result: {
+                html: cachedHtml,
+                metadata: { headings: [], codeBlocks: [], mermaidBlocks: [], images: [], links: [], wordCount: 0, frontmatter: null },
+                highlightedBlocks: new Map(),
+                mermaidSVGs: new Map(),
+                timestamp: Date.now(),
+                cacheKey: 'cached-key',
+              },
+            };
+          }
+          return {};
+        }),
+      };
+
+      const pipeline = new RenderPipeline({ messaging: mockMessaging });
+
+      const progressUpdates: string[] = [];
+      pipeline.onProgress((p) => progressUpdates.push(p.stage));
+
+      await pipeline.render({
+        container,
+        markdown: '# Hello',
+        filePath: '/test.md',
+        useCache: true,
+        useWorkers: false,
+      });
+
+      expect(container.innerHTML).toBe(cachedHtml);
+      expect(progressUpdates).toContain('cached');
+    });
+
+    it('sends CACHE_SET after successful render', async () => {
+      const mockMessaging: MessagingAdapter = {
+        send: vi.fn().mockImplementation(async (msg: IPCMessage) => {
+          if (msg.type === 'CACHE_GENERATE_KEY') {
+            return { key: 'new-cache-key' };
+          }
+          if (msg.type === 'CACHE_GET') {
+            return { result: null };
+          }
+          if (msg.type === 'CACHE_SET') {
+            return {};
+          }
+          return {};
+        }),
+      };
+
+      const pipeline = new RenderPipeline({ messaging: mockMessaging });
+
+      await pipeline.render({
+        container,
+        markdown: '# Hello',
+        filePath: '/test.md',
+        useCache: true,
+        useWorkers: false,
+      });
+
+      expect(mockMessaging.send).toHaveBeenCalledWith(
+        expect.objectContaining({ type: 'CACHE_SET' })
+      );
+    });
+  });
+
+  describe('without MessagingAdapter (graceful degradation)', () => {
+    it('renders markdown without an adapter', async () => {
+      const pipeline = new RenderPipeline();
+
+      await pipeline.render({
+        container,
+        markdown: '# Hello World',
+        useCache: true,
+        filePath: '/test.md',
+        useWorkers: false,
+      });
+
+      // Should still render successfully (just skips caching)
+      expect(container.innerHTML).toBeTruthy();
+      expect(container.innerHTML).toContain('Hello World');
+    });
+
+    it('does not throw when useCache is true but no adapter', async () => {
+      const pipeline = new RenderPipeline();
+
+      await expect(
+        pipeline.render({
+          container,
+          markdown: '**Bold text**',
+          filePath: '/test.md',
+          useCache: true,
+          useWorkers: false,
+        })
+      ).resolves.not.toThrow();
+
+      expect(container.innerHTML).toContain('Bold text');
+    });
+
+    it('skips all caching operations without an adapter', async () => {
+      const pipeline = new RenderPipeline();
+
+      const progressUpdates: string[] = [];
+      pipeline.onProgress((p) => progressUpdates.push(p.stage));
+
+      await pipeline.render({
+        container,
+        markdown: '# Test',
+        filePath: '/test.md',
+        useCache: true,
+        useWorkers: false,
+      });
+
+      // Should NOT have a 'cached' stage (no adapter means no cache hit)
+      expect(progressUpdates).not.toContain('cached');
+      // Should still complete
+      expect(progressUpdates).toContain('complete');
+    });
+
+    it('renders without filePath and without adapter', async () => {
+      const pipeline = new RenderPipeline();
+
+      await pipeline.render({
+        container,
+        markdown: '# No file path',
+        useWorkers: false,
+      });
+
+      expect(container.innerHTML).toContain('No file path');
+    });
+  });
+
+  describe('core pipeline features', () => {
+    it('supports progress callbacks', async () => {
+      const pipeline = new RenderPipeline();
+      const stages: string[] = [];
+
+      pipeline.onProgress((p) => stages.push(p.stage));
+
+      await pipeline.render({
+        container,
+        markdown: '# Test',
+        useWorkers: false,
+        useCache: false,
+      });
+
+      expect(stages).toContain('parsing');
+      expect(stages).toContain('complete');
+    });
+
+    it('supports unsubscribing from progress', async () => {
+      const pipeline = new RenderPipeline();
+      const stages: string[] = [];
+
+      const unsub = pipeline.onProgress((p) => stages.push(p.stage));
+      unsub();
+
+      await pipeline.render({
+        container,
+        markdown: '# Test',
+        useWorkers: false,
+        useCache: false,
+      });
+
+      expect(stages).toHaveLength(0);
+    });
+
+    it('cancelRender stops the pipeline', async () => {
+      const pipeline = new RenderPipeline();
+
+      // Cancel immediately
+      pipeline.cancelRender();
+
+      await pipeline.render({
+        container,
+        markdown: '# Test',
+        useWorkers: false,
+        useCache: false,
+      });
+
+      // Container should be empty since render was cancelled at the start
+      // (after parsing, before sanitizing)
+      // The exact behavior depends on timing, but it should not throw
+    });
+
+    it('getLastCommentParseResult returns null before rendering', () => {
+      const pipeline = new RenderPipeline();
+      expect(pipeline.getLastCommentParseResult()).toBeNull();
+    });
+  });
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 982e9a4..6b13168 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -30,6 +30,9 @@ export {
 } from './comments/annotation-serializer';
 // v1 comment format (legacy)
 export { parseComments } from './comments/comment-parser';
+// Comment manager
+export { CommentManager } from './comments/comment-manager';
+export type { CommentManagerAdapters } from './comments/comment-manager';
 // Context & utilities
 export * from './comments/comment-context';
 export * from './comments/source-position-map';
@@ -54,9 +57,17 @@ export type { CacheOptions } from './cache-manager';
 export { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extractor';
 export type { FrontmatterResult } from './frontmatter-extractor';
 
+// Debug logger
+export { DebugLogger, createDebugLogger, createDebug } from './utils/debug-logger';
+export type { DebugHelpers } from './utils/debug-logger';
+
 // Theme engine
 export { ThemeEngine } from './theme-engine';
 export type { ThemeInfo, ThemeOverrides } from './theme-engine';
 
+// Render pipeline
+export { RenderPipeline } from './render-pipeline';
+export type { RenderOptions, RenderProgress, ProgressCallback, RenderPipelineOptions } from './render-pipeline';
+
 // Platform adapters
 export * from './adapters';
diff --git a/packages/core/src/render-pipeline.ts b/packages/core/src/render-pipeline.ts
new file mode 100644
index 0000000..19f27ed
--- /dev/null
+++ b/packages/core/src/render-pipeline.ts
@@ -0,0 +1,1061 @@
+/**
+ * Render Pipeline
+ * Multi-stage pipeline for rendering markdown with progressive enhancement
+ *
+ * Platform-agnostic version: uses MessagingAdapter instead of chrome.runtime.sendMessage.
+ * When no adapter is provided, caching is silently skipped (graceful degradation).
+ */
+
+import { MarkdownConverter } from './markdown-converter';
+import { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extractor';
+import { domPurifier } from '../../../src/utils/dom-purifier';
+import { workerPool } from '../../../src/workers/worker-pool';
+import type {
+  ConversionResult,
+  ThemeName,
+  CachedResult,
+  ParseTaskPayload,
+  CommentParseResult,
+} from './types/index';
+import { splitIntoSections } from './utils/section-splitter';
+import { SkeletonRenderer } from '../../../src/utils/skeleton-renderer';
+import type { MessagingAdapter } from './adapters';
+
+// ---------------------------------------------------------------------------
+// No-op debug logger (temporary until debug-logger is extracted to core)
+// ---------------------------------------------------------------------------
+const debug = {
+  info: (..._args: unknown[]) => {},
+  debug: (..._args: unknown[]) => {},
+  error: (..._args: unknown[]) => {},
+  log: (..._args: unknown[]) => {},
+};
+
+export interface RenderOptions {
+  container: HTMLElement;
+  markdown: string;
+  theme?: string;
+  progressive?: boolean;
+  chunkSize?: number;
+  filePath?: string;
+  preferences?: Record<string, unknown>;
+  useCache?: boolean;
+  useWorkers?: boolean;
+  useLazySections?: boolean; // New: Enable lazy section rendering
+}
+
+export interface RenderProgress {
+  stage:
+    | 'parsing'
+    | 'sanitizing'
+    | 'transforming'
+    | 'enhancing'
+    | 'theming'
+    | 'complete'
+    | 'cached';
+  progress: number; // 0-100
+  message: string;
+}
+
+export type ProgressCallback = (progress: RenderProgress) => void;
+
+export interface RenderPipelineOptions {
+  messaging?: MessagingAdapter;
+}
+
+export class RenderPipeline {
+  private converter: MarkdownConverter;
+  private progressCallbacks: Set<ProgressCallback> = new Set();
+  private cancelRequested = false;
+  private workersEnabled = true;
+  private progressUpdateTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastProgressUpdate = 0;
+  private lastCommentParseResult: CommentParseResult | null = null;
+  private messaging?: MessagingAdapter;
+
+  constructor(options?: RenderPipelineOptions) {
+    this.converter = new MarkdownConverter();
+    this.messaging = options?.messaging;
+    // Initialize workers in background
+    void this.initializeWorkers();
+  }
+
+  /**
+   * Initialize worker pool
+   * Note: Workers are disabled on file:// URLs due to Chrome security
+   * The synchronous rendering path is optimized with Phase 1 improvements
+   */
+  private async initializeWorkers(): Promise<void> {
+    try {
+      await workerPool.initialize();
+      this.workersEnabled = true;
+      debug.info('RenderPipeline', 'Worker pool initialized');
+    } catch (error) {
+      // Workers unavailable - WorkerPool already logged the reason
+      // Silently fall back to synchronous rendering
+      this.workersEnabled = false;
+
+      // Only log errors for unexpected failures (non-file:// protocols)
+      if (typeof window !== 'undefined' && window.location?.protocol !== 'file:') {
+        debug.error('RenderPipeline', 'Worker initialization failed, using sync fallback:', error);
+      }
+    }
+  }
+
+  /**
+   * Main render function with cache and worker support
+   */
+  async render(options: RenderOptions): Promise<void> {
+    this.cancelRequested = false;
+    const {
+      container,
+      markdown,
+      theme = 'github-light',
+      filePath = '',
+      preferences = {},
+      useCache = true,
+      useWorkers = true,
+      useLazySections = false, // Lazy sections disabled by default
+    } = options;
+
+    // Update markdown converter options based on preferences
+    this.converter.updateOptions({
+      enableHtml: !!(preferences as { enableHtml?: boolean }).enableHtml,
+    });
+
+    const shouldUseWorkers = useWorkers && this.workersEnabled;
+
+    try {
+      // Check cache if enabled and adapter is available
+      if (useCache && filePath && this.messaging) {
+        const cacheKey = await this.getCacheKey(
+          filePath,
+          markdown,
+          theme as ThemeName,
+          preferences
+        );
+
+        const cached = await this.getCachedResult(cacheKey);
+        if (cached) {
+          debug.info('RenderPipeline', 'Using cached result from service worker');
+          this.notifyProgressThrottled({
+            stage: 'cached',
+            progress: 100,
+            message: 'Loading from cache...',
+          });
+
+          await this.renderFromCache(container, cached);
+          return;
+        }
+      }
+
+      // Use progressive hydration for large files (> 30KB)
+      if (useLazySections || markdown.length > 30000) {
+        debug.info('RenderPipeline', 'Using progressive hydration for large document');
+        await this.renderWithProgressiveHydration(options);
+        return;
+      }
+
+      // Preprocess: Extract frontmatter before any other processing
+      let processedMarkdown = markdown;
+      const frontmatterResult = extractFrontmatter(processedMarkdown);
+      const frontmatterData = frontmatterResult.frontmatter;
+      processedMarkdown = frontmatterResult.cleanedMarkdown;
+
+      // Preprocess: Strip existing TOC if custom TOC is enabled
+      if ((preferences as { showToc?: boolean }).showToc) {
+        const { stripTableOfContents } = await import('../../../src/utils/toc-stripper');
+        const stripResult = stripTableOfContents(processedMarkdown);
+        processedMarkdown = stripResult.markdown;
+        if (stripResult.tocFound) {
+          debug.info('RenderPipeline', 'Stripped original TOC from markdown');
+        }
+      }
+
+      // Preprocess: Strip comment footnotes before parsing
+      this.lastCommentParseResult = null;
+      if ((preferences as { commentsEnabled?: boolean }).commentsEnabled !== false) {
+        const { parseComments } = await import('../../../src/comments/annotation-parser');
+        this.lastCommentParseResult = parseComments(processedMarkdown);
+        processedMarkdown = this.lastCommentParseResult.cleanedMarkdown;
+        if (this.lastCommentParseResult.comments.length > 0) {
+          debug.info(
+            'RenderPipeline',
+            `Stripped ${this.lastCommentParseResult.comments.length} comment footnotes from markdown`
+          );
+        }
+      }
+
+      // Stage 1: Parse markdown to HTML (with worker if available)
+      this.notifyProgressThrottled({
+        stage: 'parsing',
+        progress: 10,
+        message: 'Parsing markdown...',
+      });
+
+      let result: ConversionResult;
+
+      if (shouldUseWorkers) {
+        try {
+          const taskId = `parse-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+          const payload: ParseTaskPayload = {
+            markdown: processedMarkdown,
+            options: {
+              breaks: true,
+              linkify: true,
+              typographer: true,
+              enableHtml: !!(preferences as { enableHtml?: boolean }).enableHtml,
+            },
+          };
+
+          const workerResult = await workerPool.execute<{
+            html: string;
+            metadata: ConversionResult['metadata'];
+          }>({
+            type: 'parse',
+            id: taskId,
+            payload,
+            priority: 10,
+          });
+
+          result = {
+            html: workerResult.html,
+            metadata: workerResult.metadata,
+            errors: [],
+          };
+
+          debug.debug('RenderPipeline', 'Parsed markdown in worker');
+        } catch (error) {
+          debug.error('RenderPipeline', 'Worker parsing failed, falling back to sync:', error);
+          result = this.converter.convert(processedMarkdown);
+        }
+      } else {
+        result = this.converter.convert(processedMarkdown);
+      }
+
+      if (this.cancelRequested) return;
+
+      // Stage 2: Sanitize HTML (always on main thread for security)
+      this.notifyProgressThrottled({
+        stage: 'sanitizing',
+        progress: 30,
+        message: 'Sanitizing content...',
+      });
+
+      const sanitized = this.sanitizeContent(result);
+
+      if (this.cancelRequested) return;
+
+      // Stage 3: Transform (process special blocks)
+      this.notifyProgressThrottled({
+        stage: 'transforming',
+        progress: 50,
+        message: 'Processing content...',
+      });
+
+      const transformed = this.transformContent(sanitized, result, preferences, frontmatterData);
+
+      // Store frontmatter in metadata
+      result.metadata.frontmatter = frontmatterData;
+
+      if (this.cancelRequested) return;
+
+      // Stage 4: Insert into DOM
+      const template = document.createElement('template');
+      template.innerHTML = transformed;
+
+      container.innerHTML = '';
+      container.appendChild(template.content);
+
+      // Stage 5: Enhance (add interactive features with parallel workers)
+      this.notifyProgressThrottled({
+        stage: 'enhancing',
+        progress: 70,
+        message: 'Adding interactive features...',
+      });
+
+      debug.debug('RenderPipeline', 'Enhancing content...');
+      await this.enhanceContentWithWorkers(container, result, shouldUseWorkers);
+      debug.debug('RenderPipeline', 'Content enhanced');
+
+      if (this.cancelRequested) return;
+
+      // Stage 6: Apply theme
+      this.notifyProgressThrottled({
+        stage: 'theming',
+        progress: 90,
+        message: 'Applying theme...',
+      });
+
+      debug.info('RenderPipeline', 'Applying theme...');
+      this.applyTheming(container);
+      debug.info('RenderPipeline', 'Theme applied successfully');
+
+      // Cache the result if enabled and adapter is available
+      if (useCache && filePath && this.messaging) {
+        try {
+          const cacheKey = await this.getCacheKey(
+            filePath,
+            markdown,
+            theme as ThemeName,
+            preferences
+          );
+
+          const contentHash = await this.generateContentHash(markdown);
+
+          const cachedResult: CachedResult = {
+            html: container.innerHTML,
+            metadata: result.metadata,
+            highlightedBlocks: new Map(),
+            mermaidSVGs: new Map(),
+            timestamp: Date.now(),
+            cacheKey,
+          };
+
+          await this.setCachedResult(
+            cacheKey,
+            cachedResult,
+            filePath,
+            contentHash,
+            theme as ThemeName
+          );
+          debug.debug('RenderPipeline', 'Result cached in service worker');
+        } catch (error) {
+          debug.error('RenderPipeline', 'Failed to cache result:', error);
+        }
+      }
+
+      // Complete
+      this.notifyProgressThrottled({
+        stage: 'complete',
+        progress: 100,
+        message: 'Rendering complete',
+      });
+      debug.info('RenderPipeline', 'Rendering complete');
+    } catch (error) {
+      debug.error('RenderPipeline', 'Render error:', error);
+      this.showError(container, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Render from cached result
+   */
+  private async renderFromCache(container: HTMLElement, cached: CachedResult): Promise<void> {
+    // Insert cached HTML
+    container.innerHTML = cached.html;
+
+    // Re-initialize interactive features
+    await this.reinitializeInteractiveFeatures(container);
+
+    this.notifyProgressThrottled({
+      stage: 'complete',
+      progress: 100,
+      message: 'Loaded from cache',
+    });
+  }
+
+  /**
+   * Re-initialize interactive features for cached content
+   */
+  private async reinitializeInteractiveFeatures(container: HTMLElement): Promise<void> {
+    // Re-add copy buttons
+    this.addCopyButtons(container);
+
+    // Re-setup image lazy loading
+    this.setupImageLazyLoading(container);
+
+    // Re-initialize Mermaid diagrams
+    const pendingMermaid = container.querySelectorAll('.mermaid-container.mermaid-pending');
+    const readyMermaid = container.querySelectorAll('.mermaid-container.mermaid-ready');
+
+    if (pendingMermaid.length > 0 || readyMermaid.length > 0) {
+      try {
+        const { mermaidRenderer } = await import('../../../src/renderers/mermaid-renderer');
+
+        // Re-render any pending diagrams that were cached before rendering completed
+        if (pendingMermaid.length > 0) {
+          debug.info(
+            'RenderPipeline',
+            `Re-rendering ${pendingMermaid.length} pending mermaid diagram(s) from stale cache`
+          );
+          await mermaidRenderer.renderAll(container);
+        }
+      } catch (error) {
+        debug.error('RenderPipeline', 'Failed to reinitialize mermaid:', error);
+      }
+    }
+  }
+
+  /**
+   * Enhance content with parallel worker processing
+   * Optimized: Critical operations first, non-critical during idle time
+   */
+  private async enhanceContentWithWorkers(
+    container: HTMLElement,
+    _result: ConversionResult,
+    useWorkers: boolean
+  ): Promise<void> {
+    // CRITICAL: Apply syntax highlighting to visible blocks first (lazy loaded)
+    if (useWorkers) {
+      debug.debug('RenderPipeline', 'Applying syntax highlighting with workers...');
+      await this.applySyntaxHighlightingWithWorkers(container);
+    } else {
+      debug.debug('RenderPipeline', 'Applying syntax highlighting...');
+      await this.applySyntaxHighlighting(container);
+    }
+
+    // CRITICAL: Mark and render Mermaid blocks (awaited so cache captures rendered state)
+    debug.debug('RenderPipeline', 'Rendering Mermaid blocks...');
+    await this.markAndRenderMermaidBlocks(container);
+
+    debug.debug('RenderPipeline', 'Enhancement complete');
+
+    // NON-CRITICAL: Schedule remaining enhancements during idle time
+    // This improves perceived performance by not blocking the main render
+    this.scheduleIdleEnhancements(container);
+  }
+
+  /**
+   * Schedule non-critical enhancements during browser idle time
+   */
+  private scheduleIdleEnhancements(container: HTMLElement): void {
+    const runEnhancements = () => {
+      debug.debug('RenderPipeline', 'Running idle-time enhancements...');
+
+      // Batch DOM operations for efficiency
+      this.addCopyButtons(container);
+      this.setupImageLazyLoading(container);
+      this.setupHeadingAnchors(container);
+
+      debug.debug('RenderPipeline', 'Idle-time enhancements complete');
+    };
+
+    // Use requestIdleCallback if available, otherwise setTimeout
+    if (typeof requestIdleCallback !== 'undefined') {
+      requestIdleCallback(runEnhancements, { timeout: 100 });
+    } else {
+      setTimeout(runEnhancements, 0);
+    }
+  }
+
+  /**
+   * Apply syntax highlighting using workers (parallel)
+   * Optimized: Uses lazy loading for better perceived performance
+   */
+  private async applySyntaxHighlightingWithWorkers(container: HTMLElement): Promise<void> {
+    // Even with workers available, use lazy loading for instant content display
+    // Only visible code blocks are highlighted immediately, rest on scroll
+    try {
+      const { syntaxHighlighter } = await import('../../../src/renderers/syntax-highlighter');
+      syntaxHighlighter.highlightVisible(container);
+    } catch (error) {
+      debug.error('RenderPipeline', 'Syntax highlighting error:', error);
+    }
+  }
+
+  /**
+   * Throttle progress updates to reduce reflows
+   */
+  private notifyProgressThrottled(progress: RenderProgress): void {
+    const now = Date.now();
+    const timeSinceLastUpdate = now - this.lastProgressUpdate;
+
+    // Throttle to max once per 100ms (except for complete/cached stages)
+    if (timeSinceLastUpdate < 100 && progress.stage !== 'complete' && progress.stage !== 'cached') {
+      // Schedule update for later if not already scheduled
+      if (!this.progressUpdateTimer) {
+        this.progressUpdateTimer = setTimeout(() => {
+          this.notifyProgress(progress);
+          this.progressUpdateTimer = null;
+          this.lastProgressUpdate = Date.now();
+        }, 100 - timeSinceLastUpdate);
+      }
+      return;
+    }
+
+    this.notifyProgress(progress);
+    this.lastProgressUpdate = now;
+  }
+
+  /**
+   * Get cache key via messaging adapter
+   */
+  private async getCacheKey(
+    filePath: string,
+    content: string,
+    theme: ThemeName,
+    preferences: Record<string, unknown>
+  ): Promise<string> {
+    if (!this.messaging) {
+      return '';
+    }
+    const response: unknown = await this.messaging.send({
+      type: 'CACHE_GENERATE_KEY',
+      payload: { filePath, content, theme, preferences },
+    });
+    return (response as { key: string }).key;
+  }
+
+  /**
+   * Get cached result via messaging adapter
+   */
+  private async getCachedResult(key: string): Promise<CachedResult | null> {
+    if (!this.messaging) {
+      return null;
+    }
+    const response: unknown = await this.messaging.send({
+      type: 'CACHE_GET',
+      payload: { key },
+    });
+    return (response as { result: CachedResult | null }).result || null;
+  }
+
+  /**
+   * Set cached result via messaging adapter
+   */
+  private async setCachedResult(
+    key: string,
+    result: CachedResult,
+    filePath: string,
+    contentHash: string,
+    theme: ThemeName
+  ): Promise<void> {
+    if (!this.messaging) {
+      return;
+    }
+    await this.messaging.send({
+      type: 'CACHE_SET',
+      payload: { key, result, filePath, contentHash, theme },
+    });
+  }
+
+  /**
+   * Generate content hash
+   */
+  private async generateContentHash(content: string): Promise<string> {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(content);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+    return hashHex;
+  }
+
+  /**
+   * Progressive rendering for large files
+   */
+  async renderIncremental(options: RenderOptions): Promise<void> {
+    const { container, markdown, chunkSize = 50000 } = options;
+
+    // Split markdown into chunks
+    const chunks = this.chunkMarkdown(markdown, chunkSize);
+
+    for (let i = 0; i < chunks.length; i++) {
+      if (this.cancelRequested) break;
+
+      const chunk = chunks[i];
+      const progress = ((i + 1) / chunks.length) * 100;
+
+      this.notifyProgress({
+        stage: 'parsing',
+        progress,
+        message: `Rendering chunk ${i + 1} of ${chunks.length}...`,
+      });
+
+      // Render chunk
+      const chunkContainer = document.createElement('div');
+      chunkContainer.className = 'mdview-chunk';
+
+      await this.render({
+        container: chunkContainer,
+        markdown: chunk,
+        progressive: false,
+      });
+
+      container.appendChild(chunkContainer);
+
+      // Yield to browser for responsiveness using RAF (faster than setTimeout)
+      await new Promise((resolve) => requestAnimationFrame(resolve));
+    }
+  }
+
+  /**
+   * Render using progressive hydration (for large files)
+   * PHASE 1: Instant skeleton (< 50ms) - structure with headings
+   * PHASE 2: Progressive hydration - fill in content
+   * PHASE 3: Enhancement - syntax highlighting, mermaid, etc.
+   */
+  private async renderWithProgressiveHydration(options: RenderOptions): Promise<void> {
+    const { container, markdown, preferences = {} } = options;
+    debug.debug(
+      'RenderPipeline',
+      'Starting progressive hydration with preferences:',
+      JSON.stringify(preferences)
+    );
+
+    // Update markdown converter options based on preferences
+    this.converter.updateOptions({
+      enableHtml: !!(preferences as { enableHtml?: boolean }).enableHtml,
+    });
+
+    // Preprocess: Extract frontmatter before any other processing
+    let processedMarkdown = markdown;
+    const frontmatterResult = extractFrontmatter(processedMarkdown);
+    const frontmatterData = frontmatterResult.frontmatter;
+    processedMarkdown = frontmatterResult.cleanedMarkdown;
+
+    // Preprocess: Strip existing TOC if custom TOC is enabled
+    if ((preferences as { showToc?: boolean }).showToc) {
+      const { stripTableOfContents } = await import('../../../src/utils/toc-stripper');
+      const stripResult = stripTableOfContents(processedMarkdown);
+      processedMarkdown = stripResult.markdown;
+      if (stripResult.tocFound) {
+        debug.info('RenderPipeline', 'Stripped original TOC from markdown (progressive hydration)');
+      }
+    }
+
+    // Preprocess: Strip comment footnotes before parsing
+    this.lastCommentParseResult = null;
+    if ((preferences as { commentsEnabled?: boolean }).commentsEnabled !== false) {
+      const { parseComments } = await import('../../../src/comments/annotation-parser');
+      this.lastCommentParseResult = parseComments(processedMarkdown);
+      processedMarkdown = this.lastCommentParseResult.cleanedMarkdown;
+      if (this.lastCommentParseResult.comments.length > 0) {
+        debug.info(
+          'RenderPipeline',
+          `Stripped ${this.lastCommentParseResult.comments.length} comment footnotes (progressive hydration)`
+        );
+      }
+    }
+
+    // Split markdown into sections
+    const sections = splitIntoSections(processedMarkdown);
+    debug.info('RenderPipeline', `Progressive hydration: ${sections.length} sections`);
+
+    // ===================================================================
+    // PHASE 1: Instant Skeleton (< 50ms)
+    // Render all headings + placeholders immediately
+    // This makes scroll position naturally correct!
+    // ===================================================================
+    this.notifyProgressThrottled({
+      stage: 'parsing',
+      progress: 5,
+      message: 'Rendering structure...',
+    });
+
+    const frontmatterHtml = frontmatterData ? renderFrontmatterHtml(frontmatterData) : '';
+    const skeletonHtml = SkeletonRenderer.generateSkeleton(sections);
+    container.innerHTML = frontmatterHtml + skeletonHtml;
+
+    debug.debug('RenderPipeline', 'Skeleton rendered (structure visible)');
+
+    // At this point, the user sees the full document structure!
+    // Headings are visible, scroll works naturally
+    // No need for scroll restoration!
+
+    // Notify that content is visible (remove loading overlay)
+    this.notifyProgressThrottled({
+      stage: 'parsing',
+      progress: 10,
+      message: 'Content visible - hydrating...',
+    });
+
+    // Apply theme immediately to skeleton
+    this.applyTheming(container);
+
+    // ===================================================================
+    // PHASE 2: Progressive Hydration
+    // Fill in actual content for each section
+    // ===================================================================
+    debug.debug('RenderPipeline', 'Starting progressive hydration...');
+
+    for (let i = 0; i < sections.length; i++) {
+      const section = sections[i];
+
+      this.notifyProgressThrottled({
+        stage: 'parsing',
+        progress: 5 + (i / sections.length) * 70,
+        message: `Hydrating section ${i + 1}/${sections.length}...`,
+      });
+
+      try {
+        // Find the skeleton section element
+        const sectionElement = document.getElementById(section.id);
+        if (!sectionElement || SkeletonRenderer.isHydrated(sectionElement)) {
+          continue;
+        }
+
+        // Convert markdown to HTML
+        const result = this.converter.convert(section.markdown);
+        const sanitized = this.sanitizeContent(result);
+        debug.debug(
+          'RenderPipeline',
+          `Hydrating section ${i}: Transforming content with preferences`,
+          JSON.stringify(preferences)
+        );
+        const transformed = this.transformContent(sanitized, result, preferences);
+
+        // Replace skeleton content with actual content
+        sectionElement.innerHTML = transformed;
+
+        // Mark as hydrated
+        SkeletonRenderer.markHydrated(sectionElement);
+
+        // Yield to browser to keep UI responsive
+        await new Promise((r) => requestAnimationFrame(r));
+      } catch (error) {
+        debug.error('RenderPipeline', `Failed to hydrate section ${section.id}:`, error);
+      }
+    }
+
+    debug.info('RenderPipeline', 'Progressive hydration complete');
+
+    // ===================================================================
+    // PHASE 3: Enhancement
+    // Add syntax highlighting, mermaid, copy buttons, etc.
+    // ===================================================================
+    this.notifyProgressThrottled({
+      stage: 'enhancing',
+      progress: 80,
+      message: 'Enhancing content...',
+    });
+
+    await this.enhanceContentWithWorkers(
+      container,
+      { html: '', metadata: {} } as ConversionResult,
+      false
+    );
+
+    this.notifyProgressThrottled({
+      stage: 'complete',
+      progress: 100,
+      message: 'Rendering complete',
+    });
+
+    debug.info('RenderPipeline', 'Progressive hydration fully complete');
+  }
+
+  /**
+   * Get the comment parse result from the last render
+   */
+  getLastCommentParseResult(): CommentParseResult | null {
+    return this.lastCommentParseResult;
+  }
+
+  /**
+   * Cancel rendering
+   */
+  cancelRender(): void {
+    this.cancelRequested = true;
+  }
+
+  /**
+   * Subscribe to progress updates
+   */
+  onProgress(callback: ProgressCallback): () => void {
+    this.progressCallbacks.add(callback);
+    return () => {
+      this.progressCallbacks.delete(callback);
+    };
+  }
+
+  /**
+   * Stage 2: Sanitize content
+   */
+  private sanitizeContent(result: ConversionResult): string {
+    // Use DOMPurify to sanitize
+    return domPurifier.sanitize(result.html);
+  }
+
+  /**
+   * Stage 3: Transform content (process special blocks)
+   */
+  private transformContent(
+    html: string,
+    result: ConversionResult,
+    preferences: Record<string, unknown> = {},
+    frontmatter: Record<string, string> | null = null
+  ): string {
+    debug.debug(
+      'RenderPipeline',
+      'Transforming content with preferences:',
+      JSON.stringify(preferences)
+    );
+    let transformed = html;
+
+    // Prepend frontmatter card if present
+    if (frontmatter) {
+      transformed = renderFrontmatterHtml(frontmatter) + transformed;
+    }
+
+    // Add language badges and line numbers to code blocks
+    transformed = this.addCodeBlockFeatures(transformed, result, preferences);
+
+    // Add lazy loading to images
+    transformed = this.addImageLazyLoading(transformed);
+
+    // Add table enhancements
+    transformed = this.enhanceTables(transformed);
+
+    return transformed;
+  }
+
+  /**
+   * Apply syntax highlighting to code blocks
+   */
+  private async applySyntaxHighlighting(container: HTMLElement): Promise<void> {
+    try {
+      const { syntaxHighlighter } = await import('../../../src/renderers/syntax-highlighter');
+      syntaxHighlighter.highlightVisible(container);
+    } catch (error) {
+      debug.error('RenderPipeline', 'Syntax highlighting error:', error);
+    }
+  }
+
+  /**
+   * Stage 6: Apply theming
+   */
+  private applyTheming(container: HTMLElement): void {
+    // Theme will be applied by theme engine
+    // This is a placeholder for theme-specific transformations
+    container.classList.add('mdview-rendered');
+  }
+
+  /**
+   * Add features to code blocks
+   */
+  private addCodeBlockFeatures(
+    html: string,
+    _result: ConversionResult,
+    preferences: Record<string, unknown> = {}
+  ): string {
+    const showLineNumbers = !!preferences.lineNumbers;
+    debug.debug('RenderPipeline', `addCodeBlockFeatures: showLineNumbers = ${showLineNumbers}`);
+
+    return html.replace(
+      /<pre><code class="language-(\w+)">([\s\S]*?)<\/code><\/pre>/g,
+      (_match, lang: string, code: string) => {
+        let lineNumbersHtml = '';
+        let wrapperClass = 'code-block-wrapper';
+        let contentStart = '';
+        let contentEnd = '';
+
+        if (showLineNumbers) {
+          debug.debug('RenderPipeline', 'Generating line numbers for code block');
+          wrapperClass += ' has-line-numbers';
+          // Count lines
+          const lines = code.split('\n');
+          const lineCount = lines.length;
+          // Generate line numbers column
+          const numbers = Array.from({ length: lineCount }, (_, i) => `<span>${i + 1}</span>`).join(
+            ''
+          );
+          lineNumbersHtml = `<div class="line-numbers-rows">${numbers}</div>`;
+          contentStart = '<div class="code-block-content">';
+          contentEnd = '</div>';
+        }
+
+        return `<div class="${wrapperClass}" data-language="${lang}">
+          <div class="code-block-header">
+            <span class="code-language-badge">${lang}</span>
+          </div>
+          ${contentStart}
+            ${lineNumbersHtml}
+            <pre><code class="language-${lang}">${code}</code></pre>
+          ${contentEnd}
+        </div>`;
+      }
+    );
+  }
+
+  /**
+   * Add lazy loading to images
+   */
+  private addImageLazyLoading(html: string): string {
+    return html.replace(/<img /g, '<img loading="lazy" ');
+  }
+
+  /**
+   * Enhance tables
+   */
+  private enhanceTables(html: string): string {
+    return html
+      .replace(/<table>/g, '<div class="table-wrapper"><table>')
+      .replace(/<\/table>/g, '</table></div>');
+  }
+
+  /**
+   * Add copy buttons to code blocks
+   */
+  private addCopyButtons(container: HTMLElement): void {
+    const codeBlocks = container.querySelectorAll('.code-block-wrapper');
+
+    codeBlocks.forEach((wrapper) => {
+      const copyButton = document.createElement('button');
+      copyButton.className = 'code-copy-button';
+      copyButton.textContent = 'Copy';
+      copyButton.setAttribute('aria-label', 'Copy code to clipboard');
+
+      copyButton.addEventListener('click', () => {
+        const code = wrapper.querySelector('code');
+        if (code) {
+          void (async () => {
+            try {
+              await navigator.clipboard.writeText(code.textContent || '');
+              copyButton.textContent = 'Copied';
+              setTimeout(() => {
+                copyButton.textContent = 'Copy';
+              }, 2000);
+            } catch (error) {
+              debug.error('RenderPipeline', 'Failed to copy:', error);
+              copyButton.textContent = 'Failed';
+              setTimeout(() => {
+                copyButton.textContent = 'Copy';
+              }, 2000);
+            }
+          })();
+        }
+      });
+
+      const header = wrapper.querySelector('.code-block-header');
+      if (header) {
+        header.appendChild(copyButton);
+      }
+    });
+  }
+
+  /**
+   * Set up lazy loading for images
+   */
+  private setupImageLazyLoading(container: HTMLElement): void {
+    const images = container.querySelectorAll('img[loading="lazy"]');
+
+    if ('IntersectionObserver' in window) {
+      const imageObserver = new IntersectionObserver(
+        (entries) => {
+          entries.forEach((entry) => {
+            if (entry.isIntersecting) {
+              const img = entry.target as HTMLImageElement;
+              img.classList.add('loaded');
+              imageObserver.unobserve(img);
+            }
+          });
+        },
+        { rootMargin: '50px' }
+      );
+
+      images.forEach((img) => imageObserver.observe(img));
+    }
+  }
+
+  /**
+   * Mark Mermaid blocks for rendering and await completion
+   */
+  private async markAndRenderMermaidBlocks(container: HTMLElement): Promise<void> {
+    const mermaidBlocks = container.querySelectorAll('.mermaid-container');
+    mermaidBlocks.forEach((block) => {
+      block.classList.add('mermaid-pending');
+    });
+
+    // Await mermaid rendering so cache captures the rendered state
+    if (mermaidBlocks.length > 0) {
+      await this.renderMermaidDiagrams(container);
+    }
+  }
+
+  /**
+   * Render Mermaid diagrams
+   */
+  private async renderMermaidDiagrams(container: HTMLElement): Promise<void> {
+    try {
+      const { mermaidRenderer } = await import('../../../src/renderers/mermaid-renderer');
+      await mermaidRenderer.renderAll(container);
+    } catch (error) {
+      debug.error('RenderPipeline', 'Mermaid rendering error:', error);
+    }
+  }
+
+  /**
+   * Setup heading anchors
+   */
+  private setupHeadingAnchors(container: HTMLElement): void {
+    const headings = container.querySelectorAll('h1, h2, h3, h4, h5, h6');
+
+    headings.forEach((heading) => {
+      if (heading.id) {
+        heading.classList.add('heading-with-anchor');
+      }
+    });
+  }
+
+  /**
+   * Chunk markdown for progressive rendering
+   */
+  private chunkMarkdown(markdown: string, chunkSize: number): string[] {
+    const chunks: string[] = [];
+    const lines = markdown.split('\n');
+    let currentChunk: string[] = [];
+    let currentSize = 0;
+
+    for (const line of lines) {
+      currentChunk.push(line);
+      currentSize += line.length;
+
+      // Check if we should create a new chunk
+      // Only break at block boundaries (empty lines)
+      if (currentSize >= chunkSize && line.trim() === '') {
+        chunks.push(currentChunk.join('\n'));
+        currentChunk = [];
+        currentSize = 0;
+      }
+    }
+
+    // Add remaining content
+    if (currentChunk.length > 0) {
+      chunks.push(currentChunk.join('\n'));
+    }
+
+    return chunks.length > 0 ? chunks : [markdown];
+  }
+
+  /**
+   * Notify progress callbacks
+   */
+  private notifyProgress(progress: RenderProgress): void {
+    this.progressCallbacks.forEach((callback) => {
+      try {
+        callback(progress);
+      } catch (error) {
+        debug.error('RenderPipeline', 'Progress callback error:', error);
+      }
+    });
+  }
+
+  /**
+   * Show error in container
+   */
+  private showError(container: HTMLElement, error: unknown): void {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    container.innerHTML = `
+      <div class="mdview-error" role="alert">
+        <h2>Rendering Error</h2>
+        <p>Failed to render markdown content.</p>
+        <details>
+          <summary>Technical Details</summary>
+          <pre>${this.escapeHtml(errorMessage)}</pre>
+        </details>
+      </div>
+    `;
+  }
+
+  /**
+   * Escape HTML
+   */
+  private escapeHtml(text: string): string {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+}
diff --git a/src/core/render-pipeline.ts b/src/core/render-pipeline.ts
index 3635a26..1c79ad5 100644
--- a/src/core/render-pipeline.ts
+++ b/src/core/render-pipeline.ts
@@ -1,1036 +1,52 @@
 /**
- * Render Pipeline
- * Multi-stage pipeline for rendering markdown with progressive enhancement
+ * Render Pipeline (Chrome Extension Shim)
+ *
+ * Re-exports the platform-agnostic RenderPipeline from @mdview/core,
+ * pre-configured with a Chrome MessagingAdapter that delegates
+ * to chrome.runtime.sendMessage.
  */
 
-import { MarkdownConverter } from './markdown-converter';
-import { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extractor';
-import { domPurifier } from '../utils/dom-purifier';
-import { workerPool } from '../workers/worker-pool';
-import type {
-  ConversionResult,
-  ThemeName,
-  CachedResult,
-  ParseTaskPayload,
-  CommentParseResult,
-} from '../types';
-import { debug } from '../utils/debug-logger';
-import { splitIntoSections } from '../utils/section-splitter';
-import { SkeletonRenderer } from '../utils/skeleton-renderer';
+import {
+  RenderPipeline as CoreRenderPipeline,
+  type RenderOptions,
+  type RenderProgress,
+  type ProgressCallback,
+  type RenderPipelineOptions,
+} from '../../packages/core/src/render-pipeline';
+import type { MessagingAdapter, IPCMessage } from '../../packages/core/src/adapters';
 
-export interface RenderOptions {
-  container: HTMLElement;
-  markdown: string;
-  theme?: string;
-  progressive?: boolean;
-  chunkSize?: number;
-  filePath?: string;
-  preferences?: Record<string, unknown>;
-  useCache?: boolean;
-  useWorkers?: boolean;
-  useLazySections?: boolean; // New: Enable lazy section rendering
-}
-
-export interface RenderProgress {
-  stage:
-    | 'parsing'
-    | 'sanitizing'
-    | 'transforming'
-    | 'enhancing'
-    | 'theming'
-    | 'complete'
-    | 'cached';
-  progress: number; // 0-100
-  message: string;
-}
-
-export type ProgressCallback = (progress: RenderProgress) => void;
-
-export class RenderPipeline {
-  private converter: MarkdownConverter;
-  private progressCallbacks: Set<ProgressCallback> = new Set();
-  private cancelRequested = false;
-  private workersEnabled = true;
-  private progressUpdateTimer: number | null = null;
-  private lastProgressUpdate = 0;
-  private lastCommentParseResult: CommentParseResult | null = null;
-
-  constructor() {
-    this.converter = new MarkdownConverter();
-    // Initialize workers in background
-    void this.initializeWorkers();
-  }
-
-  /**
-   * Initialize worker pool
-   * Note: Workers are disabled on file:// URLs due to Chrome security
-   * The synchronous rendering path is optimized with Phase 1 improvements
-   */
-  private async initializeWorkers(): Promise<void> {
-    try {
-      await workerPool.initialize();
-      this.workersEnabled = true;
-      debug.info('RenderPipeline', '✅ Worker pool initialized');
-    } catch (error) {
-      // Workers unavailable - WorkerPool already logged the reason
-      // Silently fall back to synchronous rendering
-      this.workersEnabled = false;
-
-      // Only log errors for unexpected failures (non-file:// protocols)
-      if (window.location.protocol !== 'file:') {
-        debug.error('RenderPipeline', 'Worker initialization failed, using sync fallback:', error);
-      }
-    }
-  }
-
-  /**
-   * Main render function with cache and worker support
-   */
-  async render(options: RenderOptions): Promise<void> {
-    this.cancelRequested = false;
-    const {
-      container,
-      markdown,
-      theme = 'github-light',
-      filePath = '',
-      preferences = {},
-      useCache = true,
-      useWorkers = true,
-      useLazySections = false, // Lazy sections disabled by default
-    } = options;
-
-    // Update markdown converter options based on preferences
-    this.converter.updateOptions({
-      enableHtml: !!(preferences as { enableHtml?: boolean }).enableHtml,
-    });
-
-    const shouldUseWorkers = useWorkers && this.workersEnabled;
-
-    try {
-      // Check cache if enabled (from service worker)
-      if (useCache && filePath) {
-        const cacheKey = await this.getCacheKey(
-          filePath,
-          markdown,
-          theme as ThemeName,
-          preferences
-        );
-
-        const cached = await this.getCachedResult(cacheKey);
-        if (cached) {
-          debug.info('RenderPipeline', 'Using cached result from service worker');
-          this.notifyProgressThrottled({
-            stage: 'cached',
-            progress: 100,
-            message: 'Loading from cache...',
-          });
-
-          await this.renderFromCache(container, cached);
-          return;
-        }
-      }
-
-      // Use progressive hydration for large files (> 30KB)
-      if (useLazySections || markdown.length > 30000) {
-        debug.info('RenderPipeline', 'Using progressive hydration for large document');
-        await this.renderWithProgressiveHydration(options);
-        return;
-      }
-
-      // Preprocess: Extract frontmatter before any other processing
-      let processedMarkdown = markdown;
-      const frontmatterResult = extractFrontmatter(processedMarkdown);
-      const frontmatterData = frontmatterResult.frontmatter;
-      processedMarkdown = frontmatterResult.cleanedMarkdown;
-
-      // Preprocess: Strip existing TOC if custom TOC is enabled
-      if ((preferences as { showToc?: boolean }).showToc) {
-        const { stripTableOfContents } = await import('../utils/toc-stripper');
-        const stripResult = stripTableOfContents(processedMarkdown);
-        processedMarkdown = stripResult.markdown;
-        if (stripResult.tocFound) {
-          debug.info('RenderPipeline', 'Stripped original TOC from markdown');
-        }
-      }
-
-      // Preprocess: Strip comment footnotes before parsing
-      this.lastCommentParseResult = null;
-      if ((preferences as { commentsEnabled?: boolean }).commentsEnabled !== false) {
-        const { parseComments } = await import('../comments/annotation-parser');
-        this.lastCommentParseResult = parseComments(processedMarkdown);
-        processedMarkdown = this.lastCommentParseResult.cleanedMarkdown;
-        if (this.lastCommentParseResult.comments.length > 0) {
-          debug.info(
-            'RenderPipeline',
-            `Stripped ${this.lastCommentParseResult.comments.length} comment footnotes from markdown`
-          );
-        }
-      }
-
-      // Stage 1: Parse markdown to HTML (with worker if available)
-      this.notifyProgressThrottled({
-        stage: 'parsing',
-        progress: 10,
-        message: 'Parsing markdown...',
-      });
-
-      let result: ConversionResult;
-
-      if (shouldUseWorkers) {
-        try {
-          const taskId = `parse-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-          const payload: ParseTaskPayload = {
-            markdown: processedMarkdown,
-            options: {
-              breaks: true,
-              linkify: true,
-              typographer: true,
-              enableHtml: !!(preferences as { enableHtml?: boolean }).enableHtml,
-            },
-          };
-
-          const workerResult = await workerPool.execute<{
-            html: string;
-            metadata: ConversionResult['metadata'];
-          }>({
-            type: 'parse',
-            id: taskId,
-            payload,
-            priority: 10,
-          });
-
-          result = {
-            html: workerResult.html,
-            metadata: workerResult.metadata,
-            errors: [],
-          };
-
-          debug.debug('RenderPipeline', 'Parsed markdown in worker');
-        } catch (error) {
-          debug.error('RenderPipeline', 'Worker parsing failed, falling back to sync:', error);
-          result = this.converter.convert(processedMarkdown);
-        }
-      } else {
-        result = this.converter.convert(processedMarkdown);
-      }
-
-      if (this.cancelRequested) return;
-
-      // Stage 2: Sanitize HTML (always on main thread for security)
-      this.notifyProgressThrottled({
-        stage: 'sanitizing',
-        progress: 30,
-        message: 'Sanitizing content...',
-      });
-
-      const sanitized = this.sanitizeContent(result);
-
-      if (this.cancelRequested) return;
-
-      // Stage 3: Transform (process special blocks)
-      this.notifyProgressThrottled({
-        stage: 'transforming',
-        progress: 50,
-        message: 'Processing content...',
-      });
-
-      const transformed = this.transformContent(sanitized, result, preferences, frontmatterData);
-
-      // Store frontmatter in metadata
-      result.metadata.frontmatter = frontmatterData;
-
-      if (this.cancelRequested) return;
-
-      // Stage 4: Insert into DOM
-      const template = document.createElement('template');
-      template.innerHTML = transformed;
-
-      container.innerHTML = '';
-      container.appendChild(template.content);
-
-      // Stage 5: Enhance (add interactive features with parallel workers)
-      this.notifyProgressThrottled({
-        stage: 'enhancing',
-        progress: 70,
-        message: 'Adding interactive features...',
-      });
-
-      debug.debug('RenderPipeline', 'Enhancing content...');
-      await this.enhanceContentWithWorkers(container, result, shouldUseWorkers);
-      debug.debug('RenderPipeline', 'Content enhanced');
-
-      if (this.cancelRequested) return;
-
-      // Stage 6: Apply theme
-      this.notifyProgressThrottled({
-        stage: 'theming',
-        progress: 90,
-        message: 'Applying theme...',
-      });
-
-      debug.info('RenderPipeline', 'Applying theme...');
-      this.applyTheming(container);
-      debug.info('RenderPipeline', 'Theme applied successfully');
-
-      // Cache the result if enabled (to service worker)
-      if (useCache && filePath) {
-        try {
-          const cacheKey = await this.getCacheKey(
-            filePath,
-            markdown,
-            theme as ThemeName,
-            preferences
-          );
-
-          const contentHash = await this.generateContentHash(markdown);
-
-          const cachedResult: CachedResult = {
-            html: container.innerHTML,
-            metadata: result.metadata,
-            highlightedBlocks: new Map(),
-            mermaidSVGs: new Map(),
-            timestamp: Date.now(),
-            cacheKey,
-          };
-
-          await this.setCachedResult(
-            cacheKey,
-            cachedResult,
-            filePath,
-            contentHash,
-            theme as ThemeName
-          );
-          debug.debug('RenderPipeline', 'Result cached in service worker');
-        } catch (error) {
-          debug.error('RenderPipeline', 'Failed to cache result:', error);
-        }
-      }
-
-      // Complete
-      this.notifyProgressThrottled({
-        stage: 'complete',
-        progress: 100,
-        message: 'Rendering complete',
-      });
-      debug.info('RenderPipeline', 'Rendering complete');
-    } catch (error) {
-      debug.error('RenderPipeline', 'Render error:', error);
-      this.showError(container, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Render from cached result
-   */
-  private async renderFromCache(container: HTMLElement, cached: CachedResult): Promise<void> {
-    // Insert cached HTML
-    container.innerHTML = cached.html;
-
-    // Re-initialize interactive features
-    await this.reinitializeInteractiveFeatures(container);
-
-    this.notifyProgressThrottled({
-      stage: 'complete',
-      progress: 100,
-      message: 'Loaded from cache',
-    });
-  }
-
-  /**
-   * Re-initialize interactive features for cached content
-   */
-  private async reinitializeInteractiveFeatures(container: HTMLElement): Promise<void> {
-    // Re-add copy buttons
-    this.addCopyButtons(container);
-
-    // Re-setup image lazy loading
-    this.setupImageLazyLoading(container);
-
-    // Re-initialize Mermaid diagrams
-    const pendingMermaid = container.querySelectorAll('.mermaid-container.mermaid-pending');
-    const readyMermaid = container.querySelectorAll('.mermaid-container.mermaid-ready');
-
-    if (pendingMermaid.length > 0 || readyMermaid.length > 0) {
-      try {
-        const { mermaidRenderer } = await import('../renderers/mermaid-renderer');
-
-        // Re-render any pending diagrams that were cached before rendering completed
-        if (pendingMermaid.length > 0) {
-          debug.info(
-            'RenderPipeline',
-            `Re-rendering ${pendingMermaid.length} pending mermaid diagram(s) from stale cache`
-          );
-          await mermaidRenderer.renderAll(container);
-        }
-      } catch (error) {
-        debug.error('RenderPipeline', 'Failed to reinitialize mermaid:', error);
-      }
-    }
-  }
-
-  /**
-   * Enhance content with parallel worker processing
-   * Optimized: Critical operations first, non-critical during idle time
-   */
-  private async enhanceContentWithWorkers(
-    container: HTMLElement,
-    _result: ConversionResult,
-    useWorkers: boolean
-  ): Promise<void> {
-    // CRITICAL: Apply syntax highlighting to visible blocks first (lazy loaded)
-    if (useWorkers) {
-      debug.debug('RenderPipeline', 'Applying syntax highlighting with workers...');
-      await this.applySyntaxHighlightingWithWorkers(container);
-    } else {
-      debug.debug('RenderPipeline', 'Applying syntax highlighting...');
-      await this.applySyntaxHighlighting(container);
-    }
-
-    // CRITICAL: Mark and render Mermaid blocks (awaited so cache captures rendered state)
-    debug.debug('RenderPipeline', 'Rendering Mermaid blocks...');
-    await this.markAndRenderMermaidBlocks(container);
-
-    debug.debug('RenderPipeline', 'Enhancement complete');
-
-    // NON-CRITICAL: Schedule remaining enhancements during idle time
-    // This improves perceived performance by not blocking the main render
-    this.scheduleIdleEnhancements(container);
-  }
-
-  /**
-   * Schedule non-critical enhancements during browser idle time
-   */
-  private scheduleIdleEnhancements(container: HTMLElement): void {
-    const runEnhancements = () => {
-      debug.debug('RenderPipeline', 'Running idle-time enhancements...');
-
-      // Batch DOM operations for efficiency
-      this.addCopyButtons(container);
-      this.setupImageLazyLoading(container);
-      this.setupHeadingAnchors(container);
-
-      debug.debug('RenderPipeline', 'Idle-time enhancements complete');
-    };
-
-    // Use requestIdleCallback if available, otherwise setTimeout
-    if ('requestIdleCallback' in window) {
-      requestIdleCallback(runEnhancements, { timeout: 100 });
-    } else {
-      setTimeout(runEnhancements, 0);
-    }
-  }
-
-  /**
-   * Apply syntax highlighting using workers (parallel)
-   * Optimized: Uses lazy loading for better perceived performance
-   */
-  private async applySyntaxHighlightingWithWorkers(container: HTMLElement): Promise<void> {
-    // Even with workers available, use lazy loading for instant content display
-    // Only visible code blocks are highlighted immediately, rest on scroll
-    try {
-      const { syntaxHighlighter } = await import('../renderers/syntax-highlighter');
-      syntaxHighlighter.highlightVisible(container);
-    } catch (error) {
-      debug.error('RenderPipeline', 'Syntax highlighting error:', error);
-    }
-  }
-
-  /**
-   * Throttle progress updates to reduce reflows
-   */
-  private notifyProgressThrottled(progress: RenderProgress): void {
-    const now = Date.now();
-    const timeSinceLastUpdate = now - this.lastProgressUpdate;
-
-    // Throttle to max once per 100ms (except for complete/cached stages)
-    if (timeSinceLastUpdate < 100 && progress.stage !== 'complete' && progress.stage !== 'cached') {
-      // Schedule update for later if not already scheduled
-      if (!this.progressUpdateTimer) {
-        this.progressUpdateTimer = window.setTimeout(() => {
-          this.notifyProgress(progress);
-          this.progressUpdateTimer = null;
-          this.lastProgressUpdate = Date.now();
-        }, 100 - timeSinceLastUpdate);
-      }
-      return;
-    }
-
-    this.notifyProgress(progress);
-    this.lastProgressUpdate = now;
-  }
-
-  /**
-   * Get cache key from service worker
-   */
-  private async getCacheKey(
-    filePath: string,
-    content: string,
-    theme: ThemeName,
-    preferences: Record<string, unknown>
-  ): Promise<string> {
-    const response: unknown = await chrome.runtime.sendMessage({
-      type: 'CACHE_GENERATE_KEY',
-      payload: { filePath, content, theme, preferences },
-    });
-    return (response as { key: string }).key;
-  }
-
-  /**
-   * Get cached result from service worker
-   */
-  private async getCachedResult(key: string): Promise<CachedResult | null> {
-    const response: unknown = await chrome.runtime.sendMessage({
-      type: 'CACHE_GET',
-      payload: { key },
-    });
-    return (response as { result: CachedResult | null }).result || null;
-  }
-
-  /**
-   * Set cached result in service worker
-   */
-  private async setCachedResult(
-    key: string,
-    result: CachedResult,
-    filePath: string,
-    contentHash: string,
-    theme: ThemeName
-  ): Promise<void> {
-    await chrome.runtime.sendMessage({
-      type: 'CACHE_SET',
-      payload: { key, result, filePath, contentHash, theme },
-    });
-  }
-
-  /**
-   * Generate content hash via service worker
-   */
-  private async generateContentHash(content: string): Promise<string> {
-    const encoder = new TextEncoder();
-    const data = encoder.encode(content);
-    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-    const hashArray = Array.from(new Uint8Array(hashBuffer));
-    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
-    return hashHex;
-  }
-
-  /**
-   * Progressive rendering for large files
-   */
-  async renderIncremental(options: RenderOptions): Promise<void> {
-    const { container, markdown, chunkSize = 50000 } = options;
-
-    // Split markdown into chunks
-    const chunks = this.chunkMarkdown(markdown, chunkSize);
-
-    for (let i = 0; i < chunks.length; i++) {
-      if (this.cancelRequested) break;
-
-      const chunk = chunks[i];
-      const progress = ((i + 1) / chunks.length) * 100;
-
-      this.notifyProgress({
-        stage: 'parsing',
-        progress,
-        message: `Rendering chunk ${i + 1} of ${chunks.length}...`,
-      });
-
-      // Render chunk
-      const chunkContainer = document.createElement('div');
-      chunkContainer.className = 'mdview-chunk';
-
-      await this.render({
-        container: chunkContainer,
-        markdown: chunk,
-        progressive: false,
-      });
+// ---------------------------------------------------------------------------
+// Chrome MessagingAdapter — bridges core pipeline to chrome.runtime
+// ---------------------------------------------------------------------------
 
-      container.appendChild(chunkContainer);
-
-      // Yield to browser for responsiveness using RAF (faster than setTimeout)
-      await new Promise((resolve) => requestAnimationFrame(resolve));
-    }
-  }
-
-  /**
-   * Render using progressive hydration (for large files)
-   * PHASE 1: Instant skeleton (< 50ms) - structure with headings
-   * PHASE 2: Progressive hydration - fill in content
-   * PHASE 3: Enhancement - syntax highlighting, mermaid, etc.
-   */
-  private async renderWithProgressiveHydration(options: RenderOptions): Promise<void> {
-    const { container, markdown, preferences = {} } = options;
-    debug.debug(
-      'RenderPipeline',
-      'Starting progressive hydration with preferences:',
-      JSON.stringify(preferences)
-    );
-
-    // Update markdown converter options based on preferences
-    this.converter.updateOptions({
-      enableHtml: !!(preferences as { enableHtml?: boolean }).enableHtml,
-    });
-
-    // Preprocess: Extract frontmatter before any other processing
-    let processedMarkdown = markdown;
-    const frontmatterResult = extractFrontmatter(processedMarkdown);
-    const frontmatterData = frontmatterResult.frontmatter;
-    processedMarkdown = frontmatterResult.cleanedMarkdown;
-
-    // Preprocess: Strip existing TOC if custom TOC is enabled
-    if ((preferences as { showToc?: boolean }).showToc) {
-      const { stripTableOfContents } = await import('../utils/toc-stripper');
-      const stripResult = stripTableOfContents(processedMarkdown);
-      processedMarkdown = stripResult.markdown;
-      if (stripResult.tocFound) {
-        debug.info('RenderPipeline', 'Stripped original TOC from markdown (progressive hydration)');
-      }
-    }
-
-    // Preprocess: Strip comment footnotes before parsing
-    this.lastCommentParseResult = null;
-    if ((preferences as { commentsEnabled?: boolean }).commentsEnabled !== false) {
-      const { parseComments } = await import('../comments/annotation-parser');
-      this.lastCommentParseResult = parseComments(processedMarkdown);
-      processedMarkdown = this.lastCommentParseResult.cleanedMarkdown;
-      if (this.lastCommentParseResult.comments.length > 0) {
-        debug.info(
-          'RenderPipeline',
-          `Stripped ${this.lastCommentParseResult.comments.length} comment footnotes (progressive hydration)`
-        );
-      }
-    }
-
-    // Split markdown into sections
-    const sections = splitIntoSections(processedMarkdown);
-    debug.info('RenderPipeline', `Progressive hydration: ${sections.length} sections`);
-
-    // ===================================================================
-    // PHASE 1: Instant Skeleton (< 50ms)
-    // Render all headings + placeholders immediately
-    // This makes scroll position naturally correct!
-    // ===================================================================
-    this.notifyProgressThrottled({
-      stage: 'parsing',
-      progress: 5,
-      message: 'Rendering structure...',
-    });
-
-    const frontmatterHtml = frontmatterData ? renderFrontmatterHtml(frontmatterData) : '';
-    const skeletonHtml = SkeletonRenderer.generateSkeleton(sections);
-    container.innerHTML = frontmatterHtml + skeletonHtml;
-
-    debug.debug('RenderPipeline', 'Skeleton rendered (structure visible)');
-
-    // At this point, the user sees the full document structure!
-    // Headings are visible, scroll works naturally
-    // No need for scroll restoration!
-
-    // Notify that content is visible (remove loading overlay)
-    this.notifyProgressThrottled({
-      stage: 'parsing',
-      progress: 10,
-      message: 'Content visible - hydrating...',
-    });
-
-    // Apply theme immediately to skeleton
-    this.applyTheming(container);
-
-    // ===================================================================
-    // PHASE 2: Progressive Hydration
-    // Fill in actual content for each section
-    // ===================================================================
-    debug.debug('RenderPipeline', 'Starting progressive hydration...');
-
-    for (let i = 0; i < sections.length; i++) {
-      const section = sections[i];
-
-      this.notifyProgressThrottled({
-        stage: 'parsing',
-        progress: 5 + (i / sections.length) * 70,
-        message: `Hydrating section ${i + 1}/${sections.length}...`,
-      });
-
-      try {
-        // Find the skeleton section element
-        const sectionElement = document.getElementById(section.id);
-        if (!sectionElement || SkeletonRenderer.isHydrated(sectionElement)) {
-          continue;
-        }
-
-        // Convert markdown to HTML
-        const result = this.converter.convert(section.markdown);
-        const sanitized = this.sanitizeContent(result);
-        debug.debug(
-          'RenderPipeline',
-          `Hydrating section ${i}: Transforming content with preferences`,
-          JSON.stringify(preferences)
-        );
-        const transformed = this.transformContent(sanitized, result, preferences);
-
-        // Replace skeleton content with actual content
-        sectionElement.innerHTML = transformed;
-
-        // Mark as hydrated
-        SkeletonRenderer.markHydrated(sectionElement);
-
-        // Yield to browser to keep UI responsive
-        await new Promise((r) => requestAnimationFrame(r));
-      } catch (error) {
-        debug.error('RenderPipeline', `Failed to hydrate section ${section.id}:`, error);
-      }
-    }
-
-    debug.info('RenderPipeline', 'Progressive hydration complete');
-
-    // ===================================================================
-    // PHASE 3: Enhancement
-    // Add syntax highlighting, mermaid, copy buttons, etc.
-    // ===================================================================
-    this.notifyProgressThrottled({
-      stage: 'enhancing',
-      progress: 80,
-      message: 'Enhancing content...',
-    });
-
-    await this.enhanceContentWithWorkers(
-      container,
-      { html: '', metadata: {} } as ConversionResult,
-      false
-    );
-
-    this.notifyProgressThrottled({
-      stage: 'complete',
-      progress: 100,
-      message: 'Rendering complete',
-    });
-
-    debug.info('RenderPipeline', 'Progressive hydration fully complete');
-  }
-
-  /**
-   * Get the comment parse result from the last render
-   */
-  getLastCommentParseResult(): CommentParseResult | null {
-    return this.lastCommentParseResult;
-  }
-
-  /**
-   * Cancel rendering
-   */
-  cancelRender(): void {
-    this.cancelRequested = true;
-  }
-
-  /**
-   * Subscribe to progress updates
-   */
-  onProgress(callback: ProgressCallback): () => void {
-    this.progressCallbacks.add(callback);
-    return () => {
-      this.progressCallbacks.delete(callback);
-    };
-  }
-
-  /**
-   * Stage 2: Sanitize content
-   */
-  private sanitizeContent(result: ConversionResult): string {
-    // Use DOMPurify to sanitize
-    return domPurifier.sanitize(result.html);
-  }
-
-  /**
-   * Stage 3: Transform content (process special blocks)
-   */
-  private transformContent(
-    html: string,
-    result: ConversionResult,
-    preferences: Record<string, unknown> = {},
-    frontmatter: Record<string, string> | null = null
-  ): string {
-    debug.debug(
-      'RenderPipeline',
-      'Transforming content with preferences:',
-      JSON.stringify(preferences)
-    );
-    let transformed = html;
-
-    // Prepend frontmatter card if present
-    if (frontmatter) {
-      transformed = renderFrontmatterHtml(frontmatter) + transformed;
-    }
-
-    // Add language badges and line numbers to code blocks
-    transformed = this.addCodeBlockFeatures(transformed, result, preferences);
-
-    // Add lazy loading to images
-    transformed = this.addImageLazyLoading(transformed);
-
-    // Add table enhancements
-    transformed = this.enhanceTables(transformed);
-
-    return transformed;
+class ChromeMessagingAdapter implements MessagingAdapter {
+  async send(message: IPCMessage): Promise<unknown> {
+    return chrome.runtime.sendMessage(message);
   }
+}
 
-  /**
-   * Apply syntax highlighting to code blocks
-   */
-  private async applySyntaxHighlighting(container: HTMLElement): Promise<void> {
-    try {
-      const { syntaxHighlighter } = await import('../renderers/syntax-highlighter');
-      syntaxHighlighter.highlightVisible(container);
-    } catch (error) {
-      debug.error('RenderPipeline', 'Syntax highlighting error:', error);
-    }
-  }
-
-  /**
-   * Stage 6: Apply theming
-   */
-  private applyTheming(container: HTMLElement): void {
-    // Theme will be applied by theme engine
-    // This is a placeholder for theme-specific transformations
-    container.classList.add('mdview-rendered');
-  }
-
-  /**
-   * Add features to code blocks
-   */
-  private addCodeBlockFeatures(
-    html: string,
-    _result: ConversionResult,
-    preferences: Record<string, unknown> = {}
-  ): string {
-    const showLineNumbers = !!preferences.lineNumbers;
-    debug.debug('RenderPipeline', `addCodeBlockFeatures: showLineNumbers = ${showLineNumbers}`);
-
-    return html.replace(
-      /<pre><code class="language-(\w+)">([\s\S]*?)<\/code><\/pre>/g,
-      (_match, lang: string, code: string) => {
-        let lineNumbersHtml = '';
-        let wrapperClass = 'code-block-wrapper';
-        let contentStart = '';
-        let contentEnd = '';
-
-        if (showLineNumbers) {
-          debug.debug('RenderPipeline', 'Generating line numbers for code block');
-          wrapperClass += ' has-line-numbers';
-          // Count lines
-          const lines = code.split('\n');
-          const lineCount = lines.length;
-          // Generate line numbers column
-          const numbers = Array.from({ length: lineCount }, (_, i) => `<span>${i + 1}</span>`).join(
-            ''
-          );
-          lineNumbersHtml = `<div class="line-numbers-rows">${numbers}</div>`;
-          contentStart = '<div class="code-block-content">';
-          contentEnd = '</div>';
-        }
-
-        return `<div class="${wrapperClass}" data-language="${lang}">
-          <div class="code-block-header">
-            <span class="code-language-badge">${lang}</span>
-          </div>
-          ${contentStart}
-            ${lineNumbersHtml}
-            <pre><code class="language-${lang}">${code}</code></pre>
-          ${contentEnd}
-        </div>`;
-      }
-    );
-  }
-
-  /**
-   * Add lazy loading to images
-   */
-  private addImageLazyLoading(html: string): string {
-    return html.replace(/<img /g, '<img loading="lazy" ');
-  }
-
-  /**
-   * Enhance tables
-   */
-  private enhanceTables(html: string): string {
-    return html
-      .replace(/<table>/g, '<div class="table-wrapper"><table>')
-      .replace(/<\/table>/g, '</table></div>');
-  }
-
-  /**
-   * Add copy buttons to code blocks
-   */
-  private addCopyButtons(container: HTMLElement): void {
-    const codeBlocks = container.querySelectorAll('.code-block-wrapper');
-
-    codeBlocks.forEach((wrapper) => {
-      const copyButton = document.createElement('button');
-      copyButton.className = 'code-copy-button';
-      copyButton.textContent = 'Copy';
-      copyButton.setAttribute('aria-label', 'Copy code to clipboard');
-
-      copyButton.addEventListener('click', () => {
-        const code = wrapper.querySelector('code');
-        if (code) {
-          void (async () => {
-            try {
-              await navigator.clipboard.writeText(code.textContent || '');
-              copyButton.textContent = '✓ Copied';
-              setTimeout(() => {
-                copyButton.textContent = 'Copy';
-              }, 2000);
-            } catch (error) {
-              debug.error('RenderPipeline', 'Failed to copy:', error);
-              copyButton.textContent = '✗ Failed';
-              setTimeout(() => {
-                copyButton.textContent = 'Copy';
-              }, 2000);
-            }
-          })();
-        }
-      });
-
-      const header = wrapper.querySelector('.code-block-header');
-      if (header) {
-        header.appendChild(copyButton);
-      }
-    });
-  }
-
-  /**
-   * Set up lazy loading for images
-   */
-  private setupImageLazyLoading(container: HTMLElement): void {
-    const images = container.querySelectorAll('img[loading="lazy"]');
-
-    if ('IntersectionObserver' in window) {
-      const imageObserver = new IntersectionObserver(
-        (entries) => {
-          entries.forEach((entry) => {
-            if (entry.isIntersecting) {
-              const img = entry.target as HTMLImageElement;
-              img.classList.add('loaded');
-              imageObserver.unobserve(img);
-            }
-          });
-        },
-        { rootMargin: '50px' }
-      );
-
-      images.forEach((img) => imageObserver.observe(img));
-    }
-  }
-
-  /**
-   * Mark Mermaid blocks for rendering and await completion
-   */
-  private async markAndRenderMermaidBlocks(container: HTMLElement): Promise<void> {
-    const mermaidBlocks = container.querySelectorAll('.mermaid-container');
-    mermaidBlocks.forEach((block) => {
-      block.classList.add('mermaid-pending');
-    });
-
-    // Await mermaid rendering so cache captures the rendered state
-    if (mermaidBlocks.length > 0) {
-      await this.renderMermaidDiagrams(container);
-    }
-  }
-
-  /**
-   * Render Mermaid diagrams
-   */
-  private async renderMermaidDiagrams(container: HTMLElement): Promise<void> {
-    try {
-      const { mermaidRenderer } = await import('../renderers/mermaid-renderer');
-      await mermaidRenderer.renderAll(container);
-    } catch (error) {
-      debug.error('RenderPipeline', 'Mermaid rendering error:', error);
-    }
-  }
-
-  /**
-   * Setup heading anchors
-   */
-  private setupHeadingAnchors(container: HTMLElement): void {
-    const headings = container.querySelectorAll('h1, h2, h3, h4, h5, h6');
-
-    headings.forEach((heading) => {
-      if (heading.id) {
-        heading.classList.add('heading-with-anchor');
-      }
-    });
-  }
-
-  /**
-   * Chunk markdown for progressive rendering
-   */
-  private chunkMarkdown(markdown: string, chunkSize: number): string[] {
-    const chunks: string[] = [];
-    const lines = markdown.split('\n');
-    let currentChunk: string[] = [];
-    let currentSize = 0;
-
-    for (const line of lines) {
-      currentChunk.push(line);
-      currentSize += line.length;
-
-      // Check if we should create a new chunk
-      // Only break at block boundaries (empty lines)
-      if (currentSize >= chunkSize && line.trim() === '') {
-        chunks.push(currentChunk.join('\n'));
-        currentChunk = [];
-        currentSize = 0;
-      }
-    }
-
-    // Add remaining content
-    if (currentChunk.length > 0) {
-      chunks.push(currentChunk.join('\n'));
-    }
-
-    return chunks.length > 0 ? chunks : [markdown];
-  }
+// ---------------------------------------------------------------------------
+// Re-export the pipeline class (consumers can still `new RenderPipeline()`)
+// ---------------------------------------------------------------------------
 
-  /**
-   * Notify progress callbacks
-   */
-  private notifyProgress(progress: RenderProgress): void {
-    this.progressCallbacks.forEach((callback) => {
-      try {
-        callback(progress);
-      } catch (error) {
-        debug.error('RenderPipeline', 'Progress callback error:', error);
-      }
+/**
+ * Chrome-flavored RenderPipeline.
+ *
+ * Extends the core pipeline by injecting a ChromeMessagingAdapter so that
+ * cache operations (CACHE_GENERATE_KEY, CACHE_GET, CACHE_SET) are routed
+ * through the Chrome extension service worker.
+ */
+export class RenderPipeline extends CoreRenderPipeline {
+  constructor(options?: RenderPipelineOptions) {
+    super({
+      messaging: new ChromeMessagingAdapter(),
+      ...options,
     });
   }
-
-  /**
-   * Show error in container
-   */
-  private showError(container: HTMLElement, error: unknown): void {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    container.innerHTML = `
-      <div class="mdview-error" role="alert">
-        <h2>⚠️ Rendering Error</h2>
-        <p>Failed to render markdown content.</p>
-        <details>
-          <summary>Technical Details</summary>
-          <pre>${this.escapeHtml(errorMessage)}</pre>
-        </details>
-      </div>
-    `;
-  }
-
-  /**
-   * Escape HTML
-   */
-  private escapeHtml(text: string): string {
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-  }
 }
 
+// Re-export types so existing consumers keep working
+export type { RenderOptions, RenderProgress, ProgressCallback };
+
 // Export singleton
 export const renderPipeline = new RenderPipeline();

From 0d2287ebbba040e7ddb8d1adc1f2e5925b621f23 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:55:15 -0400
Subject: [PATCH 16/26] refactor(core): extract debug-logger with
 StorageAdapter

---
 packages/core/package.json                    |   4 +-
 .../core/src/__tests__/barrel-export.test.ts  |  10 +
 .../core/src/__tests__/debug-logger.test.ts   | 254 ++++++++++++++++++
 packages/core/src/utils/debug-logger.ts       | 180 +++++++++++++
 src/utils/debug-logger.ts                     | 146 ++--------
 5 files changed, 474 insertions(+), 120 deletions(-)
 create mode 100644 packages/core/src/__tests__/debug-logger.test.ts
 create mode 100644 packages/core/src/utils/debug-logger.ts

diff --git a/packages/core/package.json b/packages/core/package.json
index 66845cc..76b41f9 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -4,7 +4,9 @@
   "description": "Core rendering engine for mdview",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./utils/debug-logger": "./src/utils/debug-logger.ts",
+    "./adapters": "./src/adapters.ts"
   },
   "scripts": {
     "test": "vitest",
diff --git a/packages/core/src/__tests__/barrel-export.test.ts b/packages/core/src/__tests__/barrel-export.test.ts
index 21ccad3..3881805 100644
--- a/packages/core/src/__tests__/barrel-export.test.ts
+++ b/packages/core/src/__tests__/barrel-export.test.ts
@@ -49,6 +49,10 @@ import {
   // Frontmatter
   extractFrontmatter,
   renderFrontmatterHtml,
+  // Debug logger
+  DebugLogger,
+  createDebugLogger,
+  createDebug,
 } from '../index';
 
 describe('@mdview/core barrel export', () => {
@@ -125,4 +129,10 @@ describe('@mdview/core barrel export', () => {
     expect(typeof extractFrontmatter).toBe('function');
     expect(typeof renderFrontmatterHtml).toBe('function');
   });
+
+  it('exports debug logger', () => {
+    expect(DebugLogger).toBeDefined();
+    expect(typeof createDebugLogger).toBe('function');
+    expect(typeof createDebug).toBe('function');
+  });
 });
diff --git a/packages/core/src/__tests__/debug-logger.test.ts b/packages/core/src/__tests__/debug-logger.test.ts
new file mode 100644
index 0000000..77d5caa
--- /dev/null
+++ b/packages/core/src/__tests__/debug-logger.test.ts
@@ -0,0 +1,254 @@
+import type { StorageAdapter } from '../adapters';
+import { DebugLogger, createDebugLogger, createDebug } from '../utils/debug-logger';
+
+describe('DebugLogger', () => {
+  describe('works with mock StorageAdapter that returns preferences', () => {
+    it('loads log level from storage adapter', async () => {
+      const mockAdapter: StorageAdapter = {
+        async getSync(_keys: string | string[]) {
+          return {
+            preferences: { logLevel: 'debug' },
+          };
+        },
+        async setSync() {},
+        async getLocal() {
+          return {};
+        },
+        async setLocal() {},
+      };
+
+      const logger = new DebugLogger(mockAdapter);
+      // Wait for async init to complete
+      await logger.ready;
+
+      expect(logger.getLogLevel()).toBe('debug');
+    });
+
+    it('respects legacy debug boolean from storage', async () => {
+      const mockAdapter: StorageAdapter = {
+        async getSync(_keys: string | string[]) {
+          return {
+            preferences: { debug: true },
+          };
+        },
+        async setSync() {},
+        async getLocal() {
+          return {};
+        },
+        async setLocal() {},
+      };
+
+      const logger = new DebugLogger(mockAdapter);
+      await logger.ready;
+
+      expect(logger.getLogLevel()).toBe('debug');
+    });
+
+    it('defaults to error when storage has preferences without logLevel or debug', async () => {
+      const mockAdapter: StorageAdapter = {
+        async getSync(_keys: string | string[]) {
+          return {
+            preferences: { theme: 'github-light' },
+          };
+        },
+        async setSync() {},
+        async getLocal() {
+          return {};
+        },
+        async setLocal() {},
+      };
+
+      const logger = new DebugLogger(mockAdapter);
+      await logger.ready;
+
+      expect(logger.getLogLevel()).toBe('error');
+    });
+
+    it('defaults to error when storage adapter rejects', async () => {
+      const mockAdapter: StorageAdapter = {
+        async getSync() {
+          throw new Error('storage unavailable');
+        },
+        async setSync() {},
+        async getLocal() {
+          return {};
+        },
+        async setLocal() {},
+      };
+
+      const logger = new DebugLogger(mockAdapter);
+      await logger.ready;
+
+      expect(logger.getLogLevel()).toBe('error');
+    });
+  });
+
+  describe('works without any adapter (graceful degradation)', () => {
+    it('defaults to error log level without adapter', () => {
+      const logger = new DebugLogger();
+      expect(logger.getLogLevel()).toBe('error');
+    });
+
+    it('allows setting log level manually', () => {
+      const logger = new DebugLogger();
+      logger.setLogLevel('info');
+      expect(logger.getLogLevel()).toBe('info');
+    });
+  });
+
+  describe('log level filtering works correctly', () => {
+    let consoleSpy: {
+      log: ReturnType<typeof vi.spyOn>;
+      debug: ReturnType<typeof vi.spyOn>;
+      info: ReturnType<typeof vi.spyOn>;
+      warn: ReturnType<typeof vi.spyOn>;
+      error: ReturnType<typeof vi.spyOn>;
+    };
+
+    beforeEach(() => {
+      consoleSpy = {
+        log: vi.spyOn(console, 'log').mockImplementation(() => {}),
+        debug: vi.spyOn(console, 'debug').mockImplementation(() => {}),
+        info: vi.spyOn(console, 'info').mockImplementation(() => {}),
+        warn: vi.spyOn(console, 'warn').mockImplementation(() => {}),
+        error: vi.spyOn(console, 'error').mockImplementation(() => {}),
+      };
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('at level none, suppresses all output', () => {
+      const logger = new DebugLogger();
+      logger.setLogLevel('none');
+
+      logger.error('ctx', 'msg');
+      logger.warn('ctx', 'msg');
+      logger.info('ctx', 'msg');
+      logger.debug('ctx', 'msg');
+      logger.log('ctx', 'msg');
+
+      expect(consoleSpy.error).not.toHaveBeenCalled();
+      expect(consoleSpy.warn).not.toHaveBeenCalled();
+      expect(consoleSpy.info).not.toHaveBeenCalled();
+      expect(consoleSpy.debug).not.toHaveBeenCalled();
+      expect(consoleSpy.log).not.toHaveBeenCalled();
+    });
+
+    it('at level error, only shows errors', () => {
+      const logger = new DebugLogger();
+      logger.setLogLevel('error');
+
+      logger.error('ctx', 'err msg');
+      logger.warn('ctx', 'warn msg');
+      logger.info('ctx', 'info msg');
+      logger.log('ctx', 'log msg');
+
+      expect(consoleSpy.error).toHaveBeenCalledWith('[ctx]', 'err msg');
+      expect(consoleSpy.warn).not.toHaveBeenCalled();
+      expect(consoleSpy.info).not.toHaveBeenCalled();
+      expect(consoleSpy.log).not.toHaveBeenCalled();
+    });
+
+    it('at level warn, shows errors and warnings', () => {
+      const logger = new DebugLogger();
+      logger.setLogLevel('warn');
+
+      logger.error('ctx', 'err msg');
+      logger.warn('ctx', 'warn msg');
+      logger.info('ctx', 'info msg');
+      logger.log('ctx', 'log msg');
+
+      expect(consoleSpy.error).toHaveBeenCalled();
+      expect(consoleSpy.warn).toHaveBeenCalledWith('[ctx]', 'warn msg');
+      expect(consoleSpy.info).not.toHaveBeenCalled();
+      expect(consoleSpy.log).not.toHaveBeenCalled();
+    });
+
+    it('at level info, shows errors, warnings, and info', () => {
+      const logger = new DebugLogger();
+      logger.setLogLevel('info');
+
+      logger.error('ctx', 'err');
+      logger.warn('ctx', 'warn');
+      logger.info('ctx', 'info');
+      logger.log('ctx', 'log');
+
+      expect(consoleSpy.error).toHaveBeenCalled();
+      expect(consoleSpy.warn).toHaveBeenCalled();
+      expect(consoleSpy.info).toHaveBeenCalledWith('[ctx]', 'info');
+      expect(consoleSpy.log).not.toHaveBeenCalled();
+    });
+
+    it('at level debug, shows everything', () => {
+      const logger = new DebugLogger();
+      logger.setLogLevel('debug');
+
+      logger.error('ctx', 'err');
+      logger.warn('ctx', 'warn');
+      logger.info('ctx', 'info');
+      logger.debug('ctx', 'dbg');
+      logger.log('ctx', 'log');
+
+      expect(consoleSpy.error).toHaveBeenCalled();
+      expect(consoleSpy.warn).toHaveBeenCalled();
+      expect(consoleSpy.info).toHaveBeenCalled();
+      expect(consoleSpy.debug).toHaveBeenCalledWith('[ctx]', 'dbg');
+      expect(consoleSpy.log).toHaveBeenCalledWith('[ctx]', 'log');
+    });
+  });
+
+  describe('factory functions', () => {
+    it('createDebugLogger returns a DebugLogger instance', () => {
+      const logger = createDebugLogger();
+      expect(logger).toBeInstanceOf(DebugLogger);
+    });
+
+    it('createDebugLogger accepts an optional adapter', async () => {
+      const mockAdapter: StorageAdapter = {
+        async getSync() {
+          return { preferences: { logLevel: 'warn' as const } };
+        },
+        async setSync() {},
+        async getLocal() {
+          return {};
+        },
+        async setLocal() {},
+      };
+
+      const logger = createDebugLogger(mockAdapter);
+      await logger.ready;
+      expect(logger.getLogLevel()).toBe('warn');
+    });
+
+    it('createDebug returns convenience object with all methods', () => {
+      const d = createDebug();
+      expect(typeof d.log).toBe('function');
+      expect(typeof d.debug).toBe('function');
+      expect(typeof d.info).toBe('function');
+      expect(typeof d.warn).toBe('function');
+      expect(typeof d.error).toBe('function');
+      expect(typeof d.group).toBe('function');
+      expect(typeof d.groupEnd).toBe('function');
+      expect(typeof d.table).toBe('function');
+      expect(typeof d.time).toBe('function');
+      expect(typeof d.timeEnd).toBe('function');
+      expect(typeof d.setLogLevel).toBe('function');
+      expect(typeof d.getLogLevel).toBe('function');
+      expect(typeof d.setDebugMode).toBe('function');
+      expect(typeof d.isDebugEnabled).toBe('function');
+    });
+
+    it('createDebug convenience methods delegate to logger', () => {
+      const d = createDebug();
+      d.setLogLevel('debug');
+      expect(d.getLogLevel()).toBe('debug');
+      expect(d.isDebugEnabled()).toBe(true);
+
+      d.setDebugMode(false);
+      expect(d.getLogLevel()).toBe('error');
+      expect(d.isDebugEnabled()).toBe(false);
+    });
+  });
+});
diff --git a/packages/core/src/utils/debug-logger.ts b/packages/core/src/utils/debug-logger.ts
new file mode 100644
index 0000000..2dec0bb
--- /dev/null
+++ b/packages/core/src/utils/debug-logger.ts
@@ -0,0 +1,180 @@
+/**
+ * Debug Logger (platform-agnostic)
+ * Centralized logging utility that respects verbosity level preference.
+ *
+ * Uses an optional StorageAdapter to load the log level from persistent
+ * storage.  When no adapter is provided the logger degrades gracefully
+ * to the default level ('error').
+ */
+
+import type { LogLevel } from '../types/index';
+import type { StorageAdapter } from '../adapters';
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  none: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+export class DebugLogger {
+  private logLevel: LogLevel = 'error'; // Default to error so we see failures
+  /** Resolves once async init (storage load) is complete. */
+  readonly ready: Promise<void>;
+
+  constructor(adapter?: StorageAdapter) {
+    if (adapter) {
+      this.ready = this.loadDebugState(adapter);
+    } else {
+      this.ready = Promise.resolve();
+    }
+  }
+
+  private async loadDebugState(adapter: StorageAdapter): Promise<void> {
+    try {
+      const result = (await adapter.getSync('preferences')) as {
+        preferences?: { logLevel?: LogLevel; debug?: boolean };
+      };
+      if (result.preferences?.logLevel) {
+        this.logLevel = result.preferences.logLevel;
+      } else if (result.preferences?.debug) {
+        // Migration: if debug was true, use debug level, otherwise use error (default)
+        this.logLevel = 'debug';
+      } else {
+        this.logLevel = 'error';
+      }
+    } catch {
+      // If we can't access storage, default to error
+      this.logLevel = 'error';
+    }
+  }
+
+  setLogLevel(level: LogLevel): void {
+    this.logLevel = level;
+  }
+
+  getLogLevel(): LogLevel {
+    return this.logLevel;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return LEVEL_PRIORITY[this.logLevel] >= LEVEL_PRIORITY[level];
+  }
+
+  log(context: string, ...args: unknown[]): void {
+    if (this.shouldLog('debug')) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+      console.log(`[${context}]`, ...(args as any[]));
+    }
+  }
+
+  debug(context: string, ...args: unknown[]): void {
+    if (this.shouldLog('debug')) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+      console.debug(`[${context}]`, ...(args as any[]));
+    }
+  }
+
+  info(context: string, ...args: unknown[]): void {
+    if (this.shouldLog('info')) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+      console.info(`[${context}]`, ...(args as any[]));
+    }
+  }
+
+  warn(context: string, ...args: unknown[]): void {
+    if (this.shouldLog('warn')) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+      console.warn(`[${context}]`, ...(args as any[]));
+    }
+  }
+
+  error(context: string, ...args: unknown[]): void {
+    if (this.shouldLog('error')) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+      console.error(`[${context}]`, ...(args as any[]));
+    }
+  }
+
+  group(context: string, label: string): void {
+    if (this.shouldLog('debug')) {
+      console.group(`[${context}] ${label}`);
+    }
+  }
+
+  groupEnd(): void {
+    if (this.shouldLog('debug')) {
+      console.groupEnd();
+    }
+  }
+
+  table(context: string, data: unknown): void {
+    if (this.shouldLog('debug')) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      console.log(`[${context}]`);
+      console.table(data);
+    }
+  }
+
+  time(context: string, label: string): void {
+    if (this.shouldLog('debug')) {
+      console.time(`[${context}] ${label}`);
+    }
+  }
+
+  timeEnd(context: string, label: string): void {
+    if (this.shouldLog('debug')) {
+      console.timeEnd(`[${context}] ${label}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory helpers
+// ---------------------------------------------------------------------------
+
+/** Create a new DebugLogger, optionally loading preferences from an adapter. */
+export function createDebugLogger(adapter?: StorageAdapter): DebugLogger {
+  return new DebugLogger(adapter);
+}
+
+/** Convenience object that mirrors the original `debug` export shape. */
+export interface DebugHelpers {
+  log: (context: string, ...args: unknown[]) => void;
+  debug: (context: string, ...args: unknown[]) => void;
+  info: (context: string, ...args: unknown[]) => void;
+  warn: (context: string, ...args: unknown[]) => void;
+  error: (context: string, ...args: unknown[]) => void;
+  group: (context: string, label: string) => void;
+  groupEnd: () => void;
+  table: (context: string, data: unknown) => void;
+  time: (context: string, label: string) => void;
+  timeEnd: (context: string, label: string) => void;
+  setLogLevel: (level: LogLevel) => void;
+  getLogLevel: () => LogLevel;
+  setDebugMode: (enabled: boolean) => void;
+  isDebugEnabled: () => boolean;
+}
+
+/** Create a convenience `debug` helper object backed by the given logger. */
+export function createDebug(adapter?: StorageAdapter): DebugHelpers {
+  const logger = new DebugLogger(adapter);
+  return {
+    log: (context: string, ...args: unknown[]) => logger.log(context, ...args),
+    debug: (context: string, ...args: unknown[]) => logger.debug(context, ...args),
+    info: (context: string, ...args: unknown[]) => logger.info(context, ...args),
+    warn: (context: string, ...args: unknown[]) => logger.warn(context, ...args),
+    error: (context: string, ...args: unknown[]) => logger.error(context, ...args),
+    group: (context: string, label: string) => logger.group(context, label),
+    groupEnd: () => logger.groupEnd(),
+    table: (context: string, data: unknown) => logger.table(context, data),
+    time: (context: string, label: string) => logger.time(context, label),
+    timeEnd: (context: string, label: string) => logger.timeEnd(context, label),
+    setLogLevel: (level: LogLevel) => logger.setLogLevel(level),
+    getLogLevel: () => logger.getLogLevel(),
+    // Compat
+    setDebugMode: (enabled: boolean) => logger.setLogLevel(enabled ? 'debug' : 'error'),
+    isDebugEnabled: () => logger.getLogLevel() === 'debug',
+  };
+}
diff --git a/src/utils/debug-logger.ts b/src/utils/debug-logger.ts
index d053128..d8237fb 100644
--- a/src/utils/debug-logger.ts
+++ b/src/utils/debug-logger.ts
@@ -1,137 +1,46 @@
 /**
- * Debug Logger
- * Centralized logging utility that respects verbosity level preference
+ * Debug Logger — Chrome extension shim
+ *
+ * Re-exports the platform-agnostic debug-logger from @mdview/core,
+ * pre-configured with a Chrome StorageAdapter that reads from
+ * chrome.storage.sync.  Existing callers continue to import
+ * `debug` and `debugLogger` without any changes.
  */
 
+import type { StorageAdapter } from '@mdview/core/adapters';
+import { DebugLogger as CoreDebugLogger } from '@mdview/core/utils/debug-logger';
 import type { LogLevel } from '../types';
 
-const LEVEL_PRIORITY: Record<LogLevel, number> = {
-  none: 0,
-  error: 1,
-  warn: 2,
-  info: 3,
-  debug: 4,
-};
-
-class DebugLogger {
-  private static instance: DebugLogger;
-  private logLevel: LogLevel = 'error'; // Default to error so we see failures
-
-  private constructor() {
-    // Initialize from storage
-    void this.loadDebugState();
-  }
-
-  static getInstance(): DebugLogger {
-    if (!DebugLogger.instance) {
-      DebugLogger.instance = new DebugLogger();
-    }
-    return DebugLogger.instance;
-  }
-
-  private async loadDebugState(): Promise<void> {
-    try {
-      const result = (await chrome.storage.sync.get('preferences')) as {
-        preferences?: { logLevel?: LogLevel; debug?: boolean };
-      };
-      if (result.preferences?.logLevel) {
-        this.logLevel = result.preferences.logLevel;
-      } else if (result.preferences?.debug) {
-        // Migration: if debug was true, use debug level, otherwise use error (default)
-        this.logLevel = 'debug';
-      } else {
-        this.logLevel = 'error';
-      }
-    } catch {
-      // If we can't access chrome.storage, default to error
-      this.logLevel = 'error';
-    }
-  }
-
-  setLogLevel(level: LogLevel): void {
-    this.logLevel = level;
-  }
-
-  getLogLevel(): LogLevel {
-    return this.logLevel;
-  }
-
-  private shouldLog(level: LogLevel): boolean {
-    return LEVEL_PRIORITY[this.logLevel] >= LEVEL_PRIORITY[level];
-  }
+// ---------------------------------------------------------------------------
+// Chrome StorageAdapter (sync-only for preferences)
+// ---------------------------------------------------------------------------
 
-  log(context: string, ...args: unknown[]): void {
-    if (this.shouldLog('debug')) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-      console.log(`[${context}]`, ...(args as any[]));
-    }
+class ChromeStorageAdapter implements StorageAdapter {
+  async getSync(keys: string | string[]): Promise<Record<string, unknown>> {
+    return chrome.storage.sync.get(keys) as Promise<Record<string, unknown>>;
   }
 
-  debug(context: string, ...args: unknown[]): void {
-    if (this.shouldLog('debug')) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-      console.debug(`[${context}]`, ...(args as any[]));
-    }
+  async setSync(data: Record<string, unknown>): Promise<void> {
+    await chrome.storage.sync.set(data);
   }
 
-  info(context: string, ...args: unknown[]): void {
-    if (this.shouldLog('info')) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-      console.info(`[${context}]`, ...(args as any[]));
-    }
+  async getLocal(keys: string | string[]): Promise<Record<string, unknown>> {
+    return chrome.storage.local.get(keys) as Promise<Record<string, unknown>>;
   }
 
-  warn(context: string, ...args: unknown[]): void {
-    if (this.shouldLog('warn')) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-      console.warn(`[${context}]`, ...(args as any[]));
-    }
-  }
-
-  error(context: string, ...args: unknown[]): void {
-    if (this.shouldLog('error')) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
-      console.error(`[${context}]`, ...(args as any[]));
-    }
-  }
-
-  group(context: string, label: string): void {
-    if (this.shouldLog('debug')) {
-      console.group(`[${context}] ${label}`);
-    }
-  }
-
-  groupEnd(): void {
-    if (this.shouldLog('debug')) {
-      console.groupEnd();
-    }
-  }
-
-  table(context: string, data: unknown): void {
-    if (this.shouldLog('debug')) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      console.log(`[${context}]`);
-      console.table(data);
-    }
-  }
-
-  time(context: string, label: string): void {
-    if (this.shouldLog('debug')) {
-      console.time(`[${context}] ${label}`);
-    }
-  }
-
-  timeEnd(context: string, label: string): void {
-    if (this.shouldLog('debug')) {
-      console.timeEnd(`[${context}] ${label}`);
-    }
+  async setLocal(data: Record<string, unknown>): Promise<void> {
+    await chrome.storage.local.set(data);
   }
 }
 
-// Export singleton instance
-export const debugLogger = DebugLogger.getInstance();
+// ---------------------------------------------------------------------------
+// Singleton with Chrome adapter
+// ---------------------------------------------------------------------------
+
+const chromeAdapter = new ChromeStorageAdapter();
+export const debugLogger = new CoreDebugLogger(chromeAdapter);
 
-  // Export convenience functions
+// Export convenience functions — identical shape to the original
 export const debug = {
   log: (context: string, ...args: unknown[]) => debugLogger.log(context, ...args),
   debug: (context: string, ...args: unknown[]) => debugLogger.debug(context, ...args),
@@ -149,4 +58,3 @@ export const debug = {
   setDebugMode: (enabled: boolean) => debugLogger.setLogLevel(enabled ? 'debug' : 'error'),
   isDebugEnabled: () => debugLogger.getLogLevel() === 'debug',
 };
-

From b05200ff4e5687b5d9f758f90020c46c4e736ad7 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 08:58:51 -0400
Subject: [PATCH 17/26] refactor(core): extract comment-manager with
 FileAdapter and IdentityAdapter

---
 .../src/__tests__/comment-manager.test.ts     | 394 ++++++++
 packages/core/src/comments/comment-manager.ts | 851 +++++++++++++++++
 src/comments/comment-manager.ts               | 870 ++----------------
 3 files changed, 1313 insertions(+), 802 deletions(-)
 create mode 100644 packages/core/src/__tests__/comment-manager.test.ts
 create mode 100644 packages/core/src/comments/comment-manager.ts

diff --git a/packages/core/src/__tests__/comment-manager.test.ts b/packages/core/src/__tests__/comment-manager.test.ts
new file mode 100644
index 0000000..3980aa2
--- /dev/null
+++ b/packages/core/src/__tests__/comment-manager.test.ts
@@ -0,0 +1,394 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { CommentManager } from '../comments/comment-manager';
+import type { FileAdapter, IdentityAdapter, FileWriteResult } from '../adapters';
+import type { AppState } from '../types/index';
+
+/**
+ * Minimal mock DOM environment for CommentManager tests.
+ * The manager requires DOM elements (window, document, etc.) which
+ * jsdom provides. We mock the UI and highlighter dependencies since
+ * they are browser-specific and not extracted to core yet.
+ */
+
+// Mock the browser-specific dependencies (comment-ui, comment-highlight)
+// These still live in src/comments/ and are imported via relative paths
+vi.mock('../../../../src/comments/comment-ui', () => {
+  class MockCommentUI {
+    setCurrentAuthor = vi.fn();
+    renderCard = vi.fn().mockReturnValue(document.createElement('div'));
+    renderInputForm = vi.fn().mockReturnValue(document.createElement('div'));
+    renderReplyForm = vi.fn().mockReturnValue(document.createElement('div'));
+    renderEmojiPicker = vi.fn().mockReturnValue(document.createElement('div'));
+    showToast = vi.fn();
+    destroy = vi.fn();
+  }
+  return { CommentUI: MockCommentUI };
+});
+
+vi.mock('../../../../src/comments/comment-highlight', () => {
+  class MockCommentHighlighter {
+    highlightComment = vi.fn();
+    clearActive = vi.fn();
+    setActive = vi.fn();
+    setResolved = vi.fn();
+    removeHighlight = vi.fn();
+    getHighlightElement = vi.fn().mockReturnValue(null);
+  }
+  return { CommentHighlighter: MockCommentHighlighter };
+});
+
+function createMockFileAdapter(
+  overrides: Partial<FileAdapter> = {}
+): FileAdapter {
+  return {
+    writeFile: vi.fn().mockResolvedValue({ success: true } as FileWriteResult),
+    readFile: vi.fn().mockResolvedValue(''),
+    checkChanged: vi.fn().mockResolvedValue({ changed: false }),
+    watch: vi.fn().mockReturnValue(() => {}),
+    ...overrides,
+  };
+}
+
+function createMockIdentityAdapter(
+  overrides: Partial<IdentityAdapter> = {}
+): IdentityAdapter {
+  return {
+    getUsername: vi.fn().mockResolvedValue('test-user'),
+    ...overrides,
+  };
+}
+
+function createMinimalPreferences(): AppState['preferences'] {
+  return {
+    theme: 'github-light',
+    autoTheme: false,
+    lightTheme: 'github-light',
+    darkTheme: 'github-dark',
+    syntaxTheme: 'default',
+    autoReload: false,
+    lineNumbers: false,
+    enableHtml: false,
+    syncTabs: false,
+    logLevel: 'none',
+    commentsEnabled: true,
+  };
+}
+
+const SAMPLE_MARKDOWN = `# Hello World
+
+This is a test document.
+
+Some content here.
+`;
+
+describe('CommentManager (core)', () => {
+  let manager: CommentManager;
+
+  beforeEach(() => {
+    // Set up a basic DOM container
+    const container = document.createElement('div');
+    container.id = 'mdview-container';
+    container.textContent = 'This is a test document. Some content here.';
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    if (manager) {
+      manager.destroy();
+    }
+    document.body.innerHTML = '';
+  });
+
+  describe('with FileAdapter and IdentityAdapter', () => {
+    it('uses IdentityAdapter to get username when no author is configured', async () => {
+      const identity = createMockIdentityAdapter({
+        getUsername: vi.fn().mockResolvedValue('adapter-user'),
+      });
+      const file = createMockFileAdapter();
+
+      manager = new CommentManager({ file, identity });
+      const result = await manager.initialize(
+        SAMPLE_MARKDOWN,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      expect(identity.getUsername).toHaveBeenCalled();
+      expect(result).toBeDefined();
+      expect(result.comments).toEqual([]);
+    });
+
+    it('prefers preferences.commentAuthor over IdentityAdapter', async () => {
+      const identity = createMockIdentityAdapter({
+        getUsername: vi.fn().mockResolvedValue('adapter-user'),
+      });
+      const file = createMockFileAdapter();
+
+      manager = new CommentManager({ file, identity });
+      const prefs = createMinimalPreferences();
+      prefs.commentAuthor = 'pref-author';
+
+      await manager.initialize(SAMPLE_MARKDOWN, '/test/file.md', prefs);
+
+      // Should NOT call getUsername since author is already set
+      expect(identity.getUsername).not.toHaveBeenCalled();
+    });
+
+    it('uses FileAdapter.writeFile when adding a comment', async () => {
+      const file = createMockFileAdapter();
+      const identity = createMockIdentityAdapter();
+
+      manager = new CommentManager({ file, identity });
+      await manager.initialize(
+        SAMPLE_MARKDOWN,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      await manager.addComment('test document', 'My note');
+
+      expect(file.writeFile).toHaveBeenCalledWith(
+        '/test/file.md',
+        expect.stringContaining('My note')
+      );
+    });
+
+    it('uses FileAdapter.writeFile when editing a comment', async () => {
+      const mdWithComment = `# Hello World
+
+This is a test[@1] document.
+
+<!-- mdview:annotations [{"id":1,"anchor":{"text":"test"},"body":"My note","author":"tester","date":"2024-01-01T00:00:00.000Z"}] -->
+`;
+      const file = createMockFileAdapter();
+      const identity = createMockIdentityAdapter();
+
+      manager = new CommentManager({ file, identity });
+      await manager.initialize(
+        mdWithComment,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      await manager.editComment('comment-1', 'Updated note');
+
+      expect(file.writeFile).toHaveBeenCalledWith(
+        '/test/file.md',
+        expect.stringContaining('Updated note')
+      );
+    });
+
+    it('uses FileAdapter.writeFile when resolving a comment', async () => {
+      const mdWithComment = `# Hello
+
+Test[@1] content.
+
+<!-- mdview:annotations [{"id":1,"anchor":{"text":"Test"},"body":"A note","author":"tester","date":"2024-01-01T00:00:00.000Z"}] -->
+`;
+      const file = createMockFileAdapter();
+      const identity = createMockIdentityAdapter();
+
+      manager = new CommentManager({ file, identity });
+      await manager.initialize(
+        mdWithComment,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      await manager.resolveComment('comment-1');
+
+      expect(file.writeFile).toHaveBeenCalled();
+    });
+
+    it('uses FileAdapter.writeFile when deleting a comment', async () => {
+      const mdWithComment = `# Hello
+
+Test[@1] content.
+
+<!-- mdview:annotations [{"id":1,"anchor":{"text":"Test"},"body":"A note","author":"tester","date":"2024-01-01T00:00:00.000Z"}] -->
+`;
+      const file = createMockFileAdapter();
+      const identity = createMockIdentityAdapter();
+
+      manager = new CommentManager({ file, identity });
+      await manager.initialize(
+        mdWithComment,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      await manager.deleteComment('comment-1');
+
+      expect(file.writeFile).toHaveBeenCalled();
+    });
+
+    it('reports write errors from FileAdapter', async () => {
+      const file = createMockFileAdapter({
+        writeFile: vi.fn().mockResolvedValue({
+          success: false,
+          error: 'Permission denied',
+        }),
+      });
+      const identity = createMockIdentityAdapter();
+
+      manager = new CommentManager({ file, identity });
+      await manager.initialize(
+        SAMPLE_MARKDOWN,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      // Should not throw even if write fails
+      await expect(
+        manager.addComment('test', 'note')
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe('graceful degradation without adapters', () => {
+    it('initializes without any adapters', async () => {
+      manager = new CommentManager();
+      const result = await manager.initialize(
+        SAMPLE_MARKDOWN,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      expect(result).toBeDefined();
+      expect(result.comments).toEqual([]);
+    });
+
+    it('uses empty username when no adapter and no preference set', async () => {
+      manager = new CommentManager();
+      await manager.initialize(
+        SAMPLE_MARKDOWN,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      // Comments created should have empty author
+      const comments = manager.getComments();
+      expect(comments).toEqual([]);
+    });
+
+    it('addComment works without FileAdapter (skips write)', async () => {
+      manager = new CommentManager();
+      await manager.initialize(
+        SAMPLE_MARKDOWN,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      // Should not throw even without file adapter
+      await expect(
+        manager.addComment('test document', 'A note')
+      ).resolves.not.toThrow();
+
+      const comments = manager.getComments();
+      expect(comments).toHaveLength(1);
+      expect(comments[0].body).toBe('A note');
+    });
+
+    it('editComment works without FileAdapter', async () => {
+      const mdWithComment = `# Hello
+
+Test[@1] content.
+
+<!-- mdview:annotations [{"id":1,"anchor":{"text":"Test"},"body":"A note","author":"tester","date":"2024-01-01T00:00:00.000Z"}] -->
+`;
+      manager = new CommentManager();
+      await manager.initialize(
+        mdWithComment,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      await expect(
+        manager.editComment('comment-1', 'Updated')
+      ).resolves.not.toThrow();
+    });
+
+    it('deleteComment works without FileAdapter', async () => {
+      const mdWithComment = `# Hello
+
+Test[@1] content.
+
+<!-- mdview:annotations [{"id":1,"anchor":{"text":"Test"},"body":"A note","author":"tester","date":"2024-01-01T00:00:00.000Z"}] -->
+`;
+      manager = new CommentManager();
+      await manager.initialize(
+        mdWithComment,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      await expect(
+        manager.deleteComment('comment-1')
+      ).resolves.not.toThrow();
+
+      expect(manager.getComments()).toHaveLength(0);
+    });
+
+    it('resolveComment works without FileAdapter', async () => {
+      const mdWithComment = `# Hello
+
+Test[@1] content.
+
+<!-- mdview:annotations [{"id":1,"anchor":{"text":"Test"},"body":"A note","author":"tester","date":"2024-01-01T00:00:00.000Z"}] -->
+`;
+      manager = new CommentManager();
+      await manager.initialize(
+        mdWithComment,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      await expect(
+        manager.resolveComment('comment-1')
+      ).resolves.not.toThrow();
+    });
+
+    it('provides partial adapters — only FileAdapter', async () => {
+      const file = createMockFileAdapter();
+
+      manager = new CommentManager({ file });
+      await manager.initialize(
+        SAMPLE_MARKDOWN,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      await manager.addComment('test document', 'note');
+
+      // File adapter should be used for write
+      expect(file.writeFile).toHaveBeenCalled();
+    });
+
+    it('provides partial adapters — only IdentityAdapter', async () => {
+      const identity = createMockIdentityAdapter({
+        getUsername: vi.fn().mockResolvedValue('identity-only-user'),
+      });
+
+      manager = new CommentManager({ identity });
+      await manager.initialize(
+        SAMPLE_MARKDOWN,
+        '/test/file.md',
+        createMinimalPreferences()
+      );
+
+      expect(identity.getUsername).toHaveBeenCalled();
+
+      // addComment should still work (no file write, but no crash)
+      await expect(
+        manager.addComment('test', 'note')
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe('isWriteInProgress', () => {
+    it('returns false initially', () => {
+      manager = new CommentManager();
+      expect(manager.isWriteInProgress()).toBe(false);
+    });
+  });
+});
diff --git a/packages/core/src/comments/comment-manager.ts b/packages/core/src/comments/comment-manager.ts
new file mode 100644
index 0000000..c74d847
--- /dev/null
+++ b/packages/core/src/comments/comment-manager.ts
@@ -0,0 +1,851 @@
+/**
+ * Comment Manager (core)
+ *
+ * CRUD orchestrator that connects the comment parser, serializer, UI,
+ * text highlighter, and file-writing into a single cohesive controller.
+ * All comment lifecycle operations flow through this class.
+ *
+ * This core version uses FileAdapter and IdentityAdapter instead of
+ * chrome.runtime.sendMessage, allowing it to work in any environment
+ * (Chrome extension, Electron, Node.js, tests).
+ *
+ * Both adapters are optional — the manager degrades gracefully:
+ * - Without FileAdapter: file writes are silently skipped
+ * - Without IdentityAdapter: empty username is used as fallback
+ */
+
+import type { Comment, CommentParseResult, AppState, CommentTag } from '../types/index';
+import type { FileAdapter, IdentityAdapter } from '../adapters';
+import { CommentUI } from '../../../../src/comments/comment-ui';
+import { CommentHighlighter } from '../../../../src/comments/comment-highlight';
+import { parseComments } from './annotation-parser';
+import {
+  addComment as serializerAddComment,
+  addCommentAtOffset as serializerAddCommentAtOffset,
+  removeComment as serializerRemoveComment,
+  updateComment as serializerUpdateComment,
+  updateCommentMetadata as serializerUpdateCommentMetadata,
+  resolveComment as serializerResolveComment,
+  addReply as serializerAddReply,
+  toggleReaction as serializerToggleReaction,
+  generateNextCommentId,
+} from './annotation-serializer';
+import { buildSourceMap, findInsertionPoint } from './source-position-map';
+import type { SourcePositionMap, SelectionContext } from './source-position-map';
+import { computeCommentContext } from './comment-context';
+
+export interface CommentManagerAdapters {
+  file?: FileAdapter;
+  identity?: IdentityAdapter;
+}
+
+export class CommentManager {
+  private comments: Comment[] = [];
+  private rawMarkdown: string = '';
+  private filePath: string = '';
+  private writeInProgress = false;
+  private ui: CommentUI | null = null;
+  private highlighter: CommentHighlighter | null = null;
+  private authorName: string = '';
+  private sourceMap: SourcePositionMap | null = null;
+  private pendingContext: SelectionContext | null = null;
+
+  private readonly fileAdapter: FileAdapter | null;
+  private readonly identityAdapter: IdentityAdapter | null;
+
+  private windowListeners: Array<{
+    event: string;
+    handler: EventListener;
+  }> = [];
+
+  private eventListeners: Array<{
+    event: string;
+    handler: EventListener;
+  }> = [];
+
+  /** Grace period (ms) after native write before clearing writeInProgress.
+   *  Must exceed file-watcher poll interval (1000ms) + debounce (500ms)
+   *  to prevent the auto-reload from triggering on our own write. */
+  private static readonly WRITE_GUARD_DELAY = 2000;
+
+  constructor(adapters?: CommentManagerAdapters) {
+    this.fileAdapter = adapters?.file ?? null;
+    this.identityAdapter = adapters?.identity ?? null;
+  }
+
+  /**
+   * Parse existing comments from raw markdown, set up UI and highlights,
+   * and wire event listeners for user actions.
+   */
+  async initialize(
+    markdown: string,
+    filePath: string,
+    preferences: AppState['preferences']
+  ): Promise<CommentParseResult> {
+    this.rawMarkdown = markdown;
+    this.filePath = filePath;
+    this.authorName = preferences.commentAuthor ?? '';
+
+    // If no author configured, try to get username from identity adapter
+    if (!this.authorName && this.identityAdapter) {
+      try {
+        const username = await this.identityAdapter.getUsername();
+        if (username) {
+          this.authorName = username;
+        }
+      } catch {
+        // Identity adapter may fail — leave author empty
+      }
+    }
+
+    // Build source position map for accurate comment insertion
+    this.sourceMap = buildSourceMap(markdown);
+
+    // Parse existing comments
+    const result = parseComments(markdown);
+    this.comments = [...result.comments];
+
+    // Set up UI
+    this.ui = new CommentUI();
+    this.ui.setCurrentAuthor(this.authorName);
+
+    // Set up highlighter - highlight text first, then position cards
+    this.highlighter = new CommentHighlighter();
+    const container = document.getElementById('mdview-container') || document.body;
+    for (const comment of this.comments) {
+      this.highlighter.highlightComment(container, comment);
+    }
+
+    // Render cards and position them next to their highlights
+    for (const comment of this.comments) {
+      const card = this.ui.renderCard(comment);
+      document.body.appendChild(card);
+      this.positionCardAtHighlight(card, comment.id);
+    }
+
+    // Apply cascade layout to prevent card overlap
+    this.repositionAllCards();
+
+    // Re-position cards on window resize (debounced)
+    let resizeTimer: ReturnType<typeof setTimeout> | null = null;
+    const resizeHandler = () => {
+      if (resizeTimer) clearTimeout(resizeTimer);
+      resizeTimer = setTimeout(() => this.repositionAllCards(), 150);
+    };
+    window.addEventListener('resize', resizeHandler);
+    this.windowListeners.push({ event: 'resize', handler: resizeHandler as EventListener });
+
+    // Wire up custom DOM event listeners
+    this.addEventHandler('mdview:comment:edit', (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.commentId) {
+        this.showEditForm(detail.commentId);
+      }
+    });
+
+    this.addEventHandler('mdview:comment:resolve', (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.commentId) {
+        void this.resolveComment(detail.commentId);
+      }
+    });
+
+    this.addEventHandler('mdview:comment:delete', (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.commentId) {
+        void this.deleteComment(detail.commentId);
+      }
+    });
+
+    this.addEventHandler('mdview:comment:focus', (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.commentId && this.highlighter) {
+        this.highlighter.clearActive();
+        this.highlighter.setActive(detail.commentId);
+        const el = this.highlighter.getHighlightElement(detail.commentId);
+        if (el) {
+          el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        }
+      }
+    });
+
+    this.addEventHandler('mdview:comment:reply', (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.commentId) {
+        this.showReplyForm(detail.commentId);
+      }
+    });
+
+    this.addEventHandler('mdview:comment:react', (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.commentId && detail?.emoji) {
+        void this.toggleReaction(detail.commentId, detail.emoji);
+      }
+    });
+
+    this.addEventHandler('mdview:comment:reposition', () => {
+      this.repositionAllCards();
+    });
+
+    this.addEventHandler('mdview:comment:react:picker', (e: Event) => {
+      const detail = (e as CustomEvent).detail;
+      if (detail?.commentId) {
+        this.showEmojiPicker(detail.commentId, detail.anchor);
+      }
+    });
+
+    return result;
+  }
+
+  /**
+   * Handle an "add comment" request from the Chrome context menu.
+   * Captures current DOM selection context if available, shows the input form,
+   * and creates the comment on save.
+   */
+  handleAddCommentRequest(selectionText: string): void {
+    if (!this.ui) return;
+
+    // Remove any existing input form
+    document.querySelector('.mdview-comment-input')?.remove();
+
+    // Try to capture DOM context from current selection (may still be active)
+    const selection = window.getSelection();
+    if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
+      const range = selection.getRangeAt(0);
+      this.pendingContext = {
+        prefix: this.getTextBefore(range, 30),
+        suffix: this.getTextAfter(range, 30),
+      };
+    }
+
+    // Position form at selection if available, otherwise top of viewport
+    let top = window.scrollY + 100;
+    if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
+      const rect = selection.getRangeAt(0).getBoundingClientRect();
+      top = rect.top + window.scrollY;
+    }
+
+    const form = this.ui.renderInputForm(
+      (body: string, tags: CommentTag[]) => {
+        if (body.trim()) {
+          void this.addComment(selectionText, body, tags.length > 0 ? tags : undefined);
+        }
+        form.remove();
+      },
+      () => form.remove()
+    );
+
+    form.style.top = `${top}px`;
+    document.body.appendChild(form);
+
+    const textarea = form.querySelector('textarea');
+    if (textarea) textarea.focus();
+  }
+
+  /**
+   * Show the edit form for an existing comment, pre-populated with its body.
+   */
+  private showEditForm(commentId: string): void {
+    const comment = this.comments.find((c) => c.id === commentId);
+    if (!comment || !this.ui) return;
+
+    // Find the card and replace its body with an input form
+    const card = document.querySelector(
+      `.mdview-comment-card[data-comment-id="${commentId}"]`
+    );
+    if (!card) return;
+
+    // Expand the card if it's minimized so the edit form is visible
+    if (card.classList.contains('minimized')) {
+      card.classList.remove('minimized');
+      this.repositionAllCards();
+    }
+
+    const form = this.ui.renderInputForm(
+      (newBody: string, tags: CommentTag[]) => {
+        if (newBody.trim()) {
+          void this.editComment(commentId, newBody, tags);
+        }
+        // Restore the card body
+        form.remove();
+        const bodyEl = card.querySelector('.comment-body');
+        if (bodyEl) {
+          (bodyEl as HTMLElement).style.display = '';
+          bodyEl.textContent = newBody.trim() || comment.body;
+        }
+      },
+      () => {
+        form.remove();
+        const bodyEl = card.querySelector('.comment-body');
+        if (bodyEl) {
+          (bodyEl as HTMLElement).style.display = '';
+        }
+      },
+      comment.tags
+    );
+
+    // Pre-populate textarea
+    const textarea = form.querySelector('textarea');
+    if (textarea) {
+      (textarea as HTMLTextAreaElement).value = comment.body;
+    }
+
+    // Hide the card body and insert the form
+    const bodyEl = card.querySelector('.comment-body');
+    if (bodyEl) {
+      (bodyEl as HTMLElement).style.display = 'none';
+    }
+    card.appendChild(form);
+
+    // Focus the textarea
+    if (textarea) (textarea as HTMLTextAreaElement).focus();
+  }
+
+  /**
+   * Add a new comment attached to selected text.
+   */
+  async addComment(selectedText: string, body: string, tags?: CommentTag[]): Promise<void> {
+    const nextId = generateNextCommentId(this.rawMarkdown);
+
+    // Compute insertion offset for positional context
+    const offset = this.sourceMap
+      ? findInsertionPoint(this.sourceMap, selectedText, this.pendingContext ?? undefined)
+      : null;
+
+    // Compute positional context from the offset (or fallback to text search)
+    const contentSection = this.getContentSection();
+    const contextOffset = offset ?? contentSection.indexOf(selectedText);
+    const context = contextOffset >= 0
+      ? computeCommentContext(contentSection, contextOffset)
+      : undefined;
+
+    const comment: Comment = {
+      id: nextId,
+      selectedText,
+      body,
+      author: this.authorName,
+      date: new Date().toISOString(),
+      resolved: false,
+      context,
+      ...(tags && tags.length > 0 ? { tags } : {}),
+      ...(this.pendingContext?.prefix ? { anchorPrefix: this.pendingContext.prefix } : {}),
+      ...(this.pendingContext?.suffix ? { anchorSuffix: this.pendingContext.suffix } : {}),
+    };
+
+    // Serialize into markdown using source map for accurate placement
+    const updatedMarkdown = this.sourceMap
+      ? serializerAddCommentAtOffset(this.rawMarkdown, comment, this.sourceMap, this.pendingContext ?? undefined)
+      : serializerAddComment(this.rawMarkdown, comment);
+    this.pendingContext = null;
+
+    // Update internal state immediately (optimistic)
+    this.rawMarkdown = updatedMarkdown;
+    this.sourceMap = buildSourceMap(updatedMarkdown);
+    this.comments.push(comment);
+
+    // Patch DOM immediately (optimistic)
+    const container = document.getElementById('mdview-container') || document.body;
+    if (this.highlighter) {
+      this.highlighter.highlightComment(container, comment);
+    }
+
+    if (this.ui) {
+      const card = this.ui.renderCard(comment);
+      document.body.appendChild(card);
+      this.positionCardAtHighlight(card, comment.id);
+      this.repositionAllCards();
+    }
+
+    // Write to file via adapter (if available)
+    try {
+      await this.writeFile(updatedMarkdown);
+      if (this.ui) this.ui.showToast('Comment saved');
+    } catch (error) {
+      console.error('[MDView] Comment write failed:', error);
+      if (this.ui) this.ui.showToast(`Write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Edit the body of an existing comment.
+   */
+  async editComment(id: string, newBody: string, tags?: CommentTag[]): Promise<void> {
+    let updatedMarkdown = serializerUpdateComment(
+      this.rawMarkdown,
+      id,
+      newBody
+    );
+
+    // Update internal state immediately.
+    // No source map rebuild needed — edit only changes the comments section
+    // (below the separator), which the source map does not cover.
+    const comment = this.comments.find((c) => c.id === id);
+
+    // Persist tag changes to metadata if tags were explicitly provided and differ
+    if (comment && tags !== undefined) {
+      const oldTags = comment.tags ?? [];
+      const newTags = tags.length > 0 ? tags : [];
+      const tagsChanged =
+        oldTags.length !== newTags.length ||
+        oldTags.some((t, i) => t !== newTags[i]);
+
+      if (tagsChanged) {
+        updatedMarkdown = serializerUpdateCommentMetadata(
+          updatedMarkdown,
+          id,
+          (meta) => {
+            if (newTags.length > 0) {
+              meta.tags = newTags;
+            } else {
+              delete meta.tags;
+            }
+          }
+        );
+      }
+    }
+
+    this.rawMarkdown = updatedMarkdown;
+    if (comment) {
+      comment.body = newBody;
+      if (tags !== undefined) {
+        comment.tags = tags.length > 0 ? tags : undefined;
+      }
+    }
+
+    // Write to file
+    try {
+      await this.writeFile(updatedMarkdown);
+      if (this.ui) this.ui.showToast('Comment updated');
+    } catch {
+      if (this.ui) this.ui.showToast('Comment updated locally (file write failed)');
+    }
+  }
+
+  /**
+   * Mark a comment as resolved.
+   */
+  async resolveComment(id: string): Promise<void> {
+    const updatedMarkdown = serializerResolveComment(this.rawMarkdown, id);
+
+    // Update internal state immediately.
+    // No source map rebuild needed — resolve only changes metadata in the
+    // comments section (below the separator).
+    this.rawMarkdown = updatedMarkdown;
+    const comment = this.comments.find((c) => c.id === id);
+    if (comment) {
+      comment.resolved = true;
+    }
+
+    // Update highlight to resolved state immediately
+    if (this.highlighter) {
+      this.highlighter.setResolved(id);
+    }
+
+    // Write to file
+    try {
+      await this.writeFile(updatedMarkdown);
+    } catch {
+      if (this.ui) this.ui.showToast('Resolved locally (file write failed)');
+    }
+  }
+
+  /**
+   * Delete a comment entirely.
+   */
+  async deleteComment(id: string): Promise<void> {
+    const updatedMarkdown = serializerRemoveComment(this.rawMarkdown, id);
+
+    // Update internal state immediately
+    this.rawMarkdown = updatedMarkdown;
+    this.sourceMap = buildSourceMap(updatedMarkdown);
+    this.comments = this.comments.filter((c) => c.id !== id);
+
+    // Remove highlight from DOM immediately
+    if (this.highlighter) {
+      this.highlighter.removeHighlight(id);
+    }
+
+    // Remove card from DOM and reposition remaining cards
+    const card = document.querySelector(
+      `.mdview-comment-card[data-comment-id="${id}"]`
+    );
+    if (card) card.remove();
+    this.repositionAllCards();
+
+    // Write to file
+    try {
+      await this.writeFile(updatedMarkdown);
+    } catch {
+      if (this.ui) this.ui.showToast('Deleted locally (file write failed)');
+    }
+  }
+
+  /**
+   * Write content to the file via the FileAdapter.
+   * If no FileAdapter is configured, the write is silently skipped.
+   */
+  private async writeFile(content: string): Promise<void> {
+    if (!this.fileAdapter) {
+      // No file adapter — graceful degradation, skip write
+      return;
+    }
+
+    this.writeInProgress = true;
+    try {
+      const result = await this.fileAdapter.writeFile(this.filePath, content);
+
+      if (!result.success && result.error) {
+        throw new Error(result.error);
+      }
+    } finally {
+      // Keep the guard active for a grace period so the auto-reload watcher
+      // has time to see and ignore the file change event we just caused.
+      setTimeout(() => {
+        this.writeInProgress = false;
+      }, CommentManager.WRITE_GUARD_DELAY);
+    }
+  }
+
+  /**
+   * Whether a file write is currently in progress.
+   */
+  isWriteInProgress(): boolean {
+    return this.writeInProgress;
+  }
+
+  /**
+   * Return a shallow copy of the current comments array.
+   */
+  getComments(): Comment[] {
+    return [...this.comments];
+  }
+
+  /**
+   * Extract visible text preceding a Range from the DOM.
+   */
+  private getTextBefore(range: Range, maxChars: number): string {
+    const container = document.getElementById('mdview-container') || document.body;
+    const treeWalker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
+    const texts: string[] = [];
+
+    while (treeWalker.nextNode()) {
+      const node = treeWalker.currentNode as Text;
+      if (node === range.startContainer) {
+        texts.push(node.textContent?.slice(0, range.startOffset) ?? '');
+        break;
+      }
+      texts.push(node.textContent ?? '');
+    }
+
+    const fullText = texts.join('');
+    return fullText.slice(-maxChars);
+  }
+
+  /**
+   * Extract visible text following a Range from the DOM.
+   */
+  private getTextAfter(range: Range, maxChars: number): string {
+    const container = document.getElementById('mdview-container') || document.body;
+    const treeWalker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
+    const texts: string[] = [];
+    let started = false;
+
+    while (treeWalker.nextNode()) {
+      const node = treeWalker.currentNode as Text;
+      if (node === range.endContainer) {
+        texts.push(node.textContent?.slice(range.endOffset) ?? '');
+        started = true;
+        continue;
+      }
+      if (started) {
+        texts.push(node.textContent ?? '');
+      }
+    }
+
+    const fullText = texts.join('');
+    return fullText.slice(0, maxChars);
+  }
+
+  /**
+   * Add a reply to an existing comment.
+   */
+  async addReply(commentId: string, body: string): Promise<void> {
+    const reply = {
+      author: this.authorName,
+      body,
+      date: new Date().toISOString(),
+    };
+
+    const { markdown: updatedMarkdown, replyId } = serializerAddReply(
+      this.rawMarkdown,
+      commentId,
+      reply
+    );
+
+    // Update internal state
+    this.rawMarkdown = updatedMarkdown;
+    const comment = this.comments.find((c) => c.id === commentId);
+    if (comment) {
+      const replies = comment.replies ?? [];
+      replies.push({ id: replyId, ...reply });
+      comment.replies = replies;
+    }
+
+    // Refresh the card content
+    this.refreshCardContent(commentId);
+
+    // Write to file
+    try {
+      await this.writeFile(updatedMarkdown);
+      if (this.ui) this.ui.showToast('Reply saved');
+    } catch {
+      if (this.ui) this.ui.showToast('Reply saved locally (file write failed)');
+    }
+  }
+
+  /**
+   * Toggle an emoji reaction on a comment.
+   */
+  async toggleReaction(commentId: string, emoji: string): Promise<void> {
+    const updatedMarkdown = serializerToggleReaction(
+      this.rawMarkdown,
+      commentId,
+      emoji,
+      this.authorName
+    );
+
+    // Update internal state
+    this.rawMarkdown = updatedMarkdown;
+    const comment = this.comments.find((c) => c.id === commentId);
+    if (comment) {
+      const reactions = comment.reactions ?? {};
+      const authors = reactions[emoji] ?? [];
+      const idx = authors.indexOf(this.authorName);
+      if (idx >= 0) {
+        authors.splice(idx, 1);
+        if (authors.length === 0) {
+          delete reactions[emoji];
+        } else {
+          reactions[emoji] = authors;
+        }
+      } else {
+        reactions[emoji] = [...authors, this.authorName];
+      }
+
+      if (Object.keys(reactions).length > 0) {
+        comment.reactions = reactions;
+      } else {
+        delete comment.reactions;
+      }
+    }
+
+    // Refresh the card content
+    this.refreshCardContent(commentId);
+
+    // Write to file
+    try {
+      await this.writeFile(updatedMarkdown);
+    } catch {
+      if (this.ui) this.ui.showToast('Reaction saved locally (file write failed)');
+    }
+  }
+
+  /**
+   * Show a reply form in the comment card.
+   */
+  private showReplyForm(commentId: string): void {
+    if (!this.ui) return;
+
+    const card = document.querySelector(
+      `.mdview-comment-card[data-comment-id="${commentId}"]`
+    );
+    if (!card) return;
+
+    // Remove any existing reply form
+    card.querySelector('.comment-reply-form')?.remove();
+
+    const form = this.ui.renderReplyForm(
+      (body: string) => {
+        if (body.trim()) {
+          void this.addReply(commentId, body);
+        }
+        form.remove();
+      },
+      () => form.remove()
+    );
+
+    // Insert form before the reply button or reactions
+    const replyBtn = card.querySelector('.comment-reply-btn');
+    if (replyBtn) {
+      card.insertBefore(form, replyBtn);
+    } else {
+      card.appendChild(form);
+    }
+
+    const textarea = form.querySelector('textarea');
+    if (textarea) textarea.focus();
+  }
+
+  /**
+   * Show the emoji picker anchored to a button.
+   */
+  private showEmojiPicker(commentId: string, anchor?: HTMLElement): void {
+    if (!this.ui) return;
+
+    // Remove any existing picker
+    document.querySelector('.mdview-emoji-picker')?.remove();
+
+    const anchorEl = anchor || document.querySelector(
+      `.mdview-comment-card[data-comment-id="${commentId}"] .comment-reaction-add`
+    ) as HTMLElement;
+
+    if (!anchorEl) return;
+
+    const picker = this.ui.renderEmojiPicker(
+      anchorEl,
+      (emoji: string) => {
+        void this.toggleReaction(commentId, emoji);
+        picker.remove();
+      },
+      () => picker.remove()
+    );
+
+    // Position picker near the anchor
+    const card = anchorEl.closest('.mdview-comment-card');
+    if (card) {
+      card.appendChild(picker);
+    } else {
+      document.body.appendChild(picker);
+    }
+  }
+
+  /**
+   * Re-render the replies and reactions sections of an existing card
+   * without destroying the entire card.
+   */
+  private refreshCardContent(commentId: string): void {
+    if (!this.ui) return;
+
+    const comment = this.comments.find((c) => c.id === commentId);
+    if (!comment) return;
+
+    const oldCard = document.querySelector(
+      `.mdview-comment-card[data-comment-id="${commentId}"]`
+    );
+    if (!oldCard) return;
+
+    // Replace the card with a freshly rendered one, preserving position and minimized state
+    const topStyle = (oldCard as HTMLElement).style.top;
+    const wasMinimized = oldCard.classList.contains('minimized');
+    const newCard = this.ui.renderCard(comment);
+    newCard.style.top = topStyle;
+    if (!wasMinimized) {
+      newCard.classList.remove('minimized');
+    }
+    oldCard.replaceWith(newCard);
+  }
+
+  /**
+   * Clean up UI elements and event listeners.
+   */
+  destroy(): void {
+    if (this.ui) {
+      this.ui.destroy();
+      this.ui = null;
+    }
+
+    for (const { event, handler } of this.eventListeners) {
+      document.removeEventListener(event, handler);
+    }
+    this.eventListeners = [];
+
+    for (const { event, handler } of this.windowListeners) {
+      window.removeEventListener(event, handler);
+    }
+    this.windowListeners = [];
+
+    this.highlighter = null;
+    this.sourceMap = null;
+    this.pendingContext = null;
+    this.comments = [];
+
+    // Remove any floating cards/forms from DOM
+    document.querySelectorAll('.mdview-comment-card, .mdview-comment-input').forEach((el) => el.remove());
+  }
+
+  /**
+   * Extract the content section of markdown (above the comments separator).
+   */
+  private getContentSection(): string {
+    const v1 = this.rawMarkdown.indexOf('<!-- mdview:comments -->');
+    const v2 = this.rawMarkdown.indexOf('<!-- mdview:annotations');
+    const boundaries = [v1, v2].filter(i => i !== -1);
+    if (boundaries.length === 0) return this.rawMarkdown;
+    return this.rawMarkdown.slice(0, Math.min(...boundaries));
+  }
+
+  /**
+   * Position a comment card in the right margin, aligned with its highlight.
+   */
+  private positionCardAtHighlight(card: HTMLElement, commentId: string): void {
+    if (!this.highlighter) return;
+
+    const highlight = this.highlighter.getHighlightElement(commentId);
+    if (!highlight) return;
+
+    const rect = highlight.getBoundingClientRect();
+    const scrollTop = window.scrollY;
+    card.style.top = `${rect.top + scrollTop}px`;
+  }
+
+  /**
+   * Reposition all comment cards with cascade logic to prevent overlap.
+   * Cards are sorted by their highlight's vertical position and shifted
+   * down when they would overlap a previous card.
+   */
+  private repositionAllCards(): void {
+    if (!this.highlighter) return;
+
+    const GAP = 8;
+    const cards = Array.from(
+      document.querySelectorAll<HTMLElement>('.mdview-comment-card')
+    );
+
+    // Pair each card with its highlight's Y position
+    const entries: Array<{ card: HTMLElement; desiredTop: number }> = [];
+    for (const card of cards) {
+      const commentId = card.dataset.commentId;
+      if (!commentId) continue;
+
+      const highlight = this.highlighter.getHighlightElement(commentId);
+      if (!highlight) continue;
+
+      const rect = highlight.getBoundingClientRect();
+      entries.push({
+        card,
+        desiredTop: rect.top + window.scrollY,
+      });
+    }
+
+    // Sort by desired vertical position
+    entries.sort((a, b) => a.desiredTop - b.desiredTop);
+
+    // Cascade: push cards down when they'd overlap the previous card
+    let prevBottom = -Infinity;
+    for (const { card, desiredTop } of entries) {
+      const top = desiredTop < prevBottom + GAP
+        ? prevBottom + GAP
+        : desiredTop;
+      card.style.top = `${top}px`;
+      prevBottom = top + card.offsetHeight;
+    }
+  }
+
+  /**
+   * Register a DOM event listener and track it for cleanup.
+   */
+  private addEventHandler(event: string, handler: EventListener): void {
+    document.addEventListener(event, handler);
+    this.eventListeners.push({ event, handler });
+  }
+}
diff --git a/src/comments/comment-manager.ts b/src/comments/comment-manager.ts
index b4c9daf..7f30ff5 100644
--- a/src/comments/comment-manager.ts
+++ b/src/comments/comment-manager.ts
@@ -1,828 +1,94 @@
 /**
- * Comment Manager
+ * Comment Manager — Chrome extension shim
  *
- * CRUD orchestrator that connects the comment parser, serializer, UI,
- * text highlighter, and native host file-writing into a single cohesive
- * controller. All comment lifecycle operations flow through this class.
+ * Re-exports the core CommentManager from @mdview/core, pre-configured
+ * with Chrome extension adapters that delegate to chrome.runtime.sendMessage
+ * for file writes (WRITE_FILE) and username lookup (GET_USERNAME).
+ *
+ * This shim will be removed once the extension is fully migrated to core.
  */
 
-import type { Comment, CommentParseResult, AppState, CommentTag } from '../types';
-import { CommentUI } from './comment-ui';
-import { CommentHighlighter } from './comment-highlight';
-import { parseComments } from './annotation-parser';
 import {
-  addComment as serializerAddComment,
-  addCommentAtOffset as serializerAddCommentAtOffset,
-  removeComment as serializerRemoveComment,
-  updateComment as serializerUpdateComment,
-  updateCommentMetadata as serializerUpdateCommentMetadata,
-  resolveComment as serializerResolveComment,
-  addReply as serializerAddReply,
-  toggleReaction as serializerToggleReaction,
-  generateNextCommentId,
-} from './annotation-serializer';
-import { buildSourceMap, findInsertionPoint } from './source-position-map';
-import type { SourcePositionMap, SelectionContext } from './source-position-map';
-import { computeCommentContext } from './comment-context';
-
-export class CommentManager {
-  private comments: Comment[] = [];
-  private rawMarkdown: string = '';
-  private filePath: string = '';
-  private writeInProgress = false;
-  private ui: CommentUI | null = null;
-  private highlighter: CommentHighlighter | null = null;
-  private authorName: string = '';
-  private sourceMap: SourcePositionMap | null = null;
-  private pendingContext: SelectionContext | null = null;
-
-  private windowListeners: Array<{
-    event: string;
-    handler: EventListener;
-  }> = [];
-
-  private eventListeners: Array<{
-    event: string;
-    handler: EventListener;
-  }> = [];
-
-  /** Grace period (ms) after native write before clearing writeInProgress.
-   *  Must exceed file-watcher poll interval (1000ms) + debounce (500ms)
-   *  to prevent the auto-reload from triggering on our own write. */
-  private static readonly WRITE_GUARD_DELAY = 2000;
-
-  /**
-   * Parse existing comments from raw markdown, set up UI and highlights,
-   * and wire event listeners for user actions.
-   */
-  async initialize(
-    markdown: string,
-    filePath: string,
-    preferences: AppState['preferences']
-  ): Promise<CommentParseResult> {
-    this.rawMarkdown = markdown;
-    this.filePath = filePath;
-    this.authorName = preferences.commentAuthor ?? '';
-
-    // If no author configured, try to get system username from native host
-    if (!this.authorName) {
-      try {
-        const resp = await chrome.runtime.sendMessage({ type: 'GET_USERNAME' }) as
-          { username?: string } | undefined;
-        if (resp?.username) {
-          this.authorName = resp.username;
-        }
-      } catch {
-        // Native host may not be installed — leave author empty
-      }
-    }
-
-    // Build source position map for accurate comment insertion
-    this.sourceMap = buildSourceMap(markdown);
-
-    // Parse existing comments
-    const result = parseComments(markdown);
-    this.comments = [...result.comments];
-
-    // Set up UI
-    this.ui = new CommentUI();
-    this.ui.setCurrentAuthor(this.authorName);
-
-    // Set up highlighter - highlight text first, then position cards
-    this.highlighter = new CommentHighlighter();
-    const container = document.getElementById('mdview-container') || document.body;
-    for (const comment of this.comments) {
-      this.highlighter.highlightComment(container, comment);
-    }
-
-    // Render cards and position them next to their highlights
-    for (const comment of this.comments) {
-      const card = this.ui.renderCard(comment);
-      document.body.appendChild(card);
-      this.positionCardAtHighlight(card, comment.id);
-    }
-
-    // Apply cascade layout to prevent card overlap
-    this.repositionAllCards();
-
-    // Re-position cards on window resize (debounced)
-    let resizeTimer: ReturnType<typeof setTimeout> | null = null;
-    const resizeHandler = () => {
-      if (resizeTimer) clearTimeout(resizeTimer);
-      resizeTimer = setTimeout(() => this.repositionAllCards(), 150);
-    };
-    window.addEventListener('resize', resizeHandler);
-    this.windowListeners.push({ event: 'resize', handler: resizeHandler as EventListener });
-
-    // Wire up custom DOM event listeners
-    this.addEventHandler('mdview:comment:edit', (e: Event) => {
-      const detail = (e as CustomEvent).detail;
-      if (detail?.commentId) {
-        this.showEditForm(detail.commentId);
-      }
-    });
-
-    this.addEventHandler('mdview:comment:resolve', (e: Event) => {
-      const detail = (e as CustomEvent).detail;
-      if (detail?.commentId) {
-        void this.resolveComment(detail.commentId);
-      }
-    });
-
-    this.addEventHandler('mdview:comment:delete', (e: Event) => {
-      const detail = (e as CustomEvent).detail;
-      if (detail?.commentId) {
-        void this.deleteComment(detail.commentId);
-      }
-    });
+  CommentManager as CoreCommentManager,
+  type CommentManagerAdapters,
+} from '../../packages/core/src/comments/comment-manager';
+import type {
+  FileAdapter,
+  IdentityAdapter,
+  FileWriteResult,
+  FileChangeInfo,
+} from '../../packages/core/src/adapters';
 
-    this.addEventHandler('mdview:comment:focus', (e: Event) => {
-      const detail = (e as CustomEvent).detail;
-      if (detail?.commentId && this.highlighter) {
-        this.highlighter.clearActive();
-        this.highlighter.setActive(detail.commentId);
-        const el = this.highlighter.getHighlightElement(detail.commentId);
-        if (el) {
-          el.scrollIntoView({ behavior: 'smooth', block: 'center' });
-        }
-      }
-    });
-
-    this.addEventHandler('mdview:comment:reply', (e: Event) => {
-      const detail = (e as CustomEvent).detail;
-      if (detail?.commentId) {
-        this.showReplyForm(detail.commentId);
-      }
-    });
-
-    this.addEventHandler('mdview:comment:react', (e: Event) => {
-      const detail = (e as CustomEvent).detail;
-      if (detail?.commentId && detail?.emoji) {
-        void this.toggleReaction(detail.commentId, detail.emoji);
-      }
-    });
-
-    this.addEventHandler('mdview:comment:reposition', () => {
-      this.repositionAllCards();
-    });
+/**
+ * Type-safe helper to send a Chrome runtime message and parse the response.
+ */
+async function sendChromeMessage<T>(message: Record<string, unknown>): Promise<T | undefined> {
+  const result: unknown = await chrome.runtime.sendMessage(message);
+  return result as T | undefined;
+}
 
-    this.addEventHandler('mdview:comment:react:picker', (e: Event) => {
-      const detail = (e as CustomEvent).detail;
-      if (detail?.commentId) {
-        this.showEmojiPicker(detail.commentId, detail.anchor);
-      }
+/**
+ * Chrome extension FileAdapter — delegates to the service worker
+ * via chrome.runtime.sendMessage({ type: 'WRITE_FILE', ... }).
+ */
+class ChromeFileAdapter implements FileAdapter {
+  async writeFile(path: string, content: string): Promise<FileWriteResult> {
+    const response = await sendChromeMessage<{ success?: boolean; error?: string }>({
+      type: 'WRITE_FILE',
+      payload: { path, content },
     });
 
-    return result;
-  }
-
-  /**
-   * Handle an "add comment" request from the Chrome context menu.
-   * Captures current DOM selection context if available, shows the input form,
-   * and creates the comment on save.
-   */
-  handleAddCommentRequest(selectionText: string): void {
-    if (!this.ui) return;
-
-    // Remove any existing input form
-    document.querySelector('.mdview-comment-input')?.remove();
-
-    // Try to capture DOM context from current selection (may still be active)
-    const selection = window.getSelection();
-    if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
-      const range = selection.getRangeAt(0);
-      this.pendingContext = {
-        prefix: this.getTextBefore(range, 30),
-        suffix: this.getTextAfter(range, 30),
-      };
-    }
-
-    // Position form at selection if available, otherwise top of viewport
-    let top = window.scrollY + 100;
-    if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
-      const rect = selection.getRangeAt(0).getBoundingClientRect();
-      top = rect.top + window.scrollY;
+    if (response?.error) {
+      return { success: false, error: response.error };
     }
-
-    const form = this.ui.renderInputForm(
-      (body: string, tags: CommentTag[]) => {
-        if (body.trim()) {
-          void this.addComment(selectionText, body, tags.length > 0 ? tags : undefined);
-        }
-        form.remove();
-      },
-      () => form.remove()
-    );
-
-    form.style.top = `${top}px`;
-    document.body.appendChild(form);
-
-    const textarea = form.querySelector('textarea');
-    if (textarea) textarea.focus();
+    return { success: true };
   }
 
-  /**
-   * Show the edit form for an existing comment, pre-populated with its body.
-   */
-  private showEditForm(commentId: string): void {
-    const comment = this.comments.find((c) => c.id === commentId);
-    if (!comment || !this.ui) return;
-
-    // Find the card and replace its body with an input form
-    const card = document.querySelector(
-      `.mdview-comment-card[data-comment-id="${commentId}"]`
-    );
-    if (!card) return;
-
-    // Expand the card if it's minimized so the edit form is visible
-    if (card.classList.contains('minimized')) {
-      card.classList.remove('minimized');
-      this.repositionAllCards();
-    }
-
-    const form = this.ui.renderInputForm(
-      (newBody: string, tags: CommentTag[]) => {
-        if (newBody.trim()) {
-          void this.editComment(commentId, newBody, tags);
-        }
-        // Restore the card body
-        form.remove();
-        const bodyEl = card.querySelector('.comment-body');
-        if (bodyEl) {
-          (bodyEl as HTMLElement).style.display = '';
-          bodyEl.textContent = newBody.trim() || comment.body;
-        }
-      },
-      () => {
-        form.remove();
-        const bodyEl = card.querySelector('.comment-body');
-        if (bodyEl) {
-          (bodyEl as HTMLElement).style.display = '';
-        }
-      },
-      comment.tags
-    );
-
-    // Pre-populate textarea
-    const textarea = form.querySelector('textarea');
-    if (textarea) {
-      (textarea as HTMLTextAreaElement).value = comment.body;
-    }
-
-    // Hide the card body and insert the form
-    const bodyEl = card.querySelector('.comment-body');
-    if (bodyEl) {
-      (bodyEl as HTMLElement).style.display = 'none';
-    }
-    card.appendChild(form);
-
-    // Focus the textarea
-    if (textarea) (textarea as HTMLTextAreaElement).focus();
+  readFile(_path: string): Promise<string> {
+    return Promise.reject(new Error('readFile not supported via Chrome messaging'));
   }
 
-  /**
-   * Add a new comment attached to selected text.
-   */
-  async addComment(selectedText: string, body: string, tags?: CommentTag[]): Promise<void> {
-    const nextId = generateNextCommentId(this.rawMarkdown);
-
-    // Compute insertion offset for positional context
-    const offset = this.sourceMap
-      ? findInsertionPoint(this.sourceMap, selectedText, this.pendingContext ?? undefined)
-      : null;
-
-    // Compute positional context from the offset (or fallback to text search)
-    const contentSection = this.getContentSection();
-    const contextOffset = offset ?? contentSection.indexOf(selectedText);
-    const context = contextOffset >= 0
-      ? computeCommentContext(contentSection, contextOffset)
-      : undefined;
-
-    const comment: Comment = {
-      id: nextId,
-      selectedText,
-      body,
-      author: this.authorName,
-      date: new Date().toISOString(),
-      resolved: false,
-      context,
-      ...(tags && tags.length > 0 ? { tags } : {}),
-      ...(this.pendingContext?.prefix ? { anchorPrefix: this.pendingContext.prefix } : {}),
-      ...(this.pendingContext?.suffix ? { anchorSuffix: this.pendingContext.suffix } : {}),
-    };
-
-    // Serialize into markdown using source map for accurate placement
-    const updatedMarkdown = this.sourceMap
-      ? serializerAddCommentAtOffset(this.rawMarkdown, comment, this.sourceMap, this.pendingContext ?? undefined)
-      : serializerAddComment(this.rawMarkdown, comment);
-    this.pendingContext = null;
-
-    // Update internal state immediately (optimistic)
-    this.rawMarkdown = updatedMarkdown;
-    this.sourceMap = buildSourceMap(updatedMarkdown);
-    this.comments.push(comment);
-
-    // Patch DOM immediately (optimistic)
-    const container = document.getElementById('mdview-container') || document.body;
-    if (this.highlighter) {
-      this.highlighter.highlightComment(container, comment);
-    }
-
-    if (this.ui) {
-      const card = this.ui.renderCard(comment);
-      document.body.appendChild(card);
-      this.positionCardAtHighlight(card, comment.id);
-      this.repositionAllCards();
-    }
-
-    // Write to file in the background
-    try {
-      await this.writeFile(updatedMarkdown);
-      if (this.ui) this.ui.showToast('Comment saved');
-    } catch (error) {
-      console.error('[MDView] Comment write failed:', error);
-      if (this.ui) this.ui.showToast(`Write failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  /**
-   * Edit the body of an existing comment.
-   */
-  async editComment(id: string, newBody: string, tags?: CommentTag[]): Promise<void> {
-    let updatedMarkdown = serializerUpdateComment(
-      this.rawMarkdown,
-      id,
-      newBody
-    );
-
-    // Update internal state immediately.
-    // No source map rebuild needed — edit only changes the comments section
-    // (below the separator), which the source map does not cover.
-    const comment = this.comments.find((c) => c.id === id);
-
-    // Persist tag changes to metadata if tags were explicitly provided and differ
-    if (comment && tags !== undefined) {
-      const oldTags = comment.tags ?? [];
-      const newTags = tags.length > 0 ? tags : [];
-      const tagsChanged =
-        oldTags.length !== newTags.length ||
-        oldTags.some((t, i) => t !== newTags[i]);
-
-      if (tagsChanged) {
-        updatedMarkdown = serializerUpdateCommentMetadata(
-          updatedMarkdown,
-          id,
-          (meta) => {
-            if (newTags.length > 0) {
-              meta.tags = newTags;
-            } else {
-              delete meta.tags;
-            }
-          }
-        );
-      }
-    }
-
-    this.rawMarkdown = updatedMarkdown;
-    if (comment) {
-      comment.body = newBody;
-      if (tags !== undefined) {
-        comment.tags = tags.length > 0 ? tags : undefined;
-      }
-    }
-
-    // Write to file
-    try {
-      await this.writeFile(updatedMarkdown);
-      if (this.ui) this.ui.showToast('Comment updated');
-    } catch {
-      if (this.ui) this.ui.showToast('Comment updated locally (file write failed)');
-    }
+  checkChanged(_url: string, _lastHash: string): Promise<FileChangeInfo> {
+    return Promise.resolve({ changed: false });
   }
 
-  /**
-   * Mark a comment as resolved.
-   */
-  async resolveComment(id: string): Promise<void> {
-    const updatedMarkdown = serializerResolveComment(this.rawMarkdown, id);
-
-    // Update internal state immediately.
-    // No source map rebuild needed — resolve only changes metadata in the
-    // comments section (below the separator).
-    this.rawMarkdown = updatedMarkdown;
-    const comment = this.comments.find((c) => c.id === id);
-    if (comment) {
-      comment.resolved = true;
-    }
-
-    // Update highlight to resolved state immediately
-    if (this.highlighter) {
-      this.highlighter.setResolved(id);
-    }
-
-    // Write to file
-    try {
-      await this.writeFile(updatedMarkdown);
-    } catch {
-      if (this.ui) this.ui.showToast('Resolved locally (file write failed)');
-    }
+  watch(_path: string, _callback: () => void): () => void {
+    return () => {};
   }
+}
 
-  /**
-   * Delete a comment entirely.
-   */
-  async deleteComment(id: string): Promise<void> {
-    const updatedMarkdown = serializerRemoveComment(this.rawMarkdown, id);
-
-    // Update internal state immediately
-    this.rawMarkdown = updatedMarkdown;
-    this.sourceMap = buildSourceMap(updatedMarkdown);
-    this.comments = this.comments.filter((c) => c.id !== id);
-
-    // Remove highlight from DOM immediately
-    if (this.highlighter) {
-      this.highlighter.removeHighlight(id);
-    }
-
-    // Remove card from DOM and reposition remaining cards
-    const card = document.querySelector(
-      `.mdview-comment-card[data-comment-id="${id}"]`
-    );
-    if (card) card.remove();
-    this.repositionAllCards();
-
-    // Write to file
+/**
+ * Chrome extension IdentityAdapter — delegates to the native host
+ * via chrome.runtime.sendMessage({ type: 'GET_USERNAME' }).
+ */
+class ChromeIdentityAdapter implements IdentityAdapter {
+  async getUsername(): Promise<string> {
     try {
-      await this.writeFile(updatedMarkdown);
+      const resp = await sendChromeMessage<{ username?: string }>({
+        type: 'GET_USERNAME',
+      });
+      return resp?.username ?? '';
     } catch {
-      if (this.ui) this.ui.showToast('Deleted locally (file write failed)');
-    }
-  }
-
-  /**
-   * Write content to the file via the native messaging host.
-   */
-  private async writeFile(content: string): Promise<void> {
-    this.writeInProgress = true;
-    try {
-      // Relay through service worker since content scripts can't use sendNativeMessage
-      const response = await chrome.runtime.sendMessage({
-        type: 'WRITE_FILE',
-        payload: { path: this.filePath, content },
-      }) as { success?: boolean; error?: string };
-
-      if (response?.error) {
-        throw new Error(response.error);
-      }
-    } finally {
-      // Keep the guard active for a grace period so the auto-reload watcher
-      // has time to see and ignore the file change event we just caused.
-      setTimeout(() => {
-        this.writeInProgress = false;
-      }, CommentManager.WRITE_GUARD_DELAY);
-    }
-  }
-
-  /**
-   * Whether a file write is currently in progress.
-   */
-  isWriteInProgress(): boolean {
-    return this.writeInProgress;
-  }
-
-  /**
-   * Return a shallow copy of the current comments array.
-   */
-  getComments(): Comment[] {
-    return [...this.comments];
-  }
-
-  /**
-   * Extract visible text preceding a Range from the DOM.
-   */
-  private getTextBefore(range: Range, maxChars: number): string {
-    const container = document.getElementById('mdview-container') || document.body;
-    const treeWalker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
-    const texts: string[] = [];
-
-    while (treeWalker.nextNode()) {
-      const node = treeWalker.currentNode as Text;
-      if (node === range.startContainer) {
-        texts.push(node.textContent?.slice(0, range.startOffset) ?? '');
-        break;
-      }
-      texts.push(node.textContent ?? '');
-    }
-
-    const fullText = texts.join('');
-    return fullText.slice(-maxChars);
-  }
-
-  /**
-   * Extract visible text following a Range from the DOM.
-   */
-  private getTextAfter(range: Range, maxChars: number): string {
-    const container = document.getElementById('mdview-container') || document.body;
-    const treeWalker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
-    const texts: string[] = [];
-    let started = false;
-
-    while (treeWalker.nextNode()) {
-      const node = treeWalker.currentNode as Text;
-      if (node === range.endContainer) {
-        texts.push(node.textContent?.slice(range.endOffset) ?? '');
-        started = true;
-        continue;
-      }
-      if (started) {
-        texts.push(node.textContent ?? '');
-      }
+      // Native host may not be installed
+      return '';
     }
-
-    const fullText = texts.join('');
-    return fullText.slice(0, maxChars);
   }
+}
 
-  /**
-   * Add a reply to an existing comment.
-   */
-  async addReply(commentId: string, body: string): Promise<void> {
-    const reply = {
-      author: this.authorName,
-      body,
-      date: new Date().toISOString(),
+/**
+ * CommentManager pre-configured with Chrome extension adapters.
+ * Drop-in replacement for the previous monolithic CommentManager.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class CommentManager extends CoreCommentManager {
+  constructor(adapters?: CommentManagerAdapters) {
+    // If no adapters provided, use Chrome-backed defaults
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const resolved: CommentManagerAdapters = adapters ?? {
+      file: new ChromeFileAdapter(),
+      identity: new ChromeIdentityAdapter(),
     };
-
-    const { markdown: updatedMarkdown, replyId } = serializerAddReply(
-      this.rawMarkdown,
-      commentId,
-      reply
-    );
-
-    // Update internal state
-    this.rawMarkdown = updatedMarkdown;
-    const comment = this.comments.find((c) => c.id === commentId);
-    if (comment) {
-      const replies = comment.replies ?? [];
-      replies.push({ id: replyId, ...reply });
-      comment.replies = replies;
-    }
-
-    // Refresh the card content
-    this.refreshCardContent(commentId);
-
-    // Write to file
-    try {
-      await this.writeFile(updatedMarkdown);
-      if (this.ui) this.ui.showToast('Reply saved');
-    } catch {
-      if (this.ui) this.ui.showToast('Reply saved locally (file write failed)');
-    }
-  }
-
-  /**
-   * Toggle an emoji reaction on a comment.
-   */
-  async toggleReaction(commentId: string, emoji: string): Promise<void> {
-    const updatedMarkdown = serializerToggleReaction(
-      this.rawMarkdown,
-      commentId,
-      emoji,
-      this.authorName
-    );
-
-    // Update internal state
-    this.rawMarkdown = updatedMarkdown;
-    const comment = this.comments.find((c) => c.id === commentId);
-    if (comment) {
-      const reactions = comment.reactions ?? {};
-      const authors = reactions[emoji] ?? [];
-      const idx = authors.indexOf(this.authorName);
-      if (idx >= 0) {
-        authors.splice(idx, 1);
-        if (authors.length === 0) {
-          delete reactions[emoji];
-        } else {
-          reactions[emoji] = authors;
-        }
-      } else {
-        reactions[emoji] = [...authors, this.authorName];
-      }
-
-      if (Object.keys(reactions).length > 0) {
-        comment.reactions = reactions;
-      } else {
-        delete comment.reactions;
-      }
-    }
-
-    // Refresh the card content
-    this.refreshCardContent(commentId);
-
-    // Write to file
-    try {
-      await this.writeFile(updatedMarkdown);
-    } catch {
-      if (this.ui) this.ui.showToast('Reaction saved locally (file write failed)');
-    }
-  }
-
-  /**
-   * Show a reply form in the comment card.
-   */
-  private showReplyForm(commentId: string): void {
-    if (!this.ui) return;
-
-    const card = document.querySelector(
-      `.mdview-comment-card[data-comment-id="${commentId}"]`
-    );
-    if (!card) return;
-
-    // Remove any existing reply form
-    card.querySelector('.comment-reply-form')?.remove();
-
-    const form = this.ui.renderReplyForm(
-      (body: string) => {
-        if (body.trim()) {
-          void this.addReply(commentId, body);
-        }
-        form.remove();
-      },
-      () => form.remove()
-    );
-
-    // Insert form before the reply button or reactions
-    const replyBtn = card.querySelector('.comment-reply-btn');
-    if (replyBtn) {
-      card.insertBefore(form, replyBtn);
-    } else {
-      card.appendChild(form);
-    }
-
-    const textarea = form.querySelector('textarea');
-    if (textarea) textarea.focus();
-  }
-
-  /**
-   * Show the emoji picker anchored to a button.
-   */
-  private showEmojiPicker(commentId: string, anchor?: HTMLElement): void {
-    if (!this.ui) return;
-
-    // Remove any existing picker
-    document.querySelector('.mdview-emoji-picker')?.remove();
-
-    const anchorEl = anchor || document.querySelector(
-      `.mdview-comment-card[data-comment-id="${commentId}"] .comment-reaction-add`
-    ) as HTMLElement;
-
-    if (!anchorEl) return;
-
-    const picker = this.ui.renderEmojiPicker(
-      anchorEl,
-      (emoji: string) => {
-        void this.toggleReaction(commentId, emoji);
-        picker.remove();
-      },
-      () => picker.remove()
-    );
-
-    // Position picker near the anchor
-    const card = anchorEl.closest('.mdview-comment-card');
-    if (card) {
-      card.appendChild(picker);
-    } else {
-      document.body.appendChild(picker);
-    }
-  }
-
-  /**
-   * Re-render the replies and reactions sections of an existing card
-   * without destroying the entire card.
-   */
-  private refreshCardContent(commentId: string): void {
-    if (!this.ui) return;
-
-    const comment = this.comments.find((c) => c.id === commentId);
-    if (!comment) return;
-
-    const oldCard = document.querySelector(
-      `.mdview-comment-card[data-comment-id="${commentId}"]`
-    );
-    if (!oldCard) return;
-
-    // Replace the card with a freshly rendered one, preserving position and minimized state
-    const topStyle = (oldCard as HTMLElement).style.top;
-    const wasMinimized = oldCard.classList.contains('minimized');
-    const newCard = this.ui.renderCard(comment);
-    newCard.style.top = topStyle;
-    if (!wasMinimized) {
-      newCard.classList.remove('minimized');
-    }
-    oldCard.replaceWith(newCard);
-  }
-
-  /**
-   * Clean up UI elements and event listeners.
-   */
-  destroy(): void {
-    if (this.ui) {
-      this.ui.destroy();
-      this.ui = null;
-    }
-
-    for (const { event, handler } of this.eventListeners) {
-      document.removeEventListener(event, handler);
-    }
-    this.eventListeners = [];
-
-    for (const { event, handler } of this.windowListeners) {
-      window.removeEventListener(event, handler);
-    }
-    this.windowListeners = [];
-
-    this.highlighter = null;
-    this.sourceMap = null;
-    this.pendingContext = null;
-    this.comments = [];
-
-    // Remove any floating cards/forms from DOM
-    document.querySelectorAll('.mdview-comment-card, .mdview-comment-input').forEach((el) => el.remove());
-  }
-
-  /**
-   * Extract the content section of markdown (above the comments separator).
-   */
-  private getContentSection(): string {
-    const v1 = this.rawMarkdown.indexOf('<!-- mdview:comments -->');
-    const v2 = this.rawMarkdown.indexOf('<!-- mdview:annotations');
-    const boundaries = [v1, v2].filter(i => i !== -1);
-    if (boundaries.length === 0) return this.rawMarkdown;
-    return this.rawMarkdown.slice(0, Math.min(...boundaries));
-  }
-
-  /**
-   * Position a comment card in the right margin, aligned with its highlight.
-   */
-  private positionCardAtHighlight(card: HTMLElement, commentId: string): void {
-    if (!this.highlighter) return;
-
-    const highlight = this.highlighter.getHighlightElement(commentId);
-    if (!highlight) return;
-
-    const rect = highlight.getBoundingClientRect();
-    const scrollTop = window.scrollY;
-    card.style.top = `${rect.top + scrollTop}px`;
-  }
-
-  /**
-   * Reposition all comment cards with cascade logic to prevent overlap.
-   * Cards are sorted by their highlight's vertical position and shifted
-   * down when they would overlap a previous card.
-   */
-  private repositionAllCards(): void {
-    if (!this.highlighter) return;
-
-    const GAP = 8;
-    const cards = Array.from(
-      document.querySelectorAll<HTMLElement>('.mdview-comment-card')
-    );
-
-    // Pair each card with its highlight's Y position
-    const entries: Array<{ card: HTMLElement; desiredTop: number }> = [];
-    for (const card of cards) {
-      const commentId = card.dataset.commentId;
-      if (!commentId) continue;
-
-      const highlight = this.highlighter.getHighlightElement(commentId);
-      if (!highlight) continue;
-
-      const rect = highlight.getBoundingClientRect();
-      entries.push({
-        card,
-        desiredTop: rect.top + window.scrollY,
-      });
-    }
-
-    // Sort by desired vertical position
-    entries.sort((a, b) => a.desiredTop - b.desiredTop);
-
-    // Cascade: push cards down when they'd overlap the previous card
-    let prevBottom = -Infinity;
-    for (const { card, desiredTop } of entries) {
-      const top = desiredTop < prevBottom + GAP
-        ? prevBottom + GAP
-        : desiredTop;
-      card.style.top = `${top}px`;
-      prevBottom = top + card.offsetHeight;
-    }
-  }
-
-  /**
-   * Register a DOM event listener and track it for cleanup.
-   */
-  private addEventHandler(event: string, handler: EventListener): void {
-    document.addEventListener(event, handler);
-    this.eventListeners.push({ event, handler });
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    super(resolved);
   }
 }

From 341982f7d5648984fc3e6f479931941ed4694ff1 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 09:06:56 -0400
Subject: [PATCH 18/26] refactor(core): move DOM utilities to @mdview/core

Move dom-purifier, skeleton-renderer, and scroll-manager to
packages/core/src/utils/ and replace originals with re-export shims.
Update render-pipeline and its test to use local imports. Add dompurify
dependency to @mdview/core package.json.
---
 packages/core/package.json                    |   2 +
 .../src/__tests__/render-pipeline.test.ts     |   4 +-
 packages/core/src/index.ts                    |  11 ++
 packages/core/src/render-pipeline.ts          |   4 +-
 packages/core/src/utils/dom-purifier.ts       | 166 ++++++++++++++++
 packages/core/src/utils/scroll-manager.ts     | 180 ++++++++++++++++++
 packages/core/src/utils/skeleton-renderer.ts  | 103 ++++++++++
 src/utils/dom-purifier.ts                     | 167 +---------------
 src/utils/scroll-manager.ts                   | 179 +----------------
 src/utils/skeleton-renderer.ts                | 102 +---------
 10 files changed, 469 insertions(+), 449 deletions(-)
 create mode 100644 packages/core/src/utils/dom-purifier.ts
 create mode 100644 packages/core/src/utils/scroll-manager.ts
 create mode 100644 packages/core/src/utils/skeleton-renderer.ts

diff --git a/packages/core/package.json b/packages/core/package.json
index 76b41f9..ad49e88 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -13,6 +13,7 @@
     "test:ci": "vitest --run"
   },
   "dependencies": {
+    "dompurify": "^3.0.6",
     "markdown-it": "^14.1.0",
     "markdown-it-anchor": "^8.6.7",
     "markdown-it-attrs": "^4.1.6",
@@ -21,6 +22,7 @@
     "markdown-it-task-lists": "^2.1.1"
   },
   "devDependencies": {
+    "@types/dompurify": "^3.0.5",
     "@types/markdown-it": "^13.0.9"
   },
   "author": "James Ainslie",
diff --git a/packages/core/src/__tests__/render-pipeline.test.ts b/packages/core/src/__tests__/render-pipeline.test.ts
index 79d387e..b9951be 100644
--- a/packages/core/src/__tests__/render-pipeline.test.ts
+++ b/packages/core/src/__tests__/render-pipeline.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { MessagingAdapter, IPCMessage } from '../adapters';
 
 // Mock heavy dependencies that live outside @mdview/core
-vi.mock('../../../../src/utils/dom-purifier', () => ({
+vi.mock('../utils/dom-purifier', () => ({
   domPurifier: {
     sanitize: (html: string) => html,
   },
@@ -38,7 +38,7 @@ vi.mock('../../../../src/comments/annotation-parser', () => ({
   })),
 }));
 
-vi.mock('../../../../src/utils/skeleton-renderer', () => ({
+vi.mock('../utils/skeleton-renderer', () => ({
   SkeletonRenderer: {
     generateSkeleton: vi.fn(() => '<div>skeleton</div>'),
     isHydrated: vi.fn(() => false),
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 6b13168..419a445 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -44,6 +44,10 @@ export * from './utils/filename-generator';
 export * from './utils/toc-stripper';
 export { FileScanner } from './utils/file-scanner';
 export type { WatchFileOptions } from './utils/file-scanner';
+export { DOMPurifierUtil, domPurifier } from './utils/dom-purifier';
+export { SkeletonRenderer } from './utils/skeleton-renderer';
+export type { SkeletonSection } from './utils/skeleton-renderer';
+export { ScrollManager } from './utils/scroll-manager';
 
 // Markdown converter
 export { MarkdownConverter, markdownConverter } from './markdown-converter';
@@ -71,3 +75,10 @@ export type { RenderOptions, RenderProgress, ProgressCallback, RenderPipelineOpt
 
 // Platform adapters
 export * from './adapters';
+
+// Workers
+export { WorkerPool, workerPool } from './workers/worker-pool';
+export type { WorkerPoolOptions } from './workers/worker-pool';
+export { handleParseTask } from './workers/tasks/parse-task';
+export { handleHighlightTask } from './workers/tasks/highlight-task';
+export { handleMermaidTask } from './workers/tasks/mermaid-task';
diff --git a/packages/core/src/render-pipeline.ts b/packages/core/src/render-pipeline.ts
index 19f27ed..27430a1 100644
--- a/packages/core/src/render-pipeline.ts
+++ b/packages/core/src/render-pipeline.ts
@@ -8,7 +8,7 @@
 
 import { MarkdownConverter } from './markdown-converter';
 import { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extractor';
-import { domPurifier } from '../../../src/utils/dom-purifier';
+import { domPurifier } from './utils/dom-purifier';
 import { workerPool } from '../../../src/workers/worker-pool';
 import type {
   ConversionResult,
@@ -18,7 +18,7 @@ import type {
   CommentParseResult,
 } from './types/index';
 import { splitIntoSections } from './utils/section-splitter';
-import { SkeletonRenderer } from '../../../src/utils/skeleton-renderer';
+import { SkeletonRenderer } from './utils/skeleton-renderer';
 import type { MessagingAdapter } from './adapters';
 
 // ---------------------------------------------------------------------------
diff --git a/packages/core/src/utils/dom-purifier.ts b/packages/core/src/utils/dom-purifier.ts
new file mode 100644
index 0000000..905a9cb
--- /dev/null
+++ b/packages/core/src/utils/dom-purifier.ts
@@ -0,0 +1,166 @@
+/**
+ * DOM Purifier Utility
+ * Sanitizes HTML content using DOMPurify for security
+ */
+
+import DOMPurify from 'dompurify';
+
+export class DOMPurifierUtil {
+  private static config = {
+    ALLOWED_TAGS: [
+      'p',
+      'br',
+      'strong',
+      'em',
+      'u',
+      's',
+      'code',
+      'pre',
+      'h1',
+      'h2',
+      'h3',
+      'h4',
+      'h5',
+      'h6',
+      'ul',
+      'ol',
+      'li',
+      'dl',
+      'dt',
+      'dd',
+      'a',
+      'img',
+      'blockquote',
+      'hr',
+      'div',
+      'span',
+      'table',
+      'thead',
+      'tbody',
+      'tfoot',
+      'tr',
+      'th',
+      'td',
+      'svg',
+      'path',
+      'circle',
+      'rect',
+      'line',
+      'polyline',
+      'polygon',
+      'g',
+      'text',
+      'defs',
+      'marker',
+      'input',
+      'label',
+      'details',
+      'summary',
+    ],
+    ALLOWED_ATTR: [
+      'href',
+      'src',
+      'alt',
+      'title',
+      'class',
+      'id',
+      'width',
+      'height',
+      'target',
+      'rel',
+      // SVG attributes
+      'd',
+      'cx',
+      'cy',
+      'r',
+      'x',
+      'y',
+      'x1',
+      'y1',
+      'x2',
+      'y2',
+      'viewBox',
+      'fill',
+      'stroke',
+      'stroke-width',
+      'transform',
+      'points',
+      // Data attributes for internal use
+      'data-has-code',
+      'data-language',
+      'data-line',
+      // Task list attributes
+      'type',
+      'checked',
+      'disabled',
+    ],
+    FORBID_TAGS: ['style', 'iframe', 'object', 'embed', 'form', 'button'],
+    FORBID_ATTR: ['onerror', 'onload', 'onclick', 'onmouseover', 'onmouseout', 'onmousemove'],
+    ALLOW_DATA_ATTR: true, // Allow data-* attributes with whitelist
+    ALLOW_UNKNOWN_PROTOCOLS: false,
+    SAFE_FOR_TEMPLATES: true,
+    RETURN_TRUSTED_TYPE: false,
+  };
+
+  /**
+   * Sanitize HTML string
+   */
+  static sanitize(dirty: string): string {
+    return DOMPurify.sanitize(dirty, this.config);
+  }
+
+  /**
+   * Sanitize HTML element
+   */
+  static sanitizeElement(element: HTMLElement): HTMLElement {
+    const sanitized = this.sanitize(element.outerHTML);
+    const temp = document.createElement('div');
+    temp.innerHTML = sanitized;
+    return temp.firstChild as HTMLElement;
+  }
+
+  /**
+   * Check if content is safe
+   */
+  static isSafe(content: string): boolean {
+    const sanitized = this.sanitize(content);
+    return content === sanitized;
+  }
+
+  /**
+   * Get list of removed elements after sanitization
+   */
+  static getRemovedElements(content: string): string[] {
+    const removed: string[] = [];
+
+    DOMPurify.addHook('uponSanitizeElement', (_node, data) => {
+      const allowedTags = data.allowedTags as Record<string, boolean> | undefined;
+      if (allowedTags && allowedTags[data.tagName] === false) {
+        removed.push(data.tagName);
+      }
+    });
+
+    this.sanitize(content);
+    DOMPurify.removeAllHooks();
+
+    return removed;
+  }
+
+  /**
+   * Configure custom sanitization rules
+   */
+  static configure(customConfig: Partial<typeof DOMPurifierUtil.config>): void {
+    Object.assign(this.config, customConfig);
+  }
+
+  /**
+   * Reset to default configuration
+   */
+  static resetConfig(): void {
+    // Config is already set in the class definition
+    // This method allows runtime reset if needed
+  }
+}
+
+// Export singleton for convenience
+export const domPurifier = DOMPurifierUtil;
diff --git a/packages/core/src/utils/scroll-manager.ts b/packages/core/src/utils/scroll-manager.ts
new file mode 100644
index 0000000..3fdcc33
--- /dev/null
+++ b/packages/core/src/utils/scroll-manager.ts
@@ -0,0 +1,180 @@
+/**
+ * Scroll Manager
+ * Saves and restores scroll position across page reloads
+ */
+
+import { createDebug } from './debug-logger';
+
+const debug = createDebug();
+
+interface ScrollState {
+  position: number;
+  timestamp: number;
+  filePath: string;
+  visibleSectionId?: string;
+}
+
+export class ScrollManager {
+  private static readonly STORAGE_KEY = 'mdview-scroll-state';
+  private static readonly MAX_AGE = 5000; // 5 seconds - only restore recent scrolls
+  private saveTimeout: number | null = null;
+  private filePath: string;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  /**
+   * Save current scroll position (debounced)
+   */
+  savePosition(visibleSectionId?: string): void {
+    if (this.saveTimeout) {
+      clearTimeout(this.saveTimeout);
+    }
+
+    this.saveTimeout = window.setTimeout(() => {
+      const state: ScrollState = {
+        position: window.scrollY,
+        timestamp: Date.now(),
+        filePath: this.filePath,
+        visibleSectionId,
+      };
+
+      try {
+        sessionStorage.setItem(ScrollManager.STORAGE_KEY, JSON.stringify(state));
+        debug.debug(
+          'ScrollManager',
+          `Saved scroll position: ${state.position}px, section: ${visibleSectionId || 'none'}`
+        );
+      } catch (error) {
+        debug.error('ScrollManager', 'Failed to save scroll position:', error);
+      }
+    }, 200); // Debounce 200ms
+  }
+
+  /**
+   * Get saved scroll position for current file
+   */
+  getSavedPosition(): ScrollState | null {
+    try {
+      const stored = sessionStorage.getItem(ScrollManager.STORAGE_KEY);
+      if (!stored) return null;
+
+      const state = JSON.parse(stored) as ScrollState;
+
+      // Only restore if it's for the same file and recent
+      const age = Date.now() - state.timestamp;
+      if (state.filePath !== this.filePath || age > ScrollManager.MAX_AGE) {
+        debug.debug('ScrollManager', 'Ignoring stale or mismatched scroll state');
+        sessionStorage.removeItem(ScrollManager.STORAGE_KEY);
+        return null;
+      }
+
+      debug.info(
+        'ScrollManager',
+        `Found saved scroll position: ${state.position}px, section: ${state.visibleSectionId || 'none'}`
+      );
+      return state;
+    } catch (error) {
+      debug.error('ScrollManager', 'Failed to get scroll position:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Restore scroll position
+   */
+  restorePosition(state: ScrollState): void {
+    debug.info('ScrollManager', `Restoring scroll position to ${state.position}px`);
+
+    // Try to scroll to the section first (more reliable)
+    if (state.visibleSectionId) {
+      const section = document.querySelector(`[data-section-id="${state.visibleSectionId}"]`);
+      if (section) {
+        section.scrollIntoView({ behavior: 'auto' });
+        debug.debug('ScrollManager', `Scrolled to section: ${state.visibleSectionId}`);
+
+        // Clear the saved position immediately after restoring
+        // This prevents re-restoration on subsequent operations
+        this.clearSavedPosition();
+        return;
+      }
+    }
+
+    // Fallback to pixel position
+    window.scrollTo(0, state.position);
+
+    // Clear the saved position immediately after restoring
+    this.clearSavedPosition();
+  }
+
+  /**
+   * Clear saved position
+   */
+  clearSavedPosition(): void {
+    sessionStorage.removeItem(ScrollManager.STORAGE_KEY);
+  }
+
+  /**
+   * Get the currently visible section
+   */
+  getVisibleSection(): string | null {
+    const sections = document.querySelectorAll('[data-section-id]');
+    if (sections.length === 0) return null;
+
+    // Find the first section that's at least 30% visible in viewport
+    const viewportTop = window.scrollY;
+    const viewportBottom = viewportTop + window.innerHeight;
+    const threshold = window.innerHeight * 0.3;
+
+    for (const section of Array.from(sections)) {
+      const rect = section.getBoundingClientRect();
+      const sectionTop = rect.top + window.scrollY;
+      const sectionBottom = sectionTop + rect.height;
+
+      // Check if section is in viewport
+      if (sectionBottom > viewportTop && sectionTop < viewportBottom) {
+        // Check if at least threshold is visible
+        const visibleTop = Math.max(sectionTop, viewportTop);
+        const visibleBottom = Math.min(sectionBottom, viewportBottom);
+        const visibleHeight = visibleBottom - visibleTop;
+
+        if (visibleHeight >= threshold) {
+          return section.getAttribute('data-section-id');
+        }
+      }
+    }
+
+    // Fallback to first section in viewport
+    for (const section of Array.from(sections)) {
+      const rect = section.getBoundingClientRect();
+      if (rect.top < window.innerHeight && rect.bottom > 0) {
+        return section.getAttribute('data-section-id');
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Set up automatic scroll position tracking
+   */
+  startTracking(): () => void {
+    const handleScroll = () => {
+      const visibleSection = this.getVisibleSection();
+      this.savePosition(visibleSection || undefined);
+    };
+
+    window.addEventListener('scroll', handleScroll, { passive: true });
+    debug.debug('ScrollManager', 'Started tracking scroll position');
+
+    // Return cleanup function
+    return () => {
+      window.removeEventListener('scroll', handleScroll);
+      if (this.saveTimeout) {
+        clearTimeout(this.saveTimeout);
+      }
+      debug.debug('ScrollManager', 'Stopped tracking scroll position');
+    };
+  }
+}
diff --git a/packages/core/src/utils/skeleton-renderer.ts b/packages/core/src/utils/skeleton-renderer.ts
new file mode 100644
index 0000000..30258a4
--- /dev/null
+++ b/packages/core/src/utils/skeleton-renderer.ts
@@ -0,0 +1,103 @@
+/**
+ * Skeleton Renderer
+ * Renders document structure instantly (headings + placeholders)
+ * Content is hydrated progressively afterwards
+ */
+
+import type { MarkdownSection } from './section-splitter';
+import { createDebug } from './debug-logger';
+
+const debug = createDebug();
+
+export interface SkeletonSection {
+  id: string;
+  heading?: string;
+  level?: number;
+  estimatedHeight: number;
+}
+
+export class SkeletonRenderer {
+  /**
+   * Generate skeleton HTML from sections
+   * This renders instantly (< 10ms) with just headings and placeholders
+   */
+  static generateSkeleton(sections: MarkdownSection[]): string {
+    debug.log('SkeletonRenderer', `Generating skeleton for ${sections.length} sections`);
+
+    const skeletonHtml = sections
+      .map((section) => {
+        // Estimate height based on content length
+        // ~0.3px per character is a rough estimate
+        const estimatedHeight = Math.max(100, Math.min(section.markdown.length * 0.3, 2000));
+
+        return `
+        <div
+          class="mdview-section mdview-section-skeleton"
+          id="${section.id}"
+          data-section-id="${section.id}"
+          data-hydrated="false"
+          style="min-height: ${estimatedHeight}px;"
+        >
+          ${
+            section.heading
+              ? `
+            <h${section.level || 2} class="section-heading">
+              ${this.escapeHtml(section.heading)}
+            </h${section.level || 2}>
+          `
+              : ''
+          }
+          <div class="section-placeholder">
+            <div class="placeholder-shimmer"></div>
+          </div>
+        </div>
+      `;
+      })
+      .join('\n');
+
+    debug.log('SkeletonRenderer', 'Skeleton generated');
+    return skeletonHtml;
+  }
+
+  /**
+   * Check if a section is hydrated
+   */
+  static isHydrated(sectionElement: HTMLElement): boolean {
+    return sectionElement.dataset.hydrated === 'true';
+  }
+
+  /**
+   * Mark a section as hydrated
+   */
+  static markHydrated(sectionElement: HTMLElement): void {
+    sectionElement.dataset.hydrated = 'true';
+    sectionElement.classList.remove('mdview-section-skeleton');
+    sectionElement.classList.add('mdview-section-hydrated');
+
+    // Remove skeleton min-height (let content determine height)
+    sectionElement.style.minHeight = '';
+
+    // Remove placeholder
+    const placeholder = sectionElement.querySelector('.section-placeholder');
+    if (placeholder) {
+      placeholder.remove();
+    }
+  }
+
+  /**
+   * Get all unhydrated sections
+   */
+  static getUnhydratedSections(container: HTMLElement): HTMLElement[] {
+    const sections = container.querySelectorAll('.mdview-section[data-hydrated="false"]');
+    return Array.from(sections) as HTMLElement[];
+  }
+
+  /**
+   * Escape HTML for safe rendering
+   */
+  private static escapeHtml(text: string): string {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+}
diff --git a/src/utils/dom-purifier.ts b/src/utils/dom-purifier.ts
index 905a9cb..9bb58f7 100644
--- a/src/utils/dom-purifier.ts
+++ b/src/utils/dom-purifier.ts
@@ -1,166 +1 @@
-/**
- * DOM Purifier Utility
- * Sanitizes HTML content using DOMPurify for security
- */
-
-import DOMPurify from 'dompurify';
-
-export class DOMPurifierUtil {
-  private static config = {
-    ALLOWED_TAGS: [
-      'p',
-      'br',
-      'strong',
-      'em',
-      'u',
-      's',
-      'code',
-      'pre',
-      'h1',
-      'h2',
-      'h3',
-      'h4',
-      'h5',
-      'h6',
-      'ul',
-      'ol',
-      'li',
-      'dl',
-      'dt',
-      'dd',
-      'a',
-      'img',
-      'blockquote',
-      'hr',
-      'div',
-      'span',
-      'table',
-      'thead',
-      'tbody',
-      'tfoot',
-      'tr',
-      'th',
-      'td',
-      'svg',
-      'path',
-      'circle',
-      'rect',
-      'line',
-      'polyline',
-      'polygon',
-      'g',
-      'text',
-      'defs',
-      'marker',
-      'input',
-      'label',
-      'details',
-      'summary',
-    ],
-    ALLOWED_ATTR: [
-      'href',
-      'src',
-      'alt',
-      'title',
-      'class',
-      'id',
-      'width',
-      'height',
-      'target',
-      'rel',
-      // SVG attributes
-      'd',
-      'cx',
-      'cy',
-      'r',
-      'x',
-      'y',
-      'x1',
-      'y1',
-      'x2',
-      'y2',
-      'viewBox',
-      'fill',
-      'stroke',
-      'stroke-width',
-      'transform',
-      'points',
-      // Data attributes for internal use
-      'data-has-code',
-      'data-language',
-      'data-line',
-      // Task list attributes
-      'type',
-      'checked',
-      'disabled',
-    ],
-    FORBID_TAGS: ['style', 'iframe', 'object', 'embed', 'form', 'button'],
-    FORBID_ATTR: ['onerror', 'onload', 'onclick', 'onmouseover', 'onmouseout', 'onmousemove'],
-    ALLOW_DATA_ATTR: true, // Allow data-* attributes with whitelist
-    ALLOW_UNKNOWN_PROTOCOLS: false,
-    SAFE_FOR_TEMPLATES: true,
-    RETURN_TRUSTED_TYPE: false,
-  };
-
-  /**
-   * Sanitize HTML string
-   */
-  static sanitize(dirty: string): string {
-    return DOMPurify.sanitize(dirty, this.config);
-  }
-
-  /**
-   * Sanitize HTML element
-   */
-  static sanitizeElement(element: HTMLElement): HTMLElement {
-    const sanitized = this.sanitize(element.outerHTML);
-    const temp = document.createElement('div');
-    temp.innerHTML = sanitized;
-    return temp.firstChild as HTMLElement;
-  }
-
-  /**
-   * Check if content is safe
-   */
-  static isSafe(content: string): boolean {
-    const sanitized = this.sanitize(content);
-    return content === sanitized;
-  }
-
-  /**
-   * Get list of removed elements after sanitization
-   */
-  static getRemovedElements(content: string): string[] {
-    const removed: string[] = [];
-
-    DOMPurify.addHook('uponSanitizeElement', (_node, data) => {
-      const allowedTags = data.allowedTags as Record<string, boolean> | undefined;
-      if (allowedTags && allowedTags[data.tagName] === false) {
-        removed.push(data.tagName);
-      }
-    });
-
-    this.sanitize(content);
-    DOMPurify.removeAllHooks();
-
-    return removed;
-  }
-
-  /**
-   * Configure custom sanitization rules
-   */
-  static configure(customConfig: Partial<typeof DOMPurifierUtil.config>): void {
-    Object.assign(this.config, customConfig);
-  }
-
-  /**
-   * Reset to default configuration
-   */
-  static resetConfig(): void {
-    // Config is already set in the class definition
-    // This method allows runtime reset if needed
-  }
-}
-
-// Export singleton for convenience
-export const domPurifier = DOMPurifierUtil;
+export * from '../../packages/core/src/utils/dom-purifier';
diff --git a/src/utils/scroll-manager.ts b/src/utils/scroll-manager.ts
index f23b69a..b3794be 100644
--- a/src/utils/scroll-manager.ts
+++ b/src/utils/scroll-manager.ts
@@ -1,178 +1 @@
-/**
- * Scroll Manager
- * Saves and restores scroll position across page reloads
- */
-
-import { debug } from './debug-logger';
-
-interface ScrollState {
-  position: number;
-  timestamp: number;
-  filePath: string;
-  visibleSectionId?: string;
-}
-
-export class ScrollManager {
-  private static readonly STORAGE_KEY = 'mdview-scroll-state';
-  private static readonly MAX_AGE = 5000; // 5 seconds - only restore recent scrolls
-  private saveTimeout: number | null = null;
-  private filePath: string;
-
-  constructor(filePath: string) {
-    this.filePath = filePath;
-  }
-
-  /**
-   * Save current scroll position (debounced)
-   */
-  savePosition(visibleSectionId?: string): void {
-    if (this.saveTimeout) {
-      clearTimeout(this.saveTimeout);
-    }
-
-    this.saveTimeout = window.setTimeout(() => {
-      const state: ScrollState = {
-        position: window.scrollY,
-        timestamp: Date.now(),
-        filePath: this.filePath,
-        visibleSectionId,
-      };
-
-      try {
-        sessionStorage.setItem(ScrollManager.STORAGE_KEY, JSON.stringify(state));
-        debug.debug(
-          'ScrollManager',
-          `Saved scroll position: ${state.position}px, section: ${visibleSectionId || 'none'}`
-        );
-      } catch (error) {
-        debug.error('ScrollManager', 'Failed to save scroll position:', error);
-      }
-    }, 200); // Debounce 200ms
-  }
-
-  /**
-   * Get saved scroll position for current file
-   */
-  getSavedPosition(): ScrollState | null {
-    try {
-      const stored = sessionStorage.getItem(ScrollManager.STORAGE_KEY);
-      if (!stored) return null;
-
-      const state = JSON.parse(stored) as ScrollState;
-
-      // Only restore if it's for the same file and recent
-      const age = Date.now() - state.timestamp;
-      if (state.filePath !== this.filePath || age > ScrollManager.MAX_AGE) {
-        debug.debug('ScrollManager', 'Ignoring stale or mismatched scroll state');
-        sessionStorage.removeItem(ScrollManager.STORAGE_KEY);
-        return null;
-      }
-
-      debug.info(
-        'ScrollManager',
-        `Found saved scroll position: ${state.position}px, section: ${state.visibleSectionId || 'none'}`
-      );
-      return state;
-    } catch (error) {
-      debug.error('ScrollManager', 'Failed to get scroll position:', error);
-      return null;
-    }
-  }
-
-  /**
-   * Restore scroll position
-   */
-  restorePosition(state: ScrollState): void {
-    debug.info('ScrollManager', `Restoring scroll position to ${state.position}px`);
-
-    // Try to scroll to the section first (more reliable)
-    if (state.visibleSectionId) {
-      const section = document.querySelector(`[data-section-id="${state.visibleSectionId}"]`);
-      if (section) {
-        section.scrollIntoView({ behavior: 'auto' });
-        debug.debug('ScrollManager', `Scrolled to section: ${state.visibleSectionId}`);
-
-        // Clear the saved position immediately after restoring
-        // This prevents re-restoration on subsequent operations
-        this.clearSavedPosition();
-        return;
-      }
-    }
-
-    // Fallback to pixel position
-    window.scrollTo(0, state.position);
-
-    // Clear the saved position immediately after restoring
-    this.clearSavedPosition();
-  }
-
-  /**
-   * Clear saved position
-   */
-  clearSavedPosition(): void {
-    sessionStorage.removeItem(ScrollManager.STORAGE_KEY);
-  }
-
-  /**
-   * Get the currently visible section
-   */
-  getVisibleSection(): string | null {
-    const sections = document.querySelectorAll('[data-section-id]');
-    if (sections.length === 0) return null;
-
-    // Find the first section that's at least 30% visible in viewport
-    const viewportTop = window.scrollY;
-    const viewportBottom = viewportTop + window.innerHeight;
-    const threshold = window.innerHeight * 0.3;
-
-    for (const section of Array.from(sections)) {
-      const rect = section.getBoundingClientRect();
-      const sectionTop = rect.top + window.scrollY;
-      const sectionBottom = sectionTop + rect.height;
-
-      // Check if section is in viewport
-      if (sectionBottom > viewportTop && sectionTop < viewportBottom) {
-        // Check if at least threshold is visible
-        const visibleTop = Math.max(sectionTop, viewportTop);
-        const visibleBottom = Math.min(sectionBottom, viewportBottom);
-        const visibleHeight = visibleBottom - visibleTop;
-
-        if (visibleHeight >= threshold) {
-          return section.getAttribute('data-section-id');
-        }
-      }
-    }
-
-    // Fallback to first section in viewport
-    for (const section of Array.from(sections)) {
-      const rect = section.getBoundingClientRect();
-      if (rect.top < window.innerHeight && rect.bottom > 0) {
-        return section.getAttribute('data-section-id');
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Set up automatic scroll position tracking
-   */
-  startTracking(): () => void {
-    const handleScroll = () => {
-      const visibleSection = this.getVisibleSection();
-      this.savePosition(visibleSection || undefined);
-    };
-
-    window.addEventListener('scroll', handleScroll, { passive: true });
-    debug.debug('ScrollManager', 'Started tracking scroll position');
-
-    // Return cleanup function
-    return () => {
-      window.removeEventListener('scroll', handleScroll);
-      if (this.saveTimeout) {
-        clearTimeout(this.saveTimeout);
-      }
-      debug.debug('ScrollManager', 'Stopped tracking scroll position');
-    };
-  }
-}
+export * from '../../packages/core/src/utils/scroll-manager';
diff --git a/src/utils/skeleton-renderer.ts b/src/utils/skeleton-renderer.ts
index c69ab9a..1703602 100644
--- a/src/utils/skeleton-renderer.ts
+++ b/src/utils/skeleton-renderer.ts
@@ -1,101 +1 @@
-/**
- * Skeleton Renderer
- * Renders document structure instantly (headings + placeholders)
- * Content is hydrated progressively afterwards
- */
-
-import type { MarkdownSection } from './section-splitter';
-import { debug } from './debug-logger';
-
-export interface SkeletonSection {
-  id: string;
-  heading?: string;
-  level?: number;
-  estimatedHeight: number;
-}
-
-export class SkeletonRenderer {
-  /**
-   * Generate skeleton HTML from sections
-   * This renders instantly (< 10ms) with just headings and placeholders
-   */
-  static generateSkeleton(sections: MarkdownSection[]): string {
-    debug.log('SkeletonRenderer', `Generating skeleton for ${sections.length} sections`);
-
-    const skeletonHtml = sections
-      .map((section) => {
-        // Estimate height based on content length
-        // ~0.3px per character is a rough estimate
-        const estimatedHeight = Math.max(100, Math.min(section.markdown.length * 0.3, 2000));
-
-        return `
-        <div 
-          class="mdview-section mdview-section-skeleton" 
-          id="${section.id}" 
-          data-section-id="${section.id}"
-          data-hydrated="false"
-          style="min-height: ${estimatedHeight}px;"
-        >
-          ${
-            section.heading
-              ? `
-            <h${section.level || 2} class="section-heading">
-              ${this.escapeHtml(section.heading)}
-            </h${section.level || 2}>
-          `
-              : ''
-          }
-          <div class="section-placeholder">
-            <div class="placeholder-shimmer"></div>
-          </div>
-        </div>
-      `;
-      })
-      .join('\n');
-
-    debug.log('SkeletonRenderer', 'Skeleton generated');
-    return skeletonHtml;
-  }
-
-  /**
-   * Check if a section is hydrated
-   */
-  static isHydrated(sectionElement: HTMLElement): boolean {
-    return sectionElement.dataset.hydrated === 'true';
-  }
-
-  /**
-   * Mark a section as hydrated
-   */
-  static markHydrated(sectionElement: HTMLElement): void {
-    sectionElement.dataset.hydrated = 'true';
-    sectionElement.classList.remove('mdview-section-skeleton');
-    sectionElement.classList.add('mdview-section-hydrated');
-
-    // Remove skeleton min-height (let content determine height)
-    sectionElement.style.minHeight = '';
-
-    // Remove placeholder
-    const placeholder = sectionElement.querySelector('.section-placeholder');
-    if (placeholder) {
-      placeholder.remove();
-    }
-  }
-
-  /**
-   * Get all unhydrated sections
-   */
-  static getUnhydratedSections(container: HTMLElement): HTMLElement[] {
-    const sections = container.querySelectorAll('.mdview-section[data-hydrated="false"]');
-    return Array.from(sections) as HTMLElement[];
-  }
-
-  /**
-   * Escape HTML for safe rendering
-   */
-  private static escapeHtml(text: string): string {
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-  }
-}
+export * from '../../packages/core/src/utils/skeleton-renderer';

From 58ff331a96d824afadbc7396b12e93ea3990de4f Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 09:08:54 -0400
Subject: [PATCH 19/26] refactor(core): move comment UI modules to @mdview/core

---
 .../src/__tests__/comment-manager.test.ts     |   7 +-
 .../core/src/comments/comment-highlight.ts    | 241 +++++++
 packages/core/src/comments/comment-manager.ts |   4 +-
 packages/core/src/comments/comment-ui.ts      | 615 +++++++++++++++++
 src/comments/comment-highlight.ts             | 242 +------
 src/comments/comment-ui.ts                    | 616 +-----------------
 6 files changed, 863 insertions(+), 862 deletions(-)
 create mode 100644 packages/core/src/comments/comment-highlight.ts
 create mode 100644 packages/core/src/comments/comment-ui.ts

diff --git a/packages/core/src/__tests__/comment-manager.test.ts b/packages/core/src/__tests__/comment-manager.test.ts
index 3980aa2..7aa0243 100644
--- a/packages/core/src/__tests__/comment-manager.test.ts
+++ b/packages/core/src/__tests__/comment-manager.test.ts
@@ -10,9 +10,8 @@ import type { AppState } from '../types/index';
  * they are browser-specific and not extracted to core yet.
  */
 
-// Mock the browser-specific dependencies (comment-ui, comment-highlight)
-// These still live in src/comments/ and are imported via relative paths
-vi.mock('../../../../src/comments/comment-ui', () => {
+// Mock the DOM-dependent comment UI modules (now in core/src/comments/)
+vi.mock('../comments/comment-ui', () => {
   class MockCommentUI {
     setCurrentAuthor = vi.fn();
     renderCard = vi.fn().mockReturnValue(document.createElement('div'));
@@ -25,7 +24,7 @@ vi.mock('../../../../src/comments/comment-ui', () => {
   return { CommentUI: MockCommentUI };
 });
 
-vi.mock('../../../../src/comments/comment-highlight', () => {
+vi.mock('../comments/comment-highlight', () => {
   class MockCommentHighlighter {
     highlightComment = vi.fn();
     clearActive = vi.fn();
diff --git a/packages/core/src/comments/comment-highlight.ts b/packages/core/src/comments/comment-highlight.ts
new file mode 100644
index 0000000..c22cd1a
--- /dev/null
+++ b/packages/core/src/comments/comment-highlight.ts
@@ -0,0 +1,241 @@
+import type { Comment } from '../types/index';
+
+const HIGHLIGHT_CLASS = 'mdview-comment-highlight';
+const COMMENT_ID_ATTR = 'data-comment-id';
+
+/**
+ * Manages text highlighting in the rendered DOM for margin comments.
+ *
+ * Uses TreeWalker to locate text nodes and the Range API to wrap
+ * matched substrings without disrupting the surrounding DOM structure.
+ * Supports selections that span across inline element boundaries.
+ */
+export class CommentHighlighter {
+  /**
+   * Find text within `container` that matches `selectedText`,
+   * wrap the matching portions in highlight `<span>` elements,
+   * and return the first span (used for card positioning).
+   *
+   * Handles text that spans across inline elements (e.g. bold, italic, code)
+   * by wrapping each text node portion separately with the same comment ID.
+   *
+   * Returns `null` if no matching text is found.
+   */
+  highlightComment(
+    container: HTMLElement,
+    comment: Comment
+  ): HTMLElement | null {
+    const { selectedText, id, resolved } = comment;
+
+    // Collect all text nodes and build a concatenated string
+    const textNodes: Text[] = [];
+    const walker = document.createTreeWalker(
+      container,
+      NodeFilter.SHOW_TEXT,
+      null
+    );
+    let node: Text | null;
+    while ((node = walker.nextNode() as Text | null)) {
+      textNodes.push(node);
+    }
+
+    // Build concatenated text with offset mappings.
+    // Insert a synthetic space between text nodes in different block-level
+    // parents so cross-block selections can match even when the DOM has no
+    // whitespace text node between adjacent block elements.
+    const BLOCK_TAGS = new Set([
+      'ADDRESS', 'ARTICLE', 'ASIDE', 'BLOCKQUOTE', 'DD', 'DETAILS', 'DIV',
+      'DL', 'DT', 'FIELDSET', 'FIGCAPTION', 'FIGURE', 'FOOTER', 'FORM',
+      'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'HEADER', 'HGROUP', 'HR',
+      'LI', 'MAIN', 'NAV', 'OL', 'P', 'PRE', 'SECTION', 'TABLE', 'UL',
+    ]);
+
+    const closestBlock = (node: Node): Element | null => {
+      let el: Node | null = node.parentNode;
+      while (el && el !== container) {
+        if (el.nodeType === Node.ELEMENT_NODE && BLOCK_TAGS.has((el as Element).tagName)) {
+          return el as Element;
+        }
+        el = el.parentNode;
+      }
+      return null;
+    };
+
+    let concat = '';
+    const nodeOffsets: Array<{ node: Text; start: number; end: number }> = [];
+    let prevBlock: Element | null = null;
+    for (const textNode of textNodes) {
+      const text = textNode.textContent ?? '';
+      const block = closestBlock(textNode);
+      // Insert a space when crossing block boundaries (if concat doesn't
+      // already end with whitespace)
+      if (
+        prevBlock !== null &&
+        block !== prevBlock &&
+        concat.length > 0 &&
+        !/\s$/.test(concat)
+      ) {
+        concat += ' ';
+      }
+      prevBlock = block;
+      const start = concat.length;
+      concat += text;
+      nodeOffsets.push({ node: textNode, start, end: concat.length });
+    }
+
+    // Find the selected text in the concatenated string.
+    // Try exact match first; fall back to whitespace-normalized match
+    // for cross-block selections where the browser inserts \n between
+    // block elements that may differ from the DOM text nodes.
+    let matchIndex = concat.indexOf(selectedText);
+    let matchEnd: number;
+
+    if (matchIndex !== -1) {
+      matchEnd = matchIndex + selectedText.length;
+    } else {
+      // Build a mapping from normalized offsets back to original offsets
+      const normalizedChars: number[] = []; // normalizedChars[i] = original index
+      let prevWs = false;
+      for (let i = 0; i < concat.length; i++) {
+        const isWs = /\s/.test(concat[i]);
+        if (isWs && prevWs) continue; // collapse consecutive whitespace
+        normalizedChars.push(i);
+        prevWs = isWs;
+      }
+      const normalizedConcat = normalizedChars
+        .map((i) => (/\s/.test(concat[i]) ? ' ' : concat[i]))
+        .join('');
+      const normalizedSearch = selectedText.replace(/\s+/g, ' ');
+
+      const normIdx = normalizedConcat.indexOf(normalizedSearch);
+      if (normIdx === -1) {
+        return null;
+      }
+
+      matchIndex = normalizedChars[normIdx];
+      // Map the end: normIdx + normalizedSearch.length may be past the end
+      const normEnd = normIdx + normalizedSearch.length;
+      matchEnd = normEnd < normalizedChars.length
+        ? normalizedChars[normEnd]
+        : concat.length;
+    }
+
+    // Find which text nodes overlap with the match
+    const overlapping = nodeOffsets.filter(
+      (entry) => entry.start < matchEnd && entry.end > matchIndex
+    );
+
+    if (overlapping.length === 0) {
+      return null;
+    }
+
+    // Single text node — use the simple Range.surroundContents approach
+    if (overlapping.length === 1) {
+      const entry = overlapping[0];
+      const localStart = matchIndex - entry.start;
+      const localEnd = localStart + selectedText.length;
+
+      const range = document.createRange();
+      range.setStart(entry.node, localStart);
+      range.setEnd(entry.node, localEnd);
+
+      const span = document.createElement('span');
+      span.className = HIGHLIGHT_CLASS;
+      if (resolved) {
+        span.classList.add('resolved');
+      }
+      span.setAttribute(COMMENT_ID_ATTR, id);
+
+      range.surroundContents(span);
+      return span;
+    }
+
+    // Cross-node: wrap each overlapping text node's matched portion
+    let firstSpan: HTMLElement | null = null;
+
+    // Process in reverse order so DOM mutations don't shift subsequent nodes
+    for (let i = overlapping.length - 1; i >= 0; i--) {
+      const entry = overlapping[i];
+      const localStart = Math.max(0, matchIndex - entry.start);
+      const localEnd = Math.min(
+        entry.node.textContent?.length ?? 0,
+        matchEnd - entry.start
+      );
+
+      const range = document.createRange();
+      range.setStart(entry.node, localStart);
+      range.setEnd(entry.node, localEnd);
+
+      const span = document.createElement('span');
+      span.className = HIGHLIGHT_CLASS;
+      if (resolved) {
+        span.classList.add('resolved');
+      }
+      span.setAttribute(COMMENT_ID_ATTR, id);
+
+      range.surroundContents(span);
+      firstSpan = span;
+    }
+
+    return firstSpan;
+  }
+
+  /**
+   * Remove all highlight spans for `commentId`, replacing each with its
+   * plain text content and normalising adjacent text nodes.
+   */
+  removeHighlight(commentId: string): void {
+    const spans = document.querySelectorAll(
+      `.${HIGHLIGHT_CLASS}[${COMMENT_ID_ATTR}="${commentId}"]`
+    );
+
+    for (const span of spans) {
+      const parent = span.parentNode;
+      if (!parent) continue;
+
+      const textNode = document.createTextNode(span.textContent ?? '');
+      parent.replaceChild(textNode, span);
+      parent.normalize();
+    }
+  }
+
+  /**
+   * Mark the highlight span for `commentId` as active (adds `.active` class).
+   */
+  setActive(commentId: string): void {
+    const span = this.getHighlightElement(commentId);
+    if (span) {
+      span.classList.add('active');
+    }
+  }
+
+  /**
+   * Remove the `.active` class from all highlight spans in the document.
+   */
+  clearActive(): void {
+    const spans = document.querySelectorAll(`.${HIGHLIGHT_CLASS}.active`);
+    for (const span of spans) {
+      span.classList.remove('active');
+    }
+  }
+
+  /**
+   * Mark the highlight span for `commentId` as resolved (adds `.resolved` class).
+   */
+  setResolved(commentId: string): void {
+    const span = this.getHighlightElement(commentId);
+    if (span) {
+      span.classList.add('resolved');
+    }
+  }
+
+  /**
+   * Return the first highlight `<span>` for the given `commentId`, or `null`
+   * if it does not exist in the document.
+   */
+  getHighlightElement(commentId: string): HTMLElement | null {
+    return document.querySelector<HTMLElement>(
+      `.${HIGHLIGHT_CLASS}[${COMMENT_ID_ATTR}="${commentId}"]`
+    );
+  }
+}
diff --git a/packages/core/src/comments/comment-manager.ts b/packages/core/src/comments/comment-manager.ts
index c74d847..3fa1ec2 100644
--- a/packages/core/src/comments/comment-manager.ts
+++ b/packages/core/src/comments/comment-manager.ts
@@ -16,8 +16,8 @@
 
 import type { Comment, CommentParseResult, AppState, CommentTag } from '../types/index';
 import type { FileAdapter, IdentityAdapter } from '../adapters';
-import { CommentUI } from '../../../../src/comments/comment-ui';
-import { CommentHighlighter } from '../../../../src/comments/comment-highlight';
+import { CommentUI } from './comment-ui';
+import { CommentHighlighter } from './comment-highlight';
 import { parseComments } from './annotation-parser';
 import {
   addComment as serializerAddComment,
diff --git a/packages/core/src/comments/comment-ui.ts b/packages/core/src/comments/comment-ui.ts
new file mode 100644
index 0000000..6e99450
--- /dev/null
+++ b/packages/core/src/comments/comment-ui.ts
@@ -0,0 +1,615 @@
+/**
+ * Comment UI Module
+ * Renders margin comment cards, input form, reply forms, reaction pills,
+ * emoji picker, and overflow menus.
+ * Dispatches custom events for all user actions.
+ */
+
+import type { Comment, CommentTag, CommentReply, CommentReactions } from '../types/index';
+import { QUICK_EMOJIS, EMOJI_CATEGORIES, searchEmojis } from './emoji-data';
+
+const ALL_TAGS: CommentTag[] = [
+  'blocking', 'nit', 'suggestion', 'question', 'praise', 'todo', 'fyi',
+];
+
+export class CommentUI {
+  private gutter: HTMLElement | null = null;
+  private cards: HTMLElement[] = [];
+  private activeMenu: HTMLElement | null = null;
+  private clickOutsideHandler: ((e: MouseEvent) => void) | null = null;
+  private currentAuthor: string = '';
+
+  /**
+   * Set the current author name (used for reaction pill .mine class)
+   */
+  setCurrentAuthor(author: string): void {
+    this.currentAuthor = author;
+  }
+
+  /**
+   * Create the comment gutter container
+   */
+  createGutter(): HTMLElement {
+    this.gutter = document.createElement('div');
+    this.gutter.className = 'mdview-comment-gutter';
+    return this.gutter;
+  }
+
+  /**
+   * Render a comment card element
+   */
+  renderCard(comment: Comment): HTMLElement {
+    const card = document.createElement('div');
+    card.className = 'mdview-comment-card minimized';
+    card.dataset.commentId = comment.id;
+
+    if (comment.resolved) {
+      card.classList.add('resolved');
+    }
+
+    // Header
+    const header = document.createElement('div');
+    header.className = 'comment-header';
+
+    const author = document.createElement('strong');
+    author.className = 'comment-author';
+    author.textContent = comment.author || 'Anonymous';
+
+    const date = document.createElement('span');
+    date.className = 'comment-date';
+    date.textContent = this.formatRelativeTime(comment.date);
+
+    const menuBtn = document.createElement('button');
+    menuBtn.className = 'comment-menu-btn';
+    menuBtn.textContent = '\u2026'; // ellipsis character
+    menuBtn.setAttribute('aria-label', 'Comment actions');
+    menuBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.showOverflowMenu(comment.id, menuBtn);
+    });
+
+    header.appendChild(author);
+    header.appendChild(date);
+    header.appendChild(menuBtn);
+
+    // Body
+    const body = document.createElement('div');
+    body.className = 'comment-body';
+    body.textContent = comment.body;
+
+    card.appendChild(header);
+
+    // Snippet (visible only when minimized, via CSS)
+    const snippet = document.createElement('div');
+    snippet.className = 'comment-snippet';
+    const maxLen = 60;
+    snippet.textContent = comment.body.length > maxLen
+      ? comment.body.slice(0, maxLen) + '...'
+      : comment.body;
+    card.appendChild(snippet);
+
+    // Tag pills
+    if (comment.tags && comment.tags.length > 0) {
+      const tagsContainer = document.createElement('div');
+      tagsContainer.className = 'comment-tags';
+      for (const tag of comment.tags) {
+        const pill = document.createElement('span');
+        pill.className = `comment-tag comment-tag--${tag}`;
+        pill.textContent = tag;
+        tagsContainer.appendChild(pill);
+      }
+      card.appendChild(tagsContainer);
+    }
+
+    card.appendChild(body);
+
+    // Replies
+    if (comment.replies && comment.replies.length > 0) {
+      card.appendChild(this.renderReplies(comment.replies));
+    }
+
+    // Reply button (non-resolved only)
+    if (!comment.resolved) {
+      const replyBtn = document.createElement('button');
+      replyBtn.className = 'comment-reply-btn';
+      replyBtn.textContent = 'Reply';
+      replyBtn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        document.dispatchEvent(
+          new CustomEvent('mdview:comment:reply', {
+            detail: { commentId: comment.id },
+          })
+        );
+      });
+      card.appendChild(replyBtn);
+    }
+
+    // Reactions
+    if (this.currentAuthor) {
+      card.appendChild(this.renderReactions(comment.id, comment.reactions ?? {}));
+    }
+
+    // Resolved badge
+    if (comment.resolved) {
+      const badge = document.createElement('span');
+      badge.className = 'resolved-badge';
+      badge.textContent = 'Resolved';
+      card.appendChild(badge);
+    }
+
+    // Click toggles minimized/expanded state
+    card.addEventListener('click', () => {
+      const wasMinimized = card.classList.contains('minimized');
+      card.classList.toggle('minimized');
+
+      // Only focus the highlight when expanding
+      if (wasMinimized) {
+        document.dispatchEvent(
+          new CustomEvent('mdview:comment:focus', {
+            detail: { commentId: comment.id },
+          })
+        );
+      }
+
+      // Always reposition after size change
+      document.dispatchEvent(new CustomEvent('mdview:comment:reposition'));
+    });
+
+    this.cards.push(card);
+    return card;
+  }
+
+  /**
+   * Render replies section
+   */
+  private renderReplies(replies: CommentReply[]): HTMLElement {
+    const container = document.createElement('div');
+    container.className = 'comment-replies';
+
+    for (const reply of replies) {
+      const replyEl = document.createElement('div');
+      replyEl.className = 'comment-reply';
+
+      const replyHeader = document.createElement('div');
+      replyHeader.className = 'comment-reply-header';
+
+      const replyAuthor = document.createElement('strong');
+      replyAuthor.className = 'comment-reply-author';
+      replyAuthor.textContent = reply.author || 'Anonymous';
+
+      const replyDate = document.createElement('span');
+      replyDate.className = 'comment-reply-date';
+      replyDate.textContent = this.formatRelativeTime(reply.date);
+
+      replyHeader.appendChild(replyAuthor);
+      replyHeader.appendChild(replyDate);
+
+      const replyBody = document.createElement('div');
+      replyBody.className = 'comment-reply-body';
+      replyBody.textContent = reply.body;
+
+      replyEl.appendChild(replyHeader);
+      replyEl.appendChild(replyBody);
+      container.appendChild(replyEl);
+    }
+
+    return container;
+  }
+
+  /**
+   * Render reaction pills and "+" button
+   */
+  private renderReactions(commentId: string, reactions: CommentReactions): HTMLElement {
+    const container = document.createElement('div');
+    container.className = 'comment-reactions';
+
+    const emojis = Object.keys(reactions);
+    for (const emoji of emojis) {
+      const authors = reactions[emoji];
+      if (!authors || authors.length === 0) continue;
+
+      const pill = document.createElement('button');
+      pill.className = 'comment-reaction';
+      if (this.currentAuthor && authors.includes(this.currentAuthor)) {
+        pill.classList.add('mine');
+      }
+      pill.textContent = `${emoji} ${authors.length}`;
+      pill.dataset.emoji = emoji;
+      pill.addEventListener('click', (e) => {
+        e.stopPropagation();
+        document.dispatchEvent(
+          new CustomEvent('mdview:comment:react', {
+            detail: { commentId, emoji },
+          })
+        );
+      });
+      container.appendChild(pill);
+    }
+
+    // "+" add reaction button
+    const addBtn = document.createElement('button');
+    addBtn.className = 'comment-reaction-add';
+    addBtn.textContent = '+';
+    addBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      document.dispatchEvent(
+        new CustomEvent('mdview:comment:react:picker', {
+          detail: { commentId, anchor: addBtn },
+        })
+      );
+    });
+    container.appendChild(addBtn);
+
+    return container;
+  }
+
+  /**
+   * Render a compact reply form (no tag picker)
+   */
+  renderReplyForm(
+    onSave: (body: string) => void,
+    onCancel: () => void
+  ): HTMLElement {
+    const form = document.createElement('div');
+    form.className = 'comment-reply-form';
+
+    const textarea = document.createElement('textarea');
+    textarea.placeholder = 'Write a reply...';
+    textarea.rows = 2;
+
+    textarea.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        onSave(textarea.value);
+      }
+    });
+
+    const actions = document.createElement('div');
+    actions.className = 'mdview-comment-input-actions';
+
+    const saveBtn = document.createElement('button');
+    saveBtn.className = 'mdview-comment-btn-save';
+    saveBtn.textContent = 'Save';
+    saveBtn.addEventListener('click', () => {
+      onSave(textarea.value);
+    });
+
+    const cancelBtn = document.createElement('button');
+    cancelBtn.className = 'mdview-comment-btn-cancel';
+    cancelBtn.textContent = 'Cancel';
+    cancelBtn.addEventListener('click', () => {
+      onCancel();
+    });
+
+    actions.appendChild(saveBtn);
+    actions.appendChild(cancelBtn);
+
+    form.appendChild(textarea);
+    form.appendChild(actions);
+
+    return form;
+  }
+
+  /**
+   * Render the emoji picker
+   */
+  renderEmojiPicker(
+    _anchor: HTMLElement,
+    onSelect: (emoji: string) => void,
+    onClose: () => void
+  ): HTMLElement {
+    const picker = document.createElement('div');
+    picker.className = 'mdview-emoji-picker';
+
+    // Quick palette row
+    const quickRow = document.createElement('div');
+    quickRow.className = 'emoji-picker-quick';
+    for (const emoji of QUICK_EMOJIS) {
+      const btn = document.createElement('button');
+      btn.textContent = emoji.char;
+      btn.title = emoji.name;
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        onSelect(emoji.char);
+      });
+      quickRow.appendChild(btn);
+    }
+    picker.appendChild(quickRow);
+
+    // Search input
+    const searchInput = document.createElement('input');
+    searchInput.className = 'emoji-picker-search';
+    searchInput.type = 'text';
+    searchInput.placeholder = 'Search emojis...';
+    picker.appendChild(searchInput);
+
+    // Categorized grid
+    const grid = document.createElement('div');
+    grid.className = 'emoji-picker-grid';
+    this.renderEmojiGrid(grid, EMOJI_CATEGORIES, onSelect);
+    picker.appendChild(grid);
+
+    // Search filtering
+    searchInput.addEventListener('input', () => {
+      const query = searchInput.value.trim();
+      if (query) {
+        const results = searchEmojis(query);
+        grid.innerHTML = '';
+        const catName = document.createElement('div');
+        catName.className = 'emoji-picker-category-name';
+        catName.textContent = 'Search Results';
+        grid.appendChild(catName);
+        for (const emoji of results) {
+          const btn = document.createElement('button');
+          btn.textContent = emoji.char;
+          btn.title = emoji.name;
+          btn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            onSelect(emoji.char);
+          });
+          grid.appendChild(btn);
+        }
+      } else {
+        grid.innerHTML = '';
+        this.renderEmojiGrid(grid, EMOJI_CATEGORIES, onSelect);
+      }
+    });
+
+    // Click-outside to dismiss
+    const clickOutsideHandler = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (!picker.contains(target)) {
+        document.removeEventListener('click', clickOutsideHandler);
+        onClose();
+      }
+    };
+    document.addEventListener('click', clickOutsideHandler);
+
+    return picker;
+  }
+
+  /**
+   * Render the categorized emoji grid into a container
+   */
+  private renderEmojiGrid(
+    container: HTMLElement,
+    categories: typeof EMOJI_CATEGORIES,
+    onSelect: (emoji: string) => void
+  ): void {
+    for (const cat of categories) {
+      const catName = document.createElement('div');
+      catName.className = 'emoji-picker-category-name';
+      catName.textContent = cat.name;
+      container.appendChild(catName);
+
+      for (const emoji of cat.emojis) {
+        const btn = document.createElement('button');
+        btn.textContent = emoji.char;
+        btn.title = emoji.name;
+        btn.addEventListener('click', (e) => {
+          e.stopPropagation();
+          onSelect(emoji.char);
+        });
+        container.appendChild(btn);
+      }
+    }
+  }
+
+  /**
+   * Show the overflow menu for a comment card
+   */
+  private showOverflowMenu(commentId: string, anchorElement: HTMLElement): void {
+    // Close any existing menu first
+    this.closeOverflowMenu();
+
+    const menu = document.createElement('div');
+    menu.className = 'mdview-comment-menu';
+    menu.setAttribute('role', 'menu');
+
+    const actions = [
+      { label: 'Edit', event: 'mdview:comment:edit' },
+      { label: 'Resolve', event: 'mdview:comment:resolve' },
+      { label: 'Delete', event: 'mdview:comment:delete' },
+    ];
+
+    for (const action of actions) {
+      const item = document.createElement('button');
+      item.className = 'mdview-comment-menu-item';
+      item.setAttribute('role', 'menuitem');
+      item.textContent = action.label;
+
+      item.addEventListener('click', (e) => {
+        e.stopPropagation();
+        document.dispatchEvent(
+          new CustomEvent(action.event, {
+            detail: { commentId },
+          })
+        );
+        this.closeOverflowMenu();
+      });
+
+      menu.appendChild(item);
+    }
+
+    // Position relative to anchor
+    anchorElement.parentElement?.appendChild(menu);
+    this.activeMenu = menu;
+
+    // Setup click-outside handler. The menu button uses stopPropagation,
+    // so registering synchronously is safe.
+    this.clickOutsideHandler = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (this.activeMenu && !this.activeMenu.contains(target)) {
+        this.closeOverflowMenu();
+      }
+    };
+
+    document.addEventListener('click', this.clickOutsideHandler);
+  }
+
+  /**
+   * Close the currently open overflow menu
+   */
+  private closeOverflowMenu(): void {
+    if (this.activeMenu) {
+      this.activeMenu.remove();
+      this.activeMenu = null;
+    }
+
+    if (this.clickOutsideHandler) {
+      document.removeEventListener('click', this.clickOutsideHandler);
+      this.clickOutsideHandler = null;
+    }
+  }
+
+  /**
+   * Render the comment input form
+   */
+  renderInputForm(
+    onSave: (body: string, tags: CommentTag[]) => void,
+    onCancel: () => void,
+    initialTags?: CommentTag[]
+  ): HTMLElement {
+    const form = document.createElement('div');
+    form.className = 'mdview-comment-input';
+
+    const selectedTags = new Set<CommentTag>(initialTags ?? []);
+
+    const textarea = document.createElement('textarea');
+    textarea.placeholder = 'Add a comment...';
+    textarea.rows = 3;
+
+    const getSelectedTags = (): CommentTag[] =>
+      ALL_TAGS.filter((t) => selectedTags.has(t));
+
+    // Cmd+Enter or Ctrl+Enter to save
+    textarea.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        onSave(textarea.value, getSelectedTags());
+      }
+    });
+
+    // Tag picker
+    const picker = document.createElement('div');
+    picker.className = 'comment-tag-picker';
+    for (const tag of ALL_TAGS) {
+      const pill = document.createElement('span');
+      pill.className = `comment-tag-option comment-tag-option--${tag}`;
+      pill.textContent = tag;
+      if (selectedTags.has(tag)) {
+        pill.classList.add('active');
+      }
+      pill.addEventListener('click', () => {
+        if (selectedTags.has(tag)) {
+          selectedTags.delete(tag);
+          pill.classList.remove('active');
+        } else {
+          selectedTags.add(tag);
+          pill.classList.add('active');
+        }
+      });
+      picker.appendChild(pill);
+    }
+
+    const actions = document.createElement('div');
+    actions.className = 'mdview-comment-input-actions';
+
+    const saveBtn = document.createElement('button');
+    saveBtn.className = 'mdview-comment-btn-save';
+    saveBtn.textContent = 'Save';
+    saveBtn.addEventListener('click', () => {
+      onSave(textarea.value, getSelectedTags());
+    });
+
+    const cancelBtn = document.createElement('button');
+    cancelBtn.className = 'mdview-comment-btn-cancel';
+    cancelBtn.textContent = 'Cancel';
+    cancelBtn.addEventListener('click', () => {
+      onCancel();
+    });
+
+    actions.appendChild(saveBtn);
+    actions.appendChild(cancelBtn);
+
+    form.appendChild(textarea);
+    form.appendChild(picker);
+    form.appendChild(actions);
+
+    return form;
+  }
+
+  /**
+   * Show a toast notification
+   */
+  showToast(message: string, duration: number = 2000): void {
+    const toast = document.createElement('div');
+    toast.className = 'mdview-toast';
+    toast.textContent = message;
+    document.body.appendChild(toast);
+
+    // Add visible class after a frame for CSS transition
+    requestAnimationFrame(() => {
+      toast.classList.add('visible');
+    });
+
+    // Remove after duration
+    setTimeout(() => {
+      toast.remove();
+    }, duration);
+  }
+
+  /**
+   * Clean up all resources
+   */
+  destroy(): void {
+    this.closeOverflowMenu();
+
+    // Remove gutter (which also removes cards inside it)
+    if (this.gutter) {
+      this.gutter.remove();
+      this.gutter = null;
+    }
+
+    // Remove any cards that were not inside the gutter
+    for (const card of this.cards) {
+      card.remove();
+    }
+    this.cards = [];
+  }
+
+  /**
+   * Format an ISO date string as relative time
+   */
+  private formatRelativeTime(isoDate: string): string {
+    const date = new Date(isoDate);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffSeconds = Math.floor(diffMs / 1000);
+    const diffMinutes = Math.floor(diffSeconds / 60);
+    const diffHours = Math.floor(diffMinutes / 60);
+    const diffDays = Math.floor(diffHours / 24);
+
+    if (diffMinutes < 1) {
+      return 'just now';
+    }
+
+    if (diffMinutes < 60) {
+      return `${diffMinutes} minute${diffMinutes === 1 ? '' : 's'} ago`;
+    }
+
+    if (diffHours < 24) {
+      return `${diffHours} hour${diffHours === 1 ? '' : 's'} ago`;
+    }
+
+    if (diffDays < 7) {
+      return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
+    }
+
+    const months = [
+      'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+      'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+    ];
+    return `${months[date.getMonth()]} ${date.getDate()}, ${date.getFullYear()}`;
+  }
+}
diff --git a/src/comments/comment-highlight.ts b/src/comments/comment-highlight.ts
index 84e2241..ff458ce 100644
--- a/src/comments/comment-highlight.ts
+++ b/src/comments/comment-highlight.ts
@@ -1,241 +1 @@
-import type { Comment } from '../types';
-
-const HIGHLIGHT_CLASS = 'mdview-comment-highlight';
-const COMMENT_ID_ATTR = 'data-comment-id';
-
-/**
- * Manages text highlighting in the rendered DOM for margin comments.
- *
- * Uses TreeWalker to locate text nodes and the Range API to wrap
- * matched substrings without disrupting the surrounding DOM structure.
- * Supports selections that span across inline element boundaries.
- */
-export class CommentHighlighter {
-  /**
-   * Find text within `container` that matches `selectedText`,
-   * wrap the matching portions in highlight `<span>` elements,
-   * and return the first span (used for card positioning).
-   *
-   * Handles text that spans across inline elements (e.g. bold, italic, code)
-   * by wrapping each text node portion separately with the same comment ID.
-   *
-   * Returns `null` if no matching text is found.
-   */
-  highlightComment(
-    container: HTMLElement,
-    comment: Comment
-  ): HTMLElement | null {
-    const { selectedText, id, resolved } = comment;
-
-    // Collect all text nodes and build a concatenated string
-    const textNodes: Text[] = [];
-    const walker = document.createTreeWalker(
-      container,
-      NodeFilter.SHOW_TEXT,
-      null
-    );
-    let node: Text | null;
-    while ((node = walker.nextNode() as Text | null)) {
-      textNodes.push(node);
-    }
-
-    // Build concatenated text with offset mappings.
-    // Insert a synthetic space between text nodes in different block-level
-    // parents so cross-block selections can match even when the DOM has no
-    // whitespace text node between adjacent block elements.
-    const BLOCK_TAGS = new Set([
-      'ADDRESS', 'ARTICLE', 'ASIDE', 'BLOCKQUOTE', 'DD', 'DETAILS', 'DIV',
-      'DL', 'DT', 'FIELDSET', 'FIGCAPTION', 'FIGURE', 'FOOTER', 'FORM',
-      'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'HEADER', 'HGROUP', 'HR',
-      'LI', 'MAIN', 'NAV', 'OL', 'P', 'PRE', 'SECTION', 'TABLE', 'UL',
-    ]);
-
-    const closestBlock = (node: Node): Element | null => {
-      let el: Node | null = node.parentNode;
-      while (el && el !== container) {
-        if (el.nodeType === Node.ELEMENT_NODE && BLOCK_TAGS.has((el as Element).tagName)) {
-          return el as Element;
-        }
-        el = el.parentNode;
-      }
-      return null;
-    };
-
-    let concat = '';
-    const nodeOffsets: Array<{ node: Text; start: number; end: number }> = [];
-    let prevBlock: Element | null = null;
-    for (const textNode of textNodes) {
-      const text = textNode.textContent ?? '';
-      const block = closestBlock(textNode);
-      // Insert a space when crossing block boundaries (if concat doesn't
-      // already end with whitespace)
-      if (
-        prevBlock !== null &&
-        block !== prevBlock &&
-        concat.length > 0 &&
-        !/\s$/.test(concat)
-      ) {
-        concat += ' ';
-      }
-      prevBlock = block;
-      const start = concat.length;
-      concat += text;
-      nodeOffsets.push({ node: textNode, start, end: concat.length });
-    }
-
-    // Find the selected text in the concatenated string.
-    // Try exact match first; fall back to whitespace-normalized match
-    // for cross-block selections where the browser inserts \n between
-    // block elements that may differ from the DOM text nodes.
-    let matchIndex = concat.indexOf(selectedText);
-    let matchEnd: number;
-
-    if (matchIndex !== -1) {
-      matchEnd = matchIndex + selectedText.length;
-    } else {
-      // Build a mapping from normalized offsets back to original offsets
-      const normalizedChars: number[] = []; // normalizedChars[i] = original index
-      let prevWs = false;
-      for (let i = 0; i < concat.length; i++) {
-        const isWs = /\s/.test(concat[i]);
-        if (isWs && prevWs) continue; // collapse consecutive whitespace
-        normalizedChars.push(i);
-        prevWs = isWs;
-      }
-      const normalizedConcat = normalizedChars
-        .map((i) => (/\s/.test(concat[i]) ? ' ' : concat[i]))
-        .join('');
-      const normalizedSearch = selectedText.replace(/\s+/g, ' ');
-
-      const normIdx = normalizedConcat.indexOf(normalizedSearch);
-      if (normIdx === -1) {
-        return null;
-      }
-
-      matchIndex = normalizedChars[normIdx];
-      // Map the end: normIdx + normalizedSearch.length may be past the end
-      const normEnd = normIdx + normalizedSearch.length;
-      matchEnd = normEnd < normalizedChars.length
-        ? normalizedChars[normEnd]
-        : concat.length;
-    }
-
-    // Find which text nodes overlap with the match
-    const overlapping = nodeOffsets.filter(
-      (entry) => entry.start < matchEnd && entry.end > matchIndex
-    );
-
-    if (overlapping.length === 0) {
-      return null;
-    }
-
-    // Single text node — use the simple Range.surroundContents approach
-    if (overlapping.length === 1) {
-      const entry = overlapping[0];
-      const localStart = matchIndex - entry.start;
-      const localEnd = localStart + selectedText.length;
-
-      const range = document.createRange();
-      range.setStart(entry.node, localStart);
-      range.setEnd(entry.node, localEnd);
-
-      const span = document.createElement('span');
-      span.className = HIGHLIGHT_CLASS;
-      if (resolved) {
-        span.classList.add('resolved');
-      }
-      span.setAttribute(COMMENT_ID_ATTR, id);
-
-      range.surroundContents(span);
-      return span;
-    }
-
-    // Cross-node: wrap each overlapping text node's matched portion
-    let firstSpan: HTMLElement | null = null;
-
-    // Process in reverse order so DOM mutations don't shift subsequent nodes
-    for (let i = overlapping.length - 1; i >= 0; i--) {
-      const entry = overlapping[i];
-      const localStart = Math.max(0, matchIndex - entry.start);
-      const localEnd = Math.min(
-        entry.node.textContent?.length ?? 0,
-        matchEnd - entry.start
-      );
-
-      const range = document.createRange();
-      range.setStart(entry.node, localStart);
-      range.setEnd(entry.node, localEnd);
-
-      const span = document.createElement('span');
-      span.className = HIGHLIGHT_CLASS;
-      if (resolved) {
-        span.classList.add('resolved');
-      }
-      span.setAttribute(COMMENT_ID_ATTR, id);
-
-      range.surroundContents(span);
-      firstSpan = span;
-    }
-
-    return firstSpan;
-  }
-
-  /**
-   * Remove all highlight spans for `commentId`, replacing each with its
-   * plain text content and normalising adjacent text nodes.
-   */
-  removeHighlight(commentId: string): void {
-    const spans = document.querySelectorAll(
-      `.${HIGHLIGHT_CLASS}[${COMMENT_ID_ATTR}="${commentId}"]`
-    );
-
-    for (const span of spans) {
-      const parent = span.parentNode;
-      if (!parent) continue;
-
-      const textNode = document.createTextNode(span.textContent ?? '');
-      parent.replaceChild(textNode, span);
-      parent.normalize();
-    }
-  }
-
-  /**
-   * Mark the highlight span for `commentId` as active (adds `.active` class).
-   */
-  setActive(commentId: string): void {
-    const span = this.getHighlightElement(commentId);
-    if (span) {
-      span.classList.add('active');
-    }
-  }
-
-  /**
-   * Remove the `.active` class from all highlight spans in the document.
-   */
-  clearActive(): void {
-    const spans = document.querySelectorAll(`.${HIGHLIGHT_CLASS}.active`);
-    for (const span of spans) {
-      span.classList.remove('active');
-    }
-  }
-
-  /**
-   * Mark the highlight span for `commentId` as resolved (adds `.resolved` class).
-   */
-  setResolved(commentId: string): void {
-    const span = this.getHighlightElement(commentId);
-    if (span) {
-      span.classList.add('resolved');
-    }
-  }
-
-  /**
-   * Return the first highlight `<span>` for the given `commentId`, or `null`
-   * if it does not exist in the document.
-   */
-  getHighlightElement(commentId: string): HTMLElement | null {
-    return document.querySelector<HTMLElement>(
-      `.${HIGHLIGHT_CLASS}[${COMMENT_ID_ATTR}="${commentId}"]`
-    );
-  }
-}
+export * from '../../packages/core/src/comments/comment-highlight';
diff --git a/src/comments/comment-ui.ts b/src/comments/comment-ui.ts
index 31cc63f..d7c05ba 100644
--- a/src/comments/comment-ui.ts
+++ b/src/comments/comment-ui.ts
@@ -1,615 +1 @@
-/**
- * Comment UI Module
- * Renders margin comment cards, input form, reply forms, reaction pills,
- * emoji picker, and overflow menus.
- * Dispatches custom events for all user actions.
- */
-
-import type { Comment, CommentTag, CommentReply, CommentReactions } from '../types';
-import { QUICK_EMOJIS, EMOJI_CATEGORIES, searchEmojis } from './emoji-data';
-
-const ALL_TAGS: CommentTag[] = [
-  'blocking', 'nit', 'suggestion', 'question', 'praise', 'todo', 'fyi',
-];
-
-export class CommentUI {
-  private gutter: HTMLElement | null = null;
-  private cards: HTMLElement[] = [];
-  private activeMenu: HTMLElement | null = null;
-  private clickOutsideHandler: ((e: MouseEvent) => void) | null = null;
-  private currentAuthor: string = '';
-
-  /**
-   * Set the current author name (used for reaction pill .mine class)
-   */
-  setCurrentAuthor(author: string): void {
-    this.currentAuthor = author;
-  }
-
-  /**
-   * Create the comment gutter container
-   */
-  createGutter(): HTMLElement {
-    this.gutter = document.createElement('div');
-    this.gutter.className = 'mdview-comment-gutter';
-    return this.gutter;
-  }
-
-  /**
-   * Render a comment card element
-   */
-  renderCard(comment: Comment): HTMLElement {
-    const card = document.createElement('div');
-    card.className = 'mdview-comment-card minimized';
-    card.dataset.commentId = comment.id;
-
-    if (comment.resolved) {
-      card.classList.add('resolved');
-    }
-
-    // Header
-    const header = document.createElement('div');
-    header.className = 'comment-header';
-
-    const author = document.createElement('strong');
-    author.className = 'comment-author';
-    author.textContent = comment.author || 'Anonymous';
-
-    const date = document.createElement('span');
-    date.className = 'comment-date';
-    date.textContent = this.formatRelativeTime(comment.date);
-
-    const menuBtn = document.createElement('button');
-    menuBtn.className = 'comment-menu-btn';
-    menuBtn.textContent = '\u2026'; // ellipsis character
-    menuBtn.setAttribute('aria-label', 'Comment actions');
-    menuBtn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      this.showOverflowMenu(comment.id, menuBtn);
-    });
-
-    header.appendChild(author);
-    header.appendChild(date);
-    header.appendChild(menuBtn);
-
-    // Body
-    const body = document.createElement('div');
-    body.className = 'comment-body';
-    body.textContent = comment.body;
-
-    card.appendChild(header);
-
-    // Snippet (visible only when minimized, via CSS)
-    const snippet = document.createElement('div');
-    snippet.className = 'comment-snippet';
-    const maxLen = 60;
-    snippet.textContent = comment.body.length > maxLen
-      ? comment.body.slice(0, maxLen) + '...'
-      : comment.body;
-    card.appendChild(snippet);
-
-    // Tag pills
-    if (comment.tags && comment.tags.length > 0) {
-      const tagsContainer = document.createElement('div');
-      tagsContainer.className = 'comment-tags';
-      for (const tag of comment.tags) {
-        const pill = document.createElement('span');
-        pill.className = `comment-tag comment-tag--${tag}`;
-        pill.textContent = tag;
-        tagsContainer.appendChild(pill);
-      }
-      card.appendChild(tagsContainer);
-    }
-
-    card.appendChild(body);
-
-    // Replies
-    if (comment.replies && comment.replies.length > 0) {
-      card.appendChild(this.renderReplies(comment.replies));
-    }
-
-    // Reply button (non-resolved only)
-    if (!comment.resolved) {
-      const replyBtn = document.createElement('button');
-      replyBtn.className = 'comment-reply-btn';
-      replyBtn.textContent = 'Reply';
-      replyBtn.addEventListener('click', (e) => {
-        e.stopPropagation();
-        document.dispatchEvent(
-          new CustomEvent('mdview:comment:reply', {
-            detail: { commentId: comment.id },
-          })
-        );
-      });
-      card.appendChild(replyBtn);
-    }
-
-    // Reactions
-    if (this.currentAuthor) {
-      card.appendChild(this.renderReactions(comment.id, comment.reactions ?? {}));
-    }
-
-    // Resolved badge
-    if (comment.resolved) {
-      const badge = document.createElement('span');
-      badge.className = 'resolved-badge';
-      badge.textContent = 'Resolved';
-      card.appendChild(badge);
-    }
-
-    // Click toggles minimized/expanded state
-    card.addEventListener('click', () => {
-      const wasMinimized = card.classList.contains('minimized');
-      card.classList.toggle('minimized');
-
-      // Only focus the highlight when expanding
-      if (wasMinimized) {
-        document.dispatchEvent(
-          new CustomEvent('mdview:comment:focus', {
-            detail: { commentId: comment.id },
-          })
-        );
-      }
-
-      // Always reposition after size change
-      document.dispatchEvent(new CustomEvent('mdview:comment:reposition'));
-    });
-
-    this.cards.push(card);
-    return card;
-  }
-
-  /**
-   * Render replies section
-   */
-  private renderReplies(replies: CommentReply[]): HTMLElement {
-    const container = document.createElement('div');
-    container.className = 'comment-replies';
-
-    for (const reply of replies) {
-      const replyEl = document.createElement('div');
-      replyEl.className = 'comment-reply';
-
-      const replyHeader = document.createElement('div');
-      replyHeader.className = 'comment-reply-header';
-
-      const replyAuthor = document.createElement('strong');
-      replyAuthor.className = 'comment-reply-author';
-      replyAuthor.textContent = reply.author || 'Anonymous';
-
-      const replyDate = document.createElement('span');
-      replyDate.className = 'comment-reply-date';
-      replyDate.textContent = this.formatRelativeTime(reply.date);
-
-      replyHeader.appendChild(replyAuthor);
-      replyHeader.appendChild(replyDate);
-
-      const replyBody = document.createElement('div');
-      replyBody.className = 'comment-reply-body';
-      replyBody.textContent = reply.body;
-
-      replyEl.appendChild(replyHeader);
-      replyEl.appendChild(replyBody);
-      container.appendChild(replyEl);
-    }
-
-    return container;
-  }
-
-  /**
-   * Render reaction pills and "+" button
-   */
-  private renderReactions(commentId: string, reactions: CommentReactions): HTMLElement {
-    const container = document.createElement('div');
-    container.className = 'comment-reactions';
-
-    const emojis = Object.keys(reactions);
-    for (const emoji of emojis) {
-      const authors = reactions[emoji];
-      if (!authors || authors.length === 0) continue;
-
-      const pill = document.createElement('button');
-      pill.className = 'comment-reaction';
-      if (this.currentAuthor && authors.includes(this.currentAuthor)) {
-        pill.classList.add('mine');
-      }
-      pill.textContent = `${emoji} ${authors.length}`;
-      pill.dataset.emoji = emoji;
-      pill.addEventListener('click', (e) => {
-        e.stopPropagation();
-        document.dispatchEvent(
-          new CustomEvent('mdview:comment:react', {
-            detail: { commentId, emoji },
-          })
-        );
-      });
-      container.appendChild(pill);
-    }
-
-    // "+" add reaction button
-    const addBtn = document.createElement('button');
-    addBtn.className = 'comment-reaction-add';
-    addBtn.textContent = '+';
-    addBtn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      document.dispatchEvent(
-        new CustomEvent('mdview:comment:react:picker', {
-          detail: { commentId, anchor: addBtn },
-        })
-      );
-    });
-    container.appendChild(addBtn);
-
-    return container;
-  }
-
-  /**
-   * Render a compact reply form (no tag picker)
-   */
-  renderReplyForm(
-    onSave: (body: string) => void,
-    onCancel: () => void
-  ): HTMLElement {
-    const form = document.createElement('div');
-    form.className = 'comment-reply-form';
-
-    const textarea = document.createElement('textarea');
-    textarea.placeholder = 'Write a reply...';
-    textarea.rows = 2;
-
-    textarea.addEventListener('keydown', (e) => {
-      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
-        e.preventDefault();
-        onSave(textarea.value);
-      }
-    });
-
-    const actions = document.createElement('div');
-    actions.className = 'mdview-comment-input-actions';
-
-    const saveBtn = document.createElement('button');
-    saveBtn.className = 'mdview-comment-btn-save';
-    saveBtn.textContent = 'Save';
-    saveBtn.addEventListener('click', () => {
-      onSave(textarea.value);
-    });
-
-    const cancelBtn = document.createElement('button');
-    cancelBtn.className = 'mdview-comment-btn-cancel';
-    cancelBtn.textContent = 'Cancel';
-    cancelBtn.addEventListener('click', () => {
-      onCancel();
-    });
-
-    actions.appendChild(saveBtn);
-    actions.appendChild(cancelBtn);
-
-    form.appendChild(textarea);
-    form.appendChild(actions);
-
-    return form;
-  }
-
-  /**
-   * Render the emoji picker
-   */
-  renderEmojiPicker(
-    _anchor: HTMLElement,
-    onSelect: (emoji: string) => void,
-    onClose: () => void
-  ): HTMLElement {
-    const picker = document.createElement('div');
-    picker.className = 'mdview-emoji-picker';
-
-    // Quick palette row
-    const quickRow = document.createElement('div');
-    quickRow.className = 'emoji-picker-quick';
-    for (const emoji of QUICK_EMOJIS) {
-      const btn = document.createElement('button');
-      btn.textContent = emoji.char;
-      btn.title = emoji.name;
-      btn.addEventListener('click', (e) => {
-        e.stopPropagation();
-        onSelect(emoji.char);
-      });
-      quickRow.appendChild(btn);
-    }
-    picker.appendChild(quickRow);
-
-    // Search input
-    const searchInput = document.createElement('input');
-    searchInput.className = 'emoji-picker-search';
-    searchInput.type = 'text';
-    searchInput.placeholder = 'Search emojis...';
-    picker.appendChild(searchInput);
-
-    // Categorized grid
-    const grid = document.createElement('div');
-    grid.className = 'emoji-picker-grid';
-    this.renderEmojiGrid(grid, EMOJI_CATEGORIES, onSelect);
-    picker.appendChild(grid);
-
-    // Search filtering
-    searchInput.addEventListener('input', () => {
-      const query = searchInput.value.trim();
-      if (query) {
-        const results = searchEmojis(query);
-        grid.innerHTML = '';
-        const catName = document.createElement('div');
-        catName.className = 'emoji-picker-category-name';
-        catName.textContent = 'Search Results';
-        grid.appendChild(catName);
-        for (const emoji of results) {
-          const btn = document.createElement('button');
-          btn.textContent = emoji.char;
-          btn.title = emoji.name;
-          btn.addEventListener('click', (e) => {
-            e.stopPropagation();
-            onSelect(emoji.char);
-          });
-          grid.appendChild(btn);
-        }
-      } else {
-        grid.innerHTML = '';
-        this.renderEmojiGrid(grid, EMOJI_CATEGORIES, onSelect);
-      }
-    });
-
-    // Click-outside to dismiss
-    const clickOutsideHandler = (e: MouseEvent) => {
-      const target = e.target as Node;
-      if (!picker.contains(target)) {
-        document.removeEventListener('click', clickOutsideHandler);
-        onClose();
-      }
-    };
-    document.addEventListener('click', clickOutsideHandler);
-
-    return picker;
-  }
-
-  /**
-   * Render the categorized emoji grid into a container
-   */
-  private renderEmojiGrid(
-    container: HTMLElement,
-    categories: typeof EMOJI_CATEGORIES,
-    onSelect: (emoji: string) => void
-  ): void {
-    for (const cat of categories) {
-      const catName = document.createElement('div');
-      catName.className = 'emoji-picker-category-name';
-      catName.textContent = cat.name;
-      container.appendChild(catName);
-
-      for (const emoji of cat.emojis) {
-        const btn = document.createElement('button');
-        btn.textContent = emoji.char;
-        btn.title = emoji.name;
-        btn.addEventListener('click', (e) => {
-          e.stopPropagation();
-          onSelect(emoji.char);
-        });
-        container.appendChild(btn);
-      }
-    }
-  }
-
-  /**
-   * Show the overflow menu for a comment card
-   */
-  private showOverflowMenu(commentId: string, anchorElement: HTMLElement): void {
-    // Close any existing menu first
-    this.closeOverflowMenu();
-
-    const menu = document.createElement('div');
-    menu.className = 'mdview-comment-menu';
-    menu.setAttribute('role', 'menu');
-
-    const actions = [
-      { label: 'Edit', event: 'mdview:comment:edit' },
-      { label: 'Resolve', event: 'mdview:comment:resolve' },
-      { label: 'Delete', event: 'mdview:comment:delete' },
-    ];
-
-    for (const action of actions) {
-      const item = document.createElement('button');
-      item.className = 'mdview-comment-menu-item';
-      item.setAttribute('role', 'menuitem');
-      item.textContent = action.label;
-
-      item.addEventListener('click', (e) => {
-        e.stopPropagation();
-        document.dispatchEvent(
-          new CustomEvent(action.event, {
-            detail: { commentId },
-          })
-        );
-        this.closeOverflowMenu();
-      });
-
-      menu.appendChild(item);
-    }
-
-    // Position relative to anchor
-    anchorElement.parentElement?.appendChild(menu);
-    this.activeMenu = menu;
-
-    // Setup click-outside handler. The menu button uses stopPropagation,
-    // so registering synchronously is safe.
-    this.clickOutsideHandler = (e: MouseEvent) => {
-      const target = e.target as Node;
-      if (this.activeMenu && !this.activeMenu.contains(target)) {
-        this.closeOverflowMenu();
-      }
-    };
-
-    document.addEventListener('click', this.clickOutsideHandler);
-  }
-
-  /**
-   * Close the currently open overflow menu
-   */
-  private closeOverflowMenu(): void {
-    if (this.activeMenu) {
-      this.activeMenu.remove();
-      this.activeMenu = null;
-    }
-
-    if (this.clickOutsideHandler) {
-      document.removeEventListener('click', this.clickOutsideHandler);
-      this.clickOutsideHandler = null;
-    }
-  }
-
-  /**
-   * Render the comment input form
-   */
-  renderInputForm(
-    onSave: (body: string, tags: CommentTag[]) => void,
-    onCancel: () => void,
-    initialTags?: CommentTag[]
-  ): HTMLElement {
-    const form = document.createElement('div');
-    form.className = 'mdview-comment-input';
-
-    const selectedTags = new Set<CommentTag>(initialTags ?? []);
-
-    const textarea = document.createElement('textarea');
-    textarea.placeholder = 'Add a comment...';
-    textarea.rows = 3;
-
-    const getSelectedTags = (): CommentTag[] =>
-      ALL_TAGS.filter((t) => selectedTags.has(t));
-
-    // Cmd+Enter or Ctrl+Enter to save
-    textarea.addEventListener('keydown', (e) => {
-      if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
-        e.preventDefault();
-        onSave(textarea.value, getSelectedTags());
-      }
-    });
-
-    // Tag picker
-    const picker = document.createElement('div');
-    picker.className = 'comment-tag-picker';
-    for (const tag of ALL_TAGS) {
-      const pill = document.createElement('span');
-      pill.className = `comment-tag-option comment-tag-option--${tag}`;
-      pill.textContent = tag;
-      if (selectedTags.has(tag)) {
-        pill.classList.add('active');
-      }
-      pill.addEventListener('click', () => {
-        if (selectedTags.has(tag)) {
-          selectedTags.delete(tag);
-          pill.classList.remove('active');
-        } else {
-          selectedTags.add(tag);
-          pill.classList.add('active');
-        }
-      });
-      picker.appendChild(pill);
-    }
-
-    const actions = document.createElement('div');
-    actions.className = 'mdview-comment-input-actions';
-
-    const saveBtn = document.createElement('button');
-    saveBtn.className = 'mdview-comment-btn-save';
-    saveBtn.textContent = 'Save';
-    saveBtn.addEventListener('click', () => {
-      onSave(textarea.value, getSelectedTags());
-    });
-
-    const cancelBtn = document.createElement('button');
-    cancelBtn.className = 'mdview-comment-btn-cancel';
-    cancelBtn.textContent = 'Cancel';
-    cancelBtn.addEventListener('click', () => {
-      onCancel();
-    });
-
-    actions.appendChild(saveBtn);
-    actions.appendChild(cancelBtn);
-
-    form.appendChild(textarea);
-    form.appendChild(picker);
-    form.appendChild(actions);
-
-    return form;
-  }
-
-  /**
-   * Show a toast notification
-   */
-  showToast(message: string, duration: number = 2000): void {
-    const toast = document.createElement('div');
-    toast.className = 'mdview-toast';
-    toast.textContent = message;
-    document.body.appendChild(toast);
-
-    // Add visible class after a frame for CSS transition
-    requestAnimationFrame(() => {
-      toast.classList.add('visible');
-    });
-
-    // Remove after duration
-    setTimeout(() => {
-      toast.remove();
-    }, duration);
-  }
-
-  /**
-   * Clean up all resources
-   */
-  destroy(): void {
-    this.closeOverflowMenu();
-
-    // Remove gutter (which also removes cards inside it)
-    if (this.gutter) {
-      this.gutter.remove();
-      this.gutter = null;
-    }
-
-    // Remove any cards that were not inside the gutter
-    for (const card of this.cards) {
-      card.remove();
-    }
-    this.cards = [];
-  }
-
-  /**
-   * Format an ISO date string as relative time
-   */
-  private formatRelativeTime(isoDate: string): string {
-    const date = new Date(isoDate);
-    const now = new Date();
-    const diffMs = now.getTime() - date.getTime();
-    const diffSeconds = Math.floor(diffMs / 1000);
-    const diffMinutes = Math.floor(diffSeconds / 60);
-    const diffHours = Math.floor(diffMinutes / 60);
-    const diffDays = Math.floor(diffHours / 24);
-
-    if (diffMinutes < 1) {
-      return 'just now';
-    }
-
-    if (diffMinutes < 60) {
-      return `${diffMinutes} minute${diffMinutes === 1 ? '' : 's'} ago`;
-    }
-
-    if (diffHours < 24) {
-      return `${diffHours} hour${diffHours === 1 ? '' : 's'} ago`;
-    }
-
-    if (diffDays < 7) {
-      return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
-    }
-
-    const months = [
-      'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
-      'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
-    ];
-    return `${months[date.getMonth()]} ${date.getDate()}, ${date.getFullYear()}`;
-  }
-}
+export * from '../../packages/core/src/comments/comment-ui';

From d07db38d2d85bbfd75f860a695814d82fa9df60d Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 09:11:55 -0400
Subject: [PATCH 20/26] refactor(core): move export modules to @mdview/core

---
 packages/core/package.json                   |   6 +-
 packages/core/src/export-controller.ts       | 137 ++++
 packages/core/src/index.ts                   |  13 +
 packages/core/src/utils/content-collector.ts | 415 ++++++++++++
 packages/core/src/utils/debug-logger.ts      |   6 +
 packages/core/src/utils/docx-generator.ts    | 627 ++++++++++++++++++
 packages/core/src/utils/pdf-generator.ts     | 460 ++++++++++++++
 packages/core/src/utils/svg-converter.ts     | 598 ++++++++++++++++++
 src/core/export-controller.ts                | 141 +----
 src/utils/content-collector.ts               | 419 +-----------
 src/utils/docx-generator.ts                  | 631 +------------------
 src/utils/pdf-generator.ts                   | 463 +-------------
 src/utils/svg-converter.ts                   | 601 +-----------------
 13 files changed, 2276 insertions(+), 2241 deletions(-)
 create mode 100644 packages/core/src/export-controller.ts
 create mode 100644 packages/core/src/utils/content-collector.ts
 create mode 100644 packages/core/src/utils/docx-generator.ts
 create mode 100644 packages/core/src/utils/pdf-generator.ts
 create mode 100644 packages/core/src/utils/svg-converter.ts

diff --git a/packages/core/package.json b/packages/core/package.json
index ad49e88..f10326c 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -13,13 +13,17 @@
     "test:ci": "vitest --run"
   },
   "dependencies": {
+    "@jamesainslie/docx": "^9.5.1-svg.1",
     "dompurify": "^3.0.6",
+    "highlight.js": "^11.9.0",
     "markdown-it": "^14.1.0",
     "markdown-it-anchor": "^8.6.7",
     "markdown-it-attrs": "^4.1.6",
     "markdown-it-emoji": "^3.0.0",
     "markdown-it-footnote": "^4.0.0",
-    "markdown-it-task-lists": "^2.1.1"
+    "markdown-it-task-lists": "^2.1.1",
+    "mermaid": "^11.12.1",
+    "panzoom": "^9.4.3"
   },
   "devDependencies": {
     "@types/dompurify": "^3.0.5",
diff --git a/packages/core/src/export-controller.ts b/packages/core/src/export-controller.ts
new file mode 100644
index 0000000..8a9edc1
--- /dev/null
+++ b/packages/core/src/export-controller.ts
@@ -0,0 +1,137 @@
+/**
+ * Export Controller
+ * Orchestrates the document export process
+ */
+
+import type { ExportOptions, ExportProgress, ProgressCallback, ExportFormat } from './types/index';
+import { ContentCollector } from './utils/content-collector';
+import { SVGConverter } from './utils/svg-converter';
+import { debug } from './utils/debug-logger';
+
+/**
+ * Controls the export process from content collection to file download
+ */
+export class ExportController {
+  /**
+   * Export the rendered markdown to the specified format
+   */
+  async export(
+    container: HTMLElement,
+    options: ExportOptions,
+    onProgress?: ProgressCallback
+  ): Promise<void> {
+    const report = (stage: ExportProgress['stage'], progress: number, message: string) => {
+      onProgress?.({ stage, progress, message });
+    };
+
+    try {
+      // Stage 0: Ensure all Mermaid diagrams are rendered (0-5%)
+      const mermaidContainers = container.querySelectorAll('.mermaid-container');
+      if (mermaidContainers.length > 0) {
+        report('collecting', 2, 'Rendering diagrams...');
+        try {
+          const { mermaidRenderer } = await import('./renderers/mermaid-renderer');
+          await mermaidRenderer.renderAllImmediate(container);
+        } catch (error) {
+          debug.warn('ExportController', 'Could not force-render Mermaid diagrams before export:', error);
+        }
+      }
+
+      // Stage 1: Collect content (5-20%)
+      report('collecting', 5, 'Analyzing document structure...');
+      const collector = new ContentCollector();
+      const content = collector.collect(container);
+      report('collecting', 20, `Found ${content.nodes.length} elements`);
+
+      debug.info(
+        'ExportController',
+        `Collected content: ${content.nodes.length} nodes, ${content.metadata.wordCount} words`
+      );
+
+      // Stage 2: Convert SVGs (20-50%)
+      report('converting', 25, 'Converting diagrams...');
+      const converter = new SVGConverter();
+      const svgNodeList = container.querySelectorAll<SVGElement>('.mermaid-container svg');
+      const svgs = Array.from(svgNodeList);
+
+      const images = converter.convertAll(svgs);
+      report('converting', 50, `Converted ${images.size} diagrams`);
+
+      debug.info('ExportController', `Converted ${images.size} SVG diagrams`);
+
+      // Stage 3: Generate document (50-90%)
+      if (options.format === 'docx') {
+        report('generating', 55, 'Generating Word document...');
+
+        // Dynamic import to avoid loading docx unless needed
+        const { DOCXGenerator } = await import('./utils/docx-generator');
+        const generator = new DOCXGenerator();
+
+        const blob = await generator.generate(content, images, {
+          title: options.filename || content.title,
+        });
+
+        report('generating', 90, 'Document ready');
+
+        // Stage 4: Download (90-100%)
+        report('downloading', 95, 'Preparing download...');
+        const filename = this.sanitizeFilename(options.filename || content.title);
+        await this.downloadBlob(blob, `${filename}.docx`);
+        report('downloading', 100, 'Download complete');
+
+        debug.info('ExportController', `Export complete: ${filename}.docx`);
+      } else {
+        throw new Error(`Unsupported export format: ${options.format}`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      debug.error('ExportController', 'Export failed:', error);
+      throw new Error(`Export failed: ${message}`);
+    }
+  }
+
+
+  /**
+   * Get list of supported export formats
+   */
+  getSupportedFormats(): ExportFormat[] {
+    return ['docx', 'pdf'];
+  }
+
+  /**
+   * Download a blob as a file
+   */
+  private async downloadBlob(blob: Blob, filename: string): Promise<void> {
+    const url = URL.createObjectURL(blob);
+
+    try {
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = filename;
+      a.style.display = 'none';
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+
+      // Wait a moment for download to start
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    } finally {
+      // Clean up the blob URL
+      URL.revokeObjectURL(url);
+    }
+  }
+
+  /**
+   * Sanitize a filename by removing invalid characters
+   */
+  private sanitizeFilename(name: string): string {
+    return (
+      name
+        .replace(/[<>:"/\\|?*]/g, '') // Remove invalid chars
+        .replace(/\s+/g, '-') // Replace spaces with dashes
+        .replace(/-+/g, '-') // Collapse multiple dashes
+        .replace(/^-|-$/g, '') // Remove leading/trailing dashes
+        .slice(0, 200) || 'document'
+    ); // Limit length with fallback
+  }
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 419a445..654bee1 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -73,6 +73,19 @@ export type { ThemeInfo, ThemeOverrides } from './theme-engine';
 export { RenderPipeline } from './render-pipeline';
 export type { RenderOptions, RenderProgress, ProgressCallback, RenderPipelineOptions } from './render-pipeline';
 
+// Renderers
+export { SyntaxHighlighter, syntaxHighlighter, SYNTAX_THEME_MAP } from './renderers/syntax-highlighter';
+export type { HighlightResult, DetectionResult } from './renderers/syntax-highlighter';
+export { MermaidRenderer, mermaidRenderer } from './renderers/mermaid-renderer';
+export type { MermaidOptions, DiagramControls } from './renderers/mermaid-renderer';
+
+// Export modules
+export { ContentCollector } from './utils/content-collector';
+export { SVGConverter } from './utils/svg-converter';
+export { DOCXGenerator } from './utils/docx-generator';
+export { PDFGenerator } from './utils/pdf-generator';
+export { ExportController } from './export-controller';
+
 // Platform adapters
 export * from './adapters';
 
diff --git a/packages/core/src/utils/content-collector.ts b/packages/core/src/utils/content-collector.ts
new file mode 100644
index 0000000..a8ee4f6
--- /dev/null
+++ b/packages/core/src/utils/content-collector.ts
@@ -0,0 +1,415 @@
+/**
+ * Content Collector
+ * Extracts structured content from rendered markdown DOM for export
+ */
+
+import type { ContentNode, CollectedContent } from '../types/index';
+import { debug } from './debug-logger';
+
+/**
+ * Collects and structures content from rendered markdown for export
+ */
+export class ContentCollector {
+  /**
+   * Main entry point - collects all content from container
+   */
+  collect(container: HTMLElement): CollectedContent {
+    debug.info('ContentCollector', 'Starting content collection');
+
+    const nodes: ContentNode[] = [];
+    const children = Array.from(container.children);
+
+    for (const child of children) {
+      const node = this.processElement(child as HTMLElement);
+      if (node) {
+        nodes.push(node);
+      }
+    }
+
+    const title = this.extractTitle(nodes);
+    const metadata = this.calculateMetadata(nodes);
+
+    debug.info('ContentCollector', `Collected ${nodes.length} nodes, title: "${title}"`);
+
+    return {
+      title,
+      nodes,
+      metadata,
+    };
+  }
+
+  /**
+   * Process a single HTML element into a ContentNode
+   */
+  private processElement(element: HTMLElement): ContentNode | null {
+    const tagName = element.tagName.toLowerCase();
+
+    switch (tagName) {
+      case 'h1':
+      case 'h2':
+      case 'h3':
+      case 'h4':
+      case 'h5':
+      case 'h6':
+        return this.processHeading(element);
+      case 'p':
+        return this.processParagraph(element);
+      case 'ul':
+      case 'ol':
+        return this.processList(element);
+      case 'pre':
+        return this.processCodeBlock(element);
+      case 'table':
+        return this.processTable(element);
+      case 'blockquote':
+        return this.processBlockquote(element);
+      case 'hr':
+        return { type: 'hr', content: '', attributes: {} };
+      case 'div':
+        // Check for mermaid container
+        if (element.classList.contains('mermaid-container')) {
+          return this.processMermaid(element);
+        }
+        // Recurse into generic divs
+        return this.processContainer(element);
+      default:
+        debug.debug('ContentCollector', `Skipping unsupported element: ${tagName}`);
+        return null;
+    }
+  }
+
+  /**
+   * Extract heading (H1-H6)
+   * Uses plain text content - no markdown link conversion
+   */
+  private processHeading(element: HTMLElement): ContentNode {
+    const level = parseInt(element.tagName.substring(1));
+    // Use textContent for headings - don't convert anchor links to markdown
+    const text = (element.textContent || '').trim();
+    const id = element.id || '';
+
+    return {
+      type: 'heading',
+      content: text,
+      attributes: {
+        level,
+        id,
+      },
+    };
+  }
+
+  /**
+   * Extract paragraph with inline formatting
+   */
+  private processParagraph(element: HTMLElement): ContentNode {
+    const content = this.extractInlineContent(element);
+
+    return {
+      type: 'paragraph',
+      content,
+      attributes: {},
+    };
+  }
+
+  /**
+   * Extract list (UL/OL) with nested support
+   */
+  private processList(element: HTMLElement): ContentNode {
+    const ordered = element.tagName.toLowerCase() === 'ol';
+    const children: ContentNode[] = [];
+
+    const items = Array.from(element.children);
+    for (const item of items) {
+      if (item.tagName.toLowerCase() === 'li') {
+        const liContent = this.processListItem(item as HTMLElement);
+        children.push(liContent);
+      }
+    }
+
+    return {
+      type: 'list',
+      content: children,
+      attributes: {
+        ordered,
+      },
+      children,
+    };
+  }
+
+  /**
+   * Process a single list item (may contain nested lists)
+   */
+  private processListItem(li: HTMLElement): ContentNode {
+    const children: ContentNode[] = [];
+    let textContent = '';
+
+    // Process child nodes
+    for (const child of Array.from(li.childNodes)) {
+      if (child.nodeType === Node.TEXT_NODE) {
+        textContent += child.textContent || '';
+      } else if (child.nodeType === Node.ELEMENT_NODE) {
+        const element = child as HTMLElement;
+        const tagName = element.tagName.toLowerCase();
+
+        if (tagName === 'ul' || tagName === 'ol') {
+          // Nested list
+          const nestedList = this.processList(element);
+          children.push(nestedList);
+        } else {
+          // Inline content
+          textContent += this.extractInlineContent(element);
+        }
+      }
+    }
+
+    return {
+      type: 'paragraph', // List items are treated as paragraphs
+      content: textContent.trim(),
+      attributes: {},
+      children: children.length > 0 ? children : undefined,
+    };
+  }
+
+  /**
+   * Extract code block
+   */
+  private processCodeBlock(element: HTMLElement): ContentNode {
+    const codeElement = element.querySelector('code');
+    const code = codeElement ? codeElement.textContent || '' : element.textContent || '';
+
+    // Try to extract language from class
+    let language = '';
+    if (codeElement) {
+      const classes = Array.from(codeElement.classList);
+      const langClass = classes.find((c) => c.startsWith('language-'));
+      if (langClass) {
+        language = langClass.replace('language-', '');
+      }
+    }
+
+    return {
+      type: 'code',
+      content: code,
+      attributes: {
+        language,
+      },
+    };
+  }
+
+  /**
+   * Extract table
+   */
+  private processTable(element: HTMLElement): ContentNode {
+    const rows: string[][] = [];
+
+    // Process thead and tbody
+    const thead = element.querySelector('thead');
+    const tbody = element.querySelector('tbody');
+
+    if (thead) {
+      const headerRows = thead.querySelectorAll('tr');
+      headerRows.forEach((tr) => {
+        const cells = Array.from(tr.querySelectorAll('th, td')).map((cell) =>
+          this.extractInlineContent(cell as HTMLElement)
+        );
+        rows.push(cells);
+      });
+    }
+
+    if (tbody) {
+      const bodyRows = tbody.querySelectorAll('tr');
+      bodyRows.forEach((tr) => {
+        const cells = Array.from(tr.querySelectorAll('th, td')).map((cell) =>
+          this.extractInlineContent(cell as HTMLElement)
+        );
+        rows.push(cells);
+      });
+    } else {
+      // No tbody, process all rows
+      const allRows = element.querySelectorAll('tr');
+      allRows.forEach((tr) => {
+        const cells = Array.from(tr.querySelectorAll('th, td')).map((cell) =>
+          this.extractInlineContent(cell as HTMLElement)
+        );
+        rows.push(cells);
+      });
+    }
+
+    return {
+      type: 'table',
+      content: JSON.stringify(rows),
+      attributes: {
+        rows: rows.length,
+        cols: rows[0]?.length || 0,
+      },
+    };
+  }
+
+  /**
+   * Extract blockquote
+   */
+  private processBlockquote(element: HTMLElement): ContentNode {
+    const children: ContentNode[] = [];
+
+    for (const child of Array.from(element.children)) {
+      const node = this.processElement(child as HTMLElement);
+      if (node) {
+        children.push(node);
+      }
+    }
+
+    return {
+      type: 'blockquote',
+      content: children,
+      attributes: {},
+      children,
+    };
+  }
+
+  /**
+   * Extract mermaid diagram container
+   */
+  private processMermaid(element: HTMLElement): ContentNode {
+    const id = element.id || '';
+    const svg = element.querySelector('svg');
+
+    return {
+      type: 'mermaid',
+      content: '',
+      attributes: {
+        id,
+        width: svg?.getAttribute('width') || '',
+        height: svg?.getAttribute('height') || '',
+      },
+    };
+  }
+
+  /**
+   * Process a container element (recurse into children)
+   */
+  private processContainer(element: HTMLElement): ContentNode | null {
+    const children: ContentNode[] = [];
+
+    for (const child of Array.from(element.children)) {
+      const node = this.processElement(child as HTMLElement);
+      if (node) {
+        children.push(node);
+      }
+    }
+
+    // If only one child, return it directly
+    if (children.length === 1) {
+      return children[0];
+    }
+
+    // If multiple children or none, return null (skip the container)
+    return null;
+  }
+
+  /**
+   * Extract inline content with formatting
+   * Preserves bold, italic, code, and links
+   */
+  private extractInlineContent(element: HTMLElement): string {
+    let result = '';
+
+    for (const node of Array.from(element.childNodes)) {
+      if (node.nodeType === Node.TEXT_NODE) {
+        result += node.textContent || '';
+      } else if (node.nodeType === Node.ELEMENT_NODE) {
+        const el = node as HTMLElement;
+        const tagName = el.tagName.toLowerCase();
+
+        switch (tagName) {
+          case 'strong':
+          case 'b':
+            result += `**${this.extractInlineContent(el)}**`;
+            break;
+          case 'em':
+          case 'i':
+            result += `*${this.extractInlineContent(el)}*`;
+            break;
+          case 'code':
+            result += `\`${el.textContent || ''}\``;
+            break;
+          case 'a': {
+            const href = el.getAttribute('href') || '';
+            const linkText = this.extractInlineContent(el);
+            // Internal anchor links (TOC) - just use text, no markdown syntax
+            if (href.startsWith('#')) {
+              result += linkText;
+            } else {
+              // External links - convert to markdown format
+              result += `[${linkText}](${href})`;
+            }
+            break;
+          }
+          case 'br':
+            result += '\n';
+            break;
+          default:
+            // For other elements, just get text content
+            result += this.extractInlineContent(el);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Extract title from nodes (first H1 or use "Untitled")
+   */
+  private extractTitle(nodes: ContentNode[]): string {
+    const firstHeading = nodes.find((node) => node.type === 'heading' && node.attributes.level === 1);
+    if (firstHeading && typeof firstHeading.content === 'string') {
+      return firstHeading.content;
+    }
+    return 'Untitled Document';
+  }
+
+  /**
+   * Calculate metadata from nodes
+   */
+  private calculateMetadata(nodes: ContentNode[]): CollectedContent['metadata'] {
+    let wordCount = 0;
+    let imageCount = 0;
+    let mermaidCount = 0;
+
+    const countWords = (text: string): number => {
+      return text.split(/\s+/).filter((word) => word.length > 0).length;
+    };
+
+    const processNode = (node: ContentNode): void => {
+      if (node.type === 'mermaid') {
+        mermaidCount++;
+      } else if (node.type === 'image') {
+        imageCount++;
+      }
+
+      if (typeof node.content === 'string') {
+        // Count words from string content
+        if (node.type === 'heading' || node.type === 'paragraph') {
+          wordCount += countWords(node.content);
+        }
+      } else if (Array.isArray(node.content)) {
+        // Recurse into children
+        node.content.forEach(processNode);
+      }
+
+      // Process children if present
+      if (node.children) {
+        node.children.forEach(processNode);
+      }
+    };
+
+    nodes.forEach(processNode);
+
+    return {
+      wordCount,
+      imageCount,
+      mermaidCount,
+      exportedAt: new Date(),
+    };
+  }
+}
diff --git a/packages/core/src/utils/debug-logger.ts b/packages/core/src/utils/debug-logger.ts
index 2dec0bb..a668545 100644
--- a/packages/core/src/utils/debug-logger.ts
+++ b/packages/core/src/utils/debug-logger.ts
@@ -178,3 +178,9 @@ export function createDebug(adapter?: StorageAdapter): DebugHelpers {
     isDebugEnabled: () => logger.getLogLevel() === 'debug',
   };
 }
+
+// ---------------------------------------------------------------------------
+// Default singleton — provides a zero-config `debug` object for core modules
+// that don't have access to a StorageAdapter.
+// ---------------------------------------------------------------------------
+export const debug: DebugHelpers = createDebug();
diff --git a/packages/core/src/utils/docx-generator.ts b/packages/core/src/utils/docx-generator.ts
new file mode 100644
index 0000000..109aa70
--- /dev/null
+++ b/packages/core/src/utils/docx-generator.ts
@@ -0,0 +1,627 @@
+/**
+ * DOCX Generator
+ * Converts structured content to Word documents using the docx library
+ */
+
+import {
+  Document,
+  Packer,
+  Paragraph,
+  TextRun,
+  Table,
+  TableRow,
+  TableCell,
+  ImageRun,
+  ExternalHyperlink,
+  AlignmentType,
+  HeadingLevel,
+  BorderStyle,
+  WidthType,
+  convertInchesToTwip,
+  type IStylesOptions,
+  type ISectionOptions,
+} from '@jamesainslie/docx';
+import type { CollectedContent, ConvertedImage, ContentNode, DOCXGeneratorOptions } from '../types/index';
+import { debug } from './debug-logger';
+
+/**
+ * Generates DOCX documents from collected content
+ */
+export class DOCXGenerator {
+  /**
+   * Generate a DOCX document from collected content
+   */
+  async generate(
+    content: CollectedContent,
+    images: Map<string, ConvertedImage>,
+    options: DOCXGeneratorOptions = {}
+  ): Promise<Blob> {
+    debug.info('DOCXGenerator', `Generating DOCX for "${content.title}"`);
+
+    const doc = new Document({
+      creator: options.author || 'MDView',
+      title: options.title || content.title,
+      description: 'Exported from MDView',
+      styles: this.createStyles(),
+      numbering: {
+        config: [
+          {
+            reference: 'default-numbering',
+            levels: [
+              {
+                level: 0,
+                format: 'decimal',
+                text: '%1.',
+                alignment: AlignmentType.START,
+                style: {
+                  paragraph: {
+                    indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.25) },
+                  },
+                },
+              },
+              {
+                level: 1,
+                format: 'decimal',
+                text: '%2.',
+                alignment: AlignmentType.START,
+                style: {
+                  paragraph: {
+                    indent: { left: convertInchesToTwip(1), hanging: convertInchesToTwip(0.25) },
+                  },
+                },
+              },
+              {
+                level: 2,
+                format: 'decimal',
+                text: '%3.',
+                alignment: AlignmentType.START,
+                style: {
+                  paragraph: {
+                    indent: { left: convertInchesToTwip(1.5), hanging: convertInchesToTwip(0.25) },
+                  },
+                },
+              },
+            ],
+          },
+          {
+            reference: 'bullet-numbering',
+            levels: [
+              {
+                level: 0,
+                format: 'bullet',
+                text: '\u2022',
+                alignment: AlignmentType.START,
+                style: {
+                  paragraph: {
+                    indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.25) },
+                  },
+                },
+              },
+              {
+                level: 1,
+                format: 'bullet',
+                text: '\u25E6',
+                alignment: AlignmentType.START,
+                style: {
+                  paragraph: {
+                    indent: { left: convertInchesToTwip(1), hanging: convertInchesToTwip(0.25) },
+                  },
+                },
+              },
+              {
+                level: 2,
+                format: 'bullet',
+                text: '\u25AA',
+                alignment: AlignmentType.START,
+                style: {
+                  paragraph: {
+                    indent: { left: convertInchesToTwip(1.5), hanging: convertInchesToTwip(0.25) },
+                  },
+                },
+              },
+            ],
+          },
+        ],
+      },
+      sections: [
+        {
+          properties: this.createPageProperties(options),
+          children: this.convertNodes(content.nodes, images),
+        },
+      ],
+    });
+
+    debug.info('DOCXGenerator', 'Converting document to blob');
+    const blob = await Packer.toBlob(doc);
+    debug.info('DOCXGenerator', `Generated DOCX blob (${blob.size} bytes)`);
+
+    return blob;
+  }
+
+  /**
+   * Create document styles - minimal approach like Pandoc
+   * Uses Aptos (modern Word default) or Calibri as fallback
+   */
+  private createStyles(): IStylesOptions {
+    return {
+      default: {
+        document: {
+          run: {
+            font: 'Aptos', // Modern Word default (falls back to Calibri if unavailable)
+            size: 24, // 12pt
+          },
+          paragraph: {
+            spacing: {
+              after: 200,
+            },
+          },
+        },
+        heading1: {
+          run: {
+            font: 'Aptos Display',
+            size: 40, // 20pt
+            color: '0F4761',
+          },
+        },
+        heading2: {
+          run: {
+            font: 'Aptos Display',
+            size: 32, // 16pt
+            color: '0F4761',
+          },
+        },
+        heading3: {
+          run: {
+            font: 'Aptos Display',
+            size: 28, // 14pt
+            color: '0F4761',
+          },
+        },
+        heading4: {
+          run: {
+            font: 'Aptos Display',
+            italics: true,
+            color: '0F4761',
+          },
+        },
+        heading5: {
+          run: {
+            font: 'Aptos Display',
+            color: '0F4761',
+          },
+        },
+        heading6: {
+          run: {
+            font: 'Aptos Display',
+            italics: true,
+            color: '595959',
+          },
+        },
+      },
+      paragraphStyles: [
+        {
+          id: 'Normal',
+          name: 'Normal',
+          quickFormat: true,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Standard paper sizes in inches (width x height in portrait)
+   */
+  private static readonly PAPER_SIZES: Record<string, { width: number; height: number }> = {
+    // ISO A-series (mm converted to inches)
+    A0: { width: 33.11, height: 46.81 }, // 841 x 1189 mm
+    A1: { width: 23.39, height: 33.11 }, // 594 x 841 mm
+    A3: { width: 11.69, height: 16.54 }, // 297 x 420 mm
+    A4: { width: 8.27, height: 11.69 }, // 210 x 297 mm
+    A5: { width: 5.83, height: 8.27 }, // 148 x 210 mm
+    A6: { width: 4.13, height: 5.83 }, // 105 x 148 mm
+    // North American sizes
+    Letter: { width: 8.5, height: 11.0 }, // 8.5 x 11 in
+    Legal: { width: 8.5, height: 14.0 }, // 8.5 x 14 in
+    Tabloid: { width: 11.0, height: 17.0 }, // 11 x 17 in
+    Executive: { width: 7.25, height: 10.5 }, // 7.25 x 10.5 in
+  };
+
+  /**
+   * Create page properties
+   */
+  private createPageProperties(options: DOCXGeneratorOptions): ISectionOptions['properties'] {
+    const pageSize = options.pageSize || 'A4';
+    const margins = options.margins || {
+      top: convertInchesToTwip(1),
+      bottom: convertInchesToTwip(1),
+      left: convertInchesToTwip(1),
+      right: convertInchesToTwip(1),
+    };
+
+    // Get paper dimensions, default to A4 if unknown
+    const paper = DOCXGenerator.PAPER_SIZES[pageSize] || DOCXGenerator.PAPER_SIZES.A4;
+    const pageDimensions = {
+      width: convertInchesToTwip(paper.width),
+      height: convertInchesToTwip(paper.height),
+    };
+
+    return {
+      page: {
+        size: pageDimensions,
+        margin: margins,
+      },
+    };
+  }
+
+  /**
+   * Convert content nodes to DOCX elements
+   */
+  private convertNodes(nodes: ContentNode[], images: Map<string, ConvertedImage>): (Paragraph | Table)[] {
+    const elements: (Paragraph | Table)[] = [];
+
+    for (const node of nodes) {
+      try {
+        switch (node.type) {
+          case 'heading':
+            elements.push(this.convertHeading(node));
+            break;
+          case 'paragraph':
+            elements.push(this.convertParagraph(node));
+            break;
+          case 'list':
+            elements.push(...this.convertList(node, 0));
+            break;
+          case 'code':
+            elements.push(...this.convertCodeBlock(node));
+            break;
+          case 'table':
+            elements.push(this.convertTable(node));
+            break;
+          case 'blockquote':
+            elements.push(...this.convertBlockquote(node, images));
+            break;
+          case 'mermaid': {
+            const mermaidPara = this.convertMermaid(node, images);
+            if (mermaidPara) {
+              elements.push(mermaidPara);
+            }
+            break;
+          }
+          case 'hr':
+            elements.push(this.convertHorizontalRule());
+            break;
+          default:
+            debug.warn('DOCXGenerator', `Unsupported node type: ${node.type}`);
+        }
+      } catch (error) {
+        debug.error('DOCXGenerator', `Error converting node type ${node.type}:`, error);
+      }
+    }
+
+    return elements;
+  }
+
+  /**
+   * Convert heading node
+   */
+  private convertHeading(node: ContentNode): Paragraph {
+    const level = (node.attributes.level as number) || 1;
+    const text = typeof node.content === 'string' ? node.content : '';
+
+    // Map heading level to HeadingLevel enum
+    const headingLevelMap: Record<number, (typeof HeadingLevel)[keyof typeof HeadingLevel]> = {
+      1: HeadingLevel.HEADING_1,
+      2: HeadingLevel.HEADING_2,
+      3: HeadingLevel.HEADING_3,
+      4: HeadingLevel.HEADING_4,
+      5: HeadingLevel.HEADING_5,
+      6: HeadingLevel.HEADING_6,
+    };
+
+    return new Paragraph({
+      text,
+      heading: headingLevelMap[level] || HeadingLevel.HEADING_1,
+    });
+  }
+
+  /**
+   * Convert paragraph node - plain text, no custom styling
+   */
+  private convertParagraph(node: ContentNode): Paragraph {
+    const text = typeof node.content === 'string' ? node.content : '';
+    const runs = this.parseInlineFormatting(text);
+
+    return new Paragraph({
+      children: runs,
+    });
+  }
+
+  /**
+   * Parse inline formatting from markdown-style text
+   */
+  private parseInlineFormatting(text: string): (TextRun | ExternalHyperlink)[] {
+    const children: (TextRun | ExternalHyperlink)[] = [];
+
+    // Pattern to match: **bold**, *italic*, `code`, [text](url), or plain text
+    const pattern = /(\*\*[^*]+\*\*)|(\*[^*]+\*)|(`[^`]+`)|(\[[^\]]+]\([^)]+\))|([^*`[]+)/g;
+
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      if (match[1]) {
+        // Bold: **text**
+        const boldText = match[1].slice(2, -2);
+        children.push(new TextRun({ text: boldText, bold: true }));
+      } else if (match[2]) {
+        // Italic: *text*
+        const italicText = match[2].slice(1, -1);
+        children.push(new TextRun({ text: italicText, italics: true }));
+      } else if (match[3]) {
+        // Inline code: `text` - monospace font
+        const codeText = match[3].slice(1, -1);
+        children.push(new TextRun({ text: codeText, font: 'Consolas' }));
+      } else if (match[4]) {
+        // Link: [text](url) - Word will style with default Hyperlink
+        const linkMatch = match[4].match(/\[([^\]]+)\]\(([^)]+)\)/);
+        if (linkMatch) {
+          children.push(
+            new ExternalHyperlink({
+              children: [new TextRun({ text: linkMatch[1] })],
+              link: linkMatch[2],
+            })
+          );
+        }
+      } else if (match[5]) {
+        // Plain text
+        children.push(new TextRun({ text: match[5] }));
+      }
+    }
+
+    // If no matches, return plain text
+    if (children.length === 0) {
+      children.push(new TextRun({ text }));
+    }
+
+    return children;
+  }
+
+  /**
+   * Convert list node (recursive for nested lists)
+   */
+  private convertList(node: ContentNode, level: number): Paragraph[] {
+    const paragraphs: Paragraph[] = [];
+    const ordered = node.attributes.ordered === true;
+
+    if (Array.isArray(node.content)) {
+      for (const item of node.content) {
+        if (item.type === 'paragraph') {
+          const text = typeof item.content === 'string' ? item.content : '';
+          const runs = this.parseInlineFormatting(text);
+
+          paragraphs.push(
+            new Paragraph({
+              children: runs,
+              numbering: ordered
+                ? { reference: 'default-numbering', level }
+                : { reference: 'bullet-numbering', level },
+            })
+          );
+
+          // Handle nested lists
+          if (item.children && item.children.length > 0) {
+            for (const child of item.children) {
+              if (child.type === 'list') {
+                paragraphs.push(...this.convertList(child, level + 1));
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return paragraphs;
+  }
+
+  /**
+   * Convert code block node - monospace font
+   */
+  private convertCodeBlock(node: ContentNode): Paragraph[] {
+    const code = typeof node.content === 'string' ? node.content : '';
+    const lines = code.split('\n');
+
+    return lines.map(
+      (line) =>
+        new Paragraph({
+          children: [
+            new TextRun({
+              text: line || ' ',
+              font: 'Consolas',
+            }),
+          ],
+        })
+    );
+  }
+
+  /**
+   * Convert table node - Pandoc style: header with bottom border only
+   */
+  private convertTable(node: ContentNode): Table {
+    const rowsData = JSON.parse(
+      typeof node.content === 'string' ? node.content : '[]'
+    ) as string[][];
+
+    const rows = rowsData.map(
+      (rowData, rowIndex) =>
+        new TableRow({
+          children: rowData.map(
+            (cellData) =>
+              new TableCell({
+                children: [
+                  new Paragraph({
+                    children: rowIndex === 0
+                      ? [new TextRun({ text: cellData, bold: true })]
+                      : this.parseInlineFormatting(cellData),
+                  }),
+                ],
+                // Header row: bottom border only (Pandoc style)
+                borders: rowIndex === 0
+                  ? {
+                      top: { style: BorderStyle.NONE, size: 0 },
+                      bottom: { style: BorderStyle.SINGLE, size: 6, color: '000000' },
+                      left: { style: BorderStyle.NONE, size: 0 },
+                      right: { style: BorderStyle.NONE, size: 0 },
+                    }
+                  : {
+                      top: { style: BorderStyle.NONE, size: 0 },
+                      bottom: { style: BorderStyle.NONE, size: 0 },
+                      left: { style: BorderStyle.NONE, size: 0 },
+                      right: { style: BorderStyle.NONE, size: 0 },
+                    },
+              })
+          ),
+        })
+    );
+
+    return new Table({
+      rows,
+      width: {
+        size: 100,
+        type: WidthType.PERCENTAGE,
+      },
+      // Remove table-level borders
+      borders: {
+        top: { style: BorderStyle.NONE, size: 0 },
+        bottom: { style: BorderStyle.NONE, size: 0 },
+        left: { style: BorderStyle.NONE, size: 0 },
+        right: { style: BorderStyle.NONE, size: 0 },
+        insideHorizontal: { style: BorderStyle.NONE, size: 0 },
+        insideVertical: { style: BorderStyle.NONE, size: 0 },
+      },
+    });
+  }
+
+  /**
+   * Convert blockquote node - indented text
+   */
+  private convertBlockquote(node: ContentNode, _images: Map<string, ConvertedImage>): Paragraph[] {
+    const paragraphs: Paragraph[] = [];
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) {
+        if (child.type === 'paragraph') {
+          const text = typeof child.content === 'string' ? child.content : '';
+          const runs = this.parseInlineFormatting(text);
+          paragraphs.push(
+            new Paragraph({
+              children: runs,
+              indent: { left: 720 }, // 0.5 inch indent
+            })
+          );
+        } else if (child.type === 'table') {
+          paragraphs.push(
+            new Paragraph({
+              children: [new TextRun({ text: '[Table in blockquote]' })],
+              indent: { left: 720 },
+            })
+          );
+        }
+      }
+    }
+
+    return paragraphs;
+  }
+
+  /**
+   * Convert mermaid diagram to embedded image.
+   * Supports both SVG (vector, preferred) and raster (PNG/JPEG) formats.
+   */
+  private convertMermaid(node: ContentNode, images: Map<string, ConvertedImage>): Paragraph | null {
+    const id = node.attributes.id as string;
+    const image = images.get(id);
+
+    if (!image) {
+      debug.warn('DOCXGenerator', `No image found for mermaid diagram: ${id}`);
+      return null;
+    }
+
+    // Convert base64 to Uint8Array (browser-safe, no Node Buffer dependency)
+    const binary = atob(image.data);
+    const length = binary.length;
+    const bytes = new Uint8Array(length);
+    for (let i = 0; i < length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+
+    // Calculate dimensions
+    // - Preserve aspect ratio
+    // - Scale uniformly to fit maxWidth
+    const maxWidth = 600; // Max width in document units (about 8.3 inches)
+    const scale = image.width > 0 ? Math.min(1, maxWidth / image.width) : 1;
+    const width = image.width * scale;
+    const height = image.height * scale;
+
+    // Determine if this is an SVG image
+    const isSvg = image.format === 'svg';
+
+    // For SVG images, use the forked docx library's SVG support
+    // which requires type: "svg" and a PNG fallback for older Word versions
+    if (isSvg) {
+      // Create a minimal 1x1 transparent PNG as fallback for older Word versions
+      // This is a base64-encoded 1x1 transparent PNG
+      const fallbackPngBase64 =
+        'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+      const fallbackBinary = atob(fallbackPngBase64);
+      const fallbackBytes = new Uint8Array(fallbackBinary.length);
+      for (let i = 0; i < fallbackBinary.length; i++) {
+        fallbackBytes[i] = fallbackBinary.charCodeAt(i);
+      }
+
+      return new Paragraph({
+        children: [
+          new ImageRun({
+            type: 'svg',
+            data: bytes,
+            transformation: {
+              width,
+              height,
+            },
+            fallback: {
+              type: 'png',
+              data: fallbackBytes,
+            },
+          }),
+        ],
+        alignment: AlignmentType.CENTER,
+      });
+    }
+
+    // For raster images (PNG, JPEG), use the standard approach with explicit type
+    return new Paragraph({
+      children: [
+        new ImageRun({
+          type: 'png', // Default to PNG for raster images
+          data: bytes,
+          transformation: {
+            width,
+            height,
+          },
+        }),
+      ],
+      alignment: AlignmentType.CENTER,
+    });
+  }
+
+  /**
+   * Convert horizontal rule
+   */
+  private convertHorizontalRule(): Paragraph {
+    return new Paragraph({
+      children: [new TextRun({ text: '' })],
+      border: {
+        bottom: {
+          style: BorderStyle.SINGLE,
+          size: 6,
+        },
+      },
+    });
+  }
+}
diff --git a/packages/core/src/utils/pdf-generator.ts b/packages/core/src/utils/pdf-generator.ts
new file mode 100644
index 0000000..d50d3bc
--- /dev/null
+++ b/packages/core/src/utils/pdf-generator.ts
@@ -0,0 +1,460 @@
+/**
+ * PDF Generator
+ * Handles PDF export via browser print with SVG-to-image conversion
+ */
+
+import type { PDFGeneratorOptions, ProgressCallback, ExportProgress } from '../types/index';
+import { debug } from './debug-logger';
+
+export class PDFGenerator {
+  private originalSvgs: Map<Element, { element: SVGElement; parent: Element; html: string }> =
+    new Map();
+  private printStyleElement: HTMLStyleElement | null = null;
+  private replacedImages: Element[] = [];
+
+  constructor() {
+    debug.info('PDFGenerator', 'PDF Generator initialized');
+  }
+
+  /**
+   * Prepare document for print and trigger print dialog
+   *
+   * Progress mapping:
+   * - 5-25%  : Collecting diagrams / DOM state
+   * - 30-80% : Converting SVG diagrams to images
+   * - 85-95% : Applying print styles and opening dialog
+   */
+  async print(
+    container: HTMLElement,
+    options: PDFGeneratorOptions = {},
+    onProgress?: ProgressCallback,
+    signal?: AbortSignal
+  ): Promise<void> {
+    debug.info('PDFGenerator', 'Starting print process');
+
+    try {
+      this.ensureNotAborted(signal);
+      this.reportProgress(onProgress, 'collecting', 5, 'Preparing document for print...');
+
+      // Ensure all Mermaid diagrams are rendered before conversion
+      this.reportProgress(onProgress, 'collecting', 15, 'Rendering diagrams...');
+      try {
+        const { mermaidRenderer } = await import('../renderers/mermaid-renderer');
+        // Bypass lazy loading: render every diagram in the container now
+        await mermaidRenderer.renderAllImmediate(container);
+      } catch (error) {
+        debug.warn('PDFGenerator', 'Could not force-render Mermaid diagrams:', error);
+      }
+
+      // Quick sanity check on diagram state
+      await this.waitForMermaidDiagrams(container);
+      this.ensureNotAborted(signal);
+      this.reportProgress(onProgress, 'collecting', 25, 'Diagrams ready for conversion');
+
+      // Prepare for print
+      if (options.convertSvgsToImages !== false) {
+        await this.prepareSvgsForPrint(container, options, onProgress, signal);
+      }
+
+      this.ensureNotAborted(signal);
+
+      this.reportProgress(onProgress, 'generating', 85, 'Applying print styles...');
+      this.addPrintClass();
+      this.injectPrintStyles(options);
+
+      // Small delay to ensure styles are applied
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      this.ensureNotAborted(signal);
+
+      // Trigger print
+      this.reportProgress(onProgress, 'generating', 90, 'Opening print dialog...');
+      debug.info('PDFGenerator', 'Opening print dialog');
+      window.print();
+
+      // Wait for dialog to close
+      await this.waitForPrintDialog();
+
+      this.reportProgress(onProgress, 'generating', 100, 'Print dialog closed');
+      debug.info('PDFGenerator', 'Print dialog closed');
+    } catch (error) {
+      debug.error('PDFGenerator', 'Print failed:', error);
+      throw error;
+    } finally {
+      // Restore state
+      this.restoreSvgs();
+      this.removePrintClass();
+      this.removePrintStyles();
+      debug.info('PDFGenerator', 'State restored after print');
+    }
+  }
+
+  /**
+   * Check for Mermaid diagrams - warn if any are still pending
+   */
+  private async waitForMermaidDiagrams(container: HTMLElement): Promise<void> {
+    // Get diagram counts
+    const readyCount = container.querySelectorAll('.mermaid-container.mermaid-ready').length;
+    const pendingCount = container.querySelectorAll('.mermaid-container.mermaid-pending').length;
+
+    if (readyCount === 0 && pendingCount === 0) {
+      debug.info('PDFGenerator', 'No Mermaid diagrams in document');
+      return;
+    }
+
+    debug.info('PDFGenerator', `Diagrams: ${readyCount} ready, ${pendingCount} pending`);
+
+    if (pendingCount > 0) {
+      debug.warn(
+        'PDFGenerator',
+        `${pendingCount} diagram(s) not yet rendered. Scroll through document first to render all diagrams.`
+      );
+    }
+
+    // Small delay to ensure DOM is stable
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  /**
+   * Convert SVGs to images for print compatibility
+   * Scales diagrams based on target page size to avoid squashing.
+   */
+  private prepareSvgsForPrint(
+    container: HTMLElement,
+    options: PDFGeneratorOptions,
+    onProgress?: ProgressCallback,
+    signal?: AbortSignal
+  ): Promise<void> {
+    debug.info('PDFGenerator', 'Preparing SVGs for print');
+
+    const svgs = container.querySelectorAll('.mermaid-container svg');
+    debug.info('PDFGenerator', `Found ${svgs.length} SVGs to convert`);
+
+    if (svgs.length === 0) {
+      return Promise.resolve();
+    }
+
+    const total = svgs.length;
+
+    const paperSize = options.paperSize ?? 'A4';
+    const margins = options.margins ?? '2cm';
+    const orientation = options.orientation ?? 'portrait';
+    const { width: maxContentWidth, height: maxContentHeight } = this.getPrintableContentBox(
+      paperSize,
+      margins,
+      orientation
+    );
+
+    this.reportProgress(
+      onProgress,
+      'converting',
+      30,
+      total === 1 ? 'Converting diagram for print...' : 'Converting diagrams for print...'
+    );
+
+    let index = 0;
+
+    for (const svg of svgs) {
+      this.ensureNotAborted(signal);
+
+      const svgElement = svg as SVGElement;
+      const parent = svg.parentElement;
+
+      if (!parent) {
+        debug.warn('PDFGenerator', 'SVG has no parent, skipping');
+        continue;
+      }
+
+      // Store original SVG and its parent
+      this.originalSvgs.set(svg, {
+        element: svgElement,
+        parent: parent,
+        html: svg.outerHTML,
+      });
+
+      // First, get the SVG's natural dimensions
+      const svgRect = svgElement.getBoundingClientRect();
+      const naturalWidth = svgRect.width || 800;
+      const naturalHeight = svgRect.height || 600;
+
+      // Compute the target dimensions to fit within one page
+      // Reserve 40px for borders, margins, and padding around the diagram
+      const reservedSpace = 40;
+      const availableWidth = maxContentWidth - reservedSpace;
+      const availableHeight = maxContentHeight - reservedSpace;
+
+      const scaleToWidth = availableWidth / naturalWidth;
+      const scaleToHeight = availableHeight / naturalHeight;
+      const scaleFactor = Math.min(1, scaleToWidth, scaleToHeight);
+
+      // Target dimensions in CSS pixels
+      const targetWidth = Math.round(naturalWidth * scaleFactor);
+      const targetHeight = Math.round(naturalHeight * scaleFactor);
+
+      debug.info(
+        'PDFGenerator',
+        `Diagram ${index}: natural=${naturalWidth.toFixed(0)}x${naturalHeight.toFixed(0)}, ` +
+          `maxContent=${maxContentWidth.toFixed(0)}x${maxContentHeight.toFixed(0)}, ` +
+          `scale=${scaleFactor.toFixed(3)}, target=${targetWidth}x${targetHeight}`
+      );
+
+      // For PDF export we prefer the browser's high-quality, theme-aware SVG
+      // rendering rather than the wasm-based PNGs used for DOCX. Here we
+      // simply clone and scale the SVG element itself so that labels and
+      // styling match what you see in the MDView page.
+      const scaledSvg = svgElement.cloneNode(true) as SVGElement;
+      scaledSvg.setAttribute('width', String(targetWidth));
+      scaledSvg.setAttribute('height', String(targetHeight));
+      scaledSvg.style.cssText = `
+        display: block !important;
+        width: ${targetWidth}px !important;
+        height: ${targetHeight}px !important;
+        max-width: ${maxContentWidth}px !important;
+        max-height: ${maxContentHeight}px !important;
+        margin: 8pt auto !important;
+        page-break-inside: avoid !important;
+        break-inside: avoid !important;
+      `;
+      const replacement = scaledSvg as unknown as HTMLElement;
+
+      debug.info('PDFGenerator', `Scaled SVG directly for print: ${targetWidth}x${targetHeight}`);
+
+      // Replace original SVG
+      parent.replaceChild(replacement, svg);
+      this.replacedImages.push(replacement);
+
+      index += 1;
+
+      // Progress update
+      const fraction = index / total;
+      const progress = 35 + Math.round(fraction * 45);
+      const message =
+        total === 1
+          ? 'Prepared diagram for print'
+          : `Preparing diagrams for print (${index}/${total})...`;
+      this.reportProgress(onProgress, 'converting', Math.min(progress, 80), message);
+    }
+
+    debug.info(
+      'PDFGenerator',
+      `Prepared ${this.replacedImages.length} SVGs for print (scaled SVGs)`
+    );
+
+    return Promise.resolve();
+  }
+
+  /**
+   * Restore original SVGs after print
+   */
+  private restoreSvgs(): void {
+    debug.info('PDFGenerator', 'Restoring original SVGs');
+
+    this.originalSvgs.forEach((data) => {
+      try {
+        // Find the img element that replaced this SVG
+        const img = this.replacedImages.find((el) => el.parentElement === data.parent);
+
+        if (img && data.parent) {
+          // Create a new SVG element from the stored HTML
+          const temp = document.createElement('div');
+          temp.innerHTML = data.html;
+          const restoredSvg = temp.firstElementChild;
+
+          if (restoredSvg) {
+            data.parent.replaceChild(restoredSvg, img);
+            debug.debug('PDFGenerator', 'Restored SVG');
+          }
+        }
+      } catch (error) {
+        debug.error('PDFGenerator', 'Failed to restore SVG:', error);
+      }
+    });
+
+    // Clear tracking
+    this.originalSvgs.clear();
+    this.replacedImages = [];
+
+    debug.info('PDFGenerator', 'SVG restoration complete');
+  }
+
+  /**
+   * Add print class to body
+   */
+  private addPrintClass(): void {
+    document.body.classList.add('mdview-printing');
+    debug.debug('PDFGenerator', 'Added print class');
+  }
+
+  /**
+   * Remove print class from body
+   */
+  private removePrintClass(): void {
+    document.body.classList.remove('mdview-printing');
+    debug.debug('PDFGenerator', 'Removed print class');
+  }
+
+  /**
+   * Inject dynamic print styles
+   */
+  private injectPrintStyles(options: PDFGeneratorOptions): void {
+    if (this.printStyleElement) {
+      this.removePrintStyles();
+    }
+
+    const { paperSize = 'A4', orientation = 'portrait', margins = '2cm' } = options;
+
+    const styles = `
+      @media print {
+        @page {
+          size: ${paperSize} ${orientation};
+          margin: ${margins};
+        }
+      }
+    `;
+
+    this.printStyleElement = document.createElement('style');
+    this.printStyleElement.id = 'mdview-dynamic-print-styles';
+    this.printStyleElement.textContent = styles;
+    document.head.appendChild(this.printStyleElement);
+
+    debug.debug(
+      'PDFGenerator',
+      `Injected print styles: ${paperSize} ${orientation}, margins: ${margins}`
+    );
+  }
+
+  /**
+   * Remove dynamic print styles
+   */
+  private removePrintStyles(): void {
+    if (this.printStyleElement) {
+      this.printStyleElement.remove();
+      this.printStyleElement = null;
+      debug.debug('PDFGenerator', 'Removed print styles');
+    }
+  }
+
+  /**
+   * Wait for print dialog to close (with short timeout)
+   */
+  private waitForPrintDialog(): Promise<void> {
+    return new Promise((resolve) => {
+      // The afterprint event fires when the dialog closes
+      const handler = () => {
+        window.removeEventListener('afterprint', handler);
+        setTimeout(resolve, 50);
+      };
+
+      window.addEventListener('afterprint', handler);
+
+      // Very short fallback - print dialog should open immediately
+      // If it doesn't fire within 2 seconds, just continue
+      setTimeout(() => {
+        window.removeEventListener('afterprint', handler);
+        resolve();
+      }, 2000);
+    });
+  }
+
+  /**
+   * Standard paper sizes in inches (width x height in portrait)
+   */
+  private static readonly PAPER_SIZES: Record<string, { width: number; height: number }> = {
+    // ISO A-series (mm converted to inches)
+    A0: { width: 33.11, height: 46.81 }, // 841 x 1189 mm
+    A1: { width: 23.39, height: 33.11 }, // 594 x 841 mm
+    A3: { width: 11.69, height: 16.54 }, // 297 x 420 mm
+    A4: { width: 8.27, height: 11.69 }, // 210 x 297 mm
+    A5: { width: 5.83, height: 8.27 }, // 148 x 210 mm
+    A6: { width: 4.13, height: 5.83 }, // 105 x 148 mm
+    // North American sizes
+    Letter: { width: 8.5, height: 11.0 }, // 8.5 x 11 in
+    Legal: { width: 8.5, height: 14.0 }, // 8.5 x 14 in
+    Tabloid: { width: 11.0, height: 17.0 }, // 11 x 17 in
+    Executive: { width: 7.25, height: 10.5 }, // 7.25 x 10.5 in
+  };
+
+  /**
+   * Helper: compute printable content box (width/height) in CSS pixels
+   */
+  private getPrintableContentBox(
+    paperSize: string,
+    margins: string,
+    orientation: 'portrait' | 'landscape'
+  ): { width: number; height: number } {
+    const dpi = 96; // CSS pixels per inch
+
+    // Get paper dimensions, default to A4 if unknown
+    const paper = PDFGenerator.PAPER_SIZES[paperSize] || PDFGenerator.PAPER_SIZES.A4;
+    let pageWidthInches = paper.width;
+    let pageHeightInches = paper.height;
+
+    // Swap for landscape
+    if (orientation === 'landscape') {
+      [pageWidthInches, pageHeightInches] = [pageHeightInches, pageWidthInches];
+    }
+
+    // Parse margin value; assume symmetric margins on all sides
+    let marginPx = (2 / 2.54) * dpi; // Default 2cm in px
+    const match = margins.match(/([\d.]+)\s*(cm|mm|in|px)/i);
+
+    if (match) {
+      const value = parseFloat(match[1]);
+      const unit = match[2].toLowerCase();
+
+      if (!Number.isNaN(value)) {
+        switch (unit) {
+          case 'cm':
+            marginPx = (value / 2.54) * dpi;
+            break;
+          case 'mm':
+            marginPx = (value / 25.4) * dpi;
+            break;
+          case 'in':
+            marginPx = value * dpi;
+            break;
+          case 'px':
+            marginPx = value;
+            break;
+        }
+      }
+    }
+
+    const totalMarginX = marginPx * 2;
+    const totalMarginY = marginPx * 2;
+
+    const pageWidthPx = pageWidthInches * dpi;
+    const pageHeightPx = pageHeightInches * dpi;
+
+    const contentWidth = pageWidthPx - totalMarginX;
+    const contentHeight = pageHeightPx - totalMarginY;
+
+    // Guard against negative or very small values
+    return {
+      width: Math.max(200, contentWidth),
+      height: Math.max(200, contentHeight),
+    };
+  }
+
+  /**
+   * Helper: report progress if a callback is provided
+   */
+  private reportProgress(
+    onProgress: ProgressCallback | undefined,
+    stage: ExportProgress['stage'],
+    progress: number,
+    message: string
+  ): void {
+    if (!onProgress) return;
+    onProgress({ stage, progress, message });
+  }
+
+  /**
+   * Helper: throw if an abort signal has been triggered
+   */
+  private ensureNotAborted(signal?: AbortSignal): void {
+    if (signal?.aborted) {
+      throw new DOMException('Export aborted', 'AbortError');
+    }
+  }
+}
diff --git a/packages/core/src/utils/svg-converter.ts b/packages/core/src/utils/svg-converter.ts
new file mode 100644
index 0000000..7b96b23
--- /dev/null
+++ b/packages/core/src/utils/svg-converter.ts
@@ -0,0 +1,598 @@
+/**
+ * SVG Converter
+ * Extracts SVG elements as vector images for document embedding.
+ *
+ * This implementation serializes SVG elements directly to XML strings,
+ * avoiding rasterization entirely. The forked docx library (jamesainslie/docx)
+ * supports embedding SVG images natively via mimeType: 'image/svg+xml'.
+ *
+ * Important: Mermaid diagrams use <foreignObject> elements for text labels
+ * in many diagram types. Word does not support <foreignObject>, so we
+ * convert these to native SVG <text> elements before export.
+ */
+
+import type { SVGConversionOptions, ConvertedImage } from '../types/index';
+import { debug } from './debug-logger';
+
+/**
+ * Converts SVG elements to embeddable image formats (now SVG-native)
+ */
+export class SVGConverter {
+  /**
+   * Convert a single SVG element to an embeddable image.
+   * Returns the SVG as a base64-encoded string with format 'svg'.
+   */
+  convert(svg: SVGElement, _options: SVGConversionOptions = {}): ConvertedImage {
+    // Prefer the Mermaid container ID so that it matches ContentCollector's
+    // mermaid node IDs (e.g. "mermaid-xyz"), falling back to the SVG ID.
+    const container = svg.closest<HTMLElement>('.mermaid-container');
+    const id = container?.id || svg.id || `svg-${Date.now()}`;
+
+    debug.info('SVGConverter', `Extracting SVG ${id} as vector image`);
+
+    // Get SVG dimensions
+    const { width, height } = this.getSVGDimensions(svg);
+
+    debug.debug('SVGConverter', `Dimensions: ${width}x${height}`);
+
+    // Clone and normalize the SVG for export
+    const exportSvg = this.prepareSvgForExport(svg, width, height);
+
+    // Convert foreignObject elements to native SVG text (for Word compatibility)
+    this.convertForeignObjectsToText(exportSvg);
+
+    // Serialize to string
+    let svgMarkup = new XMLSerializer().serializeToString(exportSvg);
+
+    // Post-process SVG string for Word compatibility
+    svgMarkup = this.fixSvgForWordCompatibility(svgMarkup);
+
+    // Base64 encode the SVG XML
+    const base64Data = this.stringToBase64(svgMarkup);
+
+    debug.info('SVGConverter', `Successfully extracted SVG ${id} (${width}x${height})`);
+
+    return {
+      id,
+      data: base64Data,
+      width,
+      height,
+      format: 'svg',
+    };
+  }
+
+  /**
+   * Prepare SVG for export: clone, set explicit dimensions, ensure namespace,
+   * and inline computed styles for Word compatibility.
+   */
+  private prepareSvgForExport(svg: SVGElement, width: number, height: number): SVGElement {
+    const clone = svg.cloneNode(true) as SVGElement;
+
+    // Set explicit dimensions
+    clone.setAttribute('width', String(width));
+    clone.setAttribute('height', String(height));
+
+    // Ensure xmlns attributes are present (required for standalone SVG)
+    if (!clone.getAttribute('xmlns')) {
+      clone.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+    }
+    if (!clone.getAttribute('xmlns:xlink')) {
+      clone.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink');
+    }
+
+    // Inline computed styles for all elements (Word doesn't process CSS well)
+    this.inlineAllStyles(svg, clone);
+
+    return clone;
+  }
+
+  /**
+   * Inline computed styles from the original SVG to the clone.
+   * This ensures all styling survives when embedded in Word.
+   */
+  private inlineAllStyles(originalSvg: SVGElement, cloneSvg: SVGElement): void {
+    // Get all elements that could have visual styles
+    const selectors = [
+      'path',
+      'line',
+      'polyline',
+      'polygon',
+      'rect',
+      'circle',
+      'ellipse',
+      'text',
+      'tspan',
+      'g',
+    ];
+
+    for (const selector of selectors) {
+      const originalElements = Array.from(originalSvg.querySelectorAll(selector));
+      const cloneElements = Array.from(cloneSvg.querySelectorAll(selector));
+
+      if (originalElements.length !== cloneElements.length) {
+        debug.debug(
+          'SVGConverter',
+          `Element count mismatch for "${selector}": ${originalElements.length} vs ${cloneElements.length}`
+        );
+        continue;
+      }
+
+      originalElements.forEach((originalEl, index) => {
+        const cloneEl = cloneElements[index] as SVGElement;
+        if (!cloneEl) return;
+
+        this.inlineSingleElementStyles(originalEl as SVGElement, cloneEl);
+      });
+    }
+
+    // Also process elements inside defs (markers, etc.)
+    this.inlineDefsStyles(originalSvg, cloneSvg);
+
+    debug.info('SVGConverter', 'Inlined all computed styles for Word compatibility');
+  }
+
+  /**
+   * Inline all relevant computed styles for a single element.
+   */
+  private inlineSingleElementStyles(original: SVGElement, clone: SVGElement): void {
+    try {
+      const computed = window.getComputedStyle(original);
+
+      // Common properties for all elements
+      const fill = computed.fill;
+      if (fill && fill !== 'none' && !fill.startsWith('url(')) {
+        clone.setAttribute('fill', fill);
+      } else if (!clone.hasAttribute('fill') && original.tagName.toLowerCase() !== 'g') {
+        // Preserve 'none' explicitly if that's what it should be
+        const originalFill = original.getAttribute('fill');
+        if (originalFill) {
+          clone.setAttribute('fill', originalFill);
+        }
+      }
+
+      const stroke = computed.stroke;
+      if (stroke && stroke !== 'none') {
+        clone.setAttribute('stroke', stroke);
+      }
+
+      const strokeWidth = computed.strokeWidth;
+      if (strokeWidth && strokeWidth !== '0' && strokeWidth !== '0px') {
+        clone.setAttribute('stroke-width', strokeWidth);
+      }
+
+      // Stroke dash array (for dashed lines)
+      // Important: stroke-dasharray:0 causes lines to disappear in Word
+      // Convert "0" to "none" for compatibility
+      const strokeDasharray = computed.strokeDasharray;
+      if (strokeDasharray && strokeDasharray !== 'none') {
+        // Fix: stroke-dasharray of "0" should be "none" for Word compatibility
+        const fixedDasharray = strokeDasharray === '0' || strokeDasharray === '0px' ? 'none' : strokeDasharray;
+        if (fixedDasharray !== 'none') {
+          clone.setAttribute('stroke-dasharray', fixedDasharray);
+        }
+      }
+
+      // Stroke line cap and join
+      const strokeLinecap = computed.strokeLinecap;
+      if (strokeLinecap && strokeLinecap !== 'butt') {
+        clone.setAttribute('stroke-linecap', strokeLinecap);
+      }
+
+      const strokeLinejoin = computed.strokeLinejoin;
+      if (strokeLinejoin && strokeLinejoin !== 'miter') {
+        clone.setAttribute('stroke-linejoin', strokeLinejoin);
+      }
+
+      // Opacity
+      const opacity = computed.opacity;
+      if (opacity && opacity !== '1') {
+        clone.setAttribute('opacity', opacity);
+      }
+
+      // Text-specific properties
+      const tagName = original.tagName.toLowerCase();
+      if (tagName === 'text' || tagName === 'tspan') {
+        const fontSize = computed.fontSize;
+        if (fontSize) {
+          clone.setAttribute('font-size', fontSize);
+        }
+
+        const fontFamily = computed.fontFamily;
+        if (fontFamily) {
+          clone.setAttribute('font-family', fontFamily.replace(/["']/g, ''));
+        }
+
+        const fontWeight = computed.fontWeight;
+        if (fontWeight && fontWeight !== 'normal' && fontWeight !== '400') {
+          clone.setAttribute('font-weight', fontWeight);
+        }
+
+        const textAnchor = computed.textAnchor;
+        if (textAnchor && textAnchor !== 'start') {
+          clone.setAttribute('text-anchor', textAnchor);
+        }
+
+        const dominantBaseline = computed.dominantBaseline;
+        if (dominantBaseline && dominantBaseline !== 'auto') {
+          clone.setAttribute('dominant-baseline', dominantBaseline);
+        }
+      }
+
+      // Preserve marker references (these are URL references, not computed styles)
+      const markerEnd = original.getAttribute('marker-end');
+      if (markerEnd) {
+        clone.setAttribute('marker-end', markerEnd);
+      }
+
+      const markerStart = original.getAttribute('marker-start');
+      if (markerStart) {
+        clone.setAttribute('marker-start', markerStart);
+      }
+
+      const markerMid = original.getAttribute('marker-mid');
+      if (markerMid) {
+        clone.setAttribute('marker-mid', markerMid);
+      }
+    } catch (error) {
+      // getComputedStyle can fail for detached elements
+      debug.debug('SVGConverter', `Could not get computed style for element`);
+    }
+  }
+
+  /**
+   * Inline styles for elements inside defs (markers, gradients, etc.)
+   */
+  private inlineDefsStyles(originalSvg: SVGElement, cloneSvg: SVGElement): void {
+    const originalDefs = originalSvg.querySelector('defs');
+    const cloneDefs = cloneSvg.querySelector('defs');
+
+    if (!originalDefs || !cloneDefs) return;
+
+    // Process all shape elements inside defs
+    const selectors = ['path', 'polygon', 'circle', 'rect', 'line', 'polyline'];
+
+    for (const selector of selectors) {
+      const originalElements = Array.from(originalDefs.querySelectorAll(selector));
+      const cloneElements = Array.from(cloneDefs.querySelectorAll(selector));
+
+      if (originalElements.length !== cloneElements.length) continue;
+
+      originalElements.forEach((originalEl, index) => {
+        const cloneEl = cloneElements[index] as SVGElement;
+        if (!cloneEl) return;
+
+        // For defs elements, we need to be more aggressive about inlining
+        // since they might not be in the document flow
+        try {
+          const computed = window.getComputedStyle(originalEl);
+
+          const fill = computed.fill;
+          if (fill && fill !== 'none') {
+            cloneEl.setAttribute('fill', fill);
+          }
+
+          const stroke = computed.stroke;
+          if (stroke && stroke !== 'none') {
+            cloneEl.setAttribute('stroke', stroke);
+          }
+        } catch {
+          // If we can't get computed styles, copy the original attributes
+          const fill = (originalEl as SVGElement).getAttribute('fill');
+          if (fill) cloneEl.setAttribute('fill', fill);
+
+          const stroke = (originalEl as SVGElement).getAttribute('stroke');
+          if (stroke) cloneEl.setAttribute('stroke', stroke);
+        }
+      });
+    }
+
+    debug.debug('SVGConverter', 'Processed defs elements');
+  }
+
+  /**
+   * Fix SVG string for Word compatibility issues.
+   * - stroke-dasharray:0 causes lines to disappear in Word
+   * - Some style attributes need adjustment
+   */
+  private fixSvgForWordCompatibility(svgMarkup: string): string {
+    // Fix stroke-dasharray:0 which causes lines to disappear in Word
+    // This can appear in style attributes or as standalone attributes
+    let fixed = svgMarkup;
+
+    // Fix in style attributes: stroke-dasharray:0; or stroke-dasharray: 0;
+    fixed = fixed.replace(/stroke-dasharray:\s*0\s*;/g, 'stroke-dasharray:none;');
+    fixed = fixed.replace(/stroke-dasharray:\s*0px\s*;/g, 'stroke-dasharray:none;');
+
+    // Fix as standalone attribute: stroke-dasharray="0"
+    fixed = fixed.replace(/stroke-dasharray="0"/g, 'stroke-dasharray="none"');
+    fixed = fixed.replace(/stroke-dasharray="0px"/g, 'stroke-dasharray="none"');
+
+    // Remove any stroke-dasharray="none" as it's the default
+    // (This reduces file size and avoids potential issues)
+    fixed = fixed.replace(/\s*stroke-dasharray="none"/g, '');
+
+    debug.debug('SVGConverter', 'Applied Word compatibility fixes to SVG');
+
+    return fixed;
+  }
+
+  /**
+   * Convert foreignObject elements to native SVG text elements.
+   * Word does not support foreignObject, which Mermaid uses for HTML labels.
+   * This extracts the text content and creates SVG text elements instead.
+   */
+  private convertForeignObjectsToText(svg: SVGElement): void {
+    const foreignObjects = svg.querySelectorAll('foreignObject');
+    const existingTextElements = svg.querySelectorAll('text');
+    let convertedCount = 0;
+
+    debug.info(
+      'SVGConverter',
+      `SVG analysis: ${foreignObjects.length} foreignObjects, ${existingTextElements.length} existing text elements`
+    );
+
+    // Log sample of existing text elements
+    if (existingTextElements.length > 0) {
+      const samples = Array.from(existingTextElements).slice(0, 3);
+      samples.forEach((text, i) => {
+        debug.debug(
+          'SVGConverter',
+          `Existing text[${i}]: "${text.textContent?.substring(0, 50)}"`
+        );
+      });
+    }
+
+    foreignObjects.forEach((fo) => {
+      try {
+        // Get position and dimensions from foreignObject
+        const x = parseFloat(fo.getAttribute('x') || '0');
+        const y = parseFloat(fo.getAttribute('y') || '0');
+        const foWidth = parseFloat(fo.getAttribute('width') || '100');
+        const foHeight = parseFloat(fo.getAttribute('height') || '20');
+
+        // Extract text content from the HTML inside foreignObject
+        const textContent = this.extractTextFromHtml(fo);
+
+        if (!textContent.trim()) {
+          // No text content, just remove the foreignObject
+          fo.parentNode?.removeChild(fo);
+          return;
+        }
+
+        // Create SVG text element
+        const textElement = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+
+        // Position text in the center of where foreignObject was
+        // Add half height to y because SVG text is positioned by baseline
+        textElement.setAttribute('x', String(x + foWidth / 2));
+        textElement.setAttribute('y', String(y + foHeight / 2));
+        textElement.setAttribute('text-anchor', 'middle');
+        textElement.setAttribute('dominant-baseline', 'middle');
+
+        // Extract and apply styles from the HTML content
+        const styles = this.extractStylesFromForeignObject(fo);
+        if (styles.fontSize) {
+          textElement.setAttribute('font-size', styles.fontSize);
+        } else {
+          textElement.setAttribute('font-size', '14px');
+        }
+        if (styles.fontFamily) {
+          textElement.setAttribute('font-family', styles.fontFamily);
+        } else {
+          textElement.setAttribute('font-family', 'sans-serif');
+        }
+        if (styles.fill) {
+          textElement.setAttribute('fill', styles.fill);
+        } else {
+          textElement.setAttribute('fill', '#333');
+        }
+        if (styles.fontWeight) {
+          textElement.setAttribute('font-weight', styles.fontWeight);
+        }
+
+        // Handle multi-line text by creating tspan elements
+        const lines = textContent.split('\n').filter((line) => line.trim());
+        if (lines.length === 1) {
+          textElement.textContent = lines[0].trim();
+        } else {
+          // Multi-line text: use tspan elements
+          const lineHeight = parseFloat(styles.fontSize || '14') * 1.2;
+          const startY = y + foHeight / 2 - ((lines.length - 1) * lineHeight) / 2;
+
+          lines.forEach((line, index) => {
+            const tspan = document.createElementNS('http://www.w3.org/2000/svg', 'tspan');
+            tspan.setAttribute('x', String(x + foWidth / 2));
+            tspan.setAttribute('dy', index === 0 ? '0' : String(lineHeight));
+            tspan.textContent = line.trim();
+            textElement.appendChild(tspan);
+          });
+
+          // Adjust the y position for multi-line
+          textElement.setAttribute('y', String(startY));
+        }
+
+        // Replace foreignObject with text element
+        const parent = fo.parentNode;
+        if (parent) {
+          parent.insertBefore(textElement, fo);
+          parent.removeChild(fo);
+          convertedCount++;
+        }
+      } catch (error) {
+        debug.warn('SVGConverter', `Failed to convert foreignObject to text:`, error);
+        // Remove the problematic foreignObject anyway
+        fo.parentNode?.removeChild(fo);
+      }
+    });
+
+    if (convertedCount > 0) {
+      debug.info('SVGConverter', `Converted ${convertedCount} foreignObject elements to SVG text`);
+    }
+  }
+
+  /**
+   * Extract plain text content from HTML inside foreignObject.
+   */
+  private extractTextFromHtml(fo: Element): string {
+    // Get all text content, preserving some structure
+    const html = fo.innerHTML;
+
+    // Create a temporary element to parse the HTML
+    const temp = document.createElement('div');
+    temp.innerHTML = html;
+
+    // Extract text, converting <br> and block elements to newlines
+    const extractText = (node: Node): string => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        return node.textContent || '';
+      }
+
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        const el = node as Element;
+        const tagName = el.tagName.toLowerCase();
+
+        // Block elements and br create line breaks
+        const isBlock = ['div', 'p', 'br', 'li', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(
+          tagName
+        );
+        const prefix = isBlock && el.previousSibling ? '\n' : '';
+
+        let text = prefix;
+        el.childNodes.forEach((child) => {
+          text += extractText(child);
+        });
+
+        return text;
+      }
+
+      return '';
+    };
+
+    return extractText(temp).trim();
+  }
+
+  /**
+   * Extract CSS styles from the HTML content inside foreignObject.
+   */
+  private extractStylesFromForeignObject(
+    fo: Element
+  ): { fontSize?: string; fontFamily?: string; fill?: string; fontWeight?: string } {
+    const styles: { fontSize?: string; fontFamily?: string; fill?: string; fontWeight?: string } =
+      {};
+
+    // Look for styled elements inside the foreignObject
+    const styledElements = fo.querySelectorAll('[style], span, div, p');
+
+    for (const el of styledElements) {
+      const htmlEl = el as HTMLElement;
+      const computedStyle = htmlEl.style;
+
+      // Try to get font-size
+      if (!styles.fontSize && computedStyle.fontSize) {
+        styles.fontSize = computedStyle.fontSize;
+      }
+
+      // Try to get font-family
+      if (!styles.fontFamily && computedStyle.fontFamily) {
+        styles.fontFamily = computedStyle.fontFamily;
+      }
+
+      // Try to get color (becomes fill in SVG)
+      if (!styles.fill && computedStyle.color) {
+        styles.fill = computedStyle.color;
+      }
+
+      // Try to get font-weight
+      if (!styles.fontWeight && computedStyle.fontWeight) {
+        styles.fontWeight = computedStyle.fontWeight;
+      }
+    }
+
+    // Also check the foreignObject itself for transform styles
+    const foStyle = (fo as HTMLElement).getAttribute('style');
+    if (foStyle) {
+      const fontSizeMatch = foStyle.match(/font-size:\s*([^;]+)/i);
+      if (fontSizeMatch && !styles.fontSize) {
+        styles.fontSize = fontSizeMatch[1].trim();
+      }
+    }
+
+    return styles;
+  }
+
+  /**
+   * Convert a string to base64.
+   */
+  private stringToBase64(str: string): string {
+    // Handle Unicode characters by encoding to UTF-8 first
+    const bytes = new TextEncoder().encode(str);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+
+  /**
+   * Convert multiple SVGs in batch
+   */
+  convertAll(svgs: SVGElement[]): Map<string, ConvertedImage> {
+    debug.info('SVGConverter', `Extracting ${svgs.length} SVGs`);
+
+    const results = new Map<string, ConvertedImage>();
+
+    for (const svg of svgs) {
+      try {
+        const image = this.convert(svg);
+        results.set(image.id, image);
+      } catch (error) {
+        debug.error('SVGConverter', `Failed to extract SVG ${svg.id}:`, error);
+        // Continue with other SVGs
+      }
+    }
+
+    debug.info('SVGConverter', `Successfully extracted ${results.size}/${svgs.length} SVGs`);
+
+    return results;
+  }
+
+  /**
+   * Extract dimensions from SVG element
+   */
+  private getSVGDimensions(svg: SVGElement): { width: number; height: number } {
+    // Try width/height attributes first
+    const widthAttr = svg.getAttribute('width');
+    const heightAttr = svg.getAttribute('height');
+
+    if (widthAttr && heightAttr) {
+      const width = parseFloat(widthAttr);
+      const height = parseFloat(heightAttr);
+      if (!isNaN(width) && !isNaN(height)) {
+        return { width, height };
+      }
+    }
+
+    // Try viewBox
+    const viewBox = svg.getAttribute('viewBox');
+    if (viewBox) {
+      const parts = viewBox.split(/\s+|,/);
+      if (parts.length === 4) {
+        const width = parseFloat(parts[2]);
+        const height = parseFloat(parts[3]);
+        if (!isNaN(width) && !isNaN(height)) {
+          return { width, height };
+        }
+      }
+    }
+
+    // Try getBoundingClientRect as fallback
+    const rect = svg.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0) {
+      return { width: rect.width, height: rect.height };
+    }
+
+    // Default dimensions
+    debug.warn('SVGConverter', 'Could not determine SVG dimensions, using defaults');
+    return { width: 800, height: 600 };
+  }
+}
diff --git a/src/core/export-controller.ts b/src/core/export-controller.ts
index 544a45a..6017980 100644
--- a/src/core/export-controller.ts
+++ b/src/core/export-controller.ts
@@ -1,138 +1,3 @@
-/**
- * Export Controller
- * Orchestrates the document export process
- */
-
-import type { ExportOptions, ExportProgress, ProgressCallback, ExportFormat } from '../types';
-import { ContentCollector } from '../utils/content-collector';
-import { SVGConverter } from '../utils/svg-converter';
-import { debug } from '../utils/debug-logger';
-
-/**
- * Controls the export process from content collection to file download
- */
-export class ExportController {
-  /**
-   * Export the rendered markdown to the specified format
-   */
-  async export(
-    container: HTMLElement,
-    options: ExportOptions,
-    onProgress?: ProgressCallback
-  ): Promise<void> {
-    const report = (stage: ExportProgress['stage'], progress: number, message: string) => {
-      onProgress?.({ stage, progress, message });
-    };
-
-    try {
-      // Stage 0: Ensure all Mermaid diagrams are rendered (0-5%)
-      const mermaidContainers = container.querySelectorAll('.mermaid-container');
-      if (mermaidContainers.length > 0) {
-        report('collecting', 2, 'Rendering diagrams...');
-        try {
-          const { mermaidRenderer } = await import('../renderers/mermaid-renderer');
-          await mermaidRenderer.renderAllImmediate(container);
-        } catch (error) {
-          debug.warn('ExportController', 'Could not force-render Mermaid diagrams before export:', error);
-        }
-      }
-
-      // Stage 1: Collect content (5-20%)
-      report('collecting', 5, 'Analyzing document structure...');
-      const collector = new ContentCollector();
-      const content = collector.collect(container);
-      report('collecting', 20, `Found ${content.nodes.length} elements`);
-
-      debug.info(
-        'ExportController',
-        `Collected content: ${content.nodes.length} nodes, ${content.metadata.wordCount} words`
-      );
-
-      // Stage 2: Convert SVGs (20-50%)
-      report('converting', 25, 'Converting diagrams...');
-      const converter = new SVGConverter();
-      const svgNodeList = container.querySelectorAll<SVGElement>('.mermaid-container svg');
-      const svgs = Array.from(svgNodeList);
-
-      const images = converter.convertAll(svgs);
-      report('converting', 50, `Converted ${images.size} diagrams`);
-
-      debug.info('ExportController', `Converted ${images.size} SVG diagrams`);
-
-      // Stage 3: Generate document (50-90%)
-      if (options.format === 'docx') {
-        report('generating', 55, 'Generating Word document...');
-
-        // Dynamic import to avoid loading docx unless needed
-        const { DOCXGenerator } = await import('../utils/docx-generator');
-        const generator = new DOCXGenerator();
-
-        const blob = await generator.generate(content, images, {
-          title: options.filename || content.title,
-        });
-
-        report('generating', 90, 'Document ready');
-
-        // Stage 4: Download (90-100%)
-        report('downloading', 95, 'Preparing download...');
-        const filename = this.sanitizeFilename(options.filename || content.title);
-        await this.downloadBlob(blob, `${filename}.docx`);
-        report('downloading', 100, 'Download complete');
-
-        debug.info('ExportController', `Export complete: ${filename}.docx`);
-      } else {
-        throw new Error(`Unsupported export format: ${options.format}`);
-      }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : 'Unknown error';
-      debug.error('ExportController', 'Export failed:', error);
-      throw new Error(`Export failed: ${message}`);
-    }
-  }
-
-
-  /**
-   * Get list of supported export formats
-   */
-  getSupportedFormats(): ExportFormat[] {
-    return ['docx', 'pdf'];
-  }
-
-  /**
-   * Download a blob as a file
-   */
-  private async downloadBlob(blob: Blob, filename: string): Promise<void> {
-    const url = URL.createObjectURL(blob);
-
-    try {
-      const a = document.createElement('a');
-      a.href = url;
-      a.download = filename;
-      a.style.display = 'none';
-      document.body.appendChild(a);
-      a.click();
-      document.body.removeChild(a);
-
-      // Wait a moment for download to start
-      await new Promise((resolve) => setTimeout(resolve, 100));
-    } finally {
-      // Clean up the blob URL
-      URL.revokeObjectURL(url);
-    }
-  }
-
-  /**
-   * Sanitize a filename by removing invalid characters
-   */
-  private sanitizeFilename(name: string): string {
-    return (
-      name
-        .replace(/[<>:"/\\|?*]/g, '') // Remove invalid chars
-        .replace(/\s+/g, '-') // Replace spaces with dashes
-        .replace(/-+/g, '-') // Collapse multiple dashes
-        .replace(/^-|-$/g, '') // Remove leading/trailing dashes
-        .slice(0, 200) || 'document'
-    ); // Limit length with fallback
-  }
-}
-
+// Re-export shim: export-controller has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/export-controller';
diff --git a/src/utils/content-collector.ts b/src/utils/content-collector.ts
index b8814bc..d54809f 100644
--- a/src/utils/content-collector.ts
+++ b/src/utils/content-collector.ts
@@ -1,416 +1,3 @@
-/**
- * Content Collector
- * Extracts structured content from rendered markdown DOM for export
- */
-
-import type { ContentNode, CollectedContent } from '../types';
-import { debug } from './debug-logger';
-
-/**
- * Collects and structures content from rendered markdown for export
- */
-export class ContentCollector {
-  /**
-   * Main entry point - collects all content from container
-   */
-  collect(container: HTMLElement): CollectedContent {
-    debug.info('ContentCollector', 'Starting content collection');
-
-    const nodes: ContentNode[] = [];
-    const children = Array.from(container.children);
-
-    for (const child of children) {
-      const node = this.processElement(child as HTMLElement);
-      if (node) {
-        nodes.push(node);
-      }
-    }
-
-    const title = this.extractTitle(nodes);
-    const metadata = this.calculateMetadata(nodes);
-
-    debug.info('ContentCollector', `Collected ${nodes.length} nodes, title: "${title}"`);
-
-    return {
-      title,
-      nodes,
-      metadata,
-    };
-  }
-
-  /**
-   * Process a single HTML element into a ContentNode
-   */
-  private processElement(element: HTMLElement): ContentNode | null {
-    const tagName = element.tagName.toLowerCase();
-
-    switch (tagName) {
-      case 'h1':
-      case 'h2':
-      case 'h3':
-      case 'h4':
-      case 'h5':
-      case 'h6':
-        return this.processHeading(element);
-      case 'p':
-        return this.processParagraph(element);
-      case 'ul':
-      case 'ol':
-        return this.processList(element);
-      case 'pre':
-        return this.processCodeBlock(element);
-      case 'table':
-        return this.processTable(element);
-      case 'blockquote':
-        return this.processBlockquote(element);
-      case 'hr':
-        return { type: 'hr', content: '', attributes: {} };
-      case 'div':
-        // Check for mermaid container
-        if (element.classList.contains('mermaid-container')) {
-          return this.processMermaid(element);
-        }
-        // Recurse into generic divs
-        return this.processContainer(element);
-      default:
-        debug.debug('ContentCollector', `Skipping unsupported element: ${tagName}`);
-        return null;
-    }
-  }
-
-  /**
-   * Extract heading (H1-H6)
-   * Uses plain text content - no markdown link conversion
-   */
-  private processHeading(element: HTMLElement): ContentNode {
-    const level = parseInt(element.tagName.substring(1));
-    // Use textContent for headings - don't convert anchor links to markdown
-    const text = (element.textContent || '').trim();
-    const id = element.id || '';
-
-    return {
-      type: 'heading',
-      content: text,
-      attributes: {
-        level,
-        id,
-      },
-    };
-  }
-
-  /**
-   * Extract paragraph with inline formatting
-   */
-  private processParagraph(element: HTMLElement): ContentNode {
-    const content = this.extractInlineContent(element);
-
-    return {
-      type: 'paragraph',
-      content,
-      attributes: {},
-    };
-  }
-
-  /**
-   * Extract list (UL/OL) with nested support
-   */
-  private processList(element: HTMLElement): ContentNode {
-    const ordered = element.tagName.toLowerCase() === 'ol';
-    const children: ContentNode[] = [];
-
-    const items = Array.from(element.children);
-    for (const item of items) {
-      if (item.tagName.toLowerCase() === 'li') {
-        const liContent = this.processListItem(item as HTMLElement);
-        children.push(liContent);
-      }
-    }
-
-    return {
-      type: 'list',
-      content: children,
-      attributes: {
-        ordered,
-      },
-      children,
-    };
-  }
-
-  /**
-   * Process a single list item (may contain nested lists)
-   */
-  private processListItem(li: HTMLElement): ContentNode {
-    const children: ContentNode[] = [];
-    let textContent = '';
-
-    // Process child nodes
-    for (const child of Array.from(li.childNodes)) {
-      if (child.nodeType === Node.TEXT_NODE) {
-        textContent += child.textContent || '';
-      } else if (child.nodeType === Node.ELEMENT_NODE) {
-        const element = child as HTMLElement;
-        const tagName = element.tagName.toLowerCase();
-
-        if (tagName === 'ul' || tagName === 'ol') {
-          // Nested list
-          const nestedList = this.processList(element);
-          children.push(nestedList);
-        } else {
-          // Inline content
-          textContent += this.extractInlineContent(element);
-        }
-      }
-    }
-
-    return {
-      type: 'paragraph', // List items are treated as paragraphs
-      content: textContent.trim(),
-      attributes: {},
-      children: children.length > 0 ? children : undefined,
-    };
-  }
-
-  /**
-   * Extract code block
-   */
-  private processCodeBlock(element: HTMLElement): ContentNode {
-    const codeElement = element.querySelector('code');
-    const code = codeElement ? codeElement.textContent || '' : element.textContent || '';
-
-    // Try to extract language from class
-    let language = '';
-    if (codeElement) {
-      const classes = Array.from(codeElement.classList);
-      const langClass = classes.find((c) => c.startsWith('language-'));
-      if (langClass) {
-        language = langClass.replace('language-', '');
-      }
-    }
-
-    return {
-      type: 'code',
-      content: code,
-      attributes: {
-        language,
-      },
-    };
-  }
-
-  /**
-   * Extract table
-   */
-  private processTable(element: HTMLElement): ContentNode {
-    const rows: string[][] = [];
-
-    // Process thead and tbody
-    const thead = element.querySelector('thead');
-    const tbody = element.querySelector('tbody');
-
-    if (thead) {
-      const headerRows = thead.querySelectorAll('tr');
-      headerRows.forEach((tr) => {
-        const cells = Array.from(tr.querySelectorAll('th, td')).map((cell) =>
-          this.extractInlineContent(cell as HTMLElement)
-        );
-        rows.push(cells);
-      });
-    }
-
-    if (tbody) {
-      const bodyRows = tbody.querySelectorAll('tr');
-      bodyRows.forEach((tr) => {
-        const cells = Array.from(tr.querySelectorAll('th, td')).map((cell) =>
-          this.extractInlineContent(cell as HTMLElement)
-        );
-        rows.push(cells);
-      });
-    } else {
-      // No tbody, process all rows
-      const allRows = element.querySelectorAll('tr');
-      allRows.forEach((tr) => {
-        const cells = Array.from(tr.querySelectorAll('th, td')).map((cell) =>
-          this.extractInlineContent(cell as HTMLElement)
-        );
-        rows.push(cells);
-      });
-    }
-
-    return {
-      type: 'table',
-      content: JSON.stringify(rows),
-      attributes: {
-        rows: rows.length,
-        cols: rows[0]?.length || 0,
-      },
-    };
-  }
-
-  /**
-   * Extract blockquote
-   */
-  private processBlockquote(element: HTMLElement): ContentNode {
-    const children: ContentNode[] = [];
-
-    for (const child of Array.from(element.children)) {
-      const node = this.processElement(child as HTMLElement);
-      if (node) {
-        children.push(node);
-      }
-    }
-
-    return {
-      type: 'blockquote',
-      content: children,
-      attributes: {},
-      children,
-    };
-  }
-
-  /**
-   * Extract mermaid diagram container
-   */
-  private processMermaid(element: HTMLElement): ContentNode {
-    const id = element.id || '';
-    const svg = element.querySelector('svg');
-
-    return {
-      type: 'mermaid',
-      content: '',
-      attributes: {
-        id,
-        width: svg?.getAttribute('width') || '',
-        height: svg?.getAttribute('height') || '',
-      },
-    };
-  }
-
-  /**
-   * Process a container element (recurse into children)
-   */
-  private processContainer(element: HTMLElement): ContentNode | null {
-    const children: ContentNode[] = [];
-
-    for (const child of Array.from(element.children)) {
-      const node = this.processElement(child as HTMLElement);
-      if (node) {
-        children.push(node);
-      }
-    }
-
-    // If only one child, return it directly
-    if (children.length === 1) {
-      return children[0];
-    }
-
-    // If multiple children or none, return null (skip the container)
-    return null;
-  }
-
-  /**
-   * Extract inline content with formatting
-   * Preserves bold, italic, code, and links
-   */
-  private extractInlineContent(element: HTMLElement): string {
-    let result = '';
-
-    for (const node of Array.from(element.childNodes)) {
-      if (node.nodeType === Node.TEXT_NODE) {
-        result += node.textContent || '';
-      } else if (node.nodeType === Node.ELEMENT_NODE) {
-        const el = node as HTMLElement;
-        const tagName = el.tagName.toLowerCase();
-
-        switch (tagName) {
-          case 'strong':
-          case 'b':
-            result += `**${this.extractInlineContent(el)}**`;
-            break;
-          case 'em':
-          case 'i':
-            result += `*${this.extractInlineContent(el)}*`;
-            break;
-          case 'code':
-            result += `\`${el.textContent || ''}\``;
-            break;
-          case 'a': {
-            const href = el.getAttribute('href') || '';
-            const linkText = this.extractInlineContent(el);
-            // Internal anchor links (TOC) - just use text, no markdown syntax
-            if (href.startsWith('#')) {
-              result += linkText;
-            } else {
-              // External links - convert to markdown format
-              result += `[${linkText}](${href})`;
-            }
-            break;
-          }
-          case 'br':
-            result += '\n';
-            break;
-          default:
-            // For other elements, just get text content
-            result += this.extractInlineContent(el);
-        }
-      }
-    }
-
-    return result;
-  }
-
-  /**
-   * Extract title from nodes (first H1 or use "Untitled")
-   */
-  private extractTitle(nodes: ContentNode[]): string {
-    const firstHeading = nodes.find((node) => node.type === 'heading' && node.attributes.level === 1);
-    if (firstHeading && typeof firstHeading.content === 'string') {
-      return firstHeading.content;
-    }
-    return 'Untitled Document';
-  }
-
-  /**
-   * Calculate metadata from nodes
-   */
-  private calculateMetadata(nodes: ContentNode[]): CollectedContent['metadata'] {
-    let wordCount = 0;
-    let imageCount = 0;
-    let mermaidCount = 0;
-
-    const countWords = (text: string): number => {
-      return text.split(/\s+/).filter((word) => word.length > 0).length;
-    };
-
-    const processNode = (node: ContentNode): void => {
-      if (node.type === 'mermaid') {
-        mermaidCount++;
-      } else if (node.type === 'image') {
-        imageCount++;
-      }
-
-      if (typeof node.content === 'string') {
-        // Count words from string content
-        if (node.type === 'heading' || node.type === 'paragraph') {
-          wordCount += countWords(node.content);
-        }
-      } else if (Array.isArray(node.content)) {
-        // Recurse into children
-        node.content.forEach(processNode);
-      }
-
-      // Process children if present
-      if (node.children) {
-        node.children.forEach(processNode);
-      }
-    };
-
-    nodes.forEach(processNode);
-
-    return {
-      wordCount,
-      imageCount,
-      mermaidCount,
-      exportedAt: new Date(),
-    };
-  }
-}
-
+// Re-export shim: content-collector has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/utils/content-collector';
diff --git a/src/utils/docx-generator.ts b/src/utils/docx-generator.ts
index 7cd2d5f..f816677 100644
--- a/src/utils/docx-generator.ts
+++ b/src/utils/docx-generator.ts
@@ -1,628 +1,3 @@
-/**
- * DOCX Generator
- * Converts structured content to Word documents using the docx library
- */
-
-import {
-  Document,
-  Packer,
-  Paragraph,
-  TextRun,
-  Table,
-  TableRow,
-  TableCell,
-  ImageRun,
-  ExternalHyperlink,
-  AlignmentType,
-  HeadingLevel,
-  BorderStyle,
-  WidthType,
-  convertInchesToTwip,
-  type IStylesOptions,
-  type ISectionOptions,
-} from '@jamesainslie/docx';
-import type { CollectedContent, ConvertedImage, ContentNode, DOCXGeneratorOptions } from '../types';
-import { debug } from './debug-logger';
-
-/**
- * Generates DOCX documents from collected content
- */
-export class DOCXGenerator {
-  /**
-   * Generate a DOCX document from collected content
-   */
-  async generate(
-    content: CollectedContent,
-    images: Map<string, ConvertedImage>,
-    options: DOCXGeneratorOptions = {}
-  ): Promise<Blob> {
-    debug.info('DOCXGenerator', `Generating DOCX for "${content.title}"`);
-
-    const doc = new Document({
-      creator: options.author || 'MDView',
-      title: options.title || content.title,
-      description: 'Exported from MDView',
-      styles: this.createStyles(),
-      numbering: {
-        config: [
-          {
-            reference: 'default-numbering',
-            levels: [
-              {
-                level: 0,
-                format: 'decimal',
-                text: '%1.',
-                alignment: AlignmentType.START,
-                style: {
-                  paragraph: {
-                    indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.25) },
-                  },
-                },
-              },
-              {
-                level: 1,
-                format: 'decimal',
-                text: '%2.',
-                alignment: AlignmentType.START,
-                style: {
-                  paragraph: {
-                    indent: { left: convertInchesToTwip(1), hanging: convertInchesToTwip(0.25) },
-                  },
-                },
-              },
-              {
-                level: 2,
-                format: 'decimal',
-                text: '%3.',
-                alignment: AlignmentType.START,
-                style: {
-                  paragraph: {
-                    indent: { left: convertInchesToTwip(1.5), hanging: convertInchesToTwip(0.25) },
-                  },
-                },
-              },
-            ],
-          },
-          {
-            reference: 'bullet-numbering',
-            levels: [
-              {
-                level: 0,
-                format: 'bullet',
-                text: '•',
-                alignment: AlignmentType.START,
-                style: {
-                  paragraph: {
-                    indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.25) },
-                  },
-                },
-              },
-              {
-                level: 1,
-                format: 'bullet',
-                text: '◦',
-                alignment: AlignmentType.START,
-                style: {
-                  paragraph: {
-                    indent: { left: convertInchesToTwip(1), hanging: convertInchesToTwip(0.25) },
-                  },
-                },
-              },
-              {
-                level: 2,
-                format: 'bullet',
-                text: '▪',
-                alignment: AlignmentType.START,
-                style: {
-                  paragraph: {
-                    indent: { left: convertInchesToTwip(1.5), hanging: convertInchesToTwip(0.25) },
-                  },
-                },
-              },
-            ],
-          },
-        ],
-      },
-      sections: [
-        {
-          properties: this.createPageProperties(options),
-          children: this.convertNodes(content.nodes, images),
-        },
-      ],
-    });
-
-    debug.info('DOCXGenerator', 'Converting document to blob');
-    const blob = await Packer.toBlob(doc);
-    debug.info('DOCXGenerator', `Generated DOCX blob (${blob.size} bytes)`);
-
-    return blob;
-  }
-
-  /**
-   * Create document styles - minimal approach like Pandoc
-   * Uses Aptos (modern Word default) or Calibri as fallback
-   */
-  private createStyles(): IStylesOptions {
-    return {
-      default: {
-        document: {
-          run: {
-            font: 'Aptos', // Modern Word default (falls back to Calibri if unavailable)
-            size: 24, // 12pt
-          },
-          paragraph: {
-            spacing: {
-              after: 200,
-            },
-          },
-        },
-        heading1: {
-          run: {
-            font: 'Aptos Display',
-            size: 40, // 20pt
-            color: '0F4761',
-          },
-        },
-        heading2: {
-          run: {
-            font: 'Aptos Display',
-            size: 32, // 16pt
-            color: '0F4761',
-          },
-        },
-        heading3: {
-          run: {
-            font: 'Aptos Display',
-            size: 28, // 14pt
-            color: '0F4761',
-          },
-        },
-        heading4: {
-          run: {
-            font: 'Aptos Display',
-            italics: true,
-            color: '0F4761',
-          },
-        },
-        heading5: {
-          run: {
-            font: 'Aptos Display',
-            color: '0F4761',
-          },
-        },
-        heading6: {
-          run: {
-            font: 'Aptos Display',
-            italics: true,
-            color: '595959',
-          },
-        },
-      },
-      paragraphStyles: [
-        {
-          id: 'Normal',
-          name: 'Normal',
-          quickFormat: true,
-        },
-      ],
-    };
-  }
-
-  /**
-   * Standard paper sizes in inches (width x height in portrait)
-   */
-  private static readonly PAPER_SIZES: Record<string, { width: number; height: number }> = {
-    // ISO A-series (mm converted to inches)
-    A0: { width: 33.11, height: 46.81 }, // 841 x 1189 mm
-    A1: { width: 23.39, height: 33.11 }, // 594 x 841 mm
-    A3: { width: 11.69, height: 16.54 }, // 297 x 420 mm
-    A4: { width: 8.27, height: 11.69 }, // 210 x 297 mm
-    A5: { width: 5.83, height: 8.27 }, // 148 x 210 mm
-    A6: { width: 4.13, height: 5.83 }, // 105 x 148 mm
-    // North American sizes
-    Letter: { width: 8.5, height: 11.0 }, // 8.5 x 11 in
-    Legal: { width: 8.5, height: 14.0 }, // 8.5 x 14 in
-    Tabloid: { width: 11.0, height: 17.0 }, // 11 x 17 in
-    Executive: { width: 7.25, height: 10.5 }, // 7.25 x 10.5 in
-  };
-
-  /**
-   * Create page properties
-   */
-  private createPageProperties(options: DOCXGeneratorOptions): ISectionOptions['properties'] {
-    const pageSize = options.pageSize || 'A4';
-    const margins = options.margins || {
-      top: convertInchesToTwip(1),
-      bottom: convertInchesToTwip(1),
-      left: convertInchesToTwip(1),
-      right: convertInchesToTwip(1),
-    };
-
-    // Get paper dimensions, default to A4 if unknown
-    const paper = DOCXGenerator.PAPER_SIZES[pageSize] || DOCXGenerator.PAPER_SIZES.A4;
-    const pageDimensions = {
-      width: convertInchesToTwip(paper.width),
-      height: convertInchesToTwip(paper.height),
-    };
-
-    return {
-      page: {
-        size: pageDimensions,
-        margin: margins,
-      },
-    };
-  }
-
-  /**
-   * Convert content nodes to DOCX elements
-   */
-  private convertNodes(nodes: ContentNode[], images: Map<string, ConvertedImage>): (Paragraph | Table)[] {
-    const elements: (Paragraph | Table)[] = [];
-
-    for (const node of nodes) {
-      try {
-        switch (node.type) {
-          case 'heading':
-            elements.push(this.convertHeading(node));
-            break;
-          case 'paragraph':
-            elements.push(this.convertParagraph(node));
-            break;
-          case 'list':
-            elements.push(...this.convertList(node, 0));
-            break;
-          case 'code':
-            elements.push(...this.convertCodeBlock(node));
-            break;
-          case 'table':
-            elements.push(this.convertTable(node));
-            break;
-          case 'blockquote':
-            elements.push(...this.convertBlockquote(node, images));
-            break;
-          case 'mermaid': {
-            const mermaidPara = this.convertMermaid(node, images);
-            if (mermaidPara) {
-              elements.push(mermaidPara);
-            }
-            break;
-          }
-          case 'hr':
-            elements.push(this.convertHorizontalRule());
-            break;
-          default:
-            debug.warn('DOCXGenerator', `Unsupported node type: ${node.type}`);
-        }
-      } catch (error) {
-        debug.error('DOCXGenerator', `Error converting node type ${node.type}:`, error);
-      }
-    }
-
-    return elements;
-  }
-
-  /**
-   * Convert heading node
-   */
-  private convertHeading(node: ContentNode): Paragraph {
-    const level = (node.attributes.level as number) || 1;
-    const text = typeof node.content === 'string' ? node.content : '';
-
-    // Map heading level to HeadingLevel enum
-    const headingLevelMap: Record<number, (typeof HeadingLevel)[keyof typeof HeadingLevel]> = {
-      1: HeadingLevel.HEADING_1,
-      2: HeadingLevel.HEADING_2,
-      3: HeadingLevel.HEADING_3,
-      4: HeadingLevel.HEADING_4,
-      5: HeadingLevel.HEADING_5,
-      6: HeadingLevel.HEADING_6,
-    };
-
-    return new Paragraph({
-      text,
-      heading: headingLevelMap[level] || HeadingLevel.HEADING_1,
-    });
-  }
-
-  /**
-   * Convert paragraph node - plain text, no custom styling
-   */
-  private convertParagraph(node: ContentNode): Paragraph {
-    const text = typeof node.content === 'string' ? node.content : '';
-    const runs = this.parseInlineFormatting(text);
-
-    return new Paragraph({
-      children: runs,
-    });
-  }
-
-  /**
-   * Parse inline formatting from markdown-style text
-   */
-  private parseInlineFormatting(text: string): (TextRun | ExternalHyperlink)[] {
-    const children: (TextRun | ExternalHyperlink)[] = [];
-
-    // Pattern to match: **bold**, *italic*, `code`, [text](url), or plain text
-    const pattern = /(\*\*[^*]+\*\*)|(\*[^*]+\*)|(`[^`]+`)|(\[[^\]]+]\([^)]+\))|([^*`[]+)/g;
-
-    let match;
-    while ((match = pattern.exec(text)) !== null) {
-      if (match[1]) {
-        // Bold: **text**
-        const boldText = match[1].slice(2, -2);
-        children.push(new TextRun({ text: boldText, bold: true }));
-      } else if (match[2]) {
-        // Italic: *text*
-        const italicText = match[2].slice(1, -1);
-        children.push(new TextRun({ text: italicText, italics: true }));
-      } else if (match[3]) {
-        // Inline code: `text` - monospace font
-        const codeText = match[3].slice(1, -1);
-        children.push(new TextRun({ text: codeText, font: 'Consolas' }));
-      } else if (match[4]) {
-        // Link: [text](url) - Word will style with default Hyperlink
-        const linkMatch = match[4].match(/\[([^\]]+)\]\(([^)]+)\)/);
-        if (linkMatch) {
-          children.push(
-            new ExternalHyperlink({
-              children: [new TextRun({ text: linkMatch[1] })],
-              link: linkMatch[2],
-            })
-          );
-        }
-      } else if (match[5]) {
-        // Plain text
-        children.push(new TextRun({ text: match[5] }));
-      }
-    }
-
-    // If no matches, return plain text
-    if (children.length === 0) {
-      children.push(new TextRun({ text }));
-    }
-
-    return children;
-  }
-
-  /**
-   * Convert list node (recursive for nested lists)
-   */
-  private convertList(node: ContentNode, level: number): Paragraph[] {
-    const paragraphs: Paragraph[] = [];
-    const ordered = node.attributes.ordered === true;
-
-    if (Array.isArray(node.content)) {
-      for (const item of node.content) {
-        if (item.type === 'paragraph') {
-          const text = typeof item.content === 'string' ? item.content : '';
-          const runs = this.parseInlineFormatting(text);
-
-          paragraphs.push(
-            new Paragraph({
-              children: runs,
-              numbering: ordered
-                ? { reference: 'default-numbering', level }
-                : { reference: 'bullet-numbering', level },
-            })
-          );
-
-          // Handle nested lists
-          if (item.children && item.children.length > 0) {
-            for (const child of item.children) {
-              if (child.type === 'list') {
-                paragraphs.push(...this.convertList(child, level + 1));
-              }
-            }
-          }
-        }
-      }
-    }
-
-    return paragraphs;
-  }
-
-  /**
-   * Convert code block node - monospace font
-   */
-  private convertCodeBlock(node: ContentNode): Paragraph[] {
-    const code = typeof node.content === 'string' ? node.content : '';
-    const lines = code.split('\n');
-
-    return lines.map(
-      (line) =>
-        new Paragraph({
-          children: [
-            new TextRun({
-              text: line || ' ',
-              font: 'Consolas',
-            }),
-          ],
-        })
-    );
-  }
-
-  /**
-   * Convert table node - Pandoc style: header with bottom border only
-   */
-  private convertTable(node: ContentNode): Table {
-    const rowsData = JSON.parse(
-      typeof node.content === 'string' ? node.content : '[]'
-    ) as string[][];
-
-    const rows = rowsData.map(
-      (rowData, rowIndex) =>
-        new TableRow({
-          children: rowData.map(
-            (cellData) =>
-              new TableCell({
-                children: [
-                  new Paragraph({
-                    children: rowIndex === 0
-                      ? [new TextRun({ text: cellData, bold: true })]
-                      : this.parseInlineFormatting(cellData),
-                  }),
-                ],
-                // Header row: bottom border only (Pandoc style)
-                borders: rowIndex === 0
-                  ? {
-                      top: { style: BorderStyle.NONE, size: 0 },
-                      bottom: { style: BorderStyle.SINGLE, size: 6, color: '000000' },
-                      left: { style: BorderStyle.NONE, size: 0 },
-                      right: { style: BorderStyle.NONE, size: 0 },
-                    }
-                  : {
-                      top: { style: BorderStyle.NONE, size: 0 },
-                      bottom: { style: BorderStyle.NONE, size: 0 },
-                      left: { style: BorderStyle.NONE, size: 0 },
-                      right: { style: BorderStyle.NONE, size: 0 },
-                    },
-              })
-          ),
-        })
-    );
-
-    return new Table({
-      rows,
-      width: {
-        size: 100,
-        type: WidthType.PERCENTAGE,
-      },
-      // Remove table-level borders
-      borders: {
-        top: { style: BorderStyle.NONE, size: 0 },
-        bottom: { style: BorderStyle.NONE, size: 0 },
-        left: { style: BorderStyle.NONE, size: 0 },
-        right: { style: BorderStyle.NONE, size: 0 },
-        insideHorizontal: { style: BorderStyle.NONE, size: 0 },
-        insideVertical: { style: BorderStyle.NONE, size: 0 },
-      },
-    });
-  }
-
-  /**
-   * Convert blockquote node - indented text
-   */
-  private convertBlockquote(node: ContentNode, _images: Map<string, ConvertedImage>): Paragraph[] {
-    const paragraphs: Paragraph[] = [];
-
-    if (Array.isArray(node.content)) {
-      for (const child of node.content) {
-        if (child.type === 'paragraph') {
-          const text = typeof child.content === 'string' ? child.content : '';
-          const runs = this.parseInlineFormatting(text);
-          paragraphs.push(
-            new Paragraph({
-              children: runs,
-              indent: { left: 720 }, // 0.5 inch indent
-            })
-          );
-        } else if (child.type === 'table') {
-          paragraphs.push(
-            new Paragraph({
-              children: [new TextRun({ text: '[Table in blockquote]' })],
-              indent: { left: 720 },
-            })
-          );
-        }
-      }
-    }
-
-    return paragraphs;
-  }
-
-  /**
-   * Convert mermaid diagram to embedded image.
-   * Supports both SVG (vector, preferred) and raster (PNG/JPEG) formats.
-   */
-  private convertMermaid(node: ContentNode, images: Map<string, ConvertedImage>): Paragraph | null {
-    const id = node.attributes.id as string;
-    const image = images.get(id);
-
-    if (!image) {
-      debug.warn('DOCXGenerator', `No image found for mermaid diagram: ${id}`);
-      return null;
-    }
-
-    // Convert base64 to Uint8Array (browser-safe, no Node Buffer dependency)
-    const binary = atob(image.data);
-    const length = binary.length;
-    const bytes = new Uint8Array(length);
-    for (let i = 0; i < length; i++) {
-      bytes[i] = binary.charCodeAt(i);
-    }
-
-    // Calculate dimensions
-    // - Preserve aspect ratio
-    // - Scale uniformly to fit maxWidth
-    const maxWidth = 600; // Max width in document units (about 8.3 inches)
-    const scale = image.width > 0 ? Math.min(1, maxWidth / image.width) : 1;
-    const width = image.width * scale;
-    const height = image.height * scale;
-
-    // Determine if this is an SVG image
-    const isSvg = image.format === 'svg';
-
-    // For SVG images, use the forked docx library's SVG support
-    // which requires type: "svg" and a PNG fallback for older Word versions
-    if (isSvg) {
-      // Create a minimal 1x1 transparent PNG as fallback for older Word versions
-      // This is a base64-encoded 1x1 transparent PNG
-      const fallbackPngBase64 =
-        'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
-      const fallbackBinary = atob(fallbackPngBase64);
-      const fallbackBytes = new Uint8Array(fallbackBinary.length);
-      for (let i = 0; i < fallbackBinary.length; i++) {
-        fallbackBytes[i] = fallbackBinary.charCodeAt(i);
-      }
-
-      return new Paragraph({
-        children: [
-          new ImageRun({
-            type: 'svg',
-            data: bytes,
-            transformation: {
-              width,
-              height,
-            },
-            fallback: {
-              type: 'png',
-              data: fallbackBytes,
-            },
-          }),
-        ],
-        alignment: AlignmentType.CENTER,
-      });
-    }
-
-    // For raster images (PNG, JPEG), use the standard approach with explicit type
-    return new Paragraph({
-      children: [
-        new ImageRun({
-          type: 'png', // Default to PNG for raster images
-          data: bytes,
-          transformation: {
-            width,
-            height,
-          },
-        }),
-      ],
-      alignment: AlignmentType.CENTER,
-    });
-  }
-
-  /**
-   * Convert horizontal rule
-   */
-  private convertHorizontalRule(): Paragraph {
-    return new Paragraph({
-      children: [new TextRun({ text: '' })],
-      border: {
-        bottom: {
-          style: BorderStyle.SINGLE,
-          size: 6,
-        },
-      },
-    });
-  }
-}
-
+// Re-export shim: docx-generator has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/utils/docx-generator';
diff --git a/src/utils/pdf-generator.ts b/src/utils/pdf-generator.ts
index 32b4b99..a176e41 100644
--- a/src/utils/pdf-generator.ts
+++ b/src/utils/pdf-generator.ts
@@ -1,460 +1,3 @@
-/**
- * PDF Generator
- * Handles PDF export via browser print with SVG-to-image conversion
- */
-
-import type { PDFGeneratorOptions, ProgressCallback, ExportProgress } from '../types';
-import { debug } from './debug-logger';
-
-export class PDFGenerator {
-  private originalSvgs: Map<Element, { element: SVGElement; parent: Element; html: string }> =
-    new Map();
-  private printStyleElement: HTMLStyleElement | null = null;
-  private replacedImages: Element[] = [];
-
-  constructor() {
-    debug.info('PDFGenerator', 'PDF Generator initialized');
-  }
-
-  /**
-   * Prepare document for print and trigger print dialog
-   *
-   * Progress mapping:
-   * - 5–25%  : Collecting diagrams / DOM state
-   * - 30–80% : Converting SVG diagrams to images
-   * - 85–95% : Applying print styles and opening dialog
-   */
-  async print(
-    container: HTMLElement,
-    options: PDFGeneratorOptions = {},
-    onProgress?: ProgressCallback,
-    signal?: AbortSignal
-  ): Promise<void> {
-    debug.info('PDFGenerator', 'Starting print process');
-
-    try {
-      this.ensureNotAborted(signal);
-      this.reportProgress(onProgress, 'collecting', 5, 'Preparing document for print...');
-
-      // Ensure all Mermaid diagrams are rendered before conversion
-      this.reportProgress(onProgress, 'collecting', 15, 'Rendering diagrams...');
-      try {
-        const { mermaidRenderer } = await import('../renderers/mermaid-renderer');
-        // Bypass lazy loading: render every diagram in the container now
-        await mermaidRenderer.renderAllImmediate(container);
-      } catch (error) {
-        debug.warn('PDFGenerator', 'Could not force-render Mermaid diagrams:', error);
-      }
-
-      // Quick sanity check on diagram state
-      await this.waitForMermaidDiagrams(container);
-      this.ensureNotAborted(signal);
-      this.reportProgress(onProgress, 'collecting', 25, 'Diagrams ready for conversion');
-
-      // Prepare for print
-      if (options.convertSvgsToImages !== false) {
-        await this.prepareSvgsForPrint(container, options, onProgress, signal);
-      }
-
-      this.ensureNotAborted(signal);
-
-      this.reportProgress(onProgress, 'generating', 85, 'Applying print styles...');
-      this.addPrintClass();
-      this.injectPrintStyles(options);
-
-      // Small delay to ensure styles are applied
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      this.ensureNotAborted(signal);
-
-      // Trigger print
-      this.reportProgress(onProgress, 'generating', 90, 'Opening print dialog...');
-      debug.info('PDFGenerator', 'Opening print dialog');
-      window.print();
-
-      // Wait for dialog to close
-      await this.waitForPrintDialog();
-
-      this.reportProgress(onProgress, 'generating', 100, 'Print dialog closed');
-      debug.info('PDFGenerator', 'Print dialog closed');
-    } catch (error) {
-      debug.error('PDFGenerator', 'Print failed:', error);
-      throw error;
-    } finally {
-      // Restore state
-      this.restoreSvgs();
-      this.removePrintClass();
-      this.removePrintStyles();
-      debug.info('PDFGenerator', 'State restored after print');
-    }
-  }
-
-  /**
-   * Check for Mermaid diagrams - warn if any are still pending
-   */
-  private async waitForMermaidDiagrams(container: HTMLElement): Promise<void> {
-    // Get diagram counts
-    const readyCount = container.querySelectorAll('.mermaid-container.mermaid-ready').length;
-    const pendingCount = container.querySelectorAll('.mermaid-container.mermaid-pending').length;
-
-    if (readyCount === 0 && pendingCount === 0) {
-      debug.info('PDFGenerator', 'No Mermaid diagrams in document');
-      return;
-    }
-
-    debug.info('PDFGenerator', `Diagrams: ${readyCount} ready, ${pendingCount} pending`);
-
-    if (pendingCount > 0) {
-      debug.warn(
-        'PDFGenerator',
-        `${pendingCount} diagram(s) not yet rendered. Scroll through document first to render all diagrams.`
-      );
-    }
-
-    // Small delay to ensure DOM is stable
-    await new Promise((resolve) => setTimeout(resolve, 100));
-  }
-
-  /**
-   * Convert SVGs to images for print compatibility
-   * Scales diagrams based on target page size to avoid squashing.
-   */
-  private prepareSvgsForPrint(
-    container: HTMLElement,
-    options: PDFGeneratorOptions,
-    onProgress?: ProgressCallback,
-    signal?: AbortSignal
-  ): Promise<void> {
-    debug.info('PDFGenerator', 'Preparing SVGs for print');
-
-    const svgs = container.querySelectorAll('.mermaid-container svg');
-    debug.info('PDFGenerator', `Found ${svgs.length} SVGs to convert`);
-
-    if (svgs.length === 0) {
-      return Promise.resolve();
-    }
-
-    const total = svgs.length;
-
-    const paperSize = options.paperSize ?? 'A4';
-    const margins = options.margins ?? '2cm';
-    const orientation = options.orientation ?? 'portrait';
-    const { width: maxContentWidth, height: maxContentHeight } = this.getPrintableContentBox(
-      paperSize,
-      margins,
-      orientation
-    );
-
-    this.reportProgress(
-      onProgress,
-      'converting',
-      30,
-      total === 1 ? 'Converting diagram for print...' : 'Converting diagrams for print...'
-    );
-
-    let index = 0;
-
-    for (const svg of svgs) {
-      this.ensureNotAborted(signal);
-
-      const svgElement = svg as SVGElement;
-      const parent = svg.parentElement;
-
-      if (!parent) {
-        debug.warn('PDFGenerator', 'SVG has no parent, skipping');
-        continue;
-      }
-
-      // Store original SVG and its parent
-      this.originalSvgs.set(svg, {
-        element: svgElement,
-        parent: parent,
-        html: svg.outerHTML,
-      });
-
-      // First, get the SVG's natural dimensions
-      const svgRect = svgElement.getBoundingClientRect();
-      const naturalWidth = svgRect.width || 800;
-      const naturalHeight = svgRect.height || 600;
-
-      // Compute the target dimensions to fit within one page
-      // Reserve 40px for borders, margins, and padding around the diagram
-      const reservedSpace = 40;
-      const availableWidth = maxContentWidth - reservedSpace;
-      const availableHeight = maxContentHeight - reservedSpace;
-
-      const scaleToWidth = availableWidth / naturalWidth;
-      const scaleToHeight = availableHeight / naturalHeight;
-      const scaleFactor = Math.min(1, scaleToWidth, scaleToHeight);
-
-      // Target dimensions in CSS pixels
-      const targetWidth = Math.round(naturalWidth * scaleFactor);
-      const targetHeight = Math.round(naturalHeight * scaleFactor);
-
-      debug.info(
-        'PDFGenerator',
-        `Diagram ${index}: natural=${naturalWidth.toFixed(0)}x${naturalHeight.toFixed(0)}, ` +
-          `maxContent=${maxContentWidth.toFixed(0)}x${maxContentHeight.toFixed(0)}, ` +
-          `scale=${scaleFactor.toFixed(3)}, target=${targetWidth}x${targetHeight}`
-      );
-
-      // For PDF export we prefer the browser's high‑quality, theme‑aware SVG
-      // rendering rather than the wasm-based PNGs used for DOCX. Here we
-      // simply clone and scale the SVG element itself so that labels and
-      // styling match what you see in the MDView page.
-      const scaledSvg = svgElement.cloneNode(true) as SVGElement;
-      scaledSvg.setAttribute('width', String(targetWidth));
-      scaledSvg.setAttribute('height', String(targetHeight));
-      scaledSvg.style.cssText = `
-        display: block !important;
-        width: ${targetWidth}px !important;
-        height: ${targetHeight}px !important;
-        max-width: ${maxContentWidth}px !important;
-        max-height: ${maxContentHeight}px !important;
-        margin: 8pt auto !important;
-        page-break-inside: avoid !important;
-        break-inside: avoid !important;
-      `;
-      const replacement = scaledSvg as unknown as HTMLElement;
-
-      debug.info('PDFGenerator', `Scaled SVG directly for print: ${targetWidth}x${targetHeight}`);
-
-      // Replace original SVG
-      parent.replaceChild(replacement, svg);
-      this.replacedImages.push(replacement);
-
-      index += 1;
-
-      // Progress update
-      const fraction = index / total;
-      const progress = 35 + Math.round(fraction * 45);
-      const message =
-        total === 1
-          ? 'Prepared diagram for print'
-          : `Preparing diagrams for print (${index}/${total})...`;
-      this.reportProgress(onProgress, 'converting', Math.min(progress, 80), message);
-    }
-
-    debug.info(
-      'PDFGenerator',
-      `Prepared ${this.replacedImages.length} SVGs for print (scaled SVGs)`
-    );
-
-    return Promise.resolve();
-  }
-
-  /**
-   * Restore original SVGs after print
-   */
-  private restoreSvgs(): void {
-    debug.info('PDFGenerator', 'Restoring original SVGs');
-
-    this.originalSvgs.forEach((data) => {
-      try {
-        // Find the img element that replaced this SVG
-        const img = this.replacedImages.find((el) => el.parentElement === data.parent);
-
-        if (img && data.parent) {
-          // Create a new SVG element from the stored HTML
-          const temp = document.createElement('div');
-          temp.innerHTML = data.html;
-          const restoredSvg = temp.firstElementChild;
-
-          if (restoredSvg) {
-            data.parent.replaceChild(restoredSvg, img);
-            debug.debug('PDFGenerator', 'Restored SVG');
-          }
-        }
-      } catch (error) {
-        debug.error('PDFGenerator', 'Failed to restore SVG:', error);
-      }
-    });
-
-    // Clear tracking
-    this.originalSvgs.clear();
-    this.replacedImages = [];
-
-    debug.info('PDFGenerator', 'SVG restoration complete');
-  }
-
-  /**
-   * Add print class to body
-   */
-  private addPrintClass(): void {
-    document.body.classList.add('mdview-printing');
-    debug.debug('PDFGenerator', 'Added print class');
-  }
-
-  /**
-   * Remove print class from body
-   */
-  private removePrintClass(): void {
-    document.body.classList.remove('mdview-printing');
-    debug.debug('PDFGenerator', 'Removed print class');
-  }
-
-  /**
-   * Inject dynamic print styles
-   */
-  private injectPrintStyles(options: PDFGeneratorOptions): void {
-    if (this.printStyleElement) {
-      this.removePrintStyles();
-    }
-
-    const { paperSize = 'A4', orientation = 'portrait', margins = '2cm' } = options;
-
-    const styles = `
-      @media print {
-        @page {
-          size: ${paperSize} ${orientation};
-          margin: ${margins};
-        }
-      }
-    `;
-
-    this.printStyleElement = document.createElement('style');
-    this.printStyleElement.id = 'mdview-dynamic-print-styles';
-    this.printStyleElement.textContent = styles;
-    document.head.appendChild(this.printStyleElement);
-
-    debug.debug(
-      'PDFGenerator',
-      `Injected print styles: ${paperSize} ${orientation}, margins: ${margins}`
-    );
-  }
-
-  /**
-   * Remove dynamic print styles
-   */
-  private removePrintStyles(): void {
-    if (this.printStyleElement) {
-      this.printStyleElement.remove();
-      this.printStyleElement = null;
-      debug.debug('PDFGenerator', 'Removed print styles');
-    }
-  }
-
-  /**
-   * Wait for print dialog to close (with short timeout)
-   */
-  private waitForPrintDialog(): Promise<void> {
-    return new Promise((resolve) => {
-      // The afterprint event fires when the dialog closes
-      const handler = () => {
-        window.removeEventListener('afterprint', handler);
-        setTimeout(resolve, 50);
-      };
-
-      window.addEventListener('afterprint', handler);
-
-      // Very short fallback - print dialog should open immediately
-      // If it doesn't fire within 2 seconds, just continue
-      setTimeout(() => {
-        window.removeEventListener('afterprint', handler);
-        resolve();
-      }, 2000);
-    });
-  }
-
-  /**
-   * Standard paper sizes in inches (width x height in portrait)
-   */
-  private static readonly PAPER_SIZES: Record<string, { width: number; height: number }> = {
-    // ISO A-series (mm converted to inches)
-    A0: { width: 33.11, height: 46.81 }, // 841 x 1189 mm
-    A1: { width: 23.39, height: 33.11 }, // 594 x 841 mm
-    A3: { width: 11.69, height: 16.54 }, // 297 x 420 mm
-    A4: { width: 8.27, height: 11.69 }, // 210 x 297 mm
-    A5: { width: 5.83, height: 8.27 }, // 148 x 210 mm
-    A6: { width: 4.13, height: 5.83 }, // 105 x 148 mm
-    // North American sizes
-    Letter: { width: 8.5, height: 11.0 }, // 8.5 x 11 in
-    Legal: { width: 8.5, height: 14.0 }, // 8.5 x 14 in
-    Tabloid: { width: 11.0, height: 17.0 }, // 11 x 17 in
-    Executive: { width: 7.25, height: 10.5 }, // 7.25 x 10.5 in
-  };
-
-  /**
-   * Helper: compute printable content box (width/height) in CSS pixels
-   */
-  private getPrintableContentBox(
-    paperSize: string,
-    margins: string,
-    orientation: 'portrait' | 'landscape'
-  ): { width: number; height: number } {
-    const dpi = 96; // CSS pixels per inch
-
-    // Get paper dimensions, default to A4 if unknown
-    const paper = PDFGenerator.PAPER_SIZES[paperSize] || PDFGenerator.PAPER_SIZES.A4;
-    let pageWidthInches = paper.width;
-    let pageHeightInches = paper.height;
-
-    // Swap for landscape
-    if (orientation === 'landscape') {
-      [pageWidthInches, pageHeightInches] = [pageHeightInches, pageWidthInches];
-    }
-
-    // Parse margin value; assume symmetric margins on all sides
-    let marginPx = (2 / 2.54) * dpi; // Default 2cm in px
-    const match = margins.match(/([\d.]+)\s*(cm|mm|in|px)/i);
-
-    if (match) {
-      const value = parseFloat(match[1]);
-      const unit = match[2].toLowerCase();
-
-      if (!Number.isNaN(value)) {
-        switch (unit) {
-          case 'cm':
-            marginPx = (value / 2.54) * dpi;
-            break;
-          case 'mm':
-            marginPx = (value / 25.4) * dpi;
-            break;
-          case 'in':
-            marginPx = value * dpi;
-            break;
-          case 'px':
-            marginPx = value;
-            break;
-        }
-      }
-    }
-
-    const totalMarginX = marginPx * 2;
-    const totalMarginY = marginPx * 2;
-
-    const pageWidthPx = pageWidthInches * dpi;
-    const pageHeightPx = pageHeightInches * dpi;
-
-    const contentWidth = pageWidthPx - totalMarginX;
-    const contentHeight = pageHeightPx - totalMarginY;
-
-    // Guard against negative or very small values
-    return {
-      width: Math.max(200, contentWidth),
-      height: Math.max(200, contentHeight),
-    };
-  }
-
-  /**
-   * Helper: report progress if a callback is provided
-   */
-  private reportProgress(
-    onProgress: ProgressCallback | undefined,
-    stage: ExportProgress['stage'],
-    progress: number,
-    message: string
-  ): void {
-    if (!onProgress) return;
-    onProgress({ stage, progress, message });
-  }
-
-  /**
-   * Helper: throw if an abort signal has been triggered
-   */
-  private ensureNotAborted(signal?: AbortSignal): void {
-    if (signal?.aborted) {
-      throw new DOMException('Export aborted', 'AbortError');
-    }
-  }
-}
+// Re-export shim: pdf-generator has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/utils/pdf-generator';
diff --git a/src/utils/svg-converter.ts b/src/utils/svg-converter.ts
index 309d2a9..d6e48d0 100644
--- a/src/utils/svg-converter.ts
+++ b/src/utils/svg-converter.ts
@@ -1,598 +1,3 @@
-/**
- * SVG Converter
- * Extracts SVG elements as vector images for document embedding.
- *
- * This implementation serializes SVG elements directly to XML strings,
- * avoiding rasterization entirely. The forked docx library (jamesainslie/docx)
- * supports embedding SVG images natively via mimeType: 'image/svg+xml'.
- *
- * Important: Mermaid diagrams use <foreignObject> elements for text labels
- * in many diagram types. Word does not support <foreignObject>, so we
- * convert these to native SVG <text> elements before export.
- */
-
-import type { SVGConversionOptions, ConvertedImage } from '../types';
-import { debug } from './debug-logger';
-
-/**
- * Converts SVG elements to embeddable image formats (now SVG-native)
- */
-export class SVGConverter {
-  /**
-   * Convert a single SVG element to an embeddable image.
-   * Returns the SVG as a base64-encoded string with format 'svg'.
-   */
-  convert(svg: SVGElement, _options: SVGConversionOptions = {}): ConvertedImage {
-    // Prefer the Mermaid container ID so that it matches ContentCollector's
-    // mermaid node IDs (e.g. "mermaid-xyz"), falling back to the SVG ID.
-    const container = svg.closest<HTMLElement>('.mermaid-container');
-    const id = container?.id || svg.id || `svg-${Date.now()}`;
-
-    debug.info('SVGConverter', `Extracting SVG ${id} as vector image`);
-
-    // Get SVG dimensions
-    const { width, height } = this.getSVGDimensions(svg);
-
-    debug.debug('SVGConverter', `Dimensions: ${width}x${height}`);
-
-    // Clone and normalize the SVG for export
-    const exportSvg = this.prepareSvgForExport(svg, width, height);
-
-    // Convert foreignObject elements to native SVG text (for Word compatibility)
-    this.convertForeignObjectsToText(exportSvg);
-
-    // Serialize to string
-    let svgMarkup = new XMLSerializer().serializeToString(exportSvg);
-
-    // Post-process SVG string for Word compatibility
-    svgMarkup = this.fixSvgForWordCompatibility(svgMarkup);
-
-    // Base64 encode the SVG XML
-    const base64Data = this.stringToBase64(svgMarkup);
-
-    debug.info('SVGConverter', `Successfully extracted SVG ${id} (${width}x${height})`);
-
-    return {
-      id,
-      data: base64Data,
-      width,
-      height,
-      format: 'svg',
-    };
-  }
-
-  /**
-   * Prepare SVG for export: clone, set explicit dimensions, ensure namespace,
-   * and inline computed styles for Word compatibility.
-   */
-  private prepareSvgForExport(svg: SVGElement, width: number, height: number): SVGElement {
-    const clone = svg.cloneNode(true) as SVGElement;
-
-    // Set explicit dimensions
-    clone.setAttribute('width', String(width));
-    clone.setAttribute('height', String(height));
-
-    // Ensure xmlns attributes are present (required for standalone SVG)
-    if (!clone.getAttribute('xmlns')) {
-      clone.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
-    }
-    if (!clone.getAttribute('xmlns:xlink')) {
-      clone.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink');
-    }
-
-    // Inline computed styles for all elements (Word doesn't process CSS well)
-    this.inlineAllStyles(svg, clone);
-
-    return clone;
-  }
-
-  /**
-   * Inline computed styles from the original SVG to the clone.
-   * This ensures all styling survives when embedded in Word.
-   */
-  private inlineAllStyles(originalSvg: SVGElement, cloneSvg: SVGElement): void {
-    // Get all elements that could have visual styles
-    const selectors = [
-      'path',
-      'line',
-      'polyline',
-      'polygon',
-      'rect',
-      'circle',
-      'ellipse',
-      'text',
-      'tspan',
-      'g',
-    ];
-
-    for (const selector of selectors) {
-      const originalElements = Array.from(originalSvg.querySelectorAll(selector));
-      const cloneElements = Array.from(cloneSvg.querySelectorAll(selector));
-
-      if (originalElements.length !== cloneElements.length) {
-        debug.debug(
-          'SVGConverter',
-          `Element count mismatch for "${selector}": ${originalElements.length} vs ${cloneElements.length}`
-        );
-        continue;
-      }
-
-      originalElements.forEach((originalEl, index) => {
-        const cloneEl = cloneElements[index] as SVGElement;
-        if (!cloneEl) return;
-
-        this.inlineSingleElementStyles(originalEl as SVGElement, cloneEl);
-      });
-    }
-
-    // Also process elements inside defs (markers, etc.)
-    this.inlineDefsStyles(originalSvg, cloneSvg);
-
-    debug.info('SVGConverter', 'Inlined all computed styles for Word compatibility');
-  }
-
-  /**
-   * Inline all relevant computed styles for a single element.
-   */
-  private inlineSingleElementStyles(original: SVGElement, clone: SVGElement): void {
-    try {
-      const computed = window.getComputedStyle(original);
-
-      // Common properties for all elements
-      const fill = computed.fill;
-      if (fill && fill !== 'none' && !fill.startsWith('url(')) {
-        clone.setAttribute('fill', fill);
-      } else if (!clone.hasAttribute('fill') && original.tagName.toLowerCase() !== 'g') {
-        // Preserve 'none' explicitly if that's what it should be
-        const originalFill = original.getAttribute('fill');
-        if (originalFill) {
-          clone.setAttribute('fill', originalFill);
-        }
-      }
-
-      const stroke = computed.stroke;
-      if (stroke && stroke !== 'none') {
-        clone.setAttribute('stroke', stroke);
-      }
-
-      const strokeWidth = computed.strokeWidth;
-      if (strokeWidth && strokeWidth !== '0' && strokeWidth !== '0px') {
-        clone.setAttribute('stroke-width', strokeWidth);
-      }
-
-      // Stroke dash array (for dashed lines)
-      // Important: stroke-dasharray:0 causes lines to disappear in Word
-      // Convert "0" to "none" for compatibility
-      const strokeDasharray = computed.strokeDasharray;
-      if (strokeDasharray && strokeDasharray !== 'none') {
-        // Fix: stroke-dasharray of "0" should be "none" for Word compatibility
-        const fixedDasharray = strokeDasharray === '0' || strokeDasharray === '0px' ? 'none' : strokeDasharray;
-        if (fixedDasharray !== 'none') {
-          clone.setAttribute('stroke-dasharray', fixedDasharray);
-        }
-      }
-
-      // Stroke line cap and join
-      const strokeLinecap = computed.strokeLinecap;
-      if (strokeLinecap && strokeLinecap !== 'butt') {
-        clone.setAttribute('stroke-linecap', strokeLinecap);
-      }
-
-      const strokeLinejoin = computed.strokeLinejoin;
-      if (strokeLinejoin && strokeLinejoin !== 'miter') {
-        clone.setAttribute('stroke-linejoin', strokeLinejoin);
-      }
-
-      // Opacity
-      const opacity = computed.opacity;
-      if (opacity && opacity !== '1') {
-        clone.setAttribute('opacity', opacity);
-      }
-
-      // Text-specific properties
-      const tagName = original.tagName.toLowerCase();
-      if (tagName === 'text' || tagName === 'tspan') {
-        const fontSize = computed.fontSize;
-        if (fontSize) {
-          clone.setAttribute('font-size', fontSize);
-        }
-
-        const fontFamily = computed.fontFamily;
-        if (fontFamily) {
-          clone.setAttribute('font-family', fontFamily.replace(/["']/g, ''));
-        }
-
-        const fontWeight = computed.fontWeight;
-        if (fontWeight && fontWeight !== 'normal' && fontWeight !== '400') {
-          clone.setAttribute('font-weight', fontWeight);
-        }
-
-        const textAnchor = computed.textAnchor;
-        if (textAnchor && textAnchor !== 'start') {
-          clone.setAttribute('text-anchor', textAnchor);
-        }
-
-        const dominantBaseline = computed.dominantBaseline;
-        if (dominantBaseline && dominantBaseline !== 'auto') {
-          clone.setAttribute('dominant-baseline', dominantBaseline);
-        }
-      }
-
-      // Preserve marker references (these are URL references, not computed styles)
-      const markerEnd = original.getAttribute('marker-end');
-      if (markerEnd) {
-        clone.setAttribute('marker-end', markerEnd);
-      }
-
-      const markerStart = original.getAttribute('marker-start');
-      if (markerStart) {
-        clone.setAttribute('marker-start', markerStart);
-      }
-
-      const markerMid = original.getAttribute('marker-mid');
-      if (markerMid) {
-        clone.setAttribute('marker-mid', markerMid);
-      }
-    } catch (error) {
-      // getComputedStyle can fail for detached elements
-      debug.debug('SVGConverter', `Could not get computed style for element`);
-    }
-  }
-
-  /**
-   * Inline styles for elements inside defs (markers, gradients, etc.)
-   */
-  private inlineDefsStyles(originalSvg: SVGElement, cloneSvg: SVGElement): void {
-    const originalDefs = originalSvg.querySelector('defs');
-    const cloneDefs = cloneSvg.querySelector('defs');
-
-    if (!originalDefs || !cloneDefs) return;
-
-    // Process all shape elements inside defs
-    const selectors = ['path', 'polygon', 'circle', 'rect', 'line', 'polyline'];
-
-    for (const selector of selectors) {
-      const originalElements = Array.from(originalDefs.querySelectorAll(selector));
-      const cloneElements = Array.from(cloneDefs.querySelectorAll(selector));
-
-      if (originalElements.length !== cloneElements.length) continue;
-
-      originalElements.forEach((originalEl, index) => {
-        const cloneEl = cloneElements[index] as SVGElement;
-        if (!cloneEl) return;
-
-        // For defs elements, we need to be more aggressive about inlining
-        // since they might not be in the document flow
-        try {
-          const computed = window.getComputedStyle(originalEl);
-
-          const fill = computed.fill;
-          if (fill && fill !== 'none') {
-            cloneEl.setAttribute('fill', fill);
-          }
-
-          const stroke = computed.stroke;
-          if (stroke && stroke !== 'none') {
-            cloneEl.setAttribute('stroke', stroke);
-          }
-        } catch {
-          // If we can't get computed styles, copy the original attributes
-          const fill = (originalEl as SVGElement).getAttribute('fill');
-          if (fill) cloneEl.setAttribute('fill', fill);
-
-          const stroke = (originalEl as SVGElement).getAttribute('stroke');
-          if (stroke) cloneEl.setAttribute('stroke', stroke);
-        }
-      });
-    }
-
-    debug.debug('SVGConverter', 'Processed defs elements');
-  }
-
-  /**
-   * Fix SVG string for Word compatibility issues.
-   * - stroke-dasharray:0 causes lines to disappear in Word
-   * - Some style attributes need adjustment
-   */
-  private fixSvgForWordCompatibility(svgMarkup: string): string {
-    // Fix stroke-dasharray:0 which causes lines to disappear in Word
-    // This can appear in style attributes or as standalone attributes
-    let fixed = svgMarkup;
-
-    // Fix in style attributes: stroke-dasharray:0; or stroke-dasharray: 0;
-    fixed = fixed.replace(/stroke-dasharray:\s*0\s*;/g, 'stroke-dasharray:none;');
-    fixed = fixed.replace(/stroke-dasharray:\s*0px\s*;/g, 'stroke-dasharray:none;');
-
-    // Fix as standalone attribute: stroke-dasharray="0"
-    fixed = fixed.replace(/stroke-dasharray="0"/g, 'stroke-dasharray="none"');
-    fixed = fixed.replace(/stroke-dasharray="0px"/g, 'stroke-dasharray="none"');
-
-    // Remove any stroke-dasharray="none" as it's the default
-    // (This reduces file size and avoids potential issues)
-    fixed = fixed.replace(/\s*stroke-dasharray="none"/g, '');
-
-    debug.debug('SVGConverter', 'Applied Word compatibility fixes to SVG');
-
-    return fixed;
-  }
-
-  /**
-   * Convert foreignObject elements to native SVG text elements.
-   * Word does not support foreignObject, which Mermaid uses for HTML labels.
-   * This extracts the text content and creates SVG text elements instead.
-   */
-  private convertForeignObjectsToText(svg: SVGElement): void {
-    const foreignObjects = svg.querySelectorAll('foreignObject');
-    const existingTextElements = svg.querySelectorAll('text');
-    let convertedCount = 0;
-
-    debug.info(
-      'SVGConverter',
-      `SVG analysis: ${foreignObjects.length} foreignObjects, ${existingTextElements.length} existing text elements`
-    );
-
-    // Log sample of existing text elements
-    if (existingTextElements.length > 0) {
-      const samples = Array.from(existingTextElements).slice(0, 3);
-      samples.forEach((text, i) => {
-        debug.debug(
-          'SVGConverter',
-          `Existing text[${i}]: "${text.textContent?.substring(0, 50)}"`
-        );
-      });
-    }
-
-    foreignObjects.forEach((fo) => {
-      try {
-        // Get position and dimensions from foreignObject
-        const x = parseFloat(fo.getAttribute('x') || '0');
-        const y = parseFloat(fo.getAttribute('y') || '0');
-        const foWidth = parseFloat(fo.getAttribute('width') || '100');
-        const foHeight = parseFloat(fo.getAttribute('height') || '20');
-
-        // Extract text content from the HTML inside foreignObject
-        const textContent = this.extractTextFromHtml(fo);
-
-        if (!textContent.trim()) {
-          // No text content, just remove the foreignObject
-          fo.parentNode?.removeChild(fo);
-          return;
-        }
-
-        // Create SVG text element
-        const textElement = document.createElementNS('http://www.w3.org/2000/svg', 'text');
-
-        // Position text in the center of where foreignObject was
-        // Add half height to y because SVG text is positioned by baseline
-        textElement.setAttribute('x', String(x + foWidth / 2));
-        textElement.setAttribute('y', String(y + foHeight / 2));
-        textElement.setAttribute('text-anchor', 'middle');
-        textElement.setAttribute('dominant-baseline', 'middle');
-
-        // Extract and apply styles from the HTML content
-        const styles = this.extractStylesFromForeignObject(fo);
-        if (styles.fontSize) {
-          textElement.setAttribute('font-size', styles.fontSize);
-        } else {
-          textElement.setAttribute('font-size', '14px');
-        }
-        if (styles.fontFamily) {
-          textElement.setAttribute('font-family', styles.fontFamily);
-        } else {
-          textElement.setAttribute('font-family', 'sans-serif');
-        }
-        if (styles.fill) {
-          textElement.setAttribute('fill', styles.fill);
-        } else {
-          textElement.setAttribute('fill', '#333');
-        }
-        if (styles.fontWeight) {
-          textElement.setAttribute('font-weight', styles.fontWeight);
-        }
-
-        // Handle multi-line text by creating tspan elements
-        const lines = textContent.split('\n').filter((line) => line.trim());
-        if (lines.length === 1) {
-          textElement.textContent = lines[0].trim();
-        } else {
-          // Multi-line text: use tspan elements
-          const lineHeight = parseFloat(styles.fontSize || '14') * 1.2;
-          const startY = y + foHeight / 2 - ((lines.length - 1) * lineHeight) / 2;
-
-          lines.forEach((line, index) => {
-            const tspan = document.createElementNS('http://www.w3.org/2000/svg', 'tspan');
-            tspan.setAttribute('x', String(x + foWidth / 2));
-            tspan.setAttribute('dy', index === 0 ? '0' : String(lineHeight));
-            tspan.textContent = line.trim();
-            textElement.appendChild(tspan);
-          });
-
-          // Adjust the y position for multi-line
-          textElement.setAttribute('y', String(startY));
-        }
-
-        // Replace foreignObject with text element
-        const parent = fo.parentNode;
-        if (parent) {
-          parent.insertBefore(textElement, fo);
-          parent.removeChild(fo);
-          convertedCount++;
-        }
-      } catch (error) {
-        debug.warn('SVGConverter', `Failed to convert foreignObject to text:`, error);
-        // Remove the problematic foreignObject anyway
-        fo.parentNode?.removeChild(fo);
-      }
-    });
-
-    if (convertedCount > 0) {
-      debug.info('SVGConverter', `Converted ${convertedCount} foreignObject elements to SVG text`);
-    }
-  }
-
-  /**
-   * Extract plain text content from HTML inside foreignObject.
-   */
-  private extractTextFromHtml(fo: Element): string {
-    // Get all text content, preserving some structure
-    const html = fo.innerHTML;
-
-    // Create a temporary element to parse the HTML
-    const temp = document.createElement('div');
-    temp.innerHTML = html;
-
-    // Extract text, converting <br> and block elements to newlines
-    const extractText = (node: Node): string => {
-      if (node.nodeType === Node.TEXT_NODE) {
-        return node.textContent || '';
-      }
-
-      if (node.nodeType === Node.ELEMENT_NODE) {
-        const el = node as Element;
-        const tagName = el.tagName.toLowerCase();
-
-        // Block elements and br create line breaks
-        const isBlock = ['div', 'p', 'br', 'li', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(
-          tagName
-        );
-        const prefix = isBlock && el.previousSibling ? '\n' : '';
-
-        let text = prefix;
-        el.childNodes.forEach((child) => {
-          text += extractText(child);
-        });
-
-        return text;
-      }
-
-      return '';
-    };
-
-    return extractText(temp).trim();
-  }
-
-  /**
-   * Extract CSS styles from the HTML content inside foreignObject.
-   */
-  private extractStylesFromForeignObject(
-    fo: Element
-  ): { fontSize?: string; fontFamily?: string; fill?: string; fontWeight?: string } {
-    const styles: { fontSize?: string; fontFamily?: string; fill?: string; fontWeight?: string } =
-      {};
-
-    // Look for styled elements inside the foreignObject
-    const styledElements = fo.querySelectorAll('[style], span, div, p');
-
-    for (const el of styledElements) {
-      const htmlEl = el as HTMLElement;
-      const computedStyle = htmlEl.style;
-
-      // Try to get font-size
-      if (!styles.fontSize && computedStyle.fontSize) {
-        styles.fontSize = computedStyle.fontSize;
-      }
-
-      // Try to get font-family
-      if (!styles.fontFamily && computedStyle.fontFamily) {
-        styles.fontFamily = computedStyle.fontFamily;
-      }
-
-      // Try to get color (becomes fill in SVG)
-      if (!styles.fill && computedStyle.color) {
-        styles.fill = computedStyle.color;
-      }
-
-      // Try to get font-weight
-      if (!styles.fontWeight && computedStyle.fontWeight) {
-        styles.fontWeight = computedStyle.fontWeight;
-      }
-    }
-
-    // Also check the foreignObject itself for transform styles
-    const foStyle = (fo as HTMLElement).getAttribute('style');
-    if (foStyle) {
-      const fontSizeMatch = foStyle.match(/font-size:\s*([^;]+)/i);
-      if (fontSizeMatch && !styles.fontSize) {
-        styles.fontSize = fontSizeMatch[1].trim();
-      }
-    }
-
-    return styles;
-  }
-
-  /**
-   * Convert a string to base64.
-   */
-  private stringToBase64(str: string): string {
-    // Handle Unicode characters by encoding to UTF-8 first
-    const bytes = new TextEncoder().encode(str);
-    let binary = '';
-    for (let i = 0; i < bytes.length; i++) {
-      binary += String.fromCharCode(bytes[i]);
-    }
-    return btoa(binary);
-  }
-
-  /**
-   * Convert multiple SVGs in batch
-   */
-  convertAll(svgs: SVGElement[]): Map<string, ConvertedImage> {
-    debug.info('SVGConverter', `Extracting ${svgs.length} SVGs`);
-
-    const results = new Map<string, ConvertedImage>();
-
-    for (const svg of svgs) {
-      try {
-        const image = this.convert(svg);
-        results.set(image.id, image);
-      } catch (error) {
-        debug.error('SVGConverter', `Failed to extract SVG ${svg.id}:`, error);
-        // Continue with other SVGs
-      }
-    }
-
-    debug.info('SVGConverter', `Successfully extracted ${results.size}/${svgs.length} SVGs`);
-
-    return results;
-  }
-
-  /**
-   * Extract dimensions from SVG element
-   */
-  private getSVGDimensions(svg: SVGElement): { width: number; height: number } {
-    // Try width/height attributes first
-    const widthAttr = svg.getAttribute('width');
-    const heightAttr = svg.getAttribute('height');
-
-    if (widthAttr && heightAttr) {
-      const width = parseFloat(widthAttr);
-      const height = parseFloat(heightAttr);
-      if (!isNaN(width) && !isNaN(height)) {
-        return { width, height };
-      }
-    }
-
-    // Try viewBox
-    const viewBox = svg.getAttribute('viewBox');
-    if (viewBox) {
-      const parts = viewBox.split(/\s+|,/);
-      if (parts.length === 4) {
-        const width = parseFloat(parts[2]);
-        const height = parseFloat(parts[3]);
-        if (!isNaN(width) && !isNaN(height)) {
-          return { width, height };
-        }
-      }
-    }
-
-    // Try getBoundingClientRect as fallback
-    const rect = svg.getBoundingClientRect();
-    if (rect.width > 0 && rect.height > 0) {
-      return { width: rect.width, height: rect.height };
-    }
-
-    // Default dimensions
-    debug.warn('SVGConverter', 'Could not determine SVG dimensions, using defaults');
-    return { width: 800, height: 600 };
-  }
-}
+// Re-export shim: svg-converter has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/utils/svg-converter';

From 5b9d5e7a9893b7155d0acaaf43093392d1a1178b Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 09:12:38 -0400
Subject: [PATCH 21/26] refactor(core): move worker modules to @mdview/core

Move worker-pool, render-worker, and task modules (parse, highlight,
mermaid) to packages/core/src/workers/. Original files replaced with
re-export shims. Worker-pool uses createDebug() for platform-agnostic
logging instead of importing the Chrome-specific debug singleton.
---
 packages/core/src/lazy-section-renderer.ts    | 189 ++++++++
 packages/core/src/ui/toc-renderer.ts          | 427 +++++++++++++++++
 packages/core/src/workers/render-worker.ts    |  72 +++
 .../core/src/workers/tasks/highlight-task.ts  | 160 +++++++
 .../core/src/workers/tasks/mermaid-task.ts    |  95 ++++
 packages/core/src/workers/tasks/parse-task.ts | 220 +++++++++
 packages/core/src/workers/worker-pool.ts      | 301 ++++++++++++
 src/core/lazy-section-renderer.ts             | 192 +-------
 src/ui/toc-renderer.ts                        | 430 +-----------------
 src/workers/render-worker.ts                  |  73 +--
 src/workers/tasks/highlight-task.ts           | 161 +------
 src/workers/tasks/mermaid-task.ts             |  98 +---
 src/workers/tasks/parse-task.ts               | 221 +--------
 src/workers/worker-pool.ts                    | 300 +-----------
 14 files changed, 1475 insertions(+), 1464 deletions(-)
 create mode 100644 packages/core/src/lazy-section-renderer.ts
 create mode 100644 packages/core/src/ui/toc-renderer.ts
 create mode 100644 packages/core/src/workers/render-worker.ts
 create mode 100644 packages/core/src/workers/tasks/highlight-task.ts
 create mode 100644 packages/core/src/workers/tasks/mermaid-task.ts
 create mode 100644 packages/core/src/workers/tasks/parse-task.ts
 create mode 100644 packages/core/src/workers/worker-pool.ts

diff --git a/packages/core/src/lazy-section-renderer.ts b/packages/core/src/lazy-section-renderer.ts
new file mode 100644
index 0000000..217dbef
--- /dev/null
+++ b/packages/core/src/lazy-section-renderer.ts
@@ -0,0 +1,189 @@
+/**
+ * Lazy Section Renderer
+ * Renders markdown sections on-demand as they become visible
+ */
+
+import type { MarkdownSection } from './utils/section-splitter';
+import type { MarkdownConverter } from './markdown-converter';
+import { debug } from './utils/debug-logger';
+
+export interface LazySectionOptions {
+  rootMargin?: string;
+  threshold?: number;
+}
+
+export class LazySectionRenderer {
+  private observer: IntersectionObserver | null = null;
+  private pendingSections: Map<string, MarkdownSection> = new Map();
+  private renderedSections: Set<string> = new Set();
+  private converter: MarkdownConverter;
+  private onRender?: (section: MarkdownSection, html: string) => void;
+
+  constructor(converter: MarkdownConverter) {
+    this.converter = converter;
+  }
+
+  /**
+   * Initialize the lazy loading observer
+   */
+  initialize(options: LazySectionOptions = {}): void {
+    const { rootMargin = '500px', threshold = 0.01 } = options;
+
+    if (!('IntersectionObserver' in window)) {
+      debug.warn(
+        'LazySectionRenderer',
+        'IntersectionObserver not supported, will render all immediately'
+      );
+      return;
+    }
+
+    this.observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            const placeholder = entry.target as HTMLElement;
+            const sectionId = placeholder.dataset.sectionId;
+
+            if (sectionId && this.pendingSections.has(sectionId)) {
+              void this.renderSection(sectionId, placeholder);
+              this.observer?.unobserve(placeholder);
+            }
+          }
+        });
+      },
+      {
+        rootMargin,
+        threshold,
+      }
+    );
+
+    debug.info('LazySectionRenderer', `Lazy loading initialized (rootMargin: ${rootMargin})`);
+  }
+
+  /**
+   * Create a placeholder for a lazy-loaded section
+   */
+  createPlaceholder(section: MarkdownSection): HTMLElement {
+    const placeholder = document.createElement('div');
+    placeholder.className = 'mdview-section-placeholder';
+    placeholder.dataset.sectionId = section.id;
+    placeholder.dataset.heading = section.heading || '';
+
+    // Add visual placeholder content
+    placeholder.innerHTML = `
+      <div class="placeholder-content">
+        ${section.heading ? `<h${section.level || 2}>${section.heading}</h${section.level || 2}>` : ''}
+        <div class="placeholder-loading">Loading section...</div>
+      </div>
+    `;
+
+    // Store section for lazy loading
+    this.pendingSections.set(section.id, section);
+
+    // Observe for lazy loading
+    if (this.observer) {
+      this.observer.observe(placeholder);
+    } else {
+      // No observer support, render immediately
+      void this.renderSection(section.id, placeholder);
+    }
+
+    return placeholder;
+  }
+
+  /**
+   * Render a section when it becomes visible
+   */
+  private renderSection(sectionId: string, placeholder: HTMLElement): void {
+    const section = this.pendingSections.get(sectionId);
+    if (!section || this.renderedSections.has(sectionId)) {
+      return;
+    }
+
+    debug.debug('LazySectionRenderer', `Rendering section: ${section.heading || sectionId}`);
+
+    try {
+      // Convert markdown to HTML
+      const result = this.converter.convert(section.markdown);
+      const html = result.html;
+
+      // Create section container
+      const sectionContainer = document.createElement('div');
+      sectionContainer.className = 'mdview-section';
+      sectionContainer.dataset.sectionId = section.id;
+      sectionContainer.innerHTML = html;
+
+      // Replace placeholder with rendered content
+      placeholder.replaceWith(sectionContainer);
+
+      // Mark as rendered
+      this.renderedSections.add(sectionId);
+      this.pendingSections.delete(sectionId);
+
+      // Notify callback if provided
+      if (this.onRender) {
+        this.onRender(section, html);
+      }
+
+      debug.debug('LazySectionRenderer', `Section rendered: ${section.heading || sectionId}`);
+    } catch (error) {
+      debug.error('LazySectionRenderer', `Failed to render section ${sectionId}:`, error);
+
+      // Show error in placeholder
+      placeholder.innerHTML = `
+        <div class="mdview-section-error">
+          <p>Failed to render section</p>
+          <pre>${String(error)}</pre>
+        </div>
+      `;
+    }
+  }
+
+  /**
+   * Set callback for when a section is rendered
+   */
+  onSectionRender(callback: (section: MarkdownSection, html: string) => void): void {
+    this.onRender = callback;
+  }
+
+  /**
+   * Force render all pending sections
+   */
+  renderAll(): void {
+    debug.info(
+      'LazySectionRenderer',
+      `Force rendering ${this.pendingSections.size} pending sections`
+    );
+
+    for (const [sectionId] of this.pendingSections) {
+      const placeholder = document.querySelector(`[data-section-id="${sectionId}"]`) as HTMLElement;
+      if (placeholder) {
+        this.renderSection(sectionId, placeholder);
+      }
+    }
+  }
+
+  /**
+   * Get rendering statistics
+   */
+  getStats() {
+    return {
+      pending: this.pendingSections.size,
+      rendered: this.renderedSections.size,
+      total: this.pendingSections.size + this.renderedSections.size,
+    };
+  }
+
+  /**
+   * Clean up observer
+   */
+  cleanup(): void {
+    if (this.observer) {
+      this.observer.disconnect();
+      this.observer = null;
+    }
+    this.pendingSections.clear();
+    this.renderedSections.clear();
+    debug.debug('LazySectionRenderer', 'Cleaned up');
+  }
+}
diff --git a/packages/core/src/ui/toc-renderer.ts b/packages/core/src/ui/toc-renderer.ts
new file mode 100644
index 0000000..f091149
--- /dev/null
+++ b/packages/core/src/ui/toc-renderer.ts
@@ -0,0 +1,427 @@
+/**
+ * TOC Renderer
+ * Generates and manages a floating Table of Contents overlay
+ */
+
+import type { HeadingInfo } from '../types/index';
+import { debug } from '../utils/debug-logger';
+
+interface TocOptions {
+  maxDepth?: number; // Max heading level to show (1-6)
+  autoCollapse?: boolean; // Auto-collapse nested sections
+  position?: 'left' | 'right'; // Position of TOC
+}
+
+interface TocNode {
+  heading: HeadingInfo;
+  children: TocNode[];
+  element?: HTMLElement;
+  isExpanded?: boolean;
+}
+
+export class TocRenderer {
+  private container: HTMLElement | null = null;
+  private toggleButton: HTMLElement | null = null;
+  private headings: HeadingInfo[] = [];
+  private options: TocOptions;
+  private activeHeadingId: string | null = null;
+  private scrollListener: (() => void) | null = null;
+
+  constructor(options: TocOptions = {}) {
+    this.options = {
+      maxDepth: options.maxDepth || 6,
+      autoCollapse: options.autoCollapse !== undefined ? options.autoCollapse : false,
+      position: options.position || 'left',
+    };
+  }
+
+  /**
+   * Render the TOC overlay
+   */
+  render(headings: HeadingInfo[]): HTMLElement {
+    debug.info('TOC', `Rendering TOC with ${headings.length} headings`);
+
+    this.headings = headings.filter((h) => h.level <= (this.options.maxDepth || 6));
+
+    // Create container
+    this.container = document.createElement('div');
+    this.container.id = 'mdview-toc';
+    this.container.className = `mdview-toc-overlay position-${this.options.position || 'left'}`;
+
+    // Create header
+    const header = document.createElement('div');
+    header.className = 'mdview-toc-header';
+    header.innerHTML = `
+      <span class="mdview-toc-title">Contents</span>
+      <button class="mdview-toc-close" aria-label="Close table of contents">×</button>
+    `;
+    this.container.appendChild(header);
+
+    // Create scrollable content area
+    const content = document.createElement('div');
+    content.className = 'mdview-toc-content';
+
+    // Build tree structure
+    const tree = this.buildTree(this.headings);
+    const list = this.renderTree(tree);
+    content.appendChild(list);
+
+    this.container.appendChild(content);
+
+    // Setup event listeners
+    this.setupEventListeners();
+
+    // Setup scroll spy
+    this.setupScrollSpy();
+
+    debug.info('TOC', 'TOC rendered successfully');
+
+    return this.container;
+  }
+
+  /**
+   * Create on-page toggle button (called separately to always show)
+   */
+  createToggleButton(): void {
+    // Don't create if already exists
+    if (this.toggleButton) return;
+
+    this.toggleButton = document.createElement('button');
+    this.toggleButton.className = `mdview-toc-toggle-btn position-${this.options.position || 'left'}`;
+    this.toggleButton.setAttribute('aria-label', 'Toggle table of contents');
+    this.toggleButton.setAttribute('title', 'Toggle Table of Contents');
+    this.toggleButton.innerHTML = '☰';
+
+    this.toggleButton.addEventListener('click', () => {
+      this.toggle();
+      // Update preferences when toggled
+      const newState = this.container?.classList.contains('visible');
+      document.dispatchEvent(
+        new CustomEvent('mdview:toc:toggled', {
+          detail: { visible: newState },
+        })
+      );
+    });
+
+    document.body.appendChild(this.toggleButton);
+  }
+
+  /**
+   * Build a hierarchical tree from flat heading list
+   */
+  private buildTree(headings: HeadingInfo[]): TocNode[] {
+    const root: TocNode[] = [];
+    const stack: TocNode[] = [];
+
+    for (const heading of headings) {
+      const node: TocNode = {
+        heading,
+        children: [],
+        isExpanded: !this.options.autoCollapse || heading.level <= 2,
+      };
+
+      // Find the parent node
+      while (stack.length > 0) {
+        const parent = stack[stack.length - 1];
+        if (parent.heading.level < heading.level) {
+          parent.children.push(node);
+          break;
+        }
+        stack.pop();
+      }
+
+      // If no parent found, add to root
+      if (stack.length === 0) {
+        root.push(node);
+      }
+
+      stack.push(node);
+    }
+
+    return root;
+  }
+
+  /**
+   * Render tree nodes as nested lists
+   */
+  private renderTree(nodes: TocNode[]): HTMLElement {
+    const ul = document.createElement('ul');
+    ul.className = 'mdview-toc-list';
+
+    for (const node of nodes) {
+      const li = document.createElement('li');
+      li.className = `mdview-toc-item mdview-toc-level-${node.heading.level}`;
+      li.dataset.headingId = node.heading.id;
+
+      // Create link
+      const link = document.createElement('a');
+      link.href = `#${node.heading.id}`;
+      link.className = 'mdview-toc-link';
+      link.textContent = node.heading.text;
+      link.dataset.headingId = node.heading.id;
+
+      // Handle click
+      link.addEventListener('click', (e) => {
+        e.preventDefault();
+        this.scrollToHeading(node.heading.id);
+      });
+
+      li.appendChild(link);
+      node.element = li;
+
+      // Add children if any
+      if (node.children.length > 0) {
+        li.classList.add('has-children');
+
+        // Add expand/collapse toggle
+        if (this.options.autoCollapse) {
+          const toggle = document.createElement('button');
+          toggle.className = 'mdview-toc-toggle';
+          toggle.textContent = node.isExpanded ? '▼' : '▶';
+          toggle.setAttribute('aria-label', 'Toggle section');
+
+          toggle.addEventListener('click', (e) => {
+            e.stopPropagation();
+            this.toggleNode(node);
+          });
+
+          li.insertBefore(toggle, link);
+        }
+
+        const childList = this.renderTree(node.children);
+        if (!node.isExpanded) {
+          childList.style.display = 'none';
+        }
+        li.appendChild(childList);
+      }
+
+      ul.appendChild(li);
+    }
+
+    return ul;
+  }
+
+  /**
+   * Toggle expand/collapse state of a node
+   */
+  private toggleNode(node: TocNode): void {
+    if (!node.element) return;
+
+    node.isExpanded = !node.isExpanded;
+
+    const toggle = node.element.querySelector('.mdview-toc-toggle');
+    const childList = node.element.querySelector('ul');
+
+    if (toggle) {
+      toggle.textContent = node.isExpanded ? '▼' : '▶';
+    }
+
+    if (childList) {
+      childList.style.display = node.isExpanded ? 'block' : 'none';
+    }
+  }
+
+  /**
+   * Scroll to a heading smoothly
+   */
+  private scrollToHeading(headingId: string): void {
+    const target = document.getElementById(headingId);
+    if (!target) {
+      debug.warn('TOC', `Heading not found: ${headingId}`);
+      return;
+    }
+
+    target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+
+    // Update active state immediately
+    this.setActiveHeading(headingId);
+  }
+
+  /**
+   * Set up scroll spy to highlight current section
+   */
+  private setupScrollSpy(): void {
+    const updateActiveHeading = () => {
+      const scrollPosition = window.scrollY + 100; // Offset for better UX
+
+      // Find the current heading
+      let currentHeading: HeadingInfo | null = null;
+
+      for (let i = this.headings.length - 1; i >= 0; i--) {
+        const heading = this.headings[i];
+        const element = document.getElementById(heading.id);
+
+        if (element) {
+          const offsetTop = element.getBoundingClientRect().top + window.scrollY;
+          if (offsetTop <= scrollPosition) {
+            currentHeading = heading;
+            break;
+          }
+        }
+      }
+
+      if (currentHeading) {
+        this.setActiveHeading(currentHeading.id);
+      }
+    };
+
+    // Throttle scroll events for performance
+    let ticking = false;
+    this.scrollListener = () => {
+      if (!ticking) {
+        window.requestAnimationFrame(() => {
+          updateActiveHeading();
+          ticking = false;
+        });
+        ticking = true;
+      }
+    };
+
+    window.addEventListener('scroll', this.scrollListener, { passive: true });
+
+    // Initial update
+    updateActiveHeading();
+  }
+
+  /**
+   * Set the active heading in the TOC
+   */
+  private setActiveHeading(headingId: string): void {
+    if (this.activeHeadingId === headingId) return;
+
+    // Remove previous active state
+    if (this.activeHeadingId && this.container) {
+      const prevActive = this.container.querySelector(
+        `[data-heading-id="${this.activeHeadingId}"]`
+      );
+      if (prevActive) {
+        prevActive.classList.remove('active');
+      }
+    }
+
+    // Set new active state
+    this.activeHeadingId = headingId;
+
+    if (this.container) {
+      const newActive = this.container.querySelector(`[data-heading-id="${headingId}"]`);
+      if (newActive) {
+        newActive.classList.add('active');
+
+        // Scroll TOC to keep active item visible
+        const tocContent = this.container.querySelector('.mdview-toc-content');
+        if (tocContent && newActive instanceof HTMLElement) {
+          const tocRect = tocContent.getBoundingClientRect();
+          const itemRect = newActive.getBoundingClientRect();
+
+          if (itemRect.top < tocRect.top || itemRect.bottom > tocRect.bottom) {
+            newActive.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Set up event listeners
+   */
+  private setupEventListeners(): void {
+    if (!this.container) return;
+
+    // Close button
+    const closeButton = this.container.querySelector('.mdview-toc-close');
+    if (closeButton) {
+      closeButton.addEventListener('click', () => {
+        this.hide();
+      });
+    }
+
+    // Close on escape key
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        this.hide();
+      }
+    };
+    document.addEventListener('keydown', handleEscape);
+  }
+
+  /**
+   * Show the TOC
+   */
+  show(): void {
+    if (this.container) {
+      this.container.classList.add('visible');
+      const position = this.options.position || 'left';
+      document.body.classList.add(`toc-visible-${position}`);
+      debug.info('TOC', 'TOC shown');
+    }
+  }
+
+  /**
+   * Hide the TOC
+   */
+  hide(): void {
+    if (this.container) {
+      this.container.classList.remove('visible');
+      document.body.classList.remove('toc-visible-left', 'toc-visible-right');
+      debug.info('TOC', 'TOC hidden');
+
+      // Dispatch event for content script to update state
+      document.dispatchEvent(new CustomEvent('mdview:toc:hidden'));
+    }
+  }
+
+  /**
+   * Toggle TOC visibility
+   */
+  toggle(): void {
+    if (this.container?.classList.contains('visible')) {
+      this.hide();
+    } else {
+      this.show();
+    }
+  }
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void {
+    if (this.scrollListener) {
+      window.removeEventListener('scroll', this.scrollListener);
+      this.scrollListener = null;
+    }
+
+    if (this.toggleButton) {
+      this.toggleButton.remove();
+      this.toggleButton = null;
+    }
+
+    if (this.container) {
+      this.container.remove();
+      this.container = null;
+    }
+
+    document.body.classList.remove('toc-visible-left', 'toc-visible-right');
+
+    debug.info('TOC', 'TOC destroyed');
+  }
+
+  /**
+   * Update TOC options
+   */
+  updateOptions(options: Partial<TocOptions>): void {
+    this.options = { ...this.options, ...options };
+
+    // Re-render if container exists
+    if (this.container && this.headings.length > 0) {
+      const wasVisible = this.container.classList.contains('visible');
+      this.destroy();
+      const newContainer = this.render(this.headings);
+      document.body.appendChild(newContainer);
+      // Recreate the toggle button
+      this.createToggleButton();
+      if (wasVisible) {
+        this.show();
+      }
+    }
+  }
+}
diff --git a/packages/core/src/workers/render-worker.ts b/packages/core/src/workers/render-worker.ts
new file mode 100644
index 0000000..fbb66ec
--- /dev/null
+++ b/packages/core/src/workers/render-worker.ts
@@ -0,0 +1,72 @@
+/**
+ * Render Worker
+ * Generic web worker that handles markdown parsing, syntax highlighting, and mermaid rendering
+ */
+
+import type { WorkerTask, WorkerResponse } from '../types/index';
+
+// Import task handlers
+import { handleParseTask } from './tasks/parse-task';
+import { handleHighlightTask } from './tasks/highlight-task';
+import { handleMermaidTask } from './tasks/mermaid-task';
+
+/**
+ * Handle incoming messages
+ */
+self.onmessage = async (event: MessageEvent) => {
+  const task = event.data as WorkerTask;
+
+  try {
+    let result: unknown;
+
+    // Route to appropriate task handler
+    switch (task.type) {
+      case 'parse':
+        result = handleParseTask(task.payload);
+        break;
+
+      case 'highlight':
+        result = handleHighlightTask(task.payload);
+        break;
+
+      case 'mermaid':
+        result = await handleMermaidTask(task.payload);
+        break;
+
+      default: {
+        const exhaustiveCheck: never = task.type;
+        throw new Error(`Unknown task type: ${String(exhaustiveCheck)}`);
+      }
+    }
+
+    // Send success response
+    const response: WorkerResponse = {
+      id: task.id,
+      result,
+    };
+
+    self.postMessage(response);
+  } catch (error) {
+    // Send error response
+    const response: WorkerResponse = {
+      id: task.id,
+      error: error instanceof Error ? error.message : String(error),
+    };
+
+    self.postMessage(response);
+  }
+};
+
+/**
+ * Handle errors
+ */
+self.onerror = (event: string | Event) => {
+  console.error('[RenderWorker] Error:', event);
+};
+
+/**
+ * Handle unhandled promise rejections
+ */
+self.onunhandledrejection = (event: PromiseRejectionEvent) => {
+  console.error('[RenderWorker] Unhandled promise rejection:', event.reason);
+};
diff --git a/packages/core/src/workers/tasks/highlight-task.ts b/packages/core/src/workers/tasks/highlight-task.ts
new file mode 100644
index 0000000..248e1a8
--- /dev/null
+++ b/packages/core/src/workers/tasks/highlight-task.ts
@@ -0,0 +1,160 @@
+/**
+ * Highlight Task
+ * Handles syntax highlighting in worker context
+ */
+
+import hljs from 'highlight.js/lib/core';
+import type { LanguageFn } from 'highlight.js';
+import type { HighlightTaskPayload, HighlightTaskResult } from '../../types/index';
+
+// Import common languages
+import javascript from 'highlight.js/lib/languages/javascript';
+import typescript from 'highlight.js/lib/languages/typescript';
+import python from 'highlight.js/lib/languages/python';
+import bash from 'highlight.js/lib/languages/bash';
+import json from 'highlight.js/lib/languages/json';
+import go from 'highlight.js/lib/languages/go';
+import rust from 'highlight.js/lib/languages/rust';
+import java from 'highlight.js/lib/languages/java';
+import cpp from 'highlight.js/lib/languages/cpp';
+import c from 'highlight.js/lib/languages/c';
+import csharp from 'highlight.js/lib/languages/csharp';
+import ruby from 'highlight.js/lib/languages/ruby';
+import php from 'highlight.js/lib/languages/php';
+import sql from 'highlight.js/lib/languages/sql';
+import yaml from 'highlight.js/lib/languages/yaml';
+import xml from 'highlight.js/lib/languages/xml';
+import css from 'highlight.js/lib/languages/css';
+import scss from 'highlight.js/lib/languages/scss';
+import markdown from 'highlight.js/lib/languages/markdown';
+import dockerfile from 'highlight.js/lib/languages/dockerfile';
+import nginx from 'highlight.js/lib/languages/nginx';
+import apache from 'highlight.js/lib/languages/apache';
+import perl from 'highlight.js/lib/languages/perl';
+import r from 'highlight.js/lib/languages/r';
+import swift from 'highlight.js/lib/languages/swift';
+import kotlin from 'highlight.js/lib/languages/kotlin';
+import scala from 'highlight.js/lib/languages/scala';
+import haskell from 'highlight.js/lib/languages/haskell';
+import lua from 'highlight.js/lib/languages/lua';
+import vim from 'highlight.js/lib/languages/vim';
+import diff from 'highlight.js/lib/languages/diff';
+import makefile from 'highlight.js/lib/languages/makefile';
+import ini from 'highlight.js/lib/languages/ini';
+import properties from 'highlight.js/lib/languages/properties';
+
+// Register all languages
+const languages: Record<string, LanguageFn> = {
+  javascript,
+  typescript,
+  python,
+  bash,
+  json,
+  go,
+  rust,
+  java,
+  cpp,
+  c,
+  csharp,
+  ruby,
+  php,
+  sql,
+  yaml,
+  xml,
+  html: xml,
+  css,
+  scss,
+  markdown,
+  dockerfile,
+  nginx,
+  apache,
+  perl,
+  r,
+  swift,
+  kotlin,
+  scala,
+  haskell,
+  lua,
+  vim,
+  diff,
+  makefile,
+  ini,
+  properties,
+};
+
+// Register languages
+for (const [name, lang] of Object.entries(languages)) {
+  hljs.registerLanguage(name, lang);
+}
+
+// Configure highlight.js
+hljs.configure({
+  classPrefix: 'hljs-',
+  ignoreUnescapedHTML: true,
+});
+
+// Language aliases
+const languageAliases: Record<string, string> = {
+  js: 'javascript',
+  ts: 'typescript',
+  py: 'python',
+  sh: 'bash',
+  yml: 'yaml',
+  md: 'markdown',
+};
+
+/**
+ * Handle syntax highlighting task
+ */
+export function handleHighlightTask(payload: unknown): HighlightTaskResult {
+  const { code, language } = payload as HighlightTaskPayload;
+
+  // Normalize language name
+  const normalizedLang = normalizeLanguage(language);
+
+  try {
+    // Check if language is available
+    if (hljs.getLanguage(normalizedLang)) {
+      const result = hljs.highlight(code, {
+        language: normalizedLang,
+        ignoreIllegals: true,
+      });
+
+      return {
+        html: result.value,
+        language: normalizedLang,
+      };
+    } else {
+      // Fallback: auto-detect
+      const result = hljs.highlightAuto(code);
+      return {
+        html: result.value,
+        language: result.language || 'plaintext',
+      };
+    }
+  } catch (error) {
+    console.error(`[HighlightTask] Error highlighting ${normalizedLang}:`, error);
+    // Return unformatted code
+    return {
+      html: escapeHtml(code),
+      language: 'plaintext',
+    };
+  }
+}
+
+/**
+ * Normalize language name
+ */
+function normalizeLanguage(language: string): string {
+  const lower = language.toLowerCase();
+  return languageAliases[lower] || lower;
+}
+
+/**
+ * Escape HTML
+ */
+function escapeHtml(text: string): string {
+  const div = document.createElement('div');
+  div.textContent = text;
+  return div.innerHTML;
+}
diff --git a/packages/core/src/workers/tasks/mermaid-task.ts b/packages/core/src/workers/tasks/mermaid-task.ts
new file mode 100644
index 0000000..88c162a
--- /dev/null
+++ b/packages/core/src/workers/tasks/mermaid-task.ts
@@ -0,0 +1,95 @@
+/**
+ * Mermaid Task
+ * Handles Mermaid diagram rendering in worker context
+ */
+
+import mermaid from 'mermaid';
+import type { MermaidTaskPayload, MermaidTaskResult } from '../../types/index';
+
+// Initialize Mermaid
+mermaid.initialize({
+  startOnLoad: false,
+  securityLevel: 'strict',
+  maxTextSize: 50000,
+  maxEdges: 500,
+  theme: 'base',
+  flowchart: {
+    htmlLabels: false,
+    useMaxWidth: true,
+  },
+  sequence: {
+    useMaxWidth: true,
+  },
+  gantt: {
+    useMaxWidth: true,
+  },
+});
+
+/**
+ * Handle Mermaid rendering task
+ */
+export async function handleMermaidTask(payload: unknown): Promise<MermaidTaskResult> {
+  const { code, theme, id } = payload as MermaidTaskPayload;
+
+  try {
+    // Apply theme if provided
+    if (theme) {
+      mermaid.initialize({
+        theme: theme.theme,
+        themeVariables: theme.themeVariables,
+      });
+    }
+
+    // Validate syntax
+    const validation = await validateSyntax(code);
+    if (!validation.valid) {
+      throw new Error(validation.error || 'Invalid Mermaid syntax');
+    }
+
+    // Generate unique ID for SVG
+    const svgId = `mermaid-svg-${id}`;
+
+    // Render with timeout
+    const renderPromise = mermaid.render(svgId, code);
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => reject(new Error('Render timeout')), 5000);
+    });
+
+    const result = await Promise.race([renderPromise, timeoutPromise]);
+
+    return {
+      svg: result.svg,
+      id,
+    };
+  } catch (error) {
+    console.error('[MermaidTask] Render error:', error);
+    throw error;
+  }
+}
+
+/**
+ * Validate Mermaid syntax
+ */
+async function validateSyntax(code: string): Promise<{ valid: boolean; error?: string }> {
+  try {
+    // Basic validation
+    if (!code.trim()) {
+      return { valid: false, error: 'Empty diagram code' };
+    }
+
+    // Check size limits
+    if (code.length > 50000) {
+      return { valid: false, error: 'Diagram code exceeds size limit (50,000 characters)' };
+    }
+
+    // Try to parse
+    await mermaid.parse(code);
+
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : 'Parse error',
+    };
+  }
+}
diff --git a/packages/core/src/workers/tasks/parse-task.ts b/packages/core/src/workers/tasks/parse-task.ts
new file mode 100644
index 0000000..7cff2e4
--- /dev/null
+++ b/packages/core/src/workers/tasks/parse-task.ts
@@ -0,0 +1,220 @@
+/**
+ * Parse Task
+ * Handles markdown parsing in worker context
+ */
+
+import MarkdownIt from 'markdown-it';
+import markdownItAttrs from 'markdown-it-attrs';
+import markdownItAnchor from 'markdown-it-anchor';
+import markdownItTaskLists from 'markdown-it-task-lists';
+import * as emojiPlugin from 'markdown-it-emoji';
+import type {
+  ParseTaskPayload,
+  ParseTaskResult,
+  HeadingInfo,
+  CodeBlockInfo,
+  MermaidBlockInfo,
+  ImageInfo,
+  LinkInfo,
+} from '../../types/index';
+
+/**
+ * Handle markdown parsing task
+ */
+export function handleParseTask(payload: unknown): ParseTaskResult {
+  const { markdown, options } = payload as ParseTaskPayload;
+
+  // Metadata collection
+  const metadata = {
+    wordCount: 0,
+    headings: [] as HeadingInfo[],
+    codeBlocks: [] as CodeBlockInfo[],
+    mermaidBlocks: [] as MermaidBlockInfo[],
+    images: [] as ImageInfo[],
+    links: [] as LinkInfo[],
+    frontmatter: null as Record<string, string> | null,
+  };
+
+  // Initialize markdown-it
+  const md = new MarkdownIt({
+    html: options?.enableHtml ?? false, // Security: no raw HTML tags by default
+    breaks: options?.breaks ?? true,
+    linkify: options?.linkify ?? true,
+    typographer: options?.typographer ?? true,
+  });
+
+  // Configure plugins
+  md.use(markdownItAttrs, {
+    leftDelimiter: '{',
+    rightDelimiter: '}',
+    allowedAttributes: ['id', 'class', 'style'],
+  });
+
+  md.use(markdownItAnchor, {
+    permalink: markdownItAnchor.permalink.headerLink({
+      safariReaderFix: true,
+    }),
+    slugify: (s: string) =>
+      s
+        .toLowerCase()
+        .trim()
+        .replace(/[\s\W-]+/g, '-')
+        .replace(/^-+|-+$/g, ''),
+  });
+
+  md.use(markdownItTaskLists, {
+    enabled: true,
+    label: true,
+    labelAfter: true,
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unnecessary-type-assertion
+  const emojiPluginToUse = ((emojiPlugin as any).full || emojiPlugin) as any;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+  md.use(emojiPluginToUse);
+
+  // Add custom fence renderer for code blocks and mermaid
+  const defaultFenceRenderer =
+    md.renderer.rules.fence ||
+    function (tokens, idx, opts, _env, self) {
+      return self.renderToken(tokens, idx, opts);
+    };
+
+  md.renderer.rules.fence = (tokens, idx, opts, env, self) => {
+    const token = tokens[idx];
+    const info = token.info ? token.info.trim() : '';
+    const langName = info.split(/\s+/g)[0];
+
+    // Handle Mermaid diagrams
+    if (langName === 'mermaid' || langName === 'mmd') {
+      const code = token.content.trim();
+      const id = `mermaid-${Math.random().toString(36).substr(2, 9)}`;
+
+      metadata.mermaidBlocks.push({
+        code,
+        line: token.map ? token.map[0] : 0,
+      });
+
+      // Return container with data attribute for code
+      return `<div class="mermaid-container" id="${id}" data-mermaid-code="${escapeHtml(code)}">
+        <div class="mermaid-loading">Rendering diagram...</div>
+      </div>\n`;
+    }
+
+    // Handle regular code blocks
+    if (langName) {
+      metadata.codeBlocks.push({
+        language: langName,
+        code: token.content,
+        line: token.map ? token.map[0] : 0,
+        lines: token.content.split('\n').length,
+      });
+    }
+
+    return defaultFenceRenderer(tokens, idx, opts, env, self);
+  };
+
+  // Add heading renderer for metadata
+  const defaultHeadingOpenRenderer =
+    md.renderer.rules.heading_open ||
+    function (tokens, idx, opts, _env, self) {
+      return self.renderToken(tokens, idx, opts);
+    };
+
+  md.renderer.rules.heading_open = (tokens, idx, opts, env, self) => {
+    const token = tokens[idx];
+    const level = parseInt(token.tag.substr(1));
+    const nextToken = tokens[idx + 1];
+    const text = nextToken && nextToken.type === 'inline' ? nextToken.content : '';
+
+    const id = text
+      .toLowerCase()
+      .trim()
+      .replace(/[\s\W-]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+
+    metadata.headings.push({
+      level,
+      text,
+      id,
+      line: token.map ? token.map[0] : 0,
+    });
+
+    return defaultHeadingOpenRenderer(tokens, idx, opts, env, self);
+  };
+
+  // Add image renderer for metadata
+  const defaultImageRenderer =
+    md.renderer.rules.image ||
+    function (tokens, idx, opts, _env, self) {
+      return self.renderToken(tokens, idx, opts);
+    };
+
+  md.renderer.rules.image = (tokens, idx, opts, env, self) => {
+    const token = tokens[idx];
+    const srcIndex = token.attrIndex('src');
+    const attrs = token.attrs || [];
+    const src = srcIndex >= 0 ? attrs[srcIndex][1] : '';
+    const alt = token.content;
+    const titleIndex = token.attrIndex('title');
+    const title = titleIndex >= 0 ? attrs[titleIndex][1] : undefined;
+
+    metadata.images.push({
+      src,
+      alt,
+      title,
+      line: token.map ? token.map[0] : 0,
+    });
+
+    return defaultImageRenderer(tokens, idx, opts, env, self);
+  };
+
+  // Add link renderer for metadata
+  const defaultLinkOpenRenderer =
+    md.renderer.rules.link_open ||
+    function (tokens, idx, opts, _env, self) {
+      return self.renderToken(tokens, idx, opts);
+    };
+
+  md.renderer.rules.link_open = (tokens, idx, opts, env, self) => {
+    const token = tokens[idx];
+    const hrefIndex = token.attrIndex('href');
+    const attrs = token.attrs || [];
+    const href = hrefIndex >= 0 ? attrs[hrefIndex][1] : '';
+    const nextToken = tokens[idx + 1];
+    const text = nextToken && nextToken.type === 'inline' ? nextToken.content : '';
+
+    metadata.links.push({
+      href,
+      text,
+      line: token.map ? token.map[0] : 0,
+    });
+
+    return defaultLinkOpenRenderer(tokens, idx, opts, env, self);
+  };
+
+  // Calculate word count
+  metadata.wordCount = markdown.trim().split(/\s+/).length;
+
+  // Parse markdown
+  const html = md.render(markdown);
+
+  return {
+    html,
+    metadata,
+  };
+}
+
+/**
+ * Escape HTML for safe attribute values
+ */
+function escapeHtml(text: string): string {
+  const map: { [key: string]: string } = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;',
+  };
+  return text.replace(/[&<>"']/g, (m) => map[m]);
+}
diff --git a/packages/core/src/workers/worker-pool.ts b/packages/core/src/workers/worker-pool.ts
new file mode 100644
index 0000000..274dda0
--- /dev/null
+++ b/packages/core/src/workers/worker-pool.ts
@@ -0,0 +1,301 @@
+/**
+ * Worker Pool Manager
+ * Manages a pool of web workers for parallel processing
+ */
+
+import type { WorkerTask, WorkerResponse } from '../types/index';
+import { createDebug } from '../utils/debug-logger';
+
+const debug = createDebug();
+
+export interface WorkerPoolOptions {
+  poolSize?: number; // Number of workers (default: navigator.hardwareConcurrency or 4)
+  maxQueueSize?: number; // Max queued tasks (default: 100)
+  workerScript?: string; // Path to worker script
+}
+
+interface PendingTask {
+  task: WorkerTask;
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+  priority: number;
+}
+
+export class WorkerPool {
+  private workers: Worker[] = [];
+  private taskQueue: PendingTask[] = [];
+  private activeTasksPerWorker: Map<Worker, number> = new Map();
+  private taskCallbacks: Map<string, PendingTask> = new Map();
+  private poolSize: number;
+  private maxQueueSize: number;
+  private initialized = false;
+
+  constructor(options: WorkerPoolOptions = {}) {
+    this.poolSize = options.poolSize || navigator.hardwareConcurrency || 4;
+    this.maxQueueSize = options.maxQueueSize || 100;
+
+    debug.debug('WorkerPool', `Creating pool with ${this.poolSize} workers`);
+  }
+
+  /**
+   * Initialize worker pool
+   * Note: Workers don't work on file:// URLs due to Chrome security restrictions
+   * The synchronous fallback is well-optimized with Phase 1 performance improvements
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    // Check if we're on a file:// URL - workers don't work there
+    if (window.location.protocol === 'file:') {
+      debug.info(
+        'WorkerPool',
+        'Workers unavailable on file:// URLs (Chrome restriction), using synchronous rendering'
+      );
+      throw new Error('Workers not available on file:// URLs');
+    }
+
+    try {
+      // Import worker module (works on http:// and https:// URLs)
+      const RenderWorker = await import('./render-worker?worker');
+
+      debug.debug('WorkerPool', `Creating pool with ${this.poolSize} workers`);
+
+      for (let i = 0; i < this.poolSize; i++) {
+        const worker = new RenderWorker.default();
+
+        worker.addEventListener('message', this.handleWorkerMessage.bind(this));
+        worker.addEventListener('error', this.handleWorkerError.bind(this));
+
+        this.workers.push(worker);
+        this.activeTasksPerWorker.set(worker, 0);
+
+        debug.debug('WorkerPool', `Worker ${i + 1}/${this.poolSize} initialized`);
+      }
+
+      this.initialized = true;
+      debug.info('WorkerPool', '✅ Worker pool ready!');
+    } catch (error) {
+      debug.error('WorkerPool', 'Failed to initialize worker pool:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Execute a task in the worker pool
+   */
+  async execute<T = unknown>(task: WorkerTask): Promise<T> {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    return new Promise<T>((resolve, reject) => {
+      // Check queue size limit
+      if (this.taskQueue.length >= this.maxQueueSize) {
+        reject(new Error('Worker pool task queue is full'));
+        return;
+      }
+
+      const priority = task.priority || 0;
+      const pendingTask: PendingTask = {
+        task,
+        resolve: resolve as (value: unknown) => void,
+        reject,
+        priority,
+      };
+
+      // Try to execute immediately if a worker is available
+      const worker = this.getAvailableWorker();
+      if (worker) {
+        this.executeTask(worker, pendingTask);
+      } else {
+        // Queue the task
+        this.enqueueTask(pendingTask);
+      }
+    });
+  }
+
+  /**
+   * Handle worker message
+   */
+  private handleWorkerMessage(event: MessageEvent): void {
+    const response = event.data as WorkerResponse;
+
+    const pendingTask = this.taskCallbacks.get(response.id);
+    if (!pendingTask) {
+      debug.error('WorkerPool', 'Received response for unknown task:', response.id);
+      return;
+    }
+
+    // Remove from callbacks
+    this.taskCallbacks.delete(response.id);
+
+    // Decrease active task count for this worker
+    const worker = event.target as Worker;
+    const currentCount = this.activeTasksPerWorker.get(worker) || 0;
+    this.activeTasksPerWorker.set(worker, Math.max(0, currentCount - 1));
+
+    // Resolve or reject the task
+    if (response.error) {
+      debug.error('WorkerPool', `Task ${response.id} failed:`, response.error);
+      pendingTask.reject(new Error(response.error));
+    } else {
+      debug.debug('WorkerPool', `Task ${response.id} completed`);
+      pendingTask.resolve(response.result);
+    }
+
+    // Process next queued task if available
+    this.processQueue();
+  }
+
+  /**
+   * Handle worker error
+   */
+  private handleWorkerError(event: ErrorEvent): void {
+    debug.error('WorkerPool', 'Worker error:', event.message);
+
+    // Find and reject any tasks assigned to this worker
+    // Note: We don't currently track which worker has which task
+    // In a production system, you'd want to track this more carefully and reject only affected tasks
+  }
+
+  /**
+   * Get an available worker (least loaded)
+   */
+  private getAvailableWorker(): Worker | null {
+    if (this.workers.length === 0) {
+      return null;
+    }
+
+    // Find worker with fewest active tasks
+    let minTasks = Infinity;
+    let selectedWorker: Worker | null = null;
+
+    for (const worker of this.workers) {
+      const activeTasks = this.activeTasksPerWorker.get(worker) || 0;
+      if (activeTasks < minTasks) {
+        minTasks = activeTasks;
+        selectedWorker = worker;
+      }
+    }
+
+    // Return worker if it's not overloaded (max 3 tasks per worker)
+    if (selectedWorker && minTasks < 3) {
+      return selectedWorker;
+    }
+
+    return null;
+  }
+
+  /**
+   * Execute a task on a specific worker
+   */
+  private executeTask(worker: Worker, pendingTask: PendingTask): void {
+    // Increment active task count
+    const currentCount = this.activeTasksPerWorker.get(worker) || 0;
+    this.activeTasksPerWorker.set(worker, currentCount + 1);
+
+    // Store callback
+    this.taskCallbacks.set(pendingTask.task.id, pendingTask);
+
+    // Send task to worker
+    worker.postMessage(pendingTask.task);
+
+    debug.debug(
+      'WorkerPool',
+      `Dispatched task ${pendingTask.task.id} (type: ${pendingTask.task.type})`
+    );
+  }
+
+  /**
+   * Enqueue a task
+   */
+  private enqueueTask(pendingTask: PendingTask): void {
+    // Insert task in priority order (higher priority first)
+    let insertIndex = this.taskQueue.length;
+    for (let i = 0; i < this.taskQueue.length; i++) {
+      if (pendingTask.priority > this.taskQueue[i].priority) {
+        insertIndex = i;
+        break;
+      }
+    }
+
+    this.taskQueue.splice(insertIndex, 0, pendingTask);
+    debug.debug(
+      'WorkerPool',
+      `Queued task ${pendingTask.task.id}, queue size: ${this.taskQueue.length}`
+    );
+  }
+
+  /**
+   * Process queued tasks
+   */
+  private processQueue(): void {
+    while (this.taskQueue.length > 0) {
+      const worker = this.getAvailableWorker();
+      if (!worker) {
+        break;
+      }
+
+      const pendingTask = this.taskQueue.shift();
+      if (pendingTask) {
+        this.executeTask(worker, pendingTask);
+      }
+    }
+  }
+
+  /**
+   * Get pool statistics
+   */
+  getStats(): {
+    poolSize: number;
+    activeWorkers: number;
+    queuedTasks: number;
+    activeTasks: number;
+  } {
+    let activeTasks = 0;
+    for (const count of this.activeTasksPerWorker.values()) {
+      activeTasks += count;
+    }
+
+    return {
+      poolSize: this.workers.length,
+      activeWorkers: this.workers.filter((w) => (this.activeTasksPerWorker.get(w) || 0) > 0).length,
+      queuedTasks: this.taskQueue.length,
+      activeTasks,
+    };
+  }
+
+  /**
+   * Terminate all workers
+   */
+  terminate(): void {
+    debug.info('WorkerPool', 'Terminating worker pool');
+
+    // Reject all pending tasks
+    for (const pendingTask of this.taskCallbacks.values()) {
+      pendingTask.reject(new Error('Worker pool terminated'));
+    }
+    this.taskCallbacks.clear();
+
+    // Reject all queued tasks
+    for (const pendingTask of this.taskQueue) {
+      pendingTask.reject(new Error('Worker pool terminated'));
+    }
+    this.taskQueue = [];
+
+    // Terminate workers
+    for (const worker of this.workers) {
+      worker.terminate();
+    }
+    this.workers = [];
+    this.activeTasksPerWorker.clear();
+    this.initialized = false;
+
+    debug.info('WorkerPool', 'Worker pool terminated');
+  }
+}
+
+// Export singleton
+export const workerPool = new WorkerPool();
diff --git a/src/core/lazy-section-renderer.ts b/src/core/lazy-section-renderer.ts
index f0bd507..0280b5f 100644
--- a/src/core/lazy-section-renderer.ts
+++ b/src/core/lazy-section-renderer.ts
@@ -1,189 +1,3 @@
-/**
- * Lazy Section Renderer
- * Renders markdown sections on-demand as they become visible
- */
-
-import type { MarkdownSection } from '../utils/section-splitter';
-import type { MarkdownConverter } from './markdown-converter';
-import { debug } from '../utils/debug-logger';
-
-export interface LazySectionOptions {
-  rootMargin?: string;
-  threshold?: number;
-}
-
-export class LazySectionRenderer {
-  private observer: IntersectionObserver | null = null;
-  private pendingSections: Map<string, MarkdownSection> = new Map();
-  private renderedSections: Set<string> = new Set();
-  private converter: MarkdownConverter;
-  private onRender?: (section: MarkdownSection, html: string) => void;
-
-  constructor(converter: MarkdownConverter) {
-    this.converter = converter;
-  }
-
-  /**
-   * Initialize the lazy loading observer
-   */
-  initialize(options: LazySectionOptions = {}): void {
-    const { rootMargin = '500px', threshold = 0.01 } = options;
-
-    if (!('IntersectionObserver' in window)) {
-      debug.warn(
-        'LazySectionRenderer',
-        'IntersectionObserver not supported, will render all immediately'
-      );
-      return;
-    }
-
-    this.observer = new IntersectionObserver(
-      (entries) => {
-        entries.forEach((entry) => {
-          if (entry.isIntersecting) {
-            const placeholder = entry.target as HTMLElement;
-            const sectionId = placeholder.dataset.sectionId;
-
-            if (sectionId && this.pendingSections.has(sectionId)) {
-              void this.renderSection(sectionId, placeholder);
-              this.observer?.unobserve(placeholder);
-            }
-          }
-        });
-      },
-      {
-        rootMargin,
-        threshold,
-      }
-    );
-
-    debug.info('LazySectionRenderer', `Lazy loading initialized (rootMargin: ${rootMargin})`);
-  }
-
-  /**
-   * Create a placeholder for a lazy-loaded section
-   */
-  createPlaceholder(section: MarkdownSection): HTMLElement {
-    const placeholder = document.createElement('div');
-    placeholder.className = 'mdview-section-placeholder';
-    placeholder.dataset.sectionId = section.id;
-    placeholder.dataset.heading = section.heading || '';
-
-    // Add visual placeholder content
-    placeholder.innerHTML = `
-      <div class="placeholder-content">
-        ${section.heading ? `<h${section.level || 2}>${section.heading}</h${section.level || 2}>` : ''}
-        <div class="placeholder-loading">Loading section...</div>
-      </div>
-    `;
-
-    // Store section for lazy loading
-    this.pendingSections.set(section.id, section);
-
-    // Observe for lazy loading
-    if (this.observer) {
-      this.observer.observe(placeholder);
-    } else {
-      // No observer support, render immediately
-      void this.renderSection(section.id, placeholder);
-    }
-
-    return placeholder;
-  }
-
-  /**
-   * Render a section when it becomes visible
-   */
-  private renderSection(sectionId: string, placeholder: HTMLElement): void {
-    const section = this.pendingSections.get(sectionId);
-    if (!section || this.renderedSections.has(sectionId)) {
-      return;
-    }
-
-    debug.debug('LazySectionRenderer', `Rendering section: ${section.heading || sectionId}`);
-
-    try {
-      // Convert markdown to HTML
-      const result = this.converter.convert(section.markdown);
-      const html = result.html;
-
-      // Create section container
-      const sectionContainer = document.createElement('div');
-      sectionContainer.className = 'mdview-section';
-      sectionContainer.dataset.sectionId = section.id;
-      sectionContainer.innerHTML = html;
-
-      // Replace placeholder with rendered content
-      placeholder.replaceWith(sectionContainer);
-
-      // Mark as rendered
-      this.renderedSections.add(sectionId);
-      this.pendingSections.delete(sectionId);
-
-      // Notify callback if provided
-      if (this.onRender) {
-        this.onRender(section, html);
-      }
-
-      debug.debug('LazySectionRenderer', `Section rendered: ${section.heading || sectionId}`);
-    } catch (error) {
-      debug.error('LazySectionRenderer', `Failed to render section ${sectionId}:`, error);
-
-      // Show error in placeholder
-      placeholder.innerHTML = `
-        <div class="mdview-section-error">
-          <p>Failed to render section</p>
-          <pre>${String(error)}</pre>
-        </div>
-      `;
-    }
-  }
-
-  /**
-   * Set callback for when a section is rendered
-   */
-  onSectionRender(callback: (section: MarkdownSection, html: string) => void): void {
-    this.onRender = callback;
-  }
-
-  /**
-   * Force render all pending sections
-   */
-  renderAll(): void {
-    debug.info(
-      'LazySectionRenderer',
-      `Force rendering ${this.pendingSections.size} pending sections`
-    );
-
-    for (const [sectionId] of this.pendingSections) {
-      const placeholder = document.querySelector(`[data-section-id="${sectionId}"]`) as HTMLElement;
-      if (placeholder) {
-        this.renderSection(sectionId, placeholder);
-      }
-    }
-  }
-
-  /**
-   * Get rendering statistics
-   */
-  getStats() {
-    return {
-      pending: this.pendingSections.size,
-      rendered: this.renderedSections.size,
-      total: this.pendingSections.size + this.renderedSections.size,
-    };
-  }
-
-  /**
-   * Clean up observer
-   */
-  cleanup(): void {
-    if (this.observer) {
-      this.observer.disconnect();
-      this.observer = null;
-    }
-    this.pendingSections.clear();
-    this.renderedSections.clear();
-    debug.debug('LazySectionRenderer', 'Cleaned up');
-  }
-}
+// Re-export shim: lazy-section-renderer has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/lazy-section-renderer';
diff --git a/src/ui/toc-renderer.ts b/src/ui/toc-renderer.ts
index 0e1079c..5dd7fa4 100644
--- a/src/ui/toc-renderer.ts
+++ b/src/ui/toc-renderer.ts
@@ -1,427 +1,3 @@
-/**
- * TOC Renderer
- * Generates and manages a floating Table of Contents overlay
- */
-
-import type { HeadingInfo } from '../types';
-import { debug } from '../utils/debug-logger';
-
-interface TocOptions {
-  maxDepth?: number; // Max heading level to show (1-6)
-  autoCollapse?: boolean; // Auto-collapse nested sections
-  position?: 'left' | 'right'; // Position of TOC
-}
-
-interface TocNode {
-  heading: HeadingInfo;
-  children: TocNode[];
-  element?: HTMLElement;
-  isExpanded?: boolean;
-}
-
-export class TocRenderer {
-  private container: HTMLElement | null = null;
-  private toggleButton: HTMLElement | null = null;
-  private headings: HeadingInfo[] = [];
-  private options: TocOptions;
-  private activeHeadingId: string | null = null;
-  private scrollListener: (() => void) | null = null;
-
-  constructor(options: TocOptions = {}) {
-    this.options = {
-      maxDepth: options.maxDepth || 6,
-      autoCollapse: options.autoCollapse !== undefined ? options.autoCollapse : false,
-      position: options.position || 'left',
-    };
-  }
-
-  /**
-   * Render the TOC overlay
-   */
-  render(headings: HeadingInfo[]): HTMLElement {
-    debug.info('TOC', `Rendering TOC with ${headings.length} headings`);
-
-    this.headings = headings.filter((h) => h.level <= (this.options.maxDepth || 6));
-
-    // Create container
-    this.container = document.createElement('div');
-    this.container.id = 'mdview-toc';
-    this.container.className = `mdview-toc-overlay position-${this.options.position || 'left'}`;
-
-    // Create header
-    const header = document.createElement('div');
-    header.className = 'mdview-toc-header';
-    header.innerHTML = `
-      <span class="mdview-toc-title">Contents</span>
-      <button class="mdview-toc-close" aria-label="Close table of contents">×</button>
-    `;
-    this.container.appendChild(header);
-
-    // Create scrollable content area
-    const content = document.createElement('div');
-    content.className = 'mdview-toc-content';
-
-    // Build tree structure
-    const tree = this.buildTree(this.headings);
-    const list = this.renderTree(tree);
-    content.appendChild(list);
-
-    this.container.appendChild(content);
-
-    // Setup event listeners
-    this.setupEventListeners();
-
-    // Setup scroll spy
-    this.setupScrollSpy();
-
-    debug.info('TOC', 'TOC rendered successfully');
-
-    return this.container;
-  }
-
-  /**
-   * Create on-page toggle button (called separately to always show)
-   */
-  createToggleButton(): void {
-    // Don't create if already exists
-    if (this.toggleButton) return;
-
-    this.toggleButton = document.createElement('button');
-    this.toggleButton.className = `mdview-toc-toggle-btn position-${this.options.position || 'left'}`;
-    this.toggleButton.setAttribute('aria-label', 'Toggle table of contents');
-    this.toggleButton.setAttribute('title', 'Toggle Table of Contents');
-    this.toggleButton.innerHTML = '☰';
-
-    this.toggleButton.addEventListener('click', () => {
-      this.toggle();
-      // Update preferences when toggled
-      const newState = this.container?.classList.contains('visible');
-      document.dispatchEvent(
-        new CustomEvent('mdview:toc:toggled', {
-          detail: { visible: newState },
-        })
-      );
-    });
-
-    document.body.appendChild(this.toggleButton);
-  }
-
-  /**
-   * Build a hierarchical tree from flat heading list
-   */
-  private buildTree(headings: HeadingInfo[]): TocNode[] {
-    const root: TocNode[] = [];
-    const stack: TocNode[] = [];
-
-    for (const heading of headings) {
-      const node: TocNode = {
-        heading,
-        children: [],
-        isExpanded: !this.options.autoCollapse || heading.level <= 2,
-      };
-
-      // Find the parent node
-      while (stack.length > 0) {
-        const parent = stack[stack.length - 1];
-        if (parent.heading.level < heading.level) {
-          parent.children.push(node);
-          break;
-        }
-        stack.pop();
-      }
-
-      // If no parent found, add to root
-      if (stack.length === 0) {
-        root.push(node);
-      }
-
-      stack.push(node);
-    }
-
-    return root;
-  }
-
-  /**
-   * Render tree nodes as nested lists
-   */
-  private renderTree(nodes: TocNode[]): HTMLElement {
-    const ul = document.createElement('ul');
-    ul.className = 'mdview-toc-list';
-
-    for (const node of nodes) {
-      const li = document.createElement('li');
-      li.className = `mdview-toc-item mdview-toc-level-${node.heading.level}`;
-      li.dataset.headingId = node.heading.id;
-
-      // Create link
-      const link = document.createElement('a');
-      link.href = `#${node.heading.id}`;
-      link.className = 'mdview-toc-link';
-      link.textContent = node.heading.text;
-      link.dataset.headingId = node.heading.id;
-
-      // Handle click
-      link.addEventListener('click', (e) => {
-        e.preventDefault();
-        this.scrollToHeading(node.heading.id);
-      });
-
-      li.appendChild(link);
-      node.element = li;
-
-      // Add children if any
-      if (node.children.length > 0) {
-        li.classList.add('has-children');
-
-        // Add expand/collapse toggle
-        if (this.options.autoCollapse) {
-          const toggle = document.createElement('button');
-          toggle.className = 'mdview-toc-toggle';
-          toggle.textContent = node.isExpanded ? '▼' : '▶';
-          toggle.setAttribute('aria-label', 'Toggle section');
-
-          toggle.addEventListener('click', (e) => {
-            e.stopPropagation();
-            this.toggleNode(node);
-          });
-
-          li.insertBefore(toggle, link);
-        }
-
-        const childList = this.renderTree(node.children);
-        if (!node.isExpanded) {
-          childList.style.display = 'none';
-        }
-        li.appendChild(childList);
-      }
-
-      ul.appendChild(li);
-    }
-
-    return ul;
-  }
-
-  /**
-   * Toggle expand/collapse state of a node
-   */
-  private toggleNode(node: TocNode): void {
-    if (!node.element) return;
-
-    node.isExpanded = !node.isExpanded;
-
-    const toggle = node.element.querySelector('.mdview-toc-toggle');
-    const childList = node.element.querySelector('ul');
-
-    if (toggle) {
-      toggle.textContent = node.isExpanded ? '▼' : '▶';
-    }
-
-    if (childList) {
-      childList.style.display = node.isExpanded ? 'block' : 'none';
-    }
-  }
-
-  /**
-   * Scroll to a heading smoothly
-   */
-  private scrollToHeading(headingId: string): void {
-    const target = document.getElementById(headingId);
-    if (!target) {
-      debug.warn('TOC', `Heading not found: ${headingId}`);
-      return;
-    }
-
-    target.scrollIntoView({ behavior: 'smooth', block: 'start' });
-
-    // Update active state immediately
-    this.setActiveHeading(headingId);
-  }
-
-  /**
-   * Set up scroll spy to highlight current section
-   */
-  private setupScrollSpy(): void {
-    const updateActiveHeading = () => {
-      const scrollPosition = window.scrollY + 100; // Offset for better UX
-
-      // Find the current heading
-      let currentHeading: HeadingInfo | null = null;
-
-      for (let i = this.headings.length - 1; i >= 0; i--) {
-        const heading = this.headings[i];
-        const element = document.getElementById(heading.id);
-
-        if (element) {
-          const offsetTop = element.getBoundingClientRect().top + window.scrollY;
-          if (offsetTop <= scrollPosition) {
-            currentHeading = heading;
-            break;
-          }
-        }
-      }
-
-      if (currentHeading) {
-        this.setActiveHeading(currentHeading.id);
-      }
-    };
-
-    // Throttle scroll events for performance
-    let ticking = false;
-    this.scrollListener = () => {
-      if (!ticking) {
-        window.requestAnimationFrame(() => {
-          updateActiveHeading();
-          ticking = false;
-        });
-        ticking = true;
-      }
-    };
-
-    window.addEventListener('scroll', this.scrollListener, { passive: true });
-
-    // Initial update
-    updateActiveHeading();
-  }
-
-  /**
-   * Set the active heading in the TOC
-   */
-  private setActiveHeading(headingId: string): void {
-    if (this.activeHeadingId === headingId) return;
-
-    // Remove previous active state
-    if (this.activeHeadingId && this.container) {
-      const prevActive = this.container.querySelector(
-        `[data-heading-id="${this.activeHeadingId}"]`
-      );
-      if (prevActive) {
-        prevActive.classList.remove('active');
-      }
-    }
-
-    // Set new active state
-    this.activeHeadingId = headingId;
-
-    if (this.container) {
-      const newActive = this.container.querySelector(`[data-heading-id="${headingId}"]`);
-      if (newActive) {
-        newActive.classList.add('active');
-
-        // Scroll TOC to keep active item visible
-        const tocContent = this.container.querySelector('.mdview-toc-content');
-        if (tocContent && newActive instanceof HTMLElement) {
-          const tocRect = tocContent.getBoundingClientRect();
-          const itemRect = newActive.getBoundingClientRect();
-
-          if (itemRect.top < tocRect.top || itemRect.bottom > tocRect.bottom) {
-            newActive.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
-          }
-        }
-      }
-    }
-  }
-
-  /**
-   * Set up event listeners
-   */
-  private setupEventListeners(): void {
-    if (!this.container) return;
-
-    // Close button
-    const closeButton = this.container.querySelector('.mdview-toc-close');
-    if (closeButton) {
-      closeButton.addEventListener('click', () => {
-        this.hide();
-      });
-    }
-
-    // Close on escape key
-    const handleEscape = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        this.hide();
-      }
-    };
-    document.addEventListener('keydown', handleEscape);
-  }
-
-  /**
-   * Show the TOC
-   */
-  show(): void {
-    if (this.container) {
-      this.container.classList.add('visible');
-      const position = this.options.position || 'left';
-      document.body.classList.add(`toc-visible-${position}`);
-      debug.info('TOC', 'TOC shown');
-    }
-  }
-
-  /**
-   * Hide the TOC
-   */
-  hide(): void {
-    if (this.container) {
-      this.container.classList.remove('visible');
-      document.body.classList.remove('toc-visible-left', 'toc-visible-right');
-      debug.info('TOC', 'TOC hidden');
-
-      // Dispatch event for content script to update state
-      document.dispatchEvent(new CustomEvent('mdview:toc:hidden'));
-    }
-  }
-
-  /**
-   * Toggle TOC visibility
-   */
-  toggle(): void {
-    if (this.container?.classList.contains('visible')) {
-      this.hide();
-    } else {
-      this.show();
-    }
-  }
-
-  /**
-   * Clean up resources
-   */
-  destroy(): void {
-    if (this.scrollListener) {
-      window.removeEventListener('scroll', this.scrollListener);
-      this.scrollListener = null;
-    }
-
-    if (this.toggleButton) {
-      this.toggleButton.remove();
-      this.toggleButton = null;
-    }
-
-    if (this.container) {
-      this.container.remove();
-      this.container = null;
-    }
-
-    document.body.classList.remove('toc-visible-left', 'toc-visible-right');
-
-    debug.info('TOC', 'TOC destroyed');
-  }
-
-  /**
-   * Update TOC options
-   */
-  updateOptions(options: Partial<TocOptions>): void {
-    this.options = { ...this.options, ...options };
-
-    // Re-render if container exists
-    if (this.container && this.headings.length > 0) {
-      const wasVisible = this.container.classList.contains('visible');
-      this.destroy();
-      const newContainer = this.render(this.headings);
-      document.body.appendChild(newContainer);
-      // Recreate the toggle button
-      this.createToggleButton();
-      if (wasVisible) {
-        this.show();
-      }
-    }
-  }
-}
+// Re-export shim: toc-renderer has moved to @mdview/core
+// This shim will be removed in Phase 2.9
+export * from '../../packages/core/src/ui/toc-renderer';
diff --git a/src/workers/render-worker.ts b/src/workers/render-worker.ts
index 80237cc..643f989 100644
--- a/src/workers/render-worker.ts
+++ b/src/workers/render-worker.ts
@@ -1,72 +1 @@
-/**
- * Render Worker
- * Generic web worker that handles markdown parsing, syntax highlighting, and mermaid rendering
- */
-
-import type { WorkerTask, WorkerResponse } from '../types';
-
-// Import task handlers
-import { handleParseTask } from './tasks/parse-task';
-import { handleHighlightTask } from './tasks/highlight-task';
-import { handleMermaidTask } from './tasks/mermaid-task';
-
-/**
- * Handle incoming messages
- */
-self.onmessage = async (event: MessageEvent) => {
-  const task = event.data as WorkerTask;
-
-  try {
-    let result: unknown;
-
-    // Route to appropriate task handler
-    switch (task.type) {
-      case 'parse':
-        result = handleParseTask(task.payload);
-        break;
-
-      case 'highlight':
-        result = handleHighlightTask(task.payload);
-        break;
-
-      case 'mermaid':
-        result = await handleMermaidTask(task.payload);
-        break;
-
-      default: {
-        const exhaustiveCheck: never = task.type;
-        throw new Error(`Unknown task type: ${String(exhaustiveCheck)}`);
-      }
-    }
-
-    // Send success response
-    const response: WorkerResponse = {
-      id: task.id,
-      result,
-    };
-
-    self.postMessage(response);
-  } catch (error) {
-    // Send error response
-    const response: WorkerResponse = {
-      id: task.id,
-      error: error instanceof Error ? error.message : String(error),
-    };
-
-    self.postMessage(response);
-  }
-};
-
-/**
- * Handle errors
- */
-self.onerror = (event: string | Event) => {
-  console.error('[RenderWorker] Error:', event);
-};
-
-/**
- * Handle unhandled promise rejections
- */
-self.onunhandledrejection = (event: PromiseRejectionEvent) => {
-  console.error('[RenderWorker] Unhandled promise rejection:', event.reason);
-};
+export * from '../../packages/core/src/workers/render-worker';
diff --git a/src/workers/tasks/highlight-task.ts b/src/workers/tasks/highlight-task.ts
index b723667..c662868 100644
--- a/src/workers/tasks/highlight-task.ts
+++ b/src/workers/tasks/highlight-task.ts
@@ -1,160 +1 @@
-/**
- * Highlight Task
- * Handles syntax highlighting in worker context
- */
-
-import hljs from 'highlight.js/lib/core';
-import type { LanguageFn } from 'highlight.js';
-import type { HighlightTaskPayload, HighlightTaskResult } from '../../types';
-
-// Import common languages
-import javascript from 'highlight.js/lib/languages/javascript';
-import typescript from 'highlight.js/lib/languages/typescript';
-import python from 'highlight.js/lib/languages/python';
-import bash from 'highlight.js/lib/languages/bash';
-import json from 'highlight.js/lib/languages/json';
-import go from 'highlight.js/lib/languages/go';
-import rust from 'highlight.js/lib/languages/rust';
-import java from 'highlight.js/lib/languages/java';
-import cpp from 'highlight.js/lib/languages/cpp';
-import c from 'highlight.js/lib/languages/c';
-import csharp from 'highlight.js/lib/languages/csharp';
-import ruby from 'highlight.js/lib/languages/ruby';
-import php from 'highlight.js/lib/languages/php';
-import sql from 'highlight.js/lib/languages/sql';
-import yaml from 'highlight.js/lib/languages/yaml';
-import xml from 'highlight.js/lib/languages/xml';
-import css from 'highlight.js/lib/languages/css';
-import scss from 'highlight.js/lib/languages/scss';
-import markdown from 'highlight.js/lib/languages/markdown';
-import dockerfile from 'highlight.js/lib/languages/dockerfile';
-import nginx from 'highlight.js/lib/languages/nginx';
-import apache from 'highlight.js/lib/languages/apache';
-import perl from 'highlight.js/lib/languages/perl';
-import r from 'highlight.js/lib/languages/r';
-import swift from 'highlight.js/lib/languages/swift';
-import kotlin from 'highlight.js/lib/languages/kotlin';
-import scala from 'highlight.js/lib/languages/scala';
-import haskell from 'highlight.js/lib/languages/haskell';
-import lua from 'highlight.js/lib/languages/lua';
-import vim from 'highlight.js/lib/languages/vim';
-import diff from 'highlight.js/lib/languages/diff';
-import makefile from 'highlight.js/lib/languages/makefile';
-import ini from 'highlight.js/lib/languages/ini';
-import properties from 'highlight.js/lib/languages/properties';
-
-// Register all languages
-const languages: Record<string, LanguageFn> = {
-  javascript,
-  typescript,
-  python,
-  bash,
-  json,
-  go,
-  rust,
-  java,
-  cpp,
-  c,
-  csharp,
-  ruby,
-  php,
-  sql,
-  yaml,
-  xml,
-  html: xml,
-  css,
-  scss,
-  markdown,
-  dockerfile,
-  nginx,
-  apache,
-  perl,
-  r,
-  swift,
-  kotlin,
-  scala,
-  haskell,
-  lua,
-  vim,
-  diff,
-  makefile,
-  ini,
-  properties,
-};
-
-// Register languages
-for (const [name, lang] of Object.entries(languages)) {
-  hljs.registerLanguage(name, lang);
-}
-
-// Configure highlight.js
-hljs.configure({
-  classPrefix: 'hljs-',
-  ignoreUnescapedHTML: true,
-});
-
-// Language aliases
-const languageAliases: Record<string, string> = {
-  js: 'javascript',
-  ts: 'typescript',
-  py: 'python',
-  sh: 'bash',
-  yml: 'yaml',
-  md: 'markdown',
-};
-
-/**
- * Handle syntax highlighting task
- */
-export function handleHighlightTask(payload: unknown): HighlightTaskResult {
-  const { code, language } = payload as HighlightTaskPayload;
-
-  // Normalize language name
-  const normalizedLang = normalizeLanguage(language);
-
-  try {
-    // Check if language is available
-    if (hljs.getLanguage(normalizedLang)) {
-      const result = hljs.highlight(code, {
-        language: normalizedLang,
-        ignoreIllegals: true,
-      });
-
-      return {
-        html: result.value,
-        language: normalizedLang,
-      };
-    } else {
-      // Fallback: auto-detect
-      const result = hljs.highlightAuto(code);
-      return {
-        html: result.value,
-        language: result.language || 'plaintext',
-      };
-    }
-  } catch (error) {
-    console.error(`[HighlightTask] Error highlighting ${normalizedLang}:`, error);
-    // Return unformatted code
-    return {
-      html: escapeHtml(code),
-      language: 'plaintext',
-    };
-  }
-}
-
-/**
- * Normalize language name
- */
-function normalizeLanguage(language: string): string {
-  const lower = language.toLowerCase();
-  return languageAliases[lower] || lower;
-}
-
-/**
- * Escape HTML
- */
-function escapeHtml(text: string): string {
-  const div = document.createElement('div');
-  div.textContent = text;
-  return div.innerHTML;
-}
+export * from '../../../packages/core/src/workers/tasks/highlight-task';
diff --git a/src/workers/tasks/mermaid-task.ts b/src/workers/tasks/mermaid-task.ts
index 6038385..67f652a 100644
--- a/src/workers/tasks/mermaid-task.ts
+++ b/src/workers/tasks/mermaid-task.ts
@@ -1,97 +1 @@
-/**
- * Mermaid Task
- * Handles Mermaid diagram rendering in worker context
- */
-
-import mermaid from 'mermaid';
-import type { MermaidTaskPayload, MermaidTaskResult } from '../../types';
-
-// Initialize Mermaid
-mermaid.initialize({
-  startOnLoad: false,
-  securityLevel: 'strict',
-  maxTextSize: 50000,
-  maxEdges: 500,
-  theme: 'base',
-  flowchart: {
-    htmlLabels: false,
-    useMaxWidth: true,
-  },
-  sequence: {
-    useMaxWidth: true,
-  },
-  gantt: {
-    useMaxWidth: true,
-  },
-});
-
-/**
- * Handle Mermaid rendering task
- */
-export async function handleMermaidTask(payload: unknown): Promise<MermaidTaskResult> {
-  const { code, theme, id } = payload as MermaidTaskPayload;
-
-  try {
-    // Apply theme if provided
-    if (theme) {
-      mermaid.initialize({
-        theme: theme.theme,
-        themeVariables: theme.themeVariables,
-      });
-    }
-
-    // Validate syntax
-    const validation = await validateSyntax(code);
-    if (!validation.valid) {
-      throw new Error(validation.error || 'Invalid Mermaid syntax');
-    }
-
-    // Generate unique ID for SVG
-    const svgId = `mermaid-svg-${id}`;
-
-    // Render with timeout
-    const renderPromise = mermaid.render(svgId, code);
-    const timeoutPromise = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error('Render timeout')), 5000);
-    });
-
-    const result = await Promise.race([renderPromise, timeoutPromise]);
-
-    return {
-      svg: result.svg,
-      id,
-    };
-  } catch (error) {
-    console.error('[MermaidTask] Render error:', error);
-    throw error;
-  }
-}
-
-/**
- * Validate Mermaid syntax
- */
-async function validateSyntax(code: string): Promise<{ valid: boolean; error?: string }> {
-  try {
-    // Basic validation
-    if (!code.trim()) {
-      return { valid: false, error: 'Empty diagram code' };
-    }
-
-    // Check size limits
-    if (code.length > 50000) {
-      return { valid: false, error: 'Diagram code exceeds size limit (50,000 characters)' };
-    }
-
-    // Try to parse
-    await mermaid.parse(code);
-
-    return { valid: true };
-  } catch (error) {
-    return {
-      valid: false,
-      error: error instanceof Error ? error.message : 'Parse error',
-    };
-  }
-}
-
-
+export * from '../../../packages/core/src/workers/tasks/mermaid-task';
diff --git a/src/workers/tasks/parse-task.ts b/src/workers/tasks/parse-task.ts
index 7b892d5..670632c 100644
--- a/src/workers/tasks/parse-task.ts
+++ b/src/workers/tasks/parse-task.ts
@@ -1,220 +1 @@
-/**
- * Parse Task
- * Handles markdown parsing in worker context
- */
-
-import MarkdownIt from 'markdown-it';
-import markdownItAttrs from 'markdown-it-attrs';
-import markdownItAnchor from 'markdown-it-anchor';
-import markdownItTaskLists from 'markdown-it-task-lists';
-import * as emojiPlugin from 'markdown-it-emoji';
-import type {
-  ParseTaskPayload,
-  ParseTaskResult,
-  HeadingInfo,
-  CodeBlockInfo,
-  MermaidBlockInfo,
-  ImageInfo,
-  LinkInfo,
-} from '../../types';
-
-/**
- * Handle markdown parsing task
- */
-export function handleParseTask(payload: unknown): ParseTaskResult {
-  const { markdown, options } = payload as ParseTaskPayload;
-
-  // Metadata collection
-  const metadata = {
-    wordCount: 0,
-    headings: [] as HeadingInfo[],
-    codeBlocks: [] as CodeBlockInfo[],
-    mermaidBlocks: [] as MermaidBlockInfo[],
-    images: [] as ImageInfo[],
-    links: [] as LinkInfo[],
-    frontmatter: null as Record<string, string> | null,
-  };
-
-  // Initialize markdown-it
-  const md = new MarkdownIt({
-    html: options?.enableHtml ?? false, // Security: no raw HTML tags by default
-    breaks: options?.breaks ?? true,
-    linkify: options?.linkify ?? true,
-    typographer: options?.typographer ?? true,
-  });
-
-  // Configure plugins
-  md.use(markdownItAttrs, {
-    leftDelimiter: '{',
-    rightDelimiter: '}',
-    allowedAttributes: ['id', 'class', 'style'],
-  });
-
-  md.use(markdownItAnchor, {
-    permalink: markdownItAnchor.permalink.headerLink({
-      safariReaderFix: true,
-    }),
-    slugify: (s: string) =>
-      s
-        .toLowerCase()
-        .trim()
-        .replace(/[\s\W-]+/g, '-')
-        .replace(/^-+|-+$/g, ''),
-  });
-
-  md.use(markdownItTaskLists, {
-    enabled: true,
-    label: true,
-    labelAfter: true,
-  });
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unnecessary-type-assertion
-  const emojiPluginToUse = ((emojiPlugin as any).full || emojiPlugin) as any;
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-  md.use(emojiPluginToUse);
-
-  // Add custom fence renderer for code blocks and mermaid
-  const defaultFenceRenderer =
-    md.renderer.rules.fence ||
-    function (tokens, idx, opts, _env, self) {
-      return self.renderToken(tokens, idx, opts);
-    };
-
-  md.renderer.rules.fence = (tokens, idx, opts, env, self) => {
-    const token = tokens[idx];
-    const info = token.info ? token.info.trim() : '';
-    const langName = info.split(/\s+/g)[0];
-
-    // Handle Mermaid diagrams
-    if (langName === 'mermaid' || langName === 'mmd') {
-      const code = token.content.trim();
-      const id = `mermaid-${Math.random().toString(36).substr(2, 9)}`;
-
-      metadata.mermaidBlocks.push({
-        code,
-        line: token.map ? token.map[0] : 0,
-      });
-
-      // Return container with data attribute for code
-      return `<div class="mermaid-container" id="${id}" data-mermaid-code="${escapeHtml(code)}">
-        <div class="mermaid-loading">Rendering diagram...</div>
-      </div>\n`;
-    }
-
-    // Handle regular code blocks
-    if (langName) {
-      metadata.codeBlocks.push({
-        language: langName,
-        code: token.content,
-        line: token.map ? token.map[0] : 0,
-        lines: token.content.split('\n').length,
-      });
-    }
-
-    return defaultFenceRenderer(tokens, idx, opts, env, self);
-  };
-
-  // Add heading renderer for metadata
-  const defaultHeadingOpenRenderer =
-    md.renderer.rules.heading_open ||
-    function (tokens, idx, opts, _env, self) {
-      return self.renderToken(tokens, idx, opts);
-    };
-
-  md.renderer.rules.heading_open = (tokens, idx, opts, env, self) => {
-    const token = tokens[idx];
-    const level = parseInt(token.tag.substr(1));
-    const nextToken = tokens[idx + 1];
-    const text = nextToken && nextToken.type === 'inline' ? nextToken.content : '';
-
-    const id = text
-      .toLowerCase()
-      .trim()
-      .replace(/[\s\W-]+/g, '-')
-      .replace(/^-+|-+$/g, '');
-
-    metadata.headings.push({
-      level,
-      text,
-      id,
-      line: token.map ? token.map[0] : 0,
-    });
-
-    return defaultHeadingOpenRenderer(tokens, idx, opts, env, self);
-  };
-
-  // Add image renderer for metadata
-  const defaultImageRenderer =
-    md.renderer.rules.image ||
-    function (tokens, idx, opts, _env, self) {
-      return self.renderToken(tokens, idx, opts);
-    };
-
-  md.renderer.rules.image = (tokens, idx, opts, env, self) => {
-    const token = tokens[idx];
-    const srcIndex = token.attrIndex('src');
-    const attrs = token.attrs || [];
-    const src = srcIndex >= 0 ? attrs[srcIndex][1] : '';
-    const alt = token.content;
-    const titleIndex = token.attrIndex('title');
-    const title = titleIndex >= 0 ? attrs[titleIndex][1] : undefined;
-
-    metadata.images.push({
-      src,
-      alt,
-      title,
-      line: token.map ? token.map[0] : 0,
-    });
-
-    return defaultImageRenderer(tokens, idx, opts, env, self);
-  };
-
-  // Add link renderer for metadata
-  const defaultLinkOpenRenderer =
-    md.renderer.rules.link_open ||
-    function (tokens, idx, opts, _env, self) {
-      return self.renderToken(tokens, idx, opts);
-    };
-
-  md.renderer.rules.link_open = (tokens, idx, opts, env, self) => {
-    const token = tokens[idx];
-    const hrefIndex = token.attrIndex('href');
-    const attrs = token.attrs || [];
-    const href = hrefIndex >= 0 ? attrs[hrefIndex][1] : '';
-    const nextToken = tokens[idx + 1];
-    const text = nextToken && nextToken.type === 'inline' ? nextToken.content : '';
-
-    metadata.links.push({
-      href,
-      text,
-      line: token.map ? token.map[0] : 0,
-    });
-
-    return defaultLinkOpenRenderer(tokens, idx, opts, env, self);
-  };
-
-  // Calculate word count
-  metadata.wordCount = markdown.trim().split(/\s+/).length;
-
-  // Parse markdown
-  const html = md.render(markdown);
-
-  return {
-    html,
-    metadata,
-  };
-}
-
-/**
- * Escape HTML for safe attribute values
- */
-function escapeHtml(text: string): string {
-  const map: { [key: string]: string } = {
-    '&': '&amp;',
-    '<': '&lt;',
-    '>': '&gt;',
-    '"': '&quot;',
-    "'": '&#039;',
-  };
-  return text.replace(/[&<>"']/g, (m) => map[m]);
-}
+export * from '../../../packages/core/src/workers/tasks/parse-task';
diff --git a/src/workers/worker-pool.ts b/src/workers/worker-pool.ts
index d27686c..ba0edf6 100644
--- a/src/workers/worker-pool.ts
+++ b/src/workers/worker-pool.ts
@@ -1,299 +1 @@
-/**
- * Worker Pool Manager
- * Manages a pool of web workers for parallel processing
- */
-
-import type { WorkerTask, WorkerResponse } from '../types';
-import { debug } from '../utils/debug-logger';
-
-export interface WorkerPoolOptions {
-  poolSize?: number; // Number of workers (default: navigator.hardwareConcurrency or 4)
-  maxQueueSize?: number; // Max queued tasks (default: 100)
-  workerScript?: string; // Path to worker script
-}
-
-interface PendingTask {
-  task: WorkerTask;
-  resolve: (value: unknown) => void;
-  reject: (reason: Error) => void;
-  priority: number;
-}
-
-export class WorkerPool {
-  private workers: Worker[] = [];
-  private taskQueue: PendingTask[] = [];
-  private activeTasksPerWorker: Map<Worker, number> = new Map();
-  private taskCallbacks: Map<string, PendingTask> = new Map();
-  private poolSize: number;
-  private maxQueueSize: number;
-  private initialized = false;
-
-  constructor(options: WorkerPoolOptions = {}) {
-    this.poolSize = options.poolSize || navigator.hardwareConcurrency || 4;
-    this.maxQueueSize = options.maxQueueSize || 100;
-
-    debug.debug('WorkerPool', `Creating pool with ${this.poolSize} workers`);
-  }
-
-  /**
-   * Initialize worker pool
-   * Note: Workers don't work on file:// URLs due to Chrome security restrictions
-   * The synchronous fallback is well-optimized with Phase 1 performance improvements
-   */
-  async initialize(): Promise<void> {
-    if (this.initialized) {
-      return;
-    }
-
-    // Check if we're on a file:// URL - workers don't work there
-    if (window.location.protocol === 'file:') {
-      debug.info(
-        'WorkerPool',
-        'Workers unavailable on file:// URLs (Chrome restriction), using synchronous rendering'
-      );
-      throw new Error('Workers not available on file:// URLs');
-    }
-
-    try {
-      // Import worker module (works on http:// and https:// URLs)
-      const RenderWorker = await import('./render-worker?worker');
-
-      debug.debug('WorkerPool', `Creating pool with ${this.poolSize} workers`);
-
-      for (let i = 0; i < this.poolSize; i++) {
-        const worker = new RenderWorker.default();
-
-        worker.addEventListener('message', this.handleWorkerMessage.bind(this));
-        worker.addEventListener('error', this.handleWorkerError.bind(this));
-
-        this.workers.push(worker);
-        this.activeTasksPerWorker.set(worker, 0);
-
-        debug.debug('WorkerPool', `Worker ${i + 1}/${this.poolSize} initialized`);
-      }
-
-      this.initialized = true;
-      debug.info('WorkerPool', '✅ Worker pool ready!');
-    } catch (error) {
-      debug.error('WorkerPool', 'Failed to initialize worker pool:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * Execute a task in the worker pool
-   */
-  async execute<T = unknown>(task: WorkerTask): Promise<T> {
-    if (!this.initialized) {
-      await this.initialize();
-    }
-
-    return new Promise<T>((resolve, reject) => {
-      // Check queue size limit
-      if (this.taskQueue.length >= this.maxQueueSize) {
-        reject(new Error('Worker pool task queue is full'));
-        return;
-      }
-
-      const priority = task.priority || 0;
-      const pendingTask: PendingTask = {
-        task,
-        resolve: resolve as (value: unknown) => void,
-        reject,
-        priority,
-      };
-
-      // Try to execute immediately if a worker is available
-      const worker = this.getAvailableWorker();
-      if (worker) {
-        this.executeTask(worker, pendingTask);
-      } else {
-        // Queue the task
-        this.enqueueTask(pendingTask);
-      }
-    });
-  }
-
-  /**
-   * Handle worker message
-   */
-  private handleWorkerMessage(event: MessageEvent): void {
-    const response = event.data as WorkerResponse;
-
-    const pendingTask = this.taskCallbacks.get(response.id);
-    if (!pendingTask) {
-      debug.error('WorkerPool', 'Received response for unknown task:', response.id);
-      return;
-    }
-
-    // Remove from callbacks
-    this.taskCallbacks.delete(response.id);
-
-    // Decrease active task count for this worker
-    const worker = event.target as Worker;
-    const currentCount = this.activeTasksPerWorker.get(worker) || 0;
-    this.activeTasksPerWorker.set(worker, Math.max(0, currentCount - 1));
-
-    // Resolve or reject the task
-    if (response.error) {
-      debug.error('WorkerPool', `Task ${response.id} failed:`, response.error);
-      pendingTask.reject(new Error(response.error));
-    } else {
-      debug.debug('WorkerPool', `Task ${response.id} completed`);
-      pendingTask.resolve(response.result);
-    }
-
-    // Process next queued task if available
-    this.processQueue();
-  }
-
-  /**
-   * Handle worker error
-   */
-  private handleWorkerError(event: ErrorEvent): void {
-    debug.error('WorkerPool', 'Worker error:', event.message);
-
-    // Find and reject any tasks assigned to this worker
-    // Note: We don't currently track which worker has which task
-    // In a production system, you'd want to track this more carefully and reject only affected tasks
-  }
-
-  /**
-   * Get an available worker (least loaded)
-   */
-  private getAvailableWorker(): Worker | null {
-    if (this.workers.length === 0) {
-      return null;
-    }
-
-    // Find worker with fewest active tasks
-    let minTasks = Infinity;
-    let selectedWorker: Worker | null = null;
-
-    for (const worker of this.workers) {
-      const activeTasks = this.activeTasksPerWorker.get(worker) || 0;
-      if (activeTasks < minTasks) {
-        minTasks = activeTasks;
-        selectedWorker = worker;
-      }
-    }
-
-    // Return worker if it's not overloaded (max 3 tasks per worker)
-    if (selectedWorker && minTasks < 3) {
-      return selectedWorker;
-    }
-
-    return null;
-  }
-
-  /**
-   * Execute a task on a specific worker
-   */
-  private executeTask(worker: Worker, pendingTask: PendingTask): void {
-    // Increment active task count
-    const currentCount = this.activeTasksPerWorker.get(worker) || 0;
-    this.activeTasksPerWorker.set(worker, currentCount + 1);
-
-    // Store callback
-    this.taskCallbacks.set(pendingTask.task.id, pendingTask);
-
-    // Send task to worker
-    worker.postMessage(pendingTask.task);
-
-    debug.debug(
-      'WorkerPool',
-      `Dispatched task ${pendingTask.task.id} (type: ${pendingTask.task.type})`
-    );
-  }
-
-  /**
-   * Enqueue a task
-   */
-  private enqueueTask(pendingTask: PendingTask): void {
-    // Insert task in priority order (higher priority first)
-    let insertIndex = this.taskQueue.length;
-    for (let i = 0; i < this.taskQueue.length; i++) {
-      if (pendingTask.priority > this.taskQueue[i].priority) {
-        insertIndex = i;
-        break;
-      }
-    }
-
-    this.taskQueue.splice(insertIndex, 0, pendingTask);
-    debug.debug(
-      'WorkerPool',
-      `Queued task ${pendingTask.task.id}, queue size: ${this.taskQueue.length}`
-    );
-  }
-
-  /**
-   * Process queued tasks
-   */
-  private processQueue(): void {
-    while (this.taskQueue.length > 0) {
-      const worker = this.getAvailableWorker();
-      if (!worker) {
-        break;
-      }
-
-      const pendingTask = this.taskQueue.shift();
-      if (pendingTask) {
-        this.executeTask(worker, pendingTask);
-      }
-    }
-  }
-
-  /**
-   * Get pool statistics
-   */
-  getStats(): {
-    poolSize: number;
-    activeWorkers: number;
-    queuedTasks: number;
-    activeTasks: number;
-  } {
-    let activeTasks = 0;
-    for (const count of this.activeTasksPerWorker.values()) {
-      activeTasks += count;
-    }
-
-    return {
-      poolSize: this.workers.length,
-      activeWorkers: this.workers.filter((w) => (this.activeTasksPerWorker.get(w) || 0) > 0).length,
-      queuedTasks: this.taskQueue.length,
-      activeTasks,
-    };
-  }
-
-  /**
-   * Terminate all workers
-   */
-  terminate(): void {
-    debug.info('WorkerPool', 'Terminating worker pool');
-
-    // Reject all pending tasks
-    for (const pendingTask of this.taskCallbacks.values()) {
-      pendingTask.reject(new Error('Worker pool terminated'));
-    }
-    this.taskCallbacks.clear();
-
-    // Reject all queued tasks
-    for (const pendingTask of this.taskQueue) {
-      pendingTask.reject(new Error('Worker pool terminated'));
-    }
-    this.taskQueue = [];
-
-    // Terminate workers
-    for (const worker of this.workers) {
-      worker.terminate();
-    }
-    this.workers = [];
-    this.activeTasksPerWorker.clear();
-    this.initialized = false;
-
-    debug.info('WorkerPool', 'Worker pool terminated');
-  }
-}
-
-// Export singleton
-export const workerPool = new WorkerPool();
+export * from '../../packages/core/src/workers/worker-pool';

From f3b48c63005ea62b8d3485d9a020afd9a569200f Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 09:13:17 -0400
Subject: [PATCH 22/26] refactor(core): move renderers to @mdview/core

---
 package-lock.json                             | 139 +--
 package.json                                  |   5 +-
 .../core/src/renderers/mermaid-renderer.ts    | 903 ++++++++++++++++++
 .../core/src/renderers/syntax-highlighter.ts  | 358 +++++++
 src/renderers/mermaid-renderer.ts             | 902 +----------------
 src/renderers/syntax-highlighter.ts           | 357 +------
 6 files changed, 1272 insertions(+), 1392 deletions(-)
 create mode 100644 packages/core/src/renderers/mermaid-renderer.ts
 create mode 100644 packages/core/src/renderers/syntax-highlighter.ts

diff --git a/package-lock.json b/package-lock.json
index 4d77690..0cc848d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14,13 +14,11 @@
       "dependencies": {
         "@jamesainslie/docx": "^9.5.1-svg.1",
         "dompurify": "^3.0.6",
-        "highlight.js": "^11.9.0",
         "markdown-it-anchor": "^8.6.7",
         "markdown-it-attrs": "^4.1.6",
         "markdown-it-emoji": "^3.0.0",
         "markdown-it-footnote": "^4.0.0",
-        "markdown-it-task-lists": "^2.1.1",
-        "panzoom": "^9.4.3"
+        "markdown-it-task-lists": "^2.1.1"
       },
       "devDependencies": {
         "@crxjs/vite-plugin": "^2.0.0",
@@ -37,7 +35,6 @@
         "jsdom": "^27.2.0",
         "lint-staged": "^16.2.7",
         "markdown-it": "^14.1.0",
-        "mermaid": "^11.12.1",
         "playwright": "^1.48.0",
         "prettier": "^3.1.0",
         "sharp": "^0.34.5",
@@ -71,7 +68,6 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@antfu/install-pkg/-/install-pkg-1.1.0.tgz",
       "integrity": "sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "package-manager-detector": "^1.3.0",
@@ -167,14 +163,12 @@
       "version": "7.1.1",
       "resolved": "https://registry.npmjs.org/@braintree/sanitize-url/-/sanitize-url-7.1.1.tgz",
       "integrity": "sha512-i1L7noDNxtFyL5DmZafWy1wRVhGehQmzZaz1HiN5e7iylJMSZR7ekOV7NsIqa5qBldlLrsKv4HbgFUVlQrz8Mw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@chevrotain/cst-dts-gen": {
       "version": "11.0.3",
       "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-11.0.3.tgz",
       "integrity": "sha512-BvIKpRLeS/8UbfxXxgC33xOumsacaeCKAjAeLyOn7Pcp95HiRbrpl14S+9vaZLolnbssPIUuiUd8IvgkRyt6NQ==",
-      "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
         "@chevrotain/gast": "11.0.3",
@@ -186,7 +180,6 @@
       "version": "11.0.3",
       "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-11.0.3.tgz",
       "integrity": "sha512-+qNfcoNk70PyS/uxmj3li5NiECO+2YKZZQMbmjTqRI3Qchu8Hig/Q9vgkHpI3alNjr7M+a2St5pw5w5F6NL5/Q==",
-      "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
         "@chevrotain/types": "11.0.3",
@@ -197,21 +190,18 @@
       "version": "11.0.3",
       "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-11.0.3.tgz",
       "integrity": "sha512-1fMHaBZxLFvWI067AVbGJav1eRY7N8DDvYCTwGBiE/ytKBgP8azTdgyrKyWZ9Mfh09eHWb5PgTSO8wi7U824RA==",
-      "dev": true,
       "license": "Apache-2.0"
     },
     "node_modules/@chevrotain/types": {
       "version": "11.0.3",
       "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.0.3.tgz",
       "integrity": "sha512-gsiM3G8b58kZC2HaWR50gu6Y1440cHiJ+i3JUvcp/35JchYejb2+5MVeJK0iKThYpAa/P2PYFV4hoi44HD+aHQ==",
-      "dev": true,
       "license": "Apache-2.0"
     },
     "node_modules/@chevrotain/utils": {
       "version": "11.0.3",
       "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-11.0.3.tgz",
       "integrity": "sha512-YslZMgtJUyuMbZ+aKvfF3x1f5liK4mWNxghFRv7jqRR9C3R3fAOGTTKvxXDa2Y1s9zSbcpuO0cAxDYsc9SrXoQ==",
-      "dev": true,
       "license": "Apache-2.0"
     },
     "node_modules/@crxjs/vite-plugin": {
@@ -1088,14 +1078,12 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/@iconify/types/-/types-2.0.0.tgz",
       "integrity": "sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@iconify/utils": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/@iconify/utils/-/utils-3.1.0.tgz",
       "integrity": "sha512-Zlzem1ZXhI1iHeeERabLNzBHdOa4VhQbqAcOQaMKuTuyZCpwKbC2R4Dd0Zo3g9EAc+Y4fiarO8HIHRAth7+skw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@antfu/install-pkg": "^1.1.0",
@@ -1749,7 +1737,6 @@
       "version": "0.6.3",
       "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-0.6.3.tgz",
       "integrity": "sha512-lnjOhe7zyHjc+If7yT4zoedx2vo4sHaTmtkl1+or8BRTnCtDmcTpAjpzDSfCZrshM5bCoz0GyidzadJAH1xobA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "langium": "3.3.1"
@@ -2323,7 +2310,6 @@
       "version": "7.4.3",
       "resolved": "https://registry.npmjs.org/@types/d3/-/d3-7.4.3.tgz",
       "integrity": "sha512-lZXZ9ckh5R8uiFVt8ogUNf+pIrK4EsWrx2Np75WvF/eTpJ0FMHNhjXk8CKEx/+gpHbNQyJWehbFaTvqmHWB3ww==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-array": "*",
@@ -2362,14 +2348,12 @@
       "version": "3.2.2",
       "resolved": "https://registry.npmjs.org/@types/d3-array/-/d3-array-3.2.2.tgz",
       "integrity": "sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-axis": {
       "version": "3.0.6",
       "resolved": "https://registry.npmjs.org/@types/d3-axis/-/d3-axis-3.0.6.tgz",
       "integrity": "sha512-pYeijfZuBd87T0hGn0FO1vQ/cgLk6E1ALJjfkC0oJ8cbwkZl3TpgS8bVBLZN+2jjGgg38epgxb2zmoGtSfvgMw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-selection": "*"
@@ -2379,7 +2363,6 @@
       "version": "3.0.6",
       "resolved": "https://registry.npmjs.org/@types/d3-brush/-/d3-brush-3.0.6.tgz",
       "integrity": "sha512-nH60IZNNxEcrh6L1ZSMNA28rj27ut/2ZmI3r96Zd+1jrZD++zD3LsMIjWlvg4AYrHn/Pqz4CF3veCxGjtbqt7A==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-selection": "*"
@@ -2389,21 +2372,18 @@
       "version": "3.0.6",
       "resolved": "https://registry.npmjs.org/@types/d3-chord/-/d3-chord-3.0.6.tgz",
       "integrity": "sha512-LFYWWd8nwfwEmTZG9PfQxd17HbNPksHBiJHaKuY1XeqscXacsS2tyoo6OdRsjf+NQYeB6XrNL3a25E3gH69lcg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-color": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz",
       "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-contour": {
       "version": "3.0.6",
       "resolved": "https://registry.npmjs.org/@types/d3-contour/-/d3-contour-3.0.6.tgz",
       "integrity": "sha512-BjzLgXGnCWjUSYGfH1cpdo41/hgdWETu4YxpezoztawmqsvCeep+8QGfiY6YbDvfgHz/DkjeIkkZVJavB4a3rg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-array": "*",
@@ -2414,21 +2394,18 @@
       "version": "6.0.4",
       "resolved": "https://registry.npmjs.org/@types/d3-delaunay/-/d3-delaunay-6.0.4.tgz",
       "integrity": "sha512-ZMaSKu4THYCU6sV64Lhg6qjf1orxBthaC161plr5KuPHo3CNm8DTHiLw/5Eq2b6TsNP0W0iJrUOFscY6Q450Hw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-dispatch": {
       "version": "3.0.7",
       "resolved": "https://registry.npmjs.org/@types/d3-dispatch/-/d3-dispatch-3.0.7.tgz",
       "integrity": "sha512-5o9OIAdKkhN1QItV2oqaE5KMIiXAvDWBDPrD85e58Qlz1c1kI/J0NcqbEG88CoTwJrYe7ntUCVfeUl2UJKbWgA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-drag": {
       "version": "3.0.7",
       "resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz",
       "integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-selection": "*"
@@ -2438,21 +2415,18 @@
       "version": "3.0.7",
       "resolved": "https://registry.npmjs.org/@types/d3-dsv/-/d3-dsv-3.0.7.tgz",
       "integrity": "sha512-n6QBF9/+XASqcKK6waudgL0pf/S5XHPPI8APyMLLUHd8NqouBGLsU8MgtO7NINGtPBtk9Kko/W4ea0oAspwh9g==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-ease": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz",
       "integrity": "sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-fetch": {
       "version": "3.0.7",
       "resolved": "https://registry.npmjs.org/@types/d3-fetch/-/d3-fetch-3.0.7.tgz",
       "integrity": "sha512-fTAfNmxSb9SOWNB9IoG5c8Hg6R+AzUHDRlsXsDZsNp6sxAEOP0tkP3gKkNSO/qmHPoBFTxNrjDprVHDQDvo5aA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-dsv": "*"
@@ -2462,21 +2436,18 @@
       "version": "3.0.10",
       "resolved": "https://registry.npmjs.org/@types/d3-force/-/d3-force-3.0.10.tgz",
       "integrity": "sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-format": {
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/@types/d3-format/-/d3-format-3.0.4.tgz",
       "integrity": "sha512-fALi2aI6shfg7vM5KiR1wNJnZ7r6UuggVqtDA+xiEdPZQwy/trcQaHnwShLuLdta2rTymCNpxYTiMZX/e09F4g==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-geo": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/@types/d3-geo/-/d3-geo-3.1.0.tgz",
       "integrity": "sha512-856sckF0oP/diXtS4jNsiQw/UuK5fQG8l/a9VVLeSouf1/PPbBE1i1W852zVwKwYCBkFJJB7nCFTbk6UMEXBOQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/geojson": "*"
@@ -2486,14 +2457,12 @@
       "version": "3.1.7",
       "resolved": "https://registry.npmjs.org/@types/d3-hierarchy/-/d3-hierarchy-3.1.7.tgz",
       "integrity": "sha512-tJFtNoYBtRtkNysX1Xq4sxtjK8YgoWUNpIiUee0/jHGRwqvzYxkq0hGVbbOGSz+JgFxxRu4K8nb3YpG3CMARtg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-interpolate": {
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz",
       "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-color": "*"
@@ -2503,35 +2472,30 @@
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/@types/d3-path/-/d3-path-3.1.1.tgz",
       "integrity": "sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-polygon": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/@types/d3-polygon/-/d3-polygon-3.0.2.tgz",
       "integrity": "sha512-ZuWOtMaHCkN9xoeEMr1ubW2nGWsp4nIql+OPQRstu4ypeZ+zk3YKqQT0CXVe/PYqrKpZAi+J9mTs05TKwjXSRA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-quadtree": {
       "version": "3.0.6",
       "resolved": "https://registry.npmjs.org/@types/d3-quadtree/-/d3-quadtree-3.0.6.tgz",
       "integrity": "sha512-oUzyO1/Zm6rsxKRHA1vH0NEDG58HrT5icx/azi9MF1TWdtttWl0UIUsjEQBBh+SIkrpd21ZjEv7ptxWys1ncsg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-random": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/@types/d3-random/-/d3-random-3.0.3.tgz",
       "integrity": "sha512-Imagg1vJ3y76Y2ea0871wpabqp613+8/r0mCLEBfdtqC7xMSfj9idOnmBYyMoULfHePJyxMAw3nWhJxzc+LFwQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-scale": {
       "version": "4.0.9",
       "resolved": "https://registry.npmjs.org/@types/d3-scale/-/d3-scale-4.0.9.tgz",
       "integrity": "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-time": "*"
@@ -2541,21 +2505,18 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/@types/d3-scale-chromatic/-/d3-scale-chromatic-3.1.0.tgz",
       "integrity": "sha512-iWMJgwkK7yTRmWqRB5plb1kadXyQ5Sj8V/zYlFGMUBbIPKQScw+Dku9cAAMgJG+z5GYDoMjWGLVOvjghDEFnKQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-selection": {
       "version": "3.0.11",
       "resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.11.tgz",
       "integrity": "sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-shape": {
       "version": "3.1.7",
       "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.7.tgz",
       "integrity": "sha512-VLvUQ33C+3J+8p+Daf+nYSOsjB4GXp19/S/aGo60m9h1v6XaxjiT82lKVWJCfzhtuZ3yD7i/TPeC/fuKLLOSmg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-path": "*"
@@ -2565,28 +2526,24 @@
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-3.0.4.tgz",
       "integrity": "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-time-format": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/@types/d3-time-format/-/d3-time-format-4.0.3.tgz",
       "integrity": "sha512-5xg9rC+wWL8kdDj153qZcsJ0FWiFt0J5RB6LYUNZjwSnesfblqrI/bJ1wBdJ8OQfncgbJG5+2F+qfqnqyzYxyg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-timer": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/@types/d3-timer/-/d3-timer-3.0.2.tgz",
       "integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/d3-transition": {
       "version": "3.0.9",
       "resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz",
       "integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-selection": "*"
@@ -2596,7 +2553,6 @@
       "version": "3.0.8",
       "resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.8.tgz",
       "integrity": "sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/d3-interpolate": "*",
@@ -2648,7 +2604,6 @@
       "version": "7946.0.16",
       "resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.16.tgz",
       "integrity": "sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/har-format": {
@@ -3156,7 +3111,6 @@
       "version": "8.15.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
-      "dev": true,
       "license": "MIT",
       "bin": {
         "acorn": "bin/acorn"
@@ -3703,7 +3657,6 @@
       "version": "11.0.3",
       "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.0.3.tgz",
       "integrity": "sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==",
-      "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
         "@chevrotain/cst-dts-gen": "11.0.3",
@@ -3718,7 +3671,6 @@
       "version": "0.3.1",
       "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.3.1.tgz",
       "integrity": "sha512-b7g+y9A0v4mxCW1qUhf3BSVPg+/NvGErk/dOkrDaHA0nQIQGAtrOjlX//9OQtRlSCy+x9rfB5N8yC71lH1nvMw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "lodash-es": "^4.17.21"
@@ -3952,7 +3904,6 @@
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz",
       "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 10"
@@ -3969,7 +3920,6 @@
       "version": "0.1.8",
       "resolved": "https://registry.npmjs.org/confbox/-/confbox-0.1.8.tgz",
       "integrity": "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/convert-source-map": {
@@ -3989,7 +3939,6 @@
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-1.0.3.tgz",
       "integrity": "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "layout-base": "^1.0.0"
@@ -4114,7 +4063,6 @@
       "version": "3.33.1",
       "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.33.1.tgz",
       "integrity": "sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.10"
@@ -4124,7 +4072,6 @@
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/cytoscape-cose-bilkent/-/cytoscape-cose-bilkent-4.1.0.tgz",
       "integrity": "sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "cose-base": "^1.0.0"
@@ -4137,7 +4084,6 @@
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/cytoscape-fcose/-/cytoscape-fcose-2.2.0.tgz",
       "integrity": "sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "cose-base": "^2.2.0"
@@ -4150,7 +4096,6 @@
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-2.2.0.tgz",
       "integrity": "sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "layout-base": "^2.0.0"
@@ -4160,14 +4105,12 @@
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-2.0.1.tgz",
       "integrity": "sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/d3": {
       "version": "7.9.0",
       "resolved": "https://registry.npmjs.org/d3/-/d3-7.9.0.tgz",
       "integrity": "sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-array": "3",
@@ -4209,7 +4152,6 @@
       "version": "3.2.4",
       "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-3.2.4.tgz",
       "integrity": "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "internmap": "1 - 2"
@@ -4222,7 +4164,6 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-axis/-/d3-axis-3.0.0.tgz",
       "integrity": "sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4232,7 +4173,6 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-brush/-/d3-brush-3.0.0.tgz",
       "integrity": "sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-dispatch": "1 - 3",
@@ -4249,7 +4189,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-chord/-/d3-chord-3.0.1.tgz",
       "integrity": "sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-path": "1 - 3"
@@ -4262,7 +4201,6 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz",
       "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4272,7 +4210,6 @@
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/d3-contour/-/d3-contour-4.0.2.tgz",
       "integrity": "sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-array": "^3.2.0"
@@ -4285,7 +4222,6 @@
       "version": "6.0.4",
       "resolved": "https://registry.npmjs.org/d3-delaunay/-/d3-delaunay-6.0.4.tgz",
       "integrity": "sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "delaunator": "5"
@@ -4298,7 +4234,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
       "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4308,7 +4243,6 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz",
       "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-dispatch": "1 - 3",
@@ -4322,7 +4256,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-dsv/-/d3-dsv-3.0.1.tgz",
       "integrity": "sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "commander": "7",
@@ -4348,7 +4281,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
       "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==",
-      "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">=12"
@@ -4358,7 +4290,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-fetch/-/d3-fetch-3.0.1.tgz",
       "integrity": "sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-dsv": "1 - 3"
@@ -4371,7 +4302,6 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-force/-/d3-force-3.0.0.tgz",
       "integrity": "sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-dispatch": "1 - 3",
@@ -4386,7 +4316,6 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-3.1.0.tgz",
       "integrity": "sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4396,7 +4325,6 @@
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/d3-geo/-/d3-geo-3.1.1.tgz",
       "integrity": "sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-array": "2.5.0 - 3"
@@ -4409,7 +4337,6 @@
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/d3-hierarchy/-/d3-hierarchy-3.1.2.tgz",
       "integrity": "sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4419,7 +4346,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz",
       "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-color": "1 - 3"
@@ -4432,7 +4358,6 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz",
       "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4442,7 +4367,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-polygon/-/d3-polygon-3.0.1.tgz",
       "integrity": "sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4452,7 +4376,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-quadtree/-/d3-quadtree-3.0.1.tgz",
       "integrity": "sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4462,7 +4385,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-random/-/d3-random-3.0.1.tgz",
       "integrity": "sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4472,7 +4394,6 @@
       "version": "0.12.3",
       "resolved": "https://registry.npmjs.org/d3-sankey/-/d3-sankey-0.12.3.tgz",
       "integrity": "sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ==",
-      "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "d3-array": "1 - 2",
@@ -4483,7 +4404,6 @@
       "version": "2.12.1",
       "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-2.12.1.tgz",
       "integrity": "sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==",
-      "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "internmap": "^1.0.0"
@@ -4493,14 +4413,12 @@
       "version": "1.0.9",
       "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-1.0.9.tgz",
       "integrity": "sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==",
-      "dev": true,
       "license": "BSD-3-Clause"
     },
     "node_modules/d3-sankey/node_modules/d3-shape": {
       "version": "1.3.7",
       "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-1.3.7.tgz",
       "integrity": "sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==",
-      "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "d3-path": "1"
@@ -4510,14 +4428,12 @@
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/internmap/-/internmap-1.0.1.tgz",
       "integrity": "sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==",
-      "dev": true,
       "license": "ISC"
     },
     "node_modules/d3-scale": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz",
       "integrity": "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-array": "2.10.0 - 3",
@@ -4534,7 +4450,6 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/d3-scale-chromatic/-/d3-scale-chromatic-3.1.0.tgz",
       "integrity": "sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-color": "1 - 3",
@@ -4548,7 +4463,6 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
       "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4558,7 +4472,6 @@
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz",
       "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-path": "^3.1.0"
@@ -4571,7 +4484,6 @@
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz",
       "integrity": "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-array": "2 - 3"
@@ -4584,7 +4496,6 @@
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/d3-time-format/-/d3-time-format-4.1.0.tgz",
       "integrity": "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-time": "1 - 3"
@@ -4597,7 +4508,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
       "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -4607,7 +4517,6 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz",
       "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-color": "1 - 3",
@@ -4627,7 +4536,6 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz",
       "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "d3-dispatch": "1 - 3",
@@ -4644,7 +4552,6 @@
       "version": "7.0.13",
       "resolved": "https://registry.npmjs.org/dagre-d3-es/-/dagre-d3-es-7.0.13.tgz",
       "integrity": "sha512-efEhnxpSuwpYOKRm/L5KbqoZmNNukHa/Flty4Wp62JRvgH2ojwVgPgdYyr4twpieZnyRDdIH7PY2mopX26+j2Q==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "d3": "^7.9.0",
@@ -4680,7 +4587,6 @@
       "version": "1.11.19",
       "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.19.tgz",
       "integrity": "sha512-t5EcLVS6QPBNqM2z8fakk/NKel+Xzshgt8FFKAn+qwlD1pzZWxh0nVCrvFK7ZDb6XucZeF9z8C7CBWTRIVApAw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/debug": {
@@ -4735,7 +4641,6 @@
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/delaunator/-/delaunator-5.0.1.tgz",
       "integrity": "sha512-8nvh+XBe96aCESrGOqMp/84b13H9cdKbG5P2ejQCh4d4sK9RL4371qou9drQjMhvnPmhWl5hnmqbEE0fXr9Xnw==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "robust-predicates": "^3.0.2"
@@ -5747,7 +5652,6 @@
       "version": "0.5.2",
       "resolved": "https://registry.npmjs.org/hachure-fill/-/hachure-fill-0.5.2.tgz",
       "integrity": "sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/has-flag": {
@@ -5893,7 +5797,6 @@
       "version": "0.6.3",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
       "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "safer-buffer": ">= 2.1.2 < 3.0.0"
@@ -6010,7 +5913,6 @@
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/internmap/-/internmap-2.0.3.tgz",
       "integrity": "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==",
-      "dev": true,
       "license": "ISC",
       "engines": {
         "node": ">=12"
@@ -6336,7 +6238,6 @@
       "version": "0.16.25",
       "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.25.tgz",
       "integrity": "sha512-woHRUZ/iF23GBP1dkDQMh1QBad9dmr8/PAwNA54VrSOVYgI12MAcE14TqnDdQOdzyEonGzMepYnqBMYdsoAr8Q==",
-      "dev": true,
       "funding": [
         "https://opencollective.com/katex",
         "https://github.com/sponsors/katex"
@@ -6353,7 +6254,6 @@
       "version": "8.3.0",
       "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
       "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 12"
@@ -6372,14 +6272,12 @@
     "node_modules/khroma": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/khroma/-/khroma-2.1.0.tgz",
-      "integrity": "sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw==",
-      "dev": true
+      "integrity": "sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw=="
     },
     "node_modules/langium": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/langium/-/langium-3.3.1.tgz",
       "integrity": "sha512-QJv/h939gDpvT+9SiLVlY7tZC3xB2qK57v0J04Sh9wpMb6MP1q8gB21L3WIo8T5P1MSMg3Ep14L7KkDCFG3y4w==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "chevrotain": "~11.0.3",
@@ -6396,7 +6294,6 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-1.0.2.tgz",
       "integrity": "sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/levn": {
@@ -6616,7 +6513,6 @@
       "version": "4.17.21",
       "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz",
       "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/lodash.merge": {
@@ -6813,7 +6709,6 @@
       "version": "16.4.2",
       "resolved": "https://registry.npmjs.org/marked/-/marked-16.4.2.tgz",
       "integrity": "sha512-TI3V8YYWvkVf3KJe1dRkpnjs68JUPyEa5vjKrp1XEEJUAOaQc+Qj+L1qWbPd0SJuAdQkFU0h73sXXqwDYxsiDA==",
-      "dev": true,
       "license": "MIT",
       "bin": {
         "marked": "bin/marked.js"
@@ -6849,7 +6744,6 @@
       "version": "11.12.1",
       "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.12.1.tgz",
       "integrity": "sha512-UlIZrRariB11TY1RtTgUWp65tphtBv4CSq7vyS2ZZ2TgoMjs2nloq+wFqxiwcxlhHUvs7DPGgMjs2aeQxz5h9g==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@braintree/sanitize-url": "^7.1.1",
@@ -6935,7 +6829,6 @@
       "version": "1.8.0",
       "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.0.tgz",
       "integrity": "sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "acorn": "^8.15.0",
@@ -7183,7 +7076,6 @@
       "version": "1.6.0",
       "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.6.0.tgz",
       "integrity": "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/pako": {
@@ -7293,7 +7185,6 @@
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/path-data-parser/-/path-data-parser-0.1.0.tgz",
       "integrity": "sha512-NOnmBpt5Y2RWbuv0LMzsayp3lVylAHLPUTut412ZA3l+C4uw4ZVkQbjShYCQ8TCpUMdPapr4YjUqLYD6v68j+w==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/path-exists": {
@@ -7347,7 +7238,6 @@
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
       "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/pend": {
@@ -7529,7 +7419,6 @@
       "version": "1.3.1",
       "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.3.1.tgz",
       "integrity": "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "confbox": "^0.1.8",
@@ -7573,14 +7462,12 @@
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/points-on-curve/-/points-on-curve-0.2.0.tgz",
       "integrity": "sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/points-on-path": {
       "version": "0.2.1",
       "resolved": "https://registry.npmjs.org/points-on-path/-/points-on-path-0.2.1.tgz",
       "integrity": "sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "path-data-parser": "0.1.0",
@@ -8177,7 +8064,6 @@
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/robust-predicates/-/robust-predicates-3.0.2.tgz",
       "integrity": "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==",
-      "dev": true,
       "license": "Unlicense"
     },
     "node_modules/rollup": {
@@ -8200,7 +8086,6 @@
       "version": "4.6.6",
       "resolved": "https://registry.npmjs.org/roughjs/-/roughjs-4.6.6.tgz",
       "integrity": "sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "hachure-fill": "^0.5.2",
@@ -8237,7 +8122,6 @@
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz",
       "integrity": "sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==",
-      "dev": true,
       "license": "BSD-3-Clause"
     },
     "node_modules/rxjs": {
@@ -8270,7 +8154,6 @@
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/sax": {
@@ -8640,7 +8523,6 @@
       "version": "4.3.6",
       "resolved": "https://registry.npmjs.org/stylis/-/stylis-4.3.6.tgz",
       "integrity": "sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/sucrase": {
@@ -8864,7 +8746,6 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.2.tgz",
       "integrity": "sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18"
@@ -9004,7 +8885,6 @@
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/ts-dedent/-/ts-dedent-2.2.0.tgz",
       "integrity": "sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=6.10"
@@ -9550,7 +9430,6 @@
       "version": "1.6.1",
       "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.1.tgz",
       "integrity": "sha512-9a4/uxlTWJ4+a5i0ooc1rU7C7YOw3wT+UGqdeNNHWnOF9qcMBgLRS+4IYUqbczewFx4mLEig6gawh7X6mFlEkA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/unbzip2-stream": {
@@ -9622,7 +9501,6 @@
       "version": "11.1.0",
       "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz",
       "integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==",
-      "dev": true,
       "funding": [
         "https://github.com/sponsors/broofa",
         "https://github.com/sponsors/ctavan"
@@ -9897,7 +9775,6 @@
       "version": "8.2.0",
       "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
       "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=14.0.0"
@@ -9907,7 +9784,6 @@
       "version": "9.0.1",
       "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
       "integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "vscode-languageserver-protocol": "3.17.5"
@@ -9920,7 +9796,6 @@
       "version": "3.17.5",
       "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
       "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "vscode-jsonrpc": "8.2.0",
@@ -9931,21 +9806,18 @@
       "version": "1.0.12",
       "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
       "integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/vscode-languageserver-types": {
       "version": "3.17.5",
       "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
       "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/vscode-uri": {
       "version": "3.0.8",
       "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.0.8.tgz",
       "integrity": "sha512-AyFQ0EVmsOZOlAnxoFOGOq1SQDWAB7C6aqMGS23svWAllfOaxbuFvcT8D1i8z3Gyn8fraVeZNNmN6e9bxxXkKw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/w3c-xmlserializer": {
@@ -10236,14 +10108,19 @@
       "version": "0.0.1",
       "license": "MIT",
       "dependencies": {
+        "dompurify": "^3.0.6",
+        "highlight.js": "^11.9.0",
         "markdown-it": "^14.1.0",
         "markdown-it-anchor": "^8.6.7",
         "markdown-it-attrs": "^4.1.6",
         "markdown-it-emoji": "^3.0.0",
         "markdown-it-footnote": "^4.0.0",
-        "markdown-it-task-lists": "^2.1.1"
+        "markdown-it-task-lists": "^2.1.1",
+        "mermaid": "^11.12.1",
+        "panzoom": "^9.4.3"
       },
       "devDependencies": {
+        "@types/dompurify": "^3.0.5",
         "@types/markdown-it": "^13.0.9"
       }
     }
diff --git a/package.json b/package.json
index 7305cda..2c7dfdc 100644
--- a/package.json
+++ b/package.json
@@ -21,13 +21,11 @@
   "dependencies": {
     "@jamesainslie/docx": "^9.5.1-svg.1",
     "dompurify": "^3.0.6",
-    "highlight.js": "^11.9.0",
     "markdown-it-anchor": "^8.6.7",
     "markdown-it-attrs": "^4.1.6",
     "markdown-it-emoji": "^3.0.0",
     "markdown-it-footnote": "^4.0.0",
-    "markdown-it-task-lists": "^2.1.1",
-    "panzoom": "^9.4.3"
+    "markdown-it-task-lists": "^2.1.1"
   },
   "devDependencies": {
     "@crxjs/vite-plugin": "^2.0.0",
@@ -44,7 +42,6 @@
     "jsdom": "^27.2.0",
     "lint-staged": "^16.2.7",
     "markdown-it": "^14.1.0",
-    "mermaid": "^11.12.1",
     "playwright": "^1.48.0",
     "prettier": "^3.1.0",
     "sharp": "^0.34.5",
diff --git a/packages/core/src/renderers/mermaid-renderer.ts b/packages/core/src/renderers/mermaid-renderer.ts
new file mode 100644
index 0000000..e9f3c46
--- /dev/null
+++ b/packages/core/src/renderers/mermaid-renderer.ts
@@ -0,0 +1,903 @@
+/**
+ * Mermaid Renderer
+ * Renders and manages interactive Mermaid diagrams
+ */
+
+import mermaid from 'mermaid';
+import Panzoom from 'panzoom';
+import type { PanZoom } from 'panzoom';
+import { createDebug } from '../utils/debug-logger';
+import type { MermaidThemeConfig } from '../types/index';
+
+const debug = createDebug();
+
+export interface MermaidOptions {
+  theme?: 'base' | 'dark' | 'default' | 'forest' | 'neutral';
+  themeVariables?: Record<string, string>;
+  maxTextSize?: number;
+  maxEdges?: number;
+}
+
+export interface DiagramControls {
+  zoomIn: () => void;
+  zoomOut: () => void;
+  resetZoom: () => void;
+  fitToView: () => void;
+  maximize: () => void;
+  exportSVG: () => void;
+}
+
+export class MermaidRenderer {
+  private panzoomInstances: Map<string, PanZoom> = new Map();
+  private renderQueue: string[] = [];
+  private isRendering = false;
+  private observer: IntersectionObserver | null = null;
+
+  constructor() {
+    this.initializeMermaid();
+    this.setupIntersectionObserver();
+  }
+
+  /**
+   * Initialize Mermaid with security settings
+   */
+  private initializeMermaid(): void {
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: 'strict',
+      maxTextSize: 50000,
+      maxEdges: 500,
+      theme: 'base',
+      themeVariables: {
+        // Default light theme variables to ensure text is visible
+        textColor: '#24292f',
+        tertiaryTextColor: '#24292f',
+        primaryTextColor: '#24292f',
+        lineColor: '#24292f',
+      },
+      flowchart: {
+        htmlLabels: false,
+        useMaxWidth: true,
+      },
+      sequence: {
+        useMaxWidth: true,
+      },
+      gantt: {
+        useMaxWidth: true,
+      },
+      er: {
+        useMaxWidth: true,
+      },
+    });
+
+    debug.info('MermaidRenderer', ' Initialized');
+  }
+
+  /**
+   * Set up Intersection Observer for lazy loading
+   */
+  private setupIntersectionObserver(): void {
+    if ('IntersectionObserver' in window) {
+      this.observer = new IntersectionObserver(
+        (entries) => {
+          entries.forEach((entry) => {
+            if (entry.isIntersecting) {
+              const container = entry.target as HTMLElement;
+              const id = container.id;
+              if (id && container.classList.contains('mermaid-pending')) {
+                this.renderDiagram(id).catch(debug.error);
+              }
+            }
+          });
+        },
+        {
+          rootMargin: '100px', // Pre-load when 100px away
+          threshold: 0.01,
+        }
+      );
+    }
+  }
+
+  /**
+   * Update Mermaid theme and re-render diagrams
+   */
+  updateTheme(config: MermaidThemeConfig): void {
+    debug.info('MermaidRenderer', `Updating theme to ${config.theme}`);
+
+    // Ensure ER diagram text colors are set correctly
+    const themeVars = {
+      ...config.themeVariables,
+      // Ensure tertiary text color matches text color for ER diagrams
+      tertiaryTextColor: config.themeVariables.tertiaryTextColor || config.themeVariables.textColor,
+    };
+
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: 'strict',
+      maxTextSize: 50000,
+      maxEdges: 500,
+      theme: config.theme,
+      themeVariables: themeVars,
+      flowchart: {
+        htmlLabels: false,
+        useMaxWidth: true,
+      },
+      sequence: {
+        useMaxWidth: true,
+      },
+      gantt: {
+        useMaxWidth: true,
+      },
+      er: {
+        useMaxWidth: true,
+      },
+    });
+
+    this.rerenderAll().catch((error) => {
+      debug.error('MermaidRenderer', 'Failed to re-render diagrams:', error);
+    });
+  }
+
+  /**
+   * Re-render all initialized diagrams
+   */
+  private async rerenderAll(): Promise<void> {
+    const diagrams = document.querySelectorAll('.mermaid-container');
+
+    for (const container of Array.from(diagrams)) {
+      const element = container as HTMLElement;
+      const id = element.id;
+
+      if (!id) continue;
+
+      // Check if it was previously rendered or had an error
+      if (
+        element.classList.contains('mermaid-ready') ||
+        element.classList.contains('mermaid-error')
+      ) {
+        // Clean up Panzoom
+        const panzoom = this.panzoomInstances.get(id);
+        if (panzoom) {
+          panzoom.dispose();
+          this.panzoomInstances.delete(id);
+        }
+
+        // Clean up keyboard listeners
+        const elementWithCleanup = element as { __keyboardCleanup?: () => void };
+        if (elementWithCleanup.__keyboardCleanup) {
+          elementWithCleanup.__keyboardCleanup();
+        }
+
+        // Reset state
+        element.classList.remove('mermaid-ready', 'mermaid-error');
+        element.classList.add('mermaid-pending');
+        element.innerHTML = ''; // Clear content
+
+        // Re-render
+        await this.renderDiagram(id);
+      }
+    }
+  }
+
+  /**
+   * Render all Mermaid diagrams in a container
+   */
+  async renderAll(container: HTMLElement): Promise<void> {
+    const diagrams = container.querySelectorAll('.mermaid-container.mermaid-pending');
+
+    for (const diagram of Array.from(diagrams)) {
+      const id = diagram.id;
+      if (id) {
+        // Use observer if available, otherwise render immediately
+        if (this.observer) {
+          this.observer.observe(diagram);
+        } else {
+          await this.renderDiagram(id);
+        }
+      }
+    }
+  }
+
+  /**
+   * Force-render all Mermaid diagrams in a container, bypassing lazy loading.
+   * Used by export/print flows where we must have every diagram rendered,
+   * regardless of scroll position.
+   */
+  async renderAllImmediate(container: HTMLElement): Promise<void> {
+    const diagrams = container.querySelectorAll('.mermaid-container');
+
+    for (const diagram of Array.from(diagrams)) {
+      const id = diagram.id;
+      if (id) {
+        await this.renderDiagram(id);
+      }
+    }
+  }
+
+  /**
+   * Render a single Mermaid diagram
+   */
+  async renderDiagram(containerId: string): Promise<void> {
+    const container = document.getElementById(containerId);
+    if (!container) {
+      debug.error('MermaidRenderer', `Container not found: ${containerId}`);
+      return;
+    }
+
+    // Check if already rendered (either with wrapper or direct SVG from cache)
+    if (container.querySelector('.mermaid-rendered') || container.querySelector('svg')) {
+      debug.debug('MermaidRenderer', `Container ${containerId} already has rendered content`);
+      return;
+    }
+
+    // Get mermaid code from global registry or data attribute (fallback for lazy sections)
+    const windowWithRegistry = window as { __MDVIEW_MERMAID_CODE__?: Map<string, string> };
+    const registry = windowWithRegistry.__MDVIEW_MERMAID_CODE__;
+    let code = registry?.get(containerId)?.trim();
+
+    // Fallback: Check if code was stored in data attribute (from previous render)
+    if (!code) {
+      code = container.getAttribute('data-mermaid-code') || '';
+    }
+
+    if (!code) {
+      // If there's no code and no SVG, this is likely a cache issue where
+      // the mermaid code was never stored. Log as warning, not error.
+      debug.warn(
+        'MermaidRenderer',
+        `No code found for ${containerId} - diagram may need re-rendering from source`
+      );
+      return;
+    }
+
+    debug.debug('MermaidRenderer', `Container ${containerId}: code exists, length: ${code.length}`);
+
+    // Store code in the container as data attribute for potential re-renders
+    container.setAttribute('data-mermaid-code', code);
+
+    // Remove from registry now that we've stored it in DOM
+    // (Keep it in registry too in case of re-renders before DOM update)
+    // registry.delete(containerId); // Don't delete - keep for lazy sections
+
+    // Add to queue if currently rendering
+    if (this.isRendering) {
+      if (!this.renderQueue.includes(containerId)) {
+        this.renderQueue.push(containerId);
+      }
+      return;
+    }
+
+    this.isRendering = true;
+
+    try {
+      // Validate syntax
+      const validation = await this.validateSyntax(code);
+      if (!validation.valid) {
+        this.showError(container, validation.error || 'Invalid Mermaid syntax');
+        return;
+      }
+
+      // Generate unique ID for SVG
+      const svgId = `mermaid-svg-${containerId}`;
+
+      // Render with timeout and proper cleanup
+      let timeoutId: ReturnType<typeof setTimeout>;
+      const renderPromise = mermaid.render(svgId, code);
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error('Render timeout')), 5000);
+      });
+
+      let result: { svg: string };
+      try {
+        result = await Promise.race([renderPromise, timeoutPromise]);
+        clearTimeout(timeoutId!);
+      } catch (error) {
+        clearTimeout(timeoutId!);
+        // Clean up any orphaned DOM elements that mermaid.render() may have created
+        // mermaid creates temporary SVG elements with the svgId during rendering
+        const orphanedSvg = document.getElementById(svgId);
+        if (orphanedSvg) {
+          orphanedSvg.remove();
+        }
+        throw error;
+      }
+
+      // Clear loading state
+      container.innerHTML = '';
+
+      // Create wrapper for diagram
+      const wrapper = document.createElement('div');
+      wrapper.className = 'mermaid-rendered';
+      wrapper.innerHTML = result.svg;
+
+      container.appendChild(wrapper);
+
+      // Add controls
+      this.addControls(container);
+
+      // Initialize Panzoom
+      const svg = wrapper.querySelector('svg');
+      if (svg) {
+        this.initializePanzoom(container, svg as SVGElement);
+      }
+
+      // Mark as rendered
+      container.classList.remove('mermaid-pending');
+      container.classList.add('mermaid-ready');
+
+      // Unobserve if using IntersectionObserver
+      if (this.observer) {
+        this.observer.unobserve(container);
+      }
+
+      debug.info('MermaidRenderer', ` Rendered diagram: ${containerId}`);
+    } catch (error) {
+      debug.error('MermaidRenderer', `[MermaidRenderer] Error rendering ${containerId}:`, error);
+      this.showError(container, error instanceof Error ? error.message : String(error));
+    } finally {
+      this.isRendering = false;
+
+      // Process queue
+      if (this.renderQueue.length > 0) {
+        const nextId = this.renderQueue.shift();
+        if (nextId) {
+          this.renderDiagram(nextId).catch(debug.error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Validate Mermaid syntax
+   */
+  private async validateSyntax(code: string): Promise<{ valid: boolean; error?: string }> {
+    try {
+      // Basic validation - check for empty or malformed code
+      if (!code.trim()) {
+        return { valid: false, error: 'Empty diagram code' };
+      }
+
+      // Check size limits
+      if (code.length > 50000) {
+        return { valid: false, error: 'Diagram code exceeds size limit (50,000 characters)' };
+      }
+
+      // Try to parse (Mermaid doesn't provide a separate parse method)
+      await mermaid.parse(code);
+
+      return { valid: true };
+    } catch (error) {
+      return {
+        valid: false,
+        error: error instanceof Error ? error.message : 'Parse error',
+      };
+    }
+  }
+
+  /**
+   * Initialize Panzoom for a diagram
+   */
+  private initializePanzoom(container: HTMLElement, svg: SVGElement): void {
+    debug.debug('MermaidRenderer', `initializePanzoom() called for container: ${container.id}`);
+
+    const panzoomInstance = Panzoom(svg, {
+      maxZoom: 10,
+      minZoom: 0.1,
+      smoothScroll: false,
+      bounds: true,
+      boundsPadding: 0.1,
+    });
+
+    debug.debug('MermaidRenderer', `  Panzoom instance created, storing with ID: ${container.id}`);
+
+    // Store instance
+    this.panzoomInstances.set(container.id, panzoomInstance);
+
+    const initialTransform = panzoomInstance.getTransform();
+    debug.debug(
+      'MermaidRenderer',
+      `  Initial transform: scale=${initialTransform.scale.toFixed(2)}, pos=(${initialTransform.x.toFixed(1)}, ${initialTransform.y.toFixed(1)})`
+    );
+
+    // Listen for transform changes to debug unexpected resets
+    svg.addEventListener('panzoomchange', (() => {
+      const transform = panzoomInstance.getTransform();
+      debug.debug(
+        'MermaidRenderer',
+        `  Transform changed for ${container.id}: scale=${transform.scale.toFixed(2)}, pos=(${transform.x.toFixed(1)}, ${transform.y.toFixed(1)})`
+      );
+    }) as EventListener);
+
+    // Add mouse wheel zoom
+    svg.parentElement?.addEventListener('wheel', (e: WheelEvent) => {
+      if (e.ctrlKey || e.metaKey) {
+        e.preventDefault();
+        // Manual zoom calculation
+        const delta = e.deltaY > 0 ? 0.9 : 1.1;
+        const transform = panzoomInstance.getTransform();
+        panzoomInstance.zoomTo(e.clientX, e.clientY, transform.scale * delta);
+      }
+    });
+
+    // Add keyboard controls
+    this.setupKeyboardControls(container, panzoomInstance);
+  }
+
+  /**
+   * Setup keyboard controls for diagram
+   */
+  private setupKeyboardControls(
+    container: HTMLElement,
+    panzoom: PanZoom,
+    maximizeCallback?: () => void
+  ): void {
+    const handler = (e: KeyboardEvent) => {
+      // Only handle if container is focused or hovered
+      if (!container.matches(':hover, :focus-within')) {
+        return;
+      }
+
+      switch (e.key) {
+        case '+':
+        case '=':
+          e.preventDefault();
+          {
+            const transform = panzoom.getTransform();
+            panzoom.zoomTo(0, 0, transform.scale * 1.2);
+          }
+          break;
+        case '-':
+          e.preventDefault();
+          {
+            const transform = panzoom.getTransform();
+            panzoom.zoomTo(0, 0, transform.scale * 0.8);
+          }
+          break;
+        case '0':
+          e.preventDefault();
+          panzoom.moveTo(0, 0);
+          panzoom.zoomAbs(0, 0, 1);
+          break;
+        case 'f':
+          e.preventDefault();
+          this.fitToView(container.id);
+          break;
+        case 'm':
+          e.preventDefault();
+          // If in maximized view (callback provided), close instead of maximize
+          if (maximizeCallback) {
+            maximizeCallback();
+          } else {
+            this.maximize(container.id);
+          }
+          break;
+        case 'e':
+          e.preventDefault();
+          void this.exportSVG(container.id);
+          break;
+        case 'ArrowUp':
+          if (e.shiftKey) {
+            e.preventDefault();
+            panzoom.moveTo(panzoom.getTransform().x, panzoom.getTransform().y - 50);
+          }
+          break;
+        case 'ArrowDown':
+          if (e.shiftKey) {
+            e.preventDefault();
+            panzoom.moveTo(panzoom.getTransform().x, panzoom.getTransform().y + 50);
+          }
+          break;
+        case 'ArrowLeft':
+          if (e.shiftKey) {
+            e.preventDefault();
+            panzoom.moveTo(panzoom.getTransform().x - 50, panzoom.getTransform().y);
+          }
+          break;
+        case 'ArrowRight':
+          if (e.shiftKey) {
+            e.preventDefault();
+            panzoom.moveTo(panzoom.getTransform().x + 50, panzoom.getTransform().y);
+          }
+          break;
+      }
+    };
+
+    document.addEventListener('keydown', handler);
+
+    // Store cleanup function
+    const containerWithCleanup = container as { __keyboardCleanup?: () => void };
+    containerWithCleanup.__keyboardCleanup = () => {
+      document.removeEventListener('keydown', handler);
+    };
+  }
+
+  /**
+   * Add control buttons to diagram
+   */
+  private addControls(container: HTMLElement): void {
+    const controls = document.createElement('div');
+    controls.className = 'mermaid-controls';
+
+    const buttons = [
+      { label: '+', title: 'Zoom In (+)', action: () => this.zoomIn(container.id) },
+      { label: '\u2212', title: 'Zoom Out (-)', action: () => this.zoomOut(container.id) },
+      { label: '\u229E', title: 'Reset to 100% (0)', action: () => this.resetZoom(container.id) },
+      { label: '\u2922', title: 'Fit to View (F)', action: () => this.fitToView(container.id) },
+      { label: '\u26F6', title: 'Maximize (M)', action: () => this.maximize(container.id) },
+      { label: '\u2193', title: 'Export SVG (E)', action: () => this.exportSVG(container.id) },
+    ];
+
+    buttons.forEach(({ label, title, action }) => {
+      const button = document.createElement('button');
+      button.className = 'mermaid-control-button';
+      button.textContent = label;
+      button.title = title;
+      button.setAttribute('aria-label', title);
+      button.addEventListener('click', action);
+      controls.appendChild(button);
+    });
+
+    container.appendChild(controls);
+  }
+
+  /**
+   * Re-attach event listeners to cloned control buttons
+   * (cloneNode doesn't copy event listeners)
+   */
+  private reattachControls(container: HTMLElement, closeMaximizeCallback?: () => void): void {
+    const controls = container.querySelector('.mermaid-controls');
+    if (!controls) return;
+
+    const buttons = controls.querySelectorAll('.mermaid-control-button');
+
+    // Define actions for each button (same order as addControls)
+    const actions = [
+      () => this.zoomIn(container.id),
+      () => this.zoomOut(container.id),
+      () => this.resetZoom(container.id),
+      () => this.fitToView(container.id),
+      closeMaximizeCallback ? closeMaximizeCallback : () => this.maximize(container.id), // In maximized view, this closes instead
+      () => this.exportSVG(container.id),
+    ];
+
+    buttons.forEach((button, index) => {
+      // Remove old listeners by cloning the button (clean slate)
+      const newButton = button.cloneNode(true) as HTMLElement;
+      button.parentNode?.replaceChild(newButton, button);
+
+      // Attach new listener
+      if (actions[index]) {
+        newButton.addEventListener('click', actions[index]);
+      }
+    });
+  }
+
+  /**
+   * Zoom in
+   */
+  zoomIn(containerId: string): void {
+    const container = document.getElementById(containerId);
+    const panzoom = this.panzoomInstances.get(containerId);
+    if (panzoom && container) {
+      const transform = panzoom.getTransform();
+      const containerRect = container.getBoundingClientRect();
+      // Zoom toward center of visible area
+      const centerX = containerRect.width / 2;
+      const centerY = containerRect.height / 2;
+      panzoom.smoothZoomAbs(centerX, centerY, transform.scale * 1.2);
+    }
+  }
+
+  /**
+   * Zoom out
+   */
+  zoomOut(containerId: string): void {
+    const container = document.getElementById(containerId);
+    const panzoom = this.panzoomInstances.get(containerId);
+    if (panzoom && container) {
+      const transform = panzoom.getTransform();
+      const containerRect = container.getBoundingClientRect();
+      // Zoom toward center of visible area
+      const centerX = containerRect.width / 2;
+      const centerY = containerRect.height / 2;
+      panzoom.smoothZoomAbs(centerX, centerY, transform.scale * 0.8);
+    }
+  }
+
+  /**
+   * Reset zoom to 1:1 scale and center
+   */
+  resetZoom(containerId: string): void {
+    const container = document.getElementById(containerId);
+    const panzoom = this.panzoomInstances.get(containerId);
+
+    if (!container || !panzoom) return;
+
+    const svg = container.querySelector('svg');
+    if (!svg) return;
+
+    // Reset to 1:1 scale and identity translation
+    // The browser's SVG viewBox + width=100% handles the fitting naturally
+    panzoom.zoomAbs(0, 0, 1);
+    panzoom.moveTo(0, 0);
+
+    debug.debug('MermaidRenderer', `Reset zoom for ${containerId}`);
+  }
+
+  /**
+   * Fit diagram to view (centered)
+   */
+  fitToView(containerId: string): void {
+    debug.debug('MermaidRenderer', `Fit to view for: ${containerId}`);
+    // "Fit to view" in this context means resetting to the natural
+    // layout where the diagram fits within the container (width=100%)
+    this.resetZoom(containerId);
+  }
+
+  /**
+   * Maximize diagram (fullscreen mode)
+   */
+  maximize(containerId: string): void {
+    debug.debug('MermaidRenderer', `maximize() called for: ${containerId}`);
+
+    const container = document.getElementById(containerId);
+    if (!container) {
+      debug.error('MermaidRenderer', `Container not found: ${containerId}`);
+      return;
+    }
+
+    debug.debug('MermaidRenderer', `  Creating maximize overlay...`);
+
+    // Create overlay
+    const overlay = document.createElement('div');
+    overlay.className = 'mermaid-maximize-overlay';
+    overlay.setAttribute('tabindex', '0');
+
+    // Clone diagram
+    const clone = container.cloneNode(true) as HTMLElement;
+
+    // Give clone a unique ID for panzoom tracking
+    const maximizedId = `${containerId}-maximized`;
+    clone.id = maximizedId;
+    clone.classList.add('maximized');
+
+    debug.debug('MermaidRenderer', `  Cloned diagram with ID: ${maximizedId}`);
+
+    // Make the clone expand to fill available space
+    clone.style.width = '90vw';
+    clone.style.height = '90vh';
+    clone.style.maxWidth = '90vw';
+    clone.style.maxHeight = '90vh';
+    clone.style.display = 'flex';
+    clone.style.alignItems = 'center';
+    clone.style.justifyContent = 'center';
+
+    debug.debug('MermaidRenderer', `  Appending to DOM...`);
+    overlay.appendChild(clone);
+    document.body.appendChild(overlay);
+
+    const cleanup = () => {
+      // Clean up panzoom instance
+      const clonePanzoom = this.panzoomInstances.get(maximizedId);
+      if (clonePanzoom) {
+        clonePanzoom.dispose();
+        this.panzoomInstances.delete(maximizedId);
+      }
+
+      // Clean up keyboard handlers
+      const cloneWithCleanup = clone as { __keyboardCleanup?: () => void };
+      if (cloneWithCleanup.__keyboardCleanup) {
+        cloneWithCleanup.__keyboardCleanup();
+      }
+
+      // Remove overlay from DOM
+      if (document.body.contains(overlay)) {
+        document.body.removeChild(overlay);
+      }
+    };
+
+    // Re-attach event listeners to cloned control buttons
+    this.reattachControls(clone, cleanup);
+
+    // Add close button
+    const closeButton = document.createElement('button');
+    closeButton.className = 'mermaid-close-button';
+    closeButton.textContent = '\u2715';
+    closeButton.title = 'Close (Esc)';
+    closeButton.setAttribute('aria-label', 'Close maximize mode');
+    closeButton.addEventListener('click', cleanup);
+    overlay.appendChild(closeButton);
+
+    // Re-initialize Panzoom for maximized instance
+    const svg = clone.querySelector('svg');
+    if (svg) {
+      debug.debug('MermaidRenderer', `  Found SVG, initializing panzoom...`);
+
+      const svgElement = svg as SVGElement;
+      // Make SVG scale to fit
+      svgElement.style.width = '100%';
+      svgElement.style.height = '100%';
+      svgElement.style.maxWidth = '100%';
+      svgElement.style.maxHeight = '100%';
+
+      this.initializePanzoom(clone, svgElement);
+      debug.debug('MermaidRenderer', `  Panzoom initialized for ${maximizedId}`);
+
+      // Re-setup keyboard controls for the cloned instance
+      const clonePanzoom = this.panzoomInstances.get(maximizedId);
+      if (clonePanzoom) {
+        this.setupKeyboardControls(clone, clonePanzoom, cleanup);
+
+        // Center logic: Identity transform + moveTo(0,0)
+        // Since SVG is 100% width/height and preserves aspect ratio,
+        // this will center the content in the 90vw/90vh container
+        clonePanzoom.zoomAbs(0, 0, 1);
+        clonePanzoom.moveTo(0, 0);
+
+        debug.debug('MermaidRenderer', `  Maximized view centered`);
+      }
+    } else {
+      debug.error('MermaidRenderer', `  No SVG found in cloned container!`);
+    }
+
+    // Add ESC key handler
+    const escHandler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        cleanup();
+        document.removeEventListener('keydown', escHandler);
+      }
+    };
+    document.addEventListener('keydown', escHandler);
+
+    // Click outside to close
+    overlay.addEventListener('click', (e) => {
+      if (e.target === overlay) {
+        cleanup();
+        document.removeEventListener('keydown', escHandler);
+      }
+    });
+
+    // Focus overlay for accessibility
+    overlay.focus();
+  }
+
+  /**
+   * Export diagram as SVG
+   */
+  exportSVG(containerId: string): void {
+    const container = document.getElementById(containerId);
+    if (!container) return;
+
+    const svg = container.querySelector('svg');
+    if (!svg) {
+      debug.error('MermaidRenderer', ' No SVG found for export');
+      return;
+    }
+
+    try {
+      // Clone and clean SVG
+      const clone = svg.cloneNode(true) as SVGElement;
+
+      // Remove Panzoom transformations
+      clone.removeAttribute('style');
+      clone.querySelectorAll('[style]').forEach((el) => {
+        el.removeAttribute('style');
+      });
+
+      // Add XML declaration
+      const serializer = new XMLSerializer();
+      const svgString =
+        '<?xml version="1.0" encoding="UTF-8"?>\n' + serializer.serializeToString(clone);
+
+      // Create blob and download
+      const blob = new Blob([svgString], { type: 'image/svg+xml' });
+      const url = URL.createObjectURL(blob);
+
+      const link = document.createElement('a');
+      link.href = url;
+      link.download = `mermaid-${containerId}.svg`;
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+
+      URL.revokeObjectURL(url);
+
+      debug.info('MermaidRenderer', ` Exported SVG: ${containerId}`);
+
+      // Show success notification
+      this.showNotification(container, 'SVG exported successfully');
+    } catch (error) {
+      debug.error('MermaidRenderer', ' Export error:', error);
+      this.showNotification(container, 'Export failed', true);
+    }
+  }
+
+  /**
+   * Show error in container
+   */
+  private showError(container: HTMLElement, message: string): void {
+    const code = container.getAttribute('data-mermaid-code') || '';
+
+    container.innerHTML = `
+      <div class="mermaid-error" role="alert">
+        <h4>Mermaid Diagram Error</h4>
+        <p>${this.escapeHtml(message)}</p>
+        <details>
+          <summary>Diagram Code</summary>
+          <pre><code>${this.escapeHtml(code)}</code></pre>
+        </details>
+        <p><a href="https://mermaid.js.org/intro/" target="_blank" rel="noopener noreferrer">View Mermaid Documentation</a></p>
+        <button class="mermaid-copy-error">Copy Error</button>
+      </div>
+    `;
+
+    // Add copy error button handler
+    const copyButton = container.querySelector('.mermaid-copy-error');
+    if (copyButton) {
+      copyButton.addEventListener('click', () => {
+        void (async () => {
+          try {
+            await navigator.clipboard.writeText(`${message}\n\n${code}`);
+            (copyButton as HTMLElement).textContent = '\u2713 Copied';
+          } catch (error) {
+            debug.error('MermaidRenderer', 'Failed to copy error:', error);
+          }
+        })();
+      });
+    }
+
+    container.classList.remove('mermaid-pending');
+    container.classList.add('mermaid-error');
+  }
+
+  /**
+   * Show notification toast
+   */
+  private showNotification(container: HTMLElement, message: string, isError = false): void {
+    const toast = document.createElement('div');
+    toast.className = `mermaid-notification ${isError ? 'error' : 'success'}`;
+    toast.textContent = message;
+    toast.setAttribute('role', 'status');
+    toast.setAttribute('aria-live', 'polite');
+
+    container.appendChild(toast);
+
+    setTimeout(() => {
+      toast.classList.add('fade-out');
+      setTimeout(() => {
+        container.removeChild(toast);
+      }, 300);
+    }, 2000);
+  }
+
+  /**
+   * Escape HTML
+   */
+  private escapeHtml(text: string): string {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+
+  /**
+   * Clean up resources
+   */
+  cleanup(): void {
+    // Dispose all panzoom instances
+    this.panzoomInstances.forEach((panzoom) => {
+      panzoom.dispose();
+    });
+    this.panzoomInstances.clear();
+
+    // Disconnect observer
+    if (this.observer) {
+      this.observer.disconnect();
+      this.observer = null;
+    }
+
+    debug.info('MermaidRenderer', ' Cleaned up');
+  }
+}
+
+// Export singleton
+export const mermaidRenderer = new MermaidRenderer();
diff --git a/packages/core/src/renderers/syntax-highlighter.ts b/packages/core/src/renderers/syntax-highlighter.ts
new file mode 100644
index 0000000..dd797b7
--- /dev/null
+++ b/packages/core/src/renderers/syntax-highlighter.ts
@@ -0,0 +1,358 @@
+/**
+ * Syntax Highlighter
+ * Applies syntax highlighting to code blocks using Highlight.js
+ */
+
+import hljs from 'highlight.js/lib/core';
+import type { LanguageFn } from 'highlight.js';
+import { createDebug } from '../utils/debug-logger';
+
+const debug = createDebug();
+
+// Import common languages immediately
+import javascript from 'highlight.js/lib/languages/javascript';
+import typescript from 'highlight.js/lib/languages/typescript';
+import python from 'highlight.js/lib/languages/python';
+import bash from 'highlight.js/lib/languages/bash';
+import json from 'highlight.js/lib/languages/json';
+
+export interface HighlightResult {
+  html: string;
+  language: string;
+  relevance: number;
+}
+
+export interface DetectionResult {
+  language: string;
+  relevance: number;
+  secondBest?: {
+    language: string;
+    relevance: number;
+  };
+}
+
+/**
+ * Syntax Highlighter Class
+ */
+export class SyntaxHighlighter {
+  private loadedLanguages: Set<string> = new Set();
+  private languageAliases: Map<string, string> = new Map([
+    ['js', 'javascript'],
+    ['ts', 'typescript'],
+    ['py', 'python'],
+    ['sh', 'bash'],
+    ['yml', 'yaml'],
+    ['md', 'markdown'],
+  ]);
+
+  // Map of language module loaders
+  private languageModules: Record<string, () => Promise<{ default: LanguageFn }>> = {
+    go: () => import('highlight.js/lib/languages/go'),
+    rust: () => import('highlight.js/lib/languages/rust'),
+    java: () => import('highlight.js/lib/languages/java'),
+    cpp: () => import('highlight.js/lib/languages/cpp'),
+    c: () => import('highlight.js/lib/languages/c'),
+    csharp: () => import('highlight.js/lib/languages/csharp'),
+    ruby: () => import('highlight.js/lib/languages/ruby'),
+    php: () => import('highlight.js/lib/languages/php'),
+    sql: () => import('highlight.js/lib/languages/sql'),
+    yaml: () => import('highlight.js/lib/languages/yaml'),
+    xml: () => import('highlight.js/lib/languages/xml'),
+    html: () => import('highlight.js/lib/languages/xml'),
+    css: () => import('highlight.js/lib/languages/css'),
+    scss: () => import('highlight.js/lib/languages/scss'),
+    markdown: () => import('highlight.js/lib/languages/markdown'),
+    dockerfile: () => import('highlight.js/lib/languages/dockerfile'),
+    nginx: () => import('highlight.js/lib/languages/nginx'),
+    apache: () => import('highlight.js/lib/languages/apache'),
+    perl: () => import('highlight.js/lib/languages/perl'),
+    r: () => import('highlight.js/lib/languages/r'),
+    swift: () => import('highlight.js/lib/languages/swift'),
+    kotlin: () => import('highlight.js/lib/languages/kotlin'),
+    scala: () => import('highlight.js/lib/languages/scala'),
+    haskell: () => import('highlight.js/lib/languages/haskell'),
+    lua: () => import('highlight.js/lib/languages/lua'),
+    vim: () => import('highlight.js/lib/languages/vim'),
+    diff: () => import('highlight.js/lib/languages/diff'),
+    makefile: () => import('highlight.js/lib/languages/makefile'),
+    ini: () => import('highlight.js/lib/languages/ini'),
+    properties: () => import('highlight.js/lib/languages/properties'),
+  };
+
+  constructor() {
+    // Register common languages immediately
+    hljs.registerLanguage('javascript', javascript);
+    hljs.registerLanguage('typescript', typescript);
+    hljs.registerLanguage('python', python);
+    hljs.registerLanguage('bash', bash);
+    hljs.registerLanguage('json', json);
+
+    this.loadedLanguages.add('javascript');
+    this.loadedLanguages.add('typescript');
+    this.loadedLanguages.add('python');
+    this.loadedLanguages.add('bash');
+    this.loadedLanguages.add('json');
+
+    // Configure highlight.js
+    hljs.configure({
+      classPrefix: 'hljs-',
+      ignoreUnescapedHTML: true,
+    });
+  }
+
+  /**
+   * Highlight code with specified language
+   */
+  async highlight(code: string, language: string): Promise<HighlightResult> {
+    // Normalize language name
+    const normalizedLang = this.normalizeLanguage(language);
+
+    // Load language if not already loaded
+    await this.loadLanguage(normalizedLang);
+
+    try {
+      // Check if language is available
+      if (hljs.getLanguage(normalizedLang)) {
+        const result = hljs.highlight(code, {
+          language: normalizedLang,
+          ignoreIllegals: true,
+        });
+
+        return {
+          html: result.value,
+          language: normalizedLang,
+          relevance: result.relevance || 0,
+        };
+      } else {
+        // Fallback: auto-detect
+        return this.highlightAuto(code);
+      }
+    } catch (error) {
+      console.error(`[SyntaxHighlighter] Error highlighting ${normalizedLang}:`, error);
+      // Return unformatted code
+      return {
+        html: this.escapeHtml(code),
+        language: 'plaintext',
+        relevance: 0,
+      };
+    }
+  }
+
+  /**
+   * Auto-detect and highlight code
+   */
+  highlightAuto(code: string): HighlightResult {
+    try {
+      const result = hljs.highlightAuto(code);
+      return {
+        html: result.value,
+        language: result.language || 'plaintext',
+        relevance: result.relevance || 0,
+      };
+    } catch (error) {
+      debug.error('SyntaxHighlighter', ' Auto-detect error:', error);
+      return {
+        html: this.escapeHtml(code),
+        language: 'plaintext',
+        relevance: 0,
+      };
+    }
+  }
+
+  /**
+   * Detect code language
+   */
+  detectLanguage(code: string): DetectionResult {
+    try {
+      const result = hljs.highlightAuto(code);
+      return {
+        language: result.language || 'plaintext',
+        relevance: result.relevance || 0,
+        secondBest: result.secondBest
+          ? {
+              language: result.secondBest.language || 'plaintext',
+              relevance: result.secondBest.relevance || 0,
+            }
+          : undefined,
+      };
+    } catch (error) {
+      debug.error('SyntaxHighlighter', ' Language detection error:', error);
+      return {
+        language: 'plaintext',
+        relevance: 0,
+      };
+    }
+  }
+
+  /**
+   * Load language grammar on-demand
+   */
+  async loadLanguage(language: string): Promise<void> {
+    // Check if already loaded
+    if (this.loadedLanguages.has(language)) {
+      return;
+    }
+
+    // Check if we have a loader for this language
+    const loader = this.languageModules[language];
+    if (!loader) {
+      console.warn(`[SyntaxHighlighter] No loader for language: ${language}`);
+      return;
+    }
+
+    try {
+      const module = await loader();
+      hljs.registerLanguage(language, module.default);
+      this.loadedLanguages.add(language);
+      debug.log('SyntaxHighlighter', ` Loaded language: ${language}`);
+    } catch (error) {
+      console.error(`[SyntaxHighlighter] Failed to load language ${language}:`, error);
+    }
+  }
+
+  /**
+   * Get list of supported languages
+   */
+  getSupportedLanguages(): string[] {
+    return [...this.loadedLanguages, ...Object.keys(this.languageModules)].sort();
+  }
+
+  /**
+   * Check if language is supported
+   */
+  isLanguageSupported(language: string): boolean {
+    const normalized = this.normalizeLanguage(language);
+    return this.loadedLanguages.has(normalized) || normalized in this.languageModules;
+  }
+
+  /**
+   * Highlight all code blocks in a container
+   */
+  async highlightAll(container: HTMLElement): Promise<void> {
+    const codeBlocks = container.querySelectorAll('pre code[class*="language-"]');
+
+    for (const block of Array.from(codeBlocks)) {
+      const code = block.textContent || '';
+      const classNames = block.className.split(' ');
+      const langClass = classNames.find((cls) => cls.startsWith('language-'));
+
+      if (langClass) {
+        const lang = langClass.replace('language-', '');
+
+        // Check if code block is large (> 1000 lines)
+        if (code.split('\n').length > 1000) {
+          debug.log('SyntaxHighlighter', ` Large code block detected, highlighting may take time`);
+        }
+
+        try {
+          const result = await this.highlight(code, lang);
+          block.innerHTML = result.html;
+          block.classList.add('hljs', 'highlighted');
+          block.setAttribute('data-language', result.language);
+        } catch (error) {
+          debug.error('SyntaxHighlighter', ' Error highlighting block:', error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Highlight visible code blocks using Intersection Observer
+   */
+  highlightVisible(container: HTMLElement): void {
+    const codeBlocks = container.querySelectorAll('pre code[class*="language-"]:not(.highlighted)');
+
+    if ('IntersectionObserver' in window) {
+      const observer = new IntersectionObserver(
+        (entries) => {
+          entries.forEach((entry) => {
+            if (entry.isIntersecting) {
+              const block = entry.target as HTMLElement;
+              const code = block.textContent || '';
+              const classNames = block.className.split(' ');
+              const langClass = classNames.find((cls) => cls.startsWith('language-'));
+
+              if (langClass) {
+                const lang = langClass.replace('language-', '');
+
+                void (async () => {
+                  try {
+                    const result = await this.highlight(code, lang);
+                    block.innerHTML = result.html;
+                    block.classList.add('hljs', 'highlighted');
+                    block.setAttribute('data-language', result.language);
+                  } catch (error) {
+                    debug.error('SyntaxHighlighter', ' Error highlighting block:', error);
+                  }
+                })();
+              }
+
+              observer.unobserve(block);
+            }
+          });
+        },
+        {
+          rootMargin: '100px', // Pre-load when 100px away
+          threshold: 0.01,
+        }
+      );
+
+      codeBlocks.forEach((block) => observer.observe(block));
+    } else {
+      // Fallback: highlight all immediately
+      this.highlightAll(container).catch((error) =>
+        debug.error('SyntaxHighlighter', 'Catch error:', error)
+      );
+    }
+  }
+
+  /**
+   * Normalize language name
+   */
+  private normalizeLanguage(language: string): string {
+    const lower = language.toLowerCase();
+    return this.languageAliases.get(lower) || lower;
+  }
+
+  /**
+   * Escape HTML
+   */
+  private escapeHtml(text: string): string {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+
+  /**
+   * Set syntax theme (load CSS)
+   * Note: Dynamic CSS imports don't work in Chrome extensions, so we rely on
+   * the theme engine's CSS custom properties for styling instead.
+   */
+  setTheme(themeName: string): void {
+    // In Chrome extensions, dynamic CSS imports with ?inline don't work
+    // The theme engine applies CSS custom properties that style the hljs classes
+    // So we just log and skip the highlight.js theme loading
+    debug.log(
+      'SyntaxHighlighter',
+      `Syntax theme ${themeName} will be styled via theme engine CSS custom properties`
+    );
+
+    // Note: The .hljs-* classes are styled by our theme system through CSS variables
+    // defined in src/content/content.css and theme files
+  }
+}
+
+// Export singleton
+export const syntaxHighlighter = new SyntaxHighlighter();
+
+// Theme mapping for document themes
+export const SYNTAX_THEME_MAP: Record<string, string> = {
+  'github-light': 'github',
+  'github-dark': 'github-dark',
+  'catppuccin-latte': 'github', // Fallback to github for now
+  'catppuccin-frappe': 'github-dark',
+  'catppuccin-macchiato': 'github-dark',
+  'catppuccin-mocha': 'github-dark',
+  monokai: 'monokai',
+  'monokai-pro': 'monokai',
+};
diff --git a/src/renderers/mermaid-renderer.ts b/src/renderers/mermaid-renderer.ts
index 25f811a..9cdd3eb 100644
--- a/src/renderers/mermaid-renderer.ts
+++ b/src/renderers/mermaid-renderer.ts
@@ -1,901 +1 @@
-/**
- * Mermaid Renderer
- * Renders and manages interactive Mermaid diagrams
- */
-
-import mermaid from 'mermaid';
-import Panzoom from 'panzoom';
-import type { PanZoom } from 'panzoom';
-import { debug } from '../utils/debug-logger';
-import type { MermaidThemeConfig } from '../types';
-
-export interface MermaidOptions {
-  theme?: 'base' | 'dark' | 'default' | 'forest' | 'neutral';
-  themeVariables?: Record<string, string>;
-  maxTextSize?: number;
-  maxEdges?: number;
-}
-
-export interface DiagramControls {
-  zoomIn: () => void;
-  zoomOut: () => void;
-  resetZoom: () => void;
-  fitToView: () => void;
-  maximize: () => void;
-  exportSVG: () => void;
-}
-
-export class MermaidRenderer {
-  private panzoomInstances: Map<string, PanZoom> = new Map();
-  private renderQueue: string[] = [];
-  private isRendering = false;
-  private observer: IntersectionObserver | null = null;
-
-  constructor() {
-    this.initializeMermaid();
-    this.setupIntersectionObserver();
-  }
-
-  /**
-   * Initialize Mermaid with security settings
-   */
-  private initializeMermaid(): void {
-    mermaid.initialize({
-      startOnLoad: false,
-      securityLevel: 'strict',
-      maxTextSize: 50000,
-      maxEdges: 500,
-      theme: 'base',
-      themeVariables: {
-        // Default light theme variables to ensure text is visible
-        textColor: '#24292f',
-        tertiaryTextColor: '#24292f',
-        primaryTextColor: '#24292f',
-        lineColor: '#24292f',
-      },
-      flowchart: {
-        htmlLabels: false,
-        useMaxWidth: true,
-      },
-      sequence: {
-        useMaxWidth: true,
-      },
-      gantt: {
-        useMaxWidth: true,
-      },
-      er: {
-        useMaxWidth: true,
-      },
-    });
-
-    debug.info('MermaidRenderer', ' Initialized');
-  }
-
-  /**
-   * Set up Intersection Observer for lazy loading
-   */
-  private setupIntersectionObserver(): void {
-    if ('IntersectionObserver' in window) {
-      this.observer = new IntersectionObserver(
-        (entries) => {
-          entries.forEach((entry) => {
-            if (entry.isIntersecting) {
-              const container = entry.target as HTMLElement;
-              const id = container.id;
-              if (id && container.classList.contains('mermaid-pending')) {
-                this.renderDiagram(id).catch(debug.error);
-              }
-            }
-          });
-        },
-        {
-          rootMargin: '100px', // Pre-load when 100px away
-          threshold: 0.01,
-        }
-      );
-    }
-  }
-
-  /**
-   * Update Mermaid theme and re-render diagrams
-   */
-  updateTheme(config: MermaidThemeConfig): void {
-    debug.info('MermaidRenderer', `Updating theme to ${config.theme}`);
-
-    // Ensure ER diagram text colors are set correctly
-    const themeVars = {
-      ...config.themeVariables,
-      // Ensure tertiary text color matches text color for ER diagrams
-      tertiaryTextColor: config.themeVariables.tertiaryTextColor || config.themeVariables.textColor,
-    };
-
-    mermaid.initialize({
-      startOnLoad: false,
-      securityLevel: 'strict',
-      maxTextSize: 50000,
-      maxEdges: 500,
-      theme: config.theme,
-      themeVariables: themeVars,
-      flowchart: {
-        htmlLabels: false,
-        useMaxWidth: true,
-      },
-      sequence: {
-        useMaxWidth: true,
-      },
-      gantt: {
-        useMaxWidth: true,
-      },
-      er: {
-        useMaxWidth: true,
-      },
-    });
-
-    this.rerenderAll().catch((error) => {
-      debug.error('MermaidRenderer', 'Failed to re-render diagrams:', error);
-    });
-  }
-
-  /**
-   * Re-render all initialized diagrams
-   */
-  private async rerenderAll(): Promise<void> {
-    const diagrams = document.querySelectorAll('.mermaid-container');
-
-    for (const container of Array.from(diagrams)) {
-      const element = container as HTMLElement;
-      const id = element.id;
-
-      if (!id) continue;
-
-      // Check if it was previously rendered or had an error
-      if (
-        element.classList.contains('mermaid-ready') ||
-        element.classList.contains('mermaid-error')
-      ) {
-        // Clean up Panzoom
-        const panzoom = this.panzoomInstances.get(id);
-        if (panzoom) {
-          panzoom.dispose();
-          this.panzoomInstances.delete(id);
-        }
-
-        // Clean up keyboard listeners
-        const elementWithCleanup = element as { __keyboardCleanup?: () => void };
-        if (elementWithCleanup.__keyboardCleanup) {
-          elementWithCleanup.__keyboardCleanup();
-        }
-
-        // Reset state
-        element.classList.remove('mermaid-ready', 'mermaid-error');
-        element.classList.add('mermaid-pending');
-        element.innerHTML = ''; // Clear content
-
-        // Re-render
-        await this.renderDiagram(id);
-      }
-    }
-  }
-
-  /**
-   * Render all Mermaid diagrams in a container
-   */
-  async renderAll(container: HTMLElement): Promise<void> {
-    const diagrams = container.querySelectorAll('.mermaid-container.mermaid-pending');
-
-    for (const diagram of Array.from(diagrams)) {
-      const id = diagram.id;
-      if (id) {
-        // Use observer if available, otherwise render immediately
-        if (this.observer) {
-          this.observer.observe(diagram);
-        } else {
-          await this.renderDiagram(id);
-        }
-      }
-    }
-  }
-
-  /**
-   * Force-render all Mermaid diagrams in a container, bypassing lazy loading.
-   * Used by export/print flows where we must have every diagram rendered,
-   * regardless of scroll position.
-   */
-  async renderAllImmediate(container: HTMLElement): Promise<void> {
-    const diagrams = container.querySelectorAll('.mermaid-container');
-
-    for (const diagram of Array.from(diagrams)) {
-      const id = diagram.id;
-      if (id) {
-        await this.renderDiagram(id);
-      }
-    }
-  }
-
-  /**
-   * Render a single Mermaid diagram
-   */
-  async renderDiagram(containerId: string): Promise<void> {
-    const container = document.getElementById(containerId);
-    if (!container) {
-      debug.error('MermaidRenderer', `Container not found: ${containerId}`);
-      return;
-    }
-
-    // Check if already rendered (either with wrapper or direct SVG from cache)
-    if (container.querySelector('.mermaid-rendered') || container.querySelector('svg')) {
-      debug.debug('MermaidRenderer', `Container ${containerId} already has rendered content`);
-      return;
-    }
-
-    // Get mermaid code from global registry or data attribute (fallback for lazy sections)
-    const windowWithRegistry = window as { __MDVIEW_MERMAID_CODE__?: Map<string, string> };
-    const registry = windowWithRegistry.__MDVIEW_MERMAID_CODE__;
-    let code = registry?.get(containerId)?.trim();
-
-    // Fallback: Check if code was stored in data attribute (from previous render)
-    if (!code) {
-      code = container.getAttribute('data-mermaid-code') || '';
-    }
-
-    if (!code) {
-      // If there's no code and no SVG, this is likely a cache issue where
-      // the mermaid code was never stored. Log as warning, not error.
-      debug.warn(
-        'MermaidRenderer',
-        `No code found for ${containerId} - diagram may need re-rendering from source`
-      );
-      return;
-    }
-
-    debug.debug('MermaidRenderer', `Container ${containerId}: code exists, length: ${code.length}`);
-
-    // Store code in the container as data attribute for potential re-renders
-    container.setAttribute('data-mermaid-code', code);
-
-    // Remove from registry now that we've stored it in DOM
-    // (Keep it in registry too in case of re-renders before DOM update)
-    // registry.delete(containerId); // Don't delete - keep for lazy sections
-
-    // Add to queue if currently rendering
-    if (this.isRendering) {
-      if (!this.renderQueue.includes(containerId)) {
-        this.renderQueue.push(containerId);
-      }
-      return;
-    }
-
-    this.isRendering = true;
-
-    try {
-      // Validate syntax
-      const validation = await this.validateSyntax(code);
-      if (!validation.valid) {
-        this.showError(container, validation.error || 'Invalid Mermaid syntax');
-        return;
-      }
-
-      // Generate unique ID for SVG
-      const svgId = `mermaid-svg-${containerId}`;
-
-      // Render with timeout and proper cleanup
-      let timeoutId: ReturnType<typeof setTimeout>;
-      const renderPromise = mermaid.render(svgId, code);
-      const timeoutPromise = new Promise<never>((_, reject) => {
-        timeoutId = setTimeout(() => reject(new Error('Render timeout')), 5000);
-      });
-
-      let result: { svg: string };
-      try {
-        result = await Promise.race([renderPromise, timeoutPromise]);
-        clearTimeout(timeoutId!);
-      } catch (error) {
-        clearTimeout(timeoutId!);
-        // Clean up any orphaned DOM elements that mermaid.render() may have created
-        // mermaid creates temporary SVG elements with the svgId during rendering
-        const orphanedSvg = document.getElementById(svgId);
-        if (orphanedSvg) {
-          orphanedSvg.remove();
-        }
-        throw error;
-      }
-
-      // Clear loading state
-      container.innerHTML = '';
-
-      // Create wrapper for diagram
-      const wrapper = document.createElement('div');
-      wrapper.className = 'mermaid-rendered';
-      wrapper.innerHTML = result.svg;
-
-      container.appendChild(wrapper);
-
-      // Add controls
-      this.addControls(container);
-
-      // Initialize Panzoom
-      const svg = wrapper.querySelector('svg');
-      if (svg) {
-        this.initializePanzoom(container, svg as SVGElement);
-      }
-
-      // Mark as rendered
-      container.classList.remove('mermaid-pending');
-      container.classList.add('mermaid-ready');
-
-      // Unobserve if using IntersectionObserver
-      if (this.observer) {
-        this.observer.unobserve(container);
-      }
-
-      debug.info('MermaidRenderer', ` Rendered diagram: ${containerId}`);
-    } catch (error) {
-      debug.error('MermaidRenderer', `[MermaidRenderer] Error rendering ${containerId}:`, error);
-      this.showError(container, error instanceof Error ? error.message : String(error));
-    } finally {
-      this.isRendering = false;
-
-      // Process queue
-      if (this.renderQueue.length > 0) {
-        const nextId = this.renderQueue.shift();
-        if (nextId) {
-          this.renderDiagram(nextId).catch(debug.error);
-        }
-      }
-    }
-  }
-
-  /**
-   * Validate Mermaid syntax
-   */
-  private async validateSyntax(code: string): Promise<{ valid: boolean; error?: string }> {
-    try {
-      // Basic validation - check for empty or malformed code
-      if (!code.trim()) {
-        return { valid: false, error: 'Empty diagram code' };
-      }
-
-      // Check size limits
-      if (code.length > 50000) {
-        return { valid: false, error: 'Diagram code exceeds size limit (50,000 characters)' };
-      }
-
-      // Try to parse (Mermaid doesn't provide a separate parse method)
-      await mermaid.parse(code);
-
-      return { valid: true };
-    } catch (error) {
-      return {
-        valid: false,
-        error: error instanceof Error ? error.message : 'Parse error',
-      };
-    }
-  }
-
-  /**
-   * Initialize Panzoom for a diagram
-   */
-  private initializePanzoom(container: HTMLElement, svg: SVGElement): void {
-    debug.debug('MermaidRenderer', `initializePanzoom() called for container: ${container.id}`);
-
-    const panzoomInstance = Panzoom(svg, {
-      maxZoom: 10,
-      minZoom: 0.1,
-      smoothScroll: false,
-      bounds: true,
-      boundsPadding: 0.1,
-    });
-
-    debug.debug('MermaidRenderer', `  Panzoom instance created, storing with ID: ${container.id}`);
-
-    // Store instance
-    this.panzoomInstances.set(container.id, panzoomInstance);
-
-    const initialTransform = panzoomInstance.getTransform();
-    debug.debug(
-      'MermaidRenderer',
-      `  Initial transform: scale=${initialTransform.scale.toFixed(2)}, pos=(${initialTransform.x.toFixed(1)}, ${initialTransform.y.toFixed(1)})`
-    );
-
-    // Listen for transform changes to debug unexpected resets
-    svg.addEventListener('panzoomchange', (() => {
-      const transform = panzoomInstance.getTransform();
-      debug.debug(
-        'MermaidRenderer',
-        `  Transform changed for ${container.id}: scale=${transform.scale.toFixed(2)}, pos=(${transform.x.toFixed(1)}, ${transform.y.toFixed(1)})`
-      );
-    }) as EventListener);
-
-    // Add mouse wheel zoom
-    svg.parentElement?.addEventListener('wheel', (e: WheelEvent) => {
-      if (e.ctrlKey || e.metaKey) {
-        e.preventDefault();
-        // Manual zoom calculation
-        const delta = e.deltaY > 0 ? 0.9 : 1.1;
-        const transform = panzoomInstance.getTransform();
-        panzoomInstance.zoomTo(e.clientX, e.clientY, transform.scale * delta);
-      }
-    });
-
-    // Add keyboard controls
-    this.setupKeyboardControls(container, panzoomInstance);
-  }
-
-  /**
-   * Setup keyboard controls for diagram
-   */
-  private setupKeyboardControls(
-    container: HTMLElement,
-    panzoom: PanZoom,
-    maximizeCallback?: () => void
-  ): void {
-    const handler = (e: KeyboardEvent) => {
-      // Only handle if container is focused or hovered
-      if (!container.matches(':hover, :focus-within')) {
-        return;
-      }
-
-      switch (e.key) {
-        case '+':
-        case '=':
-          e.preventDefault();
-          {
-            const transform = panzoom.getTransform();
-            panzoom.zoomTo(0, 0, transform.scale * 1.2);
-          }
-          break;
-        case '-':
-          e.preventDefault();
-          {
-            const transform = panzoom.getTransform();
-            panzoom.zoomTo(0, 0, transform.scale * 0.8);
-          }
-          break;
-        case '0':
-          e.preventDefault();
-          panzoom.moveTo(0, 0);
-          panzoom.zoomAbs(0, 0, 1);
-          break;
-        case 'f':
-          e.preventDefault();
-          this.fitToView(container.id);
-          break;
-        case 'm':
-          e.preventDefault();
-          // If in maximized view (callback provided), close instead of maximize
-          if (maximizeCallback) {
-            maximizeCallback();
-          } else {
-            this.maximize(container.id);
-          }
-          break;
-        case 'e':
-          e.preventDefault();
-          void this.exportSVG(container.id);
-          break;
-        case 'ArrowUp':
-          if (e.shiftKey) {
-            e.preventDefault();
-            panzoom.moveTo(panzoom.getTransform().x, panzoom.getTransform().y - 50);
-          }
-          break;
-        case 'ArrowDown':
-          if (e.shiftKey) {
-            e.preventDefault();
-            panzoom.moveTo(panzoom.getTransform().x, panzoom.getTransform().y + 50);
-          }
-          break;
-        case 'ArrowLeft':
-          if (e.shiftKey) {
-            e.preventDefault();
-            panzoom.moveTo(panzoom.getTransform().x - 50, panzoom.getTransform().y);
-          }
-          break;
-        case 'ArrowRight':
-          if (e.shiftKey) {
-            e.preventDefault();
-            panzoom.moveTo(panzoom.getTransform().x + 50, panzoom.getTransform().y);
-          }
-          break;
-      }
-    };
-
-    document.addEventListener('keydown', handler);
-
-    // Store cleanup function
-    const containerWithCleanup = container as { __keyboardCleanup?: () => void };
-    containerWithCleanup.__keyboardCleanup = () => {
-      document.removeEventListener('keydown', handler);
-    };
-  }
-
-  /**
-   * Add control buttons to diagram
-   */
-  private addControls(container: HTMLElement): void {
-    const controls = document.createElement('div');
-    controls.className = 'mermaid-controls';
-
-    const buttons = [
-      { label: '+', title: 'Zoom In (+)', action: () => this.zoomIn(container.id) },
-      { label: '−', title: 'Zoom Out (-)', action: () => this.zoomOut(container.id) },
-      { label: '⊡', title: 'Reset to 100% (0)', action: () => this.resetZoom(container.id) },
-      { label: '⤢', title: 'Fit to View (F)', action: () => this.fitToView(container.id) },
-      { label: '⛶', title: 'Maximize (M)', action: () => this.maximize(container.id) },
-      { label: '↓', title: 'Export SVG (E)', action: () => this.exportSVG(container.id) },
-    ];
-
-    buttons.forEach(({ label, title, action }) => {
-      const button = document.createElement('button');
-      button.className = 'mermaid-control-button';
-      button.textContent = label;
-      button.title = title;
-      button.setAttribute('aria-label', title);
-      button.addEventListener('click', action);
-      controls.appendChild(button);
-    });
-
-    container.appendChild(controls);
-  }
-
-  /**
-   * Re-attach event listeners to cloned control buttons
-   * (cloneNode doesn't copy event listeners)
-   */
-  private reattachControls(container: HTMLElement, closeMaximizeCallback?: () => void): void {
-    const controls = container.querySelector('.mermaid-controls');
-    if (!controls) return;
-
-    const buttons = controls.querySelectorAll('.mermaid-control-button');
-
-    // Define actions for each button (same order as addControls)
-    const actions = [
-      () => this.zoomIn(container.id),
-      () => this.zoomOut(container.id),
-      () => this.resetZoom(container.id),
-      () => this.fitToView(container.id),
-      closeMaximizeCallback ? closeMaximizeCallback : () => this.maximize(container.id), // In maximized view, this closes instead
-      () => this.exportSVG(container.id),
-    ];
-
-    buttons.forEach((button, index) => {
-      // Remove old listeners by cloning the button (clean slate)
-      const newButton = button.cloneNode(true) as HTMLElement;
-      button.parentNode?.replaceChild(newButton, button);
-
-      // Attach new listener
-      if (actions[index]) {
-        newButton.addEventListener('click', actions[index]);
-      }
-    });
-  }
-
-  /**
-   * Zoom in
-   */
-  zoomIn(containerId: string): void {
-    const container = document.getElementById(containerId);
-    const panzoom = this.panzoomInstances.get(containerId);
-    if (panzoom && container) {
-      const transform = panzoom.getTransform();
-      const containerRect = container.getBoundingClientRect();
-      // Zoom toward center of visible area
-      const centerX = containerRect.width / 2;
-      const centerY = containerRect.height / 2;
-      panzoom.smoothZoomAbs(centerX, centerY, transform.scale * 1.2);
-    }
-  }
-
-  /**
-   * Zoom out
-   */
-  zoomOut(containerId: string): void {
-    const container = document.getElementById(containerId);
-    const panzoom = this.panzoomInstances.get(containerId);
-    if (panzoom && container) {
-      const transform = panzoom.getTransform();
-      const containerRect = container.getBoundingClientRect();
-      // Zoom toward center of visible area
-      const centerX = containerRect.width / 2;
-      const centerY = containerRect.height / 2;
-      panzoom.smoothZoomAbs(centerX, centerY, transform.scale * 0.8);
-    }
-  }
-
-  /**
-   * Reset zoom to 1:1 scale and center
-   */
-  resetZoom(containerId: string): void {
-    const container = document.getElementById(containerId);
-    const panzoom = this.panzoomInstances.get(containerId);
-
-    if (!container || !panzoom) return;
-
-    const svg = container.querySelector('svg');
-    if (!svg) return;
-
-    // Reset to 1:1 scale and identity translation
-    // The browser's SVG viewBox + width=100% handles the fitting naturally
-    panzoom.zoomAbs(0, 0, 1);
-    panzoom.moveTo(0, 0);
-
-    debug.debug('MermaidRenderer', `Reset zoom for ${containerId}`);
-  }
-
-  /**
-   * Fit diagram to view (centered)
-   */
-  fitToView(containerId: string): void {
-    debug.debug('MermaidRenderer', `Fit to view for: ${containerId}`);
-    // "Fit to view" in this context means resetting to the natural
-    // layout where the diagram fits within the container (width=100%)
-    this.resetZoom(containerId);
-  }
-
-  /**
-   * Maximize diagram (fullscreen mode)
-   */
-  maximize(containerId: string): void {
-    debug.debug('MermaidRenderer', `maximize() called for: ${containerId}`);
-
-    const container = document.getElementById(containerId);
-    if (!container) {
-      debug.error('MermaidRenderer', `Container not found: ${containerId}`);
-      return;
-    }
-
-    debug.debug('MermaidRenderer', `  Creating maximize overlay...`);
-
-    // Create overlay
-    const overlay = document.createElement('div');
-    overlay.className = 'mermaid-maximize-overlay';
-    overlay.setAttribute('tabindex', '0');
-
-    // Clone diagram
-    const clone = container.cloneNode(true) as HTMLElement;
-
-    // Give clone a unique ID for panzoom tracking
-    const maximizedId = `${containerId}-maximized`;
-    clone.id = maximizedId;
-    clone.classList.add('maximized');
-
-    debug.debug('MermaidRenderer', `  Cloned diagram with ID: ${maximizedId}`);
-
-    // Make the clone expand to fill available space
-    clone.style.width = '90vw';
-    clone.style.height = '90vh';
-    clone.style.maxWidth = '90vw';
-    clone.style.maxHeight = '90vh';
-    clone.style.display = 'flex';
-    clone.style.alignItems = 'center';
-    clone.style.justifyContent = 'center';
-
-    debug.debug('MermaidRenderer', `  Appending to DOM...`);
-    overlay.appendChild(clone);
-    document.body.appendChild(overlay);
-
-    const cleanup = () => {
-      // Clean up panzoom instance
-      const clonePanzoom = this.panzoomInstances.get(maximizedId);
-      if (clonePanzoom) {
-        clonePanzoom.dispose();
-        this.panzoomInstances.delete(maximizedId);
-      }
-
-      // Clean up keyboard handlers
-      const cloneWithCleanup = clone as { __keyboardCleanup?: () => void };
-      if (cloneWithCleanup.__keyboardCleanup) {
-        cloneWithCleanup.__keyboardCleanup();
-      }
-
-      // Remove overlay from DOM
-      if (document.body.contains(overlay)) {
-        document.body.removeChild(overlay);
-      }
-    };
-
-    // Re-attach event listeners to cloned control buttons
-    this.reattachControls(clone, cleanup);
-
-    // Add close button
-    const closeButton = document.createElement('button');
-    closeButton.className = 'mermaid-close-button';
-    closeButton.textContent = '✕';
-    closeButton.title = 'Close (Esc)';
-    closeButton.setAttribute('aria-label', 'Close maximize mode');
-    closeButton.addEventListener('click', cleanup);
-    overlay.appendChild(closeButton);
-
-    // Re-initialize Panzoom for maximized instance
-    const svg = clone.querySelector('svg');
-    if (svg) {
-      debug.debug('MermaidRenderer', `  Found SVG, initializing panzoom...`);
-
-      const svgElement = svg as SVGElement;
-      // Make SVG scale to fit
-      svgElement.style.width = '100%';
-      svgElement.style.height = '100%';
-      svgElement.style.maxWidth = '100%';
-      svgElement.style.maxHeight = '100%';
-
-      this.initializePanzoom(clone, svgElement);
-      debug.debug('MermaidRenderer', `  Panzoom initialized for ${maximizedId}`);
-
-      // Re-setup keyboard controls for the cloned instance
-      const clonePanzoom = this.panzoomInstances.get(maximizedId);
-      if (clonePanzoom) {
-        this.setupKeyboardControls(clone, clonePanzoom, cleanup);
-
-        // Center logic: Identity transform + moveTo(0,0)
-        // Since SVG is 100% width/height and preserves aspect ratio,
-        // this will center the content in the 90vw/90vh container
-        clonePanzoom.zoomAbs(0, 0, 1);
-        clonePanzoom.moveTo(0, 0);
-
-        debug.debug('MermaidRenderer', `  Maximized view centered`);
-      }
-    } else {
-      debug.error('MermaidRenderer', `  No SVG found in cloned container!`);
-    }
-
-    // Add ESC key handler
-    const escHandler = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        cleanup();
-        document.removeEventListener('keydown', escHandler);
-      }
-    };
-    document.addEventListener('keydown', escHandler);
-
-    // Click outside to close
-    overlay.addEventListener('click', (e) => {
-      if (e.target === overlay) {
-        cleanup();
-        document.removeEventListener('keydown', escHandler);
-      }
-    });
-
-    // Focus overlay for accessibility
-    overlay.focus();
-  }
-
-  /**
-   * Export diagram as SVG
-   */
-  exportSVG(containerId: string): void {
-    const container = document.getElementById(containerId);
-    if (!container) return;
-
-    const svg = container.querySelector('svg');
-    if (!svg) {
-      debug.error('MermaidRenderer', ' No SVG found for export');
-      return;
-    }
-
-    try {
-      // Clone and clean SVG
-      const clone = svg.cloneNode(true) as SVGElement;
-
-      // Remove Panzoom transformations
-      clone.removeAttribute('style');
-      clone.querySelectorAll('[style]').forEach((el) => {
-        el.removeAttribute('style');
-      });
-
-      // Add XML declaration
-      const serializer = new XMLSerializer();
-      const svgString =
-        '<?xml version="1.0" encoding="UTF-8"?>\n' + serializer.serializeToString(clone);
-
-      // Create blob and download
-      const blob = new Blob([svgString], { type: 'image/svg+xml' });
-      const url = URL.createObjectURL(blob);
-
-      const link = document.createElement('a');
-      link.href = url;
-      link.download = `mermaid-${containerId}.svg`;
-      document.body.appendChild(link);
-      link.click();
-      document.body.removeChild(link);
-
-      URL.revokeObjectURL(url);
-
-      debug.info('MermaidRenderer', ` Exported SVG: ${containerId}`);
-
-      // Show success notification
-      this.showNotification(container, 'SVG exported successfully');
-    } catch (error) {
-      debug.error('MermaidRenderer', ' Export error:', error);
-      this.showNotification(container, 'Export failed', true);
-    }
-  }
-
-  /**
-   * Show error in container
-   */
-  private showError(container: HTMLElement, message: string): void {
-    const code = container.getAttribute('data-mermaid-code') || '';
-
-    container.innerHTML = `
-      <div class="mermaid-error" role="alert">
-        <h4>Mermaid Diagram Error</h4>
-        <p>${this.escapeHtml(message)}</p>
-        <details>
-          <summary>Diagram Code</summary>
-          <pre><code>${this.escapeHtml(code)}</code></pre>
-        </details>
-        <p><a href="https://mermaid.js.org/intro/" target="_blank" rel="noopener noreferrer">View Mermaid Documentation</a></p>
-        <button class="mermaid-copy-error">Copy Error</button>
-      </div>
-    `;
-
-    // Add copy error button handler
-    const copyButton = container.querySelector('.mermaid-copy-error');
-    if (copyButton) {
-      copyButton.addEventListener('click', () => {
-        void (async () => {
-          try {
-            await navigator.clipboard.writeText(`${message}\n\n${code}`);
-            (copyButton as HTMLElement).textContent = '✓ Copied';
-          } catch (error) {
-            debug.error('MermaidRenderer', 'Failed to copy error:', error);
-          }
-        })();
-      });
-    }
-
-    container.classList.remove('mermaid-pending');
-    container.classList.add('mermaid-error');
-  }
-
-  /**
-   * Show notification toast
-   */
-  private showNotification(container: HTMLElement, message: string, isError = false): void {
-    const toast = document.createElement('div');
-    toast.className = `mermaid-notification ${isError ? 'error' : 'success'}`;
-    toast.textContent = message;
-    toast.setAttribute('role', 'status');
-    toast.setAttribute('aria-live', 'polite');
-
-    container.appendChild(toast);
-
-    setTimeout(() => {
-      toast.classList.add('fade-out');
-      setTimeout(() => {
-        container.removeChild(toast);
-      }, 300);
-    }, 2000);
-  }
-
-  /**
-   * Escape HTML
-   */
-  private escapeHtml(text: string): string {
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-  }
-
-  /**
-   * Clean up resources
-   */
-  cleanup(): void {
-    // Dispose all panzoom instances
-    this.panzoomInstances.forEach((panzoom) => {
-      panzoom.dispose();
-    });
-    this.panzoomInstances.clear();
-
-    // Disconnect observer
-    if (this.observer) {
-      this.observer.disconnect();
-      this.observer = null;
-    }
-
-    debug.info('MermaidRenderer', ' Cleaned up');
-  }
-}
-
-// Export singleton
-export const mermaidRenderer = new MermaidRenderer();
+export * from '../../packages/core/src/renderers/mermaid-renderer';
diff --git a/src/renderers/syntax-highlighter.ts b/src/renderers/syntax-highlighter.ts
index fb22630..1a8969a 100644
--- a/src/renderers/syntax-highlighter.ts
+++ b/src/renderers/syntax-highlighter.ts
@@ -1,356 +1 @@
-/**
- * Syntax Highlighter
- * Applies syntax highlighting to code blocks using Highlight.js
- */
-
-import hljs from 'highlight.js/lib/core';
-import type { LanguageFn } from 'highlight.js';
-import { debug } from '../utils/debug-logger';
-
-// Import common languages immediately
-import javascript from 'highlight.js/lib/languages/javascript';
-import typescript from 'highlight.js/lib/languages/typescript';
-import python from 'highlight.js/lib/languages/python';
-import bash from 'highlight.js/lib/languages/bash';
-import json from 'highlight.js/lib/languages/json';
-
-export interface HighlightResult {
-  html: string;
-  language: string;
-  relevance: number;
-}
-
-export interface DetectionResult {
-  language: string;
-  relevance: number;
-  secondBest?: {
-    language: string;
-    relevance: number;
-  };
-}
-
-/**
- * Syntax Highlighter Class
- */
-export class SyntaxHighlighter {
-  private loadedLanguages: Set<string> = new Set();
-  private languageAliases: Map<string, string> = new Map([
-    ['js', 'javascript'],
-    ['ts', 'typescript'],
-    ['py', 'python'],
-    ['sh', 'bash'],
-    ['yml', 'yaml'],
-    ['md', 'markdown'],
-  ]);
-
-  // Map of language module loaders
-  private languageModules: Record<string, () => Promise<{ default: LanguageFn }>> = {
-    go: () => import('highlight.js/lib/languages/go'),
-    rust: () => import('highlight.js/lib/languages/rust'),
-    java: () => import('highlight.js/lib/languages/java'),
-    cpp: () => import('highlight.js/lib/languages/cpp'),
-    c: () => import('highlight.js/lib/languages/c'),
-    csharp: () => import('highlight.js/lib/languages/csharp'),
-    ruby: () => import('highlight.js/lib/languages/ruby'),
-    php: () => import('highlight.js/lib/languages/php'),
-    sql: () => import('highlight.js/lib/languages/sql'),
-    yaml: () => import('highlight.js/lib/languages/yaml'),
-    xml: () => import('highlight.js/lib/languages/xml'),
-    html: () => import('highlight.js/lib/languages/xml'),
-    css: () => import('highlight.js/lib/languages/css'),
-    scss: () => import('highlight.js/lib/languages/scss'),
-    markdown: () => import('highlight.js/lib/languages/markdown'),
-    dockerfile: () => import('highlight.js/lib/languages/dockerfile'),
-    nginx: () => import('highlight.js/lib/languages/nginx'),
-    apache: () => import('highlight.js/lib/languages/apache'),
-    perl: () => import('highlight.js/lib/languages/perl'),
-    r: () => import('highlight.js/lib/languages/r'),
-    swift: () => import('highlight.js/lib/languages/swift'),
-    kotlin: () => import('highlight.js/lib/languages/kotlin'),
-    scala: () => import('highlight.js/lib/languages/scala'),
-    haskell: () => import('highlight.js/lib/languages/haskell'),
-    lua: () => import('highlight.js/lib/languages/lua'),
-    vim: () => import('highlight.js/lib/languages/vim'),
-    diff: () => import('highlight.js/lib/languages/diff'),
-    makefile: () => import('highlight.js/lib/languages/makefile'),
-    ini: () => import('highlight.js/lib/languages/ini'),
-    properties: () => import('highlight.js/lib/languages/properties'),
-  };
-
-  constructor() {
-    // Register common languages immediately
-    hljs.registerLanguage('javascript', javascript);
-    hljs.registerLanguage('typescript', typescript);
-    hljs.registerLanguage('python', python);
-    hljs.registerLanguage('bash', bash);
-    hljs.registerLanguage('json', json);
-
-    this.loadedLanguages.add('javascript');
-    this.loadedLanguages.add('typescript');
-    this.loadedLanguages.add('python');
-    this.loadedLanguages.add('bash');
-    this.loadedLanguages.add('json');
-
-    // Configure highlight.js
-    hljs.configure({
-      classPrefix: 'hljs-',
-      ignoreUnescapedHTML: true,
-    });
-  }
-
-  /**
-   * Highlight code with specified language
-   */
-  async highlight(code: string, language: string): Promise<HighlightResult> {
-    // Normalize language name
-    const normalizedLang = this.normalizeLanguage(language);
-
-    // Load language if not already loaded
-    await this.loadLanguage(normalizedLang);
-
-    try {
-      // Check if language is available
-      if (hljs.getLanguage(normalizedLang)) {
-        const result = hljs.highlight(code, {
-          language: normalizedLang,
-          ignoreIllegals: true,
-        });
-
-        return {
-          html: result.value,
-          language: normalizedLang,
-          relevance: result.relevance || 0,
-        };
-      } else {
-        // Fallback: auto-detect
-        return this.highlightAuto(code);
-      }
-    } catch (error) {
-      console.error(`[SyntaxHighlighter] Error highlighting ${normalizedLang}:`, error);
-      // Return unformatted code
-      return {
-        html: this.escapeHtml(code),
-        language: 'plaintext',
-        relevance: 0,
-      };
-    }
-  }
-
-  /**
-   * Auto-detect and highlight code
-   */
-  highlightAuto(code: string): HighlightResult {
-    try {
-      const result = hljs.highlightAuto(code);
-      return {
-        html: result.value,
-        language: result.language || 'plaintext',
-        relevance: result.relevance || 0,
-      };
-    } catch (error) {
-      debug.error('SyntaxHighlighter', ' Auto-detect error:', error);
-      return {
-        html: this.escapeHtml(code),
-        language: 'plaintext',
-        relevance: 0,
-      };
-    }
-  }
-
-  /**
-   * Detect code language
-   */
-  detectLanguage(code: string): DetectionResult {
-    try {
-      const result = hljs.highlightAuto(code);
-      return {
-        language: result.language || 'plaintext',
-        relevance: result.relevance || 0,
-        secondBest: result.secondBest
-          ? {
-              language: result.secondBest.language || 'plaintext',
-              relevance: result.secondBest.relevance || 0,
-            }
-          : undefined,
-      };
-    } catch (error) {
-      debug.error('SyntaxHighlighter', ' Language detection error:', error);
-      return {
-        language: 'plaintext',
-        relevance: 0,
-      };
-    }
-  }
-
-  /**
-   * Load language grammar on-demand
-   */
-  async loadLanguage(language: string): Promise<void> {
-    // Check if already loaded
-    if (this.loadedLanguages.has(language)) {
-      return;
-    }
-
-    // Check if we have a loader for this language
-    const loader = this.languageModules[language];
-    if (!loader) {
-      console.warn(`[SyntaxHighlighter] No loader for language: ${language}`);
-      return;
-    }
-
-    try {
-      const module = await loader();
-      hljs.registerLanguage(language, module.default);
-      this.loadedLanguages.add(language);
-      debug.log('SyntaxHighlighter', ` Loaded language: ${language}`);
-    } catch (error) {
-      console.error(`[SyntaxHighlighter] Failed to load language ${language}:`, error);
-    }
-  }
-
-  /**
-   * Get list of supported languages
-   */
-  getSupportedLanguages(): string[] {
-    return [...this.loadedLanguages, ...Object.keys(this.languageModules)].sort();
-  }
-
-  /**
-   * Check if language is supported
-   */
-  isLanguageSupported(language: string): boolean {
-    const normalized = this.normalizeLanguage(language);
-    return this.loadedLanguages.has(normalized) || normalized in this.languageModules;
-  }
-
-  /**
-   * Highlight all code blocks in a container
-   */
-  async highlightAll(container: HTMLElement): Promise<void> {
-    const codeBlocks = container.querySelectorAll('pre code[class*="language-"]');
-
-    for (const block of Array.from(codeBlocks)) {
-      const code = block.textContent || '';
-      const classNames = block.className.split(' ');
-      const langClass = classNames.find((cls) => cls.startsWith('language-'));
-
-      if (langClass) {
-        const lang = langClass.replace('language-', '');
-
-        // Check if code block is large (> 1000 lines)
-        if (code.split('\n').length > 1000) {
-          debug.log('SyntaxHighlighter', ` Large code block detected, highlighting may take time`);
-        }
-
-        try {
-          const result = await this.highlight(code, lang);
-          block.innerHTML = result.html;
-          block.classList.add('hljs', 'highlighted');
-          block.setAttribute('data-language', result.language);
-        } catch (error) {
-          debug.error('SyntaxHighlighter', ' Error highlighting block:', error);
-        }
-      }
-    }
-  }
-
-  /**
-   * Highlight visible code blocks using Intersection Observer
-   */
-  highlightVisible(container: HTMLElement): void {
-    const codeBlocks = container.querySelectorAll('pre code[class*="language-"]:not(.highlighted)');
-
-    if ('IntersectionObserver' in window) {
-      const observer = new IntersectionObserver(
-        (entries) => {
-          entries.forEach((entry) => {
-            if (entry.isIntersecting) {
-              const block = entry.target as HTMLElement;
-              const code = block.textContent || '';
-              const classNames = block.className.split(' ');
-              const langClass = classNames.find((cls) => cls.startsWith('language-'));
-
-              if (langClass) {
-                const lang = langClass.replace('language-', '');
-
-                void (async () => {
-                  try {
-                    const result = await this.highlight(code, lang);
-                    block.innerHTML = result.html;
-                    block.classList.add('hljs', 'highlighted');
-                    block.setAttribute('data-language', result.language);
-                  } catch (error) {
-                    debug.error('SyntaxHighlighter', ' Error highlighting block:', error);
-                  }
-                })();
-              }
-
-              observer.unobserve(block);
-            }
-          });
-        },
-        {
-          rootMargin: '100px', // Pre-load when 100px away
-          threshold: 0.01,
-        }
-      );
-
-      codeBlocks.forEach((block) => observer.observe(block));
-    } else {
-      // Fallback: highlight all immediately
-      this.highlightAll(container).catch((error) =>
-        debug.error('SyntaxHighlighter', 'Catch error:', error)
-      );
-    }
-  }
-
-  /**
-   * Normalize language name
-   */
-  private normalizeLanguage(language: string): string {
-    const lower = language.toLowerCase();
-    return this.languageAliases.get(lower) || lower;
-  }
-
-  /**
-   * Escape HTML
-   */
-  private escapeHtml(text: string): string {
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-  }
-
-  /**
-   * Set syntax theme (load CSS)
-   * Note: Dynamic CSS imports don't work in Chrome extensions, so we rely on
-   * the theme engine's CSS custom properties for styling instead.
-   */
-  setTheme(themeName: string): void {
-    // In Chrome extensions, dynamic CSS imports with ?inline don't work
-    // The theme engine applies CSS custom properties that style the hljs classes
-    // So we just log and skip the highlight.js theme loading
-    debug.log(
-      'SyntaxHighlighter',
-      `Syntax theme ${themeName} will be styled via theme engine CSS custom properties`
-    );
-
-    // Note: The .hljs-* classes are styled by our theme system through CSS variables
-    // defined in src/content/content.css and theme files
-  }
-}
-
-// Export singleton
-export const syntaxHighlighter = new SyntaxHighlighter();
-
-// Theme mapping for document themes
-export const SYNTAX_THEME_MAP: Record<string, string> = {
-  'github-light': 'github',
-  'github-dark': 'github-dark',
-  'catppuccin-latte': 'github', // Fallback to github for now
-  'catppuccin-frappe': 'github-dark',
-  'catppuccin-macchiato': 'github-dark',
-  'catppuccin-mocha': 'github-dark',
-  monokai: 'monokai',
-  'monokai-pro': 'monokai',
-};
+export * from '../../packages/core/src/renderers/syntax-highlighter';

From 306ca2179df4d5c58c23de72e44b6c5d039a3d69 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 09:13:55 -0400
Subject: [PATCH 23/26] refactor(core): add barrel exports for TOC renderer,
 lazy section renderer, and comment UI

---
 packages/core/src/index.ts | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 654bee1..ea3c47c 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -33,6 +33,9 @@ export { parseComments } from './comments/comment-parser';
 // Comment manager
 export { CommentManager } from './comments/comment-manager';
 export type { CommentManagerAdapters } from './comments/comment-manager';
+// Comment UI
+export { CommentHighlighter } from './comments/comment-highlight';
+export { CommentUI } from './comments/comment-ui';
 // Context & utilities
 export * from './comments/comment-context';
 export * from './comments/source-position-map';
@@ -62,7 +65,7 @@ export { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extract
 export type { FrontmatterResult } from './frontmatter-extractor';
 
 // Debug logger
-export { DebugLogger, createDebugLogger, createDebug } from './utils/debug-logger';
+export { DebugLogger, createDebugLogger, createDebug, debug } from './utils/debug-logger';
 export type { DebugHelpers } from './utils/debug-logger';
 
 // Theme engine
@@ -86,6 +89,13 @@ export { DOCXGenerator } from './utils/docx-generator';
 export { PDFGenerator } from './utils/pdf-generator';
 export { ExportController } from './export-controller';
 
+// UI
+export { TocRenderer } from './ui/toc-renderer';
+
+// Lazy section renderer
+export { LazySectionRenderer } from './lazy-section-renderer';
+export type { LazySectionOptions } from './lazy-section-renderer';
+
 // Platform adapters
 export * from './adapters';
 

From f0253d01124f8c49ed5173abcec7fc2b9c71a011 Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 09:52:19 -0400
Subject: [PATCH 24/26] refactor: move Chrome extension to packages/chrome-ext

---
 package-lock.json                             |  27 ++
 package.json                                  |  14 +-
 packages/chrome-ext/package.json              |  13 +
 .../chrome-ext/public}/icons/icon128.png      | Bin
 .../chrome-ext/public}/icons/icon128.svg      |   0
 .../chrome-ext/public}/icons/icon16.png       | Bin
 .../chrome-ext/public}/icons/icon16.svg       |   0
 .../chrome-ext/public}/icons/icon32.png       | Bin
 .../chrome-ext/public}/icons/icon32.svg       |   0
 .../chrome-ext/public}/icons/icon48.png       | Bin
 .../chrome-ext/public}/icons/icon48.svg       |   0
 .../chrome-ext/public}/manifest.json          |   0
 .../chrome-ext/scripts}/fix-manifest.js       |   0
 .../chrome-ext/scripts}/generate-icons.cjs    |   0
 .../chrome-ext/scripts}/generate-icons.js     |   0
 .../chrome-ext/scripts}/svg-to-png.cjs        |   0
 .../scripts}/update-manifest-version.js       |   0
 .../src}/background/service-worker.ts         |  24 +-
 .../src}/comments/comment-manager.ts          |  12 +-
 .../chrome-ext/src}/content/content-script.ts |  18 +-
 .../chrome-ext/src}/content/content.css       |   0
 .../chrome-ext/src}/core/render-pipeline.ts   |   5 +-
 .../chrome-ext/src}/core/theme-engine.ts      |   8 +-
 .../chrome-ext/src}/native-host/host-logic.ts |  13 +-
 .../chrome-ext/src}/native-host/manifest.json |   0
 .../chrome-ext/src}/options/options.css       |   0
 .../chrome-ext/src}/options/options.html      |   0
 .../chrome-ext/src}/options/options.ts        |   4 +-
 .../chrome-ext/src}/popup/popup.css           |   0
 .../chrome-ext/src}/popup/popup.html          |   0
 .../chrome-ext/src}/popup/popup.ts            |   2 +-
 .../chrome-ext/src}/ui/export-ui.ts           |  16 +-
 .../chrome-ext/src}/utils/debug-logger.ts     |   5 +-
 .../chrome-ext/src}/utils/file-scanner.ts     |   4 +-
 packages/chrome-ext/tsconfig.json             |  12 +
 .../chrome-ext/vite.config.ts                 |   0
 .../src/__tests__/render-pipeline.test.ts     | 119 +++---
 packages/core/src/comments/comment-context.ts |  12 +-
 packages/core/src/index.ts                    |  15 +-
 packages/core/src/render-pipeline.ts          |  18 +-
 src/comments/annotation-parser.ts             |   1 -
 src/comments/annotation-serializer.ts         |   1 -
 src/comments/comment-context.ts               |   1 -
 src/comments/comment-highlight.ts             |   1 -
 src/comments/comment-parser.ts                |   1 -
 src/comments/comment-serializer.ts            |   1 -
 src/comments/comment-ui.ts                    |   1 -
 src/comments/emoji-data.ts                    |   1 -
 src/comments/source-position-map.ts           |   1 -
 src/core/cache-manager.ts                     |   3 -
 src/core/export-controller.ts                 |   3 -
 src/core/frontmatter-extractor.ts             |   3 -
 src/core/lazy-section-renderer.ts             |   3 -
 src/core/markdown-converter.ts                |   3 -
 src/native-host/host.cjs                      | 117 ------
 src/native-host/install.sh                    |  39 --
 src/renderers/mermaid-renderer.ts             |   1 -
 src/renderers/syntax-highlighter.ts           |   1 -
 src/themes/catppuccin-frappe.ts               |   1 -
 src/themes/catppuccin-latte.ts                |   1 -
 src/themes/catppuccin-macchiato.ts            |   1 -
 src/themes/catppuccin-mocha.ts                |   1 -
 src/themes/github-dark.ts                     |   1 -
 src/themes/github-light.ts                    |   1 -
 src/themes/monokai-pro.ts                     |   1 -
 src/themes/monokai.ts                         |   1 -
 src/types/index.d.ts                          |   3 -
 src/types/markdown-it-plugins.d.ts            |  29 --
 src/ui/toc-renderer.ts                        |   3 -
 src/utils/content-collector.ts                |   3 -
 src/utils/docx-generator.ts                   |   3 -
 src/utils/dom-purifier.ts                     |   1 -
 src/utils/filename-generator.ts               |   1 -
 src/utils/pdf-generator.ts                    |   3 -
 src/utils/scroll-manager.ts                   |   1 -
 src/utils/section-splitter.ts                 |   1 -
 src/utils/skeleton-renderer.ts                |   1 -
 src/utils/svg-converter.ts                    |   3 -
 src/utils/toc-stripper.ts                     |  15 -
 src/workers/render-worker.ts                  |   1 -
 src/workers/tasks/highlight-task.ts           |   1 -
 src/workers/tasks/mermaid-task.ts             |   1 -
 src/workers/tasks/parse-task.ts               |   1 -
 src/workers/worker-pool.ts                    |   1 -
 tests/helpers/mocks.ts                        |   5 +-
 .../integration/annotation-migration.test.ts  |  24 +-
 tests/integration/annotation-v2.test.ts       |   8 +-
 tests/integration/comments.test.ts            |  11 +-
 tests/integration/export-phase1.test.ts       |   6 +-
 tests/integration/export-phase2.test.ts       |   9 +-
 tests/unit/comments/annotation-parser.test.ts |   6 +-
 .../comments/annotation-serializer.test.ts    |  22 +-
 tests/unit/comments/comment-context.test.ts   |  46 +--
 tests/unit/comments/comment-highlight.test.ts |  19 +-
 tests/unit/comments/comment-manager.test.ts   | 352 +++++++++---------
 tests/unit/comments/comment-parser.test.ts    |   2 +-
 .../unit/comments/comment-serializer.test.ts  |  22 +-
 tests/unit/comments/comment-ui.test.ts        |  52 ++-
 tests/unit/comments/emoji-data.test.ts        |   2 +-
 tests/unit/comments/native-host.test.ts       |  20 +-
 .../unit/comments/source-position-map.test.ts |   5 +-
 tests/unit/core/export-controller.test.ts     |  29 +-
 tests/unit/core/frontmatter-extractor.test.ts |   5 +-
 tests/unit/core/markdown-converter.test.ts    |   7 +-
 tests/unit/core/mermaid-cache-race.test.ts    |  28 +-
 tests/unit/core/render-pipeline.test.ts       |  25 +-
 tests/unit/core/theme-engine.test.ts          | 207 +++++++---
 tests/unit/renderers/mermaid-renderer.test.ts |  16 +-
 tests/unit/ui/export-ui.test.ts               |   8 +-
 tests/unit/utils/content-collector.test.ts    |   4 +-
 tests/unit/utils/docx-generator.test.ts       |  14 +-
 tests/unit/utils/dom-purifier.test.ts         |   2 +-
 .../unit/utils/file-scanner-blocklist.test.ts |   2 +-
 tests/unit/utils/filename-generator.test.ts   |   3 +-
 tests/unit/utils/pdf-generator.test.ts        |  48 ++-
 tests/unit/utils/svg-converter.test.ts        |   2 +-
 tests/unit/utils/toc-stripper.test.ts         |   2 +-
 tsconfig.json                                 |   4 +-
 vitest.config.ts                              |   2 +-
 119 files changed, 742 insertions(+), 880 deletions(-)
 create mode 100644 packages/chrome-ext/package.json
 rename {public => packages/chrome-ext/public}/icons/icon128.png (100%)
 rename {public => packages/chrome-ext/public}/icons/icon128.svg (100%)
 rename {public => packages/chrome-ext/public}/icons/icon16.png (100%)
 rename {public => packages/chrome-ext/public}/icons/icon16.svg (100%)
 rename {public => packages/chrome-ext/public}/icons/icon32.png (100%)
 rename {public => packages/chrome-ext/public}/icons/icon32.svg (100%)
 rename {public => packages/chrome-ext/public}/icons/icon48.png (100%)
 rename {public => packages/chrome-ext/public}/icons/icon48.svg (100%)
 rename {public => packages/chrome-ext/public}/manifest.json (100%)
 rename {scripts => packages/chrome-ext/scripts}/fix-manifest.js (100%)
 rename {scripts => packages/chrome-ext/scripts}/generate-icons.cjs (100%)
 rename {scripts => packages/chrome-ext/scripts}/generate-icons.js (100%)
 rename {scripts => packages/chrome-ext/scripts}/svg-to-png.cjs (100%)
 rename {scripts => packages/chrome-ext/scripts}/update-manifest-version.js (100%)
 rename {src => packages/chrome-ext/src}/background/service-worker.ts (96%)
 rename {src => packages/chrome-ext/src}/comments/comment-manager.ts (93%)
 rename {src => packages/chrome-ext/src}/content/content-script.ts (98%)
 rename {src => packages/chrome-ext/src}/content/content.css (100%)
 rename {src => packages/chrome-ext/src}/core/render-pipeline.ts (92%)
 rename {src => packages/chrome-ext/src}/core/theme-engine.ts (95%)
 rename {src => packages/chrome-ext/src}/native-host/host-logic.ts (90%)
 rename {src => packages/chrome-ext/src}/native-host/manifest.json (100%)
 rename {src => packages/chrome-ext/src}/options/options.css (100%)
 rename {src => packages/chrome-ext/src}/options/options.html (100%)
 rename {src => packages/chrome-ext/src}/options/options.ts (99%)
 rename {src => packages/chrome-ext/src}/popup/popup.css (100%)
 rename {src => packages/chrome-ext/src}/popup/popup.html (100%)
 rename {src => packages/chrome-ext/src}/popup/popup.ts (99%)
 rename {src => packages/chrome-ext/src}/ui/export-ui.ts (68%)
 rename {src => packages/chrome-ext/src}/utils/debug-logger.ts (93%)
 rename {src => packages/chrome-ext/src}/utils/file-scanner.ts (97%)
 create mode 100644 packages/chrome-ext/tsconfig.json
 rename vite.config.ts => packages/chrome-ext/vite.config.ts (100%)
 delete mode 100644 src/comments/annotation-parser.ts
 delete mode 100644 src/comments/annotation-serializer.ts
 delete mode 100644 src/comments/comment-context.ts
 delete mode 100644 src/comments/comment-highlight.ts
 delete mode 100644 src/comments/comment-parser.ts
 delete mode 100644 src/comments/comment-serializer.ts
 delete mode 100644 src/comments/comment-ui.ts
 delete mode 100644 src/comments/emoji-data.ts
 delete mode 100644 src/comments/source-position-map.ts
 delete mode 100644 src/core/cache-manager.ts
 delete mode 100644 src/core/export-controller.ts
 delete mode 100644 src/core/frontmatter-extractor.ts
 delete mode 100644 src/core/lazy-section-renderer.ts
 delete mode 100644 src/core/markdown-converter.ts
 delete mode 100755 src/native-host/host.cjs
 delete mode 100755 src/native-host/install.sh
 delete mode 100644 src/renderers/mermaid-renderer.ts
 delete mode 100644 src/renderers/syntax-highlighter.ts
 delete mode 100644 src/themes/catppuccin-frappe.ts
 delete mode 100644 src/themes/catppuccin-latte.ts
 delete mode 100644 src/themes/catppuccin-macchiato.ts
 delete mode 100644 src/themes/catppuccin-mocha.ts
 delete mode 100644 src/themes/github-dark.ts
 delete mode 100644 src/themes/github-light.ts
 delete mode 100644 src/themes/monokai-pro.ts
 delete mode 100644 src/themes/monokai.ts
 delete mode 100644 src/types/index.d.ts
 delete mode 100644 src/types/markdown-it-plugins.d.ts
 delete mode 100644 src/ui/toc-renderer.ts
 delete mode 100644 src/utils/content-collector.ts
 delete mode 100644 src/utils/docx-generator.ts
 delete mode 100644 src/utils/dom-purifier.ts
 delete mode 100644 src/utils/filename-generator.ts
 delete mode 100644 src/utils/pdf-generator.ts
 delete mode 100644 src/utils/scroll-manager.ts
 delete mode 100644 src/utils/section-splitter.ts
 delete mode 100644 src/utils/skeleton-renderer.ts
 delete mode 100644 src/utils/svg-converter.ts
 delete mode 100644 src/utils/toc-stripper.ts
 delete mode 100644 src/workers/render-worker.ts
 delete mode 100644 src/workers/tasks/highlight-task.ts
 delete mode 100644 src/workers/tasks/mermaid-task.ts
 delete mode 100644 src/workers/tasks/parse-task.ts
 delete mode 100644 src/workers/worker-pool.ts

diff --git a/package-lock.json b/package-lock.json
index 0cc848d..0b1a2ad 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1670,6 +1670,10 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@mdview/chrome-ext": {
+      "resolved": "packages/chrome-ext",
+      "link": true
+    },
     "node_modules/@mdview/core": {
       "resolved": "packages/core",
       "link": true
@@ -10103,11 +10107,34 @@
         "url": "https://github.com/sponsors/colinhacks"
       }
     },
+    "packages/chrome-ext": {
+      "name": "@mdview/chrome-ext",
+      "version": "0.3.4",
+      "dependencies": {
+        "@mdview/core": "*"
+      },
+      "devDependencies": {
+        "@crxjs/vite-plugin": "^2.0.0-beta.28",
+        "@types/chrome": "^0.0.287"
+      }
+    },
+    "packages/chrome-ext/node_modules/@types/chrome": {
+      "version": "0.0.287",
+      "resolved": "https://registry.npmjs.org/@types/chrome/-/chrome-0.0.287.tgz",
+      "integrity": "sha512-wWhBNPNXZHwycHKNYnexUcpSbrihVZu++0rdp6GEk5ZgAglenLx+RwdEouh6FrHS0XQiOxSd62yaujM1OoQlZQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/filesystem": "*",
+        "@types/har-format": "*"
+      }
+    },
     "packages/core": {
       "name": "@mdview/core",
       "version": "0.0.1",
       "license": "MIT",
       "dependencies": {
+        "@jamesainslie/docx": "^9.5.1-svg.1",
         "dompurify": "^3.0.6",
         "highlight.js": "^11.9.0",
         "markdown-it": "^14.1.0",
diff --git a/package.json b/package.json
index 2c7dfdc..fb87289 100644
--- a/package.json
+++ b/package.json
@@ -7,15 +7,16 @@
     "packages/*"
   ],
   "scripts": {
-    "dev": "vite build --watch",
-    "build": "node scripts/update-manifest-version.js && tsc && vite build && node scripts/fix-manifest.js",
+    "dev": "npm -w @mdview/chrome-ext run dev",
+    "build": "npm -w @mdview/chrome-ext run build",
+    "build:ext": "npm -w @mdview/chrome-ext run build",
     "export:docx": "tsx scripts/export-docx-mermaid-cli.ts",
     "preview": "vite preview",
     "test": "vitest",
     "test:ci": "vitest --run",
     "test:e2e": "playwright test",
-    "lint": "eslint src --ext ts,tsx",
-    "format": "prettier --write \"src/**/*.{ts,tsx,css}\"",
+    "lint": "eslint packages --ext ts,tsx",
+    "format": "prettier --write \"packages/*/src/**/*.{ts,tsx,css}\"",
     "prepare": "husky"
   },
   "dependencies": {
@@ -65,9 +66,12 @@
   "author": "James Ainslie",
   "license": "MIT",
   "lint-staged": {
-    "{src,tests}/**/*.{ts,tsx}": [
+    "packages/*/src/**/*.{ts,tsx}": [
       "eslint --fix",
       "prettier --write"
+    ],
+    "tests/**/*.{ts,tsx}": [
+      "prettier --write"
     ]
   }
 }
diff --git a/packages/chrome-ext/package.json b/packages/chrome-ext/package.json
new file mode 100644
index 0000000..5c31fb2
--- /dev/null
+++ b/packages/chrome-ext/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "@mdview/chrome-ext",
+  "version": "0.3.4",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@mdview/core": "*"
+  },
+  "devDependencies": {
+    "@crxjs/vite-plugin": "^2.0.0-beta.28",
+    "@types/chrome": "^0.0.287"
+  }
+}
diff --git a/public/icons/icon128.png b/packages/chrome-ext/public/icons/icon128.png
similarity index 100%
rename from public/icons/icon128.png
rename to packages/chrome-ext/public/icons/icon128.png
diff --git a/public/icons/icon128.svg b/packages/chrome-ext/public/icons/icon128.svg
similarity index 100%
rename from public/icons/icon128.svg
rename to packages/chrome-ext/public/icons/icon128.svg
diff --git a/public/icons/icon16.png b/packages/chrome-ext/public/icons/icon16.png
similarity index 100%
rename from public/icons/icon16.png
rename to packages/chrome-ext/public/icons/icon16.png
diff --git a/public/icons/icon16.svg b/packages/chrome-ext/public/icons/icon16.svg
similarity index 100%
rename from public/icons/icon16.svg
rename to packages/chrome-ext/public/icons/icon16.svg
diff --git a/public/icons/icon32.png b/packages/chrome-ext/public/icons/icon32.png
similarity index 100%
rename from public/icons/icon32.png
rename to packages/chrome-ext/public/icons/icon32.png
diff --git a/public/icons/icon32.svg b/packages/chrome-ext/public/icons/icon32.svg
similarity index 100%
rename from public/icons/icon32.svg
rename to packages/chrome-ext/public/icons/icon32.svg
diff --git a/public/icons/icon48.png b/packages/chrome-ext/public/icons/icon48.png
similarity index 100%
rename from public/icons/icon48.png
rename to packages/chrome-ext/public/icons/icon48.png
diff --git a/public/icons/icon48.svg b/packages/chrome-ext/public/icons/icon48.svg
similarity index 100%
rename from public/icons/icon48.svg
rename to packages/chrome-ext/public/icons/icon48.svg
diff --git a/public/manifest.json b/packages/chrome-ext/public/manifest.json
similarity index 100%
rename from public/manifest.json
rename to packages/chrome-ext/public/manifest.json
diff --git a/scripts/fix-manifest.js b/packages/chrome-ext/scripts/fix-manifest.js
similarity index 100%
rename from scripts/fix-manifest.js
rename to packages/chrome-ext/scripts/fix-manifest.js
diff --git a/scripts/generate-icons.cjs b/packages/chrome-ext/scripts/generate-icons.cjs
similarity index 100%
rename from scripts/generate-icons.cjs
rename to packages/chrome-ext/scripts/generate-icons.cjs
diff --git a/scripts/generate-icons.js b/packages/chrome-ext/scripts/generate-icons.js
similarity index 100%
rename from scripts/generate-icons.js
rename to packages/chrome-ext/scripts/generate-icons.js
diff --git a/scripts/svg-to-png.cjs b/packages/chrome-ext/scripts/svg-to-png.cjs
similarity index 100%
rename from scripts/svg-to-png.cjs
rename to packages/chrome-ext/scripts/svg-to-png.cjs
diff --git a/scripts/update-manifest-version.js b/packages/chrome-ext/scripts/update-manifest-version.js
similarity index 100%
rename from scripts/update-manifest-version.js
rename to packages/chrome-ext/scripts/update-manifest-version.js
diff --git a/src/background/service-worker.ts b/packages/chrome-ext/src/background/service-worker.ts
similarity index 96%
rename from src/background/service-worker.ts
rename to packages/chrome-ext/src/background/service-worker.ts
index 53e85a8..fa96e89 100644
--- a/src/background/service-worker.ts
+++ b/packages/chrome-ext/src/background/service-worker.ts
@@ -3,8 +3,8 @@
  * Handles state management, message passing, coordination, and cache management
  */
 
-import type { AppState, ThemeName } from '../types';
-import { CacheManager } from '../core/cache-manager';
+import type { AppState, ThemeName, CachedResult } from '@mdview/core';
+import { CacheManager } from '@mdview/core';
 import { debug } from '../utils/debug-logger';
 
 // Default state
@@ -151,12 +151,14 @@ function setupContextMenu(): void {
 // Handle context menu clicks
 chrome.contextMenus.onClicked.addListener((info, tab) => {
   if (info.menuItemId === 'mdview-add-comment' && tab?.id) {
-    void chrome.tabs.sendMessage(tab.id, {
-      type: 'ADD_COMMENT',
-      payload: { selectionText: info.selectionText },
-    }).catch(() => {
-      // Tab may not have content script
-    });
+    void chrome.tabs
+      .sendMessage(tab.id, {
+        type: 'ADD_COMMENT',
+        payload: { selectionText: info.selectionText },
+      })
+      .catch(() => {
+        // Tab may not have content script
+      });
   }
 });
 
@@ -299,7 +301,7 @@ chrome.runtime.onMessage.addListener(
           case 'CACHE_SET': {
             const payload = message.payload as {
               key: string;
-              result: import('../types').CachedResult;
+              result: CachedResult;
               filePath: string;
               contentHash: string;
               theme: ThemeName;
@@ -367,7 +369,7 @@ chrome.runtime.onMessage.addListener(
 
           case 'GET_USERNAME': {
             try {
-              const result = await chrome.runtime.sendNativeMessage(
+              const result: unknown = await chrome.runtime.sendNativeMessage(
                 'com.mdview.filewriter',
                 { action: 'get_username' }
               );
@@ -382,7 +384,7 @@ chrome.runtime.onMessage.addListener(
           case 'WRITE_FILE': {
             const payload = message.payload as { path: string; content: string };
             try {
-              const result = await chrome.runtime.sendNativeMessage(
+              const result: unknown = await chrome.runtime.sendNativeMessage(
                 'com.mdview.filewriter',
                 {
                   action: 'write',
diff --git a/src/comments/comment-manager.ts b/packages/chrome-ext/src/comments/comment-manager.ts
similarity index 93%
rename from src/comments/comment-manager.ts
rename to packages/chrome-ext/src/comments/comment-manager.ts
index 7f30ff5..39e6ca6 100644
--- a/src/comments/comment-manager.ts
+++ b/packages/chrome-ext/src/comments/comment-manager.ts
@@ -11,13 +11,11 @@
 import {
   CommentManager as CoreCommentManager,
   type CommentManagerAdapters,
-} from '../../packages/core/src/comments/comment-manager';
-import type {
-  FileAdapter,
-  IdentityAdapter,
-  FileWriteResult,
-  FileChangeInfo,
-} from '../../packages/core/src/adapters';
+  type FileAdapter,
+  type IdentityAdapter,
+  type FileWriteResult,
+  type FileChangeInfo,
+} from '@mdview/core';
 
 /**
  * Type-safe helper to send a Chrome runtime message and parse the response.
diff --git a/src/content/content-script.ts b/packages/chrome-ext/src/content/content-script.ts
similarity index 98%
rename from src/content/content-script.ts
rename to packages/chrome-ext/src/content/content-script.ts
index 2d0c722..3e4d5f5 100644
--- a/src/content/content-script.ts
+++ b/packages/chrome-ext/src/content/content-script.ts
@@ -6,9 +6,9 @@
 // CSS is imported but only activated when we add .mdview-active to body
 import './content.css';
 import { FileScanner } from '../utils/file-scanner';
-import type { AppState } from '../types';
+import type { AppState } from '@mdview/core';
 import { debug } from '../utils/debug-logger';
-import { TocRenderer } from '../ui/toc-renderer';
+import { TocRenderer } from '@mdview/core';
 import type { ExportUI } from '../ui/export-ui';
 import type { CommentManager } from '../comments/comment-manager';
 
@@ -266,7 +266,10 @@ class MDViewContentScript {
       }
 
       // Setup Comments (only for local files, default enabled)
-      if (this.state?.preferences.commentsEnabled !== false && window.location.protocol === 'file:') {
+      if (
+        this.state?.preferences.commentsEnabled !== false &&
+        window.location.protocol === 'file:'
+      ) {
         await this.setupComments(content, filePath);
       }
 
@@ -608,7 +611,7 @@ class MDViewContentScript {
       debug.info('MDView', `[ContentScript] Received request to apply theme: ${themeName}`);
       const { themeEngine } = await import('../core/theme-engine');
       debug.debug('MDView', `[ContentScript] Theme engine imported, calling applyTheme`);
-      await themeEngine.applyTheme(themeName as import('../types').ThemeName);
+      await themeEngine.applyTheme(themeName as import('@mdview/core').ThemeName);
       debug.info('MDView', '[ContentScript] Theme applied successfully via engine');
     } catch (error) {
       debug.error('MDView', '[ContentScript] Failed to apply theme:', error);
@@ -903,7 +906,12 @@ class MDViewContentScript {
       debug.info('MDView', 'Setting up Comments...');
       const { CommentManager } = await import('../comments/comment-manager');
       this.commentManager = new CommentManager();
-      await this.commentManager.initialize(markdown, filePath, this.state!.preferences);
+      const preferences = this.state?.preferences;
+      if (!preferences) {
+        debug.warn('MDView', 'Cannot initialize comments: state not loaded');
+        return;
+      }
+      await this.commentManager.initialize(markdown, filePath, preferences);
       debug.info('MDView', 'Comments initialized');
     } catch (error) {
       debug.error('MDView', 'Failed to setup comments:', error);
diff --git a/src/content/content.css b/packages/chrome-ext/src/content/content.css
similarity index 100%
rename from src/content/content.css
rename to packages/chrome-ext/src/content/content.css
diff --git a/src/core/render-pipeline.ts b/packages/chrome-ext/src/core/render-pipeline.ts
similarity index 92%
rename from src/core/render-pipeline.ts
rename to packages/chrome-ext/src/core/render-pipeline.ts
index 1c79ad5..b477e03 100644
--- a/src/core/render-pipeline.ts
+++ b/packages/chrome-ext/src/core/render-pipeline.ts
@@ -12,8 +12,9 @@ import {
   type RenderProgress,
   type ProgressCallback,
   type RenderPipelineOptions,
-} from '../../packages/core/src/render-pipeline';
-import type { MessagingAdapter, IPCMessage } from '../../packages/core/src/adapters';
+  type MessagingAdapter,
+  type IPCMessage,
+} from '@mdview/core';
 
 // ---------------------------------------------------------------------------
 // Chrome MessagingAdapter — bridges core pipeline to chrome.runtime
diff --git a/src/core/theme-engine.ts b/packages/chrome-ext/src/core/theme-engine.ts
similarity index 95%
rename from src/core/theme-engine.ts
rename to packages/chrome-ext/src/core/theme-engine.ts
index 0090607..c511353 100644
--- a/src/core/theme-engine.ts
+++ b/packages/chrome-ext/src/core/theme-engine.ts
@@ -8,10 +8,8 @@
 
 /* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument */
 
-import type { Theme, ThemeName } from '../types';
-import type { StorageAdapter } from '@mdview/core';
+import type { Theme, ThemeName, StorageAdapter, ThemeOverrides } from '@mdview/core';
 import { ThemeEngine as CoreThemeEngine } from '@mdview/core';
-import type { ThemeOverrides } from '@mdview/core';
 import { debug } from '../utils/debug-logger';
 
 export type { ThemeInfo } from '@mdview/core';
@@ -148,7 +146,7 @@ export class ThemeEngine {
 
     // Update mermaid theme
     try {
-      const { mermaidRenderer } = await import('../renderers/mermaid-renderer');
+      const { mermaidRenderer } = await import('@mdview/core');
       mermaidRenderer.updateTheme(themeObj.mermaidTheme);
     } catch (error) {
       debug.error('ThemeEngine', 'Failed to update mermaid theme:', error);
@@ -194,7 +192,7 @@ export class ThemeEngine {
    */
   private async updateSyntaxTheme(syntaxTheme: string): Promise<void> {
     try {
-      const { syntaxHighlighter } = await import('../renderers/syntax-highlighter');
+      const { syntaxHighlighter } = await import('@mdview/core');
       syntaxHighlighter.setTheme(syntaxTheme);
     } catch (error) {
       debug.error('ThemeEngine', 'Failed to update syntax theme:', error);
diff --git a/src/native-host/host-logic.ts b/packages/chrome-ext/src/native-host/host-logic.ts
similarity index 90%
rename from src/native-host/host-logic.ts
rename to packages/chrome-ext/src/native-host/host-logic.ts
index fc6b91d..a8e158f 100644
--- a/src/native-host/host-logic.ts
+++ b/packages/chrome-ext/src/native-host/host-logic.ts
@@ -98,12 +98,10 @@ export function handleMessage(msg: HostMessage | null | string): HostResponse {
     const existingBound = findContentBoundary(existing, V1_SEP, V2_PREFIX);
     const newBound = findContentBoundary(newContent, V1_SEP, V2_PREFIX);
 
-    const existingBody = existingBound !== -1
-      ? existing.substring(0, existingBound).trimEnd()
-      : existing.trimEnd();
-    const newBody = newBound !== -1
-      ? newContent.substring(0, newBound).trimEnd()
-      : newContent.trimEnd();
+    const existingBody =
+      existingBound !== -1 ? existing.substring(0, existingBound).trimEnd() : existing.trimEnd();
+    const newBody =
+      newBound !== -1 ? newContent.substring(0, newBound).trimEnd() : newContent.trimEnd();
 
     // Strip both v1 and v2 marker formats for comparison
     const V1_REF = /\[\^comment-\d+\]/g;
@@ -113,7 +111,8 @@ export function handleMessage(msg: HostMessage | null | string): HostResponse {
 
     if (existingClean !== newClean) {
       return {
-        error: 'Refused: write would modify document content beyond comment markers. Only comment changes are allowed.',
+        error:
+          'Refused: write would modify document content beyond comment markers. Only comment changes are allowed.',
       };
     }
 
diff --git a/src/native-host/manifest.json b/packages/chrome-ext/src/native-host/manifest.json
similarity index 100%
rename from src/native-host/manifest.json
rename to packages/chrome-ext/src/native-host/manifest.json
diff --git a/src/options/options.css b/packages/chrome-ext/src/options/options.css
similarity index 100%
rename from src/options/options.css
rename to packages/chrome-ext/src/options/options.css
diff --git a/src/options/options.html b/packages/chrome-ext/src/options/options.html
similarity index 100%
rename from src/options/options.html
rename to packages/chrome-ext/src/options/options.html
diff --git a/src/options/options.ts b/packages/chrome-ext/src/options/options.ts
similarity index 99%
rename from src/options/options.ts
rename to packages/chrome-ext/src/options/options.ts
index 5f97676..92e5388 100644
--- a/src/options/options.ts
+++ b/packages/chrome-ext/src/options/options.ts
@@ -3,7 +3,7 @@
  * Manages settings page UI and interactions
  */
 
-import type { AppState, ThemeName, LogLevel, PaperSize } from '../types';
+import type { AppState, ThemeName, LogLevel, PaperSize } from '@mdview/core';
 import { debug } from '../utils/debug-logger';
 
 class OptionsManager {
@@ -363,7 +363,7 @@ class OptionsManager {
     const previewEl = document.getElementById('filename-preview-text');
     if (previewEl) {
       // Dynamic import to avoid circular dependency
-      import('../utils/filename-generator')
+      import('@mdview/core')
         .then(({ FilenameGenerator }) => {
           const preview = FilenameGenerator.generate({
             title: 'My Document',
diff --git a/src/popup/popup.css b/packages/chrome-ext/src/popup/popup.css
similarity index 100%
rename from src/popup/popup.css
rename to packages/chrome-ext/src/popup/popup.css
diff --git a/src/popup/popup.html b/packages/chrome-ext/src/popup/popup.html
similarity index 100%
rename from src/popup/popup.html
rename to packages/chrome-ext/src/popup/popup.html
diff --git a/src/popup/popup.ts b/packages/chrome-ext/src/popup/popup.ts
similarity index 99%
rename from src/popup/popup.ts
rename to packages/chrome-ext/src/popup/popup.ts
index 8871ceb..15b1b40 100644
--- a/src/popup/popup.ts
+++ b/packages/chrome-ext/src/popup/popup.ts
@@ -3,7 +3,7 @@
  * Manages popup UI and interactions
  */
 
-import type { AppState, ThemeName, LogLevel } from '../types';
+import type { AppState, ThemeName, LogLevel } from '@mdview/core';
 import { debug } from '../utils/debug-logger';
 
 class PopupManager {
diff --git a/src/ui/export-ui.ts b/packages/chrome-ext/src/ui/export-ui.ts
similarity index 68%
rename from src/ui/export-ui.ts
rename to packages/chrome-ext/src/ui/export-ui.ts
index b8e9a8e..426cf17 100644
--- a/src/ui/export-ui.ts
+++ b/packages/chrome-ext/src/ui/export-ui.ts
@@ -2,12 +2,8 @@
 // This shim provides Chrome extension MessagingAdapter and platform-specific factories.
 // It will be removed in Phase 2.9
 
-import type { ExportUIOptions } from '../types';
-import type { MessagingAdapter, IPCMessage } from '../../packages/core/src/adapters';
-import {
-  ExportUI as CoreExportUI,
-  type CoreExportUIOptions,
-} from '../../packages/core/src/ui/export-ui';
+import type { ExportUIOptions, MessagingAdapter, IPCMessage } from '@mdview/core';
+import { ExportUI as CoreExportUI, type CoreExportUIOptions } from '@mdview/core';
 
 /** Chrome extension MessagingAdapter using chrome.runtime.sendMessage */
 class ChromeMessagingAdapter implements MessagingAdapter {
@@ -30,12 +26,12 @@ export class ExportUI extends CoreExportUI {
       messaging: new ChromeMessagingAdapter(),
       factories: {
         createExportController: async () => {
-          const { ExportController } = await import('../core/export-controller');
-          return new ExportController();
+          const mod = await import('@mdview/core');
+          return new mod.ExportController();
         },
         createPDFGenerator: async () => {
-          const { PDFGenerator } = await import('../utils/pdf-generator');
-          return new PDFGenerator();
+          const mod = await import('@mdview/core');
+          return new mod.PDFGenerator();
         },
       },
     };
diff --git a/src/utils/debug-logger.ts b/packages/chrome-ext/src/utils/debug-logger.ts
similarity index 93%
rename from src/utils/debug-logger.ts
rename to packages/chrome-ext/src/utils/debug-logger.ts
index d8237fb..eeb9192 100644
--- a/src/utils/debug-logger.ts
+++ b/packages/chrome-ext/src/utils/debug-logger.ts
@@ -7,9 +7,8 @@
  * `debug` and `debugLogger` without any changes.
  */
 
-import type { StorageAdapter } from '@mdview/core/adapters';
-import { DebugLogger as CoreDebugLogger } from '@mdview/core/utils/debug-logger';
-import type { LogLevel } from '../types';
+import type { StorageAdapter, LogLevel } from '@mdview/core';
+import { DebugLogger as CoreDebugLogger } from '@mdview/core';
 
 // ---------------------------------------------------------------------------
 // Chrome StorageAdapter (sync-only for preferences)
diff --git a/src/utils/file-scanner.ts b/packages/chrome-ext/src/utils/file-scanner.ts
similarity index 97%
rename from src/utils/file-scanner.ts
rename to packages/chrome-ext/src/utils/file-scanner.ts
index 1f74f68..163d6d8 100644
--- a/src/utils/file-scanner.ts
+++ b/packages/chrome-ext/src/utils/file-scanner.ts
@@ -3,8 +3,8 @@
  * Chrome extension-specific methods (window.location, chrome.runtime).
  */
 
-import { FileScanner as CoreFileScanner } from '../../packages/core/src/utils/file-scanner';
-import type { FileAdapter, FileChangeInfo } from '../../packages/core/src/adapters';
+import { FileScanner as CoreFileScanner } from '@mdview/core';
+import type { FileAdapter, FileChangeInfo } from '@mdview/core';
 import { debug } from './debug-logger';
 
 /**
diff --git a/packages/chrome-ext/tsconfig.json b/packages/chrome-ext/tsconfig.json
new file mode 100644
index 0000000..3fda8ee
--- /dev/null
+++ b/packages/chrome-ext/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "baseUrl": ".",
+    "paths": {},
+    "types": ["chrome", "vite/client", "vitest/globals"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/vite.config.ts b/packages/chrome-ext/vite.config.ts
similarity index 100%
rename from vite.config.ts
rename to packages/chrome-ext/vite.config.ts
diff --git a/packages/core/src/__tests__/render-pipeline.test.ts b/packages/core/src/__tests__/render-pipeline.test.ts
index b9951be..5adf752 100644
--- a/packages/core/src/__tests__/render-pipeline.test.ts
+++ b/packages/core/src/__tests__/render-pipeline.test.ts
@@ -8,30 +8,30 @@ vi.mock('../utils/dom-purifier', () => ({
   },
 }));
 
-vi.mock('../../../../src/workers/worker-pool', () => ({
+vi.mock('../workers/worker-pool', () => ({
   workerPool: {
     initialize: vi.fn().mockResolvedValue(undefined),
     execute: vi.fn(),
   },
 }));
 
-vi.mock('../../../../src/renderers/syntax-highlighter', () => ({
+vi.mock('../renderers/syntax-highlighter', () => ({
   syntaxHighlighter: {
     highlightVisible: vi.fn(),
   },
 }));
 
-vi.mock('../../../../src/renderers/mermaid-renderer', () => ({
+vi.mock('../renderers/mermaid-renderer', () => ({
   mermaidRenderer: {
     renderAll: vi.fn().mockResolvedValue(undefined),
   },
 }));
 
-vi.mock('../../../../src/utils/toc-stripper', () => ({
+vi.mock('../utils/toc-stripper', () => ({
   stripTableOfContents: vi.fn((md: string) => ({ markdown: md, tocFound: false })),
 }));
 
-vi.mock('../../../../src/comments/annotation-parser', () => ({
+vi.mock('../comments/annotation-parser', () => ({
   parseComments: vi.fn((md: string) => ({
     cleanedMarkdown: md,
     comments: [],
@@ -58,20 +58,19 @@ describe('RenderPipeline', () => {
 
   describe('with MessagingAdapter', () => {
     it('sends CACHE_GENERATE_KEY and CACHE_GET when useCache is true', async () => {
-      const mockMessaging: MessagingAdapter = {
-        send: vi.fn().mockImplementation(async (msg: IPCMessage) => {
-          if (msg.type === 'CACHE_GENERATE_KEY') {
-            return { key: 'test-cache-key' };
-          }
-          if (msg.type === 'CACHE_GET') {
-            return { result: null };
-          }
-          if (msg.type === 'CACHE_SET') {
-            return {};
-          }
-          return {};
-        }),
-      };
+      const sendMock = vi.fn().mockImplementation((msg: IPCMessage) => {
+        if (msg.type === 'CACHE_GENERATE_KEY') {
+          return Promise.resolve({ key: 'test-cache-key' });
+        }
+        if (msg.type === 'CACHE_GET') {
+          return Promise.resolve({ result: null });
+        }
+        if (msg.type === 'CACHE_SET') {
+          return Promise.resolve({});
+        }
+        return Promise.resolve({});
+      });
+      const mockMessaging: MessagingAdapter = { send: sendMock };
 
       const pipeline = new RenderPipeline({ messaging: mockMessaging });
 
@@ -84,38 +83,43 @@ describe('RenderPipeline', () => {
       });
 
       // Should have called CACHE_GENERATE_KEY
-      expect(mockMessaging.send).toHaveBeenCalledWith(
+      expect(sendMock).toHaveBeenCalledWith(
         expect.objectContaining({ type: 'CACHE_GENERATE_KEY' })
       );
 
       // Should have called CACHE_GET
-      expect(mockMessaging.send).toHaveBeenCalledWith(
-        expect.objectContaining({ type: 'CACHE_GET' })
-      );
+      expect(sendMock).toHaveBeenCalledWith(expect.objectContaining({ type: 'CACHE_GET' }));
     });
 
     it('uses cached result when adapter returns a cache hit', async () => {
       const cachedHtml = '<div class="mdview-rendered"><p>Cached content</p></div>';
-      const mockMessaging: MessagingAdapter = {
-        send: vi.fn().mockImplementation(async (msg: IPCMessage) => {
-          if (msg.type === 'CACHE_GENERATE_KEY') {
-            return { key: 'cached-key' };
-          }
-          if (msg.type === 'CACHE_GET') {
-            return {
-              result: {
-                html: cachedHtml,
-                metadata: { headings: [], codeBlocks: [], mermaidBlocks: [], images: [], links: [], wordCount: 0, frontmatter: null },
-                highlightedBlocks: new Map(),
-                mermaidSVGs: new Map(),
-                timestamp: Date.now(),
-                cacheKey: 'cached-key',
+      const sendMock = vi.fn().mockImplementation((msg: IPCMessage) => {
+        if (msg.type === 'CACHE_GENERATE_KEY') {
+          return Promise.resolve({ key: 'cached-key' });
+        }
+        if (msg.type === 'CACHE_GET') {
+          return Promise.resolve({
+            result: {
+              html: cachedHtml,
+              metadata: {
+                headings: [],
+                codeBlocks: [],
+                mermaidBlocks: [],
+                images: [],
+                links: [],
+                wordCount: 0,
+                frontmatter: null,
               },
-            };
-          }
-          return {};
-        }),
-      };
+              highlightedBlocks: new Map(),
+              mermaidSVGs: new Map(),
+              timestamp: Date.now(),
+              cacheKey: 'cached-key',
+            },
+          });
+        }
+        return Promise.resolve({});
+      });
+      const mockMessaging: MessagingAdapter = { send: sendMock };
 
       const pipeline = new RenderPipeline({ messaging: mockMessaging });
 
@@ -135,20 +139,19 @@ describe('RenderPipeline', () => {
     });
 
     it('sends CACHE_SET after successful render', async () => {
-      const mockMessaging: MessagingAdapter = {
-        send: vi.fn().mockImplementation(async (msg: IPCMessage) => {
-          if (msg.type === 'CACHE_GENERATE_KEY') {
-            return { key: 'new-cache-key' };
-          }
-          if (msg.type === 'CACHE_GET') {
-            return { result: null };
-          }
-          if (msg.type === 'CACHE_SET') {
-            return {};
-          }
-          return {};
-        }),
-      };
+      const sendMock = vi.fn().mockImplementation((msg: IPCMessage) => {
+        if (msg.type === 'CACHE_GENERATE_KEY') {
+          return Promise.resolve({ key: 'new-cache-key' });
+        }
+        if (msg.type === 'CACHE_GET') {
+          return Promise.resolve({ result: null });
+        }
+        if (msg.type === 'CACHE_SET') {
+          return Promise.resolve({});
+        }
+        return Promise.resolve({});
+      });
+      const mockMessaging: MessagingAdapter = { send: sendMock };
 
       const pipeline = new RenderPipeline({ messaging: mockMessaging });
 
@@ -160,9 +163,7 @@ describe('RenderPipeline', () => {
         useWorkers: false,
       });
 
-      expect(mockMessaging.send).toHaveBeenCalledWith(
-        expect.objectContaining({ type: 'CACHE_SET' })
-      );
+      expect(sendMock).toHaveBeenCalledWith(expect.objectContaining({ type: 'CACHE_SET' }));
     });
   });
 
diff --git a/packages/core/src/comments/comment-context.ts b/packages/core/src/comments/comment-context.ts
index 1622442..02b0634 100644
--- a/packages/core/src/comments/comment-context.ts
+++ b/packages/core/src/comments/comment-context.ts
@@ -8,16 +8,13 @@
  */
 
 import type { CommentContext } from '../types/index';
-import { splitIntoSections, type MarkdownSection } from '../../../../src/utils/section-splitter';
+import { splitIntoSections, type MarkdownSection } from '../utils/section-splitter';
 
 /**
  * Compute positional context for a comment at a given character offset
  * in the content section of markdown (above the comment separator).
  */
-export function computeCommentContext(
-  contentMarkdown: string,
-  charOffset: number
-): CommentContext {
+export function computeCommentContext(contentMarkdown: string, charOffset: number): CommentContext {
   const line = offsetToLine(contentMarkdown, charOffset);
   const sections = splitIntoSections(contentMarkdown);
   const { section, sectionLevel, breadcrumb } = findSectionContext(sections, line);
@@ -83,10 +80,7 @@ function findSectionContext(
  * when encountering a heading at level N, pop all headings at level >= N,
  * then push. The final stack is the breadcrumb.
  */
-function buildBreadcrumb(
-  sections: MarkdownSection[],
-  target: MarkdownSection
-): string[] {
+function buildBreadcrumb(sections: MarkdownSection[], target: MarkdownSection): string[] {
   const stack: Array<{ heading: string; level: number }> = [];
 
   for (const s of sections) {
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index ea3c47c..20f12bd 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -74,10 +74,19 @@ export type { ThemeInfo, ThemeOverrides } from './theme-engine';
 
 // Render pipeline
 export { RenderPipeline } from './render-pipeline';
-export type { RenderOptions, RenderProgress, ProgressCallback, RenderPipelineOptions } from './render-pipeline';
+export type {
+  RenderOptions,
+  RenderProgress,
+  ProgressCallback,
+  RenderPipelineOptions,
+} from './render-pipeline';
 
 // Renderers
-export { SyntaxHighlighter, syntaxHighlighter, SYNTAX_THEME_MAP } from './renderers/syntax-highlighter';
+export {
+  SyntaxHighlighter,
+  syntaxHighlighter,
+  SYNTAX_THEME_MAP,
+} from './renderers/syntax-highlighter';
 export type { HighlightResult, DetectionResult } from './renderers/syntax-highlighter';
 export { MermaidRenderer, mermaidRenderer } from './renderers/mermaid-renderer';
 export type { MermaidOptions, DiagramControls } from './renderers/mermaid-renderer';
@@ -91,6 +100,8 @@ export { ExportController } from './export-controller';
 
 // UI
 export { TocRenderer } from './ui/toc-renderer';
+export { ExportUI } from './ui/export-ui';
+export type { CoreExportUIOptions } from './ui/export-ui';
 
 // Lazy section renderer
 export { LazySectionRenderer } from './lazy-section-renderer';
diff --git a/packages/core/src/render-pipeline.ts b/packages/core/src/render-pipeline.ts
index 27430a1..278666e 100644
--- a/packages/core/src/render-pipeline.ts
+++ b/packages/core/src/render-pipeline.ts
@@ -9,7 +9,7 @@
 import { MarkdownConverter } from './markdown-converter';
 import { extractFrontmatter, renderFrontmatterHtml } from './frontmatter-extractor';
 import { domPurifier } from './utils/dom-purifier';
-import { workerPool } from '../../../src/workers/worker-pool';
+import { workerPool } from './workers/worker-pool';
 import type {
   ConversionResult,
   ThemeName,
@@ -164,7 +164,7 @@ export class RenderPipeline {
 
       // Preprocess: Strip existing TOC if custom TOC is enabled
       if ((preferences as { showToc?: boolean }).showToc) {
-        const { stripTableOfContents } = await import('../../../src/utils/toc-stripper');
+        const { stripTableOfContents } = await import('./utils/toc-stripper');
         const stripResult = stripTableOfContents(processedMarkdown);
         processedMarkdown = stripResult.markdown;
         if (stripResult.tocFound) {
@@ -175,7 +175,7 @@ export class RenderPipeline {
       // Preprocess: Strip comment footnotes before parsing
       this.lastCommentParseResult = null;
       if ((preferences as { commentsEnabled?: boolean }).commentsEnabled !== false) {
-        const { parseComments } = await import('../../../src/comments/annotation-parser');
+        const { parseComments } = await import('./comments/annotation-parser');
         this.lastCommentParseResult = parseComments(processedMarkdown);
         processedMarkdown = this.lastCommentParseResult.cleanedMarkdown;
         if (this.lastCommentParseResult.comments.length > 0) {
@@ -372,7 +372,7 @@ export class RenderPipeline {
 
     if (pendingMermaid.length > 0 || readyMermaid.length > 0) {
       try {
-        const { mermaidRenderer } = await import('../../../src/renderers/mermaid-renderer');
+        const { mermaidRenderer } = await import('./renderers/mermaid-renderer');
 
         // Re-render any pending diagrams that were cached before rendering completed
         if (pendingMermaid.length > 0) {
@@ -448,7 +448,7 @@ export class RenderPipeline {
     // Even with workers available, use lazy loading for instant content display
     // Only visible code blocks are highlighted immediately, rest on scroll
     try {
-      const { syntaxHighlighter } = await import('../../../src/renderers/syntax-highlighter');
+      const { syntaxHighlighter } = await import('./renderers/syntax-highlighter');
       syntaxHighlighter.highlightVisible(container);
     } catch (error) {
       debug.error('RenderPipeline', 'Syntax highlighting error:', error);
@@ -608,7 +608,7 @@ export class RenderPipeline {
 
     // Preprocess: Strip existing TOC if custom TOC is enabled
     if ((preferences as { showToc?: boolean }).showToc) {
-      const { stripTableOfContents } = await import('../../../src/utils/toc-stripper');
+      const { stripTableOfContents } = await import('./utils/toc-stripper');
       const stripResult = stripTableOfContents(processedMarkdown);
       processedMarkdown = stripResult.markdown;
       if (stripResult.tocFound) {
@@ -619,7 +619,7 @@ export class RenderPipeline {
     // Preprocess: Strip comment footnotes before parsing
     this.lastCommentParseResult = null;
     if ((preferences as { commentsEnabled?: boolean }).commentsEnabled !== false) {
-      const { parseComments } = await import('../../../src/comments/annotation-parser');
+      const { parseComments } = await import('./comments/annotation-parser');
       this.lastCommentParseResult = parseComments(processedMarkdown);
       processedMarkdown = this.lastCommentParseResult.cleanedMarkdown;
       if (this.lastCommentParseResult.comments.length > 0) {
@@ -807,7 +807,7 @@ export class RenderPipeline {
    */
   private async applySyntaxHighlighting(container: HTMLElement): Promise<void> {
     try {
-      const { syntaxHighlighter } = await import('../../../src/renderers/syntax-highlighter');
+      const { syntaxHighlighter } = await import('./renderers/syntax-highlighter');
       syntaxHighlighter.highlightVisible(container);
     } catch (error) {
       debug.error('RenderPipeline', 'Syntax highlighting error:', error);
@@ -970,7 +970,7 @@ export class RenderPipeline {
    */
   private async renderMermaidDiagrams(container: HTMLElement): Promise<void> {
     try {
-      const { mermaidRenderer } = await import('../../../src/renderers/mermaid-renderer');
+      const { mermaidRenderer } = await import('./renderers/mermaid-renderer');
       await mermaidRenderer.renderAll(container);
     } catch (error) {
       debug.error('RenderPipeline', 'Mermaid rendering error:', error);
diff --git a/src/comments/annotation-parser.ts b/src/comments/annotation-parser.ts
deleted file mode 100644
index 4397b68..0000000
--- a/src/comments/annotation-parser.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/annotation-parser';
diff --git a/src/comments/annotation-serializer.ts b/src/comments/annotation-serializer.ts
deleted file mode 100644
index 8159fb0..0000000
--- a/src/comments/annotation-serializer.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/annotation-serializer';
diff --git a/src/comments/comment-context.ts b/src/comments/comment-context.ts
deleted file mode 100644
index 295e89e..0000000
--- a/src/comments/comment-context.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/comment-context';
diff --git a/src/comments/comment-highlight.ts b/src/comments/comment-highlight.ts
deleted file mode 100644
index ff458ce..0000000
--- a/src/comments/comment-highlight.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/comment-highlight';
diff --git a/src/comments/comment-parser.ts b/src/comments/comment-parser.ts
deleted file mode 100644
index f379fa6..0000000
--- a/src/comments/comment-parser.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/comment-parser';
diff --git a/src/comments/comment-serializer.ts b/src/comments/comment-serializer.ts
deleted file mode 100644
index 9c262f2..0000000
--- a/src/comments/comment-serializer.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/comment-serializer';
diff --git a/src/comments/comment-ui.ts b/src/comments/comment-ui.ts
deleted file mode 100644
index d7c05ba..0000000
--- a/src/comments/comment-ui.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/comment-ui';
diff --git a/src/comments/emoji-data.ts b/src/comments/emoji-data.ts
deleted file mode 100644
index b3e14d6..0000000
--- a/src/comments/emoji-data.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/emoji-data';
diff --git a/src/comments/source-position-map.ts b/src/comments/source-position-map.ts
deleted file mode 100644
index 0fd532e..0000000
--- a/src/comments/source-position-map.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/comments/source-position-map';
diff --git a/src/core/cache-manager.ts b/src/core/cache-manager.ts
deleted file mode 100644
index cb0d68b..0000000
--- a/src/core/cache-manager.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: cache-manager has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/cache-manager';
diff --git a/src/core/export-controller.ts b/src/core/export-controller.ts
deleted file mode 100644
index 6017980..0000000
--- a/src/core/export-controller.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: export-controller has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/export-controller';
diff --git a/src/core/frontmatter-extractor.ts b/src/core/frontmatter-extractor.ts
deleted file mode 100644
index d73a524..0000000
--- a/src/core/frontmatter-extractor.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: frontmatter-extractor has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/frontmatter-extractor';
diff --git a/src/core/lazy-section-renderer.ts b/src/core/lazy-section-renderer.ts
deleted file mode 100644
index 0280b5f..0000000
--- a/src/core/lazy-section-renderer.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: lazy-section-renderer has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/lazy-section-renderer';
diff --git a/src/core/markdown-converter.ts b/src/core/markdown-converter.ts
deleted file mode 100644
index f673b36..0000000
--- a/src/core/markdown-converter.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: markdown-converter has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/markdown-converter';
diff --git a/src/native-host/host.cjs b/src/native-host/host.cjs
deleted file mode 100755
index 3eb8592..0000000
--- a/src/native-host/host.cjs
+++ /dev/null
@@ -1,117 +0,0 @@
-#!/opt/homebrew/bin/node
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-const ALLOWED_EXTENSIONS = ['.md', '.markdown', '.mdx'];
-
-function readMessage() {
-  // Read 4-byte length prefix from stdin
-  const header = Buffer.alloc(4);
-  const bytesRead = fs.readSync(0, header, 0, 4, null);
-  if (bytesRead === 0) return null;
-
-  const length = header.readUInt32LE(0);
-  const body = Buffer.alloc(length);
-  fs.readSync(0, body, 0, length, null);
-  return JSON.parse(body.toString('utf8'));
-}
-
-function writeMessage(msg) {
-  const json = JSON.stringify(msg);
-  const header = Buffer.alloc(4);
-  header.writeUInt32LE(json.length, 0);
-  process.stdout.write(header);
-  process.stdout.write(json);
-}
-
-function validatePath(filePath) {
-  const ext = path.extname(filePath).toLowerCase();
-  if (!ALLOWED_EXTENSIONS.includes(ext)) {
-    return `Refused: not a markdown file (${ext || '<none>'})`;
-  }
-  return null;
-}
-
-function handleMessage(msg) {
-  if (!msg || typeof msg !== 'object') {
-    return writeMessage({ error: 'Invalid message format' });
-  }
-
-  if (msg.action === 'get_username') {
-    const os = require('os');
-    try {
-      return writeMessage({ success: true, username: os.userInfo().username });
-    } catch (err) {
-      return writeMessage({ error: err.message });
-    }
-  }
-
-  if (msg.action !== 'write') {
-    return writeMessage({ error: `Unknown action: ${msg.action}` });
-  }
-
-  if (!msg.path || typeof msg.path !== 'string') {
-    return writeMessage({ error: 'Missing or invalid path' });
-  }
-
-  if (msg.content === undefined || msg.content === null) {
-    return writeMessage({ error: 'Missing content' });
-  }
-
-  const pathError = validatePath(msg.path);
-  if (pathError) {
-    return writeMessage({ error: pathError });
-  }
-
-  try {
-    const existing = fs.readFileSync(msg.path, 'utf8');
-    const newContent = msg.content;
-
-    // Content boundary: earlier of v1 or v2 sentinel
-    const V1_SEP = '<!-- mdview:comments -->';
-    const V2_PREFIX = '<!-- mdview:annotations';
-
-    function findBoundary(text) {
-      const v1 = text.indexOf(V1_SEP);
-      const v2 = text.indexOf(V2_PREFIX);
-      if (v1 === -1 && v2 === -1) return -1;
-      if (v1 === -1) return v2;
-      if (v2 === -1) return v1;
-      return Math.min(v1, v2);
-    }
-
-    const existingBound = findBoundary(existing);
-    const newBound = findBoundary(newContent);
-    const existingBody = existingBound !== -1
-      ? existing.substring(0, existingBound).trimEnd()
-      : existing.trimEnd();
-    const newBody = newBound !== -1
-      ? newContent.substring(0, newBound).trimEnd()
-      : newContent.trimEnd();
-
-    // Strip both v1 and v2 marker formats for comparison
-    const V1_REF = /\[\^comment-\d+\]/g;
-    const V2_REF = /\[@\d+\]/g;
-    const existingClean = existingBody.replace(V1_REF, '').replace(V2_REF, '');
-    const newClean = newBody.replace(V1_REF, '').replace(V2_REF, '');
-
-    if (existingClean !== newClean) {
-      return writeMessage({
-        error: 'Refused: write would modify document content beyond comment markers. Only comment changes are allowed.'
-      });
-    }
-
-    fs.writeFileSync(msg.path, newContent, 'utf8');
-    writeMessage({ success: true });
-  } catch (err) {
-    writeMessage({ error: err.message });
-  }
-}
-
-// Main: read one message, handle it, exit
-const msg = readMessage();
-if (msg !== null) {
-  handleMessage(msg);
-}
diff --git a/src/native-host/install.sh b/src/native-host/install.sh
deleted file mode 100755
index 3558e53..0000000
--- a/src/native-host/install.sh
+++ /dev/null
@@ -1,39 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-HOST_SCRIPT="$SCRIPT_DIR/host.cjs"
-HOST_NAME="com.mdview.filewriter"
-
-# Determine manifest directory based on OS
-if [[ "$OSTYPE" == "darwin"* ]]; then
-  MANIFEST_DIR="$HOME/Library/Application Support/Google/Chrome/NativeMessagingHosts"
-elif [[ "$OSTYPE" == "linux"* ]]; then
-  MANIFEST_DIR="$HOME/.config/google-chrome/NativeMessagingHosts"
-else
-  echo "Unsupported OS: $OSTYPE" >&2
-  exit 1
-fi
-
-mkdir -p "$MANIFEST_DIR"
-
-# Get Chrome extension ID (user must provide or we use a wildcard)
-EXTENSION_ID="${1:-*}"
-
-# Write manifest with correct host path
-cat > "$MANIFEST_DIR/$HOST_NAME.json" << EOF
-{
-  "name": "$HOST_NAME",
-  "description": "MDView native messaging host for writing markdown files",
-  "path": "$HOST_SCRIPT",
-  "type": "stdio",
-  "allowed_origins": ["chrome-extension://$EXTENSION_ID/"]
-}
-EOF
-
-# Make host executable
-chmod +x "$HOST_SCRIPT"
-
-echo "Installed $HOST_NAME"
-echo "  Host: $HOST_SCRIPT"
-echo "  Manifest: $MANIFEST_DIR/$HOST_NAME.json"
diff --git a/src/renderers/mermaid-renderer.ts b/src/renderers/mermaid-renderer.ts
deleted file mode 100644
index 9cdd3eb..0000000
--- a/src/renderers/mermaid-renderer.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/renderers/mermaid-renderer';
diff --git a/src/renderers/syntax-highlighter.ts b/src/renderers/syntax-highlighter.ts
deleted file mode 100644
index 1a8969a..0000000
--- a/src/renderers/syntax-highlighter.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/renderers/syntax-highlighter';
diff --git a/src/themes/catppuccin-frappe.ts b/src/themes/catppuccin-frappe.ts
deleted file mode 100644
index b4efbed..0000000
--- a/src/themes/catppuccin-frappe.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from '../../packages/core/src/themes/catppuccin-frappe';
diff --git a/src/themes/catppuccin-latte.ts b/src/themes/catppuccin-latte.ts
deleted file mode 100644
index 0b868f9..0000000
--- a/src/themes/catppuccin-latte.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from '../../packages/core/src/themes/catppuccin-latte';
diff --git a/src/themes/catppuccin-macchiato.ts b/src/themes/catppuccin-macchiato.ts
deleted file mode 100644
index c48eba1..0000000
--- a/src/themes/catppuccin-macchiato.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from '../../packages/core/src/themes/catppuccin-macchiato';
diff --git a/src/themes/catppuccin-mocha.ts b/src/themes/catppuccin-mocha.ts
deleted file mode 100644
index 2202138..0000000
--- a/src/themes/catppuccin-mocha.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from '../../packages/core/src/themes/catppuccin-mocha';
diff --git a/src/themes/github-dark.ts b/src/themes/github-dark.ts
deleted file mode 100644
index 50edacf..0000000
--- a/src/themes/github-dark.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from '../../packages/core/src/themes/github-dark';
diff --git a/src/themes/github-light.ts b/src/themes/github-light.ts
deleted file mode 100644
index aaf8959..0000000
--- a/src/themes/github-light.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from '../../packages/core/src/themes/github-light';
diff --git a/src/themes/monokai-pro.ts b/src/themes/monokai-pro.ts
deleted file mode 100644
index d56cfe2..0000000
--- a/src/themes/monokai-pro.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from '../../packages/core/src/themes/monokai-pro';
diff --git a/src/themes/monokai.ts b/src/themes/monokai.ts
deleted file mode 100644
index 2cf4e24..0000000
--- a/src/themes/monokai.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from '../../packages/core/src/themes/monokai';
diff --git a/src/types/index.d.ts b/src/types/index.d.ts
deleted file mode 100644
index 81ebc2c..0000000
--- a/src/types/index.d.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: types have moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/types/index';
diff --git a/src/types/markdown-it-plugins.d.ts b/src/types/markdown-it-plugins.d.ts
deleted file mode 100644
index ea3eddb..0000000
--- a/src/types/markdown-it-plugins.d.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-/**
- * Type declarations for markdown-it plugins without official types
- */
-
-declare module 'markdown-it-attrs' {
-  import type MarkdownIt from 'markdown-it';
-  const markdownItAttrs: MarkdownIt.PluginWithOptions;
-  export default markdownItAttrs;
-}
-
-declare module 'markdown-it-task-lists' {
-  import type MarkdownIt from 'markdown-it';
-  const markdownItTaskLists: MarkdownIt.PluginWithOptions;
-  export default markdownItTaskLists;
-}
-
-declare module 'markdown-it-emoji' {
-  import type MarkdownIt from 'markdown-it';
-  const markdownItEmoji: MarkdownIt.PluginSimple;
-  export default markdownItEmoji;
-}
-
-declare module 'markdown-it-footnote' {
-  import type MarkdownIt from 'markdown-it';
-  const markdownItFootnote: MarkdownIt.PluginSimple;
-  export default markdownItFootnote;
-}
-
-
diff --git a/src/ui/toc-renderer.ts b/src/ui/toc-renderer.ts
deleted file mode 100644
index 5dd7fa4..0000000
--- a/src/ui/toc-renderer.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: toc-renderer has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/ui/toc-renderer';
diff --git a/src/utils/content-collector.ts b/src/utils/content-collector.ts
deleted file mode 100644
index d54809f..0000000
--- a/src/utils/content-collector.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: content-collector has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/utils/content-collector';
diff --git a/src/utils/docx-generator.ts b/src/utils/docx-generator.ts
deleted file mode 100644
index f816677..0000000
--- a/src/utils/docx-generator.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: docx-generator has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/utils/docx-generator';
diff --git a/src/utils/dom-purifier.ts b/src/utils/dom-purifier.ts
deleted file mode 100644
index 9bb58f7..0000000
--- a/src/utils/dom-purifier.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/utils/dom-purifier';
diff --git a/src/utils/filename-generator.ts b/src/utils/filename-generator.ts
deleted file mode 100644
index a33afba..0000000
--- a/src/utils/filename-generator.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/utils/filename-generator';
diff --git a/src/utils/pdf-generator.ts b/src/utils/pdf-generator.ts
deleted file mode 100644
index a176e41..0000000
--- a/src/utils/pdf-generator.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: pdf-generator has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/utils/pdf-generator';
diff --git a/src/utils/scroll-manager.ts b/src/utils/scroll-manager.ts
deleted file mode 100644
index b3794be..0000000
--- a/src/utils/scroll-manager.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/utils/scroll-manager';
diff --git a/src/utils/section-splitter.ts b/src/utils/section-splitter.ts
deleted file mode 100644
index 7fb20df..0000000
--- a/src/utils/section-splitter.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/utils/section-splitter';
diff --git a/src/utils/skeleton-renderer.ts b/src/utils/skeleton-renderer.ts
deleted file mode 100644
index 1703602..0000000
--- a/src/utils/skeleton-renderer.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/utils/skeleton-renderer';
diff --git a/src/utils/svg-converter.ts b/src/utils/svg-converter.ts
deleted file mode 100644
index d6e48d0..0000000
--- a/src/utils/svg-converter.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Re-export shim: svg-converter has moved to @mdview/core
-// This shim will be removed in Phase 2.9
-export * from '../../packages/core/src/utils/svg-converter';
diff --git a/src/utils/toc-stripper.ts b/src/utils/toc-stripper.ts
deleted file mode 100644
index b0b315f..0000000
--- a/src/utils/toc-stripper.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-/**
- * Re-export shim: delegates to @mdview/core and injects the Chrome extension logger.
- */
-export type { TocStripResult, TocStripperLogger } from '../../packages/core/src/utils/toc-stripper';
-
-import { stripTableOfContents as coreStripTableOfContents } from '../../packages/core/src/utils/toc-stripper';
-import { debug } from './debug-logger';
-
-/**
- * Strip Table of Contents sections from markdown.
- * This wrapper injects the extension's debug logger into the core implementation.
- */
-export function stripTableOfContents(markdown: string) {
-  return coreStripTableOfContents(markdown, debug);
-}
diff --git a/src/workers/render-worker.ts b/src/workers/render-worker.ts
deleted file mode 100644
index 643f989..0000000
--- a/src/workers/render-worker.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/workers/render-worker';
diff --git a/src/workers/tasks/highlight-task.ts b/src/workers/tasks/highlight-task.ts
deleted file mode 100644
index c662868..0000000
--- a/src/workers/tasks/highlight-task.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../../packages/core/src/workers/tasks/highlight-task';
diff --git a/src/workers/tasks/mermaid-task.ts b/src/workers/tasks/mermaid-task.ts
deleted file mode 100644
index 67f652a..0000000
--- a/src/workers/tasks/mermaid-task.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../../packages/core/src/workers/tasks/mermaid-task';
diff --git a/src/workers/tasks/parse-task.ts b/src/workers/tasks/parse-task.ts
deleted file mode 100644
index 670632c..0000000
--- a/src/workers/tasks/parse-task.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../../packages/core/src/workers/tasks/parse-task';
diff --git a/src/workers/worker-pool.ts b/src/workers/worker-pool.ts
deleted file mode 100644
index ba0edf6..0000000
--- a/src/workers/worker-pool.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '../../packages/core/src/workers/worker-pool';
diff --git a/tests/helpers/mocks.ts b/tests/helpers/mocks.ts
index 5908f15..3f39054 100644
--- a/tests/helpers/mocks.ts
+++ b/tests/helpers/mocks.ts
@@ -3,7 +3,7 @@
  */
 
 import { vi } from 'vitest';
-import type { Theme, ConversionResult, CachedResult } from '../../src/types';
+import type { Theme, ConversionResult, CachedResult } from '@mdview/core';
 import { mockTheme } from './fixtures';
 
 /**
@@ -175,7 +175,7 @@ export function createMockElement(tag: string = 'div'): HTMLElement {
  */
 export function createMockIntersectionObserver() {
   const observers: Array<{ element: Element; isIntersecting: boolean }> = [];
-  
+
   class MockIntersectionObserver implements IntersectionObserver {
     callback: IntersectionObserverCallback;
     options?: IntersectionObserverInit;
@@ -271,4 +271,3 @@ export function createMockCachedResult(overrides?: Partial<CachedResult>): Cache
     ...overrides,
   };
 }
-
diff --git a/tests/integration/annotation-migration.test.ts b/tests/integration/annotation-migration.test.ts
index 48bb1e9..490cced 100644
--- a/tests/integration/annotation-migration.test.ts
+++ b/tests/integration/annotation-migration.test.ts
@@ -6,9 +6,9 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { parseAnnotations } from '../../src/comments/annotation-parser';
-import { addComment } from '../../src/comments/annotation-serializer';
-import type { Comment } from '../../src/types';
+import { parseAnnotations } from '@mdview/core';
+import { addComment } from '@mdview/core';
+import type { Comment } from '@mdview/core';
 
 function makeNewComment(overrides: Partial<Comment> = {}): Comment {
   return {
@@ -42,7 +42,7 @@ Some text[^comment-1] here and target there.
     // All comments present
     const parsed = parseAnnotations(result);
     expect(parsed.comments.length).toBeGreaterThanOrEqual(2);
-    const migrated = parsed.comments.find(c => c.id === 'comment-1');
+    const migrated = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migrated).toBeDefined();
     expect(migrated!.selectedText).toBe('text');
     expect(migrated!.body).toBe('First comment body.');
@@ -57,7 +57,7 @@ Some text[^comment-1] here and target there.
 
     const result = addComment(v1Md, makeNewComment());
     const parsed = parseAnnotations(result);
-    const migrated = parsed.comments.find(c => c.id === 'comment-1');
+    const migrated = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migrated!.replies).toHaveLength(2);
     expect(migrated!.replies![0].author).toBe('bob');
     expect(migrated!.replies![1].author).toBe('carol');
@@ -72,7 +72,7 @@ Some text[^comment-1] here and target there.
 
     const result = addComment(v1Md, makeNewComment());
     const parsed = parseAnnotations(result);
-    const migrated = parsed.comments.find(c => c.id === 'comment-1');
+    const migrated = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migrated!.reactions).toBeDefined();
     expect(migrated!.reactions!['\u{1F44D}']).toEqual(['bob', 'carol']);
     expect(migrated!.reactions!['\u{2764}\u{FE0F}']).toEqual(['alice']);
@@ -87,7 +87,7 @@ Some text[^comment-1] here and target there.
 
     const result = addComment(v1Md, makeNewComment());
     const parsed = parseAnnotations(result);
-    const migrated = parsed.comments.find(c => c.id === 'comment-1');
+    const migrated = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migrated!.context).toBeDefined();
     expect(migrated!.context!.line).toBe(3);
     expect(migrated!.context!.section).toBe('Setup');
@@ -104,7 +104,7 @@ Some text[^comment-1] here and target there.
 
     const result = addComment(v1Md, makeNewComment());
     const parsed = parseAnnotations(result);
-    const migrated = parsed.comments.find(c => c.id === 'comment-1');
+    const migrated = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migrated!.resolved).toBe(true);
   });
 
@@ -117,7 +117,7 @@ Some text[^comment-1] here and target there.
 
     const result = addComment(v1Md, makeNewComment());
     const parsed = parseAnnotations(result);
-    const migrated = parsed.comments.find(c => c.id === 'comment-1');
+    const migrated = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migrated!.tags).toEqual(['blocking', 'nit']);
   });
 
@@ -149,8 +149,8 @@ Some text[^comment-1] here and target there.
     const parsed = parseAnnotations(result);
 
     expect(parsed.comments.length).toBeGreaterThanOrEqual(3);
-    const c1 = parsed.comments.find(c => c.id === 'comment-1');
-    const c2 = parsed.comments.find(c => c.id === 'comment-2');
+    const c1 = parsed.comments.find((c) => c.id === 'comment-1');
+    const c2 = parsed.comments.find((c) => c.id === 'comment-2');
     expect(c1!.body).toBe('First comment body.');
     expect(c2!.body).toBe('Second comment body.');
   });
@@ -183,7 +183,7 @@ Some text[^comment-1] here and target there.
 
     const result = addComment(v1Md, makeNewComment());
     const parsed = parseAnnotations(result);
-    const migrated = parsed.comments.find(c => c.id === 'comment-1');
+    const migrated = parsed.comments.find((c) => c.id === 'comment-1');
 
     expect(migrated!.resolved).toBe(true);
     expect(migrated!.context!.line).toBe(5);
diff --git a/tests/integration/annotation-v2.test.ts b/tests/integration/annotation-v2.test.ts
index 0082212..33c59a1 100644
--- a/tests/integration/annotation-v2.test.ts
+++ b/tests/integration/annotation-v2.test.ts
@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { parseAnnotations } from '../../src/comments/annotation-parser';
+import { parseAnnotations } from '@mdview/core';
 import {
   addComment,
   removeComment,
@@ -15,8 +15,8 @@ import {
   addReply,
   toggleReaction,
   generateNextCommentId,
-} from '../../src/comments/annotation-serializer';
-import type { Comment, CommentContext } from '../../src/types';
+} from '@mdview/core';
+import type { Comment, CommentContext } from '@mdview/core';
 
 function makeComment(overrides: Partial<Comment> = {}): Comment {
   return {
@@ -224,7 +224,7 @@ describe('Large document', () => {
 
     // Verify all comments are correctly anchored
     for (let i = 1; i <= 25; i++) {
-      const c = parsed.comments.find(c => c.id === `comment-${i}`);
+      const c = parsed.comments.find((c) => c.id === `comment-${i}`);
       expect(c).toBeDefined();
       expect(c!.selectedText).toBe(`unique-word-${i}`);
       expect(c!.body).toBe(`Comment ${i}`);
diff --git a/tests/integration/comments.test.ts b/tests/integration/comments.test.ts
index 815fbee..dad3892 100644
--- a/tests/integration/comments.test.ts
+++ b/tests/integration/comments.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseComments } from '../../src/comments/comment-parser';
+import { parseComments } from '@mdview/core';
 import {
   addComment,
   removeComment,
@@ -8,12 +8,13 @@ import {
   generateNextCommentId,
   addReply,
   toggleReaction,
-} from '../../src/comments/comment-serializer';
-import { computeCommentContext } from '../../src/comments/comment-context';
-import type { Comment } from '../../src/types';
+} from '../../packages/core/src/comments/comment-serializer';
+import { computeCommentContext } from '@mdview/core';
+import type { Comment } from '@mdview/core';
 
 describe('Comment System Integration', () => {
-  const baseMarkdown = '# Test Document\n\nThe quick brown fox jumps over the lazy dog.\n\nAnother paragraph here.';
+  const baseMarkdown =
+    '# Test Document\n\nThe quick brown fox jumps over the lazy dog.\n\nAnother paragraph here.';
 
   it('should round-trip: add comment then parse it back', () => {
     const comment: Comment = {
diff --git a/tests/integration/export-phase1.test.ts b/tests/integration/export-phase1.test.ts
index 5d26533..702a4a3 100644
--- a/tests/integration/export-phase1.test.ts
+++ b/tests/integration/export-phase1.test.ts
@@ -4,8 +4,8 @@
  */
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { ContentCollector } from '../../src/utils/content-collector';
-import { SVGConverter } from '../../src/utils/svg-converter';
+import { ContentCollector } from '@mdview/core';
+import { SVGConverter } from '@mdview/core';
 
 /**
  * Helper to create a comprehensive test container with various content types
@@ -484,5 +484,3 @@ describe('Phase 1 Integration', () => {
     });
   });
 });
-
-
diff --git a/tests/integration/export-phase2.test.ts b/tests/integration/export-phase2.test.ts
index 150f6fc..be03521 100644
--- a/tests/integration/export-phase2.test.ts
+++ b/tests/integration/export-phase2.test.ts
@@ -3,10 +3,10 @@
  */
 
 import { describe, test, expect, beforeEach, vi } from 'vitest';
-import { ExportController } from '../../src/core/export-controller';
-import { ContentCollector } from '../../src/utils/content-collector';
-import { SVGConverter } from '../../src/utils/svg-converter';
-import type { ExportProgress } from '../../src/types';
+import { ExportController } from '@mdview/core';
+import { ContentCollector } from '@mdview/core';
+import { SVGConverter } from '@mdview/core';
+import type { ExportProgress } from '@mdview/core';
 
 describe('Phase 2 Integration: DOCX Export', () => {
   let controller: ExportController;
@@ -385,4 +385,3 @@ describe('Phase 2 Integration: DOCX Export', () => {
     expect(allMessages).toContain('download');
   });
 });
-
diff --git a/tests/unit/comments/annotation-parser.test.ts b/tests/unit/comments/annotation-parser.test.ts
index 001d1d3..09e3c7b 100644
--- a/tests/unit/comments/annotation-parser.test.ts
+++ b/tests/unit/comments/annotation-parser.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, vi } from 'vitest';
-import { parseAnnotations, detectFormat } from '../../../src/comments/annotation-parser';
+import { parseAnnotations, detectFormat } from '@mdview/core';
 
 describe('detectFormat', () => {
   it('should detect v1 format from sentinel', () => {
@@ -587,7 +587,9 @@ describe('parseAnnotations', () => {
       expect(result.comments).toHaveLength(1);
       expect(result.comments[0].id).toBe('comment-1');
       expect(result.comments[0].selectedText).toBe('text');
-      expect(result.comments[0].body).toBe('This API endpoint needs error handling\nfor the 404 case.');
+      expect(result.comments[0].body).toBe(
+        'This API endpoint needs error handling\nfor the 404 case.'
+      );
       expect(result.comments[0].author).toBe('reviewer');
       expect(result.comments[0].date).toBe('2026-03-03T14:30:00Z');
       expect(result.comments[0].resolved).toBe(false);
diff --git a/tests/unit/comments/annotation-serializer.test.ts b/tests/unit/comments/annotation-serializer.test.ts
index 3bf1b61..92b8bd0 100644
--- a/tests/unit/comments/annotation-serializer.test.ts
+++ b/tests/unit/comments/annotation-serializer.test.ts
@@ -16,10 +16,10 @@ import {
   updateCommentMetadata,
   addReply,
   toggleReaction,
-} from '../../../src/comments/annotation-serializer';
-import { parseAnnotations } from '../../../src/comments/annotation-parser';
-import { buildSourceMap } from '../../../src/comments/source-position-map';
-import type { Comment, CommentContext, CommentReply } from '../../../src/types';
+} from '@mdview/core';
+import { parseAnnotations } from '@mdview/core';
+import { buildSourceMap } from '@mdview/core';
+import type { Comment, CommentContext, CommentReply } from '@mdview/core';
 
 function makeComment(overrides: Partial<Comment> = {}): Comment {
   return {
@@ -796,9 +796,7 @@ describe('round-trip: serialize then parse', () => {
     const comment = makeComment({
       context: sampleContext,
       tags: ['blocking', 'nit'],
-      replies: [
-        { id: 'reply-1', author: 'bob', body: 'Nice', date: '2026-03-04T10:00:00Z' },
-      ],
+      replies: [{ id: 'reply-1', author: 'bob', body: 'Nice', date: '2026-03-04T10:00:00Z' }],
       reactions: { '\u{1F44D}': ['bob'] },
       anchorPrefix: 'Some ',
       anchorSuffix: ' in',
@@ -842,7 +840,7 @@ describe('v1 input migration', () => {
     // All existing comments should be migrated
     const parsed = parseAnnotations(result);
     expect(parsed.comments.length).toBeGreaterThanOrEqual(2);
-    const migratedFirst = parsed.comments.find(c => c.id === 'comment-1');
+    const migratedFirst = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migratedFirst).toBeDefined();
     expect(migratedFirst!.selectedText).toBe('text');
     expect(migratedFirst!.body).toBe('First comment.');
@@ -863,7 +861,7 @@ describe('v1 input migration', () => {
 
     const result = addComment(v1Md, newComment);
     const parsed = parseAnnotations(result);
-    const migratedFirst = parsed.comments.find(c => c.id === 'comment-1');
+    const migratedFirst = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migratedFirst!.replies).toHaveLength(1);
     expect(migratedFirst!.reactions).toBeDefined();
   });
@@ -883,7 +881,7 @@ describe('v1 input migration', () => {
 
     const result = addComment(v1Md, newComment);
     const parsed = parseAnnotations(result);
-    const migratedFirst = parsed.comments.find(c => c.id === 'comment-1');
+    const migratedFirst = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migratedFirst!.resolved).toBe(true);
   });
 
@@ -902,7 +900,7 @@ describe('v1 input migration', () => {
 
     const result = addComment(v1Md, newComment);
     const parsed = parseAnnotations(result);
-    const migratedFirst = parsed.comments.find(c => c.id === 'comment-1');
+    const migratedFirst = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migratedFirst!.context).toBeDefined();
     expect(migratedFirst!.context!.line).toBe(3);
     expect(migratedFirst!.context!.section).toBe('Setup');
@@ -923,7 +921,7 @@ describe('v1 input migration', () => {
 
     const result = addComment(v1Md, newComment);
     const parsed = parseAnnotations(result);
-    const migratedFirst = parsed.comments.find(c => c.id === 'comment-1');
+    const migratedFirst = parsed.comments.find((c) => c.id === 'comment-1');
     expect(migratedFirst!.tags).toEqual(['blocking', 'nit']);
   });
 });
diff --git a/tests/unit/comments/comment-context.test.ts b/tests/unit/comments/comment-context.test.ts
index d89510a..a06e906 100644
--- a/tests/unit/comments/comment-context.test.ts
+++ b/tests/unit/comments/comment-context.test.ts
@@ -8,19 +8,13 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { computeCommentContext } from '../../../src/comments/comment-context';
+import { computeCommentContext } from '@mdview/core';
 
 // ─── Simple documents ────────────────────────────────────────────────
 
 describe('computeCommentContext', () => {
   it('should return line number and section for offset in a section', () => {
-    const md = [
-      '# Title',
-      '',
-      '## Installation',
-      '',
-      'Run npm install to get started.',
-    ].join('\n');
+    const md = ['# Title', '', '## Installation', '', 'Run npm install to get started.'].join('\n');
 
     // Offset pointing to "npm" on line 5 (0-indexed line 4)
     const offset = md.indexOf('npm');
@@ -51,11 +45,7 @@ describe('computeCommentContext', () => {
   });
 
   it('should handle document with no headings', () => {
-    const md = [
-      'Just some plain text.',
-      '',
-      'Another paragraph of text.',
-    ].join('\n');
+    const md = ['Just some plain text.', '', 'Another paragraph of text.'].join('\n');
 
     const offset = md.indexOf('Another');
     const ctx = computeCommentContext(md, offset);
@@ -83,11 +73,7 @@ describe('computeCommentContext', () => {
     expect(ctx.line).toBe(7);
     expect(ctx.section).toBe('Prerequisites');
     expect(ctx.sectionLevel).toBe(3);
-    expect(ctx.breadcrumb).toEqual([
-      'Getting Started',
-      'Installation',
-      'Prerequisites',
-    ]);
+    expect(ctx.breadcrumb).toEqual(['Getting Started', 'Installation', 'Prerequisites']);
   });
 
   it('should handle offset at the very start of document (offset 0)', () => {
@@ -102,13 +88,7 @@ describe('computeCommentContext', () => {
   });
 
   it('should handle offset at the end of document', () => {
-    const md = [
-      '# Title',
-      '',
-      '## Section',
-      '',
-      'Last word.',
-    ].join('\n');
+    const md = ['# Title', '', '## Section', '', 'Last word.'].join('\n');
 
     const offset = md.length;
     const ctx = computeCommentContext(md, offset);
@@ -120,13 +100,7 @@ describe('computeCommentContext', () => {
   });
 
   it('should handle skipped heading levels (h1 > h3, no h2)', () => {
-    const md = [
-      '# Title',
-      '',
-      '### Deep Section',
-      '',
-      'Content in deep section.',
-    ].join('\n');
+    const md = ['# Title', '', '### Deep Section', '', 'Content in deep section.'].join('\n');
 
     const offset = md.indexOf('Content');
     const ctx = computeCommentContext(md, offset);
@@ -164,13 +138,7 @@ describe('computeCommentContext', () => {
   });
 
   it('should handle offset on a heading line itself', () => {
-    const md = [
-      '# Title',
-      '',
-      '## Section Name',
-      '',
-      'Content.',
-    ].join('\n');
+    const md = ['# Title', '', '## Section Name', '', 'Content.'].join('\n');
 
     const offset = md.indexOf('## Section Name');
     const ctx = computeCommentContext(md, offset);
diff --git a/tests/unit/comments/comment-highlight.test.ts b/tests/unit/comments/comment-highlight.test.ts
index 9680014..ade0157 100644
--- a/tests/unit/comments/comment-highlight.test.ts
+++ b/tests/unit/comments/comment-highlight.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { CommentHighlighter } from '../../../src/comments/comment-highlight';
-import type { Comment } from '../../../src/types';
+import { CommentHighlighter } from '@mdview/core';
+import type { Comment } from '@mdview/core';
 
 describe('CommentHighlighter', () => {
   let container: HTMLElement;
@@ -76,9 +76,7 @@ describe('CommentHighlighter', () => {
       const span = highlighter.highlightComment(container, comment);
       expect(span!.textContent).toBe('sentence here');
       // The surrounding text should still be there
-      expect(container.textContent).toBe(
-        'Start of the sentence here and more.'
-      );
+      expect(container.textContent).toBe('Start of the sentence here and more.');
     });
 
     it('should highlight text spanning across inline elements', () => {
@@ -132,7 +130,8 @@ describe('CommentHighlighter', () => {
     });
 
     it('should highlight text spanning across block elements with whitespace normalization', () => {
-      container.innerHTML = '<h2>Migration path</h2><p>to the new platform requires careful planning.</p>';
+      container.innerHTML =
+        '<h2>Migration path</h2><p>to the new platform requires careful planning.</p>';
       const comment: Comment = {
         id: 'comment-1',
         selectedText: 'Migration path\nto the new platform',
@@ -223,9 +222,7 @@ describe('CommentHighlighter', () => {
       document.body.appendChild(container);
 
       highlighter.setActive('comment-1');
-      const span = container.querySelector(
-        '[data-comment-id="comment-1"]'
-      ) as HTMLElement;
+      const span = container.querySelector('[data-comment-id="comment-1"]') as HTMLElement;
       expect(span.classList.contains('active')).toBe(true);
 
       highlighter.clearActive();
@@ -242,9 +239,7 @@ describe('CommentHighlighter', () => {
       document.body.appendChild(container);
 
       highlighter.setResolved('comment-1');
-      const span = container.querySelector(
-        '[data-comment-id="comment-1"]'
-      ) as HTMLElement;
+      const span = container.querySelector('[data-comment-id="comment-1"]') as HTMLElement;
       expect(span.classList.contains('resolved')).toBe(true);
 
       document.body.removeChild(container);
diff --git a/tests/unit/comments/comment-manager.test.ts b/tests/unit/comments/comment-manager.test.ts
index 5cde54d..21fa300 100644
--- a/tests/unit/comments/comment-manager.test.ts
+++ b/tests/unit/comments/comment-manager.test.ts
@@ -6,16 +6,16 @@
  */
 
 import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
-import { CommentManager } from '../../../src/comments/comment-manager';
-import type { Comment, CommentParseResult, AppState, CommentTag } from '../../../src/types';
+import { CommentManager } from '../../../packages/chrome-ext/src/comments/comment-manager';
+import type { Comment, CommentParseResult, AppState, CommentTag } from '@mdview/core';
 
 // ── Mocks ──────────────────────────────────────────────────────────────────
 
-vi.mock('../../../src/comments/annotation-parser', () => ({
+vi.mock('../../../packages/core/src/comments/annotation-parser', () => ({
   parseComments: vi.fn(),
 }));
 
-vi.mock('../../../src/comments/annotation-serializer', () => ({
+vi.mock('../../../packages/core/src/comments/annotation-serializer', () => ({
   generateNextCommentId: vi.fn(),
   addComment: vi.fn(),
   addCommentAtOffset: vi.fn(),
@@ -27,7 +27,7 @@ vi.mock('../../../src/comments/annotation-serializer', () => ({
   toggleReaction: vi.fn(),
 }));
 
-vi.mock('../../../src/comments/source-position-map', () => ({
+vi.mock('../../../packages/core/src/comments/source-position-map', () => ({
   buildSourceMap: vi.fn(() => ({
     rawSource: '',
     plainText: '',
@@ -37,7 +37,7 @@ vi.mock('../../../src/comments/source-position-map', () => ({
   findInsertionPoint: vi.fn(() => 10),
 }));
 
-vi.mock('../../../src/comments/comment-context', () => ({
+vi.mock('../../../packages/core/src/comments/comment-context', () => ({
   computeCommentContext: vi.fn(() => ({
     line: 3,
     section: 'Title',
@@ -46,31 +46,33 @@ vi.mock('../../../src/comments/comment-context', () => ({
   })),
 }));
 
-vi.mock('../../../src/comments/comment-ui', () => ({
-  CommentUI: vi.fn().mockImplementation(() => ({
-    createGutter: vi.fn(() => document.createElement('div')),
-    renderCard: vi.fn(() => document.createElement('div')),
-    renderInputForm: vi.fn(() => document.createElement('div')),
-    renderReplyForm: vi.fn(() => document.createElement('div')),
-    renderEmojiPicker: vi.fn(() => document.createElement('div')),
-    setCurrentAuthor: vi.fn(),
-    showToast: vi.fn(),
-    destroy: vi.fn(),
-  })),
-}));
+vi.mock('../../../packages/core/src/comments/comment-ui', () => {
+  class MockCommentUI {
+    createGutter = vi.fn(() => document.createElement('div'));
+    renderCard = vi.fn(() => document.createElement('div'));
+    renderInputForm = vi.fn(() => document.createElement('div'));
+    renderReplyForm = vi.fn(() => document.createElement('div'));
+    renderEmojiPicker = vi.fn(() => document.createElement('div'));
+    setCurrentAuthor = vi.fn();
+    showToast = vi.fn();
+    destroy = vi.fn();
+  }
+  return { CommentUI: MockCommentUI };
+});
 
-vi.mock('../../../src/comments/comment-highlight', () => ({
-  CommentHighlighter: vi.fn().mockImplementation(() => ({
-    highlightComment: vi.fn(() => document.createElement('span')),
-    removeHighlight: vi.fn(),
-    setActive: vi.fn(),
-    clearActive: vi.fn(),
-    setResolved: vi.fn(),
-    getHighlightElement: vi.fn(),
-  })),
-}));
+vi.mock('../../../packages/core/src/comments/comment-highlight', () => {
+  class MockCommentHighlighter {
+    highlightComment = vi.fn(() => document.createElement('span'));
+    removeHighlight = vi.fn();
+    setActive = vi.fn();
+    clearActive = vi.fn();
+    setResolved = vi.fn();
+    getHighlightElement = vi.fn();
+  }
+  return { CommentHighlighter: MockCommentHighlighter };
+});
 
-import { parseComments } from '../../../src/comments/annotation-parser';
+import { parseComments } from '../../../packages/core/src/comments/annotation-parser';
 import {
   generateNextCommentId,
   addComment as serializerAddComment,
@@ -81,9 +83,9 @@ import {
   resolveComment as serializerResolveComment,
   addReply as serializerAddReply,
   toggleReaction as serializerToggleReaction,
-} from '../../../src/comments/annotation-serializer';
-import { computeCommentContext } from '../../../src/comments/comment-context';
-import { findInsertionPoint } from '../../../src/comments/source-position-map';
+} from '../../../packages/core/src/comments/annotation-serializer';
+import { computeCommentContext } from '../../../packages/core/src/comments/comment-context';
+import { findInsertionPoint } from '../../../packages/core/src/comments/source-position-map';
 
 const mockParseComments = vi.mocked(parseComments);
 const mockGenerateNextId = vi.mocked(generateNextCommentId);
@@ -158,7 +160,10 @@ describe('CommentManager', () => {
     mockSerializerUpdate.mockReturnValue('updated markdown after update');
     mockSerializerUpdateMetadata.mockImplementation((md) => md + ' with metadata');
     mockSerializerResolve.mockReturnValue('updated markdown after resolve');
-    mockSerializerAddReply.mockReturnValue({ markdown: 'updated markdown after reply', replyId: 'reply-1' });
+    mockSerializerAddReply.mockReturnValue({
+      markdown: 'updated markdown after reply',
+      replyId: 'reply-1',
+    });
     mockSerializerToggleReaction.mockReturnValue('updated markdown after reaction');
 
     manager = new CommentManager();
@@ -183,11 +188,7 @@ describe('CommentManager', () => {
     });
 
     test('stores author from preferences', async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
       // Verify the stored author is used when adding a new comment
       await manager.addComment('some text', 'new comment body');
@@ -199,13 +200,14 @@ describe('CommentManager', () => {
     });
 
     test('queries system username when commentAuthor is empty', async () => {
-      (chrome.runtime.sendMessage as ReturnType<typeof vi.fn>)
-        .mockImplementation((msg: { type: string }) => {
+      (chrome.runtime.sendMessage as ReturnType<typeof vi.fn>).mockImplementation(
+        (msg: { type: string }) => {
           if (msg.type === 'GET_USERNAME') {
             return Promise.resolve({ username: 'systemuser' });
           }
           return Promise.resolve({ success: true });
-        });
+        }
+      );
 
       const prefsWithNoAuthor = { ...defaultPreferences, commentAuthor: '' };
       await manager.initialize(sampleMarkdown, '/path/to/file.md', prefsWithNoAuthor);
@@ -221,13 +223,14 @@ describe('CommentManager', () => {
     });
 
     test('uses empty author if GET_USERNAME fails', async () => {
-      (chrome.runtime.sendMessage as ReturnType<typeof vi.fn>)
-        .mockImplementation((msg: { type: string }) => {
+      (chrome.runtime.sendMessage as ReturnType<typeof vi.fn>).mockImplementation(
+        (msg: { type: string }) => {
           if (msg.type === 'GET_USERNAME') {
             return Promise.reject(new Error('native host not installed'));
           }
           return Promise.resolve({ success: true });
-        });
+        }
+      );
 
       const prefsWithNoAuthor = { ...defaultPreferences, commentAuthor: '' };
       await manager.initialize(sampleMarkdown, '/path/to/file.md', prefsWithNoAuthor);
@@ -255,11 +258,7 @@ describe('CommentManager', () => {
 
   describe('addComment()', () => {
     beforeEach(async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('generates next ID and serializes into markdown', async () => {
@@ -370,11 +369,7 @@ describe('CommentManager', () => {
 
   describe('editComment()', () => {
     beforeEach(async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('updates body in serialized markdown and writes', async () => {
@@ -412,11 +407,7 @@ describe('CommentManager', () => {
         cleanedMarkdown: '# Title\n\nhello world\n',
         comments: [taggedComment],
       });
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('updates tags on existing comment in memory', async () => {
@@ -467,20 +458,13 @@ describe('CommentManager', () => {
 
   describe('resolveComment()', () => {
     beforeEach(async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('sets resolved flag and writes', async () => {
       await manager.resolveComment('comment-1');
 
-      expect(mockSerializerResolve).toHaveBeenCalledWith(
-        sampleMarkdown,
-        'comment-1'
-      );
+      expect(mockSerializerResolve).toHaveBeenCalledWith(sampleMarkdown, 'comment-1');
 
       expect(chrome.runtime.sendMessage).toHaveBeenCalledWith({
         type: 'WRITE_FILE',
@@ -501,20 +485,13 @@ describe('CommentManager', () => {
 
   describe('deleteComment()', () => {
     beforeEach(async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('removes comment and writes', async () => {
       await manager.deleteComment('comment-1');
 
-      expect(mockSerializerRemove).toHaveBeenCalledWith(
-        sampleMarkdown,
-        'comment-1'
-      );
+      expect(mockSerializerRemove).toHaveBeenCalledWith(sampleMarkdown, 'comment-1');
 
       expect(chrome.runtime.sendMessage).toHaveBeenCalledWith({
         type: 'WRITE_FILE',
@@ -534,16 +511,12 @@ describe('CommentManager', () => {
 
   describe('handleAddCommentRequest()', () => {
     beforeEach(async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('shows input form and adds comment on save', async () => {
       // Import the mock UI to check renderInputForm was called
-      const { CommentUI } = await import('../../../src/comments/comment-ui');
+      const { CommentUI } = await import('../../../packages/core/src/comments/comment-ui');
       const mockUIInstance = vi.mocked(CommentUI).mock.results[0].value as {
         renderInputForm: ReturnType<typeof vi.fn>;
         renderCard: ReturnType<typeof vi.fn>;
@@ -575,7 +548,7 @@ describe('CommentManager', () => {
     });
 
     test('does not add comment if body is empty on save', async () => {
-      const { CommentUI } = await import('../../../src/comments/comment-ui');
+      const { CommentUI } = await import('../../../packages/core/src/comments/comment-ui');
       const mockUIInstance = vi.mocked(CommentUI).mock.results[0].value as {
         renderInputForm: ReturnType<typeof vi.fn>;
       };
@@ -599,11 +572,7 @@ describe('CommentManager', () => {
 
   describe('isWriteInProgress()', () => {
     beforeEach(async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('returns true during writes and stays true during grace period', async () => {
@@ -618,9 +587,7 @@ describe('CommentManager', () => {
         resolveSendMessage = resolve;
       });
 
-      (chrome.runtime.sendMessage as ReturnType<typeof vi.fn>).mockReturnValue(
-        sendMessagePromise
-      );
+      (chrome.runtime.sendMessage as ReturnType<typeof vi.fn>).mockReturnValue(sendMessagePromise);
 
       // Start the write but don't await it yet
       const writePromise = manager.addComment('text', 'body');
@@ -649,11 +616,7 @@ describe('CommentManager', () => {
 
   describe('getComments()', () => {
     test('returns a copy of comments array', async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
       const comments1 = manager.getComments();
       const comments2 = manager.getComments();
@@ -671,14 +634,14 @@ describe('CommentManager', () => {
   describe('repositionAllCards()', () => {
     test('positions cards based on highlight Y and cascades overlaps', async () => {
       const { CommentHighlighter } = await import(
-        '../../../src/comments/comment-highlight'
+        '../../../packages/core/src/comments/comment-highlight'
       );
 
       // We need fresh initialization to get a highlighter instance
       const mgr = new CommentManager();
 
       // Set up card rendering to produce real elements with measurable height
-      const { CommentUI } = await import('../../../src/comments/comment-ui');
+      const { CommentUI } = await import('../../../packages/core/src/comments/comment-ui');
 
       // Create two comments at similar positions
       const comment1: Comment = {
@@ -804,11 +767,7 @@ describe('CommentManager', () => {
 
   describe('addReply()', () => {
     beforeEach(async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('calls serializer addReply with correct args and writes file', async () => {
@@ -848,11 +807,7 @@ describe('CommentManager', () => {
 
   describe('toggleReaction()', () => {
     beforeEach(async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
     });
 
     test('calls serializer toggleReaction and writes file', async () => {
@@ -912,14 +867,16 @@ describe('CommentManager', () => {
 
   describe('event wiring', () => {
     test('handles mdview:comment:reply event', async () => {
-      const { CommentUI } = await import('../../../src/comments/comment-ui');
+      const { CommentUI } = await import('../../../packages/core/src/comments/comment-ui');
 
       const mgr = new CommentManager();
 
       await mgr.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
       // Get the UI instance created during initialize
-      const mockUIInstance = vi.mocked(CommentUI).mock.results[vi.mocked(CommentUI).mock.results.length - 1].value as {
+      const mockUIInstance = vi.mocked(CommentUI).mock.results[
+        vi.mocked(CommentUI).mock.results.length - 1
+      ].value as {
         renderReplyForm: ReturnType<typeof vi.fn>;
         renderCard: ReturnType<typeof vi.fn>;
         setCurrentAuthor: ReturnType<typeof vi.fn>;
@@ -976,8 +933,10 @@ describe('CommentManager', () => {
     test('passes author to UI via setCurrentAuthor', async () => {
       await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
-      const { CommentUI } = await import('../../../src/comments/comment-ui');
-      const mockUIInstance = vi.mocked(CommentUI).mock.results[vi.mocked(CommentUI).mock.results.length - 1].value as {
+      const { CommentUI } = await import('../../../packages/core/src/comments/comment-ui');
+      const mockUIInstance = vi.mocked(CommentUI).mock.results[
+        vi.mocked(CommentUI).mock.results.length - 1
+      ].value as {
         setCurrentAuthor: ReturnType<typeof vi.fn>;
       };
 
@@ -990,9 +949,9 @@ describe('CommentManager', () => {
   describe('minimized card support', () => {
     test('handles mdview:comment:reposition event by repositioning cards', async () => {
       const { CommentHighlighter } = await import(
-        '../../../src/comments/comment-highlight'
+        '../../../packages/core/src/comments/comment-highlight'
       );
-      const { CommentUI } = await import('../../../src/comments/comment-ui');
+      const { CommentUI } = await import('../../../packages/core/src/comments/comment-ui');
 
       const mgr = new CommentManager();
 
@@ -1000,38 +959,51 @@ describe('CommentManager', () => {
       const highlight = document.createElement('span');
       document.body.appendChild(highlight);
       highlight.getBoundingClientRect = vi.fn(() => ({
-        top: 100, bottom: 120, left: 0, right: 100,
-        width: 100, height: 20, x: 0, y: 100, toJSON: () => ({}),
+        top: 100,
+        bottom: 120,
+        left: 0,
+        right: 100,
+        width: 100,
+        height: 20,
+        x: 0,
+        y: 100,
+        toJSON: () => ({}),
       }));
 
       // Mock highlighter
       const mockHighlighter = vi.mocked(CommentHighlighter);
-      mockHighlighter.mockImplementation(() => ({
-        highlightComment: vi.fn(),
-        removeHighlight: vi.fn(),
-        setActive: vi.fn(),
-        clearActive: vi.fn(),
-        setResolved: vi.fn(),
-        getHighlightElement: vi.fn(() => highlight),
-      }) as any);
+      mockHighlighter.mockImplementation(
+        () =>
+          ({
+            highlightComment: vi.fn(),
+            removeHighlight: vi.fn(),
+            setActive: vi.fn(),
+            clearActive: vi.fn(),
+            setResolved: vi.fn(),
+            getHighlightElement: vi.fn(() => highlight),
+          }) as any
+      );
 
       // Mock UI to produce real card elements
-      vi.mocked(CommentUI).mockImplementation(() => ({
-        createGutter: vi.fn(() => document.createElement('div')),
-        renderCard: vi.fn((comment: Comment) => {
-          const card = document.createElement('div');
-          card.className = 'mdview-comment-card';
-          card.dataset.commentId = comment.id;
-          Object.defineProperty(card, 'offsetHeight', { value: 40, configurable: true });
-          return card;
-        }),
-        renderInputForm: vi.fn(() => document.createElement('div')),
-        renderReplyForm: vi.fn(() => document.createElement('div')),
-        renderEmojiPicker: vi.fn(() => document.createElement('div')),
-        setCurrentAuthor: vi.fn(),
-        showToast: vi.fn(),
-        destroy: vi.fn(),
-      }) as any);
+      vi.mocked(CommentUI).mockImplementation(
+        () =>
+          ({
+            createGutter: vi.fn(() => document.createElement('div')),
+            renderCard: vi.fn((comment: Comment) => {
+              const card = document.createElement('div');
+              card.className = 'mdview-comment-card';
+              card.dataset.commentId = comment.id;
+              Object.defineProperty(card, 'offsetHeight', { value: 40, configurable: true });
+              return card;
+            }),
+            renderInputForm: vi.fn(() => document.createElement('div')),
+            renderReplyForm: vi.fn(() => document.createElement('div')),
+            renderEmojiPicker: vi.fn(() => document.createElement('div')),
+            setCurrentAuthor: vi.fn(),
+            showToast: vi.fn(),
+            destroy: vi.fn(),
+          }) as any
+      );
 
       await mgr.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
@@ -1042,8 +1014,15 @@ describe('CommentManager', () => {
 
       // Change the highlight position
       highlight.getBoundingClientRect = vi.fn(() => ({
-        top: 200, bottom: 220, left: 0, right: 100,
-        width: 100, height: 20, x: 0, y: 200, toJSON: () => ({}),
+        top: 200,
+        bottom: 220,
+        left: 0,
+        right: 100,
+        width: 100,
+        height: 20,
+        x: 0,
+        y: 200,
+        toJSON: () => ({}),
       }));
 
       // Dispatch reposition event
@@ -1058,28 +1037,31 @@ describe('CommentManager', () => {
     });
 
     test('refreshCardContent preserves minimized state on old card', async () => {
-      const { CommentUI } = await import('../../../src/comments/comment-ui');
+      const { CommentUI } = await import('../../../packages/core/src/comments/comment-ui');
 
       const mgr = new CommentManager();
 
       // Mock renderCard to produce cards with correct structure
       let renderCallCount = 0;
-      vi.mocked(CommentUI).mockImplementation(() => ({
-        createGutter: vi.fn(() => document.createElement('div')),
-        renderCard: vi.fn((comment: Comment) => {
-          renderCallCount++;
-          const card = document.createElement('div');
-          card.className = 'mdview-comment-card';
-          card.dataset.commentId = comment.id;
-          return card;
-        }),
-        renderInputForm: vi.fn(() => document.createElement('div')),
-        renderReplyForm: vi.fn(() => document.createElement('div')),
-        renderEmojiPicker: vi.fn(() => document.createElement('div')),
-        setCurrentAuthor: vi.fn(),
-        showToast: vi.fn(),
-        destroy: vi.fn(),
-      }) as any);
+      vi.mocked(CommentUI).mockImplementation(
+        () =>
+          ({
+            createGutter: vi.fn(() => document.createElement('div')),
+            renderCard: vi.fn((comment: Comment) => {
+              renderCallCount++;
+              const card = document.createElement('div');
+              card.className = 'mdview-comment-card';
+              card.dataset.commentId = comment.id;
+              return card;
+            }),
+            renderInputForm: vi.fn(() => document.createElement('div')),
+            renderReplyForm: vi.fn(() => document.createElement('div')),
+            renderEmojiPicker: vi.fn(() => document.createElement('div')),
+            setCurrentAuthor: vi.fn(),
+            showToast: vi.fn(),
+            destroy: vi.fn(),
+          }) as any
+      );
 
       await mgr.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
@@ -1100,25 +1082,28 @@ describe('CommentManager', () => {
     });
 
     test('refreshCardContent preserves minimized state when card was minimized', async () => {
-      const { CommentUI } = await import('../../../src/comments/comment-ui');
+      const { CommentUI } = await import('../../../packages/core/src/comments/comment-ui');
 
       const mgr = new CommentManager();
 
-      vi.mocked(CommentUI).mockImplementation(() => ({
-        createGutter: vi.fn(() => document.createElement('div')),
-        renderCard: vi.fn((comment: Comment) => {
-          const card = document.createElement('div');
-          card.className = 'mdview-comment-card minimized';
-          card.dataset.commentId = comment.id;
-          return card;
-        }),
-        renderInputForm: vi.fn(() => document.createElement('div')),
-        renderReplyForm: vi.fn(() => document.createElement('div')),
-        renderEmojiPicker: vi.fn(() => document.createElement('div')),
-        setCurrentAuthor: vi.fn(),
-        showToast: vi.fn(),
-        destroy: vi.fn(),
-      }) as any);
+      vi.mocked(CommentUI).mockImplementation(
+        () =>
+          ({
+            createGutter: vi.fn(() => document.createElement('div')),
+            renderCard: vi.fn((comment: Comment) => {
+              const card = document.createElement('div');
+              card.className = 'mdview-comment-card minimized';
+              card.dataset.commentId = comment.id;
+              return card;
+            }),
+            renderInputForm: vi.fn(() => document.createElement('div')),
+            renderReplyForm: vi.fn(() => document.createElement('div')),
+            renderEmojiPicker: vi.fn(() => document.createElement('div')),
+            setCurrentAuthor: vi.fn(),
+            showToast: vi.fn(),
+            destroy: vi.fn(),
+          }) as any
+      );
 
       await mgr.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
@@ -1143,18 +1128,13 @@ describe('CommentManager', () => {
 
   describe('destroy()', () => {
     test('cleans up UI', async () => {
-      await manager.initialize(
-        sampleMarkdown,
-        '/path/to/file.md',
-        defaultPreferences
-      );
+      await manager.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
       // Import the mock to verify destroy was called
-      const { CommentUI } = await import(
-        '../../../src/comments/comment-ui'
-      );
-      const mockInstance = vi.mocked(CommentUI).mock.results[0]
-        .value as { destroy: ReturnType<typeof vi.fn> };
+      const { CommentUI } = await import('@mdview/core');
+      const mockInstance = vi.mocked(CommentUI).mock.results[0].value as {
+        destroy: ReturnType<typeof vi.fn>;
+      };
 
       manager.destroy();
 
diff --git a/tests/unit/comments/comment-parser.test.ts b/tests/unit/comments/comment-parser.test.ts
index 6a3f568..d9bff7e 100644
--- a/tests/unit/comments/comment-parser.test.ts
+++ b/tests/unit/comments/comment-parser.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { parseComments } from '../../../src/comments/comment-parser';
+import { parseComments } from '@mdview/core';
 
 describe('parseComments', () => {
   describe('No comments', () => {
diff --git a/tests/unit/comments/comment-serializer.test.ts b/tests/unit/comments/comment-serializer.test.ts
index 84a121c..0073355 100644
--- a/tests/unit/comments/comment-serializer.test.ts
+++ b/tests/unit/comments/comment-serializer.test.ts
@@ -16,9 +16,9 @@ import {
   updateCommentMetadata,
   addReply,
   toggleReaction,
-} from '../../../src/comments/comment-serializer';
-import { buildSourceMap } from '../../../src/comments/source-position-map';
-import type { Comment, CommentContext, CommentReply } from '../../../src/types';
+} from '../../../packages/core/src/comments/comment-serializer';
+import { buildSourceMap } from '@mdview/core';
+import type { Comment, CommentContext, CommentReply } from '@mdview/core';
 
 function makeComment(overrides: Partial<Comment> = {}): Comment {
   return {
@@ -380,13 +380,9 @@ describe('resolveComment', () => {
     const result = resolveComment(md, 'comment-1');
 
     // comment-1 should be resolved
-    expect(result).toMatch(
-      /\[\^comment-1\]:.*"resolved":true/
-    );
+    expect(result).toMatch(/\[\^comment-1\]:.*"resolved":true/);
     // comment-2 should NOT have resolved
-    const comment2Line = result
-      .split('\n')
-      .find((l) => l.includes('[^comment-2]:'));
+    const comment2Line = result.split('\n').find((l) => l.includes('[^comment-2]:'));
     expect(comment2Line).toBeDefined();
     expect(comment2Line).not.toContain('"resolved"');
   });
@@ -602,7 +598,9 @@ describe('replies and reactions in metadata', () => {
     const comment = makeComment({ replies });
     const result = addComment(md, comment);
 
-    expect(result).toContain('"replies":[{"id":"reply-1","author":"bob","body":"Good catch","date":"2026-03-04T10:00:00Z"}]');
+    expect(result).toContain(
+      '"replies":[{"id":"reply-1","author":"bob","body":"Good catch","date":"2026-03-04T10:00:00Z"}]'
+    );
   });
 
   it('should omit replies when empty array', () => {
@@ -742,7 +740,9 @@ describe('addReply', () => {
     const { markdown, replyId } = addReply(mdWithComment, 'comment-1', reply);
 
     expect(replyId).toBe('reply-1');
-    expect(markdown).toContain('"replies":[{"id":"reply-1","author":"bob","body":"Good catch","date":"2026-03-04T10:00:00Z"}]');
+    expect(markdown).toContain(
+      '"replies":[{"id":"reply-1","author":"bob","body":"Good catch","date":"2026-03-04T10:00:00Z"}]'
+    );
   });
 
   it('should generate sequential reply IDs', () => {
diff --git a/tests/unit/comments/comment-ui.test.ts b/tests/unit/comments/comment-ui.test.ts
index 6338424..b316040 100644
--- a/tests/unit/comments/comment-ui.test.ts
+++ b/tests/unit/comments/comment-ui.test.ts
@@ -3,8 +3,8 @@
  */
 
 import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
-import { CommentUI } from '../../../src/comments/comment-ui';
-import type { Comment, CommentReply, CommentReactions } from '../../../src/types';
+import { CommentUI } from '@mdview/core';
+import type { Comment, CommentReply, CommentReactions } from '@mdview/core';
 
 describe('CommentUI', () => {
   let ui: CommentUI;
@@ -604,7 +604,13 @@ describe('CommentUI', () => {
       const tagPills = form.querySelectorAll('.comment-tag-picker .comment-tag-option');
       const tagNames = Array.from(tagPills).map((p) => p.textContent);
       expect(tagNames).toEqual([
-        'blocking', 'nit', 'suggestion', 'question', 'praise', 'todo', 'fyi',
+        'blocking',
+        'nit',
+        'suggestion',
+        'question',
+        'praise',
+        'todo',
+        'fyi',
       ]);
     });
 
@@ -692,7 +698,9 @@ describe('CommentUI', () => {
       const children = Array.from(form.children);
       const textareaIdx = children.findIndex((el) => el.tagName === 'TEXTAREA');
       const pickerIdx = children.findIndex((el) => el.classList.contains('comment-tag-picker'));
-      const actionsIdx = children.findIndex((el) => el.classList.contains('mdview-comment-input-actions'));
+      const actionsIdx = children.findIndex((el) =>
+        el.classList.contains('mdview-comment-input-actions')
+      );
 
       expect(textareaIdx).toBeLessThan(pickerIdx);
       expect(pickerIdx).toBeLessThan(actionsIdx);
@@ -970,11 +978,13 @@ describe('CommentUI', () => {
       const textarea = form.querySelector('textarea') as HTMLTextAreaElement;
       textarea.value = 'Keyboard reply';
 
-      textarea.dispatchEvent(new KeyboardEvent('keydown', {
-        key: 'Enter',
-        metaKey: true,
-        bubbles: true,
-      }));
+      textarea.dispatchEvent(
+        new KeyboardEvent('keydown', {
+          key: 'Enter',
+          metaKey: true,
+          bubbles: true,
+        })
+      );
 
       expect(onSave).toHaveBeenCalledWith('Keyboard reply');
     });
@@ -1107,11 +1117,7 @@ describe('CommentUI', () => {
     });
 
     test('should render search input', () => {
-      const picker = ui.renderEmojiPicker(
-        document.createElement('div'),
-        vi.fn(),
-        vi.fn()
-      );
+      const picker = ui.renderEmojiPicker(document.createElement('div'), vi.fn(), vi.fn());
 
       const searchInput = picker.querySelector('.emoji-picker-search');
       expect(searchInput).not.toBeNull();
@@ -1119,11 +1125,7 @@ describe('CommentUI', () => {
     });
 
     test('should render categorized grid', () => {
-      const picker = ui.renderEmojiPicker(
-        document.createElement('div'),
-        vi.fn(),
-        vi.fn()
-      );
+      const picker = ui.renderEmojiPicker(document.createElement('div'), vi.fn(), vi.fn());
 
       const grid = picker.querySelector('.emoji-picker-grid');
       expect(grid).not.toBeNull();
@@ -1135,11 +1137,7 @@ describe('CommentUI', () => {
 
     test('should call onSelect with emoji char when clicked', () => {
       const onSelect = vi.fn();
-      const picker = ui.renderEmojiPicker(
-        document.createElement('div'),
-        onSelect,
-        vi.fn()
-      );
+      const picker = ui.renderEmojiPicker(document.createElement('div'), onSelect, vi.fn());
       document.body.appendChild(picker);
 
       const firstQuickEmoji = picker.querySelector('.emoji-picker-quick button') as HTMLElement;
@@ -1150,11 +1148,7 @@ describe('CommentUI', () => {
     });
 
     test('should have correct class name', () => {
-      const picker = ui.renderEmojiPicker(
-        document.createElement('div'),
-        vi.fn(),
-        vi.fn()
-      );
+      const picker = ui.renderEmojiPicker(document.createElement('div'), vi.fn(), vi.fn());
 
       expect(picker.classList.contains('mdview-emoji-picker')).toBe(true);
     });
diff --git a/tests/unit/comments/emoji-data.test.ts b/tests/unit/comments/emoji-data.test.ts
index 3ccaefe..9cb1048 100644
--- a/tests/unit/comments/emoji-data.test.ts
+++ b/tests/unit/comments/emoji-data.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { QUICK_EMOJIS, EMOJI_CATEGORIES, searchEmojis } from '../../../src/comments/emoji-data';
+import { QUICK_EMOJIS, EMOJI_CATEGORIES, searchEmojis } from '@mdview/core';
 
 describe('QUICK_EMOJIS', () => {
   it('should have exactly 12 entries', () => {
diff --git a/tests/unit/comments/native-host.test.ts b/tests/unit/comments/native-host.test.ts
index 42c3fec..b541982 100644
--- a/tests/unit/comments/native-host.test.ts
+++ b/tests/unit/comments/native-host.test.ts
@@ -5,7 +5,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import * as fs from 'fs';
 import * as os from 'os';
-import { validatePath, handleMessage, ALLOWED_EXTENSIONS } from '../../../src/native-host/host-logic';
+import {
+  validatePath,
+  handleMessage,
+  ALLOWED_EXTENSIONS,
+} from '../../../packages/chrome-ext/src/native-host/host-logic';
 
 vi.mock('os');
 
@@ -187,14 +191,15 @@ describe('Native Host Message Handling', () => {
       expect(fs.writeFileSync).toHaveBeenCalledWith(
         '/docs/page.mdx',
         'import { Component } from "react"',
-        'utf8',
+        'utf8'
       );
       expect(result).toEqual({ success: true });
     });
 
     it('should accept v1 comment marker changes', () => {
       const existing = '# Doc\n\nSome text here.';
-      const withComment = '# Doc\n\nSome text[^comment-1] here.\n\n<!-- mdview:comments -->\n[^comment-1]: <!-- mdview:comment {"author":"a","date":"2026-01-01T00:00:00Z"} -->\n    note';
+      const withComment =
+        '# Doc\n\nSome text[^comment-1] here.\n\n<!-- mdview:comments -->\n[^comment-1]: <!-- mdview:comment {"author":"a","date":"2026-01-01T00:00:00Z"} -->\n    note';
       vi.mocked(fs.readFileSync).mockReturnValue(existing);
       vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
 
@@ -209,7 +214,8 @@ describe('Native Host Message Handling', () => {
 
     it('should accept v2 annotation marker changes', () => {
       const existing = '# Doc\n\nSome text here.';
-      const withAnnotation = '# Doc\n\nSome text[@1] here.\n\n<!-- mdview:annotations [{"id":1,"anchor":{"text":"text"},"body":"note","author":"a","date":"2026-01-01T00:00:00Z"}] -->';
+      const withAnnotation =
+        '# Doc\n\nSome text[@1] here.\n\n<!-- mdview:annotations [{"id":1,"anchor":{"text":"text"},"body":"note","author":"a","date":"2026-01-01T00:00:00Z"}] -->';
       vi.mocked(fs.readFileSync).mockReturnValue(existing);
       vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
 
@@ -224,7 +230,8 @@ describe('Native Host Message Handling', () => {
 
     it('should detect v2 sentinel as content boundary', () => {
       const existing = '# Doc\n\nSome text[@1] here.\n\n<!-- mdview:annotations [{"id":1}] -->';
-      const updated = '# Doc\n\nSome text[@1][@2] here.\n\n<!-- mdview:annotations [{"id":1},{"id":2}] -->';
+      const updated =
+        '# Doc\n\nSome text[@1][@2] here.\n\n<!-- mdview:annotations [{"id":1},{"id":2}] -->';
       vi.mocked(fs.readFileSync).mockReturnValue(existing);
       vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
 
@@ -238,7 +245,8 @@ describe('Native Host Message Handling', () => {
     });
 
     it('should accept v1 to v2 migration write', () => {
-      const existing = '# Doc\n\nSome text[^comment-1] here.\n\n<!-- mdview:comments -->\n[^comment-1]: stuff';
+      const existing =
+        '# Doc\n\nSome text[^comment-1] here.\n\n<!-- mdview:comments -->\n[^comment-1]: stuff';
       const migrated = '# Doc\n\nSome text[@1] here.\n\n<!-- mdview:annotations [{"id":1}] -->';
       vi.mocked(fs.readFileSync).mockReturnValue(existing);
       vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
diff --git a/tests/unit/comments/source-position-map.test.ts b/tests/unit/comments/source-position-map.test.ts
index 7f9bb33..58cefe7 100644
--- a/tests/unit/comments/source-position-map.test.ts
+++ b/tests/unit/comments/source-position-map.test.ts
@@ -6,10 +6,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import {
-  buildSourceMap,
-  findInsertionPoint,
-} from '../../../src/comments/source-position-map';
+import { buildSourceMap, findInsertionPoint } from '@mdview/core';
 
 // ─── buildSourceMap ──────────────────────────────────────────────────
 
diff --git a/tests/unit/core/export-controller.test.ts b/tests/unit/core/export-controller.test.ts
index e36d69e..1c2f281 100644
--- a/tests/unit/core/export-controller.test.ts
+++ b/tests/unit/core/export-controller.test.ts
@@ -4,18 +4,35 @@
 
 /* eslint-disable @typescript-eslint/unbound-method */
 import { describe, test, expect, beforeEach, vi, afterEach } from 'vitest';
-import { ExportController } from '../../../src/core/export-controller';
-import type { ExportProgress } from '../../../src/types';
+import { ExportController } from '@mdview/core';
+import type { ExportProgress } from '@mdview/core';
 
 // Don't mock modules - use real implementations
-vi.mock('../../../src/utils/debug-logger', () => ({
-  debug: {
+vi.mock('../../../packages/core/src/utils/debug-logger', () => {
+  const mockHelpers = {
     info: vi.fn(),
     warn: vi.fn(),
     error: vi.fn(),
     debug: vi.fn(),
-  },
-}));
+    log: vi.fn(),
+  };
+  return {
+    debug: mockHelpers,
+    createDebug: vi.fn(() => mockHelpers),
+    createDebugLogger: vi.fn(() => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    })),
+    DebugLogger: vi.fn().mockImplementation(() => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    })),
+  };
+});
 
 describe('ExportController', () => {
   let controller: ExportController;
diff --git a/tests/unit/core/frontmatter-extractor.test.ts b/tests/unit/core/frontmatter-extractor.test.ts
index e538724..f6e7e8e 100644
--- a/tests/unit/core/frontmatter-extractor.test.ts
+++ b/tests/unit/core/frontmatter-extractor.test.ts
@@ -3,10 +3,7 @@
  */
 
 import { describe, test, expect } from 'vitest';
-import {
-  extractFrontmatter,
-  renderFrontmatterHtml,
-} from '../../../src/core/frontmatter-extractor';
+import { extractFrontmatter, renderFrontmatterHtml } from '@mdview/core';
 
 describe('extractFrontmatter', () => {
   test('returns null frontmatter for empty string', () => {
diff --git a/tests/unit/core/markdown-converter.test.ts b/tests/unit/core/markdown-converter.test.ts
index 322528f..e0b9fd1 100644
--- a/tests/unit/core/markdown-converter.test.ts
+++ b/tests/unit/core/markdown-converter.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, test, expect, beforeEach } from 'vitest';
-import { MarkdownConverter } from '../../../src/core/markdown-converter';
+import { MarkdownConverter } from '@mdview/core';
 import { markdownSamples, expectedHtml } from '../../helpers/fixtures';
 import { assertHtmlMatches } from '../../helpers/test-utils';
 
@@ -316,7 +316,7 @@ describe('MarkdownConverter', () => {
   describe('Complex Document', () => {
     test('should render complex document with all features', async () => {
       const result = await converter.convert(markdownSamples.complex);
-      
+
       // Check all features are present
       expect(result.html).toContain('<h1');
       expect(result.html).toContain('<h2');
@@ -329,7 +329,7 @@ describe('MarkdownConverter', () => {
       expect(result.html).toContain('<blockquote>');
       expect(result.html).toContain('<a href');
       expect(result.html).toContain('<img');
-      
+
       // Check metadata
       expect(result.metadata.headings.length).toBeGreaterThan(0);
       expect(result.metadata.codeBlocks.length).toBeGreaterThan(0);
@@ -339,4 +339,3 @@ describe('MarkdownConverter', () => {
     });
   });
 });
-
diff --git a/tests/unit/core/mermaid-cache-race.test.ts b/tests/unit/core/mermaid-cache-race.test.ts
index d9602c3..1e93cc7 100644
--- a/tests/unit/core/mermaid-cache-race.test.ts
+++ b/tests/unit/core/mermaid-cache-race.test.ts
@@ -8,22 +8,24 @@
  */
 
 import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
-import { RenderPipeline } from '../../../src/core/render-pipeline';
+import { RenderPipeline } from '../../../packages/chrome-ext/src/core/render-pipeline';
 import { createTestContainer, cleanupTestContainer, mockConsole } from '../../helpers/test-utils';
 import { mockChromeRuntime, waitFor } from '../../helpers/mocks';
 
 // The mock renderAll should simulate what the real one does: change classes on containers
-const mockRenderAll = vi.fn().mockImplementation(async (container: HTMLElement) => {
-  // Simulate successful rendering: remove pending, add ready
-  const pending = container.querySelectorAll('.mermaid-container.mermaid-pending');
-  pending.forEach((el) => {
-    el.classList.remove('mermaid-pending');
-    el.classList.add('mermaid-ready');
-    el.innerHTML = '<div class="mermaid-rendered"><svg>rendered</svg></div>';
-  });
-});
+const { mockRenderAll } = vi.hoisted(() => ({
+  mockRenderAll: vi.fn().mockImplementation(async (container: HTMLElement) => {
+    // Simulate successful rendering: remove pending, add ready
+    const pending = container.querySelectorAll('.mermaid-container.mermaid-pending');
+    pending.forEach((el) => {
+      el.classList.remove('mermaid-pending');
+      el.classList.add('mermaid-ready');
+      el.innerHTML = '<div class="mermaid-rendered"><svg>rendered</svg></div>';
+    });
+  }),
+}));
 
-vi.mock('../../../src/renderers/mermaid-renderer', () => ({
+vi.mock('../../../packages/core/src/renderers/mermaid-renderer', () => ({
   mermaidRenderer: {
     renderAll: mockRenderAll,
     renderAllImmediate: vi.fn().mockResolvedValue(undefined),
@@ -32,7 +34,7 @@ vi.mock('../../../src/renderers/mermaid-renderer', () => ({
   },
 }));
 
-vi.mock('../../../src/renderers/syntax-highlighter', () => ({
+vi.mock('../../../packages/core/src/renderers/syntax-highlighter', () => ({
   syntaxHighlighter: {
     highlightVisible: vi.fn(),
     highlightAll: vi.fn(),
@@ -40,7 +42,7 @@ vi.mock('../../../src/renderers/syntax-highlighter', () => ({
   },
 }));
 
-vi.mock('../../../src/workers/worker-pool', () => ({
+vi.mock('../../../packages/core/src/workers/worker-pool', () => ({
   workerPool: {
     initialize: vi.fn().mockRejectedValue(new Error('file:// not supported')),
     execute: vi.fn(),
diff --git a/tests/unit/core/render-pipeline.test.ts b/tests/unit/core/render-pipeline.test.ts
index a6fecb3..bafa304 100644
--- a/tests/unit/core/render-pipeline.test.ts
+++ b/tests/unit/core/render-pipeline.test.ts
@@ -3,13 +3,13 @@
  */
 
 import { describe, test, expect, beforeEach, vi, afterEach } from 'vitest';
-import { RenderPipeline } from '../../../src/core/render-pipeline';
+import { RenderPipeline } from '../../../packages/chrome-ext/src/core/render-pipeline';
 import { markdownSamples } from '../../helpers/fixtures';
 import { mockChromeRuntime, waitFor } from '../../helpers/mocks';
 import { createTestContainer, cleanupTestContainer, mockConsole } from '../../helpers/test-utils';
 
-// Mock the worker pool module
-vi.mock('../../../src/workers/worker-pool', () => ({
+// Mock the worker pool module (internal to core's render-pipeline)
+vi.mock('../../../packages/core/src/workers/worker-pool', () => ({
   workerPool: {
     initialize: vi.fn().mockResolvedValue(undefined),
     execute: vi.fn().mockResolvedValue({
@@ -36,11 +36,11 @@ describe('RenderPipeline', () => {
   beforeEach(() => {
     // Suppress console output during tests to keep run clean
     consoleMock = mockConsole();
-    
+
     pipeline = new RenderPipeline();
     container = createTestContainer();
     mockChromeRuntime();
-    
+
     // Mock window.crypto for hash generation
     Object.defineProperty(global, 'crypto', {
       value: {
@@ -98,7 +98,7 @@ describe('RenderPipeline', () => {
 
     test('should sanitize HTML content', async () => {
       const malicious = '<script>alert("xss")</script>\n# Safe Content';
-      
+
       await pipeline.render({
         container,
         markdown: malicious,
@@ -182,7 +182,7 @@ describe('RenderPipeline', () => {
     test('should support multiple progress listeners', async () => {
       const callback1 = vi.fn();
       const callback2 = vi.fn();
-      
+
       pipeline.onProgress(callback1);
       pipeline.onProgress(callback2);
 
@@ -200,7 +200,7 @@ describe('RenderPipeline', () => {
     test('should cleanup listener on unsubscribe', async () => {
       const callback = vi.fn();
       const unsubscribe = pipeline.onProgress(callback);
-      
+
       unsubscribe();
 
       await pipeline.render({
@@ -234,7 +234,7 @@ describe('RenderPipeline', () => {
     test('should trigger progressive mode for large files', async () => {
       const largeMarkdown = 'a'.repeat(50000);
       const progressStages: string[] = [];
-      
+
       pipeline.onProgress((progress) => {
         progressStages.push(progress.stage);
       });
@@ -454,7 +454,7 @@ describe('RenderPipeline', () => {
     test('should escape HTML in error messages', async () => {
       // This test verifies the escapeHtml private method works
       const errorWithHtml = '<script>alert("xss")</script>';
-      
+
       // The pipeline should handle this safely
       expect(() => {
         (pipeline as any).escapeHtml(errorWithHtml);
@@ -563,14 +563,14 @@ describe('RenderPipeline', () => {
   describe('Performance', () => {
     test('should render small files quickly', async () => {
       const start = Date.now();
-      
+
       await pipeline.render({
         container,
         markdown: '# Small file\n\nSome content.',
         useCache: false,
         useWorkers: false,
       });
-      
+
       const duration = Date.now() - start;
       expect(duration).toBeLessThan(1000); // Should be much faster, but allowing margin
     });
@@ -589,4 +589,3 @@ describe('RenderPipeline', () => {
     });
   });
 });
-
diff --git a/tests/unit/core/theme-engine.test.ts b/tests/unit/core/theme-engine.test.ts
index ecf6651..43c1b1e 100644
--- a/tests/unit/core/theme-engine.test.ts
+++ b/tests/unit/core/theme-engine.test.ts
@@ -3,11 +3,98 @@
  */
 
 import { describe, test, expect, beforeEach, vi, afterEach } from 'vitest';
-import { ThemeEngine } from '../../../src/core/theme-engine';
+import { ThemeEngine } from '../../../packages/chrome-ext/src/core/theme-engine';
 import { mockTheme } from '../../helpers/fixtures';
 import { mockChromeStorage } from '../../helpers/mocks';
 import { mockConsole } from '../../helpers/test-utils';
 
+// Hoist the mock theme so it's available when vi.mock factory runs
+const { hoistedMockTheme } = vi.hoisted(() => ({
+  hoistedMockTheme: {
+    name: 'test-theme' as const,
+    displayName: 'Test Theme',
+    variant: 'light' as const,
+    author: 'Test Author',
+    version: '1.0.0',
+    colors: {
+      background: '#ffffff',
+      backgroundSecondary: '#f6f8fa',
+      backgroundTertiary: '#f0f0f0',
+      foreground: '#24292e',
+      foregroundSecondary: '#586069',
+      foregroundMuted: '#6a737d',
+      primary: '#0366d6',
+      secondary: '#28a745',
+      accent: '#f66a0a',
+      heading: '#24292e',
+      link: '#0366d6',
+      linkHover: '#0256c7',
+      linkVisited: '#6f42c1',
+      codeBackground: '#f6f8fa',
+      codeText: '#24292e',
+      codeKeyword: '#d73a49',
+      codeString: '#032f62',
+      codeComment: '#6a737d',
+      codeFunction: '#6f42c1',
+      border: '#e1e4e8',
+      borderLight: '#eaecef',
+      borderHeavy: '#d1d5da',
+      selection: '#c8e1ff',
+      highlight: '#fffbdd',
+      shadow: 'rgba(0, 0, 0, 0.1)',
+      success: '#28a745',
+      warning: '#ffd33d',
+      error: '#d73a49',
+      info: '#0366d6',
+      commentHighlight: 'rgba(255, 212, 59, 0.35)',
+      commentHighlightResolved: 'rgba(155, 155, 155, 0.2)',
+      commentCardBg: '#f6f8fa',
+    },
+    typography: {
+      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
+      codeFontFamily: '"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace',
+      baseFontSize: '16px',
+      baseLineHeight: 1.6,
+      h1Size: '2em',
+      h2Size: '1.5em',
+      h3Size: '1.25em',
+      h4Size: '1em',
+      h5Size: '0.875em',
+      h6Size: '0.85em',
+      fontWeightNormal: 400,
+      fontWeightBold: 600,
+      headingFontWeight: 600,
+    },
+    spacing: {
+      blockMargin: '1em 0',
+      paragraphMargin: '0 0 1em 0',
+      listItemMargin: '0.25em 0',
+      headingMargin: '1.5em 0 0.5em 0',
+      codeBlockPadding: '1em',
+      tableCellPadding: '0.5em 1em',
+    },
+    syntaxTheme: 'github',
+    mermaidTheme: {
+      theme: 'default' as const,
+      themeVariables: {
+        primaryColor: '#0366d6',
+        primaryTextColor: '#ffffff',
+        primaryBorderColor: '#0256c7',
+        lineColor: '#586069',
+        secondaryColor: '#28a745',
+        tertiaryColor: '#f66a0a',
+        background: '#ffffff',
+        mainBkg: '#f6f8fa',
+      },
+    },
+  },
+}));
+
+// Mock all theme modules so they return our mock theme (hoisted)
+vi.mock('../../../packages/core/src/themes/github-light', () => ({
+  default: hoistedMockTheme,
+}));
+
 describe('ThemeEngine', () => {
   let engine: ThemeEngine;
   let consoleMock: { restore: () => void };
@@ -16,11 +103,6 @@ describe('ThemeEngine', () => {
     consoleMock = mockConsole();
     engine = new ThemeEngine();
     mockChromeStorage();
-    
-    // Mock dynamic imports for themes
-    vi.mock('../../../src/themes/github-light.ts', () => ({
-      default: mockTheme,
-    }));
   });
 
   afterEach(() => {
@@ -31,13 +113,13 @@ describe('ThemeEngine', () => {
   describe('Theme Loading', () => {
     test('should load theme from cache on second request', async () => {
       // Mock the dynamic import
-      vi.doMock('../../../src/themes/github-light.ts', () => ({
+      vi.doMock('../../../packages/core/src/themes/github-light', () => ({
         default: { ...mockTheme, name: 'github-light' },
       }));
 
       const theme1 = await engine.loadTheme('github-light');
       const theme2 = await engine.loadTheme('github-light');
-      
+
       expect(theme1).toBeDefined();
       expect(theme2).toBeDefined();
       // Second call should return the same cached instance
@@ -45,25 +127,22 @@ describe('ThemeEngine', () => {
     });
 
     test('should cache theme after first load', async () => {
-      vi.doMock('../../../src/themes/github-light.ts', () => ({
+      vi.doMock('../../../packages/core/src/themes/github-light', () => ({
         default: { ...mockTheme, name: 'github-light' },
       }));
 
       const theme = await engine.loadTheme('github-light');
       expect(theme.name).toBe('github-light');
-      
+
       // Load again - should use cache
       const cachedTheme = await engine.loadTheme('github-light');
       expect(cachedTheme).toBe(theme);
     });
 
     test('should fallback to github-light on error', async () => {
-      // Mock a failing theme load
-      vi.doMock('../../../src/themes/invalid-theme.ts', () => {
-        throw new Error('Theme not found');
-      });
-      
-      vi.doMock('../../../src/themes/github-light.ts', () => ({
+      // Mock a failing theme load (invalid-theme is not in registry, so loadTheme
+      // catches the error and falls back to github-light)
+      vi.doMock('../../../packages/core/src/themes/github-light', () => ({
         default: { ...mockTheme, name: 'github-light' },
       }));
 
@@ -76,48 +155,48 @@ describe('ThemeEngine', () => {
     test('should apply theme object to document', async () => {
       const mockRoot = document.documentElement;
       await engine.applyTheme(mockTheme);
-      
+
       // Check that data attributes are set
       expect(mockRoot.getAttribute('data-theme')).toBe(mockTheme.name);
       expect(mockRoot.getAttribute('data-theme-variant')).toBe(mockTheme.variant);
     });
 
     test('should apply theme by name', async () => {
-      vi.doMock('../../../src/themes/github-light.ts', () => ({
+      vi.doMock('../../../packages/core/src/themes/github-light', () => ({
         default: { ...mockTheme, name: 'github-light' },
       }));
 
       await engine.applyTheme('github-light');
-      
+
       const current = engine.getCurrentTheme();
       expect(current?.name).toBe('github-light');
     });
 
     test('should compile CSS variables correctly', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       // Check color variables
       expect(cssVars['--md-bg']).toBe(mockTheme.colors.background);
       expect(cssVars['--md-fg']).toBe(mockTheme.colors.foreground);
       expect(cssVars['--md-primary']).toBe(mockTheme.colors.primary);
       expect(cssVars['--md-link']).toBe(mockTheme.colors.link);
-      
+
       // Check typography variables
       expect(cssVars['--md-font-family']).toBe(mockTheme.typography.fontFamily);
       expect(cssVars['--md-font-family-code']).toBe(mockTheme.typography.codeFontFamily);
       expect(cssVars['--md-font-size']).toBe(mockTheme.typography.baseFontSize);
-      
+
       // Check spacing variables
       expect(cssVars['--md-block-margin']).toBe(mockTheme.spacing.blockMargin);
     });
 
     test('should set all required CSS variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       // Count variables (should have ~50+ variables)
       const varCount = Object.keys(cssVars).length;
       expect(varCount).toBeGreaterThan(40);
-      
+
       // Check critical variables exist
       expect(cssVars['--md-bg']).toBeDefined();
       expect(cssVars['--md-fg']).toBeDefined();
@@ -127,31 +206,31 @@ describe('ThemeEngine', () => {
 
     test('should apply CSS variables to document root', async () => {
       await engine.applyTheme(mockTheme);
-      
+
       const root = document.documentElement;
       const bgColor = root.style.getPropertyValue('--md-bg');
-      
+
       // Variable should be set (exact value may vary based on processing)
       expect(bgColor).toBeTruthy();
     });
 
     test('should set data-theme attribute', async () => {
       await engine.applyTheme(mockTheme);
-      
+
       const theme = document.documentElement.getAttribute('data-theme');
       expect(theme).toBe(mockTheme.name);
     });
 
     test('should set data-theme-variant attribute', async () => {
       await engine.applyTheme(mockTheme);
-      
+
       const variant = document.documentElement.getAttribute('data-theme-variant');
       expect(variant).toBe(mockTheme.variant);
     });
 
     test('should apply background color directly to body', async () => {
       await engine.applyTheme(mockTheme);
-      
+
       // Browser converts hex to rgb format
       const bgColor = document.body.style.backgroundColor;
       expect(bgColor).toBeTruthy();
@@ -160,19 +239,22 @@ describe('ThemeEngine', () => {
 
     test('should add and remove transition class', async () => {
       const root = document.documentElement;
-      
+
       await engine.applyTheme(mockTheme);
-      
+
       // Transition class should eventually be removed (after animation frames)
       // We can't easily test timing, but we can verify it was added initially
-      expect(root.classList.contains('theme-transitioning') || !root.classList.contains('theme-transitioning')).toBe(true);
+      expect(
+        root.classList.contains('theme-transitioning') ||
+          !root.classList.contains('theme-transitioning')
+      ).toBe(true);
     });
   });
 
   describe('CSS Variable Generation', () => {
     test('should generate background color variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-bg']).toBe(mockTheme.colors.background);
       expect(cssVars['--md-bg-secondary']).toBe(mockTheme.colors.backgroundSecondary);
       expect(cssVars['--md-bg-tertiary']).toBe(mockTheme.colors.backgroundTertiary);
@@ -180,7 +262,7 @@ describe('ThemeEngine', () => {
 
     test('should generate foreground color variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-fg']).toBe(mockTheme.colors.foreground);
       expect(cssVars['--md-fg-secondary']).toBe(mockTheme.colors.foregroundSecondary);
       expect(cssVars['--md-fg-muted']).toBe(mockTheme.colors.foregroundMuted);
@@ -188,7 +270,7 @@ describe('ThemeEngine', () => {
 
     test('should generate semantic color variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-primary']).toBe(mockTheme.colors.primary);
       expect(cssVars['--md-secondary']).toBe(mockTheme.colors.secondary);
       expect(cssVars['--md-accent']).toBe(mockTheme.colors.accent);
@@ -196,7 +278,7 @@ describe('ThemeEngine', () => {
 
     test('should generate element color variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-heading']).toBe(mockTheme.colors.heading);
       expect(cssVars['--md-link']).toBe(mockTheme.colors.link);
       expect(cssVars['--md-code-bg']).toBe(mockTheme.colors.codeBackground);
@@ -205,7 +287,7 @@ describe('ThemeEngine', () => {
 
     test('should generate border color variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-border']).toBe(mockTheme.colors.border);
       expect(cssVars['--md-border-light']).toBe(mockTheme.colors.borderLight);
       expect(cssVars['--md-border-heavy']).toBe(mockTheme.colors.borderHeavy);
@@ -213,7 +295,7 @@ describe('ThemeEngine', () => {
 
     test('should generate state color variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-success']).toBe(mockTheme.colors.success);
       expect(cssVars['--md-warning']).toBe(mockTheme.colors.warning);
       expect(cssVars['--md-error']).toBe(mockTheme.colors.error);
@@ -222,14 +304,14 @@ describe('ThemeEngine', () => {
 
     test('should generate font family variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-font-family']).toBe(mockTheme.typography.fontFamily);
       expect(cssVars['--md-font-family-code']).toBe(mockTheme.typography.codeFontFamily);
     });
 
     test('should generate font size variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-font-size']).toBe(mockTheme.typography.baseFontSize);
       expect(cssVars['--md-h1-size']).toBe(mockTheme.typography.h1Size);
       expect(cssVars['--md-h2-size']).toBe(mockTheme.typography.h2Size);
@@ -241,21 +323,23 @@ describe('ThemeEngine', () => {
 
     test('should generate font weight variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-font-weight']).toBe(mockTheme.typography.fontWeightNormal.toString());
       expect(cssVars['--md-font-weight-bold']).toBe(mockTheme.typography.fontWeightBold.toString());
-      expect(cssVars['--md-heading-font-weight']).toBe(mockTheme.typography.headingFontWeight.toString());
+      expect(cssVars['--md-heading-font-weight']).toBe(
+        mockTheme.typography.headingFontWeight.toString()
+      );
     });
 
     test('should generate line height variable', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-line-height']).toBe(mockTheme.typography.baseLineHeight.toString());
     });
 
     test('should generate spacing variables', () => {
       const cssVars = engine.compileToCSSVariables(mockTheme);
-      
+
       expect(cssVars['--md-block-margin']).toBe(mockTheme.spacing.blockMargin);
       expect(cssVars['--md-paragraph-margin']).toBe(mockTheme.spacing.paragraphMargin);
       expect(cssVars['--md-list-item-margin']).toBe(mockTheme.spacing.listItemMargin);
@@ -270,9 +354,9 @@ describe('ThemeEngine', () => {
         codeFontFamily: 'Custom Mono',
         baseLineHeight: 2.0,
       };
-      
+
       const cssVars = engine.compileToCSSVariables(mockTheme, overrides);
-      
+
       expect(cssVars['--md-font-family']).toBe('Custom Font');
       expect(cssVars['--md-font-family-code']).toBe('Custom Mono');
       expect(cssVars['--md-line-height']).toBe('2');
@@ -283,17 +367,17 @@ describe('ThemeEngine', () => {
     test('should attach media query listener', () => {
       const callback = vi.fn();
       const cleanup = engine.watchSystemTheme(callback);
-      
+
       expect(callback).toHaveBeenCalled();
       expect(cleanup).toBeInstanceOf(Function);
-      
+
       cleanup();
     });
 
     test('should invoke callback on system theme change', () => {
       const callback = vi.fn();
       engine.watchSystemTheme(callback);
-      
+
       // Initial call
       expect(callback).toHaveBeenCalled();
     });
@@ -301,14 +385,14 @@ describe('ThemeEngine', () => {
     test('should cleanup listener on unsubscribe', () => {
       const callback = vi.fn();
       const cleanup = engine.watchSystemTheme(callback);
-      
+
       expect(() => cleanup()).not.toThrow();
     });
 
     test('should detect initial dark mode state', () => {
       const callback = vi.fn();
       engine.watchSystemTheme(callback);
-      
+
       expect(callback).toHaveBeenCalledWith(expect.any(Boolean));
     });
   });
@@ -321,7 +405,7 @@ describe('ThemeEngine', () => {
 
     test('should include theme info with name and display name', () => {
       const themes = engine.getAvailableThemes();
-      
+
       themes.forEach((theme) => {
         expect(theme.name).toBeDefined();
         expect(theme.displayName).toBeDefined();
@@ -332,7 +416,7 @@ describe('ThemeEngine', () => {
     test('should correctly flag light themes', () => {
       const themes = engine.getAvailableThemes();
       const lightThemes = themes.filter((t) => t.variant === 'light');
-      
+
       expect(lightThemes.length).toBeGreaterThan(0);
       expect(lightThemes.some((t) => t.name === 'github-light')).toBe(true);
     });
@@ -340,7 +424,7 @@ describe('ThemeEngine', () => {
     test('should correctly flag dark themes', () => {
       const themes = engine.getAvailableThemes();
       const darkThemes = themes.filter((t) => t.variant === 'dark');
-      
+
       expect(darkThemes.length).toBeGreaterThan(0);
       expect(darkThemes.some((t) => t.name === 'github-dark')).toBe(true);
     });
@@ -348,7 +432,7 @@ describe('ThemeEngine', () => {
     test('should include all expected themes', () => {
       const themes = engine.getAvailableThemes();
       const themeNames = themes.map((t) => t.name);
-      
+
       expect(themeNames).toContain('github-light');
       expect(themeNames).toContain('github-dark');
       expect(themeNames).toContain('catppuccin-latte');
@@ -368,17 +452,17 @@ describe('ThemeEngine', () => {
 
     test('should return current theme after application', async () => {
       await engine.applyTheme(mockTheme);
-      
+
       const current = engine.getCurrentTheme();
       expect(current).toBe(mockTheme);
     });
 
     test('should update current theme on theme change', async () => {
       await engine.applyTheme(mockTheme);
-      
+
       const newTheme = { ...mockTheme, name: 'github-dark' as const };
       await engine.applyTheme(newTheme);
-      
+
       const current = engine.getCurrentTheme();
       expect(current?.name).toBe('github-dark');
     });
@@ -390,20 +474,19 @@ describe('ThemeEngine', () => {
       for (let i = 0; i < 10; i++) {
         await engine.applyTheme(mockTheme);
       }
-      
+
       // Should complete without errors
       expect(engine.getCurrentTheme()).toBe(mockTheme);
     });
 
     test('should persist theme across operations', async () => {
       await engine.applyTheme(mockTheme);
-      
+
       const current1 = engine.getCurrentTheme();
       const current2 = engine.getCurrentTheme();
-      
+
       expect(current1).toBe(current2);
       expect(current1).toBe(mockTheme);
     });
   });
 });
-
diff --git a/tests/unit/renderers/mermaid-renderer.test.ts b/tests/unit/renderers/mermaid-renderer.test.ts
index 8db61c0..93d6121 100644
--- a/tests/unit/renderers/mermaid-renderer.test.ts
+++ b/tests/unit/renderers/mermaid-renderer.test.ts
@@ -12,7 +12,9 @@ vi.mock('mermaid', () => ({
   default: {
     initialize: vi.fn(),
     parse: vi.fn().mockResolvedValue({ diagramType: 'flowchart-v2', config: {} }),
-    render: vi.fn().mockResolvedValue({ svg: '<svg id="test">mock</svg>', diagramType: 'flowchart-v2' }),
+    render: vi
+      .fn()
+      .mockResolvedValue({ svg: '<svg id="test">mock</svg>', diagramType: 'flowchart-v2' }),
   },
 }));
 
@@ -30,7 +32,7 @@ vi.mock('panzoom', () => ({
 // Import after mocks are set up
 import mermaid from 'mermaid';
 import Panzoom from 'panzoom';
-import { MermaidRenderer } from '../../../src/renderers/mermaid-renderer';
+import { MermaidRenderer } from '@mdview/core';
 
 describe('MermaidRenderer', () => {
   let renderer: MermaidRenderer;
@@ -44,7 +46,10 @@ describe('MermaidRenderer', () => {
 
     // Reset mermaid mocks to success state
     vi.mocked(mermaid.parse).mockResolvedValue({ diagramType: 'flowchart-v2', config: {} });
-    vi.mocked(mermaid.render).mockResolvedValue({ svg: '<svg id="test">mock diagram</svg>', diagramType: 'flowchart-v2' });
+    vi.mocked(mermaid.render).mockResolvedValue({
+      svg: '<svg id="test">mock diagram</svg>',
+      diagramType: 'flowchart-v2',
+    });
 
     renderer = new MermaidRenderer();
   });
@@ -140,7 +145,10 @@ describe('MermaidRenderer', () => {
       let resolveFirst!: (value: { svg: string; diagramType: string }) => void;
       vi.mocked(mermaid.render)
         .mockImplementationOnce(
-          () => new Promise((resolve) => { resolveFirst = resolve; })
+          () =>
+            new Promise((resolve) => {
+              resolveFirst = resolve;
+            })
         )
         .mockResolvedValueOnce({ svg: '<svg>second</svg>', diagramType: 'flowchart-v2' });
 
diff --git a/tests/unit/ui/export-ui.test.ts b/tests/unit/ui/export-ui.test.ts
index 60af762..ad07790 100644
--- a/tests/unit/ui/export-ui.test.ts
+++ b/tests/unit/ui/export-ui.test.ts
@@ -3,10 +3,10 @@
  */
 
 import { describe, test, expect, beforeEach, vi, afterEach } from 'vitest';
-import { ExportUI } from '../../../src/ui/export-ui';
+import { ExportUI } from '../../../packages/chrome-ext/src/ui/export-ui';
 
 // Mock the debug logger
-vi.mock('../../../src/utils/debug-logger', () => ({
+vi.mock('../../../packages/chrome-ext/src/utils/debug-logger', () => ({
   debug: {
     info: vi.fn(),
     warn: vi.fn(),
@@ -15,8 +15,8 @@ vi.mock('../../../src/utils/debug-logger', () => ({
   },
 }));
 
-// Mock the ExportController
-vi.mock('../../../src/core/export-controller', () => {
+// Mock the ExportController (imported dynamically by the Chrome adapter)
+vi.mock('../../../packages/core/src/export-controller', () => {
   class MockExportController {
     export = vi.fn().mockResolvedValue(undefined);
   }
diff --git a/tests/unit/utils/content-collector.test.ts b/tests/unit/utils/content-collector.test.ts
index ce2b3c2..8cae0a5 100644
--- a/tests/unit/utils/content-collector.test.ts
+++ b/tests/unit/utils/content-collector.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, beforeEach } from 'vitest';
-import { ContentCollector } from '../../../src/utils/content-collector';
+import { ContentCollector } from '@mdview/core';
 
 /**
  * Helper to create a test container with HTML
@@ -545,5 +545,3 @@ line 3</code></pre>
     });
   });
 });
-
-
diff --git a/tests/unit/utils/docx-generator.test.ts b/tests/unit/utils/docx-generator.test.ts
index bb92d7a..8a320a1 100644
--- a/tests/unit/utils/docx-generator.test.ts
+++ b/tests/unit/utils/docx-generator.test.ts
@@ -3,8 +3,8 @@
  */
 
 import { describe, test, expect, beforeEach } from 'vitest';
-import { DOCXGenerator } from '../../../src/utils/docx-generator';
-import type { ContentNode, CollectedContent, ConvertedImage } from '../../../src/types';
+import { DOCXGenerator } from '@mdview/core';
+import type { ContentNode, CollectedContent, ConvertedImage } from '@mdview/core';
 
 describe('DOCXGenerator', () => {
   let generator: DOCXGenerator;
@@ -49,7 +49,9 @@ describe('DOCXGenerator', () => {
       const blob = await generator.generate(content, new Map());
 
       expect(blob).toBeInstanceOf(Blob);
-      expect(blob.type).toBe('application/vnd.openxmlformats-officedocument.wordprocessingml.document');
+      expect(blob.type).toBe(
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+      );
       expect(blob.size).toBeGreaterThan(0);
     });
 
@@ -394,7 +396,10 @@ describe('DOCXGenerator', () => {
     });
 
     test('should apply borders', async () => {
-      const tableData = [['A', 'B'], ['C', 'D']];
+      const tableData = [
+        ['A', 'B'],
+        ['C', 'D'],
+      ];
 
       const content = createTestContent([
         {
@@ -575,4 +580,3 @@ describe('DOCXGenerator', () => {
     });
   });
 });
-
diff --git a/tests/unit/utils/dom-purifier.test.ts b/tests/unit/utils/dom-purifier.test.ts
index 506f5ba..e642cf7 100644
--- a/tests/unit/utils/dom-purifier.test.ts
+++ b/tests/unit/utils/dom-purifier.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, test, expect, beforeEach } from 'vitest';
-import { DOMPurifierUtil } from '../../../src/utils/dom-purifier';
+import { DOMPurifierUtil } from '@mdview/core';
 import { xssPayloads } from '../../helpers/fixtures';
 
 describe('DOMPurifier', () => {
diff --git a/tests/unit/utils/file-scanner-blocklist.test.ts b/tests/unit/utils/file-scanner-blocklist.test.ts
index 6cd28d8..2799cc5 100644
--- a/tests/unit/utils/file-scanner-blocklist.test.ts
+++ b/tests/unit/utils/file-scanner-blocklist.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { FileScanner } from '../../../src/utils/file-scanner';
+import { FileScanner } from '../../../packages/chrome-ext/src/utils/file-scanner';
 
 describe('FileScanner Blocklist', () => {
   beforeEach(() => {
diff --git a/tests/unit/utils/filename-generator.test.ts b/tests/unit/utils/filename-generator.test.ts
index d157401..75e4478 100644
--- a/tests/unit/utils/filename-generator.test.ts
+++ b/tests/unit/utils/filename-generator.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, test, expect, beforeEach, vi } from 'vitest';
-import { FilenameGenerator } from '../../../src/utils/filename-generator';
+import { FilenameGenerator } from '@mdview/core';
 
 describe('FilenameGenerator', () => {
   beforeEach(() => {
@@ -180,4 +180,3 @@ describe('FilenameGenerator', () => {
     });
   });
 });
-
diff --git a/tests/unit/utils/pdf-generator.test.ts b/tests/unit/utils/pdf-generator.test.ts
index 0c67458..17fea67 100644
--- a/tests/unit/utils/pdf-generator.test.ts
+++ b/tests/unit/utils/pdf-generator.test.ts
@@ -3,20 +3,37 @@
  */
 
 import { describe, test, expect, beforeEach, vi, afterEach } from 'vitest';
-import { PDFGenerator } from '../../../src/utils/pdf-generator';
+import { PDFGenerator } from '@mdview/core';
 
-// Mock the debug logger
-vi.mock('../../../src/utils/debug-logger', () => ({
-  debug: {
+// Mock the debug logger (core internal)
+vi.mock('../../../packages/core/src/utils/debug-logger', () => {
+  const mockHelpers = {
     info: vi.fn(),
     warn: vi.fn(),
     error: vi.fn(),
     debug: vi.fn(),
-  },
-}));
+    log: vi.fn(),
+  };
+  return {
+    debug: mockHelpers,
+    createDebug: vi.fn(() => mockHelpers),
+    createDebugLogger: vi.fn(() => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    })),
+    DebugLogger: vi.fn().mockImplementation(() => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    })),
+  };
+});
 
-// Mock SVGConverter
-vi.mock('../../../src/utils/svg-converter', () => ({
+// Mock SVGConverter (core internal dependency of PDFGenerator)
+vi.mock('../../../packages/core/src/utils/svg-converter', () => ({
   SVGConverter: vi.fn().mockImplementation(() => ({
     convert: vi.fn().mockResolvedValue({
       id: 'test-svg',
@@ -28,8 +45,8 @@ vi.mock('../../../src/utils/svg-converter', () => ({
   })),
 }));
 
-// Mock mermaid renderer
-vi.mock('../../../src/renderers/mermaid-renderer', () => ({
+// Mock mermaid renderer (core internal dependency)
+vi.mock('../../../packages/core/src/renderers/mermaid-renderer', () => ({
   mermaidRenderer: {
     renderAllImmediate: vi.fn().mockResolvedValue(undefined),
   },
@@ -76,7 +93,9 @@ describe('PDFGenerator', () => {
     HTMLCanvasElement.prototype.getContext = vi.fn().mockReturnValue({
       drawImage: vi.fn(),
     });
-    HTMLCanvasElement.prototype.toDataURL = vi.fn().mockReturnValue('data:image/png;base64,mockdata');
+    HTMLCanvasElement.prototype.toDataURL = vi
+      .fn()
+      .mockReturnValue('data:image/png;base64,mockdata');
 
     // Mock getBoundingClientRect for SVGs
     Element.prototype.getBoundingClientRect = vi.fn().mockReturnValue({
@@ -247,7 +266,7 @@ describe('PDFGenerator', () => {
       svgContainer.appendChild(mermaidDiv);
 
       // Mock converter to throw error
-      const { SVGConverter } = await import('../../../src/utils/svg-converter');
+      const { SVGConverter } = await import('@mdview/core');
       (SVGConverter as any).mockImplementationOnce(() => ({
         convert: vi.fn().mockRejectedValue(new Error('Conversion failed')),
       }));
@@ -310,9 +329,7 @@ describe('PDFGenerator', () => {
         throw new Error('Print failed');
       });
 
-      await expect(
-        generator.print(svgContainer, { convertSvgsToImages: true })
-      ).rejects.toThrow();
+      await expect(generator.print(svgContainer, { convertSvgsToImages: true })).rejects.toThrow();
 
       // SVGs should be restored even on error
       const restoredSvg = mermaidDiv.querySelector('svg');
@@ -320,4 +337,3 @@ describe('PDFGenerator', () => {
     });
   });
 });
-
diff --git a/tests/unit/utils/svg-converter.test.ts b/tests/unit/utils/svg-converter.test.ts
index 4e19cba..086149d 100644
--- a/tests/unit/utils/svg-converter.test.ts
+++ b/tests/unit/utils/svg-converter.test.ts
@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect, beforeEach } from 'vitest';
-import { SVGConverter } from '../../../src/utils/svg-converter';
+import { SVGConverter } from '@mdview/core';
 
 /**
  * Helper to create a mock SVG element
diff --git a/tests/unit/utils/toc-stripper.test.ts b/tests/unit/utils/toc-stripper.test.ts
index 96a75c0..0150099 100644
--- a/tests/unit/utils/toc-stripper.test.ts
+++ b/tests/unit/utils/toc-stripper.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { stripTableOfContents } from '../../../src/utils/toc-stripper';
+import { stripTableOfContents } from '@mdview/core';
 
 describe('stripTableOfContents', () => {
   describe('Basic TOC Detection', () => {
diff --git a/tsconfig.json b/tsconfig.json
index fb19e33..4683906 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -17,10 +17,10 @@
     "types": ["chrome", "vite/client", "vitest/globals"],
     "baseUrl": ".",
     "paths": {
-      "@/*": ["src/*"]
+      "@/*": ["packages/chrome-ext/src/*"]
     }
   },
-  "include": ["src/**/*", "tests/**/*"],
+  "include": ["packages/*/src/**/*", "tests/**/*"],
   "exclude": ["node_modules", "dist"]
 }
 
diff --git a/vitest.config.ts b/vitest.config.ts
index 7ad0f8e..29f060a 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -28,7 +28,7 @@ export default defineConfig({
   },
   resolve: {
     alias: {
-      '@': resolve(__dirname, './src'),
+      '@': resolve(__dirname, './packages/chrome-ext/src'),
     },
   },
 });

From 235293b6c6671794c792809c468fad16903a88da Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 10:01:06 -0400
Subject: [PATCH 25/26] fix(tests): repair vi.mock factories for Node built-ins
 and class constructors

native-host.test.ts: provide explicit mock factories for 'fs' and 'os'
since vitest auto-mocking doesn't work with Node built-ins.

comment-manager.test.ts: convert vi.fn() constructor mocks from arrow
functions to function(this) syntax since arrow functions can't be used
as constructors with `new`.
---
 tests/unit/comments/comment-manager.test.ts | 223 +++++++++-----------
 tests/unit/comments/native-host.test.ts     |  11 +-
 2 files changed, 109 insertions(+), 125 deletions(-)

diff --git a/tests/unit/comments/comment-manager.test.ts b/tests/unit/comments/comment-manager.test.ts
index 21fa300..20ee1f3 100644
--- a/tests/unit/comments/comment-manager.test.ts
+++ b/tests/unit/comments/comment-manager.test.ts
@@ -47,29 +47,27 @@ vi.mock('../../../packages/core/src/comments/comment-context', () => ({
 }));
 
 vi.mock('../../../packages/core/src/comments/comment-ui', () => {
-  class MockCommentUI {
-    createGutter = vi.fn(() => document.createElement('div'));
-    renderCard = vi.fn(() => document.createElement('div'));
-    renderInputForm = vi.fn(() => document.createElement('div'));
-    renderReplyForm = vi.fn(() => document.createElement('div'));
-    renderEmojiPicker = vi.fn(() => document.createElement('div'));
-    setCurrentAuthor = vi.fn();
-    showToast = vi.fn();
-    destroy = vi.fn();
-  }
-  return { CommentUI: MockCommentUI };
+  const CommentUI = vi.fn();
+  CommentUI.prototype.createGutter = vi.fn(() => document.createElement('div'));
+  CommentUI.prototype.renderCard = vi.fn(() => document.createElement('div'));
+  CommentUI.prototype.renderInputForm = vi.fn(() => document.createElement('div'));
+  CommentUI.prototype.renderReplyForm = vi.fn(() => document.createElement('div'));
+  CommentUI.prototype.renderEmojiPicker = vi.fn(() => document.createElement('div'));
+  CommentUI.prototype.setCurrentAuthor = vi.fn();
+  CommentUI.prototype.showToast = vi.fn();
+  CommentUI.prototype.destroy = vi.fn();
+  return { CommentUI };
 });
 
 vi.mock('../../../packages/core/src/comments/comment-highlight', () => {
-  class MockCommentHighlighter {
-    highlightComment = vi.fn(() => document.createElement('span'));
-    removeHighlight = vi.fn();
-    setActive = vi.fn();
-    clearActive = vi.fn();
-    setResolved = vi.fn();
-    getHighlightElement = vi.fn();
-  }
-  return { CommentHighlighter: MockCommentHighlighter };
+  const CommentHighlighter = vi.fn();
+  CommentHighlighter.prototype.highlightComment = vi.fn(() => document.createElement('span'));
+  CommentHighlighter.prototype.removeHighlight = vi.fn();
+  CommentHighlighter.prototype.setActive = vi.fn();
+  CommentHighlighter.prototype.clearActive = vi.fn();
+  CommentHighlighter.prototype.setResolved = vi.fn();
+  CommentHighlighter.prototype.getHighlightElement = vi.fn();
+  return { CommentHighlighter };
 });
 
 import { parseComments } from '../../../packages/core/src/comments/annotation-parser';
@@ -699,45 +697,38 @@ describe('CommentManager', () => {
 
       // Mock highlighter to return these elements
       const mockHighlighter = vi.mocked(CommentHighlighter);
-      mockHighlighter.mockImplementation(
-        () =>
-          ({
-            highlightComment: vi.fn(),
-            removeHighlight: vi.fn(),
-            setActive: vi.fn(),
-            clearActive: vi.fn(),
-            setResolved: vi.fn(),
-            getHighlightElement: vi.fn((id: string) => {
-              if (id === 'comment-1') return highlight1;
-              if (id === 'comment-2') return highlight2;
-              return null;
-            }),
-          }) as any
-      );
+      mockHighlighter.mockImplementation(function (this: any) {
+        this.highlightComment = vi.fn();
+        this.removeHighlight = vi.fn();
+        this.setActive = vi.fn();
+        this.clearActive = vi.fn();
+        this.setResolved = vi.fn();
+        this.getHighlightElement = vi.fn((id: string) => {
+          if (id === 'comment-1') return highlight1;
+          if (id === 'comment-2') return highlight2;
+          return null;
+        });
+      } as any);
 
       // Cards will be rendered as real divs but with zero offsetHeight in jsdom
       // We mock offsetHeight via Object.defineProperty on the card elements
       const mockUIImpl = vi.mocked(CommentUI);
-      mockUIImpl.mockImplementation(
-        () =>
-          ({
-            createGutter: vi.fn(() => document.createElement('div')),
-            renderCard: vi.fn((comment: Comment) => {
-              const card = document.createElement('div');
-              card.className = 'mdview-comment-card';
-              card.dataset.commentId = comment.id;
-              // Give cards a height of 40px
-              Object.defineProperty(card, 'offsetHeight', { value: 40, configurable: true });
-              return card;
-            }),
-            renderInputForm: vi.fn(() => document.createElement('div')),
-            renderReplyForm: vi.fn(() => document.createElement('div')),
-            renderEmojiPicker: vi.fn(() => document.createElement('div')),
-            setCurrentAuthor: vi.fn(),
-            showToast: vi.fn(),
-            destroy: vi.fn(),
-          }) as any
-      );
+      mockUIImpl.mockImplementation(function (this: any) {
+        this.createGutter = vi.fn(() => document.createElement('div'));
+        this.renderCard = vi.fn((comment: Comment) => {
+          const card = document.createElement('div');
+          card.className = 'mdview-comment-card';
+          card.dataset.commentId = comment.id;
+          Object.defineProperty(card, 'offsetHeight', { value: 40, configurable: true });
+          return card;
+        });
+        this.renderInputForm = vi.fn(() => document.createElement('div'));
+        this.renderReplyForm = vi.fn(() => document.createElement('div'));
+        this.renderEmojiPicker = vi.fn(() => document.createElement('div'));
+        this.setCurrentAuthor = vi.fn();
+        this.showToast = vi.fn();
+        this.destroy = vi.fn();
+      } as any);
 
       await mgr.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
@@ -972,38 +963,32 @@ describe('CommentManager', () => {
 
       // Mock highlighter
       const mockHighlighter = vi.mocked(CommentHighlighter);
-      mockHighlighter.mockImplementation(
-        () =>
-          ({
-            highlightComment: vi.fn(),
-            removeHighlight: vi.fn(),
-            setActive: vi.fn(),
-            clearActive: vi.fn(),
-            setResolved: vi.fn(),
-            getHighlightElement: vi.fn(() => highlight),
-          }) as any
-      );
+      mockHighlighter.mockImplementation(function (this: any) {
+        this.highlightComment = vi.fn();
+        this.removeHighlight = vi.fn();
+        this.setActive = vi.fn();
+        this.clearActive = vi.fn();
+        this.setResolved = vi.fn();
+        this.getHighlightElement = vi.fn(() => highlight);
+      } as any);
 
       // Mock UI to produce real card elements
-      vi.mocked(CommentUI).mockImplementation(
-        () =>
-          ({
-            createGutter: vi.fn(() => document.createElement('div')),
-            renderCard: vi.fn((comment: Comment) => {
-              const card = document.createElement('div');
-              card.className = 'mdview-comment-card';
-              card.dataset.commentId = comment.id;
-              Object.defineProperty(card, 'offsetHeight', { value: 40, configurable: true });
-              return card;
-            }),
-            renderInputForm: vi.fn(() => document.createElement('div')),
-            renderReplyForm: vi.fn(() => document.createElement('div')),
-            renderEmojiPicker: vi.fn(() => document.createElement('div')),
-            setCurrentAuthor: vi.fn(),
-            showToast: vi.fn(),
-            destroy: vi.fn(),
-          }) as any
-      );
+      vi.mocked(CommentUI).mockImplementation(function (this: any) {
+        this.createGutter = vi.fn(() => document.createElement('div'));
+        this.renderCard = vi.fn((comment: Comment) => {
+          const card = document.createElement('div');
+          card.className = 'mdview-comment-card';
+          card.dataset.commentId = comment.id;
+          Object.defineProperty(card, 'offsetHeight', { value: 40, configurable: true });
+          return card;
+        });
+        this.renderInputForm = vi.fn(() => document.createElement('div'));
+        this.renderReplyForm = vi.fn(() => document.createElement('div'));
+        this.renderEmojiPicker = vi.fn(() => document.createElement('div'));
+        this.setCurrentAuthor = vi.fn();
+        this.showToast = vi.fn();
+        this.destroy = vi.fn();
+      } as any);
 
       await mgr.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
@@ -1043,25 +1028,22 @@ describe('CommentManager', () => {
 
       // Mock renderCard to produce cards with correct structure
       let renderCallCount = 0;
-      vi.mocked(CommentUI).mockImplementation(
-        () =>
-          ({
-            createGutter: vi.fn(() => document.createElement('div')),
-            renderCard: vi.fn((comment: Comment) => {
-              renderCallCount++;
-              const card = document.createElement('div');
-              card.className = 'mdview-comment-card';
-              card.dataset.commentId = comment.id;
-              return card;
-            }),
-            renderInputForm: vi.fn(() => document.createElement('div')),
-            renderReplyForm: vi.fn(() => document.createElement('div')),
-            renderEmojiPicker: vi.fn(() => document.createElement('div')),
-            setCurrentAuthor: vi.fn(),
-            showToast: vi.fn(),
-            destroy: vi.fn(),
-          }) as any
-      );
+      vi.mocked(CommentUI).mockImplementation(function (this: any) {
+        this.createGutter = vi.fn(() => document.createElement('div'));
+        this.renderCard = vi.fn((comment: Comment) => {
+          renderCallCount++;
+          const card = document.createElement('div');
+          card.className = 'mdview-comment-card';
+          card.dataset.commentId = comment.id;
+          return card;
+        });
+        this.renderInputForm = vi.fn(() => document.createElement('div'));
+        this.renderReplyForm = vi.fn(() => document.createElement('div'));
+        this.renderEmojiPicker = vi.fn(() => document.createElement('div'));
+        this.setCurrentAuthor = vi.fn();
+        this.showToast = vi.fn();
+        this.destroy = vi.fn();
+      } as any);
 
       await mgr.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
@@ -1086,24 +1068,21 @@ describe('CommentManager', () => {
 
       const mgr = new CommentManager();
 
-      vi.mocked(CommentUI).mockImplementation(
-        () =>
-          ({
-            createGutter: vi.fn(() => document.createElement('div')),
-            renderCard: vi.fn((comment: Comment) => {
-              const card = document.createElement('div');
-              card.className = 'mdview-comment-card minimized';
-              card.dataset.commentId = comment.id;
-              return card;
-            }),
-            renderInputForm: vi.fn(() => document.createElement('div')),
-            renderReplyForm: vi.fn(() => document.createElement('div')),
-            renderEmojiPicker: vi.fn(() => document.createElement('div')),
-            setCurrentAuthor: vi.fn(),
-            showToast: vi.fn(),
-            destroy: vi.fn(),
-          }) as any
-      );
+      vi.mocked(CommentUI).mockImplementation(function (this: any) {
+        this.createGutter = vi.fn(() => document.createElement('div'));
+        this.renderCard = vi.fn((comment: Comment) => {
+          const card = document.createElement('div');
+          card.className = 'mdview-comment-card minimized';
+          card.dataset.commentId = comment.id;
+          return card;
+        });
+        this.renderInputForm = vi.fn(() => document.createElement('div'));
+        this.renderReplyForm = vi.fn(() => document.createElement('div'));
+        this.renderEmojiPicker = vi.fn(() => document.createElement('div'));
+        this.setCurrentAuthor = vi.fn();
+        this.showToast = vi.fn();
+        this.destroy = vi.fn();
+      } as any);
 
       await mgr.initialize(sampleMarkdown, '/path/to/file.md', defaultPreferences);
 
diff --git a/tests/unit/comments/native-host.test.ts b/tests/unit/comments/native-host.test.ts
index b541982..ac45102 100644
--- a/tests/unit/comments/native-host.test.ts
+++ b/tests/unit/comments/native-host.test.ts
@@ -11,9 +11,14 @@ import {
   ALLOWED_EXTENSIONS,
 } from '../../../packages/chrome-ext/src/native-host/host-logic';
 
-vi.mock('os');
-
-vi.mock('fs');
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  writeFileSync: vi.fn(),
+}));
+
+vi.mock('os', () => ({
+  userInfo: vi.fn(),
+}));
 
 describe('Native Host Message Handling', () => {
   describe('ALLOWED_EXTENSIONS', () => {

From b9678eefa6ad9a80ae95c1dea8f0f4a42a231eec Mon Sep 17 00:00:00 2001
From: James Ainslie <42301770+jamesainslie@users.noreply.github.com>
Date: Fri, 20 Mar 2026 10:20:20 -0400
Subject: [PATCH 26/26] fix(chrome-ext): add build and dev scripts to
 package.json

---
 packages/chrome-ext/package.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/chrome-ext/package.json b/packages/chrome-ext/package.json
index 5c31fb2..3de5e54 100644
--- a/packages/chrome-ext/package.json
+++ b/packages/chrome-ext/package.json
@@ -3,6 +3,10 @@
   "version": "0.3.4",
   "private": true,
   "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
   "dependencies": {
     "@mdview/core": "*"
   },