@shaykec/bridge 0.4.19 → 0.4.21

package/src/server.e2e.test.js

@@ -1,12 +1,15 @@
 /**
  * Bridge server E2E tests.
  * Starts the server programmatically and exercises all major endpoints,
- * WebSocket handshake, SSE, and the visual pipeline round-trip.
+ * WebSocket handshake, SSE, and the unified visual pipeline.
  */
 
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
-import { startServer } from './server.js';
+import { startServer, enrichModulesWithMetadata, parseProgressYaml, serializeProgressYaml, createFileProgressProvider } from './server.js';
 import WebSocket from 'ws';
+import { writeFileSync, unlinkSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
 import {
   createEnvelope,
   PROTOCOL_VERSION,
@@ -16,22 +19,32 @@ import {
   MSG_CANVAS_GAME,
   MSG_CANVAS_HTML,
   MSG_CANVAS_DASHBOARD,
+  MSG_CANVAS_SLIDES,
   MSG_EVENT_CLICK,
   MSG_EVENT_QUIZ_ANSWER,
   MSG_EVENT_GAME_RESULT,
+  MSG_EVENT_SLIDE_CHANGE,
   MSG_CHAT_SEND,
-  MSG_CHAT_STATUS,
 } from '@shaykec/shared';
 
 // --- Shared state ---
 
 let bridge, port, BASE_URL;
 
+function createInMemoryProgressProvider() {
+  let data = { user: { xp: 0 }, modules: {}, journey: { active: null, progress: {} } };
+  return {
+    getProgress: () => data,
+    saveProgress: (updated) => { data = updated; },
+  };
+}
+
 beforeAll(async () => {
   port = 20000 + Math.floor(Math.random() * 10000);
   await new Promise((resolve) => {
     bridge = startServer({
       port,
+      progressProvider: createInMemoryProgressProvider(),
       onReady: () => resolve(),
     });
   });
@@ -77,6 +90,10 @@ function makeEnvelope(type, payload = {}, source = 'plugin') {
   return createEnvelope(type, payload, source);
 }
 
+function makeEnvelopeWithAwait(type, payload, source, awaitSpec) {
+  return createEnvelope(type, payload, source, { await: awaitSpec });
+}
+
 async function connectWs(clientType = 'canvas') {
   return new Promise((resolve, reject) => {
     const ws = new WebSocket(`ws://localhost:${port}/ws`);
@@ -205,9 +222,6 @@ describe('Bridge E2E: Static file serving', () => {
   });
 
   it('path traversal does not leak files outside canvas-dist', async () => {
-    // Node's HTTP parser normalises /../.. but even if a traversal path gets through,
-    // the server's startsWith guard in serveStatic prevents leaking files.
-    // We verify that requesting a path like /etc/passwd never returns passwd content.
     const { get } = await import('http');
     const body = await new Promise((resolve, reject) => {
       const req = get({ hostname: 'localhost', port, path: '/../../etc/passwd' }, (res) => {
@@ -217,7 +231,6 @@ describe('Bridge E2E: Static file serving', () => {
       });
       req.on('error', reject);
     });
-    // Must not contain actual /etc/passwd content
     expect(body).not.toContain('root:');
   });
 });
@@ -254,73 +267,122 @@ describe('Bridge E2E: POST /api/event', () => {
 });
 
 // =====================================================================
-//  Group D — POST /api/visual
+//  Group D — Unified POST /api/canvas
 // =====================================================================
 
-describe('Bridge E2E: POST /api/visual', () => {
-  it('accepts a valid canvas:diagram envelope', async () => {
+describe('Bridge E2E: Unified POST /api/canvas', () => {
+  beforeEach(() => drainEvents());
+
+  it('accepts a fire-and-forget canvas:diagram (no await)', async () => {
     const envelope = makeEnvelope(MSG_CANVAS_DIAGRAM, {
-      type: 'flow',
-      title: 'Test',
-      nodes: [],
-      edges: [],
+      format: 'mermaid',
+      content: 'graph TD; A-->B',
     });
-    const { status, data } = await postJson('/api/visual', envelope);
+    const { status, data } = await postJson('/api/canvas', envelope);
     expect(status).toBe(200);
     expect(data.ok).toBe(true);
+    expect(data).toHaveProperty('tier');
   });
 
-  it('rejects canvas:quiz with redirect message', async () => {
-    const envelope = makeEnvelope(MSG_CANVAS_QUIZ, { question: 'test?' });
-    const { status, data } = await postJson('/api/visual', envelope);
-    expect(status).toBe(400);
-    expect(data.error).toContain('/api/quiz');
+  it('accepts canvas:dashboard (no await)', async () => {
+    const envelope = makeEnvelope(MSG_CANVAS_DASHBOARD, { belt: 'white', xp: 0 });
+    const { status, data } = await postJson('/api/canvas', envelope);
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
   });
 
-  it('rejects canvas:game with redirect message', async () => {
-    const envelope = makeEnvelope(MSG_CANVAS_GAME, { gameType: 'speed-round' });
-    const { status, data } = await postJson('/api/visual', envelope);
-    expect(status).toBe(400);
-    expect(data.error).toContain('/api/game');
+  it('accepts canvas:html (no await)', async () => {
+    const envelope = makeEnvelope(MSG_CANVAS_HTML, { html: '<h1>Test</h1>' });
+    const { status, data } = await postJson('/api/canvas', envelope);
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
   });
 
-  it('rejects invalid envelope', async () => {
-    const { status } = await postJson('/api/visual', { bad: true });
-    expect(status).toBe(400);
+  it('accepts canvas:slides (no await)', async () => {
+    const envelope = makeEnvelope(MSG_CANVAS_SLIDES, {
+      title: 'Git Branching',
+      module: 'git',
+      slides: [
+        { title: 'Slide 1', layout: 'center', blocks: [{ type: 'markdown', content: '## Hello' }] },
+        { title: 'Slide 2', layout: 'split', blocks: [{ type: 'code', content: 'git branch', language: 'bash' }] },
+      ],
+    });
+    const { status, data } = await postJson('/api/canvas', envelope);
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
+    expect(data).toHaveProperty('tier');
   });
-});
-
-// =====================================================================
-//  Group E — Quiz & Game Atomic Endpoints
-// =====================================================================
 
-describe('Bridge E2E: Atomic quiz & game endpoints', () => {
-  beforeEach(() => drainEvents());
+  it('broadcasts canvas:slides to WebSocket clients', async () => {
+    const { ws } = await connectWs('canvas');
+    const messages = [];
+    ws.on('message', (raw) => {
+      try { messages.push(JSON.parse(raw.toString())); } catch {}
+    });
+    await new Promise(r => setTimeout(r, 200));
 
-  it('POST /api/quiz?timeout=1 times out with empty events', async () => {
-    const envelope = makeEnvelope(MSG_CANVAS_QUIZ, {
-      question: 'What is 2+2?',
-      options: ['3', '4'],
-      answer: 1,
+    const envelope = makeEnvelope(MSG_CANVAS_SLIDES, {
+      title: 'Test Deck',
+      slides: [{ title: 'Only Slide', blocks: [{ type: 'markdown', content: 'Content' }] }],
     });
-    const { status, data } = await postJson('/api/quiz?timeout=1', envelope);
+    await postJson('/api/canvas', envelope);
+    await new Promise(r => setTimeout(r, 300));
+
+    const slideMsg = messages.find(m => m.type === 'canvas:slides');
+    expect(slideMsg).toBeDefined();
+    expect(slideMsg.payload.title).toBe('Test Deck');
+    expect(slideMsg.payload.slides).toHaveLength(1);
+    ws.close();
+  });
+
+  it('routes event:slide-change through the event endpoint', async () => {
+    const envelope = makeEnvelope(MSG_EVENT_SLIDE_CHANGE, {
+      slide: 2,
+      total: 5,
+      title: 'Slide Three',
+    }, 'canvas');
+    const { status, data } = await postJson('/api/event', envelope);
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
+  });
+
+  it('accepts canvas:quiz with await and times out with empty events', async () => {
+    const envelope = makeEnvelopeWithAwait(
+      MSG_CANVAS_QUIZ,
+      { question: 'What is 2+2?', options: ['3', '4'] },
+      'plugin',
+      { event: 'event:quiz-answer', timeout: 1 },
+    );
+    const { status, data } = await postJson('/api/canvas', envelope);
     expect(status).toBe(200);
     expect(data.ok).toBe(true);
     expect(data.events).toEqual([]);
     expect(data.count).toBe(0);
   });
 
-  it('POST /api/quiz resolves with answer when sent during wait', async () => {
-    const quizEnvelope = makeEnvelope(MSG_CANVAS_QUIZ, {
-      question: 'Capital of France?',
-      options: ['Berlin', 'Paris'],
-      answer: 1,
-    });
+  it('accepts canvas:game with await and times out with empty events', async () => {
+    const envelope = makeEnvelopeWithAwait(
+      MSG_CANVAS_GAME,
+      { gameType: 'speed-round', title: 'Test Game', rounds: [] },
+      'plugin',
+      { event: 'event:game-result', timeout: 1 },
+    );
+    const { status, data } = await postJson('/api/canvas', envelope);
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
+    expect(data.events).toEqual([]);
+  });
+
+  it('canvas:quiz with await resolves with answer when sent during wait', async () => {
+    const envelope = makeEnvelopeWithAwait(
+      MSG_CANVAS_QUIZ,
+      { question: 'Capital of France?', options: ['Berlin', 'Paris'] },
+      'plugin',
+      { event: 'event:quiz-answer', timeout: 5 },
+    );
 
-    // Start quiz (long timeout) and concurrently send answer
-    const quizPromise = postJson('/api/quiz?timeout=5', quizEnvelope);
+    const quizPromise = postJson('/api/canvas', envelope);
 
-    // Send answer after a short delay
     await new Promise(r => setTimeout(r, 300));
     const answerEnvelope = makeEnvelope(MSG_EVENT_QUIZ_ANSWER, {
       answer: 1,
@@ -335,32 +397,19 @@ describe('Bridge E2E: Atomic quiz & game endpoints', () => {
     expect(answer).toBeDefined();
   });
 
-  it('POST /api/game?timeout=1 times out with empty events', async () => {
-    const envelope = makeEnvelope(MSG_CANVAS_GAME, {
-      gameType: 'speed-round',
-      title: 'Test Game',
-      rounds: [{ question: '2+2?', options: ['3', '4'], answer: 1, timeLimit: 10 }],
-    });
-    const { status, data } = await postJson('/api/game?timeout=1', envelope);
-    expect(status).toBe(200);
-    expect(data.ok).toBe(true);
-    expect(data.events).toEqual([]);
-  });
-
-  it('POST /api/game resolves with result when sent during wait', async () => {
-    const gameEnvelope = makeEnvelope(MSG_CANVAS_GAME, {
-      gameType: 'speed-round',
-      title: 'Test',
-      rounds: [{ question: '1+1?', options: ['2', '3'], answer: 0, timeLimit: 10 }],
-    });
+  it('canvas:game with await resolves with result when sent during wait', async () => {
+    const envelope = makeEnvelopeWithAwait(
+      MSG_CANVAS_GAME,
+      { gameType: 'speed-round', title: 'Test', rounds: [] },
+      'plugin',
+      { event: 'event:game-result', timeout: 5 },
+    );
 
-    const gamePromise = postJson('/api/game?timeout=5', gameEnvelope);
+    const gamePromise = postJson('/api/canvas', envelope);
 
     await new Promise(r => setTimeout(r, 300));
     const resultEnvelope = makeEnvelope(MSG_EVENT_GAME_RESULT, {
-      score: 300,
-      accuracy: 1.0,
-      stars: 3,
+      score: 300, accuracy: 1.0, stars: 3,
     }, 'canvas');
     await postJson('/api/event', resultEnvelope);
 
@@ -370,6 +419,46 @@ describe('Bridge E2E: Atomic quiz & game endpoints', () => {
     const result = data.events.find(e => e.type === MSG_EVENT_GAME_RESULT);
     expect(result).toBeDefined();
   });
+
+  it('rejects invalid envelope', async () => {
+    const { status } = await postJson('/api/canvas', { bad: true });
+    expect(status).toBe(400);
+  });
+
+  it('canvas:quiz without await is fire-and-forget (no waiting)', async () => {
+    const envelope = makeEnvelope(MSG_CANVAS_QUIZ, { question: 'Quick?' });
+    const start = Date.now();
+    const { status, data } = await postJson('/api/canvas', envelope);
+    const elapsed = Date.now() - start;
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
+    expect(data.events).toBeUndefined();
+    expect(elapsed).toBeLessThan(2000);
+  });
+});
+
+// =====================================================================
+//  Group E — Old Endpoints Removed
+// =====================================================================
+
+describe('Bridge E2E: Old endpoints removed', () => {
+  it('POST /api/visual returns 404', async () => {
+    const envelope = makeEnvelope(MSG_CANVAS_DIAGRAM, { content: 'graph TD' });
+    const { status } = await postJson('/api/visual', envelope);
+    expect(status).toBe(404);
+  });
+
+  it('POST /api/quiz returns 404', async () => {
+    const envelope = makeEnvelope(MSG_CANVAS_QUIZ, { question: 'test?' });
+    const { status } = await postJson('/api/quiz?timeout=1', envelope);
+    expect(status).toBe(404);
+  });
+
+  it('POST /api/game returns 404', async () => {
+    const envelope = makeEnvelope(MSG_CANVAS_GAME, { gameType: 'speed-round' });
+    const { status } = await postJson('/api/game?timeout=1', envelope);
+    expect(status).toBe(404);
+  });
 });
 
 // =====================================================================
@@ -387,7 +476,6 @@ describe('Bridge E2E: Long-poll /api/events/wait', () => {
   });
 
   it('resolves immediately when events are already queued', async () => {
-    // Queue an event first
     await postJson('/api/event', makeEnvelope(MSG_EVENT_CLICK, { target: 'x' }, 'canvas'));
 
     const start = Date.now();
@@ -395,7 +483,7 @@ describe('Bridge E2E: Long-poll /api/events/wait', () => {
     const elapsed = Date.now() - start;
 
     expect(data.count).toBeGreaterThanOrEqual(1);
-    expect(elapsed).toBeLessThan(2000); // Should resolve near-instantly
+    expect(elapsed).toBeLessThan(2000);
   });
 
   it('resolves when event arrives during the wait', async () => {
@@ -439,12 +527,12 @@ describe('Bridge E2E: POST /api/terminal/exec', () => {
 });
 
 // =====================================================================
-//  Group H — Chat Endpoints
+//  Group H — Chat Endpoints (via @shaykec/agent-web middleware)
 // =====================================================================
 
-describe('Bridge E2E: Chat endpoints', () => {
+describe('Bridge E2E: Chat endpoints (agent-web)', () => {
   it('POST /api/chat/start returns 200 (SDK available) or 500 (SDK missing)', async () => {
-    const { status, data } = await postJson('/api/chat/start', { clientId: 'e2e-test' });
+    const { status, data } = await postJson('/api/chat/start', {});
     expect([200, 500]).toContain(status);
     if (status === 200) {
       expect(data.sessionId).toBeDefined();
@@ -459,16 +547,15 @@ describe('Bridge E2E: Chat endpoints', () => {
     expect(Array.isArray(data.sessions)).toBe(true);
   });
 
-  it('POST /api/chat/message returns 400 without valid sessionId', async () => {
+  it('POST /api/chat/message returns error without valid sessionId', async () => {
     const { status, data } = await postJson('/api/chat/message', { text: 'hello' });
-    expect(status).toBe(400);
+    expect(status).toBeGreaterThanOrEqual(400);
     expect(data.error).toBeDefined();
   });
 
-  it('POST /api/chat/stop returns 400 without sessionId', async () => {
-    const { status, data } = await postJson('/api/chat/stop', {});
-    expect(status).toBe(400);
-    expect(data.error).toContain('sessionId');
+  it('POST /api/chat/stop returns 200 (best-effort)', async () => {
+    const { status } = await postJson('/api/chat/stop', {});
+    expect(status).toBe(200);
   });
 });
 
@@ -529,13 +616,11 @@ describe('Bridge E2E: WebSocket handshake', () => {
   it('canvas client upgrades tier to TIER_CANVAS', async () => {
     const { ws } = await connectWs('canvas');
     try {
-      // Give server a moment to update tier
       await new Promise(r => setTimeout(r, 100));
       const { data } = await getJson('/api/tier');
-      expect(data.tier).toBe(2); // TIER_CANVAS
+      expect(data.tier).toBe(2);
     } finally {
       ws.close();
-      // Wait for disconnect processing
       await new Promise(r => setTimeout(r, 200));
     }
   });
@@ -563,16 +648,15 @@ describe('Bridge E2E: WebSocket message routing', () => {
     }
   });
 
-  it('WS client receives visual command broadcast', async () => {
+  it('WS client receives visual command broadcast from /api/canvas', async () => {
     const { ws } = await connectWs('canvas');
     try {
       const msgPromise = waitForWsMessage(ws, m => m.type === MSG_CANVAS_DIAGRAM);
 
-      await postJson('/api/visual', makeEnvelope(MSG_CANVAS_DIAGRAM, {
-        type: 'flow',
+      await postJson('/api/canvas', makeEnvelope(MSG_CANVAS_DIAGRAM, {
+        format: 'mermaid',
+        content: 'graph TD; A-->B',
         title: 'WS Test',
-        nodes: [],
-        edges: [],
       }));
 
       const msg = await msgPromise;
@@ -590,7 +674,7 @@ describe('Bridge E2E: WebSocket message routing', () => {
       const msg1Promise = waitForWsMessage(client1.ws, m => m.type === MSG_CANVAS_HTML);
       const msg2Promise = waitForWsMessage(client2.ws, m => m.type === MSG_CANVAS_HTML);
 
-      await postJson('/api/visual', makeEnvelope(MSG_CANVAS_HTML, {
+      await postJson('/api/canvas', makeEnvelope(MSG_CANVAS_HTML, {
         html: '<h1>Multi</h1>',
         title: 'Multi Test',
       }));
@@ -617,12 +701,10 @@ describe('Bridge E2E: SSE /sse endpoint', () => {
       expect(resp.status).toBe(200);
       expect(resp.headers.get('content-type')).toContain('text/event-stream');
 
-      // Read the first chunk from the SSE stream
       const reader = resp.body.getReader();
       const decoder = new TextDecoder();
       let buffer = '';
 
-      // Read until we get a complete SSE message
       while (true) {
         const { value, done } = await reader.read();
         if (done) break;
@@ -630,7 +712,6 @@ describe('Bridge E2E: SSE /sse endpoint', () => {
         if (buffer.includes('\n\n')) break;
       }
 
-      // Parse the SSE data line
       const dataLine = buffer.split('\n').find(l => l.startsWith('data:'));
       expect(dataLine).toBeDefined();
       const msg = JSON.parse(dataLine.replace('data:', '').trim());
@@ -641,7 +722,7 @@ describe('Bridge E2E: SSE /sse endpoint', () => {
     }
   });
 
-  it('SSE client receives visual command broadcasts', async () => {
+  it('SSE client receives visual command broadcasts from /api/canvas', async () => {
     const controller = new AbortController();
     try {
       const resp = await fetch(`${BASE_URL}/sse`, { signal: controller.signal });
@@ -649,7 +730,6 @@ describe('Bridge E2E: SSE /sse endpoint', () => {
       const decoder = new TextDecoder();
       let buffer = '';
 
-      // Read the initial sys:connect message
       while (true) {
         const { value, done } = await reader.read();
         if (done) break;
@@ -657,16 +737,13 @@ describe('Bridge E2E: SSE /sse endpoint', () => {
         if (buffer.includes('\n\n')) break;
       }
 
-      // Clear buffer after connect
       buffer = '';
 
-      // Send a visual command
-      await postJson('/api/visual', makeEnvelope(MSG_CANVAS_DASHBOARD, {
+      await postJson('/api/canvas', makeEnvelope(MSG_CANVAS_DASHBOARD, {
         belt: 'white',
         xp: 0,
       }));
 
-      // Read the broadcast
       while (true) {
         const { value, done } = await reader.read();
         if (done) break;
@@ -691,27 +768,22 @@ describe('Bridge E2E: SSE /sse endpoint', () => {
 describe('Bridge E2E: Visual pipeline integration', () => {
   beforeEach(() => drainEvents());
 
-  it('full round-trip: POST visual → WS receives → send event → poll returns it', async () => {
+  it('full round-trip: POST canvas → WS receives → send event → poll returns it', async () => {
     const { ws } = await connectWs('canvas');
     try {
-      // Step 1: POST visual command
       const msgPromise = waitForWsMessage(ws, m => m.type === MSG_CANVAS_DIAGRAM);
-      await postJson('/api/visual', makeEnvelope(MSG_CANVAS_DIAGRAM, {
-        type: 'flow',
+      await postJson('/api/canvas', makeEnvelope(MSG_CANVAS_DIAGRAM, {
+        format: 'mermaid',
+        content: 'graph TD; A-->B',
         title: 'Pipeline Test',
-        nodes: [],
-        edges: [],
       }));
 
-      // Step 2: WS client receives it
       const received = await msgPromise;
       expect(received.type).toBe(MSG_CANVAS_DIAGRAM);
 
-      // Step 3: Send event via WS (user interaction response)
       ws.send(JSON.stringify(makeEnvelope(MSG_EVENT_CLICK, { target: 'pipeline' }, 'canvas')));
       await new Promise(r => setTimeout(r, 100));
 
-      // Step 4: Poll returns the event
       const { data } = await getJson('/api/events');
       expect(data.count).toBeGreaterThanOrEqual(1);
       const click = data.events.find(e => e.payload?.target === 'pipeline');
@@ -721,30 +793,26 @@ describe('Bridge E2E: Visual pipeline integration', () => {
     }
   });
 
-  it('atomic quiz: send + WS answer → quiz response includes answer', async () => {
-    // Connect a WS client to receive the quiz
+  it('atomic quiz: send canvas:quiz with await + WS answer → response includes answer', async () => {
     const { ws } = await connectWs('canvas');
     try {
-      const quizEnvelope = makeEnvelope(MSG_CANVAS_QUIZ, {
-        question: 'Pipeline quiz?',
-        options: ['A', 'B'],
-        answer: 0,
-      });
+      const quizEnvelope = makeEnvelopeWithAwait(
+        MSG_CANVAS_QUIZ,
+        { question: 'Pipeline quiz?', options: ['A', 'B'], answer: 0 },
+        'plugin',
+        { event: 'event:quiz-answer', timeout: 5 },
+      );
 
-      // Start quiz with timeout
-      const quizPromise = postJson('/api/quiz?timeout=5', quizEnvelope);
+      const quizPromise = postJson('/api/canvas', quizEnvelope);
 
-      // WS client receives the quiz broadcast
       const quizMsg = await waitForWsMessage(ws, m => m.type === MSG_CANVAS_QUIZ);
       expect(quizMsg.payload.question).toBe('Pipeline quiz?');
 
-      // Send answer via HTTP (as canvas would)
       await postJson('/api/event', makeEnvelope(MSG_EVENT_QUIZ_ANSWER, {
         answer: 0,
         correct: true,
       }, 'canvas'));
 
-      // Quiz endpoint resolves with the answer
       const { data } = await quizPromise;
       expect(data.count).toBeGreaterThanOrEqual(1);
       const answerEvent = data.events.find(e => e.type === MSG_EVENT_QUIZ_ANSWER);
@@ -760,17 +828,14 @@ describe('Bridge E2E: Visual pipeline integration', () => {
 // =====================================================================
 
 describe('Bridge E2E: Chat message routing', () => {
-  it('chat:send via WS is routed to the chat handler (no active session)', async () => {
+  it('chat:send via bridge WS is silently accepted (no crash)', async () => {
     const { ws } = await connectWs('canvas');
     try {
-      // Send a chat message via WebSocket — no session active, so it should be
-      // silently ignored (sessionId check fails) but NOT error the connection
       ws.send(JSON.stringify(createEnvelope(MSG_CHAT_SEND, {
         text: '/teach git',
         sessionId: 'nonexistent-session',
       }, 'canvas')));
 
-      // Connection should remain open
       await new Promise(r => setTimeout(r, 200));
       expect(ws.readyState).toBe(WebSocket.OPEN);
     } finally {
@@ -787,50 +852,24 @@ describe('Bridge E2E: Chat message routing', () => {
     expect(data.ok).toBe(true);
   });
 
-  it('POST /api/chat/start returns 200 with sessionId (SDK available) or 500 with error', async () => {
-    const { status, data } = await postJson('/api/chat/start', { clientId: 'test-client-123' });
-    expect([200, 500]).toContain(status);
-    if (status === 200) {
-      expect(data.sessionId).toBeDefined();
-      expect(data.ok).toBe(true);
-    } else {
-      expect(data.error).toBeDefined();
-    }
-  });
-
-  it('POST /api/chat/message requires sessionId', async () => {
-    const resp = await postJson('/api/chat/message', { text: 'hello' });
-    expect(resp.status).toBe(400);
-  });
-
   it('POST /api/chat/message with invalid sessionId returns error', async () => {
     const resp = await postJson('/api/chat/message', {
       text: '/teach git',
       sessionId: 'nonexistent',
     });
-    // Should be 400 or 500 since session doesn't exist
     expect(resp.status).toBeGreaterThanOrEqual(400);
   });
 
   it('POST /api/chat/resume with invalid sessionId does not crash server', async () => {
     const { status } = await postJson('/api/chat/resume', {
       sessionId: 'nonexistent',
-      clientId: 'test-client',
     });
-    // 200 if SDK accepts the ID, 500 if it rejects — either is valid
     expect([200, 500]).toContain(status);
   });
-
-  it('GET /api/chat/sessions returns array', async () => {
-    const resp = await fetch(`${BASE_URL}/api/chat/sessions`);
-    expect(resp.status).toBe(200);
-    const data = await resp.json();
-    expect(Array.isArray(data.sessions)).toBe(true);
-  });
 });
 
 // =====================================================================
-//  Group N — Teaching Module Flow (via HTTP API)
+//  Group N — Teaching Module Flow (via unified /api/canvas)
 // =====================================================================
 
 describe('Bridge E2E: Teaching module flow', () => {
@@ -839,33 +878,34 @@ describe('Bridge E2E: Teaching module flow', () => {
   it('teaching quiz is broadcast to WS clients and answer is collected', async () => {
     const { ws } = await connectWs('canvas');
     try {
-      // Simulate a teaching quiz being sent (as the plugin would via /api/quiz)
-      const quizPayload = createEnvelope(MSG_CANVAS_QUIZ, {
-        question: 'What does `git add .` do?',
-        options: [
-          'Stages all files in the current directory',
-          'Creates a new branch',
-          'Pushes to remote',
-          'Deletes untracked files',
-        ],
-        answer: 0,
-        hint: 'Think about the staging area',
-      }, 'plugin');
-
-      const quizPromise = postJson('/api/quiz?timeout=3', quizPayload);
+      const quizPayload = makeEnvelopeWithAwait(
+        MSG_CANVAS_QUIZ,
+        {
+          question: 'What does `git add .` do?',
+          options: [
+            'Stages all files in the current directory',
+            'Creates a new branch',
+            'Pushes to remote',
+            'Deletes untracked files',
+          ],
+          answer: 0,
+          hint: 'Think about the staging area',
+        },
+        'plugin',
+        { event: 'event:quiz-answer', timeout: 3 },
+      );
+
+      const quizPromise = postJson('/api/canvas', quizPayload);
 
-      // WS client receives the quiz
       const quizMsg = await waitForWsMessage(ws, m => m.type === MSG_CANVAS_QUIZ);
       expect(quizMsg.payload.question).toContain('git add');
       expect(quizMsg.payload.options).toHaveLength(4);
 
-      // User answers the quiz via event POST (as the canvas UI would)
       await postJson('/api/event', createEnvelope(MSG_EVENT_QUIZ_ANSWER, {
         answer: 0,
         correct: true,
       }, 'canvas'));
 
-      // Quiz resolves with the answer
       const { data } = await quizPromise;
       const answerEvent = data.events.find(e => e.type === MSG_EVENT_QUIZ_ANSWER);
       expect(answerEvent).toBeDefined();
@@ -880,8 +920,7 @@ describe('Bridge E2E: Teaching module flow', () => {
     try {
       const msgPromise = waitForWsMessage(ws, m => m.type === MSG_CANVAS_DIAGRAM);
 
-      // Simulate plugin sending a teaching diagram
-      await postJson('/api/visual', createEnvelope(MSG_CANVAS_DIAGRAM, {
+      await postJson('/api/canvas', createEnvelope(MSG_CANVAS_DIAGRAM, {
         format: 'mermaid',
         code: 'graph TD; A[Working Dir]-->B[Staging]; B-->C[Repository];',
         title: 'Git Workflow',
@@ -901,8 +940,7 @@ describe('Bridge E2E: Teaching module flow', () => {
     try {
       const msgPromise = waitForWsMessage(ws, m => m.type === MSG_CANVAS_DASHBOARD);
 
-      // Simulate progress update after completing a module step
-      await postJson('/api/visual', createEnvelope(MSG_CANVAS_DASHBOARD, {
+      await postJson('/api/canvas', createEnvelope(MSG_CANVAS_DASHBOARD, {
         belt: 'white',
         xp: 50,
         streak: 1,
@@ -928,14 +966,13 @@ describe('Bridge E2E: Teaching module flow', () => {
         if (msg.type.startsWith('canvas:')) received.push(msg);
       });
 
-      // Send diagram, then dashboard update (like a teaching step)
-      await postJson('/api/visual', createEnvelope(MSG_CANVAS_DIAGRAM, {
+      await postJson('/api/canvas', createEnvelope(MSG_CANVAS_DIAGRAM, {
         format: 'mermaid',
         code: 'graph LR; A-->B;',
         title: 'Step 1',
       }, 'plugin'));
 
-      await postJson('/api/visual', createEnvelope(MSG_CANVAS_DASHBOARD, {
+      await postJson('/api/canvas', createEnvelope(MSG_CANVAS_DASHBOARD, {
         belt: 'white',
         xp: 25,
       }, 'plugin'));
@@ -949,3 +986,601 @@ describe('Bridge E2E: Teaching module flow', () => {
     }
   });
 });
+
+// =====================================================================
+//  Group O — Module Content Endpoint
+// =====================================================================
+
+describe('Bridge E2E: Module content endpoint', () => {
+  it('GET /api/module/git returns module content (if git module exists)', async () => {
+    const { status, data } = await getJson('/api/module/git');
+    if (status === 200) {
+      expect(data.slug).toBe('git');
+      expect(data).toHaveProperty('meta');
+      expect(data).toHaveProperty('files');
+      expect(data.files).toHaveProperty('module.yaml');
+    } else {
+      expect(status).toBe(404);
+    }
+  });
+
+  it('GET /api/module/nonexistent returns 404', async () => {
+    const { status, data } = await getJson('/api/module/nonexistent-slug-xyz');
+    expect(status).toBe(404);
+    expect(data.error).toContain('not found');
+  });
+});
+
+// =====================================================================
+//  Group P — SDK Config Verification
+// =====================================================================
+
+describe('Bridge E2E: SDK config verification', () => {
+  it('agentServer was created with proper config', () => {
+    expect(bridge.agentServer).toBeDefined();
+  });
+});
+
+// =====================================================================
+//  Group Q — Journey Endpoints
+// =====================================================================
+
+describe('Bridge E2E: Journey endpoints', () => {
+  it('GET /api/journeys returns journeys array', async () => {
+    const { status, data } = await getJson('/api/journeys');
+    expect(status).toBe(200);
+    expect(data).toHaveProperty('journeys');
+    expect(data.journeys).toBeInstanceOf(Array);
+    expect(data.journeys.length).toBeGreaterThanOrEqual(1);
+    expect(data).toHaveProperty('activeJourney');
+  });
+
+  it('each journey has slug, title, stages, and stats', async () => {
+    const { data } = await getJson('/api/journeys');
+    for (const j of data.journeys) {
+      expect(j).toHaveProperty('slug');
+      expect(j).toHaveProperty('title');
+      expect(j).toHaveProperty('stages');
+      expect(j.stages).toBeInstanceOf(Array);
+      expect(j.stages.length).toBeGreaterThan(0);
+      expect(j).toHaveProperty('stats');
+      expect(j.stats).toHaveProperty('totalModules');
+      expect(j.stats).toHaveProperty('comingSoonModules');
+      expect(j.stats).toHaveProperty('progressPercent');
+      expect(j.stats).toHaveProperty('totalStages');
+    }
+  });
+
+  it('journey stages contain modules with status fields', async () => {
+    const { data } = await getJson('/api/journeys');
+    const journey = data.journeys[0];
+    const firstStage = journey.stages[0];
+    expect(firstStage).toHaveProperty('name');
+    expect(firstStage).toHaveProperty('modules');
+    expect(firstStage.modules.length).toBeGreaterThan(0);
+    for (const mod of firstStage.modules) {
+      expect(mod).toHaveProperty('slug');
+      expect(mod).toHaveProperty('title');
+      expect(mod).toHaveProperty('status');
+      expect(['available', 'completed', 'in_progress', 'locked', 'coming_soon']).toContain(mod.status);
+    }
+  });
+
+  it('journeys include coming_soon modules for TBD content', async () => {
+    const { data } = await getJson('/api/journeys');
+    const hasComingSoon = data.journeys.some(j => j.stats.comingSoonModules > 0);
+    expect(hasComingSoon).toBe(true);
+
+    const journeyWithTBD = data.journeys.find(j => j.stats.comingSoonModules > 0);
+    const allModules = journeyWithTBD.stages.flatMap(s => s.modules);
+    const comingSoon = allModules.filter(m => m.status === 'coming_soon');
+    expect(comingSoon.length).toBe(journeyWithTBD.stats.comingSoonModules);
+  });
+
+  it('POST /api/journeys/activate sets active journey', async () => {
+    const { status, data } = await postJson('/api/journeys/activate', { slug: 'frontend-developer' });
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
+    expect(data.active).toBe('frontend-developer');
+  });
+
+  it('GET /api/journeys reflects activated journey', async () => {
+    await postJson('/api/journeys/activate', { slug: 'frontend-developer' });
+    const { data } = await getJson('/api/journeys');
+    expect(data.activeJourney).toBe('frontend-developer');
+  });
+
+  it('POST /api/journeys/activate with null deactivates', async () => {
+    await postJson('/api/journeys/activate', { slug: 'frontend-developer' });
+    const { status, data } = await postJson('/api/journeys/activate', { slug: null });
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
+    expect(data.active).toBeNull();
+  });
+
+  it('GET /api/journeys shows null activeJourney after deactivation', async () => {
+    await postJson('/api/journeys/activate', { slug: 'frontend-developer' });
+    await postJson('/api/journeys/activate', { slug: null });
+    const { data } = await getJson('/api/journeys');
+    expect(data.activeJourney).toBeNull();
+  });
+
+  it('first stage is available, later stages locked for fresh progress', async () => {
+    const { data } = await getJson('/api/journeys');
+    const journey = data.journeys.find(j => j.stages.length >= 3);
+    if (journey) {
+      expect(journey.stages[0].status).toBe('available');
+      const lockedStages = journey.stages.slice(2).filter(s => s.status === 'locked');
+      expect(lockedStages.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+// =====================================================================
+//  Group R — Progress Sync (POST /api/progress + provider + broadcast)
+// =====================================================================
+
+describe('Bridge E2E: Progress sync', () => {
+  it('POST /api/progress updates XP via progressProvider', async () => {
+    const { status, data } = await postJson('/api/progress', { xp: 150 });
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
+
+    const { data: progress } = await getJson('/api/progress');
+    expect(progress.user.xp).toBe(150);
+  });
+
+  it('POST /api/progress updates module status', async () => {
+    const { status, data } = await postJson('/api/progress', {
+      module: 'git',
+      status: 'in-progress',
+    });
+    expect(status).toBe(200);
+    expect(data.ok).toBe(true);
+
+    const { data: progress } = await getJson('/api/progress');
+    expect(progress.modules.git).toBeDefined();
+    expect(progress.modules.git.status).toBe('in-progress');
+    expect(progress.modules.git.last_session).toBeDefined();
+  });
+
+  it('POST /api/progress updates module with walkthroughStep', async () => {
+    await postJson('/api/progress', {
+      module: 'hooks',
+      status: 'in-progress',
+      walkthroughStep: 3,
+    });
+
+    const { data: progress } = await getJson('/api/progress');
+    expect(progress.modules.hooks).toBeDefined();
+    expect(progress.modules.hooks.walkthrough_step).toBe(3);
+  });
+
+  it('POST /api/progress marks module completed and updates count', async () => {
+    await postJson('/api/progress', { module: 'test-mod', status: 'completed' });
+
+    const { data: progress } = await getJson('/api/progress');
+    expect(progress.modules['test-mod'].status).toBe('completed');
+    expect(progress.user.modules_completed).toBeGreaterThanOrEqual(1);
+  });
+
+  it('POST /api/progress rejects invalid body', async () => {
+    const { status } = await postRaw('/api/progress', 'not json');
+    expect(status).toBe(400);
+  });
+
+  it('POST /api/progress rejects non-object body', async () => {
+    const { status } = await postJson('/api/progress', 'just a string');
+    expect(status).toBe(400);
+  });
+
+  it('POST /api/progress broadcasts canvas:dashboard to WebSocket clients', async () => {
+    const { ws } = await connectWs('canvas');
+    const messages = [];
+
+    ws.on('message', (raw) => {
+      try { messages.push(JSON.parse(raw.toString())); } catch {}
+    });
+
+    await postJson('/api/progress', { xp: 999 });
+
+    await new Promise(r => setTimeout(r, 300));
+
+    ws.close();
+
+    const dashboardMsg = messages.find(m => m.type === 'canvas:dashboard');
+    expect(dashboardMsg).toBeDefined();
+    expect(dashboardMsg.payload.progress.xp).toBe(999);
+  });
+
+  it('journey activation persists via saveProgress', async () => {
+    await postJson('/api/journeys/activate', { slug: 'frontend-developer' });
+    const { data } = await getJson('/api/journeys');
+    expect(data.activeJourney).toBe('frontend-developer');
+
+    await postJson('/api/journeys/activate', { slug: null });
+    const { data: data2 } = await getJson('/api/journeys');
+    expect(data2.activeJourney).toBeNull();
+  });
+});
+
+// =====================================================================
+//  Group S — Constants Endpoint
+// =====================================================================
+
+describe('Bridge E2E: Constants endpoint', () => {
+  it('GET /api/constants returns belt data', async () => {
+    const { status, data } = await getJson('/api/constants');
+    expect(status).toBe(200);
+    expect(data).toHaveProperty('belts');
+    expect(data.belts).toBeInstanceOf(Array);
+    expect(data.belts.length).toBeGreaterThanOrEqual(7);
+  });
+
+  it('belt data includes required fields', async () => {
+    const { data } = await getJson('/api/constants');
+    for (const belt of data.belts) {
+      expect(belt).toHaveProperty('name');
+      expect(belt).toHaveProperty('minXP');
+      expect(belt).toHaveProperty('badge');
+      expect(typeof belt.name).toBe('string');
+      expect(typeof belt.minXP).toBe('number');
+    }
+  });
+
+  it('belt thresholds match shared constants', async () => {
+    const { BELTS: sharedBelts } = await import('@shaykec/shared');
+    const { data } = await getJson('/api/constants');
+    expect(data.belts).toEqual(sharedBelts);
+  });
+});
+
+// =====================================================================
+//  Group S2 — Modules Catalog Endpoint
+// =====================================================================
+
+describe('Bridge E2E: Modules catalog endpoint', () => {
+  it('GET /api/modules returns a modules array', async () => {
+    const { status, data } = await getJson('/api/modules');
+    expect(status).toBe(200);
+    expect(data).toHaveProperty('modules');
+    expect(data.modules).toBeInstanceOf(Array);
+  });
+
+  it('each module has slug, title, category, difficulty', async () => {
+    const { data } = await getJson('/api/modules');
+    expect(data.modules.length).toBeGreaterThan(0);
+    for (const mod of data.modules) {
+      expect(mod).toHaveProperty('slug');
+      expect(mod).toHaveProperty('title');
+      expect(mod).toHaveProperty('category');
+      expect(mod).toHaveProperty('difficulty');
+      expect(typeof mod.slug).toBe('string');
+      expect(typeof mod.title).toBe('string');
+    }
+  });
+
+  it('includes known built-in modules', async () => {
+    const { data } = await getJson('/api/modules');
+    const slugs = data.modules.map(m => m.slug);
+    expect(slugs).toContain('git');
+  });
+
+  it('returns CORS headers', async () => {
+    const { headers } = await getJson('/api/modules');
+    expect(headers.get('access-control-allow-origin')).toBeTruthy();
+  });
+
+  it('returns JSON content type', async () => {
+    const resp = await fetch(`${BASE_URL}/api/modules`);
+    expect(resp.headers.get('content-type')).toMatch(/application\/json/);
+  });
+
+  it('slugs are unique across all modules', async () => {
+    const { data } = await getJson('/api/modules');
+    const slugs = data.modules.map(m => m.slug);
+    expect(new Set(slugs).size).toBe(slugs.length);
+  });
+
+  it('slugs contain only valid characters (lowercase, hyphens, numbers)', async () => {
+    const { data } = await getJson('/api/modules');
+    for (const mod of data.modules) {
+      expect(mod.slug).toMatch(/^[a-z0-9-]+$/);
+    }
+  });
+
+  it('difficulty values are from expected set', async () => {
+    const validDifficulties = ['beginner', 'intermediate', 'advanced'];
+    const { data } = await getJson('/api/modules');
+    for (const mod of data.modules) {
+      expect(validDifficulties).toContain(mod.difficulty);
+    }
+  });
+
+  it('includes multiple categories', async () => {
+    const { data } = await getJson('/api/modules');
+    const categories = new Set(data.modules.map(m => m.category));
+    expect(categories.size).toBeGreaterThan(1);
+  });
+});
+
+// =====================================================================
+//  Group T — Module Enrichment
+// =====================================================================
+
+describe('Bridge E2E: Module enrichment', () => {
+  it('GET /api/progress returns modules with title field', async () => {
+    await postJson('/api/progress', { module: 'git', status: 'in-progress' });
+    const { data } = await getJson('/api/progress');
+    expect(data.modules.git).toBeDefined();
+    expect(data.modules.git.title).toBeDefined();
+    expect(typeof data.modules.git.title).toBe('string');
+    expect(data.modules.git.title.length).toBeGreaterThan(0);
+  });
+
+  it('GET /api/progress includes available modules from catalog', async () => {
+    const { data } = await getJson('/api/progress');
+    const slugs = Object.keys(data.modules);
+    expect(slugs.length).toBeGreaterThan(1);
+    const available = Object.values(data.modules).filter(m => m.status === 'available');
+    expect(available.length).toBeGreaterThan(0);
+    for (const mod of available) {
+      expect(mod.title).toBeDefined();
+      expect(mod.title.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('GET /api/progress enriches modules with description and difficulty', async () => {
+    const { data } = await getJson('/api/progress');
+    const anyModule = Object.values(data.modules).find(m => m.title && m.title !== m.slug);
+    expect(anyModule).toBeDefined();
+    expect(anyModule).toHaveProperty('description');
+    expect(anyModule).toHaveProperty('difficulty');
+  });
+
+  it('POST /api/progress broadcast includes enriched module titles', async () => {
+    const { ws } = await connectWs('canvas');
+    const messages = [];
+
+    ws.on('message', (raw) => {
+      try { messages.push(JSON.parse(raw.toString())); } catch {}
+    });
+
+    await postJson('/api/progress', { module: 'git', status: 'in-progress' });
+    await new Promise(r => setTimeout(r, 300));
+    ws.close();
+
+    const dashboardMsg = messages.find(m => m.type === 'canvas:dashboard');
+    expect(dashboardMsg).toBeDefined();
+    const gitModule = dashboardMsg.payload.progress.modules.find(m => m.slug === 'git');
+    expect(gitModule).toBeDefined();
+    expect(gitModule.title).toBeDefined();
+    expect(gitModule.title.length).toBeGreaterThan(0);
+  });
+});
+
+// =====================================================================
+//  Group U — Unit: enrichModulesWithMetadata
+// =====================================================================
+
+describe('enrichModulesWithMetadata', () => {
+  it('merges catalog metadata into progress modules', () => {
+    const progressModules = {
+      git: { status: 'in-progress', xp_earned: 30 },
+    };
+    const moduleMap = new Map([
+      ['git', { slug: 'git', title: 'Git Fundamentals', description: 'Learn git', difficulty: 'beginner' }],
+    ]);
+
+    const result = enrichModulesWithMetadata(progressModules, moduleMap);
+    expect(result.git.title).toBe('Git Fundamentals');
+    expect(result.git.description).toBe('Learn git');
+    expect(result.git.difficulty).toBe('beginner');
+    expect(result.git.status).toBe('in-progress');
+    expect(result.git.xp_earned).toBe(30);
+  });
+
+  it('falls back to slug as title when module not in catalog', () => {
+    const progressModules = {
+      'custom-mod': { status: 'completed', xp_earned: 100 },
+    };
+    const moduleMap = new Map();
+
+    const result = enrichModulesWithMetadata(progressModules, moduleMap);
+    expect(result['custom-mod'].title).toBe('custom-mod');
+    expect(result['custom-mod'].status).toBe('completed');
+  });
+
+  it('includes catalog modules not in progress as available', () => {
+    const progressModules = {};
+    const moduleMap = new Map([
+      ['hooks', { slug: 'hooks', title: 'React Hooks', description: 'Hooks guide', difficulty: 'intermediate' }],
+    ]);
+
+    const result = enrichModulesWithMetadata(progressModules, moduleMap);
+    expect(result.hooks).toBeDefined();
+    expect(result.hooks.status).toBe('available');
+    expect(result.hooks.title).toBe('React Hooks');
+  });
+
+  it('handles null/undefined progressModules', () => {
+    const moduleMap = new Map([
+      ['git', { slug: 'git', title: 'Git', description: '', difficulty: 'beginner' }],
+    ]);
+
+    const result = enrichModulesWithMetadata(null, moduleMap);
+    expect(result.git.status).toBe('available');
+  });
+
+  it('handles empty moduleMap', () => {
+    const progressModules = { git: { status: 'in-progress' } };
+    const result = enrichModulesWithMetadata(progressModules, new Map());
+    expect(result.git.title).toBe('git');
+    expect(result.git.status).toBe('in-progress');
+  });
+});
+
+// =====================================================================
+//  Group V — Unit: parseProgressYaml / serializeProgressYaml
+// =====================================================================
+
+describe('parseProgressYaml', () => {
+  it('parses a typical progress file', () => {
+    const yaml = `user:
+  xp: 250
+  belt: green
+  modules_completed: 2
+modules:
+  git:
+    status: completed
+    xp_earned: 100
+    started: 2026-03-01
+  hooks:
+    status: in-progress
+    xp_earned: 50
+    walkthrough_step: 3
+journey:
+  active: frontend-developer
+  progress: {}
+`;
+    const result = parseProgressYaml(yaml);
+    expect(result.user.xp).toBe(250);
+    expect(result.user.belt).toBe('green');
+    expect(result.user.modules_completed).toBe(2);
+    expect(result.modules.git.status).toBe('completed');
+    expect(result.modules.git.xp_earned).toBe(100);
+    expect(result.modules.hooks.walkthrough_step).toBe(3);
+    expect(result.journey.active).toBe('frontend-developer');
+  });
+
+  it('returns defaults for empty input', () => {
+    const result = parseProgressYaml('');
+    expect(result.user.xp).toBe(0);
+    expect(result.modules).toEqual({});
+    expect(result.journey.active).toBeNull();
+  });
+
+  it('returns defaults for null input', () => {
+    const result = parseProgressYaml(null);
+    expect(result.user.xp).toBe(0);
+  });
+
+  it('parses journey active: null correctly', () => {
+    const yaml = `journey:
+  active: null
+  progress: {}
+`;
+    const result = parseProgressYaml(yaml);
+    expect(result.journey.active).toBeNull();
+  });
+
+  it('parses quoted string values', () => {
+    const yaml = `user:
+  xp: 0
+  belt: 'white'
+modules:
+  git:
+    quiz_score: "4/5"
+`;
+    const result = parseProgressYaml(yaml);
+    expect(result.user.belt).toBe('white');
+    expect(result.modules.git.quiz_score).toBe('4/5');
+  });
+});
+
+describe('serializeProgressYaml', () => {
+  it('round-trips a progress object', () => {
+    const original = {
+      user: { xp: 100, belt: 'yellow', modules_completed: 1 },
+      modules: {
+        git: { status: 'completed', xp_earned: 100, started: '2026-03-01' },
+      },
+      journey: { active: 'frontend-developer', progress: {} },
+    };
+
+    const yaml = serializeProgressYaml(original);
+    const parsed = parseProgressYaml(yaml);
+    expect(parsed.user.xp).toBe(100);
+    expect(parsed.user.belt).toBe('yellow');
+    expect(parsed.modules.git.status).toBe('completed');
+    expect(parsed.modules.git.xp_earned).toBe(100);
+    expect(parsed.journey.active).toBe('frontend-developer');
+  });
+
+  it('serializes empty modules as modules: {}', () => {
+    const yaml = serializeProgressYaml({
+      user: { xp: 0 },
+      modules: {},
+      journey: { active: null, progress: {} },
+    });
+    expect(yaml).toContain('modules: {}');
+  });
+
+  it('serializes null journey active', () => {
+    const yaml = serializeProgressYaml({
+      user: { xp: 0 },
+      modules: {},
+      journey: { active: null, progress: {} },
+    });
+    expect(yaml).toContain('active: null');
+  });
+});
+
+// =====================================================================
+//  Group W — Unit: createFileProgressProvider
+// =====================================================================
+
+describe('createFileProgressProvider', () => {
+  const testFile = join(tmpdir(), `.socrates-progress-test-${Date.now()}.yaml`);
+
+  afterAll(() => {
+    try { if (existsSync(testFile)) unlinkSync(testFile); } catch {}
+  });
+
+  it('returns defaults when file does not exist', () => {
+    const provider = createFileProgressProvider(join(tmpdir(), 'nonexistent-progress.yaml'));
+    const progress = provider.getProgress();
+    expect(progress.user.xp).toBe(0);
+    expect(progress.modules).toEqual({});
+  });
+
+  it('reads and writes progress to file', () => {
+    const provider = createFileProgressProvider(testFile);
+
+    const progress = provider.getProgress();
+    progress.user.xp = 500;
+    progress.modules.git = { status: 'completed', xp_earned: 200 };
+    provider.saveProgress(progress);
+
+    const reloaded = provider.getProgress();
+    expect(reloaded.user.xp).toBe(500);
+    expect(reloaded.modules.git.status).toBe('completed');
+    expect(reloaded.modules.git.xp_earned).toBe(200);
+  });
+
+  it('reads an externally written progress file', () => {
+    const externalFile = join(tmpdir(), `.socrates-progress-ext-${Date.now()}.yaml`);
+    writeFileSync(externalFile, `user:
+  xp: 300
+  belt: green
+modules:
+  hooks:
+    status: in-progress
+    xp_earned: 75
+journey:
+  active: null
+  progress: {}
+`, 'utf-8');
+
+    try {
+      const provider = createFileProgressProvider(externalFile);
+      const progress = provider.getProgress();
+      expect(progress.user.xp).toBe(300);
+      expect(progress.user.belt).toBe('green');
+      expect(progress.modules.hooks.status).toBe('in-progress');
+      expect(progress.modules.hooks.xp_earned).toBe(75);
+    } finally {
+      try { unlinkSync(externalFile); } catch {}
+    }
+  });
+});