coursecode 0.1.43 → 0.1.46

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -679,7 +679,12 @@ Runs **in Node.js** during build (via `vite.framework-dev.config.js` `closeBundl
 
 ### MCP `coursecode_lint` — Build-Time Only
 
-The MCP `coursecode_lint` tool runs the build linter (config validation, CSS class verification, structure checks). It does NOT include runtime errors. For runtime errors and contrast warnings, use `coursecode_errors` (lightweight — just errors and console logs) or `coursecode_state` (full state snapshot including errors).
+The MCP `coursecode_lint` tool runs the static/build-time linter (config validation, CSS class verification, structure checks). It does **not** inspect the running preview and does **not** include live runtime, browser console, or Vite build-watch diagnostics.
+
+Use:
+- `coursecode_lint` for static preflight validation after source/config edits
+- `coursecode_errors` for the live "what is broken right now?" preview rollup
+- `coursecode_state` when you also need current slide, TOC, engagement, LMS state, and diagnostics
 
 ### Shared Rules (`lib/validation-rules.js`)
 
@@ -861,16 +866,18 @@ The MCP server runs a **persistent headless Chrome** internally via `puppeteer-c
 
 ### Preview Server Ownership
 
-The MCP does **not** start or manage the preview server. The preview must be running before using runtime tools:
+The MCP does **not** start or manage the preview server. Runtime tools connect to an already-running preview server.
 
-- **Human**: run `coursecode preview` (or `npm run preview`) in a terminal
-- **AI agent**: use your terminal/command execution tool to run `npm run preview`
+- If preview is already running for the current project, use it. Do **not** start a second preview server.
+- If preview is not running, start it in a terminal with `coursecode preview`.
+- For framework development from this repo, use `npm run preview`.
+- AI agents may start preview only via their terminal/command execution tool, and only after confirming preview is not already running or after a runtime MCP tool reports that preview is not running.
 
 If the preview is not running, runtime tools fail fast with a clear error message.
 
 ### Setup
 
-1. Start the preview server externally (see above)
+1. Make sure the preview server is running externally (see above)
 2. Add to IDE MCP config:
 
 ```json
@@ -885,10 +892,12 @@ If the preview is not running, runtime tools fail fast with a clear error messag
 
 ### Runtime Tools (require preview server)
 
+Tool results include machine-readable `structuredContent` plus text content for compatibility. Tool failures use structured error payloads with stable `code`, `message`, `hint`, and optional `details` fields so AI clients can recover without parsing prose.
+
 | Tool | Purpose | Returns |
 |------|---------|--------|
-| `coursecode_state` | Full course snapshot | `{slide, toc, interactions, engagement, lmsState, apiLog, errors, frameworkLogs, consoleLogs}` |
-| `coursecode_errors` | Errors + console logs only | `{errors, consoleLogs, count, clean}` — same error sources as `coursecode_state`, without the state payload |
+| `coursecode_state` | Full course snapshot + live diagnostics | `{slide, toc, interactions, engagement, lmsState, apiLog, diagnostics, issues, errors, frameworkLogs, consoleLogs}` |
+| `coursecode_errors` | Live diagnostic rollup only | `{build, runtime, framework, console, issues, errors, count, clean}` — same diagnostic sources as `coursecode_state`, without the state payload |
 | `coursecode_navigate` | Go to slide by ID | `{slide, interactions, engagement, accessibility}` |
 | `coursecode_interact` | Set response + evaluate | `{interactionId, response}` → `{correct, score, feedback}` |
 | `coursecode_screenshot` | Visual capture (JPEG) | Optional `slideId` to navigate first, `fullPage` for scroll capture |
@@ -933,7 +942,7 @@ MCP Server (IDE) ──puppeteer──▶ Headless Chrome ──HTTP──▶ Pr
                                     └── Course iframe (CourseCodeAutomation API)
 ```
 
-- **Preview not running?** → Tools return clear error: "Start preview server first"
+- **Preview not running?** → Tools return a clear error. Start preview externally in a terminal, then retry.
 - **Chrome not found?** → Install Google Chrome or set `CHROME_PATH` env var
 
 ### Pre-Release Responsive Checks (Framework)

package/framework/docs/USER_GUIDE.md

@@ -297,7 +297,8 @@ Once connected, your AI assistant gains these capabilities:
 | `coursecode_screenshot` | Take a screenshot of any slide |
 | `coursecode_interact` | Answer an interaction and check if it's correct |
 | `coursecode_reset` | Clear progress and restart the course |
-| `coursecode_lint` | Check for errors (bad CSS classes, missing components, config issues) |
+| `coursecode_errors` | Check live preview diagnostics (build, runtime, framework, and console issues) |
+| `coursecode_lint` | Run static preflight checks (bad CSS classes, missing components, config issues) |
 | `coursecode_component_catalog` | Browse available UI components (tabs, accordion, cards, etc.) |
 | `coursecode_interaction_catalog` | Browse available interaction types (multiple choice, drag-drop, etc.) |
 | `coursecode_css_catalog` | Browse available CSS classes by category |
@@ -306,7 +307,7 @@ Once connected, your AI assistant gains these capabilities:
 | `coursecode_workflow_status` | Get guidance on what to do next based on your project's current state |
 | `coursecode_build` | Build the course for LMS deployment |
 
-> **Note:** The preview server must be running before using runtime tools like `coursecode_state`, `coursecode_screenshot`, or `coursecode_navigate`. Start it with `coursecode preview` in a terminal.
+> **Note:** The preview server must be running before using runtime tools like `coursecode_state`, `coursecode_errors`, `coursecode_screenshot`, or `coursecode_navigate`. If preview is not already running for this project, start it with `coursecode preview` in a terminal. Do not start a second preview server if one is already running.
 
 ### How the Workflow Changes
 

package/framework/js/automation/api-interactions.js

@@ -6,7 +6,7 @@
 
 import interactionRegistry from '../managers/interaction-registry.js';
 import { courseConfig } from '../../../course/course-config.js';
-import { recordInteractionResult } from '../components/interactions/interaction-base.js';
+import { getInteractionState, recordInteractionResult } from '../components/interactions/interaction-base.js';
 import { logger } from '../utilities/logger.js';
 
 /**
@@ -18,11 +18,26 @@ export function createInteractionMethods(logTrace) {
     return {
         listInteractions() {
             const interactions = interactionRegistry.getAll();
-            const simplifiedList = interactions.map(i => ({
-                id: i.id,
-                type: i.type,
-                description: i.description
-            }));
+            const simplifiedList = interactions.map(i => {
+                const savedState = getInteractionState(i.id);
+                let response = savedState?.response;
+
+                if (response === undefined && typeof i.instance?.getResponse === 'function') {
+                    try {
+                        response = i.instance.getResponse();
+                    } catch {
+                        response = undefined;
+                    }
+                }
+
+                return {
+                    id: i.id,
+                    type: i.type,
+                    description: i.description,
+                    hasResponse: response !== null && response !== undefined && response !== '',
+                    isChecked: savedState?.submitted === true
+                };
+            });
             logTrace('listInteractions', { count: simplifiedList.length });
             return simplifiedList;
         },
@@ -33,10 +48,23 @@ export function createInteractionMethods(logTrace) {
                 throw new Error(`CourseCodeAutomation: Interaction "${interactionId}" not found on the current slide`);
             }
             logTrace('getInteractionMetadata', { interactionId });
+            const savedState = getInteractionState(entry.id);
+            let response = savedState?.response;
+
+            if (response === undefined && typeof entry.instance?.getResponse === 'function') {
+                try {
+                    response = entry.instance.getResponse();
+                } catch {
+                    response = undefined;
+                }
+            }
+
             return {
                 id: entry.id,
                 type: entry.type,
-                description: entry.description
+                description: entry.description,
+                hasResponse: response !== null && response !== undefined && response !== '',
+                isChecked: savedState?.submitted === true
             };
         },
 

package/lib/headless-browser.js

@@ -358,8 +358,8 @@ class HeadlessBrowser {
 
         // Navigate to specific slide if requested
         if (slideId) {
-            await this.evaluate((id) => {
-                window.CourseCodeAutomation.goToSlide(id);
+            await this.evaluate(async (id) => {
+                await window.CourseCodeAutomation.goToSlide(id);
             }, slideId);
             // Wait for slide transition
             await new Promise(resolve => setTimeout(resolve, 500));

package/lib/mcp-prompts.js

@@ -20,7 +20,7 @@ export const TOOLS = [
     // --- Runtime Tools (require headless browser) ---
     {
         name: 'coursecode_state',
-        description: `Get course state, runtime errors, and warnings in one call. This is the primary tool for checking errors.
+        description: `Get course state and live preview diagnostics in one call.
 
 Returns:
 - slide: current slide ID (string)
@@ -29,12 +29,15 @@ Returns:
 - engagement: slide engagement {complete, percentage, requirements}
 - lmsState: LMS data {score, completion, success, bookmark, format, objectives, state}
 - apiLog: last 20 LMS API calls [{timestamp, method, args, result}]
-- errors: runtime errors/warnings [{type, message, hint, isWarning}]
+- diagnostics: live issue rollup with build, runtime, framework, console, issues, count, clean
+- issues/errors: flat live issue list [{source, severity, isWarning, type, message, hint?}]
+- runtimeErrors: runtime/debug-panel errors and warnings only
+- buildErrors/buildWarnings: backward-compatible build-watch aliases
 - frameworkLogs: structured framework log events [{level, domain, operation, message, stack?, timestamp}]
 - consoleLogs: browser console warnings/errors [{type, text, time}]
 
 Use this first to understand the course state before taking actions.
-For error checking only (after file edits), prefer coursecode_errors — same error sources, smaller payload.
+For checking what is broken after file edits, prefer coursecode_errors — same live diagnostic sources, smaller payload.
 Requires preview server to be running.`,
         inputSchema: {
             type: 'object',
@@ -48,15 +51,23 @@ Requires preview server to be running.`,
     },
     {
         name: 'coursecode_errors',
-        description: `Get runtime errors and warnings from the live preview. Uses the same error sources as coursecode_state (preview server errors + browser console) but without the heavyweight state payload.
+        description: `Get all current live preview diagnostics without the heavyweight course state payload.
+
+This is the primary "what is broken right now?" tool after edits. It aggregates:
+- build: Vite/build-watch errors and warnings from the running preview server
+- runtime: stub LMS/debug-panel errors and warnings
+- framework: CourseCode logger warnings/errors
+- console: browser console warnings/errors
+
+This is different from coursecode_lint, which is a static/build-time linter and does not inspect the running preview.
 
 Returns:
-- errors: [{type, message, hint?, isWarning?}] — preview server errors and warnings
-- consoleLogs: [{type, text, time}] — browser console warnings/errors
-- count: total number of errors + console logs
-- clean: true if no errors, warnings, or console issues
+- build/runtime/framework/console: grouped diagnostics by source
+- issues/errors: flat list [{source, severity, isWarning, type, message, hint?}] for agents
+- count: total issue count
+- clean: true if no live issues were found
+- runtimeErrors/frameworkLogs/consoleLogs: source-specific aliases
 
-Use after making file changes to check for breakage without the overhead of coursecode_state.
 Requires preview server to be running.`,
         inputSchema: {
             type: 'object',
@@ -378,16 +389,16 @@ Use to discover available interactions before creating assessments.`,
     },
     {
         name: 'coursecode_lint',
-        description: `Run the course linter and get structured results.
+        description: `Run the static course linter and get structured results.
 
-Always runs build-time lint (config, CSS classes, structure). Does NOT include runtime errors — use coursecode_state for runtime errors and contrast warnings when the preview server is running.
+This is a preflight/static validation tool for config, source structure, CSS class names, and schema rules. It does NOT inspect the running preview and does NOT include live runtime, browser console, or Vite build-watch diagnostics. Use coursecode_errors for the live "what is broken right now?" view when preview is running.
 
 Returns:
 - errors: [{slideId?, rule, message, severity, hint?}]
 - warnings: [{slideId?, rule, message, severity, hint?}]
 - passed: boolean
 
-Build-time rules (always checked):
+Static rules (always checked):
 - undefined-css-class: hallucinated or stale class names (with fix suggestions)
 - unknown-component: unregistered data-component types
 - requirement-missing-component: engagement requirement without matching component
@@ -396,7 +407,7 @@ Build-time rules (always checked):
 - assessment-id-mismatch: config ID doesn't match assessment ID
 - invalid-gating: bad gating condition configuration
 
-Use AFTER making changes to validate the course.`,
+Use after making source/config changes as a fast static check. Then use coursecode_errors against the running preview for live diagnostics.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -764,12 +775,16 @@ All runtime tools (state, navigate, interact, screenshot, viewport, reset) execu
 
 ### Preview Server Ownership
 - The MCP does NOT start or manage the preview server
-- The preview must be started externally: run \`coursecode preview\` in a terminal (human) or via a terminal/command execution tool (AI agent)
-- If preview is not running, runtime tools will fail with a clear error message
+- Before using runtime tools, check whether preview is already running for this project
+- If preview is already running, use it; do not start a second preview server
+- If preview is not running, start it externally in a terminal: run \`coursecode preview\` (or \`npm run preview\` for framework development)
+- AI agents may start preview only via a terminal/command execution tool, and only after a runtime tool reports that preview is not running
 - The headless browser auto-reconnects when Vite rebuilds (file changes)
 
 ### Navigation API
-- coursecode_state → get slim TOC with slide IDs, current slide, interactions, engagement, lmsState, apiLog, errors, frameworkLogs, consoleLogs
+- coursecode_state → get slim TOC with slide IDs, current slide, interactions, engagement, lmsState, apiLog, diagnostics, frameworkLogs, consoleLogs
+- coursecode_errors → get live diagnostics only (build/runtime/framework/console); use this after edits
+- coursecode_lint → run static preflight lint only; it is not a live preview diagnostic
 - coursecode_navigate(slideId) → go to any slide instantly by ID
 - coursecode_viewport(breakpoint or {width,height}) → set viewport for responsive testing (persists until changed)
 - coursecode_screenshot(slideId) → navigate + capture in one call (quality modes only, never changes viewport)

package/lib/mcp-server.js

@@ -37,6 +37,178 @@ import { TOOLS, buildInstructions, getWorkflowStatusWithInstructions } from './m
 
 const DEFAULT_PORT = 4173;
 
+class McpToolError extends Error {
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'McpToolError';
+        this.code = code;
+        this.hint = options.hint;
+        this.details = options.details;
+    }
+}
+
+function normalizePort(port) {
+    const parsed = parseInt(port ?? DEFAULT_PORT, 10);
+    return Number.isFinite(parsed) ? parsed : DEFAULT_PORT;
+}
+
+function makeToolResult(result) {
+    return {
+        content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+        }],
+        structuredContent: result
+    };
+}
+
+function normalizeToolError(error) {
+    if (error instanceof McpToolError) {
+        return {
+            code: error.code,
+            message: error.message,
+            ...(error.hint ? { hint: error.hint } : {}),
+            ...(error.details ? { details: error.details } : {})
+        };
+    }
+
+    const message = error?.message || String(error);
+    if (/Preview server not running/i.test(message)) {
+        return {
+            code: 'preview_not_running',
+            message,
+            hint: 'Start the CourseCode preview server for this project, then retry the MCP tool call.'
+        };
+    }
+
+    if (/Slide ".*" not found/i.test(message)) {
+        return {
+            code: 'invalid_slide_id',
+            message,
+            hint: 'Call coursecode_state to get valid slide IDs, then retry with one of those IDs.'
+        };
+    }
+
+    if (/is required|Provide either/i.test(message)) {
+        return {
+            code: 'invalid_arguments',
+            message,
+            hint: 'Check the tool input schema and retry with the required arguments.'
+        };
+    }
+
+    if (/Unknown tool:/i.test(message)) {
+        return {
+            code: 'unknown_tool',
+            message,
+            hint: 'Call tools/list and retry with one of the advertised CourseCode tool names.'
+        };
+    }
+
+    return {
+        code: 'tool_failed',
+        message,
+        hint: 'Inspect the message and retry after correcting the underlying issue.'
+    };
+}
+
+function makeToolErrorResult(error) {
+    const normalized = normalizeToolError(error);
+    const result = {
+        success: false,
+        error: normalized,
+        code: normalized.code,
+        message: normalized.message,
+        ...(normalized.hint ? { hint: normalized.hint } : {}),
+        ...(normalized.details ? { details: normalized.details } : {})
+    };
+
+    return {
+        content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+        }],
+        structuredContent: result,
+        isError: true
+    };
+}
+
+function normalizeIssue(source, severity, issue) {
+    const isWarning = severity === 'warning' || issue?.isWarning === true || issue?.level === 'warn';
+    return {
+        source,
+        severity: isWarning ? 'warning' : 'error',
+        isWarning,
+        type: issue?.type || issue?.domain || source,
+        message: issue?.message || issue?.text || String(issue),
+        ...(issue?.hint ? { hint: issue.hint } : {}),
+        ...(issue?.operation ? { operation: issue.operation } : {}),
+        ...(issue?.time ? { time: issue.time } : {}),
+        ...(issue?.timestamp ? { timestamp: issue.timestamp } : {})
+    };
+}
+
+async function getLiveDiagnostics(port, frameworkLogs = []) {
+    const diagnostics = {
+        build: { errors: [], warnings: [] },
+        runtime: { errors: [], warnings: [] },
+        framework: { errors: [], warnings: [] },
+        console: { errors: [], warnings: [] },
+        issues: []
+    };
+
+    try {
+        const buildResp = await fetch(`http://localhost:${port}/__mcp/errors`);
+        if (buildResp.ok) {
+            const buildData = await buildResp.json();
+            diagnostics.build.errors = buildData.errors || [];
+            diagnostics.build.warnings = buildData.warnings || [];
+        }
+    } catch {
+        // Preview build diagnostics unavailable — leave empty.
+    }
+
+    try {
+        const errResp = await fetch(`http://localhost:${port}/__lms/errors`);
+        if (errResp.ok) {
+            const errData = await errResp.json();
+            diagnostics.runtime.errors = errData.errors || [];
+            diagnostics.runtime.warnings = errData.warnings || [];
+        }
+    } catch {
+        // Runtime diagnostics unavailable — leave empty.
+    }
+
+    for (const log of frameworkLogs || []) {
+        if (log.level === 'warn') diagnostics.framework.warnings.push(log);
+        else if (log.level === 'error' || log.level === 'fatal') diagnostics.framework.errors.push(log);
+    }
+
+    const consoleLogs = headless.getConsoleLogs();
+    for (const log of consoleLogs) {
+        // logger.warn/error entries are already represented as structured
+        // framework diagnostics, so do not double-count their console echo.
+        if (/^\[(WARN|ERROR|FATAL)\]/.test(log.text || '')) continue;
+        if (log.type === 'warning') diagnostics.console.warnings.push(log);
+        else diagnostics.console.errors.push(log);
+    }
+
+    diagnostics.issues = [
+        ...diagnostics.build.errors.map(issue => normalizeIssue('build', 'error', issue)),
+        ...diagnostics.build.warnings.map(issue => normalizeIssue('build', 'warning', issue)),
+        ...diagnostics.runtime.errors.map(issue => normalizeIssue('runtime', 'error', issue)),
+        ...diagnostics.runtime.warnings.map(issue => normalizeIssue('runtime', 'warning', issue)),
+        ...diagnostics.framework.errors.map(issue => normalizeIssue('framework', 'error', issue)),
+        ...diagnostics.framework.warnings.map(issue => normalizeIssue('framework', 'warning', issue)),
+        ...diagnostics.console.errors.map(issue => normalizeIssue('console', 'error', issue)),
+        ...diagnostics.console.warnings.map(issue => normalizeIssue('console', 'warning', issue))
+    ];
+
+    diagnostics.count = diagnostics.issues.length;
+    diagnostics.clean = diagnostics.count === 0;
+    return diagnostics;
+}
+
 /**
  * Ensure headless browser is connected to preview server.
  * Fails fast if preview is not running — humans own the preview lifecycle.
@@ -60,7 +232,7 @@ async function ensureHeadless(port) {
  * Create and run the MCP server
  */
 export async function startMcpServer(options = {}) {
-    const port = options.port || DEFAULT_PORT;
+    const port = normalizePort(options.port);
     
     // Build dynamic instructions for current authoring stage
     const instructions = await buildInstructions(port);
@@ -68,10 +240,10 @@ export async function startMcpServer(options = {}) {
     const server = new Server(
         {
             name: 'coursecode',
-            version: '2.0.0',
-            instructions
+            version: '2.0.0'
         },
         {
+            instructions,
             capabilities: {
                 tools: {}
             }
@@ -106,29 +278,32 @@ export async function startMcpServer(options = {}) {
                             lmsState: api.getLmsState()
                         };
                     });
-                    // Read API log and error log from preview server (same data user sees in debug panel)
+                    // Read API log plus a unified diagnostic rollup from the preview server/headless page.
                     try {
-                        const [logResp, errResp] = await Promise.all([
-                            fetch(`http://localhost:${port}/__lms/log`),
-                            fetch(`http://localhost:${port}/__lms/errors`)
-                        ]);
+                        const logResp = await fetch(`http://localhost:${port}/__lms/log`);
                         result.apiLog = logResp.ok ? (await logResp.json()).entries?.slice(0, 20) || [] : [];
-                        if (errResp.ok) {
-                            const errData = await errResp.json();
-                            result.errors = [...(errData.errors || []), ...(errData.warnings || [])];
-                        } else {
-                            result.errors = [];
-                        }
                     } catch {
                         result.apiLog = [];
-                        result.errors = [];
                     }
-                    // Append console errors/warnings captured from the page
-                    result.consoleLogs = headless.getConsoleLogs();
+                    result.diagnostics = await getLiveDiagnostics(port, result.frameworkLogs);
+                    result.issues = result.diagnostics.issues;
+                    result.errors = result.diagnostics.issues;
+                    result.runtimeErrors = [
+                        ...result.diagnostics.runtime.errors,
+                        ...result.diagnostics.runtime.warnings
+                    ];
+                    result.buildErrors = result.diagnostics.build.errors;
+                    result.buildWarnings = result.diagnostics.build.warnings;
+                    result.consoleLogs = [
+                        ...result.diagnostics.console.errors,
+                        ...result.diagnostics.console.warnings
+                    ];
                     break;
 
                 case 'coursecode_navigate':
-                    if (!args?.slideId) throw new Error('slideId is required');
+                    if (!args?.slideId) throw new McpToolError('missing_required_argument', 'slideId is required', {
+                        hint: 'Call coursecode_state to get valid slide IDs, then pass one as slideId.'
+                    });
                     await ensureHeadless(port);
                     // Apply accessibility preferences before navigation
                     if (args.theme || args.highContrast !== undefined) {
@@ -147,11 +322,14 @@ export async function startMcpServer(options = {}) {
                             return toc.some(item => item.id === slideId);
                         }, args.slideId);
                         if (!validSlide) {
-                            throw new Error(`Slide "${args.slideId}" not found. Use coursecode_state to get valid slide IDs.`);
+                            throw new McpToolError('invalid_slide_id', `Slide "${args.slideId}" not found.`, {
+                                hint: 'Call coursecode_state to get valid slide IDs, then retry with one of those IDs.',
+                                details: { slideId: args.slideId }
+                            });
                         }
                     }
-                    await headless.evaluate((slideId) => {
-                        window.CourseCodeAutomation.goToSlide(slideId);
+                    await headless.evaluate(async (slideId) => {
+                        await window.CourseCodeAutomation.goToSlide(slideId);
                     }, args.slideId);
                     // State updates asynchronously after navigation
                     await new Promise(resolve => setTimeout(resolve, 50));
@@ -167,8 +345,12 @@ export async function startMcpServer(options = {}) {
                     break;
 
                 case 'coursecode_interact':
-                    if (!args?.interactionId) throw new Error('interactionId is required');
-                    if (args.response === undefined) throw new Error('response is required');
+                    if (!args?.interactionId) throw new McpToolError('missing_required_argument', 'interactionId is required', {
+                        hint: 'Call coursecode_state on the target slide to list valid interaction IDs.'
+                    });
+                    if (args.response === undefined) throw new McpToolError('missing_required_argument', 'response is required', {
+                        hint: 'Pass a response value matching the interaction type.'
+                    });
                     await ensureHeadless(port);
                     result = await headless.evaluate(({ interactionId, response }) => {
                         const api = window.CourseCodeAutomation;
@@ -204,7 +386,10 @@ export async function startMcpServer(options = {}) {
                             return toc.some(item => item.id === slideId);
                         }, args.slideId);
                         if (!validSlide) {
-                            throw new Error(`Slide "${args.slideId}" not found. Use coursecode_state to get valid slide IDs.`);
+                            throw new McpToolError('invalid_slide_id', `Slide "${args.slideId}" not found.`, {
+                                hint: 'Call coursecode_state to get valid slide IDs, then retry with one of those IDs.',
+                                details: { slideId: args.slideId }
+                            });
                         }
                     }
                     result = await headless.screenshot({
@@ -228,30 +413,33 @@ export async function startMcpServer(options = {}) {
                     } else if (args?.width && args?.height) {
                         result = await headless.setViewport({ width: args.width, height: args.height });
                     } else {
-                        throw new Error('Provide either a breakpoint name or both width and height.');
+                        throw new McpToolError('missing_required_argument', 'Provide either a breakpoint name or both width and height.', {
+                            hint: 'Use breakpoint: "desktop" or pass explicit width and height numbers.'
+                        });
                     }
                     break;
 
                 case 'coursecode_errors': {
-                    // Same error-gathering mechanism as coursecode_state,
-                    // but without the heavyweight state payload (TOC, interactions, etc.)
+                    // Live diagnostic rollup without the heavyweight state payload (TOC, interactions, etc.).
                     await ensureHeadless(port);
-                    let errors = [];
-                    try {
-                        const errResp = await fetch(`http://localhost:${port}/__lms/errors`);
-                        if (errResp.ok) {
-                            const errData = await errResp.json();
-                            errors = [...(errData.errors || []), ...(errData.warnings || [])];
-                        }
-                    } catch {
-                        // Preview server unreachable — errors array stays empty
-                    }
-                    const consoleLogs = headless.getConsoleLogs();
+                    const frameworkLogs = await headless.evaluate(() => {
+                        return window.CourseCodeAutomation.getFrameworkLogs();
+                    });
+                    const diagnostics = await getLiveDiagnostics(port, frameworkLogs);
                     result = {
-                        errors,
-                        consoleLogs,
-                        count: errors.length + consoleLogs.length,
-                        clean: errors.length === 0 && consoleLogs.length === 0
+                        ...diagnostics,
+                        // Convenience aliases for agents that expect a flat list.
+                        issues: diagnostics.issues,
+                        errors: diagnostics.issues,
+                        runtimeErrors: [
+                            ...diagnostics.runtime.errors,
+                            ...diagnostics.runtime.warnings
+                        ],
+                        frameworkLogs,
+                        consoleLogs: [
+                            ...diagnostics.console.errors,
+                            ...diagnostics.console.warnings
+                        ]
                     };
                     break;
                 }
@@ -295,23 +483,15 @@ export async function startMcpServer(options = {}) {
 
 
                 default:
-                    throw new Error(`Unknown tool: ${name}`);
+                    throw new McpToolError('unknown_tool', `Unknown tool: ${name}`, {
+                        hint: 'Call tools/list and retry with one of the advertised CourseCode tool names.',
+                        details: { name }
+                    });
             }
-            
-            return {
-                content: [{
-                    type: 'text',
-                    text: JSON.stringify(result, null, 2)
-                }]
-            };
+
+            return makeToolResult(result);
         } catch (error) {
-            return {
-                content: [{
-                    type: 'text',
-                    text: `Error: ${error.message}`
-                }],
-                isError: true
-            };
+            return makeToolErrorResult(error);
         }
     });
 
@@ -355,6 +535,7 @@ export async function startMcpServer(options = {}) {
 if (process.argv[1]?.endsWith('mcp-server.js')) {
     const args = process.argv.slice(2);
     const portArg = args.find(a => a.startsWith('--port='));
-    const port = portArg ? parseInt(portArg.split('=')[1], 10) : DEFAULT_PORT;
+    const portValue = portArg ? portArg.split('=')[1] : args[args.indexOf('--port') + 1];
+    const port = normalizePort(portValue);
     startMcpServer({ port });
 }

package/lib/preview-server.js

@@ -269,6 +269,11 @@ export async function previewServer(options = {}) {
     viteProcess.stdout.on('data', (data) => {
         const output = data.toString();
         process.stdout.write(output);
+        if (output.includes('Building...')) {
+            buildState.errors = [];
+            buildState.warnings = [];
+            buildState.lastBuildSuccess = false;
+        }
         if (output.includes('Build complete')) {
             buildState.lastBuildTime = new Date().toISOString();
             buildState.lastBuildSuccess = true;

package/lib/upgrade.js

@@ -83,6 +83,36 @@ function copyFileWithBackup(src, dest) {
   return { updated: true, backup: null };
 }
 
+export function addMissingRuntimeDependencies(projectPkg, templatePkg) {
+  const requiredDeps = templatePkg.dependencies || {};
+  const existingDeps = projectPkg.dependencies || {};
+  const existingDevDeps = projectPkg.devDependencies || {};
+  const added = [];
+
+  for (const [name, version] of Object.entries(requiredDeps)) {
+    if (existingDeps[name]) {
+      continue;
+    }
+
+    existingDeps[name] = existingDevDeps[name] || version;
+    delete existingDevDeps[name];
+    added.push(name);
+  }
+
+  if (added.length > 0) {
+    projectPkg.dependencies = Object.fromEntries(
+      Object.entries(existingDeps).sort(([a], [b]) => a.localeCompare(b))
+    );
+    if (projectPkg.devDependencies) {
+      projectPkg.devDependencies = Object.fromEntries(
+        Object.entries(existingDevDeps).sort(([a], [b]) => a.localeCompare(b))
+      );
+    }
+  }
+
+  return added;
+}
+
 export async function upgrade(options = {}) {
   const cwd = process.cwd();
   const rcPath = path.join(cwd, '.coursecoderc.json');
@@ -109,6 +139,7 @@ export async function upgrade(options = {}) {
   // Get CLI version (this is the version we'll upgrade to)
   const cliPkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
   const targetVersion = cliPkg.version;
+  const templatePkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'template', 'package.json'), 'utf-8'));
 
   console.log(`
 📦 CourseCode Upgrade
@@ -138,6 +169,7 @@ export async function upgrade(options = {}) {
    - framework/     (replace entirely)
    - schemas/       (replace entirely)
    - lib/manifest/  (replace entirely)
+   - package.json   (add missing runtime dependencies)
    - .coursecoderc.json  (update version)`;
 
     if (options.configs) {
@@ -150,7 +182,6 @@ export async function upgrade(options = {}) {
    
    Would NOT touch:
    - course/        (your content)${!options.configs ? '\n   - vite.config.js\n   - eslint.config.js' : ''}
-   - package.json
    - .env
 `;
     console.log(dryRunMsg);
@@ -231,6 +262,18 @@ export async function upgrade(options = {}) {
   rcConfig.upgradedFrom = currentVersion;
   fs.writeFileSync(rcPath, JSON.stringify(rcConfig, null, 2));
 
+  // Add any runtime dependencies introduced by the new framework while preserving
+  // the project's existing version ranges.
+  const pkgPath = path.join(cwd, 'package.json');
+  let addedRuntimeDeps = [];
+  if (fs.existsSync(pkgPath)) {
+    const projectPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    addedRuntimeDeps = addMissingRuntimeDependencies(projectPkg, templatePkg);
+    if (addedRuntimeDeps.length > 0) {
+      fs.writeFileSync(pkgPath, JSON.stringify(projectPkg, null, 2) + '\n');
+    }
+  }
+
   let successMsg = `
 ✅ Upgrade complete!
 
@@ -238,6 +281,15 @@ export async function upgrade(options = {}) {
 
    Your course/ directory was not modified.`;
 
+  if (addedRuntimeDeps.length > 0) {
+    successMsg += `
+
+   Runtime dependencies added to package.json:
+   - ${addedRuntimeDeps.join('\n   - ')}
+
+   Run npm install to update node_modules and your lockfile.`;
+  }
+
   if (configUpdates.length > 0) {
     successMsg += `
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecode",
-  "version": "0.1.43",
+  "version": "0.1.46",
   "description": "Multi-format course authoring framework with CLI tools (SCORM 2004, SCORM 1.2, cmi5, LTI 1.3)",
   "type": "module",
   "bin": {

package/template/vite.config.js

@@ -190,6 +190,7 @@ function scanDistFiles() {
 function scormPostBuild(isDev) {
   return {
     name: 'scorm-post-build',
+    enforce: 'post',
     buildStart() {
       if (isDev) console.log('🔨 Building...');
     },
@@ -251,7 +252,7 @@ function scormPostBuild(isDev) {
             console.log('\n📦 Creating external hosting package archives...');
             await createExternalPackagesForClients({ rootDir: ROOT_DIR, config });
           }
-          console.log('\n✅ Package built successfully');
+          console.log('\n✓ Package archive created');
         } else {
           console.log('✅ Build complete\n');
         }