playable-lessons 0.2.2 → 0.6.2

package/out/shared/h5pExporter.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * H5P export: convert a pure-branching Ink story into an H5P Branching
+ * Scenario package (.h5p).
+ *
+ * H5P's Branching Scenario is a decision tree — it has no variables and no
+ * conditional logic, so only stories with no state can be converted
+ * faithfully. `findStateConstructs` detects state so callers can refuse (with
+ * a useful message) rather than silently flatten; `exportH5P` throws on
+ * stateful sources for the same reason.
+ *
+ * The package is "content-only": it declares its library dependencies in
+ * h5p.json but does not bundle the libraries themselves. It imports into any
+ * host that already has Branching Scenario installed (an LMS with H5P, Lumi
+ * via the H5P Hub). Targets H5P.BranchingScenario 1.x semantics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findStateConstructs = findStateConstructs;
+exports.describeStateConstructs = describeStateConstructs;
+exports.toBranchingScenarioContent = toBranchingScenarioContent;
+exports.exportH5P = exportH5P;
+exports.bytesToBase64 = bytesToBase64;
+const inkParser_js_1 = require("./inkParser.js");
+const storyExport_js_1 = require("./storyExport.js");
+/**
+ * Scan Ink source for constructs Branching Scenario cannot represent:
+ * VAR declarations, ~ assignments/expressions, and any { ... } logic
+ * (conditional blocks, inline conditionals, alternatives, choice conditions).
+ * Tag lines (# ...) are ignored.
+ */
+function findStateConstructs(source) {
+    const issues = [];
+    const lines = source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('//'))
+            continue;
+        const push = (kind) => issues.push({ line: i + 1, kind, snippet: trimmed.slice(0, 80) });
+        if (/^VAR\s+\w+\s*=/.test(trimmed)) {
+            push('variable declaration');
+        }
+        else if (trimmed.startsWith('~')) {
+            push('variable assignment');
+        }
+        else if (/[{}]/.test(trimmed)) {
+            push('conditional logic');
+        }
+    }
+    return issues;
+}
+/** One-line human summary of why a story can't convert, for error messages. */
+function describeStateConstructs(issues) {
+    const shown = issues
+        .slice(0, 5)
+        .map((c) => `  line ${c.line} (${c.kind}): ${c.snippet}`)
+        .join('\n');
+    const more = issues.length > 5 ? `\n  …and ${issues.length - 5} more` : '';
+    return (`This story uses state that H5P Branching Scenario cannot represent:\n${shown}${more}\n` +
+        `Regenerate the story with "H5P / LMS compatible" enabled to get a convertible version.`);
+}
+// ─── Ink graph → Branching Scenario content ──────────────────────────────────
+/** Divert targets that mean "the story ends here". */
+const END_TARGETS = new Set(['END', 'DONE']);
+/**
+ * The passage prose shown for a knot: lines up to the first choice, minus
+ * structural lines (tags, diverts, stitch markers). Returned as escaped HTML
+ * paragraphs.
+ */
+function passageHtml(knot) {
+    const paragraphs = [];
+    for (const raw of knot.rawContent.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (line.startsWith('*') || line.startsWith('+'))
+            break; // choices begin
+        if (line.startsWith('#') || line.startsWith('->') || line.startsWith('='))
+            continue;
+        paragraphs.push(`<p>${(0, storyExport_js_1.escapeHtml)(line)}</p>`);
+    }
+    return paragraphs.join('\n') || '<p></p>';
+}
+/** The knot's plain divert target (first `-> target` outside a choice), if any. */
+function plainDivertTarget(knot) {
+    for (const raw of knot.rawContent.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('*') || line.startsWith('+'))
+            break; // choice diverts don't count
+        const m = line.match(/^->\s*(\w+)/);
+        if (m)
+            return m[1];
+    }
+    return null;
+}
+/** Deterministic uuid-shaped subContentId (H5P requires the uuid format). */
+function subContentId(n) {
+    const hex = n.toString(16).padStart(12, '0');
+    return `00000000-0000-4000-8000-${hex}`;
+}
+/**
+ * Build the Branching Scenario content.json object from Ink source.
+ * Throws if the story uses state (variables/conditionals).
+ *
+ * Mapping: each knot becomes one screen. A knot with choices becomes a
+ * Branching Question (passage prose as the question, choices as alternatives);
+ * a knot without choices becomes a text screen whose "proceed" follows the
+ * knot's divert. Diverts to END/DONE (or nowhere) go to the end screen (-1).
+ */
+function toBranchingScenarioContent(source, title) {
+    const issues = findStateConstructs(source);
+    if (issues.length > 0) {
+        throw new Error(describeStateConstructs(issues));
+    }
+    const parsed = (0, inkParser_js_1.parseInkSource)(source);
+    if (parsed.knots.length === 0) {
+        throw new Error('No knots found in the Ink source — nothing to export.');
+    }
+    // Order knots start-first: content[0] is where Branching Scenario begins.
+    const startId = parsed.topLevelDivert && parsed.knots.some((k) => k.id === parsed.topLevelDivert)
+        ? parsed.topLevelDivert
+        : parsed.knots[0].id;
+    const knots = [
+        ...parsed.knots.filter((k) => k.id === startId),
+        ...parsed.knots.filter((k) => k.id !== startId)
+    ];
+    const idOf = new Map();
+    knots.forEach((k, i) => idOf.set(k.id, i));
+    const resolve = (target) => {
+        if (!target || END_TARGETS.has(target))
+            return -1;
+        return idOf.get(target) ?? -1;
+    };
+    const content = knots.map((knot, i) => {
+        const common = {
+            contentBehaviour: 'useBehavioural',
+            forceContentFinished: 'useBehavioural',
+            showContentTitle: false,
+            feedback: { subtitle: '' },
+            contentId: i
+        };
+        if (knot.choices.length > 0) {
+            const alternatives = knot.choices.map((c) => ({
+                text: c.text,
+                nextContentId: resolve(c.target),
+                addFeedback: false,
+                feedback: { title: '', subtitle: '' }
+            }));
+            return {
+                ...common,
+                type: {
+                    library: 'H5P.BranchingQuestion 1.0',
+                    params: { branchingQuestion: { question: passageHtml(knot), alternatives } },
+                    subContentId: subContentId(i),
+                    metadata: { contentType: 'Branching Question', license: 'U', title: knot.title }
+                },
+                nextContentId: -1
+            };
+        }
+        return {
+            ...common,
+            type: {
+                library: 'H5P.AdvancedText 1.1',
+                params: { text: passageHtml(knot) },
+                subContentId: subContentId(i),
+                metadata: { contentType: 'Text', license: 'U', title: knot.title }
+            },
+            nextContentId: resolve(plainDivertTarget(knot) ?? '')
+        };
+    });
+    return {
+        branchingScenario: {
+            content,
+            startScreen: { startScreenTitle: title, startScreenSubtitle: '' },
+            endScreens: [
+                { endScreenTitle: 'The End', endScreenSubtitle: '', contentId: -1, endScreenScore: 0 }
+            ],
+            scoringOptionGroup: { scoringOption: 'no-score', includeInteractionsScores: false },
+            behaviour: {
+                enableBackwardsNavigation: false,
+                forceContentFinished: false,
+                randomizeBranchingQuestions: false
+            },
+            l10n: {
+                startScreenButtonText: 'Start',
+                endScreenButtonText: 'Restart',
+                backButtonText: 'Back',
+                disableProceedButtonText: 'Require to complete the current module',
+                replayButtonText: 'Replay',
+                scoreText: 'Your score:',
+                fullscreenAria: 'Fullscreen'
+            }
+        }
+    };
+}
+/** The h5p.json package manifest (content-only: dependencies declared, not bundled). */
+function h5pManifest(title) {
+    return {
+        title,
+        language: 'und',
+        defaultLanguage: 'en',
+        mainLibrary: 'H5P.BranchingScenario',
+        embedTypes: ['iframe'],
+        license: 'U',
+        preloadedDependencies: [
+            { machineName: 'H5P.BranchingScenario', majorVersion: '1', minorVersion: '8' },
+            { machineName: 'H5P.AdvancedText', majorVersion: '1', minorVersion: '1' },
+            { machineName: 'H5P.BranchingQuestion', majorVersion: '1', minorVersion: '0' }
+        ]
+    };
+}
+// ─── Minimal ZIP writer (store method, no compression) ───────────────────────
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(data) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < data.length; i++) {
+        crc = CRC_TABLE[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+// Fixed DOS timestamp (2026-01-01 00:00) keeps output byte-identical across runs.
+const DOS_DATE = ((2026 - 1980) << 9) | (1 << 5) | 1;
+const DOS_TIME = 0;
+/** Assemble a store-only (uncompressed) zip from named UTF-8 entries. */
+function zipStore(entries) {
+    const encoder = new TextEncoder();
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    const u16 = (v) => new Uint8Array([v & 0xff, (v >> 8) & 0xff]);
+    const u32 = (v) => new Uint8Array([v & 0xff, (v >>> 8) & 0xff, (v >>> 16) & 0xff, (v >>> 24) & 0xff]);
+    const cat = (...parts) => {
+        const total = parts.reduce((n, p) => n + p.length, 0);
+        const out = new Uint8Array(total);
+        let pos = 0;
+        for (const p of parts) {
+            out.set(p, pos);
+            pos += p.length;
+        }
+        return out;
+    };
+    for (const entry of entries) {
+        const name = encoder.encode(entry.name);
+        const data = encoder.encode(entry.text);
+        const crc = crc32(data);
+        // Local file header: flag bit 11 set = UTF-8 names; method 0 = store.
+        const local = cat(u32(0x04034b50), u16(20), u16(0x0800), u16(0), u16(DOS_TIME), u16(DOS_DATE), u32(crc), u32(data.length), u32(data.length), u16(name.length), u16(0), name, data);
+        central.push(cat(u32(0x02014b50), u16(20), u16(20), u16(0x0800), u16(0), u16(DOS_TIME), u16(DOS_DATE), u32(crc), u32(data.length), u32(data.length), u16(name.length), u16(0), u16(0), u16(0), u16(0), u32(0), u32(offset), name));
+        chunks.push(local);
+        offset += local.length;
+    }
+    const centralBlob = cat(...central);
+    const eocd = cat(u32(0x06054b50), u16(0), u16(0), u16(entries.length), u16(entries.length), u32(centralBlob.length), u32(offset), u16(0));
+    return cat(...chunks, centralBlob, eocd);
+}
+// ─── Public entry point ──────────────────────────────────────────────────────
+/**
+ * Convert a pure-branching Ink story to a .h5p package (zip bytes).
+ * Throws with a construct-by-construct explanation if the story uses state.
+ */
+function exportH5P(inkSource, title) {
+    const content = toBranchingScenarioContent(inkSource, title);
+    return zipStore([
+        { name: 'h5p.json', text: JSON.stringify(h5pManifest(title)) },
+        { name: 'content/content.json', text: JSON.stringify(content) }
+    ]);
+}
+/** Base64-encode package bytes (works in both Node and the browser). */
+function bytesToBase64(bytes) {
+    const B = globalThis.Buffer;
+    if (B)
+        return B.from(bytes).toString('base64');
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}

package/out/shared/imageClient.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * Provider-agnostic image generation, shared by the renderer and the CLI.
+ *
+ * Mirrors aiClient.ts: pure and config-driven (no Zustand store, no DOM), using
+ * the global `fetch`/`AbortController` available in the browser and Node 18+.
+ * Every provider returns a data URL so images embed directly into the preview,
+ * project.json, and standalone HTML exports without filesystem access.
+ *
+ * Provider pattern borrowed from slide-stream's providers/images.py.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSceneImagePrompt = buildSceneImagePrompt;
+exports.isImageProviderConfigured = isImageProviderConfigured;
+exports.generateImage = generateImage;
+exports.normalizeImageBaseUrl = normalizeImageBaseUrl;
+const REQUEST_TIMEOUT_MS = 180_000; // image generation can be slow
+/** Short style directive prepended to every scene prompt. */
+const STYLE_DIRECTIVES = {
+    cartoon: 'Flat cartoon illustration: bold clean outlines, vibrant colors, simple storybook style.',
+    photorealistic: 'Photorealistic cinematic photograph: natural lighting, shallow depth of field, high detail.'
+};
+/**
+ * Build the full image prompt for a story scene. The style directive keeps
+ * every image in a story visually consistent; "no text" avoids garbled
+ * captions baked into the image.
+ */
+function buildSceneImagePrompt(scenePrompt, style = 'cartoon') {
+    const directive = STYLE_DIRECTIVES[style] ?? STYLE_DIRECTIVES.cartoon;
+    return `${directive} No text, words, or letters in the image. Scene: ${scenePrompt.trim()}`;
+}
+/** True when the config has enough to attempt a generation. */
+function isImageProviderConfigured(config) {
+    switch (config.provider) {
+        case 'openai':
+            return !!config.apiKey;
+        case 'gemini':
+            return !!config.apiKey;
+        case 'custom':
+            return !!config.baseUrl && !!config.model;
+        case 'swarmui':
+            return !!config.baseUrl;
+        default:
+            return false;
+    }
+}
+/** Generate one image. Resolves to a data URL (data:image/...;base64,...). */
+async function generateImage(prompt, config) {
+    switch (config.provider) {
+        case 'openai':
+            return generateOpenAICompatibleImage(prompt, 'https://api.openai.com/v1', config);
+        case 'gemini':
+            return generateGeminiImage(prompt, config);
+        case 'custom':
+            if (!config.baseUrl)
+                throw new Error('No base URL configured for the custom image endpoint');
+            return generateOpenAICompatibleImage(prompt, normalizeImageBaseUrl(config.baseUrl), config);
+        case 'swarmui':
+            return generateSwarmUIImage(prompt, config);
+        default:
+            throw new Error(`Unknown image provider: ${String(config.provider)}`);
+    }
+}
+// ─── OpenAI + OpenAI-compatible (/images/generations) ────────────────────────
+async function generateOpenAICompatibleImage(prompt, baseUrl, config) {
+    const model = config.model || 'gpt-image-1';
+    const body = {
+        model,
+        prompt,
+        n: 1,
+        // Custom endpoints are typically self-hosted (CPU LocalAI etc.) where
+        // 1024px is impractically slow — default smaller there.
+        size: config.size || (config.provider === 'custom' ? '512x512' : '1024x1024')
+    };
+    // gpt-image models always return b64_json and reject response_format;
+    // dall-e models need it explicitly to avoid a URL response.
+    if (model.startsWith('dall-e'))
+        body.response_format = 'b64_json';
+    const headers = { 'Content-Type': 'application/json' };
+    if (config.apiKey)
+        headers['Authorization'] = `Bearer ${config.apiKey}`;
+    const response = await fetchWithTimeout(`${baseUrl}/images/generations`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+        throw new Error(`Image API error (${response.status}): ${await response.text()}`);
+    }
+    const data = await response.json();
+    const item = data?.data?.[0];
+    if (!item)
+        throw new Error('Image API returned no image data');
+    if (typeof item.b64_json === 'string' && item.b64_json) {
+        return `data:image/png;base64,${item.b64_json}`;
+    }
+    if (typeof item.url === 'string' && item.url) {
+        return fetchAsDataUrl(item.url);
+    }
+    throw new Error('Image API returned neither b64_json nor a URL');
+}
+// ─── Google Imagen (:predict) ────────────────────────────────────────────────
+async function generateGeminiImage(prompt, config) {
+    if (!config.apiKey)
+        throw new Error('A Google API key is required for Imagen');
+    const model = config.model || 'imagen-4.0-fast-generate-001';
+    const aspectRatio = config.size || '4:3';
+    const response = await fetchWithTimeout(`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:predict`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-goog-api-key': config.apiKey
+        },
+        body: JSON.stringify({
+            instances: [{ prompt }],
+            parameters: { sampleCount: 1, aspectRatio }
+        })
+    });
+    if (!response.ok) {
+        throw new Error(`Imagen API error (${response.status}): ${await response.text()}`);
+    }
+    const data = await response.json();
+    const prediction = data?.predictions?.[0];
+    const b64 = prediction?.bytesBase64Encoded;
+    if (typeof b64 !== 'string' || !b64)
+        throw new Error('Imagen returned no image');
+    const mime = typeof prediction?.mimeType === 'string' ? prediction.mimeType : 'image/png';
+    return `data:${mime};base64,${b64}`;
+}
+// ─── SwarmUI (native API — it does not speak OpenAI /images) ─────────────────
+//
+// Flow ported from slide-stream's SwarmUIImageProvider: open a session, call
+// GenerateText2Image, then download the returned server path. apiKey is sent as
+// a Bearer token (only needed when the server is fronted by auth).
+async function generateSwarmUIImage(prompt, config) {
+    if (!config.baseUrl)
+        throw new Error('No base URL configured for SwarmUI');
+    const baseUrl = normalizeImageBaseUrl(config.baseUrl);
+    const headers = { 'Content-Type': 'application/json' };
+    if (config.apiKey)
+        headers['Authorization'] = `Bearer ${config.apiKey}`;
+    // 1. Open a session.
+    const session = await fetchWithTimeout(`${baseUrl}/API/GetNewSession`, {
+        method: 'POST',
+        headers,
+        body: '{}'
+    }, 30_000);
+    if (!session.ok) {
+        throw new Error(`SwarmUI session error (${session.status}): ${await session.text()}`);
+    }
+    const sessionId = (await session.json())?.session_id;
+    if (typeof sessionId !== 'string' || !sessionId) {
+        throw new Error('SwarmUI did not return a session_id');
+    }
+    // 2. Generate. SDXL-class models want ~1024px; a landscape frame suits a
+    // scene illustration above story text.
+    const [width, height] = parseSize(config.size) ?? [1024, 576];
+    const body = { session_id: sessionId, prompt, images: 1, width, height };
+    if (config.model)
+        body.model = config.model;
+    const gen = await fetchWithTimeout(`${baseUrl}/API/GenerateText2Image`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body)
+    });
+    if (!gen.ok) {
+        throw new Error(`SwarmUI generation error (${gen.status}): ${await gen.text()}`);
+    }
+    const data = await gen.json();
+    const images = data?.images;
+    if (!Array.isArray(images) || typeof images[0] !== 'string') {
+        throw new Error('SwarmUI returned no image');
+    }
+    // 3. Fetch the generated image by its server path.
+    return fetchAsDataUrl(`${baseUrl}/${images[0].replace(/^\/+/, '')}`, headers);
+}
+/** Parse a '1024x576' size string into [width, height]; null if malformed. */
+function parseSize(size) {
+    if (!size)
+        return null;
+    const m = size.trim().match(/^(\d+)\s*x\s*(\d+)$/i);
+    if (!m)
+        return null;
+    const w = parseInt(m[1], 10);
+    const h = parseInt(m[2], 10);
+    return w > 0 && h > 0 ? [w, h] : null;
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/** Strip trailing slashes so `${base}/images/generations` is well-formed. */
+function normalizeImageBaseUrl(url) {
+    return url.trim().replace(/\/+$/, '');
+}
+async function fetchWithTimeout(url, options, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...options, signal: controller.signal });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new Error(`Image request timed out after ${timeoutMs / 1000}s`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Download an image URL and return it as a data URL (avoids expiring URLs). */
+async function fetchAsDataUrl(url, headers = {}) {
+    const response = await fetchWithTimeout(url, { method: 'GET', headers }, 60_000);
+    if (!response.ok)
+        throw new Error(`Could not download image (${response.status})`);
+    const mime = response.headers.get('content-type')?.split(';')[0] || 'image/png';
+    const buffer = await response.arrayBuffer();
+    return `data:${mime};base64,${arrayBufferToBase64(buffer)}`;
+}
+/** ArrayBuffer → base64 without Node's Buffer (the renderer has no Buffer). */
+function arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}