coursecode 0.1.59 → 0.1.61

package/framework/css/components/buttons.css

@@ -166,14 +166,14 @@
 .btn-success,
 .btn-check {
   background: var(--color-success);
-  color: var(--color-white);
+  color: var(--color-on-success);
   border-color: var(--color-success);
 }
 
 .btn-success:hover:not(:disabled),
 .btn-check:hover:not(:disabled) {
   background: var(--color-success-hover);
-  color: var(--color-white);
+  color: var(--color-on-success);
   border-color: var(--color-success-hover);
   box-shadow: var(--shadow-md);
   transform: translateY(var(--btn-hover-translate-y));

package/framework/css/design-tokens.css

@@ -153,6 +153,7 @@
   --color-success-light: color-mix(in srgb, var(--palette-green) 4%, var(--palette-white));
   --color-success-hover: color-mix(in srgb, var(--palette-green) 80%, var(--palette-black));
   --color-success-text: color-mix(in srgb, var(--palette-green) 85%, var(--palette-black));
+  --color-on-success: var(--color-white); /* Text/icon color on success-filled backgrounds */
 
   --color-partial: var(--palette-amber);  /* Partial credit feedback */
 

package/framework/docs/COURSE_AUTHORING_GUIDE.md

@@ -102,6 +102,8 @@ Test your course with a stub LMS wrapper.
 
 Runs Vite build in watch mode + stub LMS server. Changes to source files trigger automatic rebuilds:
 
+> **MCP-first workflow for AI agents:** Start by calling `coursecode_state`. If it connects, reuse that running preview for the entire authoring session. After editing course files, rely on preview hot reload and use `coursecode_errors`, `coursecode_screenshot`, `coursecode_viewport`, and the other CourseCode MCP runtime tools to inspect the result. Do not restart preview or run a production build after routine edits. If `coursecode_state` reports that preview is unavailable, start `coursecode preview` once in a terminal, then return to the MCP tools. Use `coursecode_lint` for static preflight checks and reserve `coursecode_build` for final package verification or export.
+
 ```bash
 coursecode preview                    # Open http://localhost:4173
 ```

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 { getInteractionState, recordInteractionResult } from '../components/interactions/interaction-base.js';
+import { dispatchInteractionChecked, getInteractionState, recordInteractionResult } from '../components/interactions/interaction-base.js';
 import { logger } from '../utilities/logger.js';
 
 /**
@@ -144,6 +144,9 @@ export function createInteractionMethods(logTrace) {
                     }
                 }
 
+                const interactionElement = document.querySelector(`[data-interaction-id="${CSS.escape(interactionId)}"]`);
+                dispatchInteractionChecked(interactionElement, evaluation);
+
                 return evaluation;
             } catch (error) {
                 logTrace('checkAnswer:error', { interactionId, error: error.message });

package/framework/js/components/interactions/hotspot.js

@@ -6,7 +6,6 @@ import {
   clearFeedback,
   validateContainer,
   parseResponse,
-  recordInteractionResult,
   registerCoreInteraction
 } from './interaction-base.js';
 import { logger } from '../../utilities/logger.js';
@@ -330,6 +329,7 @@ export function createHotspotQuestion(config) {
       if (!selections.length) {
         displayFeedback(
           targetContainer,
+          id,
           'Select at least one hotspot before checking your answer.',
           'error'
         );
@@ -341,7 +341,8 @@ export function createHotspotQuestion(config) {
       if (evaluation.correct) {
         displayFeedback(
           targetContainer,
-          '✓ Excellent! You found all the correct areas.',
+          id,
+          feedback?.correct || '✓ Excellent! You found all the correct areas.',
           'correct'
         );
       } else {
@@ -349,21 +350,12 @@ export function createHotspotQuestion(config) {
         const selectedCount = selections.length;
         displayFeedback(
           targetContainer,
-          `✗ Keep trying. ${selectedCount} selected / ${correctCount} required.`,
+          id,
+          feedback?.incorrect || `✗ Keep trying. ${selectedCount} selected / ${correctCount} required.`,
           'incorrect'
         );
       }
 
-      recordInteractionResult(
-        id,
-        'other',
-        evaluation.response,
-        evaluation.correct,
-        JSON.stringify(normalizedHotspots.filter(h => h.correct).map(h => h.id)),
-        prompt,
-        controlled
-      );
-
       return evaluation;
     },
 

package/framework/js/components/interactions/interaction-base.js

@@ -195,6 +195,8 @@ export function createInteractionEventHandler(questionObj, config, customHandler
                 if (!config.controlled) {
                     recordInteractionResult(config, evaluation);
                 }
+
+                dispatchInteractionChecked(event.currentTarget, evaluation);
                 break;
 
             case 'reset':
@@ -231,7 +233,11 @@ export function createInteractionEventHandler(questionObj, config, customHandler
  */
 export function recordInteractionResult(config, evaluation) {
     // Mark as submitted in state (for restoration purposes)
-    saveInteractionState(config.id, evaluation.response, true);
+    saveInteractionState(
+        config.id,
+        normalizeInteractionResponseForPersistence(config.scormType, evaluation.response),
+        true
+    );
 
     // Format the response according to SCORM 2004 requirements
     const scormType = config.scormType || 'other';
@@ -266,6 +272,43 @@ export function recordInteractionResult(config, evaluation) {
     }
 }
 
+/**
+ * Converts structured interaction responses back from their evaluation/SCORM
+ * JSON representation before storing them for UI restoration.
+ */
+export function normalizeInteractionResponseForPersistence(scormType, response) {
+    if (typeof response !== 'string' || !['choice', 'matching', 'sequencing', 'other'].includes(scormType)) {
+        return response;
+    }
+
+    const trimmed = response.trim();
+    if (!trimmed.startsWith('[') && !trimmed.startsWith('{')) {
+        return response;
+    }
+
+    try {
+        return JSON.parse(trimmed);
+    } catch {
+        return response;
+    }
+}
+
+/**
+ * Emits the documented interaction completion event from a rendered
+ * interaction or its author-provided container.
+ */
+export function dispatchInteractionChecked(target, evaluation) {
+    if (!target || !evaluation) return;
+
+    target.dispatchEvent(new CustomEvent('interaction-checked', {
+        bubbles: true,
+        detail: {
+            isCorrect: evaluation.correct,
+            evaluation
+        }
+    }));
+}
+
 /**
  * Creates standard interaction controls HTML.
  * Uses utility classes for layout: .flex .flex-wrap .justify-center .gap-3
@@ -430,14 +473,34 @@ const _responseDebounceTimers = new Map();
  * @param {object} questionObj - The live interaction instance.
  */
 export function registerCoreInteraction(config, questionObj) {
+    const scormTypeByInteractionType = {
+        'multiple-choice-single': 'choice',
+        'multiple-choice-multiple': 'choice',
+        'drag-drop': 'other',
+        'fill-in': 'fill-in',
+        'hotspot': 'other',
+        'likert': 'likert',
+        'matching': 'matching',
+        'numeric': 'numeric',
+        'sequencing': 'sequencing',
+        'true-false': 'true-false'
+    };
+    const registryConfig = config.scormType
+        ? config
+        : { ...config, scormType: scormTypeByInteractionType[questionObj.type] || 'other' };
+
     // Delegate to the InteractionRegistry (separate from persistence manager)
-    interactionRegistry.register(config, questionObj);
+    interactionRegistry.register(registryConfig, questionObj);
+
+    // Snapshot restoration state before deferring DOM work. An automated check can
+    // run before the next animation frame; reading state inside the callback would
+    // then mistake that new answer for pre-existing state and restore it twice.
+    const savedState = getInteractionState(config.id);
 
     // Defer state restoration and auto-save setup to next frame
     // This ensures the DOM container exists after render() completes
     requestAnimationFrame(() => {
         // Restore previously saved response state if it exists
-        const savedState = getInteractionState(config.id);
         if (savedState && savedState.response !== null && savedState.response !== undefined) {
             try {
                 if (typeof questionObj.setResponse === 'function') {
@@ -446,7 +509,9 @@ export function registerCoreInteraction(config, questionObj) {
 
                     // If it was previously submitted, also restore the feedback state
                     if (savedState.submitted && typeof questionObj.checkAnswer === 'function') {
-                        questionObj.checkAnswer();
+                        const evaluation = questionObj.checkAnswer();
+                        const interactionElement = document.querySelector(`[data-interaction-id="${CSS.escape(config.id)}"]`);
+                        dispatchInteractionChecked(interactionElement, evaluation);
                     }
                 }
             } catch (error) {

package/framework/js/components/ui-components/interactive-image.js

@@ -7,8 +7,8 @@
 export const schema = {
     type: 'interactive-image',
     description: 'Image with clickable hotspots for modals or accordion integration',
-    example: `<div data-component="interactive-image" class="interactive-image" style="position: relative; display: inline-block;">
-  <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='250' fill='%23f1f5f9'%3E%3Crect width='400' height='250' rx='8'/%3E%3Ctext x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' fill='%2394a3b8' font-family='system-ui' font-size='14'%3EInteractive Diagram%3C/text%3E%3C/svg%3E" alt="Interactive diagram">
+    example: `<div data-component="interactive-image" class="interactive-image-container">
+  <img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='250' fill='%23f1f5f9'%3E%3Crect width='400' height='250' rx='8'/%3E%3Ctext x='50%25' y='50%25' dominant-baseline='middle' text-anchor='middle' fill='%2394a3b8' font-family='system-ui' font-size='14'%3EInteractive Diagram%3C/text%3E%3C/svg%3E" alt="Interactive diagram" class="interactive-image-img">
   <button data-hotspot-id="feature-a" data-title="Feature A" data-body="Details about Feature A" class="hotspot" style="position: absolute; top: 30%; left: 25%; width: 24px; height: 24px; border-radius: 50%; background: #3b82f6; border: 2px solid white; cursor: pointer;" aria-label="Feature A"></button>
   <button data-hotspot-id="feature-b" data-title="Feature B" data-body="Details about Feature B" class="hotspot" style="position: absolute; top: 60%; left: 65%; width: 24px; height: 24px; border-radius: 50%; background: #f59e0b; border: 2px solid white; cursor: pointer;" aria-label="Feature B"></button>
 </div>`,
@@ -45,6 +45,12 @@ export function init(root, _options = {}) {
     const container = typeof root === 'string' ? document.querySelector(root) : root;
     if (!container) return;
 
+    // The data-component attribute is the author-facing contract. Normalize
+    // the internal CSS hooks so documented minimal markup positions hotspots
+    // against the image instead of an unrelated ancestor.
+    container.classList.add('interactive-image-container');
+    container.querySelector(':scope > img')?.classList.add('interactive-image-img');
+
     const hotspots = Array.from(container.querySelectorAll('[data-hotspot-id]'));
     if (!hotspots.length) return;
 

package/framework/js/dev/runtime-linter.js

@@ -781,6 +781,28 @@ function getEffectiveBackgroundColor(element) {
     return [result[0], result[1], result[2]];
 }
 
+/**
+ * Detects computed gradient backgrounds on an element or any ancestor.
+ * Course themes commonly use custom classes, so class-name allowlists cannot
+ * reliably identify every gradient that makes flat-color contrast calculation
+ * invalid.
+ * @param {HTMLElement} element
+ * @returns {boolean}
+ */
+function hasComputedGradientBackground(element) {
+    let current = element;
+
+    while (current && current.tagName !== 'HTML') {
+        const backgroundImage = window.getComputedStyle(current).backgroundImage;
+        if (backgroundImage && backgroundImage !== 'none' && backgroundImage.includes('gradient')) {
+            return true;
+        }
+        current = current.parentElement;
+    }
+
+    return false;
+}
+
 
 /**
  * Builds a compact description of an element and its ancestry for lint messages.
@@ -873,18 +895,7 @@ function validateVisualLayout(slideId, renderedContent, errors, warnings) {
             if (el.classList.contains('badge') || el.closest('.badge') !== null) continue;
 
             // Skip contrast check for elements on gradient backgrounds (can't reliably compute)
-            const hasGradientBackground = el.closest('.gradient') !== null ||
-                el.closest('.gradient-light') !== null ||
-                el.closest('.hero-gradient') !== null ||
-                el.closest('.btn-gradient') !== null ||
-                el.closest('[class*="bg-gradient-dark"]') !== null ||
-                el.closest('[class*="gradient-header"]') !== null ||
-                el.closest('[class*="gradient-success"]') !== null ||
-                el.closest('[class*="gradient-progress"]') !== null ||
-                el.closest('[style*="linear-gradient"]') !== null ||
-                el.closest('[style*="radial-gradient"]') !== null ||
-                style.backgroundImage.includes('gradient');
-            if (hasGradientBackground) continue;
+            if (hasComputedGradientBackground(el)) continue;
 
             const textColorStr = style.color;
             const bgColorRgb = getEffectiveBackgroundColor(el);

package/framework/version.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.1.59",
+  "version": "0.1.61",
   "name": "CourseCode Framework",
   "description": "Multi-format course authoring and learner runtime framework",
-  "released": "2026-07-13",
+  "released": "2026-07-20",
   "formats": [
     "SCORM 2004 4th Edition",
     "SCORM 1.2",

package/lib/headless-browser.js

@@ -410,7 +410,8 @@ class HeadlessBrowser {
         if (scrollY !== undefined && scrollY > 0) {
             await this._ensureCourseFrame();
             await this.courseFrame.evaluate((y) => {
-                const container = document.querySelector('.slide-content')
+                const container = document.querySelector('#content')
+                    || document.querySelector('.slide-content')
                     || document.querySelector('[class*="slide"]')
                     || document.documentElement;
                 container.scrollTop = y;
@@ -425,17 +426,21 @@ class HeadlessBrowser {
             // temporarily expand the viewport so nothing is clipped, then screenshot.
             await this._ensureCourseFrame();
             const contentHeight = await this.courseFrame.evaluate(() => {
+                const content = document.querySelector('#content');
                 return Math.max(
+                    content?.scrollHeight || 0,
                     document.body.scrollHeight,
                     document.documentElement.scrollHeight
                 );
             });
 
-            const fullHeight = Math.max(contentHeight, this._viewport.height);
+            const iframeElement = await this.page.$('iframe');
+            const iframeBox = await iframeElement?.boundingBox();
+            const playerChromeHeight = Math.max(0, this._viewport.height - (iframeBox?.height || this._viewport.height));
+            const fullHeight = Math.max(contentHeight + playerChromeHeight, this._viewport.height);
             await this.page.setViewport({ width: this._viewport.width, height: fullHeight });
             await new Promise(resolve => setTimeout(resolve, 200));
 
-            const iframeElement = await this.page.$('iframe');
             if (iframeElement) {
                 screenshotBuffer = await iframeElement.screenshot({
                     type: 'jpeg',
@@ -459,7 +464,9 @@ class HeadlessBrowser {
         }
 
         return {
-            data: screenshotBuffer.toString('base64'),
+            // Puppeteer >=22 returns Uint8Array, whose toString() ignores the
+            // 'base64' argument — wrap in Buffer so encoding applies.
+            data: Buffer.from(screenshotBuffer).toString('base64'),
             mimeType: 'image/jpeg'
         };
     }

package/lib/info.js

@@ -9,6 +9,18 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.join(__dirname, '..');
 
+export function findLatestCoursePackage(directory) {
+  const packages = fs.readdirSync(directory, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith('.zip'))
+    .map(entry => ({
+      name: entry.name,
+      modifiedAt: fs.statSync(path.join(directory, entry.name)).mtimeMs
+    }))
+    .sort((a, b) => b.modifiedAt - a.modifiedAt || a.name.localeCompare(b.name));
+
+  return packages[0]?.name || null;
+}
+
 export async function info() {
   const cwd = process.cwd();
 
@@ -70,9 +82,9 @@ export async function info() {
   }
 
   // Check for ZIP
-  const zipFiles = fs.readdirSync(cwd).filter(f => f.endsWith('.zip'));
-  if (zipFiles.length > 0) {
-    console.log(`   Course package: ${zipFiles[zipFiles.length - 1]}`);
+  const latestPackage = findLatestCoursePackage(cwd);
+  if (latestPackage) {
+    console.log(`   Course package: ${latestPackage}`);
   }
 
   console.log('');

package/lib/upgrade.js

@@ -113,6 +113,39 @@ export function addMissingRuntimeDependencies(projectPkg, templatePkg) {
   return added;
 }
 
+/**
+ * Keep the project-local authoring/build CLI aligned with the framework that
+ * was just installed. Generated projects rely on this dependency so an
+ * isolated checkout can run CourseCode commands without a global install.
+ */
+export function syncCoursecodeCliDependency(projectPkg, targetVersion) {
+  const targetRange = `^${targetVersion}`;
+  const currentDevRange = projectPkg.devDependencies?.coursecode;
+  const currentRuntimeRange = projectPkg.dependencies?.coursecode;
+  const updated = currentDevRange !== targetRange || Boolean(currentRuntimeRange);
+
+  if (!updated) {
+    return { updated: false, from: currentDevRange, to: targetRange };
+  }
+
+  projectPkg.devDependencies = Object.fromEntries(
+    Object.entries({
+      ...(projectPkg.devDependencies || {}),
+      coursecode: targetRange
+    }).sort(([a], [b]) => a.localeCompare(b))
+  );
+
+  if (currentRuntimeRange) {
+    delete projectPkg.dependencies.coursecode;
+  }
+
+  return {
+    updated: true,
+    from: currentDevRange || currentRuntimeRange || null,
+    to: targetRange
+  };
+}
+
 const OBSOLETE_MANAGED_DEV_DEPENDENCIES = ['@vitejs/plugin-legacy'];
 
 /**
@@ -209,7 +242,7 @@ export async function upgrade(options = {}) {
    - framework/     (replace entirely)
    - schemas/       (replace entirely)
    - lib/manifest/  (replace entirely)
-   - package.json   (add missing runtime dependencies)
+   - package.json   (sync CourseCode CLI and add missing runtime dependencies)
    - .coursecoderc.json  (update version)`;
 
     if (options.configs) {
@@ -307,14 +340,17 @@ export async function upgrade(options = {}) {
   // the project's existing version ranges.
   const pkgPath = path.join(cwd, 'package.json');
   let addedRuntimeDeps = [];
+  let cliDependencyChange = null;
   let toolingChanges = null;
   if (fs.existsSync(pkgPath)) {
     const projectPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     addedRuntimeDeps = addMissingRuntimeDependencies(projectPkg, templatePkg);
+    cliDependencyChange = syncCoursecodeCliDependency(projectPkg, targetVersion);
     if (options.configs) {
       toolingChanges = syncManagedBuildTooling(projectPkg, templatePkg);
     }
-    const packageChanged = addedRuntimeDeps.length > 0 ||
+    const packageChanged = cliDependencyChange.updated ||
+      addedRuntimeDeps.length > 0 ||
       toolingChanges?.updated.length > 0 ||
       toolingChanges?.removed.length > 0 ||
       toolingChanges?.engineUpdated;
@@ -330,13 +366,19 @@ export async function upgrade(options = {}) {
 
    Your course/ directory was not modified.`;
 
+  if (cliDependencyChange?.updated) {
+    const previousRange = cliDependencyChange.from || 'missing';
+    successMsg += `
+
+   CourseCode CLI dependency updated:
+   - coursecode: ${previousRange} → ${cliDependencyChange.to}`;
+  }
+
   if (addedRuntimeDeps.length > 0) {
     successMsg += `
 
    Runtime dependencies added to package.json:
-   - ${addedRuntimeDeps.join('\n   - ')}
-
-   Run npm install to update node_modules and your lockfile.`;
+   - ${addedRuntimeDeps.join('\n   - ')}`;
   }
 
   if (toolingChanges && (
@@ -359,9 +401,6 @@ export async function upgrade(options = {}) {
       successMsg += `
    - Updated Node engine requirement to ${templatePkg.engines.node}`;
     }
-    successMsg += `
-
-   Run npm install to update node_modules and your lockfile.`;
   }
 
   if (configUpdates.length > 0) {
@@ -373,6 +412,18 @@ ${configUpdates.join('\n')}
    Review the changes and delete .backup files when satisfied.`;
   }
 
+  if (
+    cliDependencyChange?.updated ||
+    addedRuntimeDeps.length > 0 ||
+    toolingChanges?.updated.length > 0 ||
+    toolingChanges?.removed.length > 0 ||
+    toolingChanges?.engineUpdated
+  ) {
+    successMsg += `
+
+   Run npm install to update node_modules and your lockfile.`;
+  }
+
   successMsg += `
    
    Review the changelog for breaking changes:

package/package.json

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