coursecode 0.1.57 → 0.1.58

package/lib/headless-browser.js

@@ -69,6 +69,10 @@ class HeadlessBrowser {
         this.chromePath = null;
         this._sseReloadListener = null;
         this._reconnectTimer = null;
+        this._reloadDebounceTimer = null;
+        this._reloadInProgress = false;
+        this._reloadQueued = false;
+        this._resolveReload = null;
         this._stopped = false;
         this._consoleLogs = [];
         this._viewport = { width: 1280, height: 720 };
@@ -195,19 +199,7 @@ class HeadlessBrowser {
                 res.on('data', async (chunk) => {
                     if (this._stopped) return;
                     const data = chunk.toString();
-                    if (data.includes('data: reload')) {
-                        // Track the reload so concurrent tool calls wait for it
-                        let resolveReload;
-                        this._reloadPromise = new Promise(r => { resolveReload = r; });
-                        try {
-                            await this._navigateToPreview();
-                        } catch (_e) {
-                            // Preview may be mid-rebuild, retry will happen on next SSE
-                        } finally {
-                            this._reloadPromise = null;
-                            resolveReload();
-                        }
-                    }
+                    if (data.includes('data: reload')) this._scheduleReload();
                 });
 
                 res.on('end', () => {
@@ -227,6 +219,55 @@ class HeadlessBrowser {
         connect();
     }
 
+    /**
+     * Coalesce rapid preview rebuild notifications into one browser reload.
+     * If another event arrives while navigation is running, perform one more
+     * debounced reload before releasing tool calls waiting on _reloadPromise.
+     * @private
+     */
+    _scheduleReload() {
+        if (this._stopped) return;
+
+        if (!this._reloadPromise) {
+            this._reloadPromise = new Promise(resolve => {
+                this._resolveReload = resolve;
+            });
+        }
+
+        if (this._reloadInProgress) {
+            this._reloadQueued = true;
+            return;
+        }
+
+        if (this._reloadDebounceTimer) clearTimeout(this._reloadDebounceTimer);
+        this._reloadDebounceTimer = setTimeout(() => this._performScheduledReload(), 300);
+    }
+
+    /** @private */
+    async _performScheduledReload() {
+        this._reloadDebounceTimer = null;
+        this._reloadInProgress = true;
+        this._reloadQueued = false;
+
+        try {
+            await this._navigateToPreview();
+        } catch (_e) {
+            // A later SSE event will retry after the preview finishes rebuilding.
+        } finally {
+            this._reloadInProgress = false;
+        }
+
+        if (this._reloadQueued) {
+            this._scheduleReload();
+            return;
+        }
+
+        const resolveReload = this._resolveReload;
+        this._reloadPromise = null;
+        this._resolveReload = null;
+        resolveReload?.();
+    }
+
     /**
      * Execute a function in the course iframe's context.
      * This is how runtime tools call CourseCodeAutomation methods.
@@ -481,6 +522,17 @@ class HeadlessBrowser {
             this._reconnectTimer = null;
         }
 
+        if (this._reloadDebounceTimer) {
+            clearTimeout(this._reloadDebounceTimer);
+            this._reloadDebounceTimer = null;
+        }
+
+        this._reloadQueued = false;
+        this._reloadInProgress = false;
+        this._resolveReload?.();
+        this._resolveReload = null;
+        this._reloadPromise = null;
+
         if (this._sseReloadListener) {
             this._sseReloadListener.destroy();
             this._sseReloadListener = null;
@@ -498,4 +550,4 @@ class HeadlessBrowser {
 // Singleton instance
 const headless = new HeadlessBrowser();
 export default headless;
-export { findChrome };
+export { HeadlessBrowser, findChrome };

package/lib/manifest/cmi5-manifest.js

@@ -22,20 +22,42 @@ import { escapeXmlAttribute, escapeXmlText } from './xml-utils.js';
  */
 export function generateCmi5Manifest(config, _files, options = {}) {
   // cmi5 course identifier - use configured identifier or generate from title
-  const courseId = config.identifier ||
-    `urn:coursecode:${config.title.replace(/[^a-zA-Z0-9]/g, '-').toLowerCase()}`;
+  const titleSlug = String(config.title || 'course')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'course';
+  const courseId = config.identifier || `urn:coursecode:${titleSlug}`;
+  try {
+    new URL(courseId);
+  } catch {
+    throw new Error(`cmi5 course identifier must be an absolute IRI: ${courseId}`);
+  }
 
   // Package-level mastery is optional. Do not invent a value from one
   // assessment because a course can contain multiple thresholds.
   const masteryAttribute = Number.isFinite(config.masteryScore)
     ? ` masteryScore="${(config.masteryScore / 100).toFixed(2)}"`
     : '';
+  const allowedMoveOn = new Set([
+    'Passed', 'Completed', 'CompletedAndPassed', 'CompletedOrPassed', 'NotApplicable'
+  ]);
+  const moveOn = config.moveOn || (Number.isFinite(config.masteryScore) ? 'CompletedAndPassed' : 'Completed');
+  if (!allowedMoveOn.has(moveOn)) {
+    throw new Error(`Invalid cmi5 moveOn value: ${moveOn}`);
+  }
 
   // AU identifier - derive from course ID
   const auId = `${courseId}/au/1`;
 
   // URL: absolute for cmi5-remote (use as-is), relative for standard cmi5
-  const auUrl = options.externalUrl || 'index.html';
+  let auUrl = options.externalUrl || 'index.html';
+  if (options.externalUrl) {
+    const parsedUrl = new URL(options.externalUrl);
+    if (!/\.[A-Za-z0-9]+$/.test(parsedUrl.pathname)) {
+      parsedUrl.pathname = `${parsedUrl.pathname.replace(/\/$/, '')}/index.html`;
+    }
+    auUrl = parsedUrl.toString();
+  }
   const escapedCourseId = escapeXmlAttribute(courseId);
   const escapedAuId = escapeXmlAttribute(auId);
   const escapedLanguage = escapeXmlAttribute(config.language);
@@ -55,7 +77,7 @@ export function generateCmi5Manifest(config, _files, options = {}) {
     </description>
   </course>
 
-  <au id="${escapedAuId}" moveOn="Completed"${masteryAttribute} launchMethod="OwnWindow">
+  <au id="${escapedAuId}" moveOn="${escapeXmlAttribute(moveOn)}"${masteryAttribute} launchMethod="OwnWindow">
     <title>
       <langstring lang="${escapedLanguage}">${title}</langstring>
     </title>

package/lib/manifest/lti-tool-config.js

@@ -23,8 +23,13 @@ export function generateLtiToolConfig(config, options = {}) {
     } catch {
         throw new Error(`Invalid LTI externalUrl: ${configuredUrl}`);
     }
-    if (!['https:', 'http:'].includes(parsedBaseUrl.protocol)) {
-        throw new Error('LTI externalUrl must use https (or http for local development)');
+    const localHttp = parsedBaseUrl.protocol === 'http:' &&
+        ['localhost', '127.0.0.1', '::1'].includes(parsedBaseUrl.hostname);
+    if (parsedBaseUrl.protocol !== 'https:' && !localHttp) {
+        throw new Error('LTI externalUrl must use HTTPS (HTTP is allowed only for local development)');
+    }
+    if (parsedBaseUrl.search || parsedBaseUrl.hash || parsedBaseUrl.username || parsedBaseUrl.password) {
+        throw new Error('LTI externalUrl must not contain a query, fragment, or embedded HTTP credentials');
     }
     const baseUrl = parsedBaseUrl.toString().replace(/\/$/, '');
     const title = config.title || 'CourseCode Course';

package/lib/manifest/manifest-factory.d.ts

@@ -6,5 +6,5 @@ export function generateManifest(
 ): { filename: string; content: string }
 
 export function getSchemaFiles(
-  format: 'scorm2004' | 'scorm1.2' | 'cmi5' | 'lti'
+  format: 'scorm2004' | 'scorm1.2' | 'scorm1.2-proxy' | 'scorm2004-proxy' | 'cmi5' | 'lti'
 ): string[]

package/lib/manifest/manifest-factory.js

@@ -77,6 +77,7 @@ export function getSchemaFiles(format) {
             return [];
 
         case 'scorm1.2':
+        case 'scorm1.2-proxy':
             // SCORM 1.2 schema files
             return [
                 'imscp_rootv1p1p2.xsd',
@@ -84,6 +85,7 @@ export function getSchemaFiles(format) {
                 'ims_xml.xsd'
             ];
 
+        case 'scorm2004-proxy':
         case 'scorm2004':
         default:
             // SCORM 2004 4th Edition schema files
@@ -92,8 +94,7 @@ export function getSchemaFiles(format) {
                 'adlcp_v1p3.xsd',
                 'imsss_v1p0.xsd',
                 'adlseq_v1p3.xsd',
-                'adlnav_v1p3.xsd',
-                'lom.xsd'
+                'adlnav_v1p3.xsd'
             ];
     }
 }

package/lib/manifest/scorm-12-manifest.js

@@ -8,7 +8,7 @@
  * - 4th Edition schema references
  */
 
-import { escapeXmlAttribute, escapeXmlText } from './xml-utils.js';
+import { escapeXmlAttribute, escapeXmlText, makeXmlId } from './xml-utils.js';
 
 /**
  * Generates the SCORM 1.2 manifest.
@@ -34,7 +34,7 @@ export function generateScorm12Manifest(config, files) {
     // SCORM 1.2 uses ADLCP 1.2 schema and doesn't include sequencing
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!-- SCORM 1.2 manifest - GENERATED FILE - DO NOT EDIT MANUALLY -->
-<manifest identifier="${config.title.replace(/[^a-zA-Z0-9]/g, '-')}"
+<manifest identifier="${makeXmlId(config.identifier || config.title)}"
           version="${version}"
           xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
           xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2"

package/lib/manifest/scorm-2004-manifest.js

@@ -3,7 +3,7 @@
  * @description Generates imsmanifest.xml for SCORM 2004 4th Edition packages.
  */
 
-import { escapeXmlAttribute, escapeXmlText } from './xml-utils.js';
+import { escapeXmlAttribute, escapeXmlText, makeXmlId } from './xml-utils.js';
 
 /**
  * Generates the SCORM 2004 4th Edition manifest.
@@ -21,14 +21,11 @@ export function generateScorm2004Manifest(config, files) {
 
     const fileEntries = resourceFiles.map(f => `      <file href="${escapeXmlAttribute(f)}"/>`).join('\n');
     const version = escapeXmlAttribute(config.version);
-    const language = escapeXmlAttribute(config.language);
     const title = escapeXmlText(config.title);
-    const description = escapeXmlText(config.description);
-    const author = escapeXmlText(config.author);
 
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!-- SCORM 2004 4th Edition manifest - GENERATED FILE - DO NOT EDIT MANUALLY -->
-<manifest identifier="${config.title.replace(/[^a-zA-Z0-9]/g, '-')}"
+<manifest identifier="${makeXmlId(config.identifier || config.title)}"
             version="${version}"
             xmlns="http://www.imsglobal.org/xsd/imscp_v1p1"
             xmlns:imscp="http://www.imsglobal.org/xsd/imscp_v1p1"
@@ -36,40 +33,18 @@ export function generateScorm2004Manifest(config, files) {
             xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_v1p3"
             xmlns:adlseq="http://www.adlnet.org/xsd/adlseq_v1p3"
             xmlns:adlnav="http://www.adlnet.org/xsd/adlnav_v1p3"
-            xmlns:lom="http://ltsc.ieee.org/xsd/LOM"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="
               http://www.imsglobal.org/xsd/imscp_v1p1 imscp_v1p1.xsd
               http://www.imsglobal.org/xsd/imsss imsss_v1p0.xsd
               http://www.adlnet.org/xsd/adlcp_v1p3 adlcp_v1p3.xsd
               http://www.adlnet.org/xsd/adlseq_v1p3 adlseq_v1p3.xsd
-              http://www.adlnet.org/xsd/adlnav_v1p3 adlnav_v1p3.xsd
-              http://ltsc.ieee.org/xsd/LOM lom.xsd"
+              http://www.adlnet.org/xsd/adlnav_v1p3 adlnav_v1p3.xsd"
             xml:base="./">
 
   <metadata>
     <schema>ADL SCORM</schema>
     <schemaversion>2004 4th Edition</schemaversion>
-    <lom:lom>
-      <lom:general>
-        <lom:title><lom:string language="${language}">${title}</lom:string></lom:title>
-        <lom:description><lom:string language="${language}">${description}</lom:string></lom:description>
-        <lom:language>${escapeXmlText(config.language)}</lom:language>
-      </lom:general>
-      <lom:lifecycle>
-        <lom:version><lom:string>${escapeXmlText(config.version)}</lom:string></lom:version>
-        <lom:contribute>
-          <lom:role>
-            <lom:source><lom:string>LOMv1.0</lom:string></lom:source>
-            <lom:value><lom:string>author</lom:string></lom:value>
-          </lom:role>
-          <lom:entity>${author}</lom:entity>
-        </lom:contribute>
-      </lom:lifecycle>
-      <lom:technical>
-        <lom:format>text/html</lom:format>
-      </lom:technical>
-    </lom:lom>
   </metadata>
 
   <organizations default="org-1">

package/lib/manifest/scorm-proxy-manifest.js

@@ -10,37 +10,47 @@
  * Works for both SCORM 1.2 and 2004 - pipwerks auto-detects.
  */
 
+import { escapeXmlAttribute, escapeXmlText, makeXmlId } from './xml-utils.js';
+
+function proxyIdentifier(config) {
+    return makeXmlId(config.identifier || config.title, 'course');
+}
+
 /**
  * Generate SCORM 1.2 proxy manifest
  * @param {Object} config - Course configuration
  * @returns {string} imsmanifest.xml content
  */
 export function generateScorm12ProxyManifest(config) {
-    const identifier = config.identifier || 
-        config.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
+    const identifier = proxyIdentifier(config);
+    const escapedIdentifier = escapeXmlAttribute(identifier);
 
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!-- SCORM 1.2 Proxy Manifest - Generated by CourseCode -->
-<manifest identifier="${identifier}_proxy" version="1.0"
+<manifest identifier="${escapedIdentifier}_proxy" version="1.0"
     xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
-    xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2">
+    xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="
+      http://www.imsproject.org/xsd/imscp_rootv1p1p2 imscp_rootv1p1p2.xsd
+      http://www.adlnet.org/xsd/adlcp_rootv1p2 adlcp_rootv1p2.xsd">
     
     <metadata>
         <schema>ADL SCORM</schema>
         <schemaversion>1.2</schemaversion>
     </metadata>
     
-    <organizations default="org_${identifier}">
-        <organization identifier="org_${identifier}">
-            <title>${escapeXml(config.title)}</title>
-            <item identifier="item_${identifier}" identifierref="res_${identifier}">
-                <title>${escapeXml(config.title)}</title>
+    <organizations default="org_${escapedIdentifier}">
+        <organization identifier="org_${escapedIdentifier}">
+            <title>${escapeXmlText(config.title)}</title>
+            <item identifier="item_${escapedIdentifier}" identifierref="res_${escapedIdentifier}">
+                <title>${escapeXmlText(config.title)}</title>
             </item>
         </organization>
     </organizations>
     
     <resources>
-        <resource identifier="res_${identifier}" type="webcontent" adlcp:scormtype="sco" href="proxy.html">
+        <resource identifier="res_${escapedIdentifier}" type="webcontent" adlcp:scormtype="sco" href="proxy.html">
             <file href="proxy.html"/>
             <file href="scorm-bridge.js"/>
             <file href="pipwerks.js"/>
@@ -55,34 +65,41 @@ export function generateScorm12ProxyManifest(config) {
  * @returns {string} imsmanifest.xml content
  */
 export function generateScorm2004ProxyManifest(config) {
-    const identifier = config.identifier || 
-        config.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
+    const identifier = proxyIdentifier(config);
+    const escapedIdentifier = escapeXmlAttribute(identifier);
 
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!-- SCORM 2004 Proxy Manifest - Generated by CourseCode -->
-<manifest identifier="${identifier}_proxy" version="1.0"
+<manifest identifier="${escapedIdentifier}_proxy" version="1.0"
     xmlns="http://www.imsglobal.org/xsd/imscp_v1p1"
     xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_v1p3"
     xmlns:adlseq="http://www.adlnet.org/xsd/adlseq_v1p3"
     xmlns:adlnav="http://www.adlnet.org/xsd/adlnav_v1p3"
-    xmlns:imsss="http://www.imsglobal.org/xsd/imsss">
+    xmlns:imsss="http://www.imsglobal.org/xsd/imsss"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="
+      http://www.imsglobal.org/xsd/imscp_v1p1 imscp_v1p1.xsd
+      http://www.imsglobal.org/xsd/imsss imsss_v1p0.xsd
+      http://www.adlnet.org/xsd/adlcp_v1p3 adlcp_v1p3.xsd
+      http://www.adlnet.org/xsd/adlseq_v1p3 adlseq_v1p3.xsd
+      http://www.adlnet.org/xsd/adlnav_v1p3 adlnav_v1p3.xsd">
     
     <metadata>
         <schema>ADL SCORM</schema>
         <schemaversion>2004 4th Edition</schemaversion>
     </metadata>
     
-    <organizations default="org_${identifier}">
-        <organization identifier="org_${identifier}">
-            <title>${escapeXml(config.title)}</title>
-            <item identifier="item_${identifier}" identifierref="res_${identifier}">
-                <title>${escapeXml(config.title)}</title>
+    <organizations default="org_${escapedIdentifier}">
+        <organization identifier="org_${escapedIdentifier}">
+            <title>${escapeXmlText(config.title)}</title>
+            <item identifier="item_${escapedIdentifier}" identifierref="res_${escapedIdentifier}">
+                <title>${escapeXmlText(config.title)}</title>
             </item>
         </organization>
     </organizations>
     
     <resources>
-        <resource identifier="res_${identifier}" type="webcontent" adlcp:scormType="sco" href="proxy.html">
+        <resource identifier="res_${escapedIdentifier}" type="webcontent" adlcp:scormType="sco" href="proxy.html">
             <file href="proxy.html"/>
             <file href="scorm-bridge.js"/>
             <file href="pipwerks.js"/>
@@ -90,15 +107,3 @@ export function generateScorm2004ProxyManifest(config) {
     </resources>
 </manifest>`;
 }
-
-/**
- * Escape special XML characters
- */
-function escapeXml(str) {
-    return String(str)
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&apos;');
-}

package/lib/manifest/xml-utils.js

@@ -12,3 +12,13 @@ export function escapeXmlAttribute(value) {
         .replace(/"/g, '"')
         .replace(/'/g, ''');
 }
+
+/** Create a conservative ASCII XML ID (xsd:ID) from authored text. */
+export function makeXmlId(value, fallback = 'course') {
+    const normalized = String(value ?? '')
+        .trim()
+        .replace(/[^A-Za-z0-9_.-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    const candidate = normalized || fallback;
+    return /^[A-Za-z_]/.test(candidate) ? candidate : `${fallback}-${candidate}`;
+}

package/lib/narration.js

@@ -35,10 +35,10 @@ export async function narration(options = {}) {
   if (options.rebuildCache) args.push('--rebuild-cache');
   
   return new Promise((resolve, reject) => {
-    const child = spawn('node', args, {
+    const child = spawn(process.execPath, args, {
       cwd: process.cwd(),
       stdio: 'inherit',
-      shell: true
+      shell: false
     });
     
     child.on('close', (code) => {

package/lib/portable-html.js

@@ -0,0 +1,196 @@
+/**
+ * Portable HTML build support.
+ *
+ * The Vite plugin collapses generated JavaScript and CSS. The export command
+ * then embeds CourseCode's copied runtime assets and writes the final single
+ * HTML file outside the temporary build directory.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { pathToFileURL } from 'url';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+import { getMimeType, validateProject } from './project-utils.js';
+
+const PORTABLE_BUILD_PREFIX = '.coursecode-portable-build-';
+
+export function createPortableHtmlPlugin() {
+    return viteSingleFile({
+        removeViteModuleLoader: true,
+        useRecommendedBuildConfig: true
+    });
+}
+
+function runCommand(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: process.cwd(),
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+            ...options
+        });
+        child.on('error', reject);
+        child.on('close', code => {
+            if (code === 0) resolve();
+            else reject(new Error(`${command} ${args.join(' ')} failed with code ${code}`));
+        });
+    });
+}
+
+function walkFiles(rootDir) {
+    const files = [];
+    if (!fs.existsSync(rootDir)) return files;
+
+    for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+        const absolute = path.join(rootDir, entry.name);
+        if (entry.isDirectory()) files.push(...walkFiles(absolute));
+        else if (entry.isFile()) files.push(absolute);
+    }
+    return files;
+}
+
+function toDataUrl(filePath) {
+    const mimeType = getMimeType(filePath);
+    const base64 = fs.readFileSync(filePath).toString('base64');
+    return `data:${mimeType};base64,${base64}`;
+}
+
+function addAssetAliases(map, canonicalPath, dataUrl) {
+    const canonical = canonicalPath.replace(/\\/g, '/').replace(/^\.\//, '');
+    map[canonical] = dataUrl;
+}
+
+export function collectPortableAssets(buildDir) {
+    const map = {};
+    const courseAssetsDir = path.join(buildDir, 'course', 'assets');
+    for (const filePath of walkFiles(courseAssetsDir)) {
+        const canonical = path.relative(buildDir, filePath).replace(/\\/g, '/');
+        addAssetAliases(map, canonical, toDataUrl(filePath));
+    }
+
+    for (const filename of ['_gallery-manifest.json']) {
+        const filePath = path.join(buildDir, filename);
+        if (fs.existsSync(filePath)) addAssetAliases(map, filename, toDataUrl(filePath));
+    }
+    return map;
+}
+
+function replaceDirectAssetReferences(html, assetMap) {
+    const aliases = [];
+    for (const canonical of Object.keys(assetMap)) {
+        aliases.push([`./${canonical}`, assetMap[canonical]], [canonical, assetMap[canonical]]);
+        if (canonical.startsWith('course/assets/')) {
+            const relative = canonical.slice('course/assets/'.length);
+            aliases.push([`./assets/${relative}`, assetMap[canonical]], [`assets/${relative}`, assetMap[canonical]]);
+        }
+    }
+    aliases.sort((a, b) => b[0].length - a[0].length);
+
+    let result = html;
+    for (const [alias, dataUrl] of aliases) {
+        result = result.split(alias).join(dataUrl);
+    }
+    return result;
+}
+
+export function assemblePortableHtml(indexHtml, assetMap) {
+    const serializedMap = JSON.stringify(assetMap).replace(/</g, '\\u003c');
+    const bootstrap = `<script>window.__COURSECODE_PORTABLE_ASSETS__=${serializedMap};</script>`;
+    let html = replaceDirectAssetReferences(indexHtml, assetMap);
+
+    const firstModule = html.search(/<script\b[^>]*type=["']module["']/i);
+    if (firstModule >= 0) {
+        html = `${html.slice(0, firstModule)}${bootstrap}\n${html.slice(firstModule)}`;
+    } else if (html.includes('</head>')) {
+        html = html.replace('</head>', `${bootstrap}\n</head>`);
+    } else {
+        throw new Error('Portable build is missing a document head or module entry point');
+    }
+
+    return html
+        .replace(/<title([^>]*)>(.*?)<\/title>/i, '<title$1>$2</title>')
+        .replace(/<html([^>]*)>/i, '<html$1 data-coursecode-portable="true">');
+}
+
+export function validatePortableHtml(html) {
+    const problems = [];
+    if (!html.includes('data-coursecode-portable="true"')) problems.push('portable marker missing');
+    if (!html.includes('__COURSECODE_PORTABLE_ASSETS__')) problems.push('embedded asset map missing');
+    if (/<script\b[^>]+src=["'](?!data:|https?:|\/\/)/i.test(html)) problems.push('external local script remains');
+    if (/<link\b[^>]+href=["'](?!data:|https?:|\/\/|#)/i.test(html)) problems.push('external local stylesheet remains');
+    if (/\b(?:src|href|poster)=["'](?:\.\/)?course\/assets\//i.test(html)) problems.push('unembedded course asset remains');
+    if (problems.length > 0) throw new Error(`Portable HTML validation failed: ${problems.join('; ')}`);
+}
+
+function safeFilename(value) {
+    return String(value || 'course')
+        .trim()
+        .replace(/[<>:"/\\|?*]/g, '-')
+        .replace(/\s+/g, '_') || 'course';
+}
+
+async function loadCourseConfig(coursePath) {
+    const url = `${pathToFileURL(path.join(coursePath, 'course-config.js')).href}?portable=${Date.now()}`;
+    const module = await import(url);
+    return module.courseConfig || module.default || {};
+}
+
+function assertPortableBuildSupport(rootDir) {
+    const configPath = path.join(rootDir, 'vite.config.js');
+    const configSource = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '';
+    if (configSource.includes('COURSECODE_PORTABLE_HTML') && configSource.includes('COURSECODE_OUT_DIR')) return;
+
+    throw new Error(
+        'This project\'s vite.config.js predates portable HTML export. ' +
+        'Run "coursecode upgrade --configs", review the generated config backup, and try again.'
+    );
+}
+
+export async function exportPortableHtml(options = {}) {
+    const { coursePath } = validateProject();
+    const rootDir = process.cwd();
+    assertPortableBuildSupport(rootDir);
+    const config = await loadCourseConfig(coursePath);
+    const title = config.metadata?.title || 'Course';
+    const outputPath = path.resolve(options.output || `${safeFilename(title)}.html`);
+    const buildDirName = `${PORTABLE_BUILD_PREFIX}${process.pid}`;
+    const buildDir = path.join(rootDir, buildDirName);
+
+    if (fs.existsSync(buildDir)) fs.rmSync(buildDir, { recursive: true, force: true });
+
+    console.log('\n📄 Building portable HTML course...\n');
+    try {
+        const env = {
+            ...process.env,
+            COURSECODE_PORTABLE_HTML: 'true',
+            COURSECODE_OUT_DIR: buildDirName,
+            LMS_FORMAT: 'standalone'
+        };
+
+        if (options.lint === false) {
+            await runCommand('npx', ['vite', 'build'], { env });
+        } else {
+            await runCommand('npm', ['run', 'build'], { env });
+        }
+
+        const indexPath = path.join(buildDir, 'index.html');
+        if (!fs.existsSync(indexPath)) throw new Error('Portable build did not produce index.html');
+
+        const assetMap = collectPortableAssets(buildDir);
+        const html = assemblePortableHtml(fs.readFileSync(indexPath, 'utf8'), assetMap);
+        validatePortableHtml(html);
+
+        fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+        fs.writeFileSync(outputPath, html, 'utf8');
+
+        const sizeMB = fs.statSync(outputPath).size / 1024 / 1024;
+        const sizeWarning = sizeMB >= 50
+            ? '\n   ⚠ Large portable file: test sharing limits and browser startup time.'
+            : '';
+        console.log(`\n✅ Portable HTML exported\n\n   Output: ${outputPath}\n   Size: ${sizeMB.toFixed(2)} MB${sizeWarning}\n\n   Open the file directly in a modern browser; no LMS or server is required.\n`);
+        return { outputPath, sizeBytes: fs.statSync(outputPath).size, assetCount: Object.keys(assetMap).length };
+    } finally {
+        if (fs.existsSync(buildDir)) fs.rmSync(buildDir, { recursive: true, force: true });
+    }
+}

package/lib/preview-export.js

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