playable-lessons 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 michael-borck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/out/cli/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("yargs/helpers");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const storyExport_js_1 = require("../shared/storyExport.js");
+(0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
+    .scriptName('playable-lessons')
+    .usage('$0 <command> [options]')
+    .command('validate', 'Validate an Ink source file', (yargs) => {
+    return yargs.option('input', { alias: 'i', type: 'string', demandOption: true, describe: 'Path to .ink file' });
+}, async (argv) => {
+    try {
+        const source = await (0, promises_1.readFile)(argv.input, 'utf-8');
+        await (0, storyExport_js_1.compileInk)(source);
+        console.log('Valid! Story compiled successfully.');
+    }
+    catch (err) {
+        console.error('Validation failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+})
+    .command('export', 'Export an Ink file to another format', (yargs) => {
+    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' })
+        .option('title', { alias: 't', type: 'string', default: 'Story', describe: 'Story title' });
+}, async (argv) => {
+    try {
+        const source = await (0, promises_1.readFile)(argv.input, 'utf-8');
+        const outputDir = argv.output;
+        await (0, promises_1.mkdir)(outputDir, { recursive: true });
+        const formats = argv.format.split(',');
+        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;
+                }
+                default:
+                    console.warn(`Unknown format: ${format}`);
+            }
+        }
+    }
+    catch (err) {
+        console.error('Export failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+})
+    .demandCommand(1, 'You must specify a command')
+    .help()
+    .version('0.1.0')
+    .parse();

package/out/shared/storyExport.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Shared, dependency-light story logic used by BOTH the renderer (via Vite)
+ * and the CLI (via tsc/NodeNext). Keep this file self-contained — it must not
+ * import other local modules, so it resolves cleanly under both bundler and
+ * NodeNext module resolution.
+ *
+ * Only side dependency is a dynamic import of inkjs's Compiler.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeHtml = escapeHtml;
+exports.ensureStartDivert = ensureStartDivert;
+exports.compileInk = compileInk;
+exports.exportStandaloneHTML = exportStandaloneHTML;
+// inkjs runtime loaded by exported HTML. Pin to the same major/minor the app
+// compiles with (see package.json `inkjs`) so the compiled JSON format matches
+// the runtime that plays it, and lock it down with a Subresource Integrity hash.
+const INKJS_RUNTIME_URL = 'https://cdn.jsdelivr.net/npm/inkjs@2.4.0/dist/ink.js';
+const INKJS_RUNTIME_SRI = 'sha384-wR7zU2DW6Ji/8kGVhTaLk0TSOucJhD4Zhv7lR5G1k/HoXtcWhEw5nIlcyE/+GtMb';
+/**
+ * Escape a string for safe interpolation into HTML text or double-quoted
+ * attribute values. Escapes &, <, >, ", and ' (the single quote matters for
+ * single-quoted attributes and is cheap to include).
+ */
+function escapeHtml(text) {
+    return String(text)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Ensures the Ink source has a top-level divert to the first knot.
+ * Without this, the story starts at the root and immediately ends.
+ */
+function ensureStartDivert(source) {
+    const trimmed = source.trim();
+    // Check if there's already a top-level divert before the first knot
+    const firstKnotIndex = trimmed.search(/^===\s*\w+\s*===/m);
+    if (firstKnotIndex === -1)
+        return source; // no knots at all
+    const beforeFirstKnot = trimmed.substring(0, firstKnotIndex);
+    if (/^->\s*\w+/m.test(beforeFirstKnot))
+        return source; // already has a divert
+    // Find the name of the first knot
+    const knotMatch = trimmed.match(/^===\s*(\w+)\s*===/m);
+    if (!knotMatch)
+        return source;
+    const firstKnotName = knotMatch[1];
+    // Insert a divert just before the first knot
+    return trimmed.substring(0, firstKnotIndex) + `-> ${firstKnotName}\n` + trimmed.substring(firstKnotIndex);
+}
+/**
+ * Compiles Ink source to JSON using inkjs's Compiler.
+ * Returns the compiled JSON string.
+ */
+async function compileInk(inkSource) {
+    const { Compiler } = await import('inkjs/compiler/Compiler');
+    const source = ensureStartDivert(inkSource);
+    const compiler = new Compiler(source);
+    const story = compiler.Compile();
+    if (!story) {
+        throw new Error('Ink compilation failed: no story produced');
+    }
+    const json = story.ToJson();
+    if (!json) {
+        throw new Error('Ink compilation failed: could not serialize to JSON');
+    }
+    return json;
+}
+/**
+ * Exports a standalone HTML file that plays the story.
+ * The inkjs runtime is loaded from a pinned CDN URL (with SRI) in the export.
+ *
+ * NOTE: all interpolated values are escaped — `title` is user/AI supplied and
+ * the compiled JSON is embedded via JSON.stringify (which is safe inside a
+ * <script> body as it cannot contain an unescaped `</script>` sequence for
+ * ordinary story text).
+ */
+async function exportStandaloneHTML(inkSource, title) {
+    const compiledJson = await compileInk(inkSource);
+    const escapedJson = JSON.stringify(compiledJson);
+    const safeTitle = escapeHtml(title);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${safeTitle} — Playable Lessons</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: Georgia, 'Times New Roman', serif;
+    background: #1a1a2e;
+    color: #e0e0e0;
+    min-height: 100vh;
+    display: flex;
+    justify-content: center;
+    padding: 40px 20px;
+  }
+  #story { max-width: 650px; width: 100%; }
+  h1 { font-size: 28px; margin-bottom: 32px; color: #a78bfa; text-align: center; }
+  .text p { font-size: 18px; line-height: 1.8; margin-bottom: 16px; }
+  .choices { display: flex; flex-direction: column; gap: 10px; margin-top: 24px; }
+  .choice {
+    padding: 14px 20px;
+    background: #252547;
+    border: 1px solid #3a3a5c;
+    border-radius: 8px;
+    color: #e0e0e0;
+    cursor: pointer;
+    font-size: 16px;
+    font-family: inherit;
+    text-align: left;
+    transition: all 0.15s;
+  }
+  .choice:hover { border-color: #a78bfa; background: rgba(167, 139, 250, 0.1); }
+  .ending { text-align: center; padding: 32px; color: #888; font-style: italic; font-size: 18px; }
+  .restart {
+    display: block;
+    margin: 24px auto;
+    padding: 12px 28px;
+    background: #a78bfa;
+    color: white;
+    border: none;
+    border-radius: 8px;
+    font-size: 16px;
+    cursor: pointer;
+    font-family: inherit;
+  }
+  .restart:hover { background: #8b6fdf; }
+  .meta { text-align: center; color: #555; font-size: 12px; margin-top: 48px; }
+</style>
+</head>
+<body>
+<div id="story">
+  <h1>${safeTitle}</h1>
+  <div id="content"></div>
+</div>
+
+<script src="${INKJS_RUNTIME_URL}" integrity="${INKJS_RUNTIME_SRI}" crossorigin="anonymous"></script>
+<script>
+(function() {
+  var storyJson = ${escapedJson};
+  var story = new inkjs.Story(storyJson);
+  var content = document.getElementById('content');
+
+  function continueStory() {
+    var textDiv = document.createElement('div');
+    textDiv.className = 'text';
+    while (story.canContinue) {
+      var line = story.Continue().trim();
+      if (line) {
+        var p = document.createElement('p');
+        p.textContent = line;
+        textDiv.appendChild(p);
+      }
+    }
+    content.appendChild(textDiv);
+
+    if (story.currentChoices.length > 0) {
+      var choicesDiv = document.createElement('div');
+      choicesDiv.className = 'choices';
+      story.currentChoices.forEach(function(choice, i) {
+        var btn = document.createElement('button');
+        btn.className = 'choice';
+        btn.textContent = choice.text;
+        btn.addEventListener('click', function() {
+          choicesDiv.remove();
+          story.ChooseChoiceIndex(i);
+          continueStory();
+        });
+        choicesDiv.appendChild(btn);
+      });
+      content.appendChild(choicesDiv);
+    }
+
+    if (!story.canContinue && story.currentChoices.length === 0) {
+      var endDiv = document.createElement('div');
+      endDiv.className = 'ending';
+      endDiv.textContent = '\\u2014 End of Story \\u2014';
+      content.appendChild(endDiv);
+      var restartBtn = document.createElement('button');
+      restartBtn.className = 'restart';
+      restartBtn.textContent = 'Play Again';
+      restartBtn.addEventListener('click', function() { location.reload(); });
+      content.appendChild(restartBtn);
+    }
+
+    window.scrollTo({ top: document.body.scrollHeight, behavior: 'smooth' });
+  }
+
+  continueStory();
+
+  var meta = document.createElement('div');
+  meta.className = 'meta';
+  meta.textContent = 'Created with Playable Lessons';
+  document.getElementById('story').appendChild(meta);
+})();
+</script>
+</body>
+</html>`;
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "playable-lessons",
+  "version": "0.1.0",
+  "description": "Interactive Fiction Authoring Tool for Education — Generate playable branching stories from source material using AI + Ink",
+  "main": "./out/main/index.mjs",
+  "scripts": {
+    "dev": "electron-vite dev",
+    "build": "electron-vite build",
+    "preview": "electron-vite preview",
+    "start": "electron-vite preview",
+    "postinstall": "electron-builder install-app-deps || true",
+    "build:unpack": "npm run build && electron-builder --dir",
+    "build:win": "npm run build && electron-builder --win",
+    "build:mac": "npm run build && electron-builder --mac",
+    "build:linux": "npm run build && electron-builder --linux",
+    "typecheck:node": "tsc --noEmit -p tsconfig.node.json",
+    "typecheck:web": "tsc --noEmit -p tsconfig.web.json",
+    "typecheck": "npm run typecheck:node && npm run typecheck:web",
+    "lint": "eslint . --ext .ts,.tsx",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "prepublishOnly": "npm run build:cli",
+    "cli": "npx tsx src/cli/index.ts"
+  },
+  "bin": {
+    "playable-lessons": "./out/cli/index.js"
+  },
+  "files": [
+    "out/cli/",
+    "out/shared/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "interactive-fiction",
+    "education",
+    "ink",
+    "electron",
+    "storytelling",
+    "narrative",
+    "authoring",
+    "cli"
+  ],
+  "author": "michael-borck",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/michael-borck/playable-lessons.git"
+  },
+  "homepage": "https://github.com/michael-borck/playable-lessons",
+  "dependencies": {
+    "@xyflow/react": "^12.10.2",
+    "inkjs": "^2.4.0",
+    "jszip": "^3.10.1",
+    "marked": "^17.0.5",
+    "openai": "^6.33.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "yargs": "^18.0.0",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/yargs": "^17.0.35",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "@vitejs/plugin-react": "^6.0.1",
+    "electron": "^41.1.0",
+    "electron-builder": "^26.8.1",
+    "electron-vite": "^5.0.0",
+    "eslint": "^10.1.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.8"
+  }
+}