coursecode 0.1.57 → 0.1.58

package/framework/js/utilities/utilities.js

@@ -44,10 +44,15 @@ export function deepClone(obj) {
     }
     
     const clonedObj = {};
-    for (const key in obj) {
-        if (obj.hasOwnProperty(key)) {
-            clonedObj[key] = deepClone(obj[key]);
-        }
+    for (const key of Object.keys(obj)) {
+        // defineProperty avoids invoking Object.prototype.__proto__ when state
+        // originated from JSON containing that literal key.
+        Object.defineProperty(clonedObj, key, {
+            value: deepClone(obj[key]),
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
     }
     return clonedObj;
 }
@@ -241,7 +246,7 @@ export function waitFor(condition, timeout = 5000, interval = 100) {
  * @returns {Object} The merged target object
  */
 export function deepMerge(target, ...sources) {
-    if (!target || typeof target !== 'object' || Array.isArray(target)) {
+    if (!isPlainObject(target)) {
         throw new Error('deepMerge: target must be a plain object');
     }
 
@@ -251,22 +256,23 @@ export function deepMerge(target, ...sources) {
 
     const source = sources.shift();
 
-    if (source && typeof source === 'object' && !Array.isArray(source)) {
-        for (const key in source) {
-            if (source.hasOwnProperty(key)) {
-                const sourceValue = source[key];
-                const targetValue = target[key];
-
-                if (sourceValue && typeof sourceValue === 'object' && !Array.isArray(sourceValue)) {
-                    // Recursive merge for plain objects
-                    if (!targetValue || typeof targetValue !== 'object' || Array.isArray(targetValue)) {
-                        target[key] = {};
-                    }
-                    deepMerge(target[key], sourceValue);
-                } else {
-                    // Direct assignment for primitives, arrays, and other types
-                    target[key] = sourceValue;
+    if (isPlainObject(source)) {
+        for (const key of Object.keys(source)) {
+            if (key === '__proto__' || key === 'prototype' || key === 'constructor') {
+                throw new Error(`deepMerge: unsafe key "${key}" is not allowed`);
+            }
+
+            const sourceValue = source[key];
+            const targetValue = target[key];
+
+            if (isPlainObject(sourceValue)) {
+                if (!isPlainObject(targetValue)) {
+                    target[key] = {};
                 }
+                deepMerge(target[key], sourceValue);
+            } else {
+                // Direct assignment for primitives, arrays, and non-plain objects
+                target[key] = sourceValue;
             }
         }
     }
@@ -274,6 +280,12 @@ export function deepMerge(target, ...sources) {
     return deepMerge(target, ...sources);
 }
 
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+
 /**
  * Shuffle an array using Fisher-Yates algorithm (creates new array).
  * @param {Array} array - Array to shuffle

package/framework/js/utilities/view-manager.js

@@ -1,8 +1,9 @@
 import { eventBus } from '../core/event-bus.js';
 import { logger } from './logger.js';
 import { validateRenderedHTML } from '../validation/html-validators.js';
-import { initializeDeclarativeComponents } from './ui-initializer.js';
+import { cleanupDeclarativeComponents, initializeDeclarativeComponents } from './ui-initializer.js';
 import { courseConfig } from '../../../course/course-config.js';
+import { rewritePortableAssetAttributes } from './portable-assets.js';
 
 /**
  * Creates a view manager for a given container element.
@@ -78,9 +79,20 @@ export function createViewManager(container, scope = 'local') {
         // Auto-wrap content with content-width class if configured and not already wrapped
         newElement = autoWrapContentIfNeeded(newElement, name);
 
+        // Convert copied course assets to embedded data URLs before components
+        // initialize and begin loading media in a portable HTML export.
+        rewritePortableAssetAttributes(newElement);
+
         // Validate rendered HTML for common issues BEFORE adding to DOM
         validateRenderedContent(newElement, name);
 
+        // Release component resources before removing the old view. Some
+        // components subscribe to document-level events or own media managers,
+        // so removing their DOM alone is not sufficient cleanup.
+        if (oldElement) {
+            cleanupDeclarativeComponents(oldElement);
+        }
+
         // Clear container and add new view
         container.innerHTML = '';
         container.appendChild(newElement);
@@ -243,6 +255,9 @@ export function createViewManager(container, scope = 'local') {
             if (currentElement && typeof currentView.onHide === 'function') {
                 currentView.onHide(currentElement);
             }
+            if (currentElement) {
+                cleanupDeclarativeComponents(currentElement);
+            }
         }
         container.innerHTML = '';
         currentViewName = null;

package/framework/js/validation/scorm-validators.js

@@ -229,6 +229,75 @@ export function formatLearnerResponseForScorm(interactionType, response) {
     }
 }
 
+/** SCORM 1.2 interaction vocabulary (RTE 1.2.7). */
+export const SCORM_12_INTERACTION_TYPES = [
+    'true-false',
+    'choice',
+    'fill-in',
+    'matching',
+    'performance',
+    'likert',
+    'sequencing',
+    'numeric'
+];
+
+/**
+ * Converts framework/SCORM 2004 interaction data to the materially different
+ * SCORM 1.2 vocabulary and response syntax.
+ *
+ * The framework keeps one lossless internal representation. Unsupported 2004
+ * types are represented as fill-in rows in the optional native 1.2 interaction
+ * array; the original record remains intact in suspend_data.
+ */
+export function serializeInteractionForScorm12(interaction) {
+    const type = SCORM_12_INTERACTION_TYPES.includes(interaction.type)
+        ? interaction.type
+        : 'fill-in';
+
+    const convertResponse = value => {
+        if (value === null || value === undefined) return '';
+        let serialized = String(value);
+
+        if (interaction.type === 'true-false') {
+            const normalized = serialized.toLowerCase().trim();
+            if (normalized === 'true' || normalized === 't' || normalized === '1') return 't';
+            if (normalized === 'false' || normalized === 'f' || normalized === '0') return 'f';
+            return '';
+        }
+
+        if (interaction.type === 'choice' || interaction.type === 'sequencing') {
+            serialized = serialized.replaceAll('[,]', ',');
+        } else if (interaction.type === 'matching') {
+            serialized = serialized.replaceAll('[.]', '.').replaceAll('[,]', ',');
+        }
+
+        // CMIString values in SCORM 1.2 are ASCII. Escape non-ASCII code units
+        // instead of submitting an invalid value that strict LMSs reject.
+        return serialized.replace(/[^\x00-\x7F]/g, char =>
+            `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`
+        );
+    };
+
+    const result = interaction.result === 'incorrect'
+        ? 'wrong'
+        : interaction.result;
+
+    return {
+        ...interaction,
+        id: convertResponse(interaction.id),
+        type,
+        learner_response: convertResponse(interaction.learner_response),
+        result,
+        correct_responses: interaction.correct_responses?.map(item => {
+            if (typeof item === 'object' && item !== null && 'pattern' in item) {
+                return { ...item, pattern: convertResponse(item.pattern) };
+            }
+            return convertResponse(item);
+        }),
+        objectives: interaction.objectives?.map(convertResponse)
+    };
+}
+
 /**
  * SCORM 2004 4th Edition valid completion status values.
  * @constant {string[]}

package/framework/version.json

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

package/lib/authoring-api.js

@@ -965,7 +965,32 @@ export async function getWorkflowStatus(port = 4173) {
     // Infer stage
     let stage, stageNumber, nextAction, recommendedTool;
 
-    if (checklist.hasSlides && checklist.hasCourseConfig) {
+    const isPowerPointImport = checklist.source === 'powerpoint-import';
+    const needsReferenceConversion = checklist.hasRawRefs && !checklist.hasConvertedRefs && !isPowerPointImport;
+    const needsOutline = checklist.hasConvertedRefs && !checklist.hasOutline && !isPowerPointImport;
+    const hasNoAuthoringInputs = !checklist.hasRawRefs && !checklist.hasConvertedRefs && !checklist.hasOutline && !isPowerPointImport;
+
+    if (needsReferenceConversion) {
+        stage = 'source-ingestion';
+        stageNumber = 1;
+        nextAction = 'Convert reference files to markdown: coursecode convert';
+        recommendedTool = 'coursecode_workflow_status';
+    } else if (needsOutline) {
+        stage = 'outline-creation';
+        stageNumber = 2;
+        nextAction = 'Create course outline from reference materials. Stage instructions have all file paths.';
+        recommendedTool = 'coursecode_workflow_status';
+    } else if (hasNoAuthoringInputs) {
+        stage = 'source-ingestion';
+        stageNumber = 1;
+        nextAction = 'Add reference files (PDF, DOCX, PPTX, MD) to course/references/ and run coursecode convert';
+        recommendedTool = 'coursecode_workflow_status';
+    } else if (checklist.hasOutline && (!checklist.hasSlides || !checklist.hasCourseConfig)) {
+        stage = 'course-building';
+        stageNumber = 3;
+        nextAction = 'Build slide files and course-config.js based on the outline. Stage instructions have all file paths.';
+        recommendedTool = 'coursecode_workflow_status';
+    } else if (checklist.hasSlides && checklist.hasCourseConfig) {
         // Course is built — run lint to decide polish vs export
         let lintPassed = false;
         try {
@@ -993,21 +1018,6 @@ export async function getWorkflowStatus(port = 4173) {
             }
             recommendedTool = 'coursecode_lint';
         }
-    } else if (!checklist.hasRawRefs && !checklist.hasConvertedRefs) {
-        stage = 'source-ingestion';
-        stageNumber = 1;
-        nextAction = 'Add reference files (PDF, DOCX, PPTX, MD) to course/references/ and run coursecode convert';
-        recommendedTool = 'coursecode_workflow_status';
-    } else if (checklist.hasRawRefs && !checklist.hasConvertedRefs) {
-        stage = 'source-ingestion';
-        stageNumber = 1;
-        nextAction = 'Convert reference files to markdown: coursecode convert';
-        recommendedTool = 'coursecode_workflow_status';
-    } else if (!checklist.hasOutline) {
-        stage = 'outline-creation';
-        stageNumber = 2;
-        nextAction = 'Create course outline from reference materials. Stage instructions have all file paths.';
-        recommendedTool = 'coursecode_workflow_status';
     } else {
         stage = 'course-building';
         stageNumber = 3;
@@ -1050,7 +1060,7 @@ export async function buildCourse(options = {}) {
         const child = spawn('npx', ['vite', 'build'], {
             cwd: courseRoot,
             env,
-            shell: true,
+            shell: process.platform === 'win32',
             stdio: ['ignore', 'pipe', 'pipe']
         });
 
@@ -1059,6 +1069,16 @@ export async function buildCourse(options = {}) {
 
         child.stdout.on('data', (data) => { _stdout += data.toString(); });
         child.stderr.on('data', (data) => { stderr += data.toString(); });
+        child.on('error', (error) => {
+            const duration = ((Date.now() - startTime) / 1000).toFixed(1) + 's';
+            resolve({
+                success: false,
+                error: error.message,
+                errors: [error.message],
+                warnings: [],
+                duration
+            });
+        });
 
         child.on('close', (code) => {
             const duration = ((Date.now() - startTime) / 1000).toFixed(1) + 's';
@@ -1235,4 +1255,3 @@ export async function generateNarration(options = {}) {
         });
     });
 }
-

package/lib/build-packaging.js

@@ -28,8 +28,30 @@ function sanitizeTitle(title) {
 
 function withClientCredentials(externalUrl, clientId, token) {
     if (!clientId || !token) return externalUrl;
-    const separator = externalUrl.includes('?') ? '&' : '?';
-    return `${externalUrl}${separator}clientId=${encodeURIComponent(clientId)}&token=${encodeURIComponent(token)}`;
+    const url = new URL(externalUrl);
+    url.searchParams.set('clientId', clientId);
+    url.searchParams.set('token', token);
+    return url.toString();
+}
+
+function validateExternalUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    } catch {
+        throw new Error(`externalUrl must be an absolute URL, received: ${value}`);
+    }
+    const localHttp = url.protocol === 'http:' && ['localhost', '127.0.0.1', '::1'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !localHttp) {
+        throw new Error('externalUrl must use HTTPS (HTTP is allowed only for local development)');
+    }
+    if (url.hash) {
+        throw new Error('externalUrl must not contain a URL fragment because launch credentials would not reach the server');
+    }
+    if (url.username || url.password) {
+        throw new Error('externalUrl must not embed HTTP credentials');
+    }
+    return url;
 }
 
 function zipDirectory(sourceDir, zipFilePath) {
@@ -55,6 +77,7 @@ export function validateExternalHostingConfig(config) {
     if (!config.externalUrl) {
         throw new Error(`${config.lmsFormat} format requires 'externalUrl' in course-config.js`);
     }
+    validateExternalUrl(config.externalUrl);
 
     if (config.accessControl?.enforcement !== 'server') {
         throw new Error(`${config.lmsFormat} requires accessControl.enforcement = 'server'. Browser-only token checks are not secure.`);
@@ -164,6 +187,10 @@ export async function createProxyPackage({ rootDir, config, clientId = null, tok
 
         let proxyHtml = fs.readFileSync(path.join(templatesDir, 'proxy.html'), 'utf-8');
         proxyHtml = proxyHtml.replace('{{EXTERNAL_URL_JSON}}', JSON.stringify(externalUrl));
+        proxyHtml = proxyHtml.replace(
+            '{{BASE_FORMAT_JSON}}',
+            JSON.stringify(config.lmsFormat === 'scorm1.2-proxy' ? 'scorm1.2' : 'scorm2004')
+        );
         fs.writeFileSync(path.join(proxyDir, 'proxy.html'), proxyHtml);
 
         fs.copyFileSync(path.join(templatesDir, 'scorm-bridge.js'), path.join(proxyDir, 'scorm-bridge.js'));
@@ -172,6 +199,22 @@ export async function createProxyPackage({ rootDir, config, clientId = null, tok
         const { filename, content } = generateManifest(config.lmsFormat, config, [], { externalUrl: config.externalUrl });
         fs.writeFileSync(path.join(proxyDir, filename), content);
 
+        const schemasDir = path.join(PACKAGE_ROOT, 'schemas');
+        for (const entry of fs.readdirSync(schemasDir, { withFileTypes: true })) {
+            if (entry.isFile() && /\.(?:xsd|dtd|xml)$/i.test(entry.name)) {
+                fs.copyFileSync(path.join(schemasDir, entry.name), path.join(proxyDir, entry.name));
+            }
+        }
+        fs.cpSync(path.join(schemasDir, 'common'), path.join(proxyDir, 'common'), { recursive: true });
+
+        const required = config.lmsFormat === 'scorm1.2-proxy'
+            ? ['imsmanifest.xml', 'proxy.html', 'scorm-bridge.js', 'pipwerks.js', 'imscp_rootv1p1p2.xsd', 'adlcp_rootv1p2.xsd', 'ims_xml.xsd']
+            : ['imsmanifest.xml', 'proxy.html', 'scorm-bridge.js', 'pipwerks.js', 'imscp_v1p1.xsd', 'adlcp_v1p3.xsd', 'imsss_v1p0.xsd'];
+        const missing = required.filter(file => !fs.existsSync(path.join(proxyDir, file)));
+        if (missing.length > 0 || proxyHtml.includes('{{')) {
+            throw new Error(`Proxy package validation failed: ${missing.length ? `missing ${missing.join(', ')}` : 'unresolved template placeholder'}`);
+        }
+
         if (fs.existsSync(zipFilePath)) fs.unlinkSync(zipFilePath);
         const bytes = await zipDirectory(proxyDir, zipFilePath);
         const sizeKB = (bytes / 1024).toFixed(1);
@@ -206,7 +249,8 @@ export async function createRemotePackage({ rootDir, config, clientId = null, to
         const bytes = await zipDirectory(remoteDir, zipFilePath);
         const sizeKB = (bytes / 1024).toFixed(1);
         console.warn(`📦 Created ${zipFileName} (${sizeKB} KB) - Upload to LMS`);
-        console.warn(`   AU URL points to: ${externalUrl.replace(/\/$/, '')}/index.html`);
+        const auUrl = content.match(/<url>([^<]+)<\/url>/)?.[1] || externalUrl;
+        console.warn(`   AU URL points to: ${auUrl}`);
         return zipFilePath;
     } finally {
         if (fs.existsSync(remoteDir)) fs.rmSync(remoteDir, { recursive: true });

package/lib/build.js

@@ -17,7 +17,7 @@ function runCommand(cmd, args, options = {}) {
     const child = spawn(cmd, args, {
       cwd: process.cwd(),
       stdio: 'inherit',
-      shell: true,
+      shell: process.platform === 'win32',
       env: options.env || process.env,
       ...options
     });

package/lib/cloud.js

@@ -11,7 +11,7 @@ import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import { exec } from 'child_process';
+import { execFile } from 'child_process';
 import readline from 'readline';
 import { fileURLToPath } from 'url';
 
@@ -427,10 +427,23 @@ function handleResponseError(status, body) {
  */
 function openBrowser(url) {
   const platform = process.platform;
-  const cmd = platform === 'darwin' ? 'open'
-    : platform === 'win32' ? 'start'
-      : 'xdg-open';
-  exec(`${cmd} "${url}"`);
+  let command;
+  let args;
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    command = 'rundll32';
+    args = ['url.dll,FileProtocolHandler', url];
+  } else {
+    command = 'xdg-open';
+    args = [url];
+  }
+
+  const child = execFile(command, args);
+  child.on('error', (error) => {
+    console.warn(`  ⚠ Could not open the browser automatically: ${error.message}`);
+  });
 }
 
 /**
@@ -987,9 +1000,17 @@ export async function deploy(options = {}) {
       // Reconcile local sourceType with cloud truth (handles unlink-via-dashboard)
       try {
         const statusData = JSON.parse(await statusRes.text());
-        const serverSourceType = statusData.source?.type || statusData.source_type;
+        const serverGithubRepo = statusData.source?.githubRepo || statusData.github_repo;
         const localRc = readRcConfig();
-        if (localRc?.sourceType === 'github' && serverSourceType !== 'github') {
+        if (serverGithubRepo && (
+          localRc?.sourceType !== 'github' || localRc?.githubRepo !== serverGithubRepo
+        )) {
+          updateRcConfig((rc) => {
+            rc.sourceType = 'github';
+            rc.githubRepo = serverGithubRepo;
+            return rc;
+          });
+        } else if (localRc?.sourceType === 'github' && !serverGithubRepo) {
           updateRcConfig((rc) => {
             delete rc.sourceType;
             delete rc.githubRepo;
@@ -1508,8 +1529,16 @@ export async function status(options = {}) {
 
   // Reconcile local sourceType with cloud truth (handles unlink-via-dashboard)
   const localRc = readRcConfig();
-  const serverSourceType = data.source?.type || data.source_type;
-  if (localRc?.sourceType === 'github' && serverSourceType !== 'github') {
+  const serverGithubRepo = data.source?.githubRepo || data.github_repo;
+  if (serverGithubRepo && (
+    localRc?.sourceType !== 'github' || localRc?.githubRepo !== serverGithubRepo
+  )) {
+    updateRcConfig((rc) => {
+      rc.sourceType = 'github';
+      rc.githubRepo = serverGithubRepo;
+      return rc;
+    });
+  } else if (localRc?.sourceType === 'github' && !serverGithubRepo) {
     updateRcConfig((rc) => {
       delete rc.sourceType;
       delete rc.githubRepo;
@@ -1527,9 +1556,9 @@ export async function status(options = {}) {
 
   console.log(`\n${data.slug} — ${data.name} (${data.orgName})\n`);
 
-  const sourceType = data.source?.type || data.source_type;
   const githubRepo = data.source?.githubRepo || data.github_repo;
-  if (sourceType === 'github' && githubRepo) {
+  const sourceType = data.source?.type || data.source_type;
+  if (githubRepo) {
     console.log(`Source:         GitHub — ${githubRepo}`);
     console.log('                production=github | preview=cli+github');
   } else if (sourceType) {

package/lib/convert.js

@@ -238,13 +238,41 @@ async function convertFile(filePath) {
 async function convertDocx(filePath) {
     const mammoth = await import('mammoth');
     const result = await mammoth.convertToMarkdown({ path: filePath });
+    const sanitized = replaceEmbeddedDataImages(result.value);
+    const warnings = result.messages.filter(m => m.type === 'warning');
+
+    if (sanitized.omittedImageCount > 0) {
+        warnings.push({
+            type: 'warning',
+            message: `Omitted ${sanitized.omittedImageCount} embedded image payload(s). Review the source document for visual content.`
+        });
+    }
     
     return {
-        markdown: result.value,
-        warnings: result.messages.filter(m => m.type === 'warning')
+        markdown: sanitized.markdown,
+        warnings
     };
 }
 
+/**
+ * Replace mammoth's inline base64 image output with compact review markers.
+ * Reference Markdown is consumed by AI authoring tools, where multi-megabyte
+ * data URIs waste context and do not preserve useful visual meaning.
+ */
+export function replaceEmbeddedDataImages(markdown) {
+    let omittedImageCount = 0;
+    const sanitized = markdown.replace(
+        /!\[([^\]]*)\]\(data:image\/[^;]+;base64,[^)]+\)/gi,
+        (_match, altText) => {
+            omittedImageCount++;
+            const label = altText?.trim() ? `: ${altText.trim()}` : '';
+            return `*[Embedded image omitted${label}. Review the source document for visual content.]*`;
+        }
+    );
+
+    return { markdown: sanitized, omittedImageCount };
+}
+
 /**
  * Convert PPTX to markdown using node-pptx-parser
  */

package/lib/create.js

@@ -172,7 +172,7 @@ function npmInstall(cwd) {
     const child = spawn(command, args, {
       cwd,
       stdio: 'inherit',
-      shell: !npmCli
+      shell: !npmCli && process.platform === 'win32'
     });
 
     child.on('close', (code) => {
@@ -182,6 +182,7 @@ function npmInstall(cwd) {
         reject(new Error(`npm install failed with code ${code}`));
       }
     });
+    child.on('error', reject);
   });
 }
 
@@ -193,7 +194,7 @@ function gitInit(cwd) {
     const child = spawn('git', ['init'], {
       cwd,
       stdio: 'pipe',
-      shell: true
+      shell: false
     });
 
     child.on('close', (code) => {
@@ -203,6 +204,7 @@ function gitInit(cwd) {
         reject(new Error(`git init failed with code ${code}`));
       }
     });
+    child.on('error', reject);
   });
 }
 
@@ -384,7 +386,7 @@ export async function create(name, options = {}) {
     const child = spawn(command, args, {
       cwd: targetDir,
       stdio: 'inherit',
-      shell: !npxCli
+      shell: !npxCli && process.platform === 'win32'
     });
 
     child.on('error', () => {

package/lib/dev.js

@@ -33,7 +33,7 @@ export async function dev(options = {}) {
   const viteBuild = spawn('npx', ['vite', 'build', '--mode', 'development', '--watch'], {
     cwd: process.cwd(),
     stdio: 'inherit',
-    shell: true,
+    shell: process.platform === 'win32',
     env
   });