coursecode 0.1.6 → 0.1.7

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -4,7 +4,6 @@
 
 **Related Docs:**
 - `COURSE_AUTHORING_GUIDE.md` - For course authors (not framework devs)
-
 - `DATA_MODEL.md` - Complete learner data schemas and storage architecture
 
 ---
@@ -143,7 +142,7 @@ const stampedHtml = stampFormat(indexHtml, 'scorm2004');
 const { filename, content } = generateManifest('scorm2004', config, files, options);
 ```
 
-Both are pure Node utilities
+Both are pure Node utilities.
 
 #### Key Files
 
@@ -574,6 +573,7 @@ This codebase serves two roles:
 |------|---------|---------|
 | `vite.framework-dev.config.js` | Framework developers (this repo) | Builds from `template/course/`, references `lib/` directly |
 | `template/vite.config.js` | Course authors (their project) | Builds from `course/`, imports from `coursecode` package |
+
 ### Preview Architecture
 
 Preview is **not** part of the build output. It is platform infrastructure, served separately from `dist/`:
@@ -599,7 +599,7 @@ User: coursecode build → uploads dist/
     Cloud Preview       Cloud ZIP (SCORM 2004)  Cloud ZIP (SCORM 1.2)
     ┌────────────┐      ┌──────────────────┐    ┌──────────────────┐
     │ Cloud's own │      │ Copy dist/       │    │ Copy dist/       │
-    │ stub player │      │ stampFormatInHtml│    │ stampFormatInHtml│
+    │ stub player │      │ stampFormat      │    │ stampFormat      │
     │ iframes the │      │ generateManifest │    │ generateManifest │
     │ uploaded    │      │ → ZIP            │    │ → ZIP            │
     │ dist/       │      └──────────────────┘    └──────────────────┘
@@ -609,6 +609,7 @@ User: coursecode build → uploads dist/
 **Cloud dependencies:** The cloud app imports `stampFormat` and `generateManifest` directly from the `coursecode` npm package. These are pure functions — no filesystem, no Vite, no dynamic imports of user code, no `eval`. All inputs (title, version, file list) come from scanning the uploaded `dist/` or the cloud's own database.
 
 **Security boundary:** The cloud never executes `course-config.js` or any user-authored JavaScript. The meta tag and manifest are the only format-specific artifacts, and both are generated from trusted framework source code.
+
 ---
 
 ## Course Validation
@@ -819,9 +820,6 @@ environment: {
 **Interactions**: `{id}-check-answer`, `{id}-reset`, `{id}-controls`, `{id}-feedback`, `{id}-choice-{index}`, `{id}-blank-{index}`, `{id}-input`, `{id}-drag-item-{itemId}`, `{id}-drop-zone-{zoneId}`
 
 **Assessments**: `assessment-start`, `assessment-nav-{prev|next}`, `assessment-submit`, `assessment-retake`, `assessment-review-question-{index}`
-
-
-
 ---
 
 ## MCP Integration (AI Agent Control)
@@ -833,7 +831,7 @@ The MCP server runs a **persistent headless Chrome** internally via `puppeteer-c
 The MCP does **not** start or manage the preview server. The preview must be running before using runtime tools:
 
 - **Human**: run `coursecode preview` (or `npm run preview`) in a terminal
-- **AI agent**: use `run_command` to execute `npm run preview`
+- **AI agent**: use your terminal/command execution tool to run `npm run preview`
 
 If the preview is not running, runtime tools fail fast with a clear error message.
 
@@ -856,12 +854,12 @@ If the preview is not running, runtime tools fail fast with a clear error messag
 
 | Tool | Purpose | Returns |
 |------|---------|--------|
-| `coursecode_state` | Full course snapshot | `{slide, structure, interactions, engagement, lmsState, errors}` |
-| `coursecode_navigate` | Go to slide by ID | `{slideId}` → new state |
+| `coursecode_state` | Full course snapshot | `{slide, toc, interactions, engagement, lmsState, apiLog, errors, frameworkLogs, consoleLogs}` |
+| `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 |
 | `coursecode_viewport` | Set viewport size | Breakpoint name or `{width, height}` → persists until changed |
-| `coursecode_reset` | Clear learner state | `{hard?: boolean}` → reload |
+| `coursecode_reset` | Clear learner state | No input; clears local state and reloads |
 
 ### Screenshot Quality Modes
 
@@ -881,6 +879,8 @@ Use `coursecode_viewport` for responsive design testing. Two input modes:
 
 The viewport **persists** until explicitly changed again. Default is 1280×720.
 
+> **AI tip:** For realistic mobile QA, use explicit phone dimensions (for example `{width: 375, height: 812}`) in addition to named breakpoints.
+
 ### Navigation API
 
 Use MCP tools for all course interaction — never use external browser tools:
@@ -902,6 +902,18 @@ MCP Server (IDE) ──puppeteer──▶ Headless Chrome ──HTTP──▶ Pr
 - **Preview not running?** → Tools return clear error: "Start preview server first"
 - **Chrome not found?** → Install Google Chrome or set `CHROME_PATH` env var
 
+### Pre-Release Responsive Checks (Framework)
+
+Before merging responsive/layout changes:
+
+```bash
+npm run prerelease:check
+npm run smoke:responsive -- --profile=expanded
+```
+
+- `lint:responsive` guards `responsive.css` ownership (no shell/chrome selectors)
+- `lint:responsive:structure` enforces layout exclusions/scoping for high-risk shell selectors
+
 ---
 
 ## Audio Manager (Internals)
@@ -983,6 +995,8 @@ eventBus.on('assessment:retake', ({ id, attemptNumber }) => { });
 | `components/*.css` | Individual UI component styles (cards, hero, tabs, steps, timeline, etc.) |
 | `interactions/*.css` | Interaction-specific styles |
 | `utilities/*.css` | Utility classes (spacing, display, flex) |
+| `responsive.css` | Shared content/component responsive rules (non-shell) |
+| `responsive-structure.css` | App shell/header/footer/nav/audio responsive rules |
 | `framework.css` | Main import file, orchestrates all modules |
 
 ### Layout System
@@ -1002,11 +1016,18 @@ CSS-only layouts controlled via `data-layout` attribute on `<html>`. Files in `f
 
 Set via `layout` in `course-config.js`. The `main.js` automatically applies the attribute from config.
 
+### Responsive CSS Ownership
+
+- Put shared content/component responsive rules in `framework/css/responsive.css`.
+- Put shell/chrome responsive rules (`#app`, header/brand, footer/nav/audio) in `framework/css/responsive-structure.css`.
+- For generic shell selectors, exclude layout-owned behavior (especially `article` and `focused`) unless explicitly layout-scoped.
+
 ### Auto-Wrapping
 
 Slides are automatically wrapped with content width class (default: `.content-medium`).
 
 Override per-slide with `data-content-width` attribute or globally via `slideDefaults.contentWidth` in `course-config.js`.
+
 ### Document Gallery
 
 `framework/js/navigation/document-gallery.js` — Collapsible sidebar gallery for reference documents.

package/framework/docs/USER_GUIDE.md

@@ -286,8 +286,9 @@ Once connected, your AI assistant gains these capabilities:
 
 | Tool | What It Does |
 |------|--------------|
-| `coursecode_state` | Get the full course state — current slide, structure, interactions, engagement, errors |
+| `coursecode_state` | Get the full course state — current slide, TOC, interactions, engagement, LMS state, logs, and errors |
 | `coursecode_navigate` | Jump to any slide by ID |
+| `coursecode_viewport` | Set the preview viewport (named breakpoint or explicit width/height) for responsive testing |
 | `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 |
@@ -296,6 +297,7 @@ Once connected, your AI assistant gains these capabilities:
 | `coursecode_interaction_catalog` | Browse available interaction types (multiple choice, drag-drop, etc.) |
 | `coursecode_css_catalog` | Browse available CSS classes by category |
 | `coursecode_icon_catalog` | Browse available icons by name/category |
+| `coursecode_export_content` | Export course content/interactions as Markdown or JSON for review |
 | `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 |
 

package/framework/js/utilities/icons.js

@@ -6,6 +6,8 @@
  */
 
 // Map pixel values to size class names
+import { logger } from './logger.js';
+
 const SIZE_MAP = {
     12: 'xs',
     16: 'sm',
@@ -99,14 +101,14 @@ class IconManager {
 
         // Check if it's an emoji - warn but handle gracefully
         if (this._isEmoji(name)) {
-            console.warn(`[IconManager] Emoji "${name}" passed to getIcon(). Use getEmoji() instead.`);
+            logger.warn(`[IconManager] Emoji "${name}" passed to getIcon(). Use getEmoji() instead.`);
             const size = typeof options === 'object' ? options.size : undefined;
             const extraClass = typeof options === 'object' ? options.class : (typeof options === 'string' ? options : '');
             return this.getEmoji(name, size, extraClass);
         }
 
         // Warn about unknown icons but don't block course loading - return a placeholder
-        console.warn(`[IconManager] Unknown icon: "${name}". Add it to DEFAULT_ICONS or course/icons.js.`);
+        logger.warn(`[IconManager] Unknown icon: "${name}". Add it to DEFAULT_ICONS or course/icons.js.`);
         const classes = ['icon', `icon-${name}`, 'icon-missing', sizeClass, className].filter(Boolean).join(' ');
         // Return a simple question mark circle as placeholder
         return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="${color}" stroke-width="${strokeWidth}" stroke-linecap="round" stroke-linejoin="round" class="${classes}" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/><path d="M12 17h.01"/></svg>`;

package/lib/cloud.js

@@ -583,6 +583,10 @@ export async function deploy(options = {}) {
   formData.append('file', new Blob([zipBuffer], { type: 'application/zip' }), 'deploy.zip');
   formData.append('orgId', orgId);
 
+  if (options.message) {
+    formData.append('message', options.message);
+  }
+
   if (options.preview && options.password) {
     const pw = await prompt('  Preview password: ');
     formData.append('password', pw);

package/lib/headless-browser.js

@@ -169,7 +169,7 @@ class HeadlessBrowser {
         // CourseCodeAutomation exists early but .ready is set after full boot
         await this.courseFrame.waitForFunction(
             () => window.CourseCodeAutomation?.ready === true,
-            { timeout: 10000 }
+            { timeout: 30000 }
         );
     }
 

package/lib/mcp-prompts.js

@@ -497,7 +497,7 @@ This creates a course/ directory with the starter template.
 After creating the project, the author should add reference files (PDF, DOCX, PPTX) to course/references/ for conversion.
 
 ## Next Stage
-Once the project exists and reference files are added, Stage 1 (Source Ingestion) begins. Run workflow_status to refresh.`;
+Once the project exists and reference files are added, Stage 1 (Source Ingestion) begins. Run coursecode_workflow_status to refresh.`;
 
         case 1: { // Source Ingestion
             const rawFiles = listSafe(refsDir, ['.pdf', '.docx', '.doc', '.pptx', '.ppt']);
@@ -525,7 +525,7 @@ Convert to markdown: coursecode convert
 Converted files appear in course/references/converted/
 
 ## Next Stage
-Once references are converted to markdown, Stage 2 (Outline Creation) begins. Call workflow_status after conversion to get updated guidance.`;
+Once references are converted to markdown, Stage 2 (Outline Creation) begins. Call coursecode_workflow_status after conversion to get updated guidance.`;
         }
 
         case 2: { // Outline Creation
@@ -552,7 +552,7 @@ The outline is a DESIGN document. Define content, interactions, structure, engag
 Pause for author review after creating the outline.
 
 ## Next Stage
-Once the outline is approved, Stage 3 (Course Building) begins. Call workflow_status to get updated guidance.`;
+Once the outline is approved, Stage 3 (Course Building) begins. Call coursecode_workflow_status to get updated guidance.`;
         }
 
         case 3: { // Course Building
@@ -584,8 +584,8 @@ ${refList}
      Only import local assets (images, SVGs): import myImage from '../assets/images/photo.png';
      Interactions: const { createMultipleChoiceQuestion } = CourseCode; (destructure from global, NOT import)
      Components: use data-component="tabs" in HTML (declarative, no JS needed)
-   - Use css_catalog to discover available CSS classes by category. Lint catches invalid classes with fix suggestions.
-   - Use component_catalog and interaction_catalog to discover available components and interactions.
+   - Use coursecode_css_catalog to discover available CSS classes by category. Lint catches invalid classes with fix suggestions.
+   - Use coursecode_component_catalog and coursecode_interaction_catalog to discover available components and interactions.
    - Run lint after each batch of file changes. Fix all errors before proceeding.
    - Never modify files in framework/ — all work goes in course/ only.
    - No em-dashes in sentence structure. Use alternative phrasing.
@@ -593,7 +593,7 @@ ${refList}
 Pause for author review after the initial slide build.
 
 ## Next Stage
-Once slides and config are built, Stage 4 (Preview & Polish) begins. Start the preview and call workflow_status for updated guidance.`;
+Once slides and config are built, Stage 4 (Preview & Polish) begins. Start the preview and call coursecode_workflow_status for updated guidance.`;
         }
 
         case 4: { // Preview & Polish
@@ -608,7 +608,7 @@ Once slides and config are built, Stage 4 (Preview & Polish) begins. Start the p
 
 This course was imported from a PowerPoint presentation. Each slide is currently a static image. Your job is to enhance it into an interactive course.
 
-1. Ensure the preview server is running (\`coursecode preview\` in a terminal, or AI uses run_command)
+1. Ensure the preview server is running (\`coursecode preview\` in a terminal, or AI uses a terminal/command execution tool)
 2. Review slides: screenshot each to understand the content
 3. Enhancement priorities:
    - **Replace image slides** with interactive HTML — use the extracted text from references/converted/ as source content
@@ -618,7 +618,7 @@ This course was imported from a PowerPoint presentation. Each slide is currently
    - **Customize theme** — update colors in course/theme.css
 ${refList ? `\n4. REFERENCE MATERIALS (extracted text from presentation):\n${refList}\n` : ''}
 5. RULES:
-   - Use css_catalog, component_catalog, interaction_catalog to discover available tools
+   - Use coursecode_css_catalog, coursecode_component_catalog, and coursecode_interaction_catalog to discover available options
    - Run lint after changes. Fix all errors before proceeding.
    - Efficient loop: edit files → lint → fix errors → screenshot to verify
 
@@ -630,15 +630,15 @@ Once polished and lint passes, Stage 5 (Export Ready) begins.`;
 
 Visually verify and polish the course using the preview server.
 
-1. Ensure the preview server is running (\`coursecode preview\` in a terminal, or AI uses run_command)
+1. Ensure the preview server is running (\`coursecode preview\` in a terminal, or AI uses a terminal/command execution tool)
 2. Do NOT open a browser yourself — the MCP has its own headless Chrome
 3. Workflow (all tools execute instantly via internal headless browser):
-   - state — get course structure, current slide, interactions, engagement
-   - navigate — go to any slide by ID (get IDs from state)
-   - screenshot — capture visual state (accepts slideId to navigate+capture in one call)
-   - interact — test interactions with responses
-   - export_content — extract all text content to review or compare against outline
-   - lint — validate after file changes
+   - coursecode_state — get course structure, current slide, interactions, engagement
+   - coursecode_navigate — go to any slide by ID (get IDs from coursecode_state)
+   - coursecode_screenshot — capture visual state (accepts slideId to navigate+capture in one call)
+   - coursecode_interact — test interactions with responses
+   - coursecode_export_content — extract all text content to review or compare against outline
+   - coursecode_lint — validate after file changes
 
 4. Efficient iteration loop:
    Edit files → lint → fix errors → screenshot to verify visual result
@@ -647,7 +647,7 @@ ${refList ? `\n5. REFERENCE MATERIALS (for verifying content accuracy):\n${refLi
 Run lint and ensure zero errors before moving to export.
 
 ## Next Stage
-Once the course is polished and lint passes, Stage 5 (Export Ready) begins. Call workflow_status for export guidance.`;
+Once the course is polished and lint passes, Stage 5 (Export Ready) begins. Call coursecode_workflow_status for export guidance.`;
         }
 
         case 5: // Export Ready
@@ -660,10 +660,10 @@ Export the finished course for LMS deployment.
    - cmi5 (default) for modern LMS
    - scorm1.2 for legacy systems
 
-The build produces a ZIP file in dist/ ready for LMS upload.`;
+The build produces a dist/ output for deployment. If you need a packaged ZIP for LMS upload, use the CLI packaging commands outside MCP (for example \`coursecode package\`).`;
 
         default:
-            return 'Call workflow_status to determine the current authoring stage.';
+            return 'Call coursecode_workflow_status to determine the current authoring stage.';
     }
 }
 
@@ -693,7 +693,7 @@ 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 run_command (AI agent)
+- 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
 - The headless browser auto-reconnects when Vite rebuilds (file changes)
 
@@ -713,8 +713,8 @@ All runtime tools (state, navigate, interact, screenshot, viewport, reset) execu
 - Efficient loop: edit files → lint → fix errors → screenshot specific slides to verify
 
 ### Customization (all in course/, never in framework/)
-- **CSS overrides**: Edit \`course/theme.css\` — override palette tokens to rebrand (all colors cascade via color-mix). Use framework utility classes first (css_catalog), theme.css only for brand-specific overrides.
-- **Custom components**: Add \`.js\` files to \`course/components/\` — auto-discovered at build time. Use component_catalog for built-in options first.
+- **CSS overrides**: Edit \`course/theme.css\` — override palette tokens to rebrand (all colors cascade via color-mix). Use framework utility classes first (\`coursecode_css_catalog\`), \`theme.css\` only for brand-specific overrides.
+- **Custom components**: Add \`.js\` files to \`course/components/\` — auto-discovered at build time. Use \`coursecode_component_catalog\` for built-in options first.
 - **Custom interactions**: Add \`.js\` files to \`course/interactions/\` — auto-discovered. See \`course/interactions/PLUGIN_GUIDE.md\` for the template.
 - **Custom icons**: Add SVG definitions to \`course/icons.js\` — merged with built-in icons. Use icon_catalog to check existing icons first.`;
 }
@@ -769,7 +769,7 @@ export async function buildInstructions(port = 4173) {
     let automationWarning = '';
     if (checklist.hasCourseConfig && !checklist.hasAutomationEnabled) {
         automationWarning = `\n\n## ⚠️ Automation Disabled
-MCP runtime tools (state, navigate, interact, screenshot, reset) require \`environment.automation.enabled: true\` in course-config.js. Without it, the headless browser cannot access the course API and these tools will fail.
+MCP runtime tools (\`coursecode_state\`, \`coursecode_navigate\`, \`coursecode_interact\`, and \`coursecode_reset\`, plus screenshot/navigation features that rely on course API access) require \`environment.automation.enabled: true\` in course-config.js. Without it, the headless browser cannot access the course API and these tools will fail.
 You MUST notify the author about this and let them decide whether to enable it. Do not silently modify the config.`;
     }
 

package/lib/mcp-server.js

@@ -47,7 +47,7 @@ async function ensureHeadless(port) {
             throw new Error(
                 'Preview server not running. Start it first:\n' +
                 '  • Human: run `coursecode preview` in a terminal\n' +
-                '  • AI agent: use run_command to execute `npm run preview`\n' +
+                '  • AI agent: use your terminal/command execution tool to run `coursecode preview`\n' +
                 'Then retry this tool call.'
             );
         }

package/lib/preview-routes-api.js

@@ -11,7 +11,7 @@ import os from 'os';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { generateContentHtml } from './stub-player/content-generator.js';
 import { parseCourse } from './course-parser.js';
-import { getComponentCatalog, getInteractionCatalog, getIconCatalog, getWorkflowStatus, getRefsStatus } from './authoring-api.js';
+import { getComponentCatalog, getInteractionCatalog, getIconCatalog, getWorkflowStatus, getRefsStatus, buildCourse } from './authoring-api.js';
 import { getAllIcons, getAllSchemas } from './schema-extractor.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -612,6 +612,46 @@ export async function handleApiRoutes(ctx, req, res, url) {
         return true;
     }
 
+    // Preview a converted reference file (for dashboard Stage 2 links)
+    if (url === '/__stub-player/ref-preview') {
+        const params = new URL(req.url, 'http://localhost').searchParams;
+        const fileName = params.get('file');
+        if (!fileName || fileName.includes('..')) {
+            res.writeHead(400, { 'Content-Type': 'text/plain' });
+            res.end('Invalid file parameter');
+            return true;
+        }
+        const filePath = path.join(paths.coursePath, 'references', 'converted', fileName);
+        if (!fs.existsSync(filePath)) {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('File not found');
+            return true;
+        }
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const html = ctx.simpleMarkdownToHtml(raw);
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
+        res.end(`<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${fileName} – Reference Preview</title>
+    <link rel="stylesheet" href="/__stub-player/styles.css">
+    <style>
+        body { padding: 40px; max-width: 900px; margin: 0 auto; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; background: var(--color-primary-deep, #0b1628); color: var(--color-gray-200, #d1d5db); }
+        h1 { font-size: 18px; color: var(--color-white, #fff); border-bottom: 1px solid rgba(255,255,255,0.1); padding-bottom: 8px; margin-bottom: 24px; }
+        pre { background: rgba(0,0,0,0.3); padding: 12px; border-radius: 6px; overflow-x: auto; }
+        code { background: rgba(0,0,0,0.2); padding: 2px 6px; border-radius: 3px; font-size: 13px; }
+    </style>
+</head>
+<body>
+    <h1>${fileName}</h1>
+    ${html}
+</body>
+</html>`);
+        return true;
+    }
+
     // Stub player static files
     if (url.startsWith('/__stub-player/')) {
         const relativePath = url.slice('/__stub-player/'.length);
@@ -639,6 +679,24 @@ export async function handleApiRoutes(ctx, req, res, url) {
         return true;
     }
 
+    // Build course (triggered from dashboard)
+    if (url.startsWith('/__build') && req.method === 'POST') {
+        (async () => {
+            try {
+                const params = new URL(req.url, 'http://localhost').searchParams;
+                const format = params.get('format') || 'cmi5';
+                const result = await buildCourse({ format });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(result));
+            } catch (err) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: err.message }));
+            }
+        })();
+        return true;
+    }
+
+
     // Reset (clear storage + redirect)
     if (url === '/__reset') {
         const resetHtml = `<!DOCTYPE html>