@animastor/player 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.1.0 — 2026-09-08
+
+### Release preparation (npm publication)
+
+- `@animastor/vbook-runtime` dependency switched from the monorepo
+  `file:` link to the published registry range `^0.1.0` (0.1.0 is live on
+  npm) — `npm install @animastor/player` now resolves cleanly on a fresh
+  environment. The host backend is unaffected: it injects the bookModel,
+  so the package's default facade instance is inert inside the backend
+  process; the monorepo `file:` links at `backend/package.json` are
+  unchanged.
+- Consumer metadata completed: keywords, homepage, README installation
+  section + Node >= 18 requirement + absolute doc links (relative
+  `../../docs/...` links do not resolve on npmjs.com).
+- `files` narrowed to production content (`src/` + metadata) — tests stay
+  in the repository checkout and run via `npm test`, matching the
+  repo-wide package standard (no tests in published tarballs).
+
+### Physical extraction (route split 4d1f6f0e → boundary audit → move)
+
+- The playback HTTP contour physically moved from the backend host into
+  `src/` of this package: the registrar (`player-routes.cjs`), shared
+  contour helpers (`player-shared.cjs`), scene media (`scene-media.cjs`),
+  scene data (`scene-data.cjs`), IU media (`iu-media.cjs`), playback queue
+  (`playback-queue.cjs`), the artifact-naming grammar
+  (`artifact-naming.cjs`) and the Player Model facade (`player-model.cjs`,
+  from the host `backend/src/player/index.cjs`) — final boundary audit
+  MOVE list.
+- Behavior, URLs, headers (Range / 206 / ETag / If-Range / 304 / 416),
+  status codes and response bodies unchanged (17 frozen endpoints, pinned
+  by `backend/tests/architecture/player-route-split.test.js` P1).
+- Legacy backend copies deleted: `backend/src/routes/player/`,
+  `backend/src/player/`, and the empty `routes/book/chunks-routes.cjs`
+  registrar stub.
+- Every host dependency arrives as an injected port (composition-root
+  contract in the README); the package's only dependency is
+  `@animastor/vbook-runtime` (Player Model facade).
+- Behavior tests moved into the package: `test/scene-timings.test.js`,
+  `test/scene-audio-range.test.js`.

package/LICENSE

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

package/README.md

@@ -0,0 +1,95 @@
+# @animastor/player
+
+Animastor **Player** — the playback HTTP contour of the Animastor backend:
+scene media serving (HTTP Range / 206 / ETag / If-Range streaming), scene
+data (status / storyboard / timings / waveform), IU media (iu-image /
+preview / chunk storyboard), the playback queue (chunk dedup,
+`cover_chunk_id`, `chunk_positions`) and the assets-state readiness
+projection. Includes the `createPlayerModel` facade over the Canonical Book
+Model and the read-side artifact-naming grammar.
+
+**Status: EXTRACTED (0.1.0).** The playback contour physically lives in this
+package (`src/`); the host backend consumes it only through the package
+entrypoint. See
+[`docs/architecture/PLAYER_ROUTE_SPLIT_CHECKLIST.md`](https://github.com/Animastor/animastor/blob/main/docs/architecture/PLAYER_ROUTE_SPLIT_CHECKLIST.md)
+(physical move COMPLETE) and
+[`docs/architecture/PLAYER_PACKAGE_EXTRACTION_READINESS_AUDIT.md`](https://github.com/Animastor/animastor/blob/main/docs/architecture/PLAYER_PACKAGE_EXTRACTION_READINESS_AUDIT.md).
+
+## Requirements
+
+- Node.js >= 18
+- [`@animastor/vbook-runtime`](https://www.npmjs.com/package/@animastor/vbook-runtime)
+  (installed automatically as the only runtime dependency — the Player Model
+  facade over its Canonical Book Model)
+
+## Installation
+
+```bash
+npm install @animastor/player
+```
+
+## Public API
+
+The package exposes a single entrypoint — `require('@animastor/player')`
+returns `{ createPlayerModel, createPlayerRoutes }`. Deep imports
+(`@animastor/player/src/...`) are intentionally not exported.
+
+## Boundary
+
+The package imports **nothing** from the backend host: no config, no
+generation implementation, no `workflows/`, no middleware, no
+waveform/video-timeline host modules, no Redis/PG internals, no backend
+storage. Book content is reached only through the injected `playerModel`
+(VBook boundary — the facade over `@animastor/vbook-runtime`'s Book Model).
+Every host dependency arrives as an injected port at registration time.
+
+## Standalone use (repository checkout)
+
+```bash
+npm install        # dep: @animastor/vbook-runtime (dev: mocha + chai)
+npm test           # 17 behavioral tests, no host needed
+```
+
+## Host integration (composition root)
+
+```js
+const { createPlayerModel, createPlayerRoutes } = require('@animastor/player');
+
+const playerModel = createPlayerModel({ bookModel });
+createPlayerRoutes(app, redis, {
+    playerModel,                                  // VBook boundary (book content reads)
+    outputRoot: config.OUTPUT_DIR,                // artifact root (no config reads inside)
+    playerPorts: {                                // host-owned implementations
+        assertBookAccess,                         //   auth middleware
+        computeVideoStartMs,                      //   ffprobe + workflows alignment tax
+        computeWaveform,                          //   ffmpeg
+    },
+    computeIuReady,                               // pure IU-progress math (host)
+    bookProjections: { findSceneRuntimeData, collectSceneUnits }, // pure VBook reads
+    redis, getChunk, getAllChunks, getBookWindowStatus,
+    iuRepo, sceneAssetsRepo, layerConfig,
+    image, state, activeScenes, placeholderAudio,
+    utils: { log },
+});
+```
+
+## Frozen HTTP surface (17 endpoints)
+
+```
+GET  /api/v1/chunk/:id                     GET  /api/v1/chunk/:id/audio
+GET  /api/v1/chunk/:id/image               GET  /api/v1/chunk/:id/video
+GET  /api/v1/chunk/:id/storyboard          GET  /api/v1/scene/:b/:ch/:sc/audio
+GET  /api/v1/scene/:b/:ch/:sc/video        GET  /api/v1/scene/:b/:ch/:sc/image
+GET  /api/v1/scene/:b/:ch/:sc/status       GET  /api/v1/scene/:b/:ch/:sc/storyboard
+GET  /api/v1/scene/:b/:ch/:sc/waveform     GET  /api/v1/scene/:b/:ch/:sc/timings
+PUT  /api/v1/scene/:b/:ch/:sc/timings      GET  /api/v1/iu-image/:b/:ch/:sc/:iuId
+GET  /api/v1/preview/:b/:ch/:sc/:iuId      GET  /api/v1/book/:bookId/chunks
+GET  /api/v1/book/:bookId/assets-state
+```
+
+Guards: [`backend/tests/architecture/player-route-split.test.js`](https://github.com/Animastor/animastor/blob/main/backend/tests/architecture/player-route-split.test.js) (P1–P9) and
+[`backend/tests/architecture/phase6-editor-player.test.js`](https://github.com/Animastor/animastor/blob/main/backend/tests/architecture/phase6-editor-player.test.js) (T1–T7).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@animastor/player",
+    "version": "0.1.0",
+    "description": "Animastor Player — playback HTTP contour: scene media serving (Range/206/ETag/If-Range), scene data (status/storyboard/timings/waveform), IU media, playback queue and assets-state. Reads book content only through the injected playerModel (VBook boundary); every host dependency arrives as an injected port — no config, no generation, no workflows, no Redis/PG/Redis internals in the package.",
+    "keywords": [
+        "animastor",
+        "player",
+        "playback",
+        "http-range",
+        "media-streaming"
+    ],
+    "main": "src/index.cjs",
+    "exports": {
+        ".": "./src/index.cjs"
+    },
+    "files": [
+        "src/",
+        "README.md",
+        "LICENSE",
+        "CHANGELOG.md"
+    ],
+    "scripts": {
+        "test": "mocha --exit test/*.test.js"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Animastor/animastor.git",
+        "directory": "packages/animastor-player"
+    },
+    "homepage": "https://github.com/Animastor/animastor/tree/main/packages/animastor-player#readme",
+    "bugs": {
+        "url": "https://github.com/Animastor/animastor/issues"
+    },
+    "dependencies": {
+        "@animastor/vbook-runtime": "^0.1.0"
+    },
+    "devDependencies": {
+        "chai": "^6.2.2",
+        "mocha": "^11.7.5"
+    }
+}

package/src/artifact-naming.cjs

@@ -0,0 +1,79 @@
+// ======================================================
+// @animastor/player — ARTIFACT NAMING GRAMMAR (seam)
+// ======================================================
+// The single place where the playback contour reconstructs media artifact
+// filenames. Generation WRITES these files (audio-orchestrator, video-
+// orchestrator, image pipeline, filesystem-store) and the Player contour
+// READS them; the grammar itself is an undeclared cross-domain contract
+// (Player extraction audit §4, risk R2).
+//
+// Owner of the grammar today: the generation/storage writers, canonical
+// definitions in storage/filesystem-store.js (makeSceneAudioFilename,
+// makeChunkAudioFilename, makeIUImageFilename, makePreviewFilename) plus the
+// video group grammar `${prefix}_gN.mp4` (video-orchestrator suffixes).
+// The Player must NOT import generation implementations directly — this
+// module re-exposes the grammar through an explicit, dependency-free
+// utility contract (@animastor/player/src/artifact-naming.cjs — moved with
+// the physical extraction). Generation keeps its own writer functions; the
+// byte-identity pin below is the drift guard. Long-term home (optional):
+// @animastor/vbook-runtime schema territory — out of scope here.
+//
+// NOTE: strings here MUST stay byte-identical to the writers. Guarded by
+// backend/tests/architecture/player-route-split.test.js (P7 naming pins).
+
+/**
+ * Scene audio: `${book}_${chapter}_${scene}.mp3`
+ * (mirrors filesystem-store.makeSceneAudioFilename / audio-orchestrator merge output)
+ */
+function sceneAudioName(bookId, chapterId, sceneId) {
+    return `${bookId}_${chapterId}_${sceneId}.mp3`;
+}
+
+/** Scene video (merged, player-facing): `${prefix}.mp4` */
+function sceneVideoName(bookId, chapterId, sceneId) {
+    return `${bookId}_${chapterId}_${sceneId}.mp4`;
+}
+
+/** Video group clip: `${prefix}_g${n}.mp4` (video-orchestrator suffix grammar) */
+function sceneVideoGroupName(bookId, chapterId, sceneId, group) {
+    return `${bookId}_${chapterId}_${sceneId}_g${group}.mp4`;
+}
+
+/** Scene image: `${prefix}.png` */
+function sceneImageName(bookId, chapterId, sceneId) {
+    return `${bookId}_${chapterId}_${sceneId}.png`;
+}
+
+/**
+ * IU image prefix glob: `${prefix}_iu` — IU images are
+ * `${prefix}_iu{iuId}.png` (mirrors filesystem-store.makeIUImageFilename;
+ * the route serves by exact id via iuImageName and lists by this prefix).
+ */
+function iuImagePrefix(bookId, chapterId, sceneId) {
+    return `${bookId}_${chapterId}_${sceneId}_iu`;
+}
+
+/**
+ * IU image by exact URL id: `${prefix}_${iuId}.png`. The URL :iuId carries the
+ * `iu` prefix itself (frontend unitId: u.id ?? 'iu0001'), so this equals the
+ * writer's `${prefix}_iu${strippedId}.png` (filesystem-store
+ * .makeIUImageFilename with the ^iu-stripped id — see image/preview.js).
+ */
+function iuImageName(bookId, chapterId, sceneId, iuId) {
+    return `${bookId}_${chapterId}_${sceneId}_${iuId}.png`;
+}
+
+/** Prefix shared by every scene artifact (audio/video/image/iu/preview). */
+function sceneArtifactPrefix(bookId, chapterId, sceneId) {
+    return `${bookId}_${chapterId}_${sceneId}`;
+}
+
+module.exports = {
+    sceneAudioName,
+    sceneVideoName,
+    sceneVideoGroupName,
+    sceneImageName,
+    iuImagePrefix,
+    iuImageName,
+    sceneArtifactPrefix,
+};

package/src/index.cjs

@@ -0,0 +1,49 @@
+// ======================================================
+// @animastor/player — PACKAGE ENTRYPOINT (public API)
+// ======================================================
+// The playback HTTP contour of the Animastor backend, physically extracted
+// from the host (backend/src/routes/player/ + backend/src/player/ — deleted
+// by the extraction commit; docs/architecture/PLAYER_ROUTE_SPLIT_CHECKLIST.md
+// §PHYSICAL MOVE COMPLETE).
+//
+// The package owns: route registration, Range/206/ETag/If-Range media
+// streaming, scene status/storyboard/timings handlers, IU media, the
+// playback queue (chunk dedup, cover_chunk_id, chunk_positions) and the
+// assets-state readiness projection, plus the artifact-naming grammar
+// (read-side expression of the generation⇄player filename contract).
+//
+// The package imports NOTHING from the backend host: no config, no
+// generation implementation, no workflows/, no middleware, no waveform/
+// video-timeline host modules, no Redis/PG internals, no backend storage.
+// Book content is reached ONLY through the injected playerModel (the
+// VBook boundary — the facade itself lives here over the Book Model of
+// @animastor/vbook-runtime); the two pure read projections arrive as the
+// injected bookProjections.
+//
+// Host dependencies (ports/adapters — injected by the composition root):
+//   playerModel       { loadBook(bookId, opts?), getBookIdentity(bookId),
+//                       getBookManifest(bookId) }        (VBook boundary)
+//   outputRoot        string — artifact root (host config injected)
+//   playerPorts       { assertBookAccess(req, bookId) → workspace|null,
+//                       computeVideoStartMs(ius, buildId, bookId, ch, sc,
+//                       outputRoot) → Promise<boolean>,
+//                       computeWaveform(audioPath) → Promise<number[]> }
+//   computeIuReady    (redis, sceneAssetsRepo, bookId, ch, sc, total)
+//   bookProjections   { findSceneRuntimeData(loadedBook, ch, sc),
+//                       collectSceneUnits(scenePayload) } (pure VBook reads)
+//   redis/getChunk/getAllChunks/getBookWindowStatus             (runtime state)
+//   iuRepo/sceneAssetsRepo/layerConfig/image/state/activeScenes/
+//   placeholderAudio/utils ({ log })                            (host seams)
+//
+// Public API:
+//   const { createPlayerModel, createPlayerRoutes } = require('@animastor/player');
+//   const playerModel = createPlayerModel({ bookModel });
+//   createPlayerRoutes(app, redis, routeDeps);
+//
+// Guards: backend/tests/architecture/player-route-split.test.js (P1–P9),
+//         backend/tests/architecture/phase6-editor-player.test.js (T1–T7).
+
+const { createPlayerModel } = require('./player-model.cjs');
+const createPlayerRoutes = require('./player-routes.cjs');
+
+module.exports = { createPlayerModel, createPlayerRoutes };

package/src/iu-media.cjs

@@ -0,0 +1,294 @@
+// ======================================================
+// PLAYER ROUTES — IU MEDIA (iu-image / preview / chunk storyboard+status)
+// ======================================================
+// Byte-for-byte relocation from the host routes/generation-routes.cjs
+// (Player route split, then physical move to packages/animastor-player — no
+// behavior change). The preview route may
+// GENERATE a preview via the injected image.getOrCreatePreview dep
+// (host image-pipeline internal — documented hidden write, audit §4 R3).
+// Consumers: web Edit zoom/Navigate thumbs/player IU, Android Repository,
+// tests.
+
+const fs = require('fs');
+const path = require('path');
+const naming = require('./artifact-naming.cjs');
+
+module.exports = function(app, ctx, deps) {
+    const { image, state, activeScenes, placeholderAudio } = deps;
+
+    // ── Chunk status (playback readiness, auto-redispatch repair) ────────
+    app.get('/api/v1/chunk/:id', async (req, res) => {
+        try {
+            const c = await ctx.getChunk(req.params.id);
+            if (!c) return res.json({ status: 'processing' });
+            if (await ctx.rejectIfChunkBookDenied(req, res, c.book_id)) return;
+
+            const buildDir = ctx.buildDir(c.build_id);
+            const audioPath = path.join(buildDir, naming.sceneAudioName(c.book_id, c.chapter_id, c.scene_id));
+            const imagePath = path.join(buildDir, naming.sceneImageName(c.book_id, c.chapter_id, c.scene_id));
+            const videoPath = path.join(buildDir, naming.sceneVideoName(c.book_id, c.chapter_id, c.scene_id));
+
+            // Auto-redispatch if audio flag says ready but file is missing
+            if (c.audio && !fs.existsSync(audioPath)) {
+                try {
+                    const phResult = await placeholderAudio.ensurePlaceholderAudio(
+                        c.build_id || 'default', c.book_id, c.chapter_id, c.scene_id
+                    );
+                    const phOk = !!phResult && (phResult.created || (phResult.reason === 'already_exists' && phResult.path));
+                    if (phOk && fs.existsSync(audioPath)) {
+                        ctx.log(`Placeholder audio on-demand for ${req.params.id} — keeping chunk ready`);
+                        c.audio_status = 'placeholder';
+                        await ctx.redis.set(`animastor:chunk:${req.params.id}`, JSON.stringify(c));
+                    } else {
+                        // Don't reset c.audio = false — the chunk has audio:
+                        // true, and audio_ready is computed as !!(c.audio ||
+                        // fileExists). Resetting permanently breaks the
+                        // scene for the player.
+                        ctx.log(`Placeholder audio generation returned ${JSON.stringify(phResult)} for ${req.params.id} — keeping chunk as-is`);
+                    }
+                } catch (phErr) {
+                    ctx.log(`Placeholder audio check failed for ${req.params.id}: ${phErr.message} — keeping chunk as-is`);
+                    if (c.chapter_id && c.scene_id) {
+                        const jobKey = `animastor:job:${c.book_id}_${c.chapter_id}_${c.scene_id}_0001:audio`;
+                        await ctx.redis.del(jobKey);
+                        await activeScenes.addActiveScene(ctx.redis, c.book_id, c.chapter_id, c.scene_id);
+                    }
+                }
+            }
+
+            // Reverse: file exists but flag says not ready
+            if (!c.audio && fs.existsSync(audioPath)) {
+                ctx.log(`Audio file exists for ${req.params.id} — updating flag`);
+                c.audio = true;
+                c.audio_status = 'ready';
+                await ctx.redis.set(`animastor:chunk:${req.params.id}`, JSON.stringify(c));
+            }
+
+            // Auto-redispatch for image
+            if (c.image && !fs.existsSync(imagePath)) {
+                const iuPrefix = naming.iuImagePrefix(c.book_id, c.chapter_id, c.scene_id);
+                let hasIuFiles = false;
+                try {
+                    const dirFiles = fs.readdirSync(buildDir);
+                    hasIuFiles = dirFiles.some(f => f.startsWith(iuPrefix) && f.endsWith('.png'));
+                } catch {}
+                if (!hasIuFiles) {
+                    ctx.log(`Missing image file for ${req.params.id} — resetting state for redispatch`);
+                    c.image = false;
+                    await ctx.redis.set(`animastor:chunk:${req.params.id}`, JSON.stringify(c));
+                    if (c.chapter_id && c.scene_id) {
+                        const jobKey = `animastor:job:${c.book_id}_${c.chapter_id}_${c.scene_id}_0002:image`;
+                        await ctx.redis.del(jobKey);
+                        await activeScenes.addActiveScene(ctx.redis, c.book_id, c.chapter_id, c.scene_id);
+                    }
+                }
+            }
+
+            const audioReady = !!(c.audio || fs.existsSync(audioPath));
+            let imageReady = !!c.image;
+            if (!imageReady && c.chapter_id && c.scene_id) {
+                // Check per-asset state for image readiness
+                try {
+                    const assetStates = await state.getAssetStates(ctx.redis, c.book_id, c.chapter_id, c.scene_id);
+                    if (assetStates.image === state.AssetState.READY || assetStates.image === state.AssetState.PLACEHOLDER) {
+                        imageReady = true;
+                        c.image = true;
+                        await ctx.redis.set(`animastor:chunk:${req.params.id}`, JSON.stringify(c));
+                    }
+                } catch (_) {}
+                if (!imageReady) {
+                    imageReady = fs.existsSync(imagePath);
+                    if (!imageReady) {
+                        const iuPrefix = naming.iuImagePrefix(c.book_id, c.chapter_id, c.scene_id);
+                        try {
+                            const dirFiles = fs.readdirSync(buildDir);
+                            imageReady = dirFiles.some(f => f.startsWith(iuPrefix) && f.endsWith('.png'));
+                        } catch {}
+                    }
+                }
+            }
+            const videoReady = !!(c.video && fs.existsSync(videoPath));
+            const allReady = audioReady;
+
+            res.json({
+                status: allReady ? 'ready' : 'processing', image_ready: imageReady,
+                audio_ready: audioReady, video_ready: videoReady,
+                audio_status: c.audio_status || 'pending',
+                video_status: c.video_status || 'pending',
+                scene_type: c.scene_type || 'narration',
+                scene_id: c.scene_id,
+                chapter_id: c.chapter_id,
+            });
+        } catch (err) {
+            console.error('❌ CHUNK STATUS ERROR:', err.message);
+            res.status(500).json({ error: 'Internal error fetching chunk status' });
+        }
+    });
+
+    // ── Chunk-keyed storyboard (Android legacy) ──────────────────────────
+    app.get('/api/v1/chunk/:id/storyboard', async (req, res) => {
+        try {
+            const { id } = req.params;
+            const c = await ctx.getChunk(id);
+            if (!c) return res.status(404).json({ error: 'chunk not found' });
+            if (await ctx.rejectIfChunkBookDenied(req, res, c.book_id)) return;
+
+            const { build_id, book_id, chapter_id, scene_id } = c;
+            const dir = ctx.buildDir(build_id);
+            if (!fs.existsSync(dir)) return res.status(404).json({ error: 'build directory not found' });
+
+            let ius = [];
+            try {
+                const pgRows = await ctx.iuRepo.getImageUnitsForScene(build_id, book_id, chapter_id, scene_id);
+                if (pgRows && pgRows.length > 0) {
+                    ius = pgRows.map(r => ({
+                        unit_id: r.unit_id, scene_id: r.scene_id, text: r.text,
+                        text_proportion: r.text_proportion, estimated_duration_sec: r.estimated_duration_sec,
+                        audio_file: r.scene_audio_file,
+                        // Note: start_ms=0 maps to null here, but unlike the
+                        // timings GET route this is self-corrected by the pgMap
+                        // merge below (rows with end_ms>0 override the nulls).
+                        start_ms: r.start_ms != null && (Number(r.start_ms) || 0) > 0 ? Number(r.start_ms) : null,
+                        end_ms: r.end_ms != null && (Number(r.end_ms) || 0) > 0 ? Number(r.end_ms) : null,
+                    }));
+                }
+            } catch (dbErr) {
+                console.warn('[STORYBOARD] PG read failed, falling back to book data:', dbErr.message);
+            }
+
+            if (ius.length === 0) {
+                try {
+                    const b = ctx.playerModel.loadBook(book_id);
+                    if (b) {
+                        for (const ch of b.chapters || []) {
+                            if (ch.chapter_id !== chapter_id) continue;
+                            for (const sc of ch.scenes || []) {
+                                if (sc.scene_id !== scene_id) continue;
+                                let order = 0;
+                                for (const u of sc.units || []) {
+                                    ius.push({ unit_id: u.id, scene_id, text: u.text, text_proportion: 0, estimated_duration_sec: 0, audio_file: null, start_ms: null, end_ms: null, _order: order });
+                                    order++;
+                                }
+                                for (const db of sc.dialogue_blocks || []) {
+                                    for (const u of db.units || []) {
+                                        ius.push({ unit_id: u.id, scene_id, text: u.text, text_proportion: 0, estimated_duration_sec: 0, audio_file: null, start_ms: null, end_ms: null, _order: order });
+                                        order++;
+                                    }
+                                }
+                                const totalTextLen = ius.reduce((s, i) => s + (i.text || '').length, 0);
+                                ius.sort((a, b) => a._order - b._order);
+                                for (const iu of ius) {
+                                    iu.text_proportion = totalTextLen > 0 ? (iu.text || '').length / totalTextLen : 1;
+                                    delete iu._order;
+                                    delete iu._text;
+                                }
+                                break;
+                            }
+                        }
+                    }
+                } catch (bookErr) {
+                    console.warn('[STORYBOARD] Book data fallback failed:', bookErr.message);
+                }
+            }
+
+            const needsDuration = ius.every(iu => !iu.estimated_duration_sec || iu.estimated_duration_sec === 0);
+            if (needsDuration && ius.length > 0) {
+                const sceneDuration = await image.getSceneDuration(build_id, book_id, chapter_id, scene_id);
+                if (sceneDuration > 0) {
+                    for (const iu of ius) {
+                        iu.estimated_duration_sec = parseFloat((sceneDuration * (iu.text_proportion || 0)).toFixed(3));
+                    }
+                }
+                // Compute timing boundaries (start_ms/end_ms) from cumulative durations
+                const sceneDurationMs = Math.round(sceneDuration * 1000);
+                let cursorMs = 0;
+                for (const iu of ius) {
+                    const durMs = Math.max(200, Math.round((iu.estimated_duration_sec || 1) * 1000));
+                    iu._start_ms = cursorMs;
+                    let endMs = cursorMs + durMs;
+                    if (sceneDurationMs > 0 && endMs > sceneDurationMs) endMs = sceneDurationMs;
+                    iu._end_ms = endMs;
+                    cursorMs = endMs;
+                }
+                for (const [idx, iu] of ius.entries()) {
+                    try {
+                        await ctx.iuRepo.upsertImageUnit(build_id, book_id, chapter_id, scene_id, iu.unit_id, {
+                            scene_order: idx, text: iu.text, text_length: (iu.text || '').length,
+                            text_proportion: iu.text_proportion || 0, scene_duration_sec: sceneDuration || 0,
+                            estimated_duration_sec: iu.estimated_duration_sec || 0,
+                            scene_audio_file: naming.sceneAudioName(book_id, chapter_id, scene_id),
+                            start_ms: iu._start_ms != null ? iu._start_ms : null,
+                            end_ms: iu._end_ms != null ? iu._end_ms : null,
+                        });
+                    } catch (pgErr) {
+                        console.warn('[STORYBOARD] Failed to persist IU to PG:', pgErr.message);
+                    }
+                }
+            }
+
+            try {
+                const pgRows = await ctx.iuRepo.getImageUnitsForScene(build_id, book_id, chapter_id, scene_id);
+                if (pgRows && pgRows.length > 0) {
+                    const pgMap = {};
+                    for (const r of pgRows) {
+                        if ((r.start_ms || 0) > 0 || (r.end_ms || 0) > 0) pgMap[r.unit_id] = r;
+                    }
+                    for (const iu of ius) {
+                        const pg = pgMap[iu.unit_id];
+                        if (pg) { iu.start_ms = pg.start_ms; iu.end_ms = pg.end_ms; }
+                    }
+                }
+            } catch (dbErr) {
+                console.warn('[STORYBOARD] DB timing merge failed:', dbErr.message);
+            }
+
+            // Server-computed playback duration per IU so clients never
+            // re-derive it. Rule: real interval (end-start) if positive, else
+            // estimated_duration_sec, else a 2000ms default. Mirrors the
+            // former client fallbackDurationMs().
+            for (const iu of ius) {
+                const real = (iu.start_ms != null && iu.end_ms != null) ? (iu.end_ms - iu.start_ms) : 0;
+                if (real > 0) {
+                    iu.duration_ms = real;
+                } else if (iu.estimated_duration_sec && iu.estimated_duration_sec > 0) {
+                    iu.duration_ms = Math.round(iu.estimated_duration_sec * 1000);
+                } else {
+                    iu.duration_ms = 2000;
+                }
+            }
+
+            res.json({ chunk_id: id, book_id, chapter_id, scene_id, build_id, scene_type: c.scene_type || 'narration', ius });
+        } catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+
+    // ── IU image ─────────────────────────────────────────────────────────
+    app.get('/api/v1/iu-image/:bookId/:chapterId/:sceneId/:iuId', async (req, res) => {
+        try {
+            const { bookId, chapterId, sceneId, iuId } = req.params;
+            const buildId = ctx.getEffectiveBuildId(bookId, req.query.build_id, ctx.log);
+            const imagePath = path.join(ctx.buildDir(buildId), naming.iuImageName(bookId, chapterId, sceneId, iuId));
+            if (!fs.existsSync(imagePath)) return res.status(404).json({ error: 'IU image not found' });
+            res.setHeader('Content-Type', 'image/png');
+            fs.createReadStream(imagePath).pipe(res);
+        } catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+
+    // ── Preview (may generate via injected image.getOrCreatePreview) ─────
+    app.get('/api/v1/preview/:bookId/:chapterId/:sceneId/:iuId', async (req, res) => {
+        try {
+            const { bookId, chapterId, sceneId, iuId } = req.params;
+            const buildId = ctx.getEffectiveBuildId(bookId, req.query.build_id, ctx.log);
+            const result = await image.getOrCreatePreview(bookId, chapterId, sceneId, iuId, buildId);
+            if (!result) return res.status(404).json({ error: 'IU image not found, cannot generate preview' });
+            res.setHeader('Content-Type', 'image/png');
+            res.setHeader('X-Preview-Created', String(result.created));
+            fs.createReadStream(result.path).pipe(res);
+        } catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+};