coursecode 0.1.47 → 0.1.49

package/README.md

@@ -6,6 +6,16 @@ CourseCode creates real project files you can inspect, version, and edit directl
 
 Bring your own PDFs, Word docs, or PowerPoints, use AI to accelerate authoring, and deploy to any LMS format without vendor lock-in or subscriptions.
 
+## View the demo
+
+- [View the live CourseCode demo course](https://preview.coursecodecloud.com/preview/coursecode-demo/nTfJU2qvp23P0mguxrrGFZr4FlXfM03N)
+
+## Explore the ecosystem
+
+- [Build SCORM courses with the framework](https://coursecodeframework.com/scorm/)
+- [Use CourseCode Desktop if you prefer a GUI](https://coursecodedesktop.com/scorm/)
+- [Use CourseCode Cloud for hosted delivery](https://coursecodecloud.com)
+
 ## Features
 
 - **MCP integration**: Works with Claude Code, Codex, Cursor, CourseCode Desktop, and any MCP-capable AI tool — previews, screenshots, linting, and testing without manual file sharing

package/lib/create.js

@@ -10,6 +10,44 @@ import { spawn } from 'child_process';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.join(__dirname, '..');
 
+export function toProjectDirectoryName(name) {
+  return String(name || '')
+    .trim()
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/['’]/g, '')
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+function escapeSingleQuotedValue(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+export function stampCourseTitle(configContent, title) {
+  const titleValue = escapeSingleQuotedValue(title);
+  let nextContent = configContent.replace(
+    /^(\s*)title\s*:\s*['"`][^'"`]*['"`](\s*,?)/m,
+    `$1title: '${titleValue}'$2`
+  );
+
+  nextContent = nextContent.replace(
+    /^(\s*)courseTitle\s*:\s*['"`][^'"`]*['"`](\s*,?)/m,
+    `$1courseTitle: '${titleValue}'$2`
+  );
+
+  return nextContent;
+}
+
+function writeCourseTitle(projectDir, title) {
+  const configPath = path.join(projectDir, 'course', 'course-config.js');
+  if (!fs.existsSync(configPath)) return;
+
+  const current = fs.readFileSync(configPath, 'utf-8');
+  fs.writeFileSync(configPath, stampCourseTitle(current, title), 'utf-8');
+}
+
 /**
  * Copy directory recursively
  */
@@ -85,15 +123,31 @@ function gitInit(cwd) {
 }
 
 export async function create(name, options = {}) {
-  const targetDir = path.resolve(process.cwd(), name);
+  const displayName = String(name || '').trim();
+  const directoryName = toProjectDirectoryName(displayName);
+
+  if (!displayName) {
+    console.error('\n❌ Course name is required.\n');
+    process.exit(1);
+  }
+
+  if (!directoryName) {
+    console.error('\n❌ Course name must include letters or numbers.\n');
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(process.cwd(), directoryName);
 
   // Check if directory already exists
   if (fs.existsSync(targetDir)) {
-    console.error(`\n❌ Directory "${name}" already exists.\n`);
+    console.error(`\n❌ Directory "${directoryName}" already exists.\n`);
     process.exit(1);
   }
 
-  console.log(`\n🚀 Creating CourseCode project: ${name}\n`);
+  console.log(`\n🚀 Creating CourseCode project: ${displayName}\n`);
+  if (directoryName !== displayName) {
+    console.log(`   Project folder: ${directoryName}`);
+  }
 
   // Create project directory
   fs.mkdirSync(targetDir, { recursive: true });
@@ -138,7 +192,7 @@ export async function create(name, options = {}) {
   // Read and customize package.json
   const pkgPath = path.join(targetDir, 'package.json');
   const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  pkg.name = name;
+  pkg.name = directoryName;
   fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
 
   // Create .coursecoderc.json to track framework version
@@ -161,6 +215,8 @@ export async function create(name, options = {}) {
     clean({ basePath: targetDir });
   }
 
+  writeCourseTitle(targetDir, displayName);
+
   // Install dependencies
   if (options.install !== false) {
     console.log('\n   Installing dependencies...\n');
@@ -184,7 +240,7 @@ export async function create(name, options = {}) {
   // Print success message
   if (options.blank) {
     console.log(`
-✅ CourseCode project "${name}" created (blank starter)!
+✅ CourseCode project "${displayName}" created (blank starter)!
 
    Course files:
    - course/course-config.js  - Course metadata & structure (minimal)
@@ -199,7 +255,7 @@ export async function create(name, options = {}) {
 `);
   } else {
     console.log(`
-✅ CourseCode project "${name}" created successfully!
+✅ CourseCode project "${displayName}" created successfully!
 
    Course files:
    - course/course-config.js  - Course metadata & structure
@@ -228,9 +284,15 @@ export async function create(name, options = {}) {
 
     child.on('error', () => {
       console.warn('   ⚠️  Failed to start dev server. Run manually:');
-      console.log(`      cd ${name} && coursecode dev\n`);
+      console.log(`      cd ${directoryName} && coursecode dev\n`);
     });
   } else {
-    console.log(`\n   To start developing:\n\n      cd ${name}\n      coursecode dev\n`);
+    console.log(`\n   To start developing:\n\n      cd ${directoryName}\n      coursecode dev\n`);
   }
+
+  return {
+    displayName,
+    directoryName,
+    targetDir
+  };
 }

package/lib/import.js

@@ -179,9 +179,9 @@ export async function importPresentation(source, options = {}) {
 
     // Create blank project (no example slides — they'd just be deleted)
     console.log('   ⏳ Creating course project...\n');
-    await create(name, { blank: true, install: options.install });
+    const createdProject = await create(name, { blank: true, install: options.install });
 
-    const targetDir = path.resolve(process.cwd(), name);
+    const targetDir = createdProject?.targetDir || path.resolve(process.cwd(), name);
     const courseDir = path.join(targetDir, 'course');
 
     // Import presentation in-place

package/lib/stub-player/app-viewer.js

@@ -20,6 +20,9 @@ import { createLoginHandlers } from './login-screen.js';
 const config = window.STUB_CONFIG || {};
 const LAUNCH_URL = config.launchUrl || '/';
 const START_SLIDE = config.startSlide || null;
+const QUERY = new URLSearchParams(window.location.search);
+const SHOW_HEADER = resolveShowHeader();
+const INITIAL_SKIP_GATING = resolveInitialSkipGating();
 
 // State
 let isInitialized = false;
@@ -44,27 +47,38 @@ function init() {
         ? createContentViewerHandlers({ initialContent: config.courseContent || null })
         : null;
 
+    document.body.classList.toggle('stub-player-header-hidden', !SHOW_HEADER);
+
     // Header Bar — viewer mode: Review + More menu (skip gating, reset)
-    createHeaderBarHandlers({
-        onToggle: () => {},
-        onContent: () => {
-            if (contentPanel) {
-                contentPanel.classList.toggle('visible');
-                if (contentPanel.classList.contains('visible') && !contentLoaded && contentHandlers) {
-                    contentHandlers.loadContent();
-                    contentLoaded = true;
+    if (SHOW_HEADER) {
+        createHeaderBarHandlers({
+            onToggle: () => {},
+            onContent: () => {
+                if (contentPanel) {
+                    contentPanel.classList.toggle('visible');
+                    if (contentPanel.classList.contains('visible') && !contentLoaded && contentHandlers) {
+                        contentHandlers.loadContent();
+                        contentLoaded = true;
+                    }
                 }
-            }
-        },
-        onReset: () => doReset(),
-        onSkipGating: (enabled) => {
-            if (enabled) {
-                loadCourse();
-            } else {
-                doReset();
-            }
+            },
+            onReset: () => doReset(),
+            onSkipGating: (enabled) => {
+                if (enabled) {
+                    loadCourse();
+                } else {
+                    doReset();
+                }
+            },
+            initialSkipGating: INITIAL_SKIP_GATING
+        });
+    } else if (INITIAL_SKIP_GATING !== null) {
+        try {
+            localStorage.setItem('coursecode-skipGating', INITIAL_SKIP_GATING ? 'true' : 'false');
+        } catch {
+            // ignore storage failures
         }
-    });
+    }
 
     // Load course if no login screen active
     if (!document.getElementById('stub-player-login-screen')?.classList.contains('visible')) {
@@ -75,13 +89,39 @@ function init() {
     setupOutsideClickListener(contentPanel);
 }
 
+function resolveShowHeader() {
+    const previewHeader = QUERY.get('previewHeader');
+    if (previewHeader === 'hidden') return false;
+    if (previewHeader === 'visible') return true;
+
+    const hideHeader = resolveBooleanQuery('hideHeader');
+    if (hideHeader !== null) return !hideHeader;
+
+    return config.showHeader !== false;
+}
+
+function resolveInitialSkipGating() {
+    const querySkipGating = resolveBooleanQuery('skipGating');
+    if (querySkipGating !== null) return querySkipGating;
+    return typeof config.skipGating === 'boolean' ? config.skipGating : null;
+}
+
+function resolveBooleanQuery(name) {
+    const value = QUERY.get(name);
+    if (value === null) return null;
+    const normalized = value.toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+    return null;
+}
+
 // =============================================================================
 // COURSE LOADING & NAVIGATION
 // =============================================================================
 
 function loadCourse() {
     const frame = document.getElementById('stub-player-course-frame');
-    const skipGating = document.getElementById('stub-player-skip-gating')?.checked;
+    const skipGating = resolveSkipGating();
     let url = LAUNCH_URL;
     if (skipGating) url += (url.includes('?') ? '&' : '?') + 'skipGating=true';
     frame.src = url;
@@ -99,7 +139,7 @@ function handleFrameLoad() {
         win.cmi5 = window.cmi5;
         win.lti = window.lti;
 
-        if (document.getElementById('stub-player-skip-gating')?.checked) {
+        if (resolveSkipGating()) {
             win.__SCORM_PREVIEW_SKIP_GATING = true;
         }
 
@@ -115,6 +155,11 @@ function handleFrameLoad() {
     }
 }
 
+function resolveSkipGating() {
+    if (INITIAL_SKIP_GATING !== null) return INITIAL_SKIP_GATING;
+    return document.getElementById('stub-player-skip-gating')?.checked === true;
+}
+
 function navigateToSlide(contentWindow, slideIdOrIndex) {
     const maxAttempts = 50;
     let attempts = 0;
@@ -158,10 +203,13 @@ function resolveSlideId(contentWindow, slideIdOrIndex) {
 // =============================================================================
 
 function doReset() {
-    // Static/cloud export: clear LMS localStorage and reload (no server route)
-    const storageKey = config.storageKey;
-    if (storageKey) {
-        try { localStorage.removeItem(storageKey); } catch { /* ignore */ }
+    // Viewer previews share an origin between the stub player and course iframe.
+    // Match the local /__reset route by clearing course/framework progress too.
+    let skipGating = null;
+    try { skipGating = localStorage.getItem('coursecode-skipGating'); } catch { /* ignore */ }
+    try { localStorage.clear(); } catch { /* ignore */ }
+    if (skipGating !== null) {
+        try { localStorage.setItem('coursecode-skipGating', skipGating); } catch { /* ignore */ }
     }
     window.location.reload();
 }

package/lib/stub-player/header-bar.js

@@ -102,9 +102,10 @@ export function generateHeaderBar({ isLive, hasContent }) {
  * @param {Function} callbacks.onReset - () => void
  * @param {Function} callbacks.onSkipGating - (enabled) => void
  * @param {Function} callbacks.onStatus - () => void
+ * @param {boolean|null} callbacks.initialSkipGating - query/config override for skip-gating state
  */
 export function createHeaderBarHandlers(callbacks) {
-    const { onToggle, onDebug, onConfig, onContent, onInteract, onCatalog, onEdit, onReset, onSkipGating, onStatus } = callbacks;
+    const { onToggle, onDebug, onConfig, onContent, onInteract, onCatalog, onEdit, onReset, onSkipGating, onStatus, initialSkipGating = null } = callbacks;
     const closeMoreMenu = () => {
         document.getElementById('stub-player-more-menu')?.classList.remove('visible');
     };
@@ -211,6 +212,7 @@ export function createHeaderBarHandlers(callbacks) {
     if (skipGatingCheckbox) {
         // Restore persisted state (defaults to true / skip on)
         const persistedSkip = (() => {
+            if (initialSkipGating !== null) return initialSkipGating;
             try {
                 const stored = localStorage.getItem(SKIP_GATING_STORAGE_KEY);
                 return stored !== 'false';

package/lib/stub-player/styles/_header-bar.css

@@ -333,6 +333,15 @@
             height: 100%;
         }
 
+        body.stub-player-header-hidden #stub-player-header {
+            display: none;
+        }
+
+        body.stub-player-header-hidden #stub-player-course-frame {
+            top: 0;
+            height: 100%;
+        }
+
         /* Responsive: icon-only mode on narrow viewports */
         @media (max-width: 820px) {
             #stub-player-header .btn-label {

package/lib/stub-player.d.ts

@@ -7,6 +7,8 @@ export interface StubPlayerConfig {
   liveReload?: boolean
   courseContent?: string
   startSlide?: string | number
+  showHeader?: boolean
+  skipGating?: boolean | null
   isDesktop?: boolean
   moduleBasePath?: string
 }

package/lib/stub-player.js

@@ -53,12 +53,15 @@ export { escapeHtml };
  * @param {boolean} [config.liveReload] - True to enable live reload via SSE
  * @param {string} [config.courseContent] - Markdown/HTML content for the content viewer
  * @param {string|number} [config.startSlide] - Slide ID or index to navigate to on load
+ * @param {boolean} [config.showHeader] - False to hide the preview player header
+ * @param {boolean} [config.skipGating] - True to bypass navigation locks
  * @returns {string} - Complete HTML for the player page
  */
 export function generateStubPlayer(config) {
-    const { title, launchUrl, storageKey, passwordHash, isLive, liveReload, courseContent, startSlide, isDesktop, moduleBasePath = '/__stub-player' } = config;
+    const { title, launchUrl, storageKey, passwordHash, isLive, liveReload, courseContent, startSlide, isDesktop, showHeader = true, skipGating = null, moduleBasePath = '/__stub-player' } = config;
     const hasPassword = !!passwordHash;
     const hasContent = !!courseContent;
+    const headerVisible = showHeader !== false;
 
     const stubPlayerStyles = loadStyles(isLive);
 
@@ -73,7 +76,7 @@ export function generateStubPlayer(config) {
 ${stubPlayerStyles}
     </style>
 </head>
-<body>
+<body class="${headerVisible ? '' : 'stub-player-header-hidden'}">
     ${hasPassword ? generateLoginScreen({ title: escapeHtml(title) }) : ''}
     
     <iframe id="stub-player-course-frame" name="stub-player-course-frame"></iframe>
@@ -109,6 +112,8 @@ ${stubPlayerStyles}
         liveReload: ${liveReload || false},
         startSlide: ${startSlide !== undefined ? JSON.stringify(startSlide) : 'null'},
         courseContent: ${hasContent ? JSON.stringify(courseContent) : 'null'},
+        showHeader: ${headerVisible},
+        skipGating: ${typeof skipGating === 'boolean' ? skipGating : 'null'},
         isDesktop: ${isDesktop || false},
         isCI: ${!!process.env.CI}
     };

package/package.json

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