npm - coursecode - Versions diffs - 0.1.58 → 0.1.60 - Mend

coursecode 0.1.58 → 0.1.60

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/framework/css/components/accordions.css +117 -31
package/framework/css/components/buttons.css +2 -2
package/framework/css/design-tokens.css +1 -0
package/framework/css/layouts/article.css +7 -0
package/framework/docs/COURSE_AUTHORING_GUIDE.md +6 -2
package/framework/js/automation/api-interactions.js +4 -1
package/framework/js/components/interactions/drag-drop.js +4 -4
package/framework/js/components/interactions/fill-in.js +7 -4
package/framework/js/components/interactions/hotspot.js +7 -15
package/framework/js/components/interactions/interaction-base.js +69 -4
package/framework/js/components/interactions/matching.js +4 -3
package/framework/js/components/ui-components/interactive-image.js +8 -2
package/framework/js/dev/runtime-linter.js +29 -14
package/framework/js/utilities/portable-assets.js +20 -0
package/framework/version.json +2 -2
package/lib/build-linter.js +192 -2
package/lib/build.js +68 -7
package/lib/headless-browser.js +8 -3
package/lib/info.js +15 -3
package/lib/upgrade.js +59 -8
package/package.json +1 -1
package/template/course/slides/example-ui-showcase.js +1 -1

package/framework/css/components/accordions.css CHANGED Viewed

@@ -247,8 +247,10 @@
    ACCORDION STYLE VARIANTS
    ============================================================================
-   Apply these data attributes to the .accordion container to change
-   the visual appearance.
+   Global theme tokens are bridged to data attributes on <html>. Authors may
+   override that default on an individual .accordion. Keep every variant rule
+   scoped through the accordion container so a local attribute wins over an
+   inherited global attribute.
    USAGE:
    <div class="accordion" data-accordion-style="flush">
@@ -260,33 +262,51 @@
 /* --------------------------------------
    Flush Style - No outer border, dividers only
    -------------------------------------- */
-[data-accordion-style="flush"].accordion {
+:is(
+  [data-accordion-style="flush"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="flush"]
+) {
   border: none;
   border-radius: 0;
   box-shadow: none;
   background: transparent;
 }
-[data-accordion-style="flush"] .accordion-item {
+:is(
+  [data-accordion-style="flush"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="flush"]
+) .accordion-item {
   background: transparent;
   border-bottom: 1px solid var(--color-gray-200);
 }
-[data-accordion-style="flush"] .accordion-item:last-child {
+:is(
+  [data-accordion-style="flush"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="flush"]
+) .accordion-item:last-child {
   border-bottom: 1px solid var(--color-gray-200);
 }
-[data-accordion-style="flush"] .accordion-button {
+:is(
+  [data-accordion-style="flush"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="flush"]
+) .accordion-button {
   padding-left: 0;
   padding-right: 0;
 }
-[data-accordion-style="flush"] .accordion-body {
+:is(
+  [data-accordion-style="flush"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="flush"]
+) .accordion-body {
   padding-left: 0;
   padding-right: 0;
 }
-[data-accordion-style="flush"] .accordion-content {
+:is(
+  [data-accordion-style="flush"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="flush"]
+) .accordion-content {
   background: transparent;
 }
@@ -295,7 +315,10 @@
 /* --------------------------------------
    Separated Style - Gap between items
    -------------------------------------- */
-[data-accordion-style="separated"].accordion {
+:is(
+  [data-accordion-style="separated"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="separated"]
+) {
   border: none;
   border-radius: 0;
   box-shadow: none;
@@ -305,18 +328,27 @@
   gap: var(--space-3);
 }
-[data-accordion-style="separated"] .accordion-item {
+:is(
+  [data-accordion-style="separated"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="separated"]
+) .accordion-item {
   border: 1px solid var(--color-gray-200);
   border-radius: var(--radius-lg);
   overflow: hidden;
   box-shadow: var(--shadow-sm);
 }
-[data-accordion-style="separated"] .accordion-item:last-child {
+:is(
+  [data-accordion-style="separated"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="separated"]
+) .accordion-item:last-child {
   border-bottom: 1px solid var(--color-gray-200);
 }
-[data-accordion-style="separated"] .accordion-button:not(.collapsed) {
+:is(
+  [data-accordion-style="separated"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="separated"]
+) .accordion-button:not(.collapsed) {
   border-bottom: none;
   border-radius: var(--radius-lg) var(--radius-lg) 0 0;
 }
@@ -326,56 +358,86 @@
 /* --------------------------------------
    Minimal Style - No borders, subtle hover
    -------------------------------------- */
-[data-accordion-style="minimal"].accordion {
+:is(
+  [data-accordion-style="minimal"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="minimal"]
+) {
   border: none;
   border-radius: 0;
   box-shadow: none;
   background: transparent;
 }
-[data-accordion-style="minimal"] .accordion-item {
+:is(
+  [data-accordion-style="minimal"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="minimal"]
+) .accordion-item {
   background: transparent;
   border-bottom: none;
 }
-[data-accordion-style="minimal"] .accordion-button {
+:is(
+  [data-accordion-style="minimal"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="minimal"]
+) .accordion-button {
   padding: var(--space-3) var(--space-4);
   border-radius: var(--radius-md);
 }
-[data-accordion-style="minimal"] .accordion-button:hover {
+:is(
+  [data-accordion-style="minimal"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="minimal"]
+) .accordion-button:hover {
   background: var(--bg-muted);
 }
-[data-accordion-style="minimal"] .accordion-button:not(.collapsed) {
+:is(
+  [data-accordion-style="minimal"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="minimal"]
+) .accordion-button:not(.collapsed) {
   background: var(--color-primary-alpha-05);
   border-bottom: none;
 }
-[data-accordion-style="minimal"] .accordion-content {
+:is(
+  [data-accordion-style="minimal"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="minimal"]
+) .accordion-content {
   background: transparent;
 }
-[data-accordion-style="minimal"] .accordion-body {
+:is(
+  [data-accordion-style="minimal"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="minimal"]
+) .accordion-body {
   padding: var(--space-2) var(--space-4) var(--space-4);
 }
 /* Dark mode for minimal */
-[data-theme="dark"] [data-accordion-style="minimal"] .accordion-button:not(.collapsed) {
+:is(
+  [data-theme="dark"][data-accordion-style="minimal"] .accordion:not([data-accordion-style]),
+  [data-theme="dark"] .accordion[data-accordion-style="minimal"]
+) .accordion-button:not(.collapsed) {
   background: var(--color-primary-alpha-20);
 }
 /* --------------------------------------
    Boxed Style - Each item is a bordered box
    -------------------------------------- */
-[data-accordion-style="boxed"].accordion {
+:is(
+  [data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="boxed"]
+) {
   border: none;
   border-radius: 0;
   box-shadow: none;
   background: transparent;
 }
-[data-accordion-style="boxed"] .accordion-item {
+:is(
+  [data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="boxed"]
+) .accordion-item {
   border: 2px solid var(--color-gray-200);
   border-radius: var(--radius-lg);
   margin-bottom: var(--space-3);
@@ -383,38 +445,62 @@
   background: var(--bg-surface);
 }
-[data-accordion-style="boxed"] .accordion-item:last-child {
+:is(
+  [data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="boxed"]
+) .accordion-item:last-child {
   margin-bottom: 0;
 }
-[data-accordion-style="boxed"] .accordion-button {
+:is(
+  [data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="boxed"]
+) .accordion-button {
   background: var(--bg-subtle);
 }
-[data-accordion-style="boxed"] .accordion-button:hover {
+:is(
+  [data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="boxed"]
+) .accordion-button:hover {
   background: var(--bg-muted);
 }
-[data-accordion-style="boxed"] .accordion-button:not(.collapsed) {
+:is(
+  [data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="boxed"]
+) .accordion-button:not(.collapsed) {
   background: var(--color-primary);
   color: var(--color-white);
   border-bottom: none;
 }
-[data-accordion-style="boxed"] .accordion-button:not(.collapsed) .accordion-icon {
+:is(
+  [data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="boxed"]
+) .accordion-button:not(.collapsed) .accordion-icon {
   color: var(--color-white);
 }
-[data-accordion-style="boxed"] .accordion-content {
+:is(
+  [data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  .accordion[data-accordion-style="boxed"]
+) .accordion-content {
   border-top: 2px solid var(--color-gray-200);
 }
 /* Dark mode for boxed */
-[data-theme="dark"] [data-accordion-style="boxed"] .accordion-item {
+:is(
+  [data-theme="dark"][data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  [data-theme="dark"] .accordion[data-accordion-style="boxed"]
+) .accordion-item {
   border-color: var(--border-default);
 }
-[data-theme="dark"] [data-accordion-style="boxed"] .accordion-content {
+:is(
+  [data-theme="dark"][data-accordion-style="boxed"] .accordion:not([data-accordion-style]),
+  [data-theme="dark"] .accordion[data-accordion-style="boxed"]
+) .accordion-content {
   border-top-color: var(--border-default);
 }
@@ -707,4 +793,4 @@
 [data-theme="dark"] .accordion-badge-outline {
   border-color: rgba(var(--color-primary-rgb), 0.4);
   color: var(--color-primary-light);
-}
+}

package/framework/css/components/buttons.css CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/css/layouts/article.css CHANGED Viewed

@@ -101,6 +101,13 @@
     margin: 0 auto;
 }
+/* Breadcrumbs are positioned absolutely and do not reserve layout space.
+   Add clearance only while they are visible; mobile hides them entirely. */
+html:not(.bp-max-mobile-landscape)[data-layout="article"]
+    .breadcrumbs:not(.hidden):not([hidden]) ~ #slide-container {
+    padding-top: var(--space-4);
+}
 /* Footer styling moved to components/footer.css - DATA-LAYOUT VARIANTS section */
 /* Audio player styling moved to components/audio-player.css - DATA-LAYOUT VARIANTS section */

package/framework/docs/COURSE_AUTHORING_GUIDE.md CHANGED Viewed

@@ -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
 ```
@@ -618,7 +620,7 @@ createNumericQuestion({
 ```javascript
 createHotspotQuestion({
   id: 'hot1', prompt: 'Click the correct region:',
-  image: { src: 'assets/images/diagram.png', alt: 'Diagram' },
+  image: { src: 'assets/images/diagram.png', alt: 'Diagram' }, // Relative to course/assets/
   hotspots: [
     // pos = [x%, y%, width%, height%]
     { id: 'zone1', pos: [10, 20, 15, 10], correct: true, label: 'Correct Zone', feedback: 'Good choice!' },
@@ -627,6 +629,8 @@ createHotspotQuestion({
 });
 ```
+Interaction APIs such as `createHotspotQuestion()` resolve relative asset paths against `course/assets/`. In direct HTML attributes such as `<img src>`, use the packaged path `course/assets/...` as shown in the interactive-image example below. Declarative components may document their own path base; for example, lightbox `href` values are relative to `course/` and normally begin with `assets/`.
 **Appearance themes**: `'correct'`, `'incorrect'`, `'primary'`, `'accent'` — or provide custom `appearance` object.
 ### Sequencing
@@ -1477,7 +1481,7 @@ parent.postMessage({ type: 'coursecode:resize', height: 400 }, '*');
 ```html
 <div data-component="interactive-image" id="diagram">
-  <img src="assets/images/diagram.png" alt="Diagram" />
+  <img src="course/assets/images/diagram.png" alt="Diagram" />
   <button data-hotspot-id="zone1" data-title="Component A" data-body="Description here..."
           class="interactive-image-hotspot" style="top: 20%; left: 30%;">A</button>
   <button data-hotspot-id="zone2" data-title="Component B" data-body="More details..."

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

@@ -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/drag-drop.js CHANGED Viewed

@@ -77,8 +77,7 @@ export const schema = {
             description: 'Draggable items',
             itemSchema: {
                 id: { type: 'string', required: true },
-                text: { type: 'string', required: true },
-                correctZone: { type: 'string', required: true }
+                content: { type: 'string', required: true }
             }
         },
         dropZones: {
@@ -88,7 +87,9 @@ export const schema = {
             description: 'Drop target zones',
             itemSchema: {
                 id: { type: 'string', required: true },
-                label: { type: 'string', required: true }
+                label: { type: 'string', required: true },
+                accepts: { type: 'array', required: true, minItems: 1 },
+                maxItems: { type: 'number' }
             }
         }
     }
@@ -881,4 +882,3 @@ function removeItemFromZone(container, itemId) {
     // Update state
     delete state.placements[itemId];
 }

package/framework/js/components/interactions/fill-in.js CHANGED Viewed

@@ -137,10 +137,13 @@ export const schema = {
             type: 'object',
             required: true,
             description: 'Map of blank IDs to their correct answers',
-            valueSchema: {
-                correct: { type: ['string', 'array'], required: true },
-                typoTolerance: { type: 'number', default: 0 },
-                hint: { type: 'string' }
+            mapValueSchema: {
+                type: 'object',
+                valueSchema: {
+                    correct: { type: ['string', 'array'], required: true },
+                    typoTolerance: { type: 'number', default: 0 },
+                    hint: { type: 'string' }
+                }
             }
         },
         template: {

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

@@ -6,10 +6,10 @@ import {
   clearFeedback,
   validateContainer,
   parseResponse,
-  recordInteractionResult,
   registerCoreInteraction
 } from './interaction-base.js';
 import { logger } from '../../utilities/logger.js';
+import { resolveCourseAssetUrl } from '../../utilities/portable-assets.js';
 // Default appearance themes for hotspots
 const HOTSPOT_DEFAULTS = {
@@ -282,7 +282,7 @@ export function createHotspotQuestion(config) {
           <div class="hotspot-container">
             <div class="image-container relative">
               <img
-                src="${image.src}"
+                src="${resolveCourseAssetUrl(image.src)}"
                 alt="${image.alt || ''}"
                 class="w-full h-auto"
                 id="${id}_image"
@@ -329,6 +329,7 @@ export function createHotspotQuestion(config) {
       if (!selections.length) {
         displayFeedback(
           targetContainer,
+          id,
           'Select at least one hotspot before checking your answer.',
           'error'
         );
@@ -340,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 {
@@ -348,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;
     },
@@ -699,4 +692,3 @@ function toNumber(value, fallback = 0) {
   }
   return 0;
 }

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

@@ -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/interactions/matching.js CHANGED Viewed

@@ -94,10 +94,11 @@ export const schema = {
             type: 'array',
             required: true,
             minItems: 2,
-            description: 'Source-target pairs to match',
+            description: 'Items and their matching target text',
             itemSchema: {
-                source: { type: 'string', required: true },
-                target: { type: 'string', required: true }
+                id: { type: 'string', required: true },
+                text: { type: 'string', required: true },
+                match: { type: 'string', required: true }
             }
         },
         feedbackMode: {

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

@@ -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 CHANGED Viewed

@@ -42,7 +42,7 @@ const DYNAMIC_CLASSES = new Set([
     // Component-internal classes — styled via [data-component] selectors in individual component CSS files
     'intro-card', 'card-icon',
     // Interaction-internal classes — used by interaction JS for DOM structure
-    'drag-drop', 'matching-items', 'matching-targets',
+    'drag-drop', 'matching-items', 'matching-targets', 'image-container', 'hotspot-feedback',
     // Slide-specific JS selectors — queried by slide scripts for event binding
     'resources', 'complete-remedial-btn',
 ]);
@@ -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.
@@ -833,6 +855,7 @@ function validateVisualLayout(slideId, renderedContent, errors, warnings) {
         const textElements = renderedContent.querySelectorAll('p, span:not(.accordion-icon), li, a, h1, h2, h3, h4, h5, h6, button');
         for (const el of textElements) {
             if (isLintIgnored(el, 'contrast')) continue;
+            if (el.classList.contains('sr-only') || el.closest('.sr-only')) continue;
             // Skip elements that are not visible or have no text
             if (el.offsetParent === null || el.textContent.trim() === '') continue;
@@ -872,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);
@@ -1042,7 +1054,8 @@ function validateTextProximityToVisualElements(slideId, renderedContent, warning
         'dropdown', 'dropdown-menu', 'dropdown-item',
         'table',  // Tables manage their own cell spacing
         'step-number', 'step-content', 'step',  // Pattern-steps elements have intentional circular styling
-        'btn-link'  // Link-styled button intentionally has minimal padding
+        'btn-link',  // Link-styled button intentionally has minimal padding
+        'hotspot-area', 'interactive-image-hotspot'
     ]);
     // HTML elements that manage their own spacing (exclude from checks)
@@ -1171,6 +1184,8 @@ function validateElementOverlap(slideId, renderedContent, warnings) {
     const absoluteElements = renderedContent.querySelectorAll('[style*="position:absolute"], [style*="position: absolute"]');
     for (const el of absoluteElements) {
         if (el.offsetParent === null) continue;
+        // Hotspots intentionally overlap their background image and sometimes each other.
+        if (el.matches('[data-hotspot-id], .hotspot-area, .interactive-image-hotspot')) continue;
         const rect = el.getBoundingClientRect();
         const elText = el.textContent.trim().substring(0, 30);

package/framework/js/utilities/portable-assets.js CHANGED Viewed

@@ -72,6 +72,26 @@ export function resolvePortableAssetUrl(value) {
     return value;
 }
+/**
+ * Resolve an author-facing course asset path for both normal and portable builds.
+ * Component APIs may use paths relative to course/assets (for example,
+ * "images/diagram.svg") or the legacy "assets/..." form documented by older
+ * CourseCode releases. Direct HTML should use "course/assets/...".
+ * @param {string} value
+ * @returns {string}
+ */
+export function resolveCourseAssetUrl(value) {
+    if (typeof value !== 'string' || value.length === 0) return value;
+    const portableValue = resolvePortableAssetUrl(value);
+    if (portableValue !== value) return portableValue;
+    if (/^(?:data:|blob:|https?:|mailto:|tel:|#|\/\/)/i.test(value)) return value;
+    if (value.startsWith('/') || value.startsWith('./') || value.startsWith('../')) return value;
+    if (value.startsWith('course/assets/')) return `./${value}`;
+    if (value.startsWith('assets/')) return `./course/${value}`;
+    return `./course/assets/${value}`;
+}
 /**
  * Rewrite URL-bearing attributes in freshly rendered slide DOM before
  * declarative components initialize and begin loading media.

package/framework/version.json CHANGED Viewed

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

package/lib/build-linter.js CHANGED Viewed

@@ -12,7 +12,7 @@
 import fs from 'fs';
 import path from 'path';
 import { parseSlideSource, extractAssessment } from './course-parser.js';
-import { getEngagementTrackingMap, getRegisteredComponentTypes } from './schema-extractor.js';
+import { getAllIcons, getEngagementTrackingMap, getRegisteredComponentTypes } from './schema-extractor.js';
 import { getValidCssClasses, lintCssSelectors } from './css-index.js';
 import {
   parseSlideNarration,
@@ -51,7 +51,7 @@ const DYNAMIC_CLASSES = new Set([
   // Component-internal classes — styled via [data-component] selectors in individual component CSS files
   'intro-card', 'card-icon',
   // Interaction-internal classes — used by interaction JS for DOM structure
-  'drag-drop', 'matching-items', 'matching-targets',
+  'drag-drop', 'matching-items', 'matching-targets', 'image-container', 'hotspot-feedback',
   // Slide-specific JS selectors — queried by slide scripts for event binding
   'resources', 'complete-remedial-btn',
 ]);
@@ -93,6 +93,7 @@ export async function lintCourse(courseConfig, coursePath) {
     slideFilesOnDisk
   );
   warnings.push(...globalWarnings);
+  validateMenuIcons(courseConfig, coursePath, warnings);
   // Build valid CSS class index once for all slides
   const validCssIndex = getValidCssClasses();
@@ -219,8 +220,12 @@ async function validateSlide(slide, coursePath, objectiveIds, errors, warnings,
     if (interaction.id) {
       registerInteractionId(interaction.id, slide.id, 'DOM Interaction', interactionIdRegistry, errors);
     }
+    validateInteractionSchema(slide.id, interaction, errors);
+    validateInteractionAssetReferences(slide.id, interaction, coursePath, errors);
   }
+  validateDirectAssetReferences(slide.id, slideData.elements || [], coursePath, errors);
   // Static CSS class validation — checks class attributes in source template
   validateCssClassesStatic(slide.id, source, validCssIndex, warnings);
@@ -244,6 +249,191 @@ function validateRequirementContent(slideId, requirement, slideData, engagementT
   }
 }
+function schemaTypeMatches(value, expectedType) {
+  if (Array.isArray(expectedType)) {
+    return expectedType.some(type => schemaTypeMatches(value, type));
+  }
+  if (expectedType === 'array') return Array.isArray(value);
+  if (expectedType === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (expectedType === 'number') return typeof value === 'number' && Number.isFinite(value);
+  return typeof value === expectedType;
+}
+function validateSchemaValue(reference, value, definition, errors, enforceRequiredChildren = true) {
+  if (!definition || value === undefined) return;
+  if (definition.type && !schemaTypeMatches(value, definition.type)) {
+    const actualType = Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value;
+    const expectedType = Array.isArray(definition.type) ? definition.type.join(' or ') : definition.type;
+    errors.push(`${reference} must be ${expectedType}, got ${actualType}.`);
+    return;
+  }
+  if (definition.enum && !definition.enum.includes(value)) {
+    errors.push(`${reference} must be one of: ${definition.enum.join(', ')}.`);
+  }
+  if (Array.isArray(value)) {
+    if (definition.minItems != null && value.length < definition.minItems) {
+      errors.push(`${reference} must contain at least ${definition.minItems} item(s).`);
+    }
+    if (definition.itemSchema) {
+      value.forEach((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) return;
+        for (const [key, childDefinition] of Object.entries(definition.itemSchema)) {
+          if (childDefinition.required && !Object.hasOwn(item, key)) {
+            errors.push(`${reference}[${index}] is missing required property "${key}".`);
+            continue;
+          }
+          validateSchemaValue(`${reference}[${index}].${key}`, item[key], childDefinition, errors);
+        }
+      });
+    }
+  }
+  if (definition.type === 'object' && definition.valueSchema) {
+    for (const [key, childDefinition] of Object.entries(definition.valueSchema)) {
+      if (enforceRequiredChildren && childDefinition.required && !Object.hasOwn(value, key)) {
+        errors.push(`${reference} is missing required property "${key}".`);
+        continue;
+      }
+      validateSchemaValue(`${reference}.${key}`, value[key], childDefinition, errors);
+    }
+  }
+  if (definition.type === 'object' && definition.mapValueSchema) {
+    for (const [key, childValue] of Object.entries(value)) {
+      validateSchemaValue(`${reference}.${key}`, childValue, definition.mapValueSchema, errors);
+    }
+  }
+}
+/**
+ * Validate statically parsed interaction values against the registered schema.
+ * Top-level missing values are skipped because they may be supplied by a runtime
+ * variable that the lightweight source parser cannot resolve. Known literal
+ * values, nested objects, and array items are validated fully.
+ */
+export function validateInteractionSchema(slideId, interaction, errors) {
+  const properties = interaction?.schema?.properties;
+  if (!properties) return;
+  for (const [key, definition] of Object.entries(properties)) {
+    if (!Object.hasOwn(interaction, key)) continue;
+    validateSchemaValue(`Slide "${slideId}" interaction "${interaction.id}" property "${key}"`, interaction[key], definition, errors);
+  }
+}
+const DIRECT_ASSET_ATTRIBUTES = new Set([
+  'src', 'href', 'poster', 'data-src', 'data-audio-src', 'data-video-src',
+  'data-video-poster', 'data-video-captions', 'data-lightbox-src',
+  'data-lightbox-thumbnail', 'data-md-src'
+]);
+const NATIVE_ASSET_ATTRIBUTES = new Set(['src', 'href', 'poster']);
+function isExternalAssetReference(reference) {
+  return /^(?:data:|blob:|https?:|mailto:|tel:|#|\/\/|@)/i.test(reference);
+}
+function assetPathForReference(reference, coursePath, directHtml) {
+  if (typeof reference !== 'string' || !reference || reference.includes('${')) return null;
+  if (isExternalAssetReference(reference)) return null;
+  const clean = reference.split('#', 1)[0].split('?', 1)[0].replace(/\\/g, '/');
+  const withoutDot = clean.replace(/^\.\//, '');
+  if (directHtml && withoutDot.startsWith('assets/')) {
+    return {
+      error: `Direct HTML asset path "${reference}" will not exist in LMS packages. Use "course/${withoutDot}".`
+    };
+  }
+  let relativePath = null;
+  if (withoutDot.startsWith('course/assets/')) {
+    relativePath = withoutDot.slice('course/assets/'.length);
+  } else if (!directHtml && withoutDot.startsWith('assets/')) {
+    relativePath = withoutDot.slice('assets/'.length);
+  } else if (!directHtml && !withoutDot.startsWith('/') && !withoutDot.startsWith('../')) {
+    relativePath = withoutDot;
+  }
+  if (!relativePath) return null;
+  return { filePath: path.join(coursePath, 'assets', relativePath), relativePath };
+}
+function validateAssetReference(slideId, reference, coursePath, directHtml, errors) {
+  const resolved = assetPathForReference(reference, coursePath, directHtml);
+  if (!resolved) return;
+  if (resolved.error) {
+    errors.push(`Slide "${slideId}": ${resolved.error}`);
+    return;
+  }
+  if (!fs.existsSync(resolved.filePath)) {
+    errors.push(`Slide "${slideId}": local course asset not found: course/assets/${resolved.relativePath}`);
+  }
+}
+export function validateDirectAssetReferences(slideId, elements, coursePath, errors) {
+  for (const element of elements || []) {
+    for (const [attribute, value] of Object.entries(element.attributes || {})) {
+      if (!DIRECT_ASSET_ATTRIBUTES.has(attribute)) continue;
+      const componentOwnsHref = attribute === 'href' && element.attributes?.['data-component'] === 'lightbox';
+      validateAssetReference(
+        slideId,
+        value,
+        coursePath,
+        NATIVE_ASSET_ATTRIBUTES.has(attribute) && !componentOwnsHref,
+        errors
+      );
+    }
+  }
+}
+export function validateInteractionAssetReferences(slideId, interaction, coursePath, errors) {
+  const visit = (value, key = '') => {
+    if (!value || typeof value !== 'object') return;
+    for (const [childKey, childValue] of Object.entries(value)) {
+      if (childKey === 'schema') continue;
+      if (childKey === 'src' && typeof childValue === 'string') {
+        validateAssetReference(slideId, childValue, coursePath, false, errors);
+      } else if (childValue && typeof childValue === 'object') {
+        visit(childValue, childKey || key);
+      }
+    }
+  };
+  visit(interaction);
+}
+function customIconNames(coursePath) {
+  const iconFile = path.join(coursePath, 'icons.js');
+  if (!fs.existsSync(iconFile)) return [];
+  const source = fs.readFileSync(iconFile, 'utf-8');
+  const declaration = source.match(/export\s+const\s+customIcons\s*=\s*\{([\s\S]*?)\n\};/);
+  if (!declaration) return [];
+  return [...declaration[1].matchAll(/^\s*['"]([^'"]+)['"]\s*:/gm)].map(match => match[1]);
+}
+function isEmojiIcon(value) {
+  return /^[\u{1F300}-\u{1F9FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{1FA00}-\u{1FAFF}]/u.test(value);
+}
+export function validateMenuIcons(courseConfig, coursePath, warnings) {
+  const validIcons = new Set([...Object.keys(getAllIcons()), ...customIconNames(coursePath)]);
+  const inspectIcon = (icon, owner) => {
+    if (typeof icon !== 'string' || !icon || validIcons.has(icon) || isEmojiIcon(icon)) return;
+    warnings.push(`Unknown menu icon "${icon}" on ${owner}. Add it to course/icons.js or use a registered icon.`);
+  };
+  const walk = items => {
+    for (const item of items || []) {
+      inspectIcon(item.menu?.icon, `${item.type || 'item'} "${item.id || item.title || 'unknown'}"`);
+      if (item.children) walk(item.children);
+    }
+  };
+  walk(courseConfig.structure);
+  inspectIcon(courseConfig.navigation?.documentGallery?.icon, 'navigation.documentGallery');
+}
 /**
  * Static CSS class validation — extracts class="..." values from slide source
  * and checks them against the valid CSS class index built from PostCSS.

package/lib/build.js CHANGED Viewed

@@ -9,6 +9,69 @@ import { fileURLToPath } from 'url';
 import { validateProject } from './project-utils.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export function snapshotZipFiles(directory) {
+  const snapshot = new Map();
+  if (!fs.existsSync(directory)) return snapshot;
+  for (const filename of fs.readdirSync(directory)) {
+    if (!filename.endsWith('.zip')) continue;
+    const stats = fs.statSync(path.join(directory, filename));
+    snapshot.set(filename, { mtimeMs: stats.mtimeMs, size: stats.size });
+  }
+  return snapshot;
+}
+export function findProducedZipFiles(directory, before = new Map()) {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory)
+    .filter(filename => filename.endsWith('.zip'))
+    .map(filename => {
+      const stats = fs.statSync(path.join(directory, filename));
+      return { filename, mtimeMs: stats.mtimeMs, size: stats.size };
+    })
+    .filter(file => {
+      const previous = before.get(file.filename);
+      return !previous || previous.mtimeMs !== file.mtimeMs || previous.size !== file.size;
+    })
+    .sort((a, b) => a.mtimeMs - b.mtimeMs || a.filename.localeCompare(b.filename))
+    .map(file => file.filename);
+}
+export function detectBuiltFormat(distDirectory, requestedFormat) {
+  const indexPath = path.join(distDirectory, 'index.html');
+  if (fs.existsSync(indexPath)) {
+    const html = fs.readFileSync(indexPath, 'utf8');
+    const match = html.match(/<meta\s+name=["']lms-format["']\s+content=["']([^"']+)["']/i);
+    if (match?.[1]) return match[1];
+  }
+  if (fs.existsSync(path.join(distDirectory, 'cmi5.xml'))) return 'cmi5';
+  if (fs.existsSync(path.join(distDirectory, 'lti-tool-config.json'))) return 'lti';
+  return requestedFormat || 'scorm2004';
+}
+export function formatBuildOutput(format, zipFiles = []) {
+  const normalizedFormat = format || 'scorm2004';
+  const displayNames = {
+    scorm2004: 'SCORM 2004',
+    'scorm1.2': 'SCORM 1.2',
+    cmi5: 'cmi5',
+    lti: 'LTI 1.3',
+    'scorm2004-proxy': 'SCORM 2004 proxy',
+    'scorm1.2-proxy': 'SCORM 1.2 proxy',
+    'cmi5-remote': 'cmi5 remote'
+  };
+  const displayName = displayNames[normalizedFormat] || normalizedFormat;
+  const archives = zipFiles.map(filename => `   - ${filename}   Ready for LMS upload`).join('\n');
+  return `   Output:\n   - dist/           ${displayName} package files${archives ? `\n${archives}` : ''}\n\n   To test locally, launch dist/ or the archive in a ${displayName}-compatible LMS or conformance tool.`;
+}
 /**
  * Run a command and return a promise
  */
@@ -42,6 +105,7 @@ export async function build(options = {}) {
 `);
   const startTime = Date.now();
+  const zipSnapshot = snapshotZipFiles(process.cwd());
   try {
     // Build environment — pass lib dir so vite.config.js can resolve coursecode utilities
@@ -64,17 +128,14 @@ export async function build(options = {}) {
     const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
-    // Check for output
-    const zipFiles = fs.readdirSync(process.cwd()).filter(f => f.endsWith('.zip'));
+    const zipFiles = findProducedZipFiles(process.cwd(), zipSnapshot);
+    const builtFormat = detectBuiltFormat(path.join(process.cwd(), 'dist'), options.format);
+    const output = formatBuildOutput(builtFormat, zipFiles);
     console.log(`
 ✅ Build completed in ${elapsed}s
-   Output:
-   - dist/           SCORM package files
-   ${zipFiles.length > 0 ? `- ${zipFiles[zipFiles.length - 1]}   Ready for LMS upload` : ''}
-   To test locally, load dist/ directory in a SCORM testing tool.
+${output}
 `);
   } catch (error) {

package/lib/headless-browser.js CHANGED Viewed

@@ -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',

package/lib/info.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/template/course/slides/example-ui-showcase.js CHANGED Viewed

@@ -1386,7 +1386,7 @@ export const slide = {
                 <div class="flex gap-4 flex-wrap items-start justify-between">
                   <a href="assets/docs/example_md_1.md" data-component="lightbox" data-lightbox-caption="Sample Document" data-lightbox-subtitle="Sample Document" style="width: 200px; height: 150px;"></a>
                   <a href="assets/docs/example_md_2.md" data-component="lightbox" data-lightbox-caption="Reference Table" data-lightbox-subtitle="Reference Table" style="width: 200px; height: 150px;"></a>
-                  <a href="assets/docs/example_pdf_1.pdf" data-component="lightbox" data-lightbox-caption="Quick Reference Guide" data-lightbox-thumbnail="assets/docs/example_pdf_1_thumbnail.png" data-lightbox-subtitle="Quick Reference Guide" style="width: 200px; height: 150px;"></a>
+                  <a href="assets/docs/example_pdf_2.pdf" data-component="lightbox" data-lightbox-caption="Quick Reference Guide" data-lightbox-thumbnail="assets/docs/example_pdf_1_thumbnail.png" data-lightbox-subtitle="Quick Reference Guide" style="width: 200px; height: 150px;"></a>
                 </div>
               </section>