Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
[issue-13110] Ship a standalone static reference player for exported FableLoom graphs (#13444)
[._.]/6f3e16861ae4
diff --git a/docs/features/fableloom-export-v1.md b/docs/features/fableloom-export-v1.mdindex 9c328ae9af..f312bdeb7f 100644--- a/docs/features/fableloom-export-v1.md+++ b/docs/features/fableloom-export-v1.md@@ -22,11 +22,12 @@ authority, including valid delegated agent sessions. Jobs cannot be read ordownloaded through a different loom. Instance authentication retains its existingoptional policy; no export endpoint is always-public.-`includePlayer:true`, and `includeWebm:true` on the source profile, are refused-(`EXPORT_OPTION_UNSUPPORTED`). `includeVoice:true` without+`includePlayer:true` adds the dependency-free `player/` reference client+described in the runtime contract. `includeVoice:true` without`includeCharacters:true` is refused (`EXPORT_VOICE_REQUIRES_CHARACTERS`).Character files and voice reference audio are explicit opt-ins, off by default.-Unknown media profiles are rejected at validation.+`includeWebm:true` on the source profile is refused+(`EXPORT_OPTION_UNSUPPORTED`). Unknown media profiles are rejected at validation.`DELETE /api/fableloom/:id/export/:jobId` cancels a queued/running export andwaits for worker and encoder shutdown before returning its failed status(`EXPORT_CANCELLED`). Completed jobs remain completed.@@ -158,6 +159,9 @@ accepted as completed encodes. Source media remains untouched.- `runtime-v1.md` and `README.md`: the versioned playback and hosting contracts.The README tells the host that it owns TTS and that the package grants noPortOS access.+- `player/` when `includePlayer` is set: static HTML, CSS and scripts that read+ `manifest.json` and run runtime v1 in the browser. That directory has no+ instance data, credential, or authoring-service address.All JSON object keys and ZIP member order are stable. ZIP timestamps are fixed.The same source bytes and authored snapshot, with the same PortOS/media-tooldiff --git a/docs/features/fableloom-runtime-v1.md b/docs/features/fableloom-runtime-v1.mdindex 4a83ae0afb..ebd5c5b7e5 100644--- a/docs/features/fableloom-runtime-v1.md+++ b/docs/features/fableloom-runtime-v1.md@@ -9,9 +9,10 @@ changes to traversal, admission or event meaning require a new runtime versionand corresponding hosted regression tests.This is the runtime foundation for [external package export #13104](https://github.com/atomantic/PortOS/issues/13104).-It does not yet implement an exporter, downloadable package or reference player.-PortOS remains a private authoring/rehearsal service. An external host runs its-own backend, credentials and transport; it never relays public calls into PortOS.+The exporter copies this document into each package. `includePlayer` also adds+the dependency-free reference player below. PortOS remains a private+authoring/rehearsal service. An external host runs its own backend, credentials+and transport; it never relays public calls into PortOS.## Graph and playback@@ -83,6 +84,17 @@ A host can expose `resolveTurn(nodeId, message)` returningmap stay text to narration. This adapter shape is not the private endpoint'sresponse shape. A choice-only/keyword adapter needs no network or LLM.+The reference player implements that adapter with `createSession`,+`createKeywordResolver`, `liveInputAllowed` and `mediaUrl`. `createSession`+plays one episode from the packaged manifest. `createKeywordResolver` matches+one exact intent, trigger, or transition id on the current scene and performs+no network request. `liveInputAllowed` is the admission policy above.+`mediaUrl` accepts only a packaged `media/<sha256>.<ext>` path. A host may+replace the keyword adapter by assigning `resolveTurn` before the page loads.+`player/contract-example.js` shows a host-owned `POST /story/turn` and is not+loaded by the page. The host owns that request. An unknown edge or a missing+target stays on the current scene.+## Live-input admission and half duplex`evaluateFableLoomLiveInput({node, phase, asset})` is the shared pure admission@@ -115,6 +127,11 @@ the current turn, scene revision and designated output device. Treat cancellatioplayback failure and missing completion as explicit outcomes, never an implicitsuccessful acknowledgement.+The exported reference player waits for a speech outcome bound to the turn,+node, episode and generation before it commits a move. `completed` or an+explicit `empty` may commit. `failed`, `cancelled`, `unavailable` and `missing`+leave the scene in place. A later episode or turn ignores a stale outcome.+**Hosted v1 currently guarantees synthesis and audio dispatch before commit,not completed playback.** `processHostedUtterance` emits `hosted:turn:tts`then immediately changes the node and emits `hosted:story:transition`.diff --git a/scripts/ci-test-plan.test.js b/scripts/ci-test-plan.test.jsindex 054b4fdb7c..0664e59068 100644--- a/scripts/ci-test-plan.test.js+++ b/scripts/ci-test-plan.test.js@@ -1963,7 +1963,9 @@ describe('cross-workspace browser suites (#10312)', () => {// Server-only media suites do not mount the changed client component.const runtimeOnly = ['server/lib/filmLook.browser.test.js', 'server/lib/filmLookGpu.browser.test.js', 'server/lib/musicVideoTitleCard.browser.test.js',- 'server/services/federatedMedia/sourceAudio.browser.test.js', 'server/services/htmlComposition/index.test.js'];+ 'server/services/federatedMedia/sourceAudio.browser.test.js',+ 'server/services/fableLoom/static-player/player.browser.test.js',+ 'server/services/htmlComposition/index.test.js'];expect(plan.full).toBe(false);expect(plan.browserFiles).toEqual(expect.arrayContaining(BROWSER_SUITES.filter((suite) => !runtimeOnly.includes(suite))));for (const suite of runtimeOnly) expect(plan.browserFiles).not.toContain(suite);diff --git a/scripts/lib/browserSuites.js b/scripts/lib/browserSuites.jsindex 4d701dc1d6..0c9d9c2134 100644--- a/scripts/lib/browserSuites.js+++ b/scripts/lib/browserSuites.js@@ -7,6 +7,7 @@ export const BROWSER_SUITES = ['server/routes/musicVideoProductionReview.browser.test.js','server/routes/musicVideoRichAuthoring.browser.test.js','server/routes/musicVideoSongRevision.browser.test.js',+ 'server/services/fableLoom/static-player/player.browser.test.js','server/services/federatedMedia/sourceAudio.browser.test.js','server/services/htmlComposition/index.test.js','server/services/musicVideo/animaticCapture.browser.test.js',diff --git a/server/services/fableLoom/README.md b/server/services/fableLoom/README.mdindex 3959dafd49..a63fadac70 100644--- a/server/services/fableLoom/README.md+++ b/server/services/fableLoom/README.md@@ -18,7 +18,9 @@ intent to a transition and moves them through the graph until an ending.| `production.js` | Episodic production orchestration: batch planning, DAG generation, cancellable batch runs, and user-triggered episodic continuity review (#5384). || `falVideoAutomation.js` | User-triggered, serialized Playwright automation over the persistent PortOS CDP browser: uploads a scene still + full shot prompt to fal.ai H3 Max, downloads the finished MP4 into shared video history, and attaches it to the originating scene. || `store.js` | PostgreSQL/file backend facade (`fableloom_stories`; collectionStore escape hatch for tests). |-| `exports.js` | Immutable authored snapshots, readiness/approval gates, deterministic portable ZIP packages and bounded persistent export jobs. |+| `exports.js` | Immutable authored snapshots, readiness/approval gates, deterministic portable ZIP packages, an optional static reference player, and bounded persistent export jobs. |+| `staticPlayerFiles.js` | Stable filenames copied into an export's `player/` directory when `includePlayer` is set. |+| `static-player/` | Dependency-free reference player copied into an export when `includePlayer` is set. || `exportMedia.js` | Root-confined bounded media reads, metadata-free PNG stills and H.264/AAC MP4 stream copies; no network or generation. || `exportVoice.js` | Root-confined reads of one approved voice-reference basename from that profile's source directory. Transcripts, engines and local paths stay out of the package. || `db.js` | PostgreSQL leaf I/O. |diff --git a/server/services/fableLoom/exports.js b/server/services/fableLoom/exports.jsindex dee8727391..b2e9146243 100644--- a/server/services/fableLoom/exports.js+++ b/server/services/fableLoom/exports.js@@ -23,6 +23,7 @@ import { getLoom } from './records.js';import { checkExportCancelled, readFableLoomExportSource } from './exportMedia.js';import { readFableLoomVoiceReference } from './exportVoice.js';import { createFableLoomMediaCache } from './exportMediaCache.js';+import { FABLELOOM_STATIC_PLAYER_FILES } from './staticPlayerFiles.js';const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;const active = new Map();@@ -176,6 +177,12 @@ function createMediaStore(maxBytes = FABLELOOM_EXPORT_LIMITS.maxPackageBytes) {}function packageReadme(options) {+ const playerNote = options.includePlayer+ ? `player/index.html is a dependency-free reference player for this package.+Serve the package directory and open that page. It reads manifest.json, plays a+cut through to its next scene, and holds a decision until a choice.`+ : `This package does not include the reference player. Export again with+includePlayer set to add player/index.html.`;const characters = options.includeCharacters ? `characters/<id>.json is included for each canonical cast member: the loomprotagonist, when set, and characters staged on reachable scenes. Each file@@ -217,11 +224,23 @@ The source profile remuxes H.264/AAC. Web profiles resize without upscaling,encode H.264/AAC with bitrate caps, normalize the authored audio mix and includeposter PNGs. Explicitly requested WebM alternatives use VP9/Opus. Encodingprofiles, encoder identities and byte counts are recorded in provenance.json.-The reference player is not in this package. Your host owns free-text-resolution, TTS and transport, following runtime-v1.md.+${playerNote}+Your host owns free-text resolution, TTS and transport, following runtime-v1.md;+no PortOS URL or credential is needed.`;}+async function playerEntries() {+ const entries = [];+ for (const name of FABLELOOM_STATIC_PLAYER_FILES) {+ entries.push({+ name: `player/${name}`,+ data: await readFile(new URL(`./static-player/${name}`, import.meta.url)),+ });+ }+ return entries;+}+// Voice profiles live in Postgres. Keep that module off the default export path.async function loadVoiceProfiles(universeId, characterId) {const { listVoiceProfiles } = await import('../voice/profiles.js');@@ -416,6 +435,7 @@ async function build(job, snapshot, episodes, history, universe, signal) {})) : []),{ name: 'runtime-v1.md', data: await readFile(new URL('../../../docs/features/fableloom-runtime-v1.md', import.meta.url)) },...[...media.entries()].map(([name, data]) => ({ name, data })),+ ...(job.options.includePlayer === true ? await playerEntries() : []),].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);const totalBytes = entries.reduce((n, e) => n + Buffer.byteLength(e.data), 0);if (totalBytes > FABLELOOM_EXPORT_LIMITS.maxPackageBytes) {@@ -459,8 +479,8 @@ async function run(job, context, permit) {export async function startFableLoomExport(loomId, input = {}) {const options = exportOptionsSchema.parse(input);- if (options.includePlayer || (options.mediaProfile === 'source' && options.includeWebm)) {- throw error('EXPORT_OPTION_UNSUPPORTED', 'The reference player is unavailable. WebM requires a web media profile.', 400);+ if (options.mediaProfile === 'source' && options.includeWebm) {+ throw error('EXPORT_OPTION_UNSUPPORTED', 'WebM requires a web media profile.', 400);}if (options.includeVoice && !options.includeCharacters) {throw error('EXPORT_VOICE_REQUIRES_CHARACTERS', 'Voice export requires character opt-in (includeCharacters).', 400);diff --git a/server/services/fableLoom/exports.test.js b/server/services/fableLoom/exports.test.jsindex 1926f651e2..3ea4f735d8 100644--- a/server/services/fableLoom/exports.test.js+++ b/server/services/fableLoom/exports.test.js@@ -14,6 +14,7 @@ import { findFfmpeg, findFfprobe, runFfmpegProcess } from '../../lib/ffmpeg.js';import {FABLELOOM_EXPORT_LIMITS, inspectFableLoomExportCharacters,} from '../../lib/fableLoomExport.js';+import { FABLELOOM_STATIC_PLAYER_FILES } from './staticPlayerFiles.js';import { execFileSync } from '../../lib/childProcess.js';vi.mock('../../lib/paths.js', async original => makePathsProxy(await original(), {@@ -477,7 +478,7 @@ describe('portable FableLoom export boundary', () => {});it('refuses unsupported and malformed options before creating jobs', async () => {- for (const input of [{ includePlayer: true },+ for (const input of [{ mediaProfile: 'webm' }, { includeWebm: true }, { includeWebm: 'yes' }, { mediaProfile: { width: 100 } }, { allowDraft: 'yes' },{ episodeIds: [] }, { episodeIds: ['episode-one', 'episode-one'] }, { destination: sourcePath }]) {const response = await request(app()).post('/api/fableloom/example-loom/export').send(input);@@ -490,6 +491,28 @@ describe('portable FableLoom export boundary', () => {await expect(startFableLoomExport(loom.id, { episodeIds: ['unknown-episode'] })).rejects.toMatchObject({ code: 'EXPORT_EPISODES_INVALID' });});+ videoIt('adds the reference player only when requested and keeps that directory free of private data', async () => {+ const plain = await archive(await begin({ episodeIds: ['episode-one'] }));+ expect([...plain.files.keys()].some((name) => name.startsWith('player/'))).toBe(false);+ expect(plain.files.get('README.md').toString('utf8')).toContain('does not include the reference player');+ const first = await archive(await begin({ episodeIds: ['episode-one'], includePlayer: true }));+ const second = await archive(await begin({ episodeIds: ['episode-one'], includePlayer: true }));+ expect(second.bytes.equals(first.bytes)).toBe(true);+ for (const name of FABLELOOM_STATIC_PLAYER_FILES) expect(first.files.has(`player/${name}`)).toBe(true);+ const playerText = [...first.files].filter(([name]) => name.startsWith('player/'))+ .map(([, bytes]) => bytes.toString('utf8')).join('\n');+ expect(playerText).not.toMatch(/https?:\/\//i);+ expect(playerText.toLowerCase().replaceAll('portos-allow-hidden-content', '')).not.toContain('portos');+ expect(playerText).not.toContain(privateMarker);+ expect(playerText.toLowerCase()).not.toContain('bearer');+ expect(first.files.get('player/index.html').toString('utf8')).not.toContain('contract-example');+ expect(first.files.get('README.md').toString('utf8')).toContain('player/index.html is a dependency-free');+ for (const bytes of first.files.values()) {+ expect(bytes.includes(Buffer.from(privateMarker))).toBe(false);+ expect(bytes.includes(Buffer.from(sourcePath))).toBe(false);+ }+ });+it('limits the cast to the protagonist and reachable staged characters', () => {const episodes = [{startNodeId: 'a',diff --git a/server/services/fableLoom/static-player/README.md b/server/services/fableLoom/static-player/README.mdnew file mode 100644index 0000000000..5ee90c4818--- /dev/null+++ b/server/services/fableLoom/static-player/README.md@@ -0,0 +1,15 @@+# Reference player++Serve the package directory with any static file server and open `index.html` in this folder. The page reads `manifest.json` beside this folder. It does not contact an authoring service, and this folder stores no credential, relay, or sign-in material.++A cut plays until its clip ends, then follows the first transition whose target exists. A missing target ends the scene. A clip that fails during an entry or an exit counts as ended, once. A failed hold stays on that scene. A hold that finishes while a turn is in flight advances when that turn settles. A decision holds until a choice. An ending plays its entry clip when it has one, then stops. The ending label stays on screen, with no choices and no composer.++Authored words are shown as text. Markup in the story is not executed.++While the turn is listening, typed text is matched on this machine to one intent, one trigger, or one transition id. Zero matches and several matches stay on the scene. That match performs no network request.++A host may assign `resolveTurn(nodeId, message)` on `FableLoomPlayer` before this page loads. Return `{move: transitionId}` or `{stay: text}`. A move names an edge on the current scene. An unknown edge or a missing target stays. The sample in `contract-example.js` posts to the host's own `/story/turn`. This page does not load that file. The host owns any request that resolution needs.++A host may assign `completeSpeech(turn)`. The result must echo `turnId` and `nodeId` and use status `completed`, `empty`, `failed`, `cancelled`, `unavailable`, or `missing`. The player commits a move only after `completed` or an explicit `empty`. The other statuses leave the scene in place. The built-in voice counts a stall as `failed`. Stay text is shown and spoken without changing scene.++Turns move through idle, listening, thinking, and speaking. A new line or choice is accepted only when the current phase allows it. A reply for one scene cannot change a later scene.diff --git a/server/services/fableLoom/static-player/contract-example.js b/server/services/fableLoom/static-player/contract-example.jsnew file mode 100644index 0000000000..a2393266a7--- /dev/null+++ b/server/services/fableLoom/static-player/contract-example.js@@ -0,0 +1,17 @@+// Host-owned example. index.html does not load this file.+// Assign it before the page module runs:+// globalThis.FableLoomPlayer = { resolveTurn: globalThis.FableLoomHostResolverExample };+globalThis.FableLoomHostResolverExample = async function resolveTurn(nodeId, message) {+ const response = await globalThis.fetch('/story/turn', {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ nodeId, message }),+ });+ if (!response.ok) return { stay: 'The host did not answer.' };+ const body = await response.json();+ if (body && body.action === 'move' && typeof body.transitionId === 'string') {+ return { move: body.transitionId };+ }+ const narration = body && typeof body.narration === 'string' ? body.narration : '';+ return { stay: narration };+};diff --git a/server/services/fableLoom/static-player/index.html b/server/services/fableLoom/static-player/index.htmlnew file mode 100644index 0000000000..c45d970cc3--- /dev/null+++ b/server/services/fableLoom/static-player/index.html@@ -0,0 +1,28 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="utf-8">+ <meta name="viewport" content="width=device-width, initial-scale=1">+ <title>Story</title>+ <link rel="stylesheet" href="player.css">+</head>+<body>+ <main id="player">+ <p id="failure" hidden></p>+ <h1 id="title"></h1>+ <p id="prose"></p>+ <p id="narration" hidden></p>+ <video id="stage" playsinline preload="metadata"></video>+ <button id="play" type="button" hidden>Play</button>+ <div id="choices" role="group" aria-label="Choices"></div>+ <form id="composer" hidden>+ <label for="message">Say something</label>+ <input id="message" name="message" type="text" maxlength="1000" autocomplete="off">+ <button type="submit">Send</button>+ </form>+ <p id="ending" hidden></p>+ <p id="status" role="status"></p>+ </main>+ <script type="module" src="player.js"></script><!-- portos-allow-hidden-content -->+</body>+</html>diff --git a/server/services/fableLoom/static-player/player.browser.test.js b/server/services/fableLoom/static-player/player.browser.test.jsnew file mode 100644index 0000000000..c2989a83cc--- /dev/null+++ b/server/services/fableLoom/static-player/player.browser.test.js@@ -0,0 +1,296 @@+import { execFileSync } from 'node:child_process';+import { mkdirSync } from 'node:fs';+import { createServer, request as httpRequest } from 'node:http';+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { extname, join, normalize, sep } from 'node:path';+import { fileURLToPath } from 'node:url';+import { afterAll, beforeAll, describe, expect, it } from 'vitest';+import { chromium } from 'playwright-core';+import { browserSuiteCanRun, resolveTestChrome } from '../../../lib/browserSuiteGate.js';+import { FABLELOOM_STATIC_PLAYER_FILES } from '../staticPlayerFiles.js';++const here = fileURLToPath(new URL('.', import.meta.url));+const chrome = resolveTestChrome();+const canRun = browserSuiteCanRun('fableloom static player', { Chrome: chrome });+const HASH = 'a'.repeat(64);++function graph(version = '1.0.0') {+ const clip = { file: `media/${HASH}.mp4`, durationMs: 1000, loopable: true,+ audioOccupancy: { safeForLiveVoice: true, characterDialogue: [], effects: [], clipping: false } };+ return {+ schemaVersion: version,+ runtimeVersion: '1.0.0',+ loom: {+ name: 'Example gate',+ participationMode: 'protagonist',+ episodes: [+ {+ id: 'episode-one', title: 'Gate', startNodeId: 'cut-open',+ nodes: [+ {+ id: 'cut-open', title: 'Opening',+ prose: 'A gate.<img src="x" onerror="alert(1)"><script>alert(1)</script>',+ playbackMode: 'cut', audienceConnection: 'disconnected', protagonistPresence: 'offscreen',+ isEnding: false, endingLabel: '',+ transitions: [{ id: 'arrive', intent: 'Arrive', triggers: [], description: '', targetNodeId: 'decision-gate' }],+ playbackAssets: { still: null, entry: clip, holds: [], exits: {} },+ },+ {+ id: 'decision-gate', title: 'The gate', prose: 'The gate holds.',+ playbackMode: 'decision', audienceConnection: 'connected', protagonistPresence: 'offscreen',+ isEnding: false, endingLabel: '',+ transitions: [+ { id: 'wait', intent: 'Wait here', triggers: ['wait here'], description: 'Stay', targetNodeId: 'decision-gate' },+ { id: 'open', intent: 'Open the gate', triggers: ['open the gate'], description: 'Leave', targetNodeId: 'ending-home' },+ ],+ playbackAssets: { still: null, entry: null, holds: [clip], exits: {} },+ },+ {+ id: 'ending-home', title: 'Home', prose: 'Home.',+ playbackMode: 'cut', audienceConnection: 'disconnected', protagonistPresence: 'offscreen',+ isEnding: true, endingLabel: 'Home', transitions: [],+ playbackAssets: { still: null, entry: clip, holds: [], exits: {} },+ },+ ],+ },+ {+ id: 'episode-other', title: 'Other', startNodeId: 'other-start',+ nodes: [{+ id: 'other-start', title: 'Elsewhere', prose: 'Elsewhere.',+ playbackMode: 'decision', audienceConnection: 'connected', protagonistPresence: 'offscreen',+ isEnding: false, endingLabel: '', transitions: [],+ playbackAssets: { still: null, entry: null, holds: [clip], exits: {} },+ }],+ },+ ],+ },+ };+}++function contentType(path) {+ if (extname(path) === '.js') return 'text/javascript; charset=utf-8';+ if (extname(path) === '.css') return 'text/css; charset=utf-8';+ if (extname(path) === '.html') return 'text/html; charset=utf-8';+ if (extname(path) === '.json') return 'application/json; charset=utf-8';+ return 'application/octet-stream';+}++function startPackageServer(root) {+ const rootWithSep = root.endsWith(sep) ? root : root + sep;+ const server = createServer((request, response) => {+ const fail = (code) => { response.writeHead(code); response.end(); };+ let pathname;+ try { pathname = decodeURIComponent(new URL(request.url, 'http://127.0.0.1').pathname); } catch { fail(400); return; }+ if (pathname.includes('\0')) { fail(400); return; }+ const path = normalize(join(root, pathname));+ if (path !== root && !path.startsWith(rootWithSep)) { fail(403); return; }+ readFile(path).then((data) => {+ response.writeHead(200, { 'content-type': contentType(path), 'cache-control': 'no-store' });+ response.end(data);+ }).catch(() => fail(404));+ });+ return new Promise((resolve, reject) => {+ server.once('error', reject);+ server.listen(0, '127.0.0.1', () => resolve({+ port: server.address().port,+ origin: `http://127.0.0.1:${server.address().port}`,+ close: () => new Promise((done) => server.close(done)),+ }));+ });+}++async function stage(dir, manifest) {+ await mkdir(join(dir, 'player'), { recursive: true });+ for (const name of FABLELOOM_STATIC_PLAYER_FILES) await cp(join(here, name), join(dir, 'player', name));+ await writeFile(join(dir, 'manifest.json'), JSON.stringify(manifest));+}++function writeClip(dir) {+ const media = join(dir, 'media');+ mkdirSync(media, { recursive: true });+ // A missing file fires error, and a failed entry now leaves that scene.+ // The manual ended path needs a clip that loads and does not finish itself.+ execFileSync('ffmpeg', [+ '-y', '-v', 'error', '-f', 'lavfi', '-i', 'color=c=black:s=16x16:d=1:r=1',+ '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', '-an',+ join(media, `${HASH}.mp4`),+ ], { stdio: 'ignore' });+}++async function ended(page) {+ await page.locator('#stage').evaluate((video) => video.dispatchEvent(new Event('ended')));+}++describe.skipIf(!canRun)('static reference player in a generic file server', () => {+ let browser;+ let server;+ let origin;+ let root;++ beforeAll(async () => {+ root = await mkdtemp(join(tmpdir(), 'fableloom-player-'));+ await stage(join(root, 'good'), graph());+ await stage(join(root, 'bad'), graph('2.0.0'));+ await stage(join(root, 'bare'), graph());+ writeClip(join(root, 'good'));+ writeClip(join(root, 'bad'));+ server = await startPackageServer(root);+ origin = server.origin;+ const escaped = await new Promise((resolve, reject) => {+ const request = httpRequest({ hostname: '127.0.0.1', port: server.port, path: '/../../../../../../etc/passwd' }, (response) => {+ response.resume();+ response.on('end', () => resolve(response.statusCode));+ });+ request.on('error', reject);+ request.end();+ });+ expect(escaped).not.toBe(200);+ browser = await chromium.launch({ executablePath: chrome, headless: true });+ });++ afterAll(async () => {+ await browser?.close();+ await server?.close();+ if (root) await rm(root, { recursive: true, force: true });+ });++ async function open(path, init) {+ const page = await browser.newPage();+ const requests = [];+ const dialogs = [];+ const errors = [];+ page.on('request', (request) => requests.push(request.url()));+ page.on('dialog', (dialog) => { dialogs.push(dialog.message()); void dialog.dismiss().catch(() => {}); });+ page.on('pageerror', (error) => errors.push(error.message));+ await page.addInitScript(() => {+ HTMLMediaElement.prototype.play = () => Promise.resolve();+ });+ if (init) await page.addInitScript(init);+ await page.goto(`${origin}${path}`);+ return { page, requests, dialogs, errors };+ }++ it('plays a cut into a decision loop and an ending with local text, keyboard and tap', async () => {+ const { page, requests, dialogs, errors } = await open('/good/player/index.html', () => {+ const original = globalThis.fetch.bind(globalThis);+ globalThis.__fetches = [];+ globalThis.fetch = (input, init) => {+ globalThis.__fetches.push(String(input));+ return original(input, init);+ };+ });+ try {+ await page.waitForSelector('[data-node="cut-open"][data-phase="entry"]');+ const prose = page.locator('#prose');+ expect(await prose.innerText()).toContain('<script>alert(1)</script>');+ expect(await prose.locator('img, script').count()).toBe(0);+ expect(parseFloat(await prose.evaluate((node) => getComputedStyle(node).fontSize))).toBeGreaterThanOrEqual(18);+ await ended(page);+ await page.waitForSelector('[data-node="decision-gate"][data-phase="hold"]');+ expect(await page.locator('#stage').evaluate((video) => video.loop)).toBe(true);+ await ended(page);+ expect(await page.locator('#player').getAttribute('data-node')).toBe('decision-gate');+ const chip = page.locator('button[data-choice="wait"]');+ expect(await chip.evaluate((node) => node.getBoundingClientRect().height)).toBeGreaterThanOrEqual(44);+ await chip.click();+ await page.waitForFunction(() => document.querySelector('#player').dataset.turn !== 'speaking');+ expect(await page.locator('#player').getAttribute('data-node')).toBe('decision-gate');+ await page.locator('#message').fill('open the gate');+ await page.locator('#composer button[type="submit"]').click();+ await page.waitForSelector('[data-node="ending-home"][data-phase="entry"]');+ expect(await page.locator('#choices button').count()).toBe(0);+ expect(await page.locator('#composer').isHidden()).toBe(true);+ await ended(page);+ await page.waitForSelector('[data-phase="ended"][data-ended="true"]');+ expect(await page.locator('#ending').innerText()).toBe('Home');+ expect(dialogs).toEqual([]);+ expect(errors).toEqual([]);+ const fetches = await page.evaluate(() => globalThis.__fetches);+ expect(fetches).toHaveLength(1);+ expect(fetches[0]).toContain('manifest.json');+ expect(requests.every((url) => new URL(url).host === new URL(origin).host)).toBe(true);+ expect(requests.some((url) => url.includes('contract-example') || url.includes('/story/turn'))).toBe(false);+ } finally { await page.close(); }+ });++ it('moves the choice focus with the keyboard and activates the focused chip', async () => {+ const { page, errors } = await open('/good/player/index.html');+ try {+ await page.waitForSelector('[data-node="cut-open"]');+ await ended(page);+ await page.waitForSelector('button[data-choice="open"]');+ await page.locator('button[data-choice="wait"]').focus();+ await page.keyboard.press('ArrowRight');+ expect(await page.evaluate(() => document.activeElement?.dataset.choice)).toBe('open');+ await page.keyboard.press('Enter');+ await page.waitForSelector('[data-node="ending-home"]');+ expect(errors).toEqual([]);+ } finally { await page.close(); }+ });++ it('keeps a custom resolver on the graph and ignores a speech result for an earlier episode', async () => {+ const { page, errors } = await open('/good/player/index.html', () => {+ globalThis.FableLoomPlayer = {+ resolveTurn: async (_nodeId, message) => (+ message === 'missing' ? { move: 'not-real' } : { stay: 'held here' }+ ),+ completeSpeech: (turn) => {+ const outcome = {+ status: turn.text ? 'completed' : 'empty', turnId: turn.turnId, nodeId: turn.nodeId,+ episodeId: turn.episodeId, generation: turn.generation,+ };+ if (turn.text) return outcome;+ return new Promise((resolve) => { globalThis.__finish = () => resolve({ ...outcome, status: 'completed' }); });+ },+ };+ });+ try {+ await page.waitForSelector('[data-node="cut-open"]');+ await ended(page);+ await page.waitForSelector('[data-node="decision-gate"][data-turn="listening"]');+ await page.locator('#message').fill('missing');+ await page.locator('#composer button[type="submit"]').click();+ await page.waitForFunction(() => document.querySelector('#status').textContent.includes('not on this scene'));+ expect(await page.locator('#player').getAttribute('data-node')).toBe('decision-gate');+ await page.locator('#message').fill('hello');+ await page.locator('#composer button[type="submit"]').click();+ await page.waitForFunction(() => document.querySelector('#narration').textContent === 'held here');+ expect(await page.locator('#player').getAttribute('data-node')).toBe('decision-gate');+ await page.locator('button[data-choice="open"]').click();+ await page.waitForSelector('[data-turn="speaking"]');+ expect(await page.locator('#player').getAttribute('data-node')).toBe('decision-gate');+ await page.evaluate(() => globalThis.FableLoomPlayer.session.selectEpisode('episode-other'));+ await page.waitForSelector('[data-node="other-start"]');+ await page.evaluate(() => globalThis.__finish());+ expect(await page.locator('#player').getAttribute('data-node')).toBe('other-start');+ expect(errors).toEqual([]);+ } finally { await page.close(); }+ });++ it('leaves a cut when its clip cannot be loaded and keeps the next hold', async () => {+ const { page, errors } = await open('/bare/player/index.html');+ try {+ await page.waitForSelector('[data-node="decision-gate"][data-phase="hold"]');+ await page.waitForFunction(() => document.querySelector('#status').textContent.includes('could not be played'));+ expect(await page.locator('#player').getAttribute('data-node')).toBe('decision-gate');+ expect(await page.locator('#choices button').count()).toBe(2);+ expect(errors).toEqual([]);+ } finally { await page.close(); }+ });++ it('opens the requested episode and refuses a newer package major', async () => {+ const other = await open('/good/player/index.html?episode=episode-other');+ try {+ await other.page.waitForSelector('[data-node="other-start"]');+ expect(other.errors).toEqual([]);+ } finally { await other.page.close(); }+ const bad = await open('/bad/player/index.html');+ try {+ await bad.page.waitForSelector('#failure:not([hidden])');+ expect(await bad.page.locator('#failure').innerText()).toMatch(/major version 1/);+ expect(await bad.page.locator('#player').getAttribute('data-node')).toBeNull();+ expect(bad.dialogs).toEqual([]);+ } finally { await bad.page.close(); }+ });+});diff --git a/server/services/fableLoom/static-player/player.css b/server/services/fableLoom/static-player/player.cssnew file mode 100644index 0000000000..30fcfc7f48--- /dev/null+++ b/server/services/fableLoom/static-player/player.css@@ -0,0 +1,71 @@+:root {+ color-scheme: light;+ background: #f6f3ec;+ color: #1b1a17;+ font: 18px/1.45 system-ui, sans-serif;+}++body {+ margin: 0;+}++main {+ max-width: 40rem;+ margin: 0 auto;+ padding: 1.25rem;+}++h1 {+ font-size: 1.6rem;+ line-height: 1.25;+}++#prose,+#narration,+#ending,+#failure {+ white-space: pre-wrap;+ overflow-wrap: anywhere;+}++video {+ width: 100%;+ max-height: 50vh;+ background: #d9d3c5;+}++button {+ font: inherit;+ min-height: 44px;+ min-width: 44px;+ background: #1b1a17;+ color: #f6f3ec;+ border: 0;+ border-radius: 0.4rem;+ padding: 0.4rem 0.8rem;+}++input {+ font: inherit;+ min-height: 44px;+ flex: 1 1 12rem;+}++button:focus-visible,+input:focus-visible {+ outline: 3px solid #1d4e89;+ outline-offset: 2px;+}++#choices,+#composer:not([hidden]) {+ display: flex;+ flex-wrap: wrap;+ gap: 0.5rem;+ align-items: center;+ margin: 0.75rem 0;+}++#failure {+ color: #8a1c1c;+}diff --git a/server/services/fableLoom/static-player/player.js b/server/services/fableLoom/static-player/player.jsnew file mode 100644index 0000000000..e7ec0094a6--- /dev/null+++ b/server/services/fableLoom/static-player/player.js@@ -0,0 +1,201 @@+import { createSession, mediaUrl } from './runtime.js';++const root = globalThis.document?.getElementById('player');+const failure = globalThis.document?.getElementById('failure');+const title = globalThis.document?.getElementById('title');+const prose = globalThis.document?.getElementById('prose');+const narration = globalThis.document?.getElementById('narration');+const ending = globalThis.document?.getElementById('ending');+const status = globalThis.document?.getElementById('status');+const choices = globalThis.document?.getElementById('choices');+const composer = globalThis.document?.getElementById('composer');+const message = globalThis.document?.getElementById('message');+const video = globalThis.document?.getElementById('stage');+const play = globalThis.document?.getElementById('play');++function text(element, value) {+ if (element) element.textContent = value ?? '';+}++function showFailure(value) {+ if (!failure) return;+ failure.hidden = !value;+ text(failure, value || '');+}++function outcome(turn, speechStatus) {+ return {+ status: speechStatus,+ turnId: turn.turnId,+ nodeId: turn.nodeId,+ episodeId: turn.episodeId,+ generation: turn.generation,+ };+}++function speak(turn, hooks) {+ if (typeof hooks.completeSpeech === 'function') return Promise.resolve(hooks.completeSpeech(turn));+ if (!turn.text) return Promise.resolve(outcome(turn, 'empty'));+ text(narration, turn.text);+ if (narration) narration.hidden = false;+ const synth = globalThis.speechSynthesis;+ const Utterance = globalThis.SpeechSynthesisUtterance;+ if (!synth || typeof Utterance !== 'function') return Promise.resolve(outcome(turn, 'unavailable'));+ return new Promise((resolve) => {+ let settled = false;+ let timer = 0;+ const finish = (speechStatus) => {+ if (settled) return;+ settled = true;+ globalThis.clearTimeout(timer);+ resolve(outcome(turn, speechStatus));+ };+ try {+ const utter = new Utterance(turn.text);+ utter.onend = () => finish('completed');+ utter.onerror = () => finish('failed');+ // Some browsers never fire onend or onerror. A bounded failure leaves the scene in place.+ const limit = Math.min(60000, 5000 + turn.text.length * 100);+ timer = globalThis.setTimeout(() => {+ try { synth.cancel(); } catch { /* a stalled voice may already be gone */ }+ finish('failed');+ }, limit);+ synth.cancel();+ synth.speak(utter);+ } catch {+ finish('failed');+ }+ });+}++function bind(session) {+ let shown = null;+ let detachLoad = () => {};+ function paint() {+ const snap = session.snapshot();+ if (root) {+ root.dataset.node = snap.nodeId || '';+ root.dataset.phase = snap.phase;+ root.dataset.turn = snap.turnPhase;+ root.dataset.ended = snap.ended ? 'true' : 'false';+ }+ text(title, snap.title);+ globalThis.document.title = snap.title || 'Story';+ text(prose, snap.prose);+ text(narration, snap.narration);+ if (narration) narration.hidden = !snap.narration;+ const showEnding = snap.phase === 'ended' && snap.ended;+ if (ending) ending.hidden = !showEnding;+ text(ending, showEnding ? snap.endingLabel : '');+ text(status, snap.status || (snap.turnPhase === 'idle' ? '' : snap.turnPhase));+ if (composer) composer.hidden = snap.turnPhase !== 'listening';+ if (message) message.disabled = snap.turnPhase !== 'listening';+ choices?.replaceChildren(...snap.choices.map((choice) => {+ const button = globalThis.document.createElement('button');+ button.type = 'button';+ button.dataset.choice = choice.id;+ text(button, choice.intent);+ if (choice.description) button.title = choice.description;+ button.addEventListener('click', () => {+ session.choose(choice.id).then(() => paint()).catch(() => paint());+ });+ return button;+ }));+ if (!snap.media || !mediaUrl(snap.media.url.replace(/^\.\.\//, ''))) {+ shown = null;+ detachLoad();+ detachLoad = () => {};+ if (video) {+ video.hidden = true;+ video.removeAttribute('src');+ delete video.dataset.clip;+ }+ if (play) play.hidden = true;+ } else if (video && shown !== snap.media.generation) {+ shown = snap.media.generation;+ detachLoad();+ const generation = snap.media.generation;+ const looping = snap.media.loop === true;+ const onEnded = () => {+ if (looping) return;+ detachLoad();+ detachLoad = () => {};+ session.onMediaEnded(generation);+ paint();+ };+ const onError = () => {+ if (!video.getAttribute('src')) return;+ detachLoad();+ detachLoad = () => {};+ session.noteMediaFailure(generation);+ paint();+ };+ detachLoad = () => {+ video.removeEventListener('ended', onEnded);+ video.removeEventListener('error', onError);+ };+ video.addEventListener('ended', onEnded);+ video.addEventListener('error', onError);+ video.hidden = snap.phase === 'ended';+ video.dataset.clip = String(generation);+ video.src = snap.media.url;+ video.loop = looping;+ if (play) play.hidden = true;+ video.play().then(() => {+ if (play) play.hidden = true;+ }).catch(() => {+ if (shown === generation && play) play.hidden = false;+ });+ }+ }+ play?.addEventListener('click', () => {+ video?.play().then(() => {+ play.hidden = true;+ }).catch(() => {+ play.hidden = false;+ });+ });+ choices?.addEventListener('keydown', (event) => {+ const buttons = [...choices.querySelectorAll('button')];+ const index = buttons.indexOf(globalThis.document.activeElement);+ if (index < 0) return;+ const next = event.key === 'ArrowRight' || event.key === 'ArrowDown' ? 1+ : event.key === 'ArrowLeft' || event.key === 'ArrowUp' ? -1 : 0;+ if (!next) return;+ event.preventDefault();+ buttons[(index + next + buttons.length) % buttons.length].focus();+ });+ composer?.addEventListener('submit', (event) => {+ event.preventDefault();+ const typed = message?.value ?? '';+ if (message) message.value = '';+ session.submit(typed).then(() => paint()).catch(() => paint());+ });+ return paint;+}++async function boot() {+ try {+ if (!root) return;+ const hooks = globalThis.FableLoomPlayer || {};+ const address = new URL('../manifest.json', import.meta.url);+ const response = await globalThis.fetch(address);+ if (!response.ok) throw new Error('The story package is missing manifest.json.');+ const manifest = await response.json();+ const requested = new URL(globalThis.location.href).searchParams.get('episode');+ let repaint = () => {};+ const session = createSession(manifest, {+ episodeId: requested || undefined,+ resolveTurn: typeof hooks.resolveTurn === 'function' ? hooks.resolveTurn : undefined,+ onSpeak: (turn) => speak(turn, hooks),+ onChange: () => repaint(),+ });+ repaint = bind(session);+ globalThis.FableLoomPlayer = { ...hooks, session, repaint };+ repaint();+ } catch (error) {+ showFailure(error instanceof Error ? error.message : 'The story package could not be read.');+ }+}++void boot();diff --git a/server/services/fableLoom/static-player/runtime.js b/server/services/fableLoom/static-player/runtime.jsnew file mode 100644index 0000000000..8416c7fc23--- /dev/null+++ b/server/services/fableLoom/static-player/runtime.js@@ -0,0 +1,476 @@+/**+ * Dependency-free playback for an exported package. The page copies authored+ * strings into the DOM as text. This module never fetches, and it never treats+ * a model-supplied target as a scene id.+ */++const TURN_PHASES = new Set(['idle', 'listening', 'thinking', 'speaking']);++function major(version) {+ const match = typeof version === 'string' ? /^(\d+)\.\d+\.\d+$/.exec(version) : null;+ return match ? Number(match[1]) : null;+}++function normalizePhrase(value) {+ return String(value ?? '').trim().toLowerCase().replace(/\s+/g, ' ').replace(/[.!?]+$/g, '');+}++function nodeIndex(episode) {+ const nodes = new Map();+ for (const node of episode?.nodes || []) {+ if (node && typeof node.id === 'string' && node.id && !nodes.has(node.id)) nodes.set(node.id, node);+ }+ return nodes;+}++function presence(node) {+ const windowPresence = node?.interactionWindow?.enabled ? node.interactionWindow.protagonistPresence : null;+ if (windowPresence === 'onscreen' || windowPresence === 'offscreen') return windowPresence;+ return node?.protagonistPresence === 'onscreen' ? 'onscreen' : 'offscreen';+}++function occupancyBlocks(asset) {+ if (!asset || typeof asset !== 'object') return false;+ if (asset.safeForLiveVoice === false) return true;+ const occupancy = asset.audioOccupancy;+ if (!occupancy || typeof occupancy !== 'object') return false;+ // Recompute from the intervals. A stored safeForLiveVoice true cannot override them.+ const peak = Number.isFinite(occupancy.truePeakDb) ? occupancy.truePeakDb+ : (Number.isFinite(occupancy.peakDb) ? occupancy.peakDb : null);+ if (occupancy.safeForLiveVoice === false || occupancy.clipping === true+ || occupancy.clipped === true || occupancy.clippingDetected === true+ || (peak !== null && peak > 0)) return true;+ if (Array.isArray(occupancy.characterDialogue) && occupancy.characterDialogue.length > 0) return true;+ if (Array.isArray(occupancy.effects) && occupancy.effects.some((effect) => effect?.blocking === true)) return true;+ return false;+}++/** Package-relative media only. Anything else, including a remote URL, is unusable. */+export function mediaUrl(file) {+ if (typeof file !== 'string' || !/^media\/[a-f0-9]{64}\.[a-z0-9]+$/.test(file)) return null;+ return `../${file}`;+}++function assetFile(asset) {+ return asset && mediaUrl(asset.file) ? asset : null;+}++export function liveInputAllowed(node, phase, asset) {+ if (!node) return { allowed: false, reason: 'NODE_NOT_FOUND' };+ if (node.isEnding) return { allowed: false, reason: 'STORY_ENDED' };+ if (node.audienceConnection !== 'connected') return { allowed: false, reason: 'AUDIENCE_DISCONNECTED' };+ if (node.playbackMode !== 'decision') return { allowed: false, reason: 'PLAYBACK_NOT_DECISION' };+ if (phase !== 'hold') return { allowed: false, reason: 'PLAYBACK_NOT_IN_HOLD_PHASE' };+ if (presence(node) === 'onscreen') return { allowed: false, reason: 'PROTAGONIST_ONSCREEN' };+ if (occupancyBlocks(asset)) return { allowed: false, reason: 'HOLD_ASSET_OCCUPIED_BY_DIALOGUE' };+ return { allowed: true };+}++function audienceCanChoose(manifest, node) {+ if (!node || node.isEnding || node.playbackMode !== 'decision') return false;+ if (manifest?.loom?.participationMode === 'helper') return node.audienceConnection === 'connected';+ return true;+}++function matchMessage(node, message) {+ if (!node) return { stay: '' };+ const normalized = normalizePhrase(message);+ const typed = String(message ?? '').trim();+ if (!normalized && !typed) return { stay: '' };+ const matches = [];+ for (const transition of node.transitions || []) {+ if (!transition || typeof transition.id !== 'string') continue;+ const phrases = [transition.intent, ...(Array.isArray(transition.triggers) ? transition.triggers : [])];+ const exact = transition.id === typed || phrases.some((phrase) => normalizePhrase(phrase) === normalized && normalized);+ if (exact) matches.push(transition);+ }+ if (matches.length !== 1) {+ return { stay: matches.length > 1 ? 'That could follow more than one path.' : 'Nothing on this scene answers that.' };+ }+ return { move: matches[0].id };+}++/**+ * Exact intent, trigger, or transition id. Several matches and zero matches+ * stay. No request leaves this function. The first episode that contains the+ * node id wins; a live session matches only its current episode.+ */+export function createKeywordResolver(manifest) {+ const episodes = new Map((manifest?.loom?.episodes || []).map((episode) => [episode.id, episode]));+ return function resolveTurn(nodeId, message) {+ let node = null;+ for (const episode of episodes.values()) {+ node = nodeIndex(episode).get(nodeId) || null;+ if (node) break;+ }+ return matchMessage(node, message);+ };+}++function speechOutcome(turn, outcome) {+ const status = outcome?.status;+ const known = status === 'completed' || status === 'empty' || status === 'failed'+ || status === 'cancelled' || status === 'unavailable' || status === 'missing';+ if (!known || outcome.turnId !== turn.id || outcome.nodeId !== turn.nodeId) {+ return { status: 'missing', turnId: turn.id, nodeId: turn.nodeId };+ }+ if (outcome.episodeId !== undefined && outcome.episodeId !== turn.episodeId) {+ return { status: 'missing', turnId: turn.id, nodeId: turn.nodeId };+ }+ if (outcome.generation !== undefined && outcome.generation !== turn.generation) {+ return { status: 'missing', turnId: turn.id, nodeId: turn.nodeId };+ }+ return { status, turnId: turn.id, nodeId: turn.nodeId };+}++/**+ * One episode of a versioned manifest. `resolveTurn` may be async. A move is+ * committed only after speech reports `completed` or an explicit `empty`.+ */+export function createSession(manifest, options = {}) {+ if (major(manifest?.schemaVersion) !== 1 || major(manifest?.runtimeVersion) !== 1) {+ throw Object.assign(new Error('This player supports package schema and runtime major version 1 only.'), { code: 'UNSUPPORTED_VERSION' });+ }+ const episodes = new Map();+ for (const episode of manifest?.loom?.episodes || []) {+ if (episode && typeof episode.id === 'string' && !episodes.has(episode.id)) episodes.set(episode.id, episode);+ }+ if (!episodes.size) {+ throw Object.assign(new Error('The package has no episodes.'), { code: 'MANIFEST_INVALID' });+ }+ let episodeId = episodes.has(options.episodeId) ? options.episodeId : manifest.loom.episodes[0].id;+ let nodes = nodeIndex(episodes.get(episodeId));+ const resolver = typeof options.resolveTurn === 'function'+ ? options.resolveTurn+ : (nodeId, message) => matchMessage(nodes.get(nodeId) || null, message);+ let nodeId = null;+ let phase = 'entry';+ let turnPhase = 'idle';+ let generation = 0;+ let activeTurnId = 0;+ let holdIteration = 0;+ let pendingTransitionId = null;+ let narration = '';+ let status = '';+ let clipGeneration = 0;+ let consumedClip = null;+ let deferredEnd = null;++ function notify() {+ if (typeof options.onChange === 'function') options.onChange(snapshot());+ }+ function currentNode() {+ return nodes.get(nodeId) || null;+ }+ function sameTurn(turn) {+ return turn.id === activeTurnId && turn.generation === generation+ && turn.nodeId === nodeId && turn.episodeId === episodeId;+ }+ function invalidate() {+ generation += 1;+ activeTurnId += 1;+ }+ function holdAsset(node) {+ const holds = (node?.playbackAssets?.holds || []).filter(assetFile);+ if (!holds.length) return assetFile(node?.playbackAssets?.entry);+ const count = holds.length;+ const mode = node?.interactionWindow?.holdLoopRotation;+ const index = mode === 'shuffle' ? Math.abs(holdIteration * 17) % count : holdIteration % count;+ return holds[index] || holds[0];+ }+ function currentAsset() {+ const node = currentNode();+ if (!node) return null;+ if (phase === 'entry') return assetFile(node.playbackAssets?.entry);+ if (phase === 'hold') return holdAsset(node);+ if (phase === 'exit' && pendingTransitionId) {+ const exits = node.playbackAssets?.exits;+ if (exits && typeof exits === 'object' && Object.hasOwn(exits, pendingTransitionId)) {+ return assetFile(exits[pendingTransitionId]);+ }+ }+ return null;+ }+ function settleTurnPhase(node) {+ turnPhase = phase === 'hold' && liveInputAllowed(node, phase, currentAsset()).allowed ? 'listening' : 'idle';+ }+ function staleClip(generation) {+ return typeof generation === 'number' && (generation !== clipGeneration || consumedClip === generation);+ }+ function consumeClip(generation) {+ if (typeof generation === 'number') consumedClip = generation;+ }+ function replayDeferredEnd() {+ if (deferredEnd === null) return;+ const generation = deferredEnd;+ deferredEnd = null;+ onMediaEnded(generation);+ }+ function enterNode(id) {+ deferredEnd = null;+ invalidate();+ const node = nodes.get(id);+ pendingTransitionId = null;+ holdIteration = 0;+ narration = '';+ clipGeneration += 1;+ if (!node) {+ nodeId = null;+ phase = 'ended';+ turnPhase = 'idle';+ status = 'That scene is not in this episode.';+ return;+ }+ nodeId = node.id;+ status = '';+ if (node.isEnding) phase = assetFile(node.playbackAssets?.entry) ? 'entry' : 'ended';+ else if (assetFile(node.playbackAssets?.entry)) phase = 'entry';+ else phase = 'hold';+ settleTurnPhase(node);+ }+ function edgeTarget(node, transitionId) {+ const edge = (node?.transitions || []).find((transition) => transition?.id === transitionId);+ const target = edge ? nodes.get(edge.targetNodeId) : null;+ return edge && target ? { edge, target } : null;+ }+ function beginTransition(node, edge) {+ const target = nodes.get(edge.targetNodeId);+ if (!target) {+ status = 'That path is not on this scene.';+ turnPhase = 'idle';+ return { action: 'stay', reason: 'ABSENT_TRANSITION' };+ }+ const exits = node.playbackAssets?.exits;+ const exit = exits && typeof exits === 'object' && Object.hasOwn(exits, edge.id) ? assetFile(exits[edge.id]) : null;+ if (exit) {+ pendingTransitionId = edge.id;+ phase = 'exit';+ turnPhase = 'idle';+ narration = '';+ clipGeneration += 1;+ status = '';+ return { action: 'exit', transitionId: edge.id };+ }+ enterNode(target.id);+ return { action: 'move', transitionId: edge.id, nodeId: target.id };+ }+ function chips() {+ const node = currentNode();+ if (phase !== 'hold' || turnPhase === 'thinking' || turnPhase === 'speaking' || !audienceCanChoose(manifest, node)) {+ return [];+ }+ return (node.transitions || []).filter((transition) => edgeTarget(node, transition.id)).map((transition) => ({+ id: transition.id,+ intent: typeof transition.intent === 'string' ? transition.intent : transition.id,+ description: typeof transition.description === 'string' ? transition.description : '',+ }));+ }+ function snapshot() {+ const node = currentNode();+ const asset = currentAsset();+ const holds = (node?.playbackAssets?.holds || []).filter(assetFile);+ return {+ episodeId,+ nodeId,+ phase,+ turnPhase,+ generation,+ ended: phase === 'ended' && node?.isEnding === true,+ title: typeof node?.title === 'string' ? node.title : '',+ prose: typeof node?.prose === 'string' ? node.prose : '',+ narration,+ endingLabel: node?.isEnding ? (node.endingLabel || node.title || '') : '',+ status,+ choices: chips(),+ admission: liveInputAllowed(node, phase, asset),+ media: asset ? {+ url: mediaUrl(asset.file),+ loop: phase === 'hold' && holds.length <= 1,+ generation: clipGeneration,+ } : null,+ };+ }+ function reserve(nextPhase) {+ if (!TURN_PHASES.has(nextPhase)) throw new Error('Unknown turn phase.');+ activeTurnId += 1;+ turnPhase = nextPhase;+ const turn = { id: activeTurnId, nodeId, episodeId, generation };+ notify();+ return turn;+ }+ async function finishSpeech(turn, text) {+ if (typeof options.onSpeak !== 'function') {+ return { status: text ? 'missing' : 'empty', turnId: turn.id, nodeId: turn.nodeId };+ }+ let outcome;+ try {+ outcome = await options.onSpeak({ ...turn, turnId: turn.id, text });+ } catch {+ outcome = { status: 'failed', turnId: turn.id, nodeId: turn.nodeId };+ }+ return speechOutcome(turn, outcome);+ }+ async function commitMove(turn, node, edge) {+ turnPhase = 'speaking';+ notify();+ const outcome = await finishSpeech(turn, '');+ if (!sameTurn(turn)) return { accepted: false, reason: 'STALE' };+ if (outcome.status !== 'completed' && outcome.status !== 'empty') {+ settleTurnPhase(node);+ status = 'The turn did not finish speaking, so the scene stayed.';+ notify();+ replayDeferredEnd();+ return { accepted: false, action: 'stay', reason: outcome.status };+ }+ const moved = beginTransition(node, edge);+ if (moved.action === 'stay') replayDeferredEnd();+ else deferredEnd = null;+ notify();+ return { accepted: moved.action !== 'stay', ...moved, speech: outcome.status };+ }++ function onMediaEnded(generation) {+ if (staleClip(generation)) return { action: 'ignore', reason: 'STALE_CLIP' };+ const node = currentNode();+ // The page removes its ended listener before this returns, so a clip that+ // finishes during a turn has to be replayed once the turn settles.+ if (!node || turnPhase === 'thinking' || turnPhase === 'speaking') {+ if (node && typeof generation === 'number') deferredEnd = generation;+ return { action: 'ignore', reason: 'HALF_DUPLEX' };+ }+ consumeClip(generation);+ if (phase === 'exit') {+ const chosen = edgeTarget(node, pendingTransitionId);+ if (!chosen) {+ phase = 'ended';+ turnPhase = 'idle';+ status = 'That path is not on this scene.';+ notify();+ return { action: 'stay', reason: 'ABSENT_TRANSITION' };+ }+ enterNode(chosen.target.id);+ notify();+ return { action: 'move', transitionId: chosen.edge.id, nodeId: chosen.target.id };+ }+ if (phase === 'entry') {+ if (node.isEnding || !(node.transitions || []).length) {+ phase = 'ended';+ turnPhase = 'idle';+ notify();+ return { action: 'ended' };+ }+ if (node.playbackMode === 'cut') {+ const first = edgeTarget(node, node.transitions[0]?.id);+ const result = first ? beginTransition(node, first.edge) : { action: 'stay', reason: 'ABSENT_TRANSITION' };+ if (!first) {+ phase = 'ended';+ turnPhase = 'idle';+ status = 'That path is not on this scene.';+ }+ notify();+ return result;+ }+ phase = 'hold';+ clipGeneration += 1;+ settleTurnPhase(node);+ notify();+ return { action: 'hold' };+ }+ if (phase === 'hold') {+ const holds = (node.playbackAssets?.holds || []).filter(assetFile);+ if (holds.length > 1) {+ holdIteration += 1;+ clipGeneration += 1;+ }+ settleTurnPhase(node);+ notify();+ return { action: 'loop' };+ }+ return { action: 'ignore' };+ }++ const initial = nodes.get(episodes.get(episodeId).startNodeId);+ enterNode(initial ? initial.id : '');++ return {+ snapshot,+ selectEpisode(id) {+ if (!episodes.has(id)) return { ok: false, reason: 'EPISODE_NOT_FOUND' };+ episodeId = id;+ nodes = nodeIndex(episodes.get(id));+ const start = nodes.get(episodes.get(id).startNodeId);+ enterNode(start ? start.id : '');+ notify();+ return { ok: true, ...snapshot() };+ },+ noteMediaFailure(generation) {+ if (staleClip(generation)) return { action: 'ignore', reason: 'STALE_CLIP' };+ if (phase !== 'entry' && phase !== 'exit') {+ status = 'This clip could not be played.';+ notify();+ return { action: 'status' };+ }+ const beforeNode = nodeId;+ const beforePhase = phase;+ const moved = onMediaEnded(generation);+ if (nodeId === beforeNode && phase === beforePhase) {+ status = 'This clip could not be played.';+ notify();+ }+ return moved;+ },+ onMediaEnded,+ async choose(transitionId) {+ const node = currentNode();+ if (turnPhase === 'thinking' || turnPhase === 'speaking') return { accepted: false, reason: 'HALF_DUPLEX' };+ if (!chips().some((choice) => choice.id === transitionId)) {+ return { accepted: false, action: 'stay', reason: phase === 'hold' ? 'ABSENT_TRANSITION' : 'CHIPS_CLOSED' };+ }+ const chosen = edgeTarget(node, transitionId);+ if (!chosen) return { accepted: false, action: 'stay', reason: 'ABSENT_TRANSITION' };+ const turn = reserve('speaking');+ return commitMove(turn, node, chosen.edge);+ },+ async submit(message) {+ const node = currentNode();+ const admission = liveInputAllowed(node, phase, currentAsset());+ if (!admission.allowed) return { accepted: false, reason: admission.reason };+ if (turnPhase !== 'listening') return { accepted: false, reason: 'HALF_DUPLEX' };+ const turn = reserve('thinking');+ let verdict;+ try {+ verdict = await resolver(node.id, message);+ } catch {+ if (!sameTurn(turn)) return { accepted: false, reason: 'STALE' };+ turnPhase = 'listening';+ status = 'The turn could not be resolved.';+ notify();+ replayDeferredEnd();+ return { accepted: false, reason: 'RESOLVER_FAILED' };+ }+ if (!sameTurn(turn)) return { accepted: false, reason: 'STALE' };+ if (verdict && typeof verdict.move === 'string') {+ const chosen = edgeTarget(node, verdict.move);+ if (!chosen) {+ turnPhase = 'listening';+ narration = '';+ status = 'That path is not on this scene.';+ notify();+ replayDeferredEnd();+ return { accepted: false, action: 'stay', reason: 'ABSENT_TRANSITION' };+ }+ return commitMove(turn, node, chosen.edge);+ }+ narration = verdict && typeof verdict.stay === 'string' ? verdict.stay : '';+ status = '';+ turnPhase = 'speaking';+ notify();+ const outcome = await finishSpeech(turn, narration);+ if (!sameTurn(turn)) return { accepted: false, reason: 'STALE' };+ turnPhase = 'listening';+ notify();+ replayDeferredEnd();+ return { accepted: true, action: 'stay', narration, speech: outcome.status };+ },+ };+}diff --git a/server/services/fableLoom/static-player/runtime.test.js b/server/services/fableLoom/static-player/runtime.test.jsnew file mode 100644index 0000000000..3ff5bd87ef--- /dev/null+++ b/server/services/fableLoom/static-player/runtime.test.js@@ -0,0 +1,430 @@+import { readdir, readFile } from 'node:fs/promises';+import { describe, expect, it } from 'vitest';+import { FABLELOOM_STATIC_PLAYER_FILES } from '../staticPlayerFiles.js';+import { createKeywordResolver, createSession, liveInputAllowed, mediaUrl } from './runtime.js';++const HASH = 'a'.repeat(64);+const clip = (mark = 'a', extra = {}) => ({+ file: `media/${mark.repeat(64)}.mp4`, durationMs: 1000, loopable: true, ...extra,+});++function node(id, extra) {+ return {+ id, title: id, prose: `${id} prose`, playbackMode: 'decision', audienceConnection: 'connected',+ protagonistPresence: 'offscreen', isEnding: false, endingLabel: '', transitions: [],+ playbackAssets: { still: null, entry: null, holds: [], exits: {} }, ...extra,+ };+}++function story() {+ return {+ schemaVersion: '1.0.0',+ runtimeVersion: '1.0.0',+ loom: {+ name: 'Example gate',+ participationMode: 'protagonist',+ episodes: [+ {+ id: 'episode-one', title: 'Gate', startNodeId: 'cut-open',+ nodes: [+ node('cut-open', {+ title: 'Opening',+ prose: 'A gate.<img src="x" onerror="alert(1)"><script>alert(1)</script>',+ playbackMode: 'cut', audienceConnection: 'disconnected',+ transitions: [+ { id: 'arrive', intent: 'Arrive', triggers: [], description: 'Onward', targetNodeId: 'decision-gate' },+ { id: 'skip', intent: 'Skip', triggers: [], description: '', targetNodeId: 'other-target' },+ ],+ playbackAssets: { still: null, entry: clip(), holds: [], exits: {} },+ }),+ node('other-target', {+ title: 'Wrong', prose: 'Wrong path', playbackMode: 'cut', audienceConnection: 'disconnected',+ playbackAssets: { still: null, entry: clip(), holds: [], exits: {} },+ }),+ node('decision-gate', {+ title: 'The gate', prose: 'The gate holds.',+ transitions: [+ { id: 'wait', intent: 'Wait here', triggers: ['wait here'], description: 'Stay', targetNodeId: 'decision-gate' },+ { id: 'open', intent: 'Open the gate', triggers: ['open the gate'], description: 'Leave', targetNodeId: 'ending-home' },+ ],+ playbackAssets: {+ still: null, entry: null, exits: {},+ holds: [clip('a', { audioOccupancy: { safeForLiveVoice: true, characterDialogue: [], effects: [], clipping: false } })],+ },+ }),+ node('ending-home', {+ title: 'Home', prose: 'Home.', playbackMode: 'cut', audienceConnection: 'disconnected',+ isEnding: true, endingLabel: 'Home',+ playbackAssets: { still: null, entry: clip(), holds: [], exits: {} },+ }),+ ],+ },+ {+ id: 'episode-other', title: 'Other', startNodeId: 'other-start',+ nodes: [node('other-start', { title: 'Elsewhere', prose: 'Elsewhere.', playbackAssets: { still: null, entry: null, holds: [clip()], exits: {} } })],+ },+ ],+ },+ };+}++const gateOf = (manifest) => manifest.loom.episodes[0].nodes.find((item) => item.id === 'decision-gate');+const echo = (status) => (turn) => ({+ status, turnId: turn.turnId, nodeId: turn.nodeId, episodeId: turn.episodeId, generation: turn.generation,+});+const atGate = (manifest, options) => {+ const session = createSession(manifest, options);+ expect(session.onMediaEnded().nodeId).toBe('decision-gate');+ return session;+};++describe('static reference player runtime', () => {+ it('matches one exact phrase or id and does not call the network', () => {+ const resolve = createKeywordResolver(story());+ const original = globalThis.fetch;+ let calls = 0;+ globalThis.fetch = () => { calls += 1; throw new Error('network'); };+ try {+ expect(resolve('decision-gate', ' Open the GATE! ')).toEqual({ move: 'open' });+ expect(resolve('decision-gate', 'open')).toEqual({ move: 'open' });+ expect(resolve('decision-gate', 'Open')).toEqual({ stay: 'Nothing on this scene answers that.' });+ expect(resolve('decision-gate', 'gate')).toEqual({ stay: 'Nothing on this scene answers that.' });+ expect(resolve('decision-gate', '')).toEqual({ stay: '' });+ expect(calls).toBe(0);+ } finally {+ globalThis.fetch = original;+ }+ });++ it('matches the current episode when another episode reuses the scene id', async () => {+ const manifest = story();+ const other = manifest.loom.episodes[1];+ other.startNodeId = 'decision-gate';+ other.nodes = [node('decision-gate', {+ transitions: [{ id: 'wrong', intent: 'Open the gate', triggers: ['open the gate'], description: '', targetNodeId: 'decision-gate' }],+ playbackAssets: { still: null, entry: null, holds: [clip()], exits: {} },+ })];+ manifest.loom.episodes.reverse();+ const session = createSession(manifest, { onSpeak: echo('empty') });+ session.selectEpisode('episode-one');+ expect(session.onMediaEnded().nodeId).toBe('decision-gate');+ expect(await session.submit('open the gate')).toMatchObject({ action: 'move', nodeId: 'ending-home' });+ });++ it('stays when a phrase matches more than one edge', () => {+ const manifest = story();+ gateOf(manifest).transitions.push({ id: 'also', intent: 'Also open', triggers: ['open the gate'], description: '', targetNodeId: 'ending-home' });+ expect(createKeywordResolver(manifest)('decision-gate', 'open the gate')).toEqual({ stay: 'That could follow more than one path.' });+ });++ it('plays a cut into a decision hold and then an ending', async () => {+ const session = createSession(story());+ expect(session.snapshot()).toMatchObject({ nodeId: 'cut-open', phase: 'entry', prose: expect.stringContaining('<script>') });+ expect(await session.choose('arrive')).toMatchObject({ reason: 'CHIPS_CLOSED' });+ expect(session.onMediaEnded()).toMatchObject({ action: 'move', nodeId: 'decision-gate' });+ const held = session.snapshot();+ expect(held).toMatchObject({ phase: 'hold', turnPhase: 'listening', media: { loop: true } });+ expect(held.choices.map((choice) => choice.id)).toEqual(['wait', 'open']);+ const generation = held.media.generation;+ expect(session.onMediaEnded()).toMatchObject({ action: 'loop' });+ expect(session.snapshot()).toMatchObject({ nodeId: 'decision-gate', media: { generation } });+ expect(await session.choose('wait')).toMatchObject({ action: 'move', nodeId: 'decision-gate' });+ expect(await session.submit('open the gate')).toMatchObject({ action: 'move', nodeId: 'ending-home' });+ expect(session.snapshot()).toMatchObject({ phase: 'entry', choices: [], turnPhase: 'idle' });+ expect(session.onMediaEnded()).toMatchObject({ action: 'ended' });+ expect(session.snapshot()).toMatchObject({ phase: 'ended', ended: true, endingLabel: 'Home', choices: [] });+ expect(await session.submit('open the gate')).toMatchObject({ reason: 'STORY_ENDED' });+ });++ it('ends a cut whose first edge has no target and does not take a later edge', () => {+ const missing = story();+ missing.loom.episodes[0].nodes[0].transitions[0].targetNodeId = 'missing-node';+ const session = createSession(missing);+ expect(session.onMediaEnded()).toMatchObject({ reason: 'ABSENT_TRANSITION' });+ expect(session.snapshot()).toMatchObject({ nodeId: 'cut-open', phase: 'ended', ended: false });+ });++ it('obeys a custom resolver and refuses an absent transition', async () => {+ const session = atGate(story(), {+ onSpeak: echo('empty'),+ resolveTurn: async (_nodeId, message) => (+ message === 'go' ? { move: 'open', targetNodeId: 'other-target' } : { move: 'not-real' }+ ),+ });+ expect(await session.submit('missing')).toMatchObject({ action: 'stay', reason: 'ABSENT_TRANSITION' });+ expect(session.snapshot().nodeId).toBe('decision-gate');+ expect(await session.submit('go')).toMatchObject({ action: 'move', nodeId: 'ending-home' });+ });++ it('shows stay text without leaving the scene', async () => {+ const session = atGate(story(), { resolveTurn: async () => ({ stay: 'Not yet.' }) });+ expect(await session.submit('hello')).toMatchObject({ action: 'stay', narration: 'Not yet.', speech: 'missing' });+ expect(session.snapshot()).toMatchObject({ nodeId: 'decision-gate', narration: 'Not yet.', turnPhase: 'listening' });+ });++ it.each(['failed', 'cancelled', 'unavailable', 'missing'])('%s speech does not commit a move', async (status) => {+ const session = atGate(story(), { onSpeak: echo(status) });+ expect(await session.choose('open')).toMatchObject({ accepted: false, action: 'stay' });+ expect(session.snapshot().nodeId).toBe('decision-gate');+ });++ it('commits a move after completed or explicit empty speech', async () => {+ for (const status of ['completed', 'empty']) {+ const session = atGate(story(), { onSpeak: echo(status) });+ expect(await session.choose('open')).toMatchObject({ accepted: true, nodeId: 'ending-home', speech: status });+ }+ });++ it('rejects a completed outcome that names another generation', async () => {+ const session = atGate(story(), {+ onSpeak: (turn) => ({ ...echo('completed')(turn), generation: turn.generation - 1 }),+ });+ expect(await session.choose('open')).toMatchObject({ accepted: false });+ expect(session.snapshot().nodeId).toBe('decision-gate');+ });++ it('holds an exit clip until that clip ends', async () => {+ const manifest = story();+ gateOf(manifest).playbackAssets.exits = { open: clip('e') };+ let finish = () => {};+ const session = atGate(manifest, {+ onSpeak: (turn) => new Promise((resolve) => {+ finish = () => resolve(echo('empty')(turn));+ }),+ });+ const pending = session.choose('open');+ expect(session.snapshot().turnPhase).toBe('speaking');+ expect(session.onMediaEnded()).toMatchObject({ reason: 'HALF_DUPLEX' });+ expect(session.snapshot().nodeId).toBe('decision-gate');+ finish();+ expect(await pending).toMatchObject({ action: 'exit' });+ expect(session.snapshot()).toMatchObject({ nodeId: 'decision-gate', phase: 'exit' });+ expect(session.onMediaEnded()).toMatchObject({ nodeId: 'ending-home' });+ });++ it('refuses a second submit while a turn is in flight', async () => {+ let calls = 0;+ const session = atGate(story(), {+ resolveTurn: () => { calls += 1; return new Promise(() => {}); },+ });+ void session.submit('hello');+ expect(await session.submit('again')).toMatchObject({ reason: 'HALF_DUPLEX' });+ expect(await session.choose('open')).toMatchObject({ reason: 'HALF_DUPLEX' });+ expect(calls).toBe(1);+ expect(session.snapshot().nodeId).toBe('decision-gate');+ });++ it('drops a resolver reply and a speech result after the episode changes', async () => {+ let release = () => {};+ let finish = () => {};+ const spoken = atGate(story(), {+ onSpeak: (turn) => new Promise((resolve) => { finish = () => resolve(echo('completed')(turn)); }),+ });+ const moving = spoken.choose('open');+ expect(spoken.selectEpisode('episode-other').nodeId).toBe('other-start');+ finish();+ expect(await moving).toMatchObject({ reason: 'STALE' });+ expect(spoken.snapshot()).toMatchObject({ nodeId: 'other-start', episodeId: 'episode-other' });++ const resolved = atGate(story(), {+ resolveTurn: () => new Promise((resolve) => { release = () => resolve({ move: 'open' }); }),+ });+ const pending = resolved.submit('go');+ expect(resolved.snapshot().turnPhase).toBe('thinking');+ resolved.selectEpisode('episode-other');+ release();+ expect(await pending).toMatchObject({ reason: 'STALE' });+ expect(resolved.snapshot().nodeId).toBe('other-start');+ expect(resolved.selectEpisode('missing')).toMatchObject({ ok: false, reason: 'EPISODE_NOT_FOUND' });+ });++ it('keeps choice chips and live text on different admission lanes', async () => {+ const disconnected = story();+ gateOf(disconnected).audienceConnection = 'disconnected';+ const protagonist = atGate(disconnected, { onSpeak: echo('empty') });+ expect(protagonist.snapshot().choices.map((choice) => choice.id)).toEqual(['wait', 'open']);+ expect(await protagonist.submit('open the gate')).toMatchObject({ reason: 'AUDIENCE_DISCONNECTED' });+ expect(await protagonist.choose('open')).toMatchObject({ nodeId: 'ending-home' });++ const helperManifest = story();+ helperManifest.loom.participationMode = 'helper';+ gateOf(helperManifest).audienceConnection = 'disconnected';+ const helper = atGate(helperManifest);+ expect(helper.snapshot().choices).toEqual([]);+ expect(await helper.submit('open the gate')).toMatchObject({ reason: 'AUDIENCE_DISCONNECTED' });++ const connected = story();+ connected.loom.participationMode = 'helper';+ const helped = atGate(connected, { onSpeak: echo('empty') });+ expect(helped.snapshot().choices).toHaveLength(2);+ expect(await helped.submit('open the gate')).toMatchObject({ nodeId: 'ending-home' });+ });++ it('refuses live text for an onscreen protagonist or occupied hold audio', async () => {+ const onscreen = story();+ gateOf(onscreen).protagonistPresence = 'onscreen';+ const present = atGate(onscreen);+ expect(present.snapshot().choices).toHaveLength(2);+ expect(await present.submit('open the gate')).toMatchObject({ reason: 'PROTAGONIST_ONSCREEN' });++ const windowed = story();+ const scene = gateOf(windowed);+ scene.interactionWindow = { enabled: true, protagonistPresence: 'onscreen' };+ expect(await atGate(windowed).submit('open the gate')).toMatchObject({ reason: 'PROTAGONIST_ONSCREEN' });++ const occupied = story();+ gateOf(occupied).playbackAssets.holds[0].audioOccupancy = {+ safeForLiveVoice: true, characterDialogue: [{ startMs: 0, endMs: 10 }], effects: [],+ };+ expect(await atGate(occupied).submit('open the gate')).toMatchObject({ reason: 'HOLD_ASSET_OCCUPIED_BY_DIALOGUE' });+ expect(liveInputAllowed(gateOf(occupied), 'hold', gateOf(occupied).playbackAssets.holds[0]).allowed).toBe(false);++ const blocked = story();+ gateOf(blocked).playbackAssets.holds[0].audioOccupancy = {+ safeForLiveVoice: true, characterDialogue: [], effects: [{ blocking: true }], clipping: false,+ };+ expect(await atGate(blocked).submit('open the gate')).toMatchObject({ reason: 'HOLD_ASSET_OCCUPIED_BY_DIALOGUE' });+ });++ it('rotates several holds and reloads when an entry becomes a hold', () => {+ const manifest = story();+ const gate = gateOf(manifest);+ gate.playbackAssets.entry = clip('c');+ gate.playbackAssets.holds = [clip('a'), clip('b')];+ const session = createSession(manifest);+ expect(session.onMediaEnded()).toMatchObject({ nodeId: 'decision-gate' });+ expect(session.snapshot().phase).toBe('entry');+ const generation = session.snapshot().media.generation;+ expect(session.onMediaEnded()).toMatchObject({ action: 'hold' });+ const held = session.snapshot();+ expect(held).toMatchObject({ phase: 'hold', media: { loop: false } });+ expect(held.media.generation).toBe(generation + 1);+ const first = held.media.url;+ expect(session.onMediaEnded()).toMatchObject({ action: 'loop' });+ expect(session.snapshot()).toMatchObject({ nodeId: 'decision-gate' });+ expect(session.snapshot().media.url).not.toBe(first);+ });++ it('rejects an unsupported package and an unsafe media path', () => {+ expect(() => createSession({ ...story(), schemaVersion: '2.0.0' })).toThrow(/major version 1/);+ expect(() => createSession({ ...story(), runtimeVersion: '9.0.0' })).toThrow(/major version 1/);+ expect(() => createSession({ schemaVersion: '1.0.0', runtimeVersion: '1.0.0', loom: { episodes: [] } })).toThrow(/no episodes/);+ expect(mediaUrl(`media/${HASH}.mp4`)).toBe(`../media/${HASH}.mp4`);+ for (const bad of ['https://example.invalid/a.mp4', '../media/x.mp4', `media/${'a'.repeat(63)}.mp4`, `media/${'g'.repeat(64)}.mp4`]) {+ expect(mediaUrl(bad)).toBeNull();+ }+ });++ it('treats a speech failure thrown by the host as a missed completion', async () => {+ const session = atGate(story(), { onSpeak: async () => { throw new Error('playback failed'); } });+ expect(await session.choose('open')).toMatchObject({ accepted: false, action: 'stay', reason: 'failed' });+ expect(session.snapshot()).toMatchObject({ nodeId: 'decision-gate', turnPhase: 'listening' });+ });++ it('reports a failed resolver without leaving the scene', async () => {+ const session = atGate(story(), { resolveTurn: async () => { throw new Error('boom'); } });+ expect(await session.submit('hello')).toMatchObject({ reason: 'RESOLVER_FAILED' });+ expect(session.snapshot()).toMatchObject({ nodeId: 'decision-gate', turnPhase: 'listening' });+ });++ it('rotates a hold that ended during a turn and does not carry that end into the next scene', async () => {+ const manifest = story();+ const gate = gateOf(manifest);+ gate.playbackAssets.entry = null;+ gate.playbackAssets.holds = [clip('a'), clip('b')];+ let release = () => {};+ const staying = atGate(manifest, {+ resolveTurn: () => new Promise((resolve) => { release = () => resolve({ stay: 'Not yet.' }); }),+ });+ const before = staying.snapshot();+ const pendingStay = staying.submit('hello');+ expect(staying.onMediaEnded(before.media.generation)).toMatchObject({ reason: 'HALF_DUPLEX' });+ expect(staying.snapshot().media.url).toBe(before.media.url);+ release();+ expect(await pendingStay).toMatchObject({ action: 'stay', narration: 'Not yet.' });+ expect(staying.snapshot()).toMatchObject({ nodeId: 'decision-gate', turnPhase: 'listening' });+ expect(staying.snapshot().media.url).not.toBe(before.media.url);++ let finishFail = () => {};+ const failing = atGate(manifest, {+ onSpeak: (turn) => new Promise((resolve) => { finishFail = () => resolve(echo('failed')(turn)); }),+ });+ const held = failing.snapshot();+ const pendingFail = failing.choose('open');+ expect(failing.onMediaEnded(held.media.generation)).toMatchObject({ reason: 'HALF_DUPLEX' });+ finishFail();+ expect(await pendingFail).toMatchObject({ accepted: false, reason: 'failed' });+ expect(failing.snapshot()).toMatchObject({ nodeId: 'decision-gate', turnPhase: 'listening' });+ expect(failing.snapshot().media.url).not.toBe(held.media.url);++ let finish = () => {};+ const moving = atGate(story(), {+ onSpeak: (turn) => new Promise((resolve) => { finish = () => resolve(echo('empty')(turn)); }),+ });+ const generation = moving.snapshot().media.generation;+ const pendingMove = moving.choose('open');+ expect(moving.onMediaEnded(generation)).toMatchObject({ reason: 'HALF_DUPLEX' });+ finish();+ expect(await pendingMove).toMatchObject({ nodeId: 'ending-home' });+ expect(moving.snapshot()).toMatchObject({ nodeId: 'ending-home', phase: 'entry' });+ });++ it('advances a failed entry or exit once and leaves a failed hold in place', async () => {+ const opening = createSession(story());+ const generation = opening.snapshot().media.generation;+ expect(opening.noteMediaFailure(generation)).toMatchObject({ action: 'move', nodeId: 'decision-gate' });+ expect(opening.snapshot()).toMatchObject({ nodeId: 'decision-gate', phase: 'hold', status: '' });+ expect(opening.noteMediaFailure(generation)).toMatchObject({ reason: 'STALE_CLIP' });+ expect(opening.onMediaEnded(generation)).toMatchObject({ reason: 'STALE_CLIP' });+ expect(opening.snapshot().nodeId).toBe('decision-gate');++ const held = opening.snapshot();+ expect(opening.noteMediaFailure(held.media.generation)).toMatchObject({ action: 'status' });+ expect(opening.snapshot()).toMatchObject({+ nodeId: 'decision-gate',+ phase: 'hold',+ status: 'This clip could not be played.',+ media: { generation: held.media.generation },+ });++ const missing = story();+ missing.loom.episodes[0].nodes[0].transitions[0].targetNodeId = 'missing-node';+ const stuck = createSession(missing);+ const stuckGeneration = stuck.snapshot().media.generation;+ expect(stuck.noteMediaFailure(stuckGeneration)).toMatchObject({ reason: 'ABSENT_TRANSITION' });+ expect(stuck.snapshot()).toMatchObject({ nodeId: 'cut-open', phase: 'ended' });+ expect(stuck.onMediaEnded(stuckGeneration)).toMatchObject({ reason: 'STALE_CLIP' });++ const exiting = story();+ gateOf(exiting).playbackAssets.exits = { open: clip('e') };+ const gate = atGate(exiting, { onSpeak: echo('empty') });+ expect(await gate.choose('open')).toMatchObject({ action: 'exit' });+ const exitGeneration = gate.snapshot().media.generation;+ expect(gate.noteMediaFailure(exitGeneration)).toMatchObject({ action: 'move', nodeId: 'ending-home' });+ expect(gate.snapshot()).toMatchObject({ nodeId: 'ending-home', status: '' });+ expect(gate.onMediaEnded(exitGeneration)).toMatchObject({ reason: 'STALE_CLIP' });+ });++ it('ships only the dependency-free player templates', async () => {+ const names = await readdir(new URL('.', import.meta.url));+ const extras = names.filter((name) => !FABLELOOM_STATIC_PLAYER_FILES.includes(name));+ expect(extras.every((name) => name.endsWith('.test.js'))).toBe(true);+ const banned = /https?:\/\/|localhost|127\.0\.0\.1|api\/fableloom|bearer|ngrok|tailscale|cloudflare|password|api key|secret|\bportos\b/i;+ for (const name of FABLELOOM_STATIC_PLAYER_FILES) {+ const text = (await readFile(new URL(name, import.meta.url), 'utf8')).replaceAll('portos-allow-hidden-content', '');+ expect(text, name).not.toMatch(banned);+ if (name !== 'contract-example.js' && name !== 'player.js') expect(text).not.toMatch(/\bfetch\s*\(/);+ }+ const html = await readFile(new URL('index.html', import.meta.url), 'utf8');+ const player = await readFile(new URL('player.js', import.meta.url), 'utf8');+ const contract = await readFile(new URL('contract-example.js', import.meta.url), 'utf8');+ expect(html.match(/<script/g)).toHaveLength(1);+ expect(html).toContain('<script type="module" src="player.js"></script><!-- portos-allow-hidden-content -->');+ expect(html.match(/portos-allow-hidden-content/g)).toHaveLength(1);+ expect(html).not.toContain('contract-example');+ expect(player.match(/\bfetch\s*\(/g)).toHaveLength(1);+ expect(player).not.toContain('innerHTML');+ expect(contract).toContain("'/story/turn'");+ expect(contract).not.toMatch(/export function/);+ });+});diff --git a/server/services/fableLoom/staticPlayerFiles.js b/server/services/fableLoom/staticPlayerFiles.jsnew file mode 100644index 0000000000..d3d211af6f--- /dev/null+++ b/server/services/fableLoom/staticPlayerFiles.js@@ -0,0 +1,9 @@+/** Filenames copied into an export's player/ directory. Tests and the packer share this list. */+export const FABLELOOM_STATIC_PLAYER_FILES = Object.freeze([+ 'README.md',+ 'contract-example.js',+ 'index.html',+ 'player.css',+ 'player.js',+ 'runtime.js',+]);