@animastor/player 0.1.0

package/src/playback-queue.cjs

@@ -0,0 +1,246 @@
+// ======================================================
+// PLAYER ROUTES — PLAYBACK QUEUE (book chunks + assets-state)
+// ======================================================
+// Byte-for-byte relocation from the host routes/book/chunks-routes.cjs
+// (Player route split, then physical move to packages/animastor-player — no
+// behavior change):
+//   - GET /api/v1/book/:bookId/chunks       — the playback queue
+//     (dedup per scene, cover_chunk_id, chunk_positions);
+//   - GET /api/v1/book/:bookId/assets-state — readiness counters.
+//
+// assets-state is a SHARED endpoint: the Generate page gates on it as much
+// as the Player does (dirty-unit counters, layer config) — recorded as an
+// intentional mixed responsibility (audit §3.4.5). PG scene-assets repo and
+// Redis chunk reads stay host-side infra (a full playback-projection port is
+// deliberately premature); the pure IU math stays host-side
+// (routes/book/iu-progress-utils.cjs — kept pure, injected as the
+// computeIuReady port). Consumers: web generateStore/playbackStore,
+// Android, tests.
+
+const path = require('path');
+const fs = require('fs');
+const naming = require('./artifact-naming.cjs');
+
+module.exports = function(app, ctx, deps) {
+    const { getAllChunks, getBookWindowStatus, layerConfig, sceneAssetsRepo, computeIuReady } = deps;
+
+    // ── BOOK CHUNKS (playback queue) ─────────────────────────────────────
+    app.get('/api/v1/book/:bookId/chunks', async (req, res) => {
+        const allIds = await getAllChunks(req.params.bookId);
+        const windowStatus = await getBookWindowStatus(req.params.bookId);
+
+        // Build chunk_positions map + find cover_chunk_id in one pass so the
+        // client never needs N individual getChunkStoryboard calls (F9 audit).
+        let coverChunkId = null;
+        const chunkPositions = {};
+
+        // Deduplicate: the playback queue needs exactly one entry per scene.
+        // TTS pipeline may create multiple chunks per scene (_0001, _0002,
+        // _0003) for long text segments — they all serve the same merged
+        // audio file. Keep only the first chunk (lowest chunk_index) per
+        // (chapter_id, scene_id).
+        const dedupedIds = [];
+        const seenScenes = new Set();
+
+        if (allIds.length > 0) {
+            try {
+                const keys = allIds.map(id => `animastor:chunk:${id}`);
+                const raw = await ctx.redis.mget(keys);
+                for (let i = 0; i < allIds.length; i++) {
+                    if (!raw[i]) {
+                        // Chunk without metadata — keep it (defensive)
+                        if (!seenScenes.has('__unknown__')) {
+                            seenScenes.add('__unknown__');
+                            dedupedIds.push(allIds[i]);
+                        }
+                        continue;
+                    }
+                    try {
+                        const c = JSON.parse(raw[i]);
+                        const sceneKey = `${c.chapter_id || ''}:${c.scene_id || ''}`;
+
+                        chunkPositions[allIds[i]] = {
+                            chapter_id: c.chapter_id || null,
+                            scene_id: c.scene_id || null,
+                        };
+                        if (c.scene_type === 'cover') {
+                            coverChunkId = allIds[i];
+                        }
+
+                        // Only add to deduped list if this scene hasn't been seen yet
+                        if (!seenScenes.has(sceneKey)) {
+                            seenScenes.add(sceneKey);
+                            dedupedIds.push(allIds[i]);
+                        }
+                    } catch (_) {}
+                }
+            } catch (err) {
+                console.warn('[CHUNKS] Failed to load chunk metadata:', err.message);
+                // Fallback: return all IDs (no dedup)
+                dedupedIds.push(...allIds);
+            }
+        }
+
+        res.json({
+            chunk_ids: dedupedIds,
+            total: dedupedIds.length,
+            cover_chunk_id: coverChunkId,
+            chunk_positions: chunkPositions,
+            ...windowStatus
+        });
+    });
+
+    // ── ASSETS STATE (readiness — shared with Generator gating) ──────────
+    app.get('/api/v1/book/:bookId/assets-state', async (req, res) => {
+        try {
+            const { bookId } = req.params;
+            const { scope, chapter_id, scene_id } = req.query;
+
+            const allChunkIds = await getAllChunks(bookId);
+            const totalChunks = allChunkIds.length;
+
+            const chunkById = new Map();
+            if (allChunkIds.length > 0) {
+                try {
+                    const raw = await ctx.redis.mget(allChunkIds.map(id => `animastor:chunk:${id}`));
+                    for (let i = 0; i < allChunkIds.length; i++) {
+                        if (!raw[i]) continue;
+                        try {
+                            const c = JSON.parse(raw[i]);
+                            if (!c.audio_status) c.audio_status = 'pending';
+                            if (!c.image_status) c.image_status = c.image ? 'ready' : 'pending';
+                            if (!c.video_status) c.video_status = 'pending';
+                            chunkById.set(allChunkIds[i], c);
+                        } catch (_) {}
+                    }
+                } catch (mgetErr) {
+                    for (const cid of allChunkIds) {
+                        try { const c = await ctx.getChunk(cid); if (c) chunkById.set(cid, c); } catch (_) {}
+                    }
+                }
+            }
+
+            let filteredIds = allChunkIds;
+            if ((scope === 'current_chapter' || scope === 'chapter') && chapter_id) {
+                filteredIds = allChunkIds.filter(cid => chunkById.get(cid)?.chapter_id === chapter_id);
+            } else if ((scope === 'current_scene' || scope === 'scene') && chapter_id && scene_id) {
+                filteredIds = allChunkIds.filter(cid => {
+                    const c = chunkById.get(cid);
+                    return c?.chapter_id === chapter_id && c?.scene_id === scene_id;
+                });
+            }
+
+            let audioReady = 0, audioReadyReal = 0, imageReady = 0, videoReady = 0;
+            let audioError = 0, imageError = 0, videoError = 0;
+            let hasAudio = false, hasImage = false, hasVideo = false;
+
+            const isErr = (s) => s === 'error' || s === 'failed';
+            for (const cid of filteredIds) {
+                const chunk = chunkById.get(cid);
+                if (!chunk) continue;
+                if (chunk.audio_status === 'ready' || chunk.audio_status === 'placeholder') {
+                    audioReady++; hasAudio = true;
+                    if (chunk.audio_status === 'ready') audioReadyReal++;
+                } else if (isErr(chunk.audio_status)) { audioError++; }
+                if (chunk.image_status === 'ready') { imageReady++; hasImage = true; }
+                else if (isErr(chunk.image_status)) { imageError++; }
+                if (chunk.video_status === 'ready') { videoReady++; hasVideo = true; }
+                else if (isErr(chunk.video_status)) { videoError++; }
+            }
+
+            let scopeIuTotal = 0, scopeIuReady = 0, coverIuTotal = 0, coverIuReady = 0;
+            try {
+                let buildId = chunkById.get(filteredIds[0])?.build_id;
+                if (!buildId) {
+                    for (const cid of allChunkIds) {
+                        const b = chunkById.get(cid)?.build_id;
+                        if (b) { buildId = b; break; }
+                    }
+                }
+
+                if (buildId) {
+                    const uniqueScenes = new Map();
+                    for (const cid of filteredIds) {
+                        const chunk = chunkById.get(cid);
+                        if (chunk?.chapter_id && chunk?.scene_id) {
+                            uniqueScenes.set(`${chunk.chapter_id}:${chunk.scene_id}`, {
+                                chapter_id: chunk.chapter_id, scene_id: chunk.scene_id,
+                            });
+                        }
+                    }
+
+                    for (const { chapter_id: ch, scene_id: sc } of uniqueScenes.values()) {
+                        const rows = await ctx.iuRepo.getImageUnitsForScene(buildId, bookId, ch, sc);
+                        if (rows.length > 0) {
+                            scopeIuTotal += rows.length;
+                            scopeIuReady += await computeIuReady(ctx.redis, sceneAssetsRepo, bookId, ch, sc, rows.length);
+                        }
+                    }
+
+                    const layerCfg = await layerConfig.get(ctx.redis, bookId);
+                    const imagesEnabled = layerCfg?.image_enabled !== false;
+                    if (imagesEnabled) {
+                        // Cover lookup reads through the Player boundary
+                        // (playerModel → Canonical Book Model).
+                        const coverCh = ctx.playerModel.loadBook(bookId)?.chapters?.find(ch => ch.type === 'cover');
+                        if (coverCh && coverCh.scenes && coverCh.scenes.length > 0) {
+                            const coverScene = coverCh.scenes[0];
+                            // chapter_id for modern lazy-book chapters,
+                            // `chapter` for legacy parse.js chapters.
+                            const coverChapterId = coverCh.chapter_id ?? coverCh.chapter;
+                            const coverSceneId = coverScene.scene_id;
+                            const rows = await ctx.iuRepo.getImageUnitsForScene(buildId, bookId, coverChapterId, coverSceneId);
+                            if (rows.length > 0) {
+                                coverIuTotal = rows.length;
+                                coverIuReady = await computeIuReady(ctx.redis, sceneAssetsRepo, bookId, coverChapterId, coverSceneId, rows.length);
+                            } else {
+                                const allUnits = [...(coverScene.units || [])];
+                                for (const db of (coverScene.dialogue_blocks || [])) {
+                                    if (db.units) allUnits.push(...db.units);
+                                }
+                                coverIuTotal = allUnits.length;
+                                if (coverIuTotal > 0) {
+                                    coverIuReady = await computeIuReady(ctx.redis, sceneAssetsRepo, bookId, coverChapterId, coverSceneId, allUnits.length);
+                                }
+                            }
+
+                            if (coverIuReady < coverIuTotal && buildId) {
+                                try {
+                                    const buildDir = path.join(ctx.outputRoot, buildId);
+                                    if (fs.existsSync(buildDir)) {
+                                        const iuPrefix = naming.iuImagePrefix(bookId, coverChapterId, coverSceneId);
+                                        const pngFiles = fs.readdirSync(buildDir).filter(f => f.startsWith(iuPrefix) && f.endsWith('.png'));
+                                        if (pngFiles.length >= coverIuTotal) coverIuReady = coverIuTotal;
+                                    }
+                                } catch (_) {}
+                            }
+                        }
+                    }
+                }
+            } catch (_) {}
+
+            res.json({
+                book_id: bookId, scope: scope || 'book', total_chunks: totalChunks,
+                audio_ready: audioReady, audio_ready_real: audioReadyReal,
+                image_ready: imageReady, video_ready: videoReady,
+                has_audio: hasAudio, has_image: hasImage, has_video: hasVideo,
+                all_audio_ready: audioReadyReal === filteredIds.length && filteredIds.length > 0,
+                all_image_ready: imageReady === filteredIds.length && filteredIds.length > 0,
+                all_video_ready: videoReady === filteredIds.length && filteredIds.length > 0,
+                has_assets: audioReady > 0 || imageReady > 0 || videoReady > 0,
+                scope_total: filteredIds.length,
+                scope_audio_ready: audioReady, scope_audio_ready_real: audioReadyReal,
+                scope_image_ready: imageReady, scope_video_ready: videoReady,
+                scope_all_audio_ready: audioReadyReal === filteredIds.length && filteredIds.length > 0,
+                scope_all_image_ready: imageReady === filteredIds.length && filteredIds.length > 0,
+                scope_all_video_ready: videoReady === filteredIds.length && filteredIds.length > 0,
+                scope_iu_total: scopeIuTotal, scope_iu_ready: scopeIuReady,
+                cover_iu_total: coverIuTotal, cover_iu_ready: coverIuReady,
+                audio_error: audioError, image_error: imageError, video_error: videoError,
+            });
+        } catch (err) {
+            console.error('[ASSETS-STATE] Error:', err.message);
+            res.status(500).json({ error: err.message });
+        }
+    });
+};

package/src/player-model.cjs

@@ -0,0 +1,52 @@
+// ======================================================
+// @animastor/player — Player Model facade over the Canonical Book Model
+// ======================================================
+// The Player (playback media serving + playback data reads) must reach book
+// content ONLY through this seam: Player → Player Model → Canonical Book
+// Model. It must never load books directly from host implementation
+// details (raw book loaders, PostgreSQL, Redis, runtime/orchestration
+// internals, provider implementations).
+//
+// ── Allowed dependencies ────────────────────────────────────────────────
+//   - Canonical Book Model facade (@animastor/vbook-runtime/book-model.cjs)
+//   - node builtins
+// Everything else (host modules, orchestration, runtime, Redis, PG/storage,
+// providers, services, config) is FORBIDDEN — enforced by
+// backend/tests/architecture/phase6-editor-player.test.js (T1/T3, re-aimed
+// to this package) and player-route-split.test.js (P2/P6).
+//
+// ── Contract (read-only) ────────────────────────────────────────────────
+//   loadBook(bookId, { mode })  — playback book content; 'full' (canonical
+//                                 bundle) by default, 'lazy' (canonical-
+//                                 first, draft fallback) for in-progress
+//                                 books. Delegates 1:1 to the Book Model.
+//   getBookIdentity(bookId)     — identity-only read (manifest), no content.
+//   getBookManifest(bookId)     — manifest.json only.
+//
+// The Player is read-only by design: it never mutates the canonical model
+// (that is the Editor boundary) and never writes runtime state (that is the
+// runtime/orchestration layer).
+
+const bookModel = require('@animastor/vbook-runtime/book-model.cjs');
+
+/**
+ * Create the Player model facade.
+ * @param {{ bookModel?: object }} deps - Book Model injection (defaults to the canonical facade)
+ */
+function createPlayerModel(deps = {}) {
+    const model = deps.bookModel || bookModel;
+
+    return {
+        loadBook(bookId, options) {
+            return model.loadBook(bookId, options);
+        },
+        getBookIdentity(bookId) {
+            return model.getBookIdentity(bookId);
+        },
+        getBookManifest(bookId) {
+            return model.getBookManifest(bookId);
+        },
+    };
+}
+
+module.exports = { createPlayerModel };

package/src/player-routes.cjs

@@ -0,0 +1,94 @@
+// ======================================================
+// @animastor/player — PLAYER ROUTES (playback HTTP contour)
+// ======================================================// The playback contour, physically extracted from the host backend
+// (Player route split 4d1f6f0e → packages/animastor-player move; see
+// docs/architecture/PLAYER_ROUTE_SPLIT_CHECKLIST.md).
+//
+// Serves (byte-identical to the pre-split handlers — URLs, headers, status
+// codes and response bodies unchanged):
+//   scene media:    /api/v1/scene/:b/:ch/:sc/audio|video|image  (+ Range)
+//   scene data:     /api/v1/scene/:b/:ch/:sc/status|storyboard|waveform|timings
+//   iu media:       /api/v1/iu-image/*, /api/v1/preview/*
+//   chunk-keyed:    /api/v1/chunk/:id (status), /api/v1/chunk/:id/audio|image|video|storyboard
+//   playback queue: /api/v1/book/:bookId/chunks, /api/v1/book/:bookId/assets-state
+//
+// Dependencies arrive EXCLUSIVELY through deps (composition root — host
+// backend.cjs):
+//   playerModel   — Phase 6 facade over the Canonical Book Model (book reads)
+//   outputRoot    — artifact root (config.OUTPUT_DIR injected; no direct
+//                   config reads in the player contour)
+//   playerPorts   — { assertBookAccess, computeVideoStartMs, computeWaveform }
+//                   host implementations (auth middleware, video-timeline,
+//                   waveform-service) injected as ports; the contour must
+//                   NOT import generation/host implementation modules
+//                   (workflows/, video-timeline, middleware, waveform-service)
+//                   and must not receive the video-timeline MODULE — only the
+//                   port functions (final boundary audit: the module seam was
+//                   narrowed away; scene-data reads ports via playerPorts)
+//   redis/getChunk/getAllChunks/iuRepo — runtime state (infrastructural,
+//                   host-side; a full playback-projection port is
+//                   deliberately premature — recorded in the split checklist)
+//   image/state/activeScenes/placeholderAudio/layerConfig — host
+//                   generation-pipeline seams (documented intentional deps)
+//   bookProjections — the two pure VBook-runtime read projections
+//                   (findSceneRuntimeData / collectSceneUnits); the package
+//                   never receives the whole book module surface (loaders/
+//                   writers stay host-side; book CONTENT reads go through
+//                   playerModel only)
+//
+// Usage:
+//   const { createPlayerRoutes } = require('@animastor/player');
+//   createPlayerRoutes(app, redis, deps);
+//
+// Guards: backend/tests/architecture/player-route-split.test.js +
+//         backend/tests/architecture/phase6-editor-player.test.js (re-aimed T4/T5/T6).
+
+const { createPlayerShared } = require('./player-shared.cjs');
+
+module.exports = function(app, redis, deps) {
+    const {
+        state, image, utils,
+        getChunk, getAllChunks, getBookWindowStatus,
+        activeScenes, placeholderAudio, layerConfig, iuRepo,
+        sceneAssetsRepo, playerModel,
+        // Player-route seams (composition root provides them):
+        outputRoot,            // = config.OUTPUT_DIR (injected)
+        playerPorts,           // { assertBookAccess, computeVideoStartMs, computeWaveform }
+        computeIuReady,        // pure IU math (host routes/book/iu-progress-utils.cjs)
+        bookProjections,       // { findSceneRuntimeData, collectSceneUnits } — the two
+                               // pure VBook-runtime read projections; the whole book
+                               // module surface is NOT handed to the package
+    } = deps;
+    const { log } = utils;
+
+    if (!bookProjections || typeof bookProjections.findSceneRuntimeData !== 'function'
+        || typeof bookProjections.collectSceneUnits !== 'function') {
+        throw new Error('createPlayerRoutes: bookProjections { findSceneRuntimeData, collectSceneUnits } is a required port');
+    }
+
+    const ctx = createPlayerShared({
+        playerModel,
+        playerPorts,
+        outputRoot,
+        redis,
+        getChunk,
+        iuRepo,
+        log,
+    });
+
+    require('./scene-media.cjs')(app, ctx);
+    require('./scene-data.cjs')(app, ctx, {
+        image,
+        // Pure read projections over the Canonical Book Model (VBook runtime);
+        // the whole book module surface is NOT handed to the player contour.
+        bookProjections,
+    });
+    require('./iu-media.cjs')(app, ctx, {
+        image, state, activeScenes, placeholderAudio,
+    });
+    require('./playback-queue.cjs')(app, ctx, {
+        getAllChunks, getBookWindowStatus, layerConfig, sceneAssetsRepo, computeIuReady,
+    });
+
+    log('[ROUTES] Player routes loaded');
+};

package/src/player-shared.cjs

@@ -0,0 +1,230 @@
+// ======================================================
+// @animastor/player — SHARED CONTOUR HELPERS (seam)
+// ======================================================
+// Dependency-injection seam shared by every player route sub-module.
+// The playback contour must reach host infrastructure ONLY through:
+//   - deps.playerModel   (Phase 6 facade — book content reads)
+//   - deps.outputRoot    (artifact root; replaces direct config.OUTPUT_DIR
+//                         reads — booksRoot injection precedent fb411c61)
+//   - deps.playerPorts   ({ assertBookAccess, computeVideoStartMs,
+//                         computeWaveform } — host implementations injected
+//                         by the composition root; the player must not
+//                         import auth middleware, video-timeline (which
+//                         knows workflows/), or waveform-service directly)
+//   - deps.redis / deps.getChunk / ... (runtime state — infrastructural,
+//                         stays host-side; a full playback-projection port
+//                         is deliberately premature at this stage)
+//
+// Grammar for artifact filenames comes from artifact-naming.cjs — never
+// reconstructed ad-hoc in route handlers.
+//
+// Static dependency rules are guarded by
+// backend/tests/architecture/player-route-split.test.js and Phase 6
+// T3-style scans (re-aimed to this package).
+
+const path = require('path');
+const fs = require('fs');
+const naming = require('./artifact-naming.cjs');
+
+/**
+ * Create the shared player-route context.
+ *
+ * @param {object} deps routeDeps subset (see player-routes.cjs)
+ *   - outputRoot: absolute artifact root (config.OUTPUT_DIR injected by
+ *     the composition root). Semantics preserved: joined as
+ *     path.join(outputRoot, buildId, filename) — absolute/relative behavior
+ *     identical to the previous OUTPUT_DIR joins.
+ *   - playerPorts: { assertBookAccess, computeVideoStartMs, computeWaveform }
+ */
+function createPlayerShared(deps) {
+    const { playerModel, playerPorts, redis, getChunk, iuRepo, log } = deps;
+    const outputRoot = deps.outputRoot;
+    const ports = playerPorts || {};
+
+    // ── Build id resolution ────────────────────────────────────────────
+    // manifest.json is the single source of truth for build_id (Phase 6:
+    // the read goes through the Player boundary, not a raw loader). The
+    // requested value is used only as a fallback when the manifest can't
+    // be read; the client build_id is a cache key, never an address.
+    function getEffectiveBuildId(bookId, requestedBuildId, logFn) {
+        const _log = logFn || (() => {});
+        try {
+            const loadedBook = playerModel.loadBook(bookId);
+            if (loadedBook && loadedBook.manifest && loadedBook.manifest.build_id) {
+                const manifestBuildId = loadedBook.manifest.build_id;
+                if (requestedBuildId && manifestBuildId !== requestedBuildId) {
+                    _log(`buildId resolved: "${requestedBuildId}" → "${manifestBuildId}" for ${bookId}`);
+                }
+                return manifestBuildId;
+            }
+        } catch (_) {}
+        return requestedBuildId || 'default';
+    }
+
+    // ── Artifact paths (naming grammar seam) ─────────────────────────────
+    function buildDir(buildId) {
+        return path.join(outputRoot, buildId);
+    }
+    function sceneAudioPath(buildId, bookId, chapterId, sceneId) {
+        return path.join(buildDir(buildId), naming.sceneAudioName(bookId, chapterId, sceneId));
+    }
+    function sceneVideoPath(buildId, bookId, chapterId, sceneId) {
+        return path.join(buildDir(buildId), naming.sceneVideoName(bookId, chapterId, sceneId));
+    }
+    function sceneImagePath(buildId, bookId, chapterId, sceneId) {
+        return path.join(buildDir(buildId), naming.sceneImageName(bookId, chapterId, sceneId));
+    }
+
+    // ── Book ownership guard for chunk-keyed routes ──────────────────────
+    // The target book comes from the chunk record, not the URL, so it is
+    // verified in-handler after the chunk is loaded. Pre-auth passes
+    // through (existing behaviour); authenticated requests must own the
+    // book. Returns true (and responds 403) when access is denied.
+    // The host middleware implementation arrives via playerPorts
+    // .assertBookAccess (middleware/auth-context.checkBookAccess injected
+    // at the composition root — the player package must not own auth).
+    async function rejectIfChunkBookDenied(req, res, bookId) {
+        if (!ports.assertBookAccess) return false; // no auth host → legacy open behaviour
+        const ws = await ports.assertBookAccess(req, bookId);
+        if (!ws) {
+            res.status(403).json({ error: 'Access denied: not a member of the book\'s workspace' });
+            return true;
+        }
+        return false;
+    }
+
+    // ── Video file resolution ──────────────────────────────────────────
+    // The merged `scene.mp4` (result of group concat for the player) takes
+    // priority; otherwise the first group file `_gN.mp4` (scene
+    // mid-generation). Returns null when none exists.
+    function resolveSceneVideoFile(buildDirectory, bookId, chapterId, sceneId) {
+        const mergedPath = path.join(buildDirectory, naming.sceneVideoName(bookId, chapterId, sceneId));
+        if (fs.existsSync(mergedPath)) {
+            log(`[VIDEO-SERVE] ${bookId}/${chapterId}/${sceneId}: merged scene.mp4 → ${path.basename(mergedPath)}`);
+            return mergedPath;
+        }
+        let files = [];
+        try {
+            files = fs.readdirSync(buildDirectory).filter(f =>
+                f.startsWith(naming.sceneArtifactPrefix(bookId, chapterId, sceneId))
+                && f.endsWith('.mp4')
+                && f !== naming.sceneVideoName(bookId, chapterId, sceneId)
+            );
+        } catch (_) {}
+        if (files.length === 0) {
+            log(`[VIDEO-SERVE] ${bookId}/${chapterId}/${sceneId}: no video files found`);
+            return null;
+        }
+        files.sort((a, b) => {
+            const na = parseInt((a.match(/_g(\d+)/) || [0, 0])[1], 10);
+            const nb = parseInt((b.match(/_g(\d+)/) || [0, 0])[1], 10);
+            return na - nb;
+        });
+        log(`[VIDEO-SERVE] ${bookId}/${chapterId}/${sceneId}: no merged file, serving first group → ${files[0]}`);
+        return path.join(buildDirectory, files[0]);
+    }
+
+    // ── Range streaming ─────────────────────────────────────────────────
+    // Stream a media file with HTTP Range support (206 Partial Content).
+    // The browser <audio>/<video> engine seeks (currentTime = X) by issuing
+    // Range requests; without 206 handling the seek silently fails and
+    // playback restarts from position 0.
+    function streamFileWithRange(req, res, filePath, contentType) {
+        const stat = fs.statSync(filePath);
+        const fileSize = stat.size;
+        // Content is served per build_id URL, but the backend REGENERATES
+        // files IN PLACE (same build_id → same URL, new bytes). So responses
+        // are cacheable but MUST be revalidated: ETag/Last-Modified +
+        // If-None-Match / If-Range let a browser media cache serve repeat
+        // plays and resume buffered ranges WITHOUT re-downloading the whole
+        // 20-43 MB file, while a regenerated file still propagates (changed
+        // ETag → full fresh 200).
+        const etag = `"${fileSize.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
+        const lastModified = stat.mtime.toUTCString();
+        const lastModifiedSec = Math.floor(stat.mtimeMs / 1000) * 1000;
+        res.setHeader('Content-Type', contentType);
+        res.setHeader('Accept-Ranges', 'bytes');
+        res.setHeader('ETag', etag);
+        res.setHeader('Last-Modified', lastModified);
+        res.setHeader('Cache-Control', 'public, max-age=0, must-revalidate');
+
+        const range = req.headers.range;
+        if (!range) {
+            // Conditional GET: 304 when the cached entity is still current.
+            const inm = (req.headers['if-none-match'] || '').split(',').map((s) => s.trim());
+            if (inm.includes(etag) || inm.includes('*')) {
+                res.status(304).end();
+                return;
+            }
+            const ims = req.headers['if-modified-since'];
+            if (ims && Date.parse(ims) >= lastModifiedSec) {
+                res.status(304).end();
+                return;
+            }
+            res.setHeader('Content-Length', fileSize);
+            fs.createReadStream(filePath).pipe(res);
+            return;
+        }
+
+        const match = /^bytes=(\d*)-(\d*)$/.exec(range);
+        if (!match) {
+            res.status(416).setHeader('Content-Range', `bytes */${fileSize}`).end();
+            return;
+        }
+        let start = match[1] ? parseInt(match[1], 10) : 0;
+        let end = match[2] ? parseInt(match[2], 10) : fileSize - 1;
+        if (match[1] === '' && match[2] !== '') {
+            // Suffix range "bytes=-N" — last N bytes.
+            start = Math.max(0, fileSize - parseInt(match[2], 10));
+            end = fileSize - 1;
+        }
+        if (start >= fileSize || start > end) {
+            res.status(416).setHeader('Content-Range', `bytes */${fileSize}`).end();
+            return;
+        }
+        // If-Range: the client's cached entity must still match ours (ETag
+        // or date) — otherwise the Range is ignored and the full 200 entity
+        // is served. Media players send this to resume buffered ranges
+        // without re-downloading; a regenerated file gets the full body.
+        let ifRangeOk = true;
+        const ifRange = req.headers['if-range'];
+        if (ifRange) {
+            if (ifRange.startsWith('"') || ifRange.startsWith('W/')) {
+                ifRangeOk = ifRange === etag;
+            } else {
+                ifRangeOk = Date.parse(ifRange) === lastModifiedSec;
+            }
+        }
+        if (!ifRangeOk) {
+            res.setHeader('Content-Length', fileSize);
+            fs.createReadStream(filePath).pipe(res);
+            return;
+        }
+        end = Math.min(end, fileSize - 1);
+        res.status(206);
+        res.setHeader('Content-Range', `bytes ${start}-${end}/${fileSize}`);
+        res.setHeader('Content-Length', end - start + 1);
+        fs.createReadStream(filePath, { start, end }).pipe(res);
+    }
+
+    return {
+        getEffectiveBuildId,
+        buildDir,
+        sceneAudioPath,
+        sceneVideoPath,
+        sceneImagePath,
+        rejectIfChunkBookDenied,
+        resolveSceneVideoFile,
+        streamFileWithRange,
+        // direct access to the injected seams (read-only for sub-modules)
+        get playerModel() { return playerModel; },
+        get playerPorts() { return ports; },
+        get redis() { return redis; },
+        get getChunk() { return getChunk; },
+        get iuRepo() { return iuRepo; },
+        get outputRoot() { return outputRoot; },
+        get log() { return log; },
+    };
+}
+
+module.exports = { createPlayerShared };