playable-lessons 0.6.4 → 0.8.0

package/README.md

@@ -191,6 +191,20 @@ playable-lessons export -i story.ink -o dist/ -f html,json,ink
 | `html` | Self-contained player (`.html`) — works offline, share via LMS/email |
 | `json` | Compiled Ink story JSON |
 | `ink`  | The raw Ink source (copied through) |
+| `h5p` | H5P Branching Scenario package (`.h5p`) — imports into Moodle/Canvas/Lumi |
+| `epub` | Playable EPUB 3 book (`.epub`) — each scene a chapter, each choice a link |
+| `scorm` | SCORM 1.2 package (`.zip`) — reports completion to an LMS |
+
+The desktop app also exports **Twee3/Twine** together with H5P, EPUB, and SCORM.
+H5P, EPUB, and Twee represent a decision tree, so they require a pure-branching
+story: generate with **“H5P / LMS compatible”** ticked (CLI `--style branching`).
+Stateful stories are refused with a line-level explanation rather than being
+silently flattened. SCORM wraps the full HTML player and works with either
+story style.
+
+All structural exports read the **compiled Ink JSON** (not a second regex parse
+of the source), so choice text, tags, and divert targets match exactly what the
+player executes.
 
 Run `playable-lessons --help` for all options.
 
@@ -207,6 +221,19 @@ npm run typecheck
 npm test
 ```
 
+### Updates
+
+Packaged desktop builds check GitHub Releases shortly after launch and every six
+hours, download an update in the background, and prompt to restart when it is
+ready. Updates are verified against the SHA-512 in `latest*.yml`; macOS builds
+are code-signed in CI, which Squirrel.Mac also verifies.
+
+Two caveats: versions before **0.8.0** did not contain the updater, so those
+users must install 0.8.0 manually once — every release after that updates
+itself. Windows installers are currently unsigned, so the first install may
+show a SmartScreen warning (updates still work). On Linux the app must be run
+as an AppImage for AppImage updates to apply.
+
 ### AI providers
 
 The desktop app supports **Claude**, **OpenAI**, a local **Ollama**, and any **OpenAI-compatible endpoint** (remote Ollama, OpenRouter, LiteLLM, vLLM, …) via a base URL + bearer token. Model IDs are editable, with live model listing and a connection test. API keys are stored in your OS keychain (via Electron `safeStorage`), not in plain config.
@@ -283,6 +310,24 @@ Notes for operators:
 
 ---
 
+## Security
+
+- **Desktop app:** sandboxed renderer with context isolation, cross-origin
+  navigation blocked, IPC sender + project-id validation, device permissions
+  denied, producer CSP, and API keys/GitHub tokens in the OS keychain.
+- **Web server:** Helmet security headers, constant-time access-code check,
+  typed/clamped inputs, a bounded job queue (`MAX_JOBS` / `MAX_RESULT_MB`), and
+  per-IP rate limiting. `/api/health` is public so the UI can discover whether
+  a code is required.
+- **Supply chain:** `npm audit --omit=dev` is clean and CI enforces it
+  (`.github/workflows/security.yml`), while blocking any high/critical advisory
+  in the build toolchain. The remaining moderate advisories are build-time-only
+  (`glob`/`minimatch` inside ESLint and electron-builder) and are tracked by
+  Dependabot. GitHub Actions and the build/packaging images are pinned, with Dependabot
+  and CodeQL running weekly.
+
+---
+
 ## Tech stack
 
 Electron + electron-vite · React 19 + TypeScript · Zustand · [inkjs](https://github.com/y-lohse/inkjs) (Ink compiler + runtime) · @xyflow/react (graph editor) · yargs (CLI) · Express (self-hosted server).

package/out/cli/index.js

@@ -18,6 +18,8 @@ const aiTaskExport_js_1 = require("../shared/aiTaskExport.js");
 const caseStudyExport_js_1 = require("../shared/caseStudyExport.js");
 const planExport_js_1 = require("../shared/planExport.js");
 const h5pExporter_js_1 = require("../shared/h5pExporter.js");
+const epubExporter_js_1 = require("../shared/epubExporter.js");
+const scormExporter_js_1 = require("../shared/scormExporter.js");
 const version_generated_js_1 = require("../shared/version.generated.js");
 /** Pick a provider from the environment when --provider isn't given. */
 function resolveProviderFromEnv() {
@@ -140,7 +142,7 @@ async function readStdin() {
     return yargs
         .option('input', { alias: 'i', type: 'string', demandOption: true, describe: 'Path to .ink file' })
         .option('output', { alias: 'o', type: 'string', demandOption: true, describe: 'Output directory' })
-        .option('format', { alias: 'f', type: 'string', default: 'html', describe: 'Export format: html, ink, json, h5p (h5p requires a story with no variables/conditionals)' })
+        .option('format', { alias: 'f', type: 'string', default: 'html', describe: 'Export format(s): html, ink, json, h5p, epub, scorm (h5p/epub require a story with no variables/conditionals; scorm works with any story)' })
         .option('title', { alias: 't', type: 'string', default: 'Story', describe: 'Story title' });
 }, async (argv) => {
     try {
@@ -151,36 +153,57 @@ async function readStdin() {
         const title = argv.title;
         const baseName = (0, path_1.basename)(argv.input, '.ink');
         for (const format of formats) {
-            switch (format.trim()) {
-                case 'html': {
-                    const html = await (0, storyExport_js_1.exportStandaloneHTML)(source, title);
-                    const outPath = (0, path_1.join)(outputDir, `${baseName}.html`);
-                    await (0, promises_1.writeFile)(outPath, html);
-                    console.log(`Exported HTML: ${outPath}`);
-                    break;
-                }
-                case 'json': {
-                    const json = await (0, storyExport_js_1.compileInk)(source);
-                    const outPath = (0, path_1.join)(outputDir, `${baseName}.ink.json`);
-                    await (0, promises_1.writeFile)(outPath, json);
-                    console.log(`Exported JSON: ${outPath}`);
-                    break;
-                }
-                case 'ink': {
-                    const outPath = (0, path_1.join)(outputDir, `${baseName}.ink`);
-                    await (0, promises_1.writeFile)(outPath, source);
-                    console.log(`Exported Ink: ${outPath}`);
-                    break;
-                }
-                case 'h5p': {
-                    const bytes = (0, h5pExporter_js_1.exportH5P)(source, title);
-                    const outPath = (0, path_1.join)(outputDir, `${baseName}.h5p`);
-                    await (0, promises_1.writeFile)(outPath, Buffer.from(bytes));
-                    console.log(`Exported H5P: ${outPath}`);
-                    break;
+            try {
+                switch (format.trim()) {
+                    case 'html': {
+                        const html = await (0, storyExport_js_1.exportStandaloneHTML)(source, title);
+                        const outPath = (0, path_1.join)(outputDir, `${baseName}.html`);
+                        await (0, promises_1.writeFile)(outPath, html);
+                        console.log(`Exported HTML: ${outPath}`);
+                        break;
+                    }
+                    case 'json': {
+                        const json = await (0, storyExport_js_1.compileInk)(source);
+                        const outPath = (0, path_1.join)(outputDir, `${baseName}.ink.json`);
+                        await (0, promises_1.writeFile)(outPath, json);
+                        console.log(`Exported JSON: ${outPath}`);
+                        break;
+                    }
+                    case 'ink': {
+                        const outPath = (0, path_1.join)(outputDir, `${baseName}.ink`);
+                        await (0, promises_1.writeFile)(outPath, source);
+                        console.log(`Exported Ink: ${outPath}`);
+                        break;
+                    }
+                    case 'h5p': {
+                        const bytes = await (0, h5pExporter_js_1.exportH5P)(source, title);
+                        const outPath = (0, path_1.join)(outputDir, `${baseName}.h5p`);
+                        await (0, promises_1.writeFile)(outPath, Buffer.from(bytes));
+                        console.log(`Exported H5P: ${outPath}`);
+                        break;
+                    }
+                    case 'epub': {
+                        const bytes = await (0, epubExporter_js_1.exportEpub)(source, title);
+                        const outPath = (0, path_1.join)(outputDir, `${baseName}.epub`);
+                        await (0, promises_1.writeFile)(outPath, Buffer.from(bytes));
+                        console.log(`Exported EPUB: ${outPath}`);
+                        break;
+                    }
+                    case 'scorm': {
+                        const bytes = await (0, scormExporter_js_1.exportScorm)(source, title);
+                        const outPath = (0, path_1.join)(outputDir, `${baseName}-scorm.zip`);
+                        await (0, promises_1.writeFile)(outPath, Buffer.from(bytes));
+                        console.log(`Exported SCORM: ${outPath}`);
+                        break;
+                    }
+                    default:
+                        console.warn(`Unknown format: ${format}`);
                 }
-                default:
-                    console.warn(`Unknown format: ${format}`);
+            }
+            catch (err) {
+                // One impossible format (e.g. epub for a stateful story) should not
+                // abort the formats that can be produced.
+                console.warn(`Skipped ${format}: ${err instanceof Error ? err.message : err}`);
             }
         }
     }
@@ -213,7 +236,7 @@ async function readStdin() {
         .option('protagonist', { type: 'string', default: 'the reader', describe: 'Protagonist type' })
         .option('answers', { type: 'string', describe: 'Optional answers to clarifying questions' })
         .option('retries', { type: 'number', default: 3, describe: 'Max compile attempts, with AI-assisted fixes between them (raise for weaker local models)' })
-        .option('format', { alias: 'f', type: 'string', describe: 'Output formats. story: ink|html|json|h5p (default ink,html; h5p requires --style branching). flashcards: csv|html|anki|json (default csv,html). quiz: html|txt|json (default html,json). summary: html|txt|json (default html,txt). ai-task: html|txt|json (default html,txt). case-study: html|txt|json (default html,txt).' })
+        .option('format', { alias: 'f', type: 'string', describe: 'Output formats. story: ink|html|json|h5p|epub|scorm (default ink,html; h5p/epub require --style branching; scorm works with any story). flashcards: csv|html|anki|json (default csv,html). quiz: html|txt|json (default html,json). summary: html|txt|json (default html,txt). ai-task: html|txt|json (default html,txt). case-study: html|txt|json (default html,txt).' })
         .option('title', { alias: 't', type: 'string', describe: 'Title for the story, flashcard deck, quiz, summary, AI-task set, or case study (defaults to the input/topic name)' });
 }, async (argv) => {
     try {
@@ -497,7 +520,7 @@ async function readStdin() {
                     }
                     case 'h5p': {
                         try {
-                            const bytes = (0, h5pExporter_js_1.exportH5P)(result.inkSource, title);
+                            const bytes = await (0, h5pExporter_js_1.exportH5P)(result.inkSource, title, sceneImages);
                             const outPath = (0, path_1.join)(outputDir, `${base}.h5p`);
                             await (0, promises_1.writeFile)(outPath, Buffer.from(bytes));
                             console.log(`Wrote ${outPath}`);
@@ -507,6 +530,30 @@ async function readStdin() {
                         }
                         break;
                     }
+                    case 'epub': {
+                        try {
+                            const bytes = await (0, epubExporter_js_1.exportEpub)(result.inkSource, title, sceneImages);
+                            const outPath = (0, path_1.join)(outputDir, `${base}.epub`);
+                            await (0, promises_1.writeFile)(outPath, Buffer.from(bytes));
+                            console.log(`Wrote ${outPath}`);
+                        }
+                        catch (err) {
+                            console.warn(`Skipped epub: ${err instanceof Error ? err.message : err}`);
+                        }
+                        break;
+                    }
+                    case 'scorm': {
+                        try {
+                            const bytes = await (0, scormExporter_js_1.exportScorm)(result.inkSource, title, sceneImages);
+                            const outPath = (0, path_1.join)(outputDir, `${base}-scorm.zip`);
+                            await (0, promises_1.writeFile)(outPath, Buffer.from(bytes));
+                            console.log(`Wrote ${outPath}`);
+                        }
+                        catch (err) {
+                            console.warn(`Skipped scorm: ${err instanceof Error ? err.message : err}`);
+                        }
+                        break;
+                    }
                     default:
                         console.warn(`Unknown format: ${format}`);
                 }

package/out/shared/epubExporter.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * EPUB 3 export: a self-contained, offline "reader" edition of a
+ * pure-branching story. Each knot becomes an XHTML chapter and each choice a
+ * hyperlink, so the book is still playable in any EPUB 3 reader.
+ *
+ * Stateful stories are refused (same gate as H5P/Twee): Ink variables and
+ * conditional text cannot be evaluated by an e-reader. The graph comes from
+ * the compiled Ink JSON.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportEpub = exportEpub;
+exports.exportEpubFromCompiled = exportEpubFromCompiled;
+const storyExport_js_1 = require("./storyExport.js");
+const inkGraph_js_1 = require("./inkGraph.js");
+const h5pExporter_js_1 = require("./h5pExporter.js");
+const zip_js_1 = require("./zip.js");
+const IMAGE_EXT = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+    'image/svg+xml': 'svg'
+};
+/** Decode a `data:` URL into bytes + media type; null for anything else. */
+function decodeDataUrl(value) {
+    const match = value.match(/^data:([^;,]+);base64,(.*)$/s);
+    if (!match)
+        return null;
+    return { mediaType: match[1], bytes: (0, zip_js_1.base64ToBytes)(match[2]) };
+}
+function imageForKnot(knot, sceneImages, index, images) {
+    const source = (knot.imagePrompt && sceneImages?.[knot.imagePrompt]) ||
+        (knot.imagePath && /^data:/.test(knot.imagePath) ? knot.imagePath : null);
+    if (!source)
+        return null;
+    const decoded = decodeDataUrl(source);
+    if (!decoded)
+        return null;
+    const ext = IMAGE_EXT[decoded.mediaType];
+    if (!ext)
+        return null;
+    const image = {
+        href: `images/scene-${index}.${ext}`,
+        bytes: decoded.bytes,
+        mediaType: decoded.mediaType,
+        alt: knot.imagePrompt || knot.id.replace(/_/g, ' ')
+    };
+    images.push(image);
+    return image;
+}
+function chapterXhtml(knot, image, title, isStart) {
+    const body = [];
+    if (isStart)
+        body.push(`<h1>${(0, storyExport_js_1.escapeHtml)(title)}</h1>`);
+    if (image) {
+        body.push(`<p class="scene"><img src="${image.href}" alt="${(0, storyExport_js_1.escapeHtml)(image.alt)}"/></p>`);
+    }
+    for (const paragraph of knot.paragraphs)
+        body.push(`<p>${(0, storyExport_js_1.escapeHtml)(paragraph)}</p>`);
+    if (knot.choices.length > 0) {
+        body.push('<ul class="choices">');
+        for (const choice of knot.choices) {
+            const href = choice.target ? `${choice.target}.xhtml` : 'end.xhtml';
+            body.push(`<li><a href="${href}">${(0, storyExport_js_1.escapeHtml)(choice.text)}</a></li>`);
+        }
+        body.push('</ul>');
+    }
+    else if (knot.nextTarget) {
+        body.push(`<p class="continue"><a href="${knot.nextTarget}.xhtml">Continue &#8594;</a></p>`);
+    }
+    else {
+        body.push('<p class="end">&#8212; End of Story &#8212;</p>');
+    }
+    return `<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="en" lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>${(0, storyExport_js_1.escapeHtml)(title)}</title>
+<link rel="stylesheet" href="style.css" type="text/css"/>
+</head>
+<body>
+<section epub:type="chapter">
+${body.join('\n')}
+</section>
+</body>
+</html>
+`;
+}
+function endXhtml(title) {
+    return `<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>${(0, storyExport_js_1.escapeHtml)(title)}</title>
+<link rel="stylesheet" href="style.css" type="text/css"/>
+</head>
+<body>
+<section epub:type="chapter">
+<p class="end">&#8212; End of Story &#8212;</p>
+<p><a href="__START__.xhtml">Play again</a></p>
+</section>
+</body>
+</html>
+`;
+}
+const STYLESHEET = `body { font-family: Georgia, "Times New Roman", serif; line-height: 1.6; margin: 5%; color: #222; }
+h1 { font-size: 1.6em; margin-bottom: 1em; }
+p { margin: 0 0 1em; }
+.scene img { max-width: 100%; height: auto; display: block; margin: 0 auto 1.2em; }
+.choices { list-style: none; padding: 0; }
+.choices li { margin: 0 0 0.6em; }
+.choices a, .continue a { display: block; padding: 0.7em 1em; border: 1px solid #ccc; border-radius: 6px; text-decoration: none; color: #3b2a80; }
+.choices a:hover, .continue a:hover { background: #f3f0ff; }
+.end { text-align: center; color: #666; font-style: italic; margin-top: 2em; }
+`;
+function contentOpf(title, chapters, images, startId) {
+    const uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16).toUpperCase();
+    });
+    const modified = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const items = [
+        '<item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>',
+        '<item id="css" href="style.css" media-type="text/css"/>',
+        '<item id="end" href="end.xhtml" media-type="application/xhtml+xml"/>',
+        ...chapters.map((c) => `<item id="ch-${c.id}" href="${c.href}" media-type="application/xhtml+xml"/>`),
+        ...images.map((img, i) => `<item id="img-${i}" href="${img.href}" media-type="${img.mediaType}"/>`)
+    ];
+    const spine = [
+        `<itemref idref="ch-${startId}"/>`,
+        ...chapters
+            .filter((c) => c.id !== startId)
+            .map((c) => `<itemref idref="ch-${c.id}" linear="no"/>`),
+        '<itemref idref="end" linear="no"/>'
+    ];
+    return `<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="bookid" xml:lang="en">
+<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+<dc:identifier id="bookid">urn:uuid:${uuid}</dc:identifier>
+<dc:title>${(0, storyExport_js_1.escapeHtml)(title)}</dc:title>
+<dc:language>en</dc:language>
+<meta property="dcterms:modified">${modified}</meta>
+</metadata>
+<manifest>
+${items.join('\n')}
+</manifest>
+<spine>
+${spine.join('\n')}
+</spine>
+</package>
+`;
+}
+function navXhtml(title, startId) {
+    return `<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="en" lang="en">
+<head><meta charset="utf-8"/><title>${(0, storyExport_js_1.escapeHtml)(title)}</title></head>
+<body>
+<nav epub:type="toc" id="toc">
+<h1>${(0, storyExport_js_1.escapeHtml)(title)}</h1>
+<ol><li><a href="${startId}.xhtml">Start</a></li></ol>
+</nav>
+<nav epub:type="landmarks" hidden="hidden">
+<ol><li><a epub:type="bodymatter" href="${startId}.xhtml">Start</a></li></ol>
+</nav>
+</body>
+</html>
+`;
+}
+const CONTAINER_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+<rootfiles>
+<rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
+</rootfiles>
+</container>
+`;
+function buildPackage(graph, title, sceneImages) {
+    if (graph.knots.length === 0)
+        throw new Error('No knots found in the Ink source — nothing to export.');
+    const startId = graph.start && graph.knots.some((k) => k.id === graph.start)
+        ? graph.start
+        : graph.knots[0].id;
+    const knots = [
+        ...graph.knots.filter((k) => k.id === startId),
+        ...graph.knots.filter((k) => k.id !== startId)
+    ];
+    const images = [];
+    const entries = [
+        { name: 'mimetype', data: 'application/epub+zip' },
+        { name: 'META-INF/container.xml', data: CONTAINER_XML },
+        { name: 'OEBPS/style.css', data: STYLESHEET },
+        { name: 'OEBPS/nav.xhtml', data: navXhtml(title, startId) },
+        { name: 'OEBPS/end.xhtml', data: endXhtml(title).replace(/__START__/g, startId) }
+    ];
+    knots.forEach((knot, i) => {
+        const image = imageForKnot(knot, sceneImages, i, images);
+        entries.push({
+            name: `OEBPS/${knot.id}.xhtml`,
+            data: chapterXhtml(knot, image, title, knot.id === startId)
+        });
+    });
+    for (const image of images) {
+        entries.push({ name: `OEBPS/${image.href}`, data: image.bytes });
+    }
+    entries.push({
+        name: 'OEBPS/content.opf',
+        data: contentOpf(title, graph.knots.map((k) => ({ id: k.id, href: `${k.id}.xhtml` })), images, startId)
+    });
+    return (0, zip_js_1.zipStore)(entries);
+}
+/**
+ * Build an EPUB 3 package from a pure-branching story. Throws with a
+ * construct-by-construct explanation when the story uses state.
+ */
+async function exportEpub(inkSource, title, sceneImages) {
+    const issues = (0, h5pExporter_js_1.findStateConstructs)(inkSource);
+    if (issues.length > 0)
+        throw new Error((0, h5pExporter_js_1.describeStateConstructs)(issues, 'EPUB 3 readers'));
+    const graph = (0, inkGraph_js_1.parseCompiledInk)(await (0, storyExport_js_1.compileInk)(inkSource));
+    return buildPackage(graph, title, sceneImages);
+}
+/** Same as `exportEpub` when the caller already has compiled JSON. */
+function exportEpubFromCompiled(compiledJson, title, sceneImages) {
+    return buildPackage((0, inkGraph_js_1.parseCompiledInk)(compiledJson), title, sceneImages);
+}