@shaykec/bridge 0.4.20 → 0.4.22

package/src/visual-interceptor.test.js

@@ -0,0 +1,943 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { extractAndRouteVisuals, extractAndRouteSuggestions, extractAndRouteMedia, detectMediaUrl, extractButtons, extractInlineBlocks, stripCanvasCommands } from './visual-interceptor.js';
+
+describe('extractAndRouteVisuals', () => {
+  let tierManager, router;
+
+  beforeEach(() => {
+    tierManager = {
+      broadcastWs: vi.fn(),
+      broadcastSse: vi.fn(),
+      getTier: vi.fn(() => 2),
+    };
+    router = {
+      routeVisualCommand: vi.fn(),
+      tierManager,
+    };
+  });
+
+  it('does nothing when text is null or empty', () => {
+    extractAndRouteVisuals(null, tierManager, router);
+    extractAndRouteVisuals('', tierManager, router);
+    extractAndRouteVisuals(undefined, tierManager, router);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when text has no mermaid blocks', () => {
+    extractAndRouteVisuals('Here is some text without any code blocks.', tierManager, router);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+
+  it('does nothing for non-mermaid code blocks', () => {
+    const text = '```javascript\nconsole.log("hello");\n```';
+    extractAndRouteVisuals(text, tierManager, router);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+
+  it('extracts a single mermaid block', () => {
+    const text = 'Here is a diagram:\n\n```mermaid\ngraph TD\n  A-->B\n```\n\nNice!';
+    extractAndRouteVisuals(text, tierManager, router);
+
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+    const envelope = router.routeVisualCommand.mock.calls[0][0];
+    expect(envelope.type).toBe('canvas:diagram');
+    expect(envelope.payload.format).toBe('mermaid');
+    expect(envelope.payload.content).toBe('graph TD\n  A-->B');
+    expect(envelope.payload.autoRouted).toBe(true);
+  });
+
+  it('extracts multiple mermaid blocks', () => {
+    const text = [
+      '```mermaid',
+      'graph TD',
+      '  A-->B',
+      '```',
+      'Some text between',
+      '```mermaid',
+      'sequenceDiagram',
+      '  Alice->>Bob: Hello',
+      '```',
+    ].join('\n');
+
+    extractAndRouteVisuals(text, tierManager, router);
+
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(2);
+    expect(router.routeVisualCommand.mock.calls[0][0].payload.content).toBe('graph TD\n  A-->B');
+    expect(router.routeVisualCommand.mock.calls[1][0].payload.content).toBe('sequenceDiagram\n  Alice->>Bob: Hello');
+  });
+
+  it('ignores empty mermaid blocks', () => {
+    const text = '```mermaid\n\n```';
+    extractAndRouteVisuals(text, tierManager, router);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+
+  it('handles mermaid block with extra whitespace in fence', () => {
+    const text = '```mermaid  \ngraph LR\n  X-->Y\n```';
+    extractAndRouteVisuals(text, tierManager, router);
+
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+    expect(router.routeVisualCommand.mock.calls[0][0].payload.content).toBe('graph LR\n  X-->Y');
+  });
+
+  it('does not match nested triple backticks inside mermaid', () => {
+    const text = '```mermaid\ngraph TD\n  A["with ```backticks```"]-->B\n```';
+    extractAndRouteVisuals(text, tierManager, router);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it('handles non-string input gracefully', () => {
+    extractAndRouteVisuals(42, tierManager, router);
+    extractAndRouteVisuals({}, tierManager, router);
+    extractAndRouteVisuals([], tierManager, router);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+});
+
+describe('extractAndRouteSuggestions', () => {
+  let tierManager;
+
+  beforeEach(() => {
+    tierManager = {
+      broadcastWs: vi.fn(),
+      broadcastSse: vi.fn(),
+    };
+  });
+
+  it('does nothing when text is null, empty, or non-string', () => {
+    extractAndRouteSuggestions(null, tierManager);
+    extractAndRouteSuggestions('', tierManager);
+    extractAndRouteSuggestions(undefined, tierManager);
+    extractAndRouteSuggestions(42, tierManager);
+    expect(tierManager.broadcastWs).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when text has no suggestions comment', () => {
+    extractAndRouteSuggestions('Just a normal message.', tierManager);
+    expect(tierManager.broadcastWs).not.toHaveBeenCalled();
+  });
+
+  it('extracts valid suggestions and broadcasts', () => {
+    const text = 'Great explanation!\n<!-- suggestions: [{"label":"Quiz me","text":"/teach --quiz-only"},{"label":"Continue","text":"/teach"}] -->';
+    extractAndRouteSuggestions(text, tierManager);
+
+    expect(tierManager.broadcastWs).toHaveBeenCalledTimes(1);
+    expect(tierManager.broadcastSse).toHaveBeenCalledTimes(1);
+
+    const envelope = JSON.parse(tierManager.broadcastWs.mock.calls[0][0]);
+    expect(envelope.type).toBe('chat:suggestions');
+    expect(envelope.payload.suggestions).toHaveLength(2);
+    expect(envelope.payload.suggestions[0].label).toBe('Quiz me');
+    expect(envelope.payload.suggestions[1].text).toBe('/teach');
+  });
+
+  it('handles suggestions with extra whitespace in comment', () => {
+    const text = '<!--  suggestions:  [{"label":"Hint","text":"Give me a hint"}]  -->';
+    extractAndRouteSuggestions(text, tierManager);
+
+    expect(tierManager.broadcastWs).toHaveBeenCalledTimes(1);
+    const envelope = JSON.parse(tierManager.broadcastWs.mock.calls[0][0]);
+    expect(envelope.payload.suggestions).toHaveLength(1);
+    expect(envelope.payload.suggestions[0].label).toBe('Hint');
+  });
+
+  it('ignores malformed JSON in suggestions comment', () => {
+    const text = '<!-- suggestions: [not valid json] -->';
+    extractAndRouteSuggestions(text, tierManager);
+    expect(tierManager.broadcastWs).not.toHaveBeenCalled();
+  });
+
+  it('ignores empty suggestions array', () => {
+    const text = '<!-- suggestions: [] -->';
+    extractAndRouteSuggestions(text, tierManager);
+    expect(tierManager.broadcastWs).not.toHaveBeenCalled();
+  });
+
+  it('filters out suggestions missing label or text', () => {
+    const text = '<!-- suggestions: [{"label":"Valid","text":"/teach"},{"label":"No text"},{"text":"no label"}] -->';
+    extractAndRouteSuggestions(text, tierManager);
+
+    expect(tierManager.broadcastWs).toHaveBeenCalledTimes(1);
+    const envelope = JSON.parse(tierManager.broadcastWs.mock.calls[0][0]);
+    expect(envelope.payload.suggestions).toHaveLength(1);
+    expect(envelope.payload.suggestions[0].label).toBe('Valid');
+  });
+
+  it('does not broadcast when all suggestions are invalid', () => {
+    const text = '<!-- suggestions: [{"label":"No text"},{"text":"no label"}] -->';
+    extractAndRouteSuggestions(text, tierManager);
+    expect(tierManager.broadcastWs).not.toHaveBeenCalled();
+  });
+
+  it('preserves optional icon field', () => {
+    const text = '<!-- suggestions: [{"label":"Quiz","text":"/teach --quiz-only","icon":"quiz"}] -->';
+    extractAndRouteSuggestions(text, tierManager);
+
+    const envelope = JSON.parse(tierManager.broadcastWs.mock.calls[0][0]);
+    expect(envelope.payload.suggestions[0].icon).toBe('quiz');
+  });
+});
+
+describe('detectMediaUrl', () => {
+  it('detects YouTube URLs', () => {
+    expect(detectMediaUrl('https://www.youtube.com/watch?v=HVsySz-h9r4')).toBe('youtube');
+    expect(detectMediaUrl('https://youtu.be/HVsySz-h9r4')).toBe('youtube');
+  });
+
+  it('detects Vimeo URLs', () => {
+    expect(detectMediaUrl('https://vimeo.com/123456')).toBe('vimeo');
+  });
+
+  it('detects image URLs', () => {
+    expect(detectMediaUrl('https://example.com/pic.png')).toBe('image');
+    expect(detectMediaUrl('https://example.com/pic.jpg?w=100')).toBe('image');
+  });
+
+  it('detects video URLs', () => {
+    expect(detectMediaUrl('https://example.com/clip.mp4')).toBe('video');
+  });
+
+  it('returns link for generic URLs', () => {
+    expect(detectMediaUrl('https://example.com/page')).toBe('link');
+  });
+});
+
+describe('extractAndRouteMedia', () => {
+  let router, seenUrls;
+
+  beforeEach(() => {
+    router = { routeVisualCommand: vi.fn() };
+    seenUrls = new Set();
+  });
+
+  it('does nothing for null/empty/non-string text', () => {
+    extractAndRouteMedia(null, router, seenUrls);
+    extractAndRouteMedia('', router, seenUrls);
+    extractAndRouteMedia(undefined, router, seenUrls);
+    extractAndRouteMedia(42, router, seenUrls);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when text has no URLs', () => {
+    extractAndRouteMedia('Here is a plain message with no links.', router, seenUrls);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+
+  it('does nothing for generic link URLs (not embeddable)', () => {
+    extractAndRouteMedia('Check out https://example.com for details.', router, seenUrls);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+
+  it('routes YouTube URLs as canvas:html', () => {
+    extractAndRouteMedia('Watch this: https://www.youtube.com/watch?v=HVsySz-h9r4', router, seenUrls);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+    const env = router.routeVisualCommand.mock.calls[0][0];
+    expect(env.type).toBe('canvas:html');
+    expect(env.payload.subtype).toBe('youtube');
+    expect(env.payload.html).toContain('youtube.com/embed/HVsySz-h9r4');
+    expect(env.payload.autoRouted).toBe(true);
+  });
+
+  it('routes Vimeo URLs as canvas:html', () => {
+    extractAndRouteMedia('See https://vimeo.com/999999 for demo', router, seenUrls);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+    const env = router.routeVisualCommand.mock.calls[0][0];
+    expect(env.payload.subtype).toBe('vimeo');
+    expect(env.payload.html).toContain('player.vimeo.com/video/999999');
+  });
+
+  it('routes image URLs as canvas:html', () => {
+    extractAndRouteMedia('Here is a screenshot: https://example.com/screen.png', router, seenUrls);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+    const env = router.routeVisualCommand.mock.calls[0][0];
+    expect(env.payload.subtype).toBe('image');
+    expect(env.payload.html).toContain('<img');
+  });
+
+  it('routes video file URLs as canvas:html', () => {
+    extractAndRouteMedia('Download https://example.com/tutorial.mp4', router, seenUrls);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+    const env = router.routeVisualCommand.mock.calls[0][0];
+    expect(env.payload.subtype).toBe('video');
+    expect(env.payload.html).toContain('<video');
+  });
+
+  it('deduplicates: same URL is not routed twice', () => {
+    const text = 'Watch https://www.youtube.com/watch?v=HVsySz-h9r4 again';
+    extractAndRouteMedia(text, router, seenUrls);
+    extractAndRouteMedia(text, router, seenUrls);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it('respects MAX_AUTO_MEDIA limit (3)', () => {
+    const text = [
+      'https://www.youtube.com/watch?v=aaaaaaaaaaa',
+      'https://www.youtube.com/watch?v=bbbbbbbbbbb',
+      'https://www.youtube.com/watch?v=ccccccccccc',
+      'https://www.youtube.com/watch?v=ddddddddddd',
+    ].join(' ');
+    extractAndRouteMedia(text, router, seenUrls);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(3);
+  });
+
+  it('ignores URLs inside code fences', () => {
+    const text = '```\nhttps://www.youtube.com/watch?v=HVsySz-h9r4\n```';
+    extractAndRouteMedia(text, router, seenUrls);
+    expect(router.routeVisualCommand).not.toHaveBeenCalled();
+  });
+
+  it('routes URLs outside code fences even if code fences exist', () => {
+    const text = '```\nsome code\n```\nWatch https://www.youtube.com/watch?v=HVsySz-h9r4';
+    extractAndRouteMedia(text, router, seenUrls);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it('handles multiple different media types in one message', () => {
+    const text = 'Video: https://www.youtube.com/watch?v=aaaaaaaaaaa and image: https://example.com/pic.png';
+    extractAndRouteMedia(text, router, seenUrls);
+    expect(router.routeVisualCommand).toHaveBeenCalledTimes(2);
+    const types = router.routeVisualCommand.mock.calls.map(c => c[0].payload.subtype);
+    expect(types).toContain('youtube');
+    expect(types).toContain('image');
+  });
+});
+
+describe('extractButtons', () => {
+  it('returns empty buttons for null, empty, or non-string input', () => {
+    expect(extractButtons(null)).toEqual({ cleanText: '', buttons: [] });
+    expect(extractButtons('')).toEqual({ cleanText: '', buttons: [] });
+    expect(extractButtons(undefined)).toEqual({ cleanText: '', buttons: [] });
+    expect(extractButtons(42)).toEqual({ cleanText: '', buttons: [] });
+  });
+
+  it('returns original text when no buttons comment exists', () => {
+    const text = 'Just a normal message with no buttons.';
+    const result = extractButtons(text);
+    expect(result.cleanText).toBe(text);
+    expect(result.buttons).toEqual([]);
+  });
+
+  it('extracts a single button block and strips it from text', () => {
+    const text = 'Pick a topic:\n\n<!-- buttons: {"id":"topic-1","type":"single","prompt":"Choose:","options":[{"label":"A","value":"Option A"},{"label":"B","value":"Option B"}]} -->\n\nLet me know!';
+    const result = extractButtons(text);
+
+    expect(result.buttons).toHaveLength(1);
+    expect(result.buttons[0].id).toBe('topic-1');
+    expect(result.buttons[0].type).toBe('single');
+    expect(result.buttons[0].prompt).toBe('Choose:');
+    expect(result.buttons[0].options).toHaveLength(2);
+    expect(result.buttons[0].options[0]).toEqual({ label: 'A', value: 'Option A' });
+    expect(result.cleanText).not.toContain('<!-- buttons:');
+    expect(result.cleanText).toContain('Pick a topic:');
+    expect(result.cleanText).toContain('Let me know!');
+  });
+
+  it('extracts multiple button blocks', () => {
+    const text = [
+      'First choice:',
+      '<!-- buttons: {"id":"q1","type":"single","options":[{"label":"Yes","value":"yes"},{"label":"No","value":"no"}]} -->',
+      'Second choice:',
+      '<!-- buttons: {"id":"q2","type":"rating","prompt":"Rate it:","options":[{"label":"1","value":"1"},{"label":"2","value":"2"},{"label":"3","value":"3"}]} -->',
+    ].join('\n');
+
+    const result = extractButtons(text);
+    expect(result.buttons).toHaveLength(2);
+    expect(result.buttons[0].id).toBe('q1');
+    expect(result.buttons[0].type).toBe('single');
+    expect(result.buttons[1].id).toBe('q2');
+    expect(result.buttons[1].type).toBe('rating');
+    expect(result.cleanText).not.toContain('<!-- buttons:');
+  });
+
+  it('ignores malformed JSON in buttons comment', () => {
+    const text = 'Hello\n<!-- buttons: {not valid json} -->\nWorld';
+    const result = extractButtons(text);
+    expect(result.buttons).toEqual([]);
+    expect(result.cleanText).toContain('Hello');
+  });
+
+  it('ignores buttons with missing id', () => {
+    const text = '<!-- buttons: {"type":"single","options":[{"label":"A","value":"a"}]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toEqual([]);
+  });
+
+  it('ignores buttons with invalid type', () => {
+    const text = '<!-- buttons: {"id":"x","type":"dropdown","options":[{"label":"A","value":"a"}]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toEqual([]);
+  });
+
+  it('ignores buttons with empty options array', () => {
+    const text = '<!-- buttons: {"id":"x","type":"single","options":[]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toEqual([]);
+  });
+
+  it('ignores buttons with no options field', () => {
+    const text = '<!-- buttons: {"id":"x","type":"single"} -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toEqual([]);
+  });
+
+  it('filters out options missing label or value', () => {
+    const text = '<!-- buttons: {"id":"x","type":"single","options":[{"label":"Valid","value":"v"},{"label":"No value"},{"value":"no label"}]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toHaveLength(1);
+    expect(result.buttons[0].options).toHaveLength(1);
+    expect(result.buttons[0].options[0].label).toBe('Valid');
+  });
+
+  it('drops button block entirely when all options are invalid', () => {
+    const text = '<!-- buttons: {"id":"x","type":"single","options":[{"label":"No value"},{"value":"no label"}]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toEqual([]);
+  });
+
+  it('handles extra whitespace in comment delimiters', () => {
+    const text = '<!--  buttons:  {"id":"x","type":"single","options":[{"label":"A","value":"a"}]}  -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toHaveLength(1);
+    expect(result.buttons[0].id).toBe('x');
+  });
+
+  it('accepts all three valid types: single, multi, rating', () => {
+    for (const type of ['single', 'multi', 'rating']) {
+      const text = `<!-- buttons: {"id":"t-${type}","type":"${type}","options":[{"label":"A","value":"a"}]} -->`;
+      const result = extractButtons(text);
+      expect(result.buttons).toHaveLength(1);
+      expect(result.buttons[0].type).toBe(type);
+    }
+  });
+
+  it('omits prompt field when not provided', () => {
+    const text = '<!-- buttons: {"id":"x","type":"single","options":[{"label":"A","value":"a"}]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons[0].prompt).toBeUndefined();
+  });
+
+  it('preserves prompt field when provided', () => {
+    const text = '<!-- buttons: {"id":"x","type":"single","prompt":"Choose one:","options":[{"label":"A","value":"a"}]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons[0].prompt).toBe('Choose one:');
+  });
+
+  it('handles buttons mixed with suggestions comment', () => {
+    const text = 'Hello\n<!-- buttons: {"id":"x","type":"single","options":[{"label":"A","value":"a"}]} -->\n<!-- suggestions: [{"label":"Continue","text":"/teach"}] -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toHaveLength(1);
+    expect(result.cleanText).toContain('<!-- suggestions:');
+  });
+
+  it('does not strip non-button HTML comments', () => {
+    const text = 'Hello <!-- this is a regular comment --> world';
+    const result = extractButtons(text);
+    expect(result.buttons).toEqual([]);
+    expect(result.cleanText).toBe(text);
+  });
+
+  it('handles button block at the very start of text', () => {
+    const text = '<!-- buttons: {"id":"first","type":"single","options":[{"label":"Go","value":"go"}]} -->\nThen some text.';
+    const result = extractButtons(text);
+    expect(result.buttons).toHaveLength(1);
+    expect(result.buttons[0].id).toBe('first');
+    expect(result.cleanText).toContain('Then some text.');
+    expect(result.cleanText).not.toContain('<!-- buttons:');
+  });
+
+  it('handles button block at the very end of text', () => {
+    const text = 'Some text.\n<!-- buttons: {"id":"last","type":"rating","options":[{"label":"1","value":"1"},{"label":"2","value":"2"}]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons).toHaveLength(1);
+    expect(result.buttons[0].id).toBe('last');
+    expect(result.cleanText).toBe('Some text.');
+  });
+
+  it('ignores non-object parsed JSON (e.g. array, string)', () => {
+    const text1 = '<!-- buttons: [1,2,3] -->';
+    expect(extractButtons(text1).buttons).toEqual([]);
+
+    const text2 = '<!-- buttons: "hello" -->';
+    expect(extractButtons(text2).buttons).toEqual([]);
+  });
+
+  it('ignores button with empty string id', () => {
+    const text = '<!-- buttons: {"id":"","type":"single","options":[{"label":"A","value":"a"}]} -->';
+    expect(extractButtons(text).buttons).toEqual([]);
+  });
+
+  it('preserves extra fields on options (extensible)', () => {
+    const text = '<!-- buttons: {"id":"x","type":"single","options":[{"label":"A","value":"a","icon":"star"}]} -->';
+    const result = extractButtons(text);
+    expect(result.buttons[0].options[0].label).toBe('A');
+    expect(result.buttons[0].options[0].value).toBe('a');
+    expect(result.buttons[0].options[0].icon).toBe('star');
+  });
+});
+
+describe('extractButtons — server integration simulation', () => {
+  it('enriches a chat:assistant envelope payload correctly', () => {
+    const envelope = {
+      type: 'chat:assistant',
+      payload: {
+        text: 'Choose a topic:\n\n<!-- buttons: {"id":"pick","type":"single","prompt":"Topic:","options":[{"label":"Git","value":"Teach git"},{"label":"React","value":"Teach react"}]} -->\n\n<!-- suggestions: [{"label":"Continue","text":"/teach"}] -->',
+      },
+    };
+
+    const { cleanText, buttons } = extractButtons(envelope.payload.text);
+    if (buttons.length > 0) {
+      envelope.payload.text = cleanText;
+      envelope.payload.buttons = buttons;
+    }
+
+    expect(envelope.payload.buttons).toHaveLength(1);
+    expect(envelope.payload.buttons[0].id).toBe('pick');
+    expect(envelope.payload.buttons[0].options).toHaveLength(2);
+    expect(envelope.payload.text).not.toContain('<!-- buttons:');
+    expect(envelope.payload.text).toContain('<!-- suggestions:');
+    expect(envelope.payload.text).toContain('Choose a topic:');
+  });
+
+  it('does not add buttons field when no buttons in text', () => {
+    const envelope = {
+      type: 'chat:assistant',
+      payload: { text: 'Just a normal response with no buttons.' },
+    };
+
+    const { cleanText, buttons } = extractButtons(envelope.payload.text);
+    if (buttons.length > 0) {
+      envelope.payload.text = cleanText;
+      envelope.payload.buttons = buttons;
+    }
+
+    expect(envelope.payload.buttons).toBeUndefined();
+    expect(envelope.payload.text).toBe('Just a normal response with no buttons.');
+  });
+
+  it('handles multiple button blocks in one assistant message', () => {
+    const envelope = {
+      type: 'chat:assistant',
+      payload: {
+        text: [
+          'First, pick a topic:',
+          '<!-- buttons: {"id":"topic","type":"single","options":[{"label":"A","value":"a"},{"label":"B","value":"b"}]} -->',
+          'Then rate the difficulty:',
+          '<!-- buttons: {"id":"rate","type":"rating","prompt":"Difficulty:","options":[{"label":"Easy","value":"1"},{"label":"Hard","value":"5"}]} -->',
+        ].join('\n'),
+      },
+    };
+
+    const { cleanText, buttons } = extractButtons(envelope.payload.text);
+    if (buttons.length > 0) {
+      envelope.payload.text = cleanText;
+      envelope.payload.buttons = buttons;
+    }
+
+    expect(envelope.payload.buttons).toHaveLength(2);
+    expect(envelope.payload.buttons[0].type).toBe('single');
+    expect(envelope.payload.buttons[1].type).toBe('rating');
+    expect(envelope.payload.text).toContain('First, pick a topic:');
+    expect(envelope.payload.text).toContain('Then rate the difficulty:');
+    expect(envelope.payload.text).not.toContain('<!-- buttons:');
+  });
+});
+
+describe('extractInlineBlocks', () => {
+  it('returns empty blocks for null, empty, or non-string input', () => {
+    expect(extractInlineBlocks(null)).toEqual({ cleanText: '', blocks: [] });
+    expect(extractInlineBlocks('')).toEqual({ cleanText: '', blocks: [] });
+    expect(extractInlineBlocks(undefined)).toEqual({ cleanText: '', blocks: [] });
+    expect(extractInlineBlocks(42)).toEqual({ cleanText: '', blocks: [] });
+  });
+
+  it('returns original text when no block comments exist', () => {
+    const text = 'Just a normal message.';
+    const result = extractInlineBlocks(text);
+    expect(result.cleanText).toBe(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  // --- List ---
+  it('extracts a list block with cards style', () => {
+    const text = 'Topics:\n\n<!-- list: {"id":"t1","style":"cards","items":[{"icon":"book","title":"Vars","description":"Data storage","action":"teach vars"}]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toHaveLength(1);
+    expect(result.blocks[0].blockType).toBe('list');
+    expect(result.blocks[0].id).toBe('t1');
+    expect(result.blocks[0].style).toBe('cards');
+    expect(result.blocks[0].items).toHaveLength(1);
+    expect(result.blocks[0].items[0].title).toBe('Vars');
+    expect(result.blocks[0].items[0].action).toBe('teach vars');
+    expect(result.cleanText).not.toContain('<!-- list:');
+  });
+
+  it('defaults list style to cards for unknown style', () => {
+    const text = '<!-- list: {"id":"x","style":"fancy","items":[{"title":"A"}]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks[0].style).toBe('cards');
+  });
+
+  it('rejects list with empty items array', () => {
+    const text = '<!-- list: {"id":"x","style":"cards","items":[]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('rejects list with items missing title', () => {
+    const text = '<!-- list: {"id":"x","items":[{"description":"no title"}]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('accepts all valid list styles', () => {
+    for (const style of ['cards', 'numbered', 'checklist', 'compact']) {
+      const text = `<!-- list: {"id":"s-${style}","style":"${style}","items":[{"title":"Item"}]} -->`;
+      const result = extractInlineBlocks(text);
+      expect(result.blocks).toHaveLength(1);
+      expect(result.blocks[0].style).toBe(style);
+    }
+  });
+
+  // --- Progress ---
+  it('extracts a progress block with bar style', () => {
+    const text = 'Progress:\n\n<!-- progress: {"id":"p1","label":"Steps","current":3,"total":7,"style":"bar"} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toHaveLength(1);
+    expect(result.blocks[0].blockType).toBe('progress');
+    expect(result.blocks[0].current).toBe(3);
+    expect(result.blocks[0].total).toBe(7);
+    expect(result.blocks[0].label).toBe('Steps');
+    expect(result.cleanText).not.toContain('<!-- progress:');
+  });
+
+  it('defaults progress style to bar for unknown style', () => {
+    const text = '<!-- progress: {"id":"x","current":1,"total":5,"style":"fancy"} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks[0].style).toBe('bar');
+  });
+
+  it('rejects progress with missing current or total', () => {
+    expect(extractInlineBlocks('<!-- progress: {"id":"x","current":1} -->').blocks).toEqual([]);
+    expect(extractInlineBlocks('<!-- progress: {"id":"x","total":5} -->').blocks).toEqual([]);
+  });
+
+  it('rejects progress with total <= 0', () => {
+    const text = '<!-- progress: {"id":"x","current":0,"total":0} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('accepts all valid progress styles', () => {
+    for (const style of ['bar', 'steps', 'ring']) {
+      const text = `<!-- progress: {"id":"ps-${style}","current":1,"total":5,"style":"${style}"} -->`;
+      const result = extractInlineBlocks(text);
+      expect(result.blocks[0].style).toBe(style);
+    }
+  });
+
+  // --- Card ---
+  it('extracts a card block with tip type', () => {
+    const text = 'Tip:\n\n<!-- card: {"id":"c1","type":"tip","title":"Pro Tip","content":"Use `const` by default."} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toHaveLength(1);
+    expect(result.blocks[0].blockType).toBe('card');
+    expect(result.blocks[0].type).toBe('tip');
+    expect(result.blocks[0].title).toBe('Pro Tip');
+    expect(result.blocks[0].content).toBe('Use `const` by default.');
+    expect(result.cleanText).not.toContain('<!-- card:');
+  });
+
+  it('defaults card type to tip for unknown type', () => {
+    const text = '<!-- card: {"id":"x","type":"fancy","content":"text"} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks[0].type).toBe('tip');
+  });
+
+  it('rejects card with empty content', () => {
+    const text = '<!-- card: {"id":"x","type":"tip","content":""} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('rejects card with missing content', () => {
+    const text = '<!-- card: {"id":"x","type":"tip","title":"No content"} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('accepts all valid card types', () => {
+    for (const type of ['tip', 'warning', 'error', 'success', 'concept']) {
+      const text = `<!-- card: {"id":"ct-${type}","type":"${type}","content":"text"} -->`;
+      const result = extractInlineBlocks(text);
+      expect(result.blocks[0].type).toBe(type);
+    }
+  });
+
+  // --- Code ---
+  it('extracts a code block', () => {
+    const text = 'Example:\n\n<!-- code: {"id":"e1","language":"javascript","filename":"app.js","code":"const x = 1;","highlight":[1]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toHaveLength(1);
+    expect(result.blocks[0].blockType).toBe('code');
+    expect(result.blocks[0].language).toBe('javascript');
+    expect(result.blocks[0].filename).toBe('app.js');
+    expect(result.blocks[0].code).toBe('const x = 1;');
+    expect(result.blocks[0].highlight).toEqual([1]);
+    expect(result.cleanText).not.toContain('<!-- code:');
+  });
+
+  it('defaults code language to text when missing', () => {
+    const text = '<!-- code: {"id":"x","code":"hello"} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks[0].language).toBe('text');
+  });
+
+  it('rejects code with empty code string', () => {
+    const text = '<!-- code: {"id":"x","code":""} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('filters non-number highlight values', () => {
+    const text = '<!-- code: {"id":"x","code":"a","highlight":[1,"two",3]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks[0].highlight).toEqual([1, 3]);
+  });
+
+  // --- Steps ---
+  it('extracts a steps block', () => {
+    const text = 'Steps:\n\n<!-- steps: {"id":"s1","current":2,"steps":[{"label":"Create","status":"done"},{"label":"Write","status":"active"},{"label":"Test","status":"pending"}]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toHaveLength(1);
+    expect(result.blocks[0].blockType).toBe('steps');
+    expect(result.blocks[0].steps).toHaveLength(3);
+    expect(result.blocks[0].steps[0].status).toBe('done');
+    expect(result.blocks[0].steps[1].status).toBe('active');
+    expect(result.blocks[0].steps[2].status).toBe('pending');
+    expect(result.cleanText).not.toContain('<!-- steps:');
+  });
+
+  it('defaults step status to pending for unknown status', () => {
+    const text = '<!-- steps: {"id":"x","steps":[{"label":"A","status":"unknown"}]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks[0].steps[0].status).toBe('pending');
+  });
+
+  it('rejects steps with empty steps array', () => {
+    const text = '<!-- steps: {"id":"x","steps":[]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('rejects steps with items missing label', () => {
+    const text = '<!-- steps: {"id":"x","steps":[{"status":"done"}]} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  // --- Mixed ---
+  it('extracts multiple different block types from one message', () => {
+    const text = [
+      'Here is your progress:',
+      '<!-- progress: {"id":"p","current":2,"total":5,"style":"bar"} -->',
+      'And a tip:',
+      '<!-- card: {"id":"c","type":"tip","content":"Remember to save!"} -->',
+      'Next steps:',
+      '<!-- steps: {"id":"s","steps":[{"label":"Save","status":"done"},{"label":"Push","status":"active"}]} -->',
+    ].join('\n');
+
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toHaveLength(3);
+    expect(result.blocks.map(b => b.blockType)).toEqual(['progress', 'card', 'steps']);
+    expect(result.cleanText).toContain('Here is your progress:');
+    expect(result.cleanText).not.toContain('<!-- progress:');
+    expect(result.cleanText).not.toContain('<!-- card:');
+    expect(result.cleanText).not.toContain('<!-- steps:');
+  });
+
+  it('ignores malformed JSON in block comments', () => {
+    const text = 'Hello\n<!-- list: {not valid json} -->\nWorld';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+    expect(result.cleanText).toContain('Hello');
+  });
+
+  it('ignores blocks with missing id', () => {
+    const text = '<!-- card: {"type":"tip","content":"no id"} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('ignores blocks with empty string id', () => {
+    const text = '<!-- card: {"id":"","type":"tip","content":"empty id"} -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toEqual([]);
+  });
+
+  it('does not interfere with button or suggestion comments', () => {
+    const text = [
+      '<!-- buttons: {"id":"b","type":"single","options":[{"label":"A","value":"a"}]} -->',
+      '<!-- suggestions: [{"label":"Go","text":"/go"}] -->',
+      '<!-- card: {"id":"c","type":"tip","content":"A tip"} -->',
+    ].join('\n');
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toHaveLength(1);
+    expect(result.blocks[0].blockType).toBe('card');
+    expect(result.cleanText).toContain('<!-- buttons:');
+    expect(result.cleanText).toContain('<!-- suggestions:');
+  });
+
+  it('handles extra whitespace in comment delimiters', () => {
+    const text = '<!--  card:  {"id":"x","type":"tip","content":"spaced"}  -->';
+    const result = extractInlineBlocks(text);
+    expect(result.blocks).toHaveLength(1);
+    expect(result.blocks[0].content).toBe('spaced');
+  });
+});
+
+describe('extractInlineBlocks — server integration simulation', () => {
+  it('enriches a chat:assistant envelope with blocks', () => {
+    const envelope = {
+      type: 'chat:assistant',
+      payload: {
+        text: 'Here is a tip:\n\n<!-- card: {"id":"tip1","type":"tip","title":"Hint","content":"Try using map()."} -->\n\nAnd your progress:\n\n<!-- progress: {"id":"prog1","current":3,"total":5,"style":"bar"} -->',
+      },
+    };
+
+    const { cleanText: text1, buttons } = extractButtons(envelope.payload.text);
+    if (buttons.length > 0) {
+      envelope.payload.text = text1;
+      envelope.payload.buttons = buttons;
+    }
+    const { cleanText: text2, blocks } = extractInlineBlocks(envelope.payload.text);
+    if (blocks.length > 0) {
+      envelope.payload.text = text2;
+      envelope.payload.blocks = blocks;
+    }
+
+    expect(envelope.payload.blocks).toHaveLength(2);
+    const blockTypes = envelope.payload.blocks.map(b => b.blockType).sort();
+    expect(blockTypes).toEqual(['card', 'progress']);
+    expect(envelope.payload.text).not.toContain('<!-- card:');
+    expect(envelope.payload.text).not.toContain('<!-- progress:');
+    expect(envelope.payload.text).toContain('Here is a tip:');
+    expect(envelope.payload.buttons).toBeUndefined();
+  });
+
+  it('handles buttons and blocks coexisting', () => {
+    const envelope = {
+      type: 'chat:assistant',
+      payload: {
+        text: [
+          'Choose:',
+          '<!-- buttons: {"id":"b1","type":"single","options":[{"label":"A","value":"a"}]} -->',
+          'Tip:',
+          '<!-- card: {"id":"c1","type":"warning","content":"Watch out!"} -->',
+        ].join('\n'),
+      },
+    };
+
+    const { cleanText: text1, buttons } = extractButtons(envelope.payload.text);
+    if (buttons.length > 0) {
+      envelope.payload.text = text1;
+      envelope.payload.buttons = buttons;
+    }
+    const { cleanText: text2, blocks } = extractInlineBlocks(envelope.payload.text);
+    if (blocks.length > 0) {
+      envelope.payload.text = text2;
+      envelope.payload.blocks = blocks;
+    }
+
+    expect(envelope.payload.buttons).toHaveLength(1);
+    expect(envelope.payload.blocks).toHaveLength(1);
+    expect(envelope.payload.buttons[0].id).toBe('b1');
+    expect(envelope.payload.blocks[0].blockType).toBe('card');
+    expect(envelope.payload.text).not.toContain('<!-- buttons:');
+    expect(envelope.payload.text).not.toContain('<!-- card:');
+  });
+});
+
+describe('extractAndRouteVisuals — canvas command comments', () => {
+  it('routes <!-- canvas:quiz: {...} --> as a canvas:quiz visual command', () => {
+    const routed = [];
+    const router = { routeVisualCommand: (e) => routed.push(e) };
+    const tierManager = { broadcastWs: vi.fn(), broadcastSse: vi.fn() };
+    const text = 'Here is a quiz:\n<!-- canvas:quiz: {"quizType":"timed-choice","question":"What?","options":["A","B"],"correctIndex":0,"timeLimit":30} -->';
+    extractAndRouteVisuals(text, tierManager, router);
+    const quizEnvelope = routed.find(e => e.type === 'canvas:quiz');
+    expect(quizEnvelope).toBeDefined();
+    expect(quizEnvelope.payload.quizType).toBe('timed-choice');
+    expect(quizEnvelope.payload.question).toBe('What?');
+    expect(quizEnvelope.payload.autoRouted).toBe(true);
+  });
+
+  it('routes <!-- canvas:celebrate: {...} --> as a canvas:celebrate command', () => {
+    const routed = [];
+    const router = { routeVisualCommand: (e) => routed.push(e) };
+    const tierManager = { broadcastWs: vi.fn(), broadcastSse: vi.fn() };
+    const text = 'Great job!\n<!-- canvas:celebrate: {"type":"xp","xpAwarded":25} -->';
+    extractAndRouteVisuals(text, tierManager, router);
+    const cel = routed.find(e => e.type === 'canvas:celebrate');
+    expect(cel).toBeDefined();
+    expect(cel.payload.xpAwarded).toBe(25);
+  });
+
+  it('ignores invalid canvas types', () => {
+    const routed = [];
+    const router = { routeVisualCommand: (e) => routed.push(e) };
+    const tierManager = { broadcastWs: vi.fn(), broadcastSse: vi.fn() };
+    const text = '<!-- canvas:evil: {"payload":"hack"} -->';
+    extractAndRouteVisuals(text, tierManager, router);
+    expect(routed).toHaveLength(0);
+  });
+
+  it('skips malformed JSON in canvas commands', () => {
+    const routed = [];
+    const router = { routeVisualCommand: (e) => routed.push(e) };
+    const tierManager = { broadcastWs: vi.fn(), broadcastSse: vi.fn() };
+    const text = '<!-- canvas:quiz: {not valid json} -->';
+    extractAndRouteVisuals(text, tierManager, router);
+    expect(routed).toHaveLength(0);
+  });
+
+  it('routes multiple canvas commands from one message', () => {
+    const routed = [];
+    const router = { routeVisualCommand: (e) => routed.push(e) };
+    const tierManager = { broadcastWs: vi.fn(), broadcastSse: vi.fn() };
+    const text = [
+      '<!-- canvas:quiz: {"quizType":"timed-choice","question":"Q?","options":["A"],"correctIndex":0,"timeLimit":10} -->',
+      'Some text',
+      '<!-- canvas:celebrate: {"type":"xp","xpAwarded":10} -->',
+    ].join('\n');
+    extractAndRouteVisuals(text, tierManager, router);
+    expect(routed.filter(e => e.type === 'canvas:quiz')).toHaveLength(1);
+    expect(routed.filter(e => e.type === 'canvas:celebrate')).toHaveLength(1);
+  });
+});
+
+describe('stripCanvasCommands', () => {
+  it('removes canvas command comments from text', () => {
+    const text = 'Hello\n<!-- canvas:quiz: {"quizType":"timed-choice","question":"Q?"} -->\nWorld';
+    const result = stripCanvasCommands(text);
+    expect(result).not.toContain('canvas:quiz');
+    expect(result).toContain('Hello');
+    expect(result).toContain('World');
+  });
+
+  it('collapses triple newlines after stripping', () => {
+    const text = 'Hello\n\n<!-- canvas:celebrate: {"type":"xp","xpAwarded":10} -->\n\nWorld';
+    const result = stripCanvasCommands(text);
+    expect(result).not.toMatch(/\n{3,}/);
+  });
+
+  it('returns original text when no canvas commands present', () => {
+    const text = 'Just plain text with <!-- buttons: {} --> inline';
+    expect(stripCanvasCommands(text)).toBe(text);
+  });
+
+  it('handles null/undefined gracefully', () => {
+    expect(stripCanvasCommands(null)).toBeNull();
+    expect(stripCanvasCommands(undefined)).toBeUndefined();
+    expect(stripCanvasCommands('')).toBe('');
+  });
+});