Refine line-based story scrolling

CLIENT_TODO.md

@@ -4,7 +4,7 @@ This file is the single living technical specification, implementation checklist
 
 ## Product Goal
 
-Build an AI-assisted interactive fiction client that feels like a carefully typeset illustrated novel rather than a chat window. The game server owns game state and narrative generation. The client renders incoming narrative as synchronized animated prose with optional speech, sound effects, music, future image blocks, and persistent player options.
+Build an AI-assisted interactive fiction client that feels like a carefully typeset illustrated novel rather than a chat window. The game server owns game state and narrative generation. The client renders incoming narrative as synchronized animated prose with optional speech, sound effects, music, image blocks, and persistent player options.
 
 The production client must tolerate TTS being unavailable. The safe default TTS provider is `none`; a game, user preference, or explicit option can select another provider.
 
@@ -25,8 +25,8 @@ The production client must tolerate TTS being unavailable. The safe default TTS
 - Done: mouse cursor state reporting by process state.
 - Done: placeholder game API for new/load/save/running state.
 - Done: sound effect and music folders, sound effect playback, music playback, and music ducking during TTS.
-- Partial: image markup is parsed and queued, but actual image rendering is still future work.
+- Done: image markup is parsed, persisted in history, restored from save/history, and rendered as line-snapped page blocks.
-- Partial: save-game API is a placeholder; saves are per socket session and do not survive reload.
+- Partial: save-game API restores story state and Ink state, but the broader save/storage model still needs hardening for all engines.
 - Pending: deeper automated tests for layout, playback timing, TTS provider switching, and media cue timing.
 
 ## Module System Specification
@@ -58,8 +58,8 @@ The loader is deliberately the conductor, not the orchestra. Module-specific con
 - `markup-parser-module.js`: converts story text into text blocks, inline styled spans, image blocks, sound cues, and music cues.
 - `text-processor-module.js`: applies SmartyPants and Hyphenopoly according to active language.
 - `paragraph-layout-module.js`: measures text and computes Knuth-Plass layout.
-- `layout-renderer-module.js`: turns layout data into page DOM with stable word positions and animation metadata.
+- `layout-renderer-module.js`: turns line-coordinate layout data into absolutely positioned page DOM with stable word positions and animation metadata.
-- `sentence-queue-module.js`: prepares sentence objects and coordinates layout/TTS readiness.
+- `sentence-queue-module.js`: prepares speech/media readiness. It must not own page layout, image wrapping, or history rendering state.
 - `playback-coordinator-module.js`: starts synchronized text/audio playback in the right order.
 - `animation-queue-module.js`: schedules and fast-forwards visual text animation.
 - `audio-manager-module.js`: owns sound effects, music tracks, music ducking, volume application, and speech audio playback helpers.
@@ -73,7 +73,7 @@ The loader is deliberately the conductor, not the orchestra. Module-specific con
 - `localization-module.js`: language state used by UI, hyphenation, and TTS selection.
 - `options-ui-module.js`: options modal, persisted controls, provider status displays.
 - `ui-controller-module.js`: top-bar commands, global input behavior, game API control wiring.
-- `ui-display-handler-module.js`: book page display, startup prompt, text insertion, and media block dispatch.
+- `ui-display-handler-module.js`: book page display, startup prompt, unified live/history rendering, line-coordinate scrolling, image placement, and media block dispatch.
 - `ui-input-handler-module.js`: command entry, history, fast-forward key handling.
 - `socket-client-module.js`: socket connection and game API request wrapper.
 - `game-loop-module.js`: high-level client/game flow.
@@ -95,6 +95,66 @@ The right page must look like typeset book text:
 - Punctuation and short marks should not visually break the measure; optical margin handling is desirable future polish.
 - The page must scale as a fixed-aspect book page. Font sizes and word positions scale with page size, preserving the composition when the window is resized.
 
+## Right Page History And Scrolling Specification
+
+The right page uses one virtual, line-addressed content pane. It must not behave like browser pagination and must not rely on native scrolling inside `#page_right`, `#story`, or story blocks.
+
+Line model invariants:
+
+- `#page_right` has a size relative to the browser window.
+- There is exactly one story line-height value.
+- The page height is divided into a fixed number of lines; currently `PAGE_LINE_COUNT = 25`.
+- `lineHeight = pageRightHeight / PAGE_LINE_COUNT`.
+- All rendered content has a height that is an exact multiple of line height, including margins, internal spacing, drop cap space, image vertical spacing, and section/chapter spacing.
+- All virtual content coordinates and pixel positions are derived mathematically from line coordinates.
+- Stored content does not change line numbers after creation.
+- Visible content is never inserted between already existing blocks; new live content is appended at the end of the virtual history.
+- Therefore cumulative pixel measurements from the browser DOM are not authoritative and cumulative line starts should not need updating after a block has been assigned coordinates.
+- In portrait-image cases, text and image blocks may occupy overlapping cumulative line ranges, but every block edge still lands on a line boundary.
+
+Scroll positioning:
+
+- Scrolling means translating the content pane vertically with an ease-in/ease-out animation.
+- Every finished scroll position must snap to the nearest position where page edges align with line edges.
+- Scrolling to the top means the top edge of the first line of the first block aligns with the top edge of the page.
+- Scrolling to the bottom means the bottom edge of the last line of the last rendered block aligns with the bottom edge of the page.
+- Scrolling to the bottom to insert new content uses the same bottom rule, but the new block is first added invisibly to block history, advancing the block counter and line history. The page scrolls to the resulting bottom position, then the block reveal animation starts.
+- If playback continues while the user is viewing older history, the view must first return to the live bottom insertion position before revealing new content.
+- If manual scrolling moves currently animating content out of focus, active text animation and TTS playback must be fast-forwarded through the same path used by page click/space, including TTS fade/stop.
+
+Active line and active block model:
+
+- The 41-block retention target is not pagination.
+- There is one active line representing the current view position.
+- If enough content exists above it, the active line is considered to be the last visible line of the page, line 25.
+- The block containing that active line is the active block.
+- The DOM should normally contain 20 blocks before the active block, the active block itself, and 20 blocks after the active block, when those blocks exist.
+- When normal scrolling shifts the active line into a different block, load one block in the direction of travel and unload one block from the opposite side.
+- This one-block exchange should happen as soon as the active block changes, not after the viewport reaches a DOM edge.
+- Mouse wheel, arrow key, and scrollbar interactions must drive this active-line model rather than loading page-sized chunks.
+
+Random-position and scrollbar jumps:
+
+- Scrolling to a random target first identifies the target line and target block.
+- If the target is reached by traversal, the one-block exchange model applies.
+- If the target is jumped to, the page first loads:
+  - 20 blocks before the current/starting active block, as available,
+  - the current/starting active block,
+  - all blocks between the starting block and the target block,
+  - the target block,
+  - 20 blocks after the target block, as available.
+- The whole loaded range can then be traversed smoothly from the starting position to the target position.
+- The final target aligns so the bottom edge of the requested line aligns with the bottom edge of the page when enough content exists above it; otherwise it uses the top rule.
+- After the scroll finishes, blocks farther than the retained margin are unloaded.
+- If the required loaded range would exceed a sensible DOM budget, currently 150 blocks total, all visible page content fades out, the old DOM content is unloaded, the target block plus 20 blocks before and after it are loaded, and the page fades in at the target position.
+
+Scrollbar behavior:
+
+- The custom scrollbar represents virtual history position and history size in line coordinates, not native DOM scroll state.
+- Dragging the scrollbar thumb should move the thumb preview freely without scrolling content or loading history during the drag.
+- On pointer release, the target line/block is resolved, the required block range is loaded according to the random-position rules, and then the content scroll animation runs.
+- Scrollbar pointer events must not bubble into story fast-forward/continue handlers.
+
 Processing order:
 
 1. Parse block and inline story markup.
@@ -342,7 +402,7 @@ Longer-term goal:
 - [x] Added chapter heading and dropcap markup.
 - [x] Added section/textblock markup.
 - [x] Added Markdown emphasis parsing.
-- [x] Added image markup parsing for future image rendering.
+- [x] Added image markup parsing, line-snapped rendering, and history/save restoration.
 - [x] Added sound effect markup and playback.
 - [x] Added music markup, playback modes, loop/once, and lead-in.
 - [x] Added music ducking during TTS.

NOTE.md

@@ -22,3 +22,35 @@ Assume the following:
 2.) All content has an exact multiple of line height as height all margins and paddings included.
 3.) Therefore any coordinates or pixel sizes of the virtual content pane can be derived mathematically from line coordinates.
 4.) Scrolling means translating the content vertically (with ease in/eas out animation) to the closest position where the page edges aligns with line edges.
+5.) Since stored content does not change line numbers after creation, and (visible) content is never added in between existing blocks, updating the cumulative values should be unnecessary.
+6.) Scrolling to the bottom means to scroll to the position where the bottom edge of the last line of the last element aligns with the bottom edge of the page.
+7.) Scrolling to the top means to scroll to the position where the top edge of the first line of the first block aligns with the top edge of the page.
+8.) Scrolling to the bottom to insert new content means the same as 6. but with the new content already added invisibly to the block history (advancing the current block counter), scrolling to the position and only then activating the fade in animation.
+9.) In the case of portrait format images next to text the cumulative line positions can overlap but still should border on the line edges.
+10.) Scrolling to a random position means to first load all content between the starting point and the target point + additional blocks in the movement direction into the right_page. Then scrolling so the bottom edge of the requested line aligns with the bottom edge of the page, if there is enough content above it otherwise it's the same as 7.) scrolling to the top. After the scroll has finished blocks a certain distance from the reached position are unloded.
+
+
+Looks like you partially work with outdated specs: Here the last version:
+1.) The #right_page div has a size relative to the window. There is ONE line height value, which is a divisor or the page height/the page height has a fixed number of lines: Line height = Page height/fixed number of lines.
+2.) All content has an exact multiple of line height as height all margins and paddings included.
+3.) Therefore any coordinates or pixel sizes of the virtual content pane can be derived mathematically from line coordinates.
+4.) Scrolling means translating the content vertically (with ease in/eas out animation) to the closest position where the page edges aligns with line edges.
+5.) Since stored content does not change line numbers after creation, and (visible) content is never added in between existing blocks, updating the cumulative values should be unnecessary.
+6.) Scrolling to the bottom means to scroll to the position where the bottom edge of the last line of the last element aligns with the bottom edge of the page.
+7.) Scrolling to the top means to scroll to the position where the top edge of the first line of the first block aligns with the top edge of the page.
+8.) Scrolling to the bottom to insert new content means the same as 6. but with the new content already added invisibly to the block history (advancing the current block counter), scrolling to the position and only then activating the fade in animation.
+9.) In the case of portrait format images next to text the cumulative line positions can overlap but still should border on the line edges.
+10.) Scrolling to a random position means to first load all content between the starting point and the target point + additional blocks in the movement direction into the right_page. Then scrolling so the bottom edge of the requested line aligns with the bottom edge of the page, if there is enough content above it otherwise it's the same as 7.) scrolling to the top. After the scroll has finished blocks a certain distance from the reached position are unloded.
+
+Put that wherever you keep your project specs but refine it with the following information:
+DO NOT do pagination. The 41 blocks mean there should be one line that is the current position. If there is enough lines content before it this position is always asumed to be the last line of the page (line 25). Whichever block this line belongs to is the active block. The system should always keep 20 blocks before the active block, the active block, and 20 blocks after the active block loaded. That's where the 41 blocks come from. The moment scrolling shifts the active line into a new block in any direction one other block is to be loaded (in that direction) and one is to be unloaded (opposite this direction). If the coordinate is not reached by traversal but jumped to 20 blocks before the active block, the active block, all blocks between the starting block and the target block, the target block and 20 blocks after the target block should be loaded so the whole range can be traversed. If this exceeds a sensible amount of blocks in the dom, let's say 150 blocsk in total, all content on the page is faded out and unloaded, then the target block and 20 blocks before and after it (as available) are loaded before the content of the page is faded in again.
+
+Please give me feedback whether you understand how I imagine this to work, If you agree this is feasable and then apply it to whatever your notes you keep about the project specifications.
+
+What works and what doesnt:
+1.) up arrow and down arrow perfectly scrolls up and down line by line, but pressing the button again while it is still scrolling leads to stuttering movement. Also all formats and layouts seem to be correct.
+2,) Using the mousewheel or page up and down does move the content in the right direction but seemingly a random number of lines (about 1-5) not 24 or whatever the mousewheel speed says. Find out why? How is wheel speed translated into a scroll command?
+3.) Home loads a completely new page which takes some time and then flickers into existence ... then it correctly scrolls to the top.
+4.) End removes all content from the page, takes some time then you can see the scroll bar go to the bottom, but content does not re-appear before or after the scroll. Only manually scrolling using the arrow key shows the content again.
+5.) Scrolling correctly cancels playback and animation. Resuming correctly scrolls to the bottom. Sometimes it resumes play as intended, but under certain conditions new TTS audio is played, but no new text is added. The game just always scrolls down to the last visible block and stays there, while the story and audio continues.
+Do not fix it yet. Explain to me step by step why? Do not guess. Do not invent an explanation! Trace the what the program actually does from triggering event to end state and explain to me why this should work, cannot work, is complete or was left in an unfinished state!

public/css/style.css

@@ -424,9 +424,17 @@ ol.choice {
 }
 
 #paragraphs {
+    position: relative;
     box-sizing: border-box;
     overflow: visible !important;
     overflow-anchor: none;
+    margin: 0;
+    padding: 0;
+    transition: opacity 220ms ease;
+}
+
+#paragraphs.story-history-fading {
+    opacity: 0;
 }
 
 .story-block-archiving {
@@ -453,20 +461,11 @@ ol.choice {
 
 .story-image-landscape,
 .story-image-square {
-    clear: both;
     margin-left: auto;
     margin-right: auto;
 }
 
 .story-image-portrait {
-    float: left;
-    margin-left: 0;
-    margin-right: 0;
-    shape-outside: inset(0);
-}
-
-.story-image-portrait.story-image-float-right {
-    float: right;
     margin-left: 0;
     margin-right: 0;
 }
@@ -546,6 +545,10 @@ ol.choice {
     pointer-events: auto;
 }
 
+#story_scrollbar[data-dragging="true"] #story_scrollbar_thumb {
+    transition: none;
+}
+
 
 /* ===== Scrollbar CSS ===== */
   /* Firefox */

public/index.html

@@ -297,6 +297,6 @@
             originalLog.apply(console, args);
         };
     </script>
-    <script type="module" src="/js/loader.js?v=20260515-lead-kap-verified"></script>
+    <script type="module" src="/js/loader.js?v=20260516-scroll-window"></script>
 </body>
 </html>

public/js/layout-renderer-module.js

@@ -79,15 +79,14 @@ class LayoutRendererModule extends BaseModule {
             layoutData.addTopSpace ? 'story-textblock-start' : '',
             layoutData.dropCap ? 'story-dropcap-paragraph' : ''
         ].filter(Boolean).join(' ');
-        paragraph.style.position = 'relative';
+        paragraph.style.position = 'absolute';
         paragraph.style.margin = '0';
+        paragraph.style.left = '0';
+        const globalLineStart = Math.max(0, Number(layoutData.lineStart || 0));
+        const windowOriginLine = Math.max(0, Number(layoutData.windowOriginLine || 0));
+        paragraph.style.top = `${(globalLineStart - windowOriginLine) * Number(lineHeightPx || 0)}px`;
         if (fontSize) paragraph.style.fontSize = fontSize;
         if (fontFamily) paragraph.style.fontFamily = fontFamily;
-        if (Array.isArray(measures) && measures.length > 0) {
-            paragraph.style.width = `${Math.max(...measures)}px`;
-            paragraph.style.maxWidth = '100%';
-        }
-
         // Calculate paragraph height
         const storyElement = document.getElementById('story');
         if (!storyElement) {
@@ -95,30 +94,25 @@ class LayoutRendererModule extends BaseModule {
             return null;
         }
 
+        const pageWidth = Number(layoutData.pageWidth || storyElement.clientWidth);
+        paragraph.style.width = `${pageWidth}px`;
+        paragraph.style.maxWidth = '100%';
+
         if (!Number.isFinite(Number(lineHeightPx)) || Number(lineHeightPx) <= 0) {
             throw new Error('LayoutRenderer: Missing canonical lineHeightPx for story layout.');
         }
         const lineHeight = Number(lineHeightPx);
-        let marginLines = 0;
+        const contentTopLines = Math.max(0, Number(layoutData.contentTopLines || 0));
-        if (layoutData.role === 'chapter-heading') {
-            paragraph.style.marginTop = `${lineHeight * 2}px`;
-            paragraph.style.marginBottom = `${lineHeight}px`;
-            marginLines = 3;
-        } else if (layoutData.role === 'section-heading') {
-            paragraph.style.marginTop = `${lineHeight}px`;
-            paragraph.style.marginBottom = `${lineHeight}px`;
-            marginLines = 2;
-        } else if (layoutData.addTopSpace) {
-            paragraph.style.marginTop = `${lineHeight}px`;
-            marginLines = 1;
-        }
         const maxLineWidth = Array.isArray(measures) && measures.length > 0
-            ? Math.max(...measures)
+            ? Math.max(pageWidth, ...measures)
-            : storyElement.clientWidth;
+            : pageWidth;
         // Height should include all lines (breaks.length represents number of lines)
         const numLines = Math.max(1, breaks.length - 1);
-        paragraph.style.height = `${lineHeight * numLines}px`;
+        const totalLines = Math.max(1, Number(layoutData.lineCount || (numLines + contentTopLines)));
-        paragraph.dataset.heightLines = String(numLines + marginLines);
+        paragraph.style.height = `${lineHeight * totalLines}px`;
+        paragraph.dataset.heightLines = String(totalLines);
+        paragraph.dataset.lineStart = String(globalLineStart);
+        paragraph.dataset.lineCount = String(totalLines);
 
         console.log(`LayoutRenderer: Rendering paragraph ${id} - ${breaks.length} breaks (${numLines} lines), lineHeight: ${lineHeight}px, total height: ${lineHeight * numLines}px`);
 
@@ -139,6 +133,7 @@ class LayoutRendererModule extends BaseModule {
             const dropCap = document.createElement('span');
             dropCap.className = 'drop-cap story-drop-cap';
             dropCap.textContent = layoutData.dropCapText;
+            dropCap.style.top = `${contentTopLines * lineHeight}px`;
             paragraph.appendChild(dropCap);
         }
 
@@ -195,7 +190,7 @@ class LayoutRendererModule extends BaseModule {
                         word.dataset.lineWidth = String(lineWidth);
 
                         // Calculate position with proper line and justification
-                        const topPercent = (lineIndex * lineHeight * 100) / parseFloat(paragraph.style.height);
+                        const topPercent = ((contentTopLines + lineIndex) * lineHeight * 100) / parseFloat(paragraph.style.height);
                         const leftPercent = ((lineOffset + currentLeft) * 100) / maxLineWidth;
 
                         word.style.top = `${topPercent}%`;
@@ -266,7 +261,7 @@ class LayoutRendererModule extends BaseModule {
                     word.dataset.line = String(lineIndex);
                     word.dataset.lineStart = String(lineOffset);
                     word.dataset.lineWidth = String(lineWidth);
-                    const topPercent = (lineIndex * lineHeight * 100) / parseFloat(paragraph.style.height);
+                    const topPercent = ((contentTopLines + lineIndex) * lineHeight * 100) / parseFloat(paragraph.style.height);
                     const leftPercent = ((lineOffset + currentLeft) * 100) / maxLineWidth;
                     word.style.top = `${topPercent}%`;
                     word.style.left = `${leftPercent}%`;

public/js/loader.js

@@ -24,7 +24,7 @@ const ModuleState = {
     ERROR: 'ERROR'
 };
 
-const MODULE_CACHE_BUSTER = '20260515-lead-kap-verified';
+const MODULE_CACHE_BUSTER = '20260516-scroll-window';
 window.MODULE_CACHE_BUSTER = MODULE_CACHE_BUSTER;
 
 /**

public/js/playback-coordinator-module.js

@@ -21,6 +21,7 @@ class PlaybackCoordinatorModule extends BaseModule {
             'calculateWordTimings',
             'animateWords',
             'waitForAudioStart',
+            'completeSentenceVisual',
             'fastForward',
             'stop'
         ]);
@@ -81,11 +82,25 @@ class PlaybackCoordinatorModule extends BaseModule {
             console.error('PlaybackCoordinator: Error during playback:', error);
             throw error;
         } finally {
+            this.completeSentenceVisual(sentence);
             this.isPlaying = false;
             this.currentSentence = null;
         }
     }
 
+    completeSentenceVisual(sentence) {
+        if (!sentence?.element) return;
+        sentence.element.dataset.playbackComplete = 'true';
+        sentence.element.querySelectorAll('.word').forEach(word => {
+            word.style.transition = 'none';
+            word.style.animation = 'none';
+            word.style.visibility = 'visible';
+            word.style.opacity = '1';
+            word.style.transform = 'translateY(0)';
+            word.style.clipPath = 'inset(0 0 0 0)';
+        });
+    }
+
     /**
      * Play TTS audio for a sentence
      * @param {Object} sentence - Sentence object with TTS data
@@ -307,15 +322,7 @@ class PlaybackCoordinatorModule extends BaseModule {
         }
 
         // Complete all word animations immediately
-        if (this.currentSentence.element) {
+        this.completeSentenceVisual(this.currentSentence);
-            const wordElements = this.currentSentence.element.querySelectorAll('.word');
-            wordElements.forEach(word => {
-                word.style.animation = 'none';
-                word.style.opacity = '1';
-                word.style.transform = 'translateY(0)';
-                word.style.clipPath = 'inset(0 0 0 0)';
-            });
-        }
     }
 
     /**

public/js/sentence-queue-module.js

@@ -16,10 +16,8 @@ class SentenceQueueModule extends BaseModule {
         this.isProcessing = false;
         this.onSentenceReadyCallback = null;
 
-        // Cache for prefetched sentences
+        // Cache in-flight TTS prefetches only. Layout belongs to the renderer.
-        this.preparedCache = new Map();
+        this.prefetchingSpeech = new Map();
-        this.prefetchingCache = new Map();
-        this.activeImageWrap = null;
         this.autoplay = true;
         this.inputMode = 'text';
         this.lastContinueAt = 0;
@@ -44,7 +42,6 @@ class SentenceQueueModule extends BaseModule {
             'waitForManualContinue',
             'prepareSentence',
             'prepareLayout',
-            'prepareImageLayout',
             'extractWords',
             'getDropCapText',
             'extractDropCapText',
@@ -279,9 +276,8 @@ class SentenceQueueModule extends BaseModule {
     }
     
     /**
-     * Prepare a complete sentence object with TTS and layout
+     * Prepare queue metadata. This module intentionally does not create layout:
-     * @param {string} text - Text to prepare
+     * live rendering and history rendering must go through the same renderer.
-     * @returns {Promise<Object>} - Complete sentence object
      */
     async prepareSentence(item) {
         const text = typeof item === 'string' ? item : item.text;
@@ -297,10 +293,6 @@ class SentenceQueueModule extends BaseModule {
                     }
                 }
 
-                const imageLayout = metadata.type === 'image'
-                    ? await this.prepareImageLayout(metadata)
-                    : null;
-
                 return {
                     id,
                     kind: metadata.type,
@@ -309,7 +301,7 @@ class SentenceQueueModule extends BaseModule {
                     blockId: metadata.blockId ?? null,
                     gameId: metadata.gameId ?? null,
                     status: 'ready',
-                    metadata: imageLayout ? { ...metadata, imageLayout } : metadata,
+                    metadata,
                     tts: { duration: 0, provider: null, audioData: null, play: null, stop: null, enabled: false },
                     animation: { wordTimings: [], cueTimings: [], totalDuration: 0 },
                     element: null,
@@ -322,17 +314,9 @@ class SentenceQueueModule extends BaseModule {
                 await audioManager.preloadMediaCues(metadata.cueMarkers || []);
             }
 
-            // Prepare TTS and layout in parallel
+            const ttsData = await this.prepareSpeechMetadata(text);
-            const [ttsData, layoutData] = await Promise.all([
-                this.prepareSpeechMetadata(text),
-                this.prepareLayout(text, metadata)
-            ]);
 
-            // Calculate animation timing based on TTS duration
+            console.log(`SentenceQueue: Prepared speech "${text.substring(0, 50)}..." - TTS duration: ${ttsData.duration}ms`);
-            const words = this.extractWords(layoutData.nodes);
-            const animation = this.calculateAnimationTiming(words, ttsData.duration, metadata.cueMarkers || []);
-
-            console.log(`SentenceQueue: Prepared sentence "${text.substring(0, 50)}..." - TTS duration: ${ttsData.duration}ms, Words: ${words.length}, Animation total: ${animation.totalDuration}ms, Layout breaks: ${layoutData.breaks.length}`);
 
             return {
                 id,
@@ -348,7 +332,6 @@ class SentenceQueueModule extends BaseModule {
                 addTopSpace: Boolean(metadata.addTopSpace),
                 cueMarkers: metadata.cueMarkers || [],
                 status: 'ready',
-                layout: layoutData,
                 tts: {
                     duration: ttsData.duration,
                     provider: ttsData.handler,
@@ -357,7 +340,7 @@ class SentenceQueueModule extends BaseModule {
                     stop: ttsData.stop,
                     enabled: ttsData.isTtsEnabled
                 },
-                animation: animation,
+                animation: { wordTimings: [], cueTimings: [], totalDuration: 0 },
                 element: null,
                 onComplete: null
             };
@@ -415,27 +398,10 @@ class SentenceQueueModule extends BaseModule {
             const indentWidth = (isHeading || metadata.isFirstParagraphInChapter || metadata.addTopSpace) ? 0 : lineHeight * 1.5;
             const layoutText = metadata.layoutText || text;
             const layoutPlainText = metadata.dropCap ? this.extractDropCapText(layoutText) : layoutText;
-            const wrap = this.consumeImageWrap();
+            const measures = Array.isArray(metadata.measures) && metadata.measures.length > 0
-
+                ? metadata.measures
-            // Measures are consumed in line order by the line breaker.
+                : isHeading
-            const wrappedWidth = wrap ? Math.max(120, containerWidth - wrap.width) : containerWidth;
-            const imageLeftOffset = wrap && wrap.side !== 'right' ? wrap.width : 0;
-            const imageRightOffset = wrap && wrap.side === 'right' ? wrap.width : 0;
-            const measures = isHeading
                 ? [containerWidth]
-                : wrap && metadata.dropCap
-                ? [
-                    Math.max(120, wrappedWidth - dropCapWidth),
-                    Math.max(120, wrappedWidth - dropCapWidth),
-                    ...Array(Math.max(0, wrap.lines - dropCapLines)).fill(wrappedWidth),
-                    containerWidth
-                ]
-                : wrap
-                ? [
-                    Math.max(120, wrappedWidth - indentWidth),
-                    ...Array(Math.max(0, wrap.lines - 1)).fill(wrappedWidth),
-                    containerWidth
-                ]
                 : metadata.dropCap
                 ? [
                     Math.max(120, containerWidth - dropCapWidth),
@@ -447,21 +413,10 @@ class SentenceQueueModule extends BaseModule {
                     containerWidth,
                     containerWidth
                 ];
-            const lineOffsets = isHeading
+            const lineOffsets = Array.isArray(metadata.lineOffsets) && metadata.lineOffsets.length > 0
+                ? metadata.lineOffsets
+                : isHeading
                 ? [0]
-                : wrap && metadata.dropCap
-                ? [
-                    imageLeftOffset + dropCapWidth,
-                    imageLeftOffset + dropCapWidth,
-                    ...Array(Math.max(0, wrap.lines - dropCapLines)).fill(imageLeftOffset),
-                    0
-                ]
-                : wrap
-                ? [
-                    imageLeftOffset + indentWidth,
-                    ...Array(Math.max(0, wrap.lines - 1)).fill(imageLeftOffset),
-                    0
-                ]
                 : metadata.dropCap
                 ? [
                     dropCapWidth,
@@ -474,7 +429,7 @@ class SentenceQueueModule extends BaseModule {
                     0
                 ];
 
-            console.log(`SentenceQueue: Layout calculation - indentWidth: ${indentWidth.toFixed(1)}px, imageRightOffset: ${imageRightOffset.toFixed(1)}px, measures: [${measures.map(m => m.toFixed(1)).join(', ')}], offsets: [${lineOffsets.map(m => m.toFixed(1)).join(', ')}]`);
+            console.log(`SentenceQueue: Layout calculation - indentWidth: ${indentWidth.toFixed(1)}px, measures: [${measures.map(m => m.toFixed(1)).join(', ')}], offsets: [${lineOffsets.map(m => m.toFixed(1)).join(', ')}]`);
 
             const layout = paragraphLayout.calculateLayout(layoutPlainText, {
                 measures,
@@ -488,14 +443,6 @@ class SentenceQueueModule extends BaseModule {
                 throw new Error('Paragraph layout calculation failed');
             }
 
-            if (wrap) {
-                const usedLines = Math.max(0, (layout.breaks?.length || 1) - 1);
-                const remainingLines = Math.max(0, wrap.lines - usedLines);
-                this.activeImageWrap = remainingLines > 0
-                    ? { ...wrap, lines: remainingLines }
-                    : null;
-            }
-
             return {
                 breaks: layout.breaks,
                 nodes: layout.nodes,
@@ -504,7 +451,7 @@ class SentenceQueueModule extends BaseModule {
                 measures,
                 lineOffsets,
                 indentWidth,
-                imageWrap: wrap,
+                imageWrap: metadata.imageWrap || null,
                 dropCap: Boolean(metadata.dropCap),
                 dropCapText: metadata.dropCap ? this.getDropCapText(layoutText) : '',
                 dropCapLines,
@@ -574,25 +521,9 @@ class SentenceQueueModule extends BaseModule {
     }
 
     async getPreparedSentence(item) {
-        const cacheKey = this.getCacheKey(item);
+        const pending = this.prefetchingSpeech.get(this.getCacheKey(item));
-        const cached = this.preparedCache.get(cacheKey);
-
-        if (cached) {
-            console.log('SentenceQueue: Using cached sentence');
-            this.preparedCache.delete(cacheKey);
-            return cached;
-        }
-
-        const pending = this.prefetchingCache.get(cacheKey);
         if (pending) {
-            console.log('SentenceQueue: Awaiting active prefetch');
+            await pending.catch(() => null);
-            try {
-                const prepared = await pending;
-                return prepared || await this.prepareSentence(item);
-            } finally {
-                this.prefetchingCache.delete(cacheKey);
-                this.preparedCache.delete(cacheKey);
-            }
         }
 
         return this.prepareSentence(item);
@@ -614,7 +545,7 @@ class SentenceQueueModule extends BaseModule {
         for (let index = 1; index < limit; index += 1) {
             const nextItem = this.sentenceQueue[index];
             const nextCacheKey = this.getCacheKey(nextItem);
-            if (this.preparedCache.has(nextCacheKey) || this.prefetchingCache.has(nextCacheKey)) {
+            if (this.prefetchingSpeech.has(nextCacheKey)) {
                 if (this.isSpeechItem(nextItem)) spokenPrepared += 1;
                 continue;
             }
@@ -625,25 +556,26 @@ class SentenceQueueModule extends BaseModule {
             }));
             console.log(`Process state: ${state}`, { reason: 'prefetch-start', sentenceId: nextItem.id, queueIndex: index });
 
-            const promise = this.prepareSentence(nextItem)
+            const promise = (this.isSpeechItem(nextItem)
-                .then(prepared => {
+                ? this.prepareSpeechMetadata(nextItem.text || '')
-                    this.preparedCache.set(nextCacheKey, prepared);
+                : Promise.resolve(null))
-                    console.log('SentenceQueue: Prefetched queued item', { sentenceId: nextItem.id, queueIndex: index });
+                .then(() => {
+                    console.log('SentenceQueue: Prefetched queued speech/media', { sentenceId: nextItem.id, queueIndex: index });
                     document.dispatchEvent(new CustomEvent('story:process-state', {
                         detail: { state: 'playing-ready', reason: 'prefetch-complete', sentenceId: nextItem.id, queueIndex: index }
                     }));
                     console.log('Process state: playing-ready', { reason: 'prefetch-complete', sentenceId: nextItem.id, queueIndex: index });
-                    return prepared;
+                    return true;
                 })
                 .catch(err => {
                     console.warn('SentenceQueue: Prefetch failed:', err);
                     return null;
                 })
                 .finally(() => {
-                    this.prefetchingCache.delete(nextCacheKey);
+                    this.prefetchingSpeech.delete(nextCacheKey);
                 });
 
-            this.prefetchingCache.set(nextCacheKey, promise);
+            this.prefetchingSpeech.set(nextCacheKey, promise);
             started += 1;
 
             if (this.isSpeechItem(nextItem)) {
@@ -741,76 +673,6 @@ class SentenceQueueModule extends BaseModule {
         });
     }
 
-    async prepareImageLayout(metadata = {}) {
-        const storyElement = document.getElementById('story');
-        if (!storyElement) {
-            throw new Error("Story container not found");
-        }
-
-        if (document.fonts && document.fonts.ready) {
-            await document.fonts.ready;
-        }
-
-        const computedStyle = window.getComputedStyle(storyElement);
-        const lineHeight = parseFloat(computedStyle.lineHeight) || 24;
-
-        const pageWidth = storyElement.clientWidth;
-        const requestedSize = String(metadata.size || 'landscape').toLowerCase();
-        const size = requestedSize === 'widescreen' ? 'landscape' : requestedSize;
-        const isPortrait = size === 'portrait';
-        const aspect = isPortrait ? (9 / 16) : size === 'square' ? 1 : (16 / 9);
-        const imageGap = lineHeight;
-        const maxOuterWidth = isPortrait ? pageWidth * 0.5 : pageWidth;
-        const maxImageWidth = isPortrait
-            ? Math.max(lineHeight * 4, maxOuterWidth - imageGap)
-            : maxOuterWidth;
-        const naturalHeight = maxImageWidth / aspect;
-        const imageLineCount = Math.max(1, Math.floor(naturalHeight / lineHeight));
-        const verticalMargin = isPortrait ? lineHeight / 2 : 0;
-        const lineCount = isPortrait ? imageLineCount + 1 : imageLineCount;
-        const height = isPortrait
-            ? Math.max(lineHeight, (lineCount * lineHeight) - (verticalMargin * 2))
-            : imageLineCount * lineHeight;
-        const width = Math.min(maxImageWidth, height * aspect);
-
-        if (isPortrait) {
-            this.activeImageWrap = {
-                lines: lineCount,
-                width: width + imageGap,
-                imageWidth: width,
-                gap: imageGap,
-                height,
-                lineHeight,
-                side: metadata.floatSide || 'left'
-            };
-        }
-
-        return {
-            size,
-            aspect,
-            width,
-            height,
-            gap: imageGap,
-            lineCount,
-            imageLineCount,
-            lineHeight,
-            verticalMargin,
-            floatSide: metadata.floatSide || 'left',
-            pageWidth
-        };
-    }
-
-    consumeImageWrap() {
-        if (!this.activeImageWrap || this.activeImageWrap.lines <= 0) {
-            this.activeImageWrap = null;
-            return null;
-        }
-
-        const wrap = { ...this.activeImageWrap };
-        this.activeImageWrap = null;
-        return wrap;
-    }
-
     /**
      * Extract words from layout nodes
      * @param {Array} nodes - Layout nodes from Knuth-Plass algorithm
@@ -919,8 +781,7 @@ class SentenceQueueModule extends BaseModule {
     clear() {
         this.sentenceQueue = [];
         this.isProcessing = false;
-        this.preparedCache.clear();
+        this.prefetchingSpeech.clear();
-        this.activeImageWrap = null;
         document.dispatchEvent(new CustomEvent('tts:queue-empty', {
             detail: { reason: 'sentence-queue-cleared' }
         }));

public/js/story-history-module.js

@@ -34,8 +34,9 @@ class StoryHistoryModule extends BaseModule {
             'hasSaveSlot',
             'getSaveSlots',
             'getBlocks',
+            'getBlock',
             'getBlocksRange',
-            'getWindowForTurn',
+            'getFirstBlockForTurn',
             'getRenderedLineCount',
             'findBlockForLine',
             'clearGame',
@@ -145,10 +146,10 @@ class StoryHistoryModule extends BaseModule {
         });
         if (!record) return null;
 
-        const lineCount = Math.max(1, Number(metrics.lineCount || record.lineCount || 1));
+        const lineCount = Math.max(0, Number(metrics.lineCount ?? record.lineCount ?? 1));
-        const previousLineCount = Number(record.lineCount || 0);
+        const lineStart = Number.isFinite(Number(metrics.lineStart))
-        const hadLineStart = Number.isFinite(Number(record.lineStart));
+            ? Math.max(0, Number(metrics.lineStart))
-        const lineStart = hadLineStart
+            : Number.isFinite(Number(record.lineStart))
                 ? Math.max(0, Number(record.lineStart))
                 : this.renderedLineCount;
 
@@ -159,11 +160,7 @@ class StoryHistoryModule extends BaseModule {
             metricsUpdatedAt: Date.now()
         };
 
-        if (!hadLineStart) {
         this.renderedLineCount = Math.max(this.renderedLineCount, lineStart + lineCount);
-        } else if (lineStart + previousLineCount >= this.renderedLineCount) {
-            this.renderedLineCount = Math.max(lineStart + lineCount, this.renderedLineCount + (lineCount - previousLineCount));
-        }
 
         await new Promise((resolve, reject) => {
             const request = this.tx(this.historyStore, 'readwrite').put(updated);
@@ -235,6 +232,16 @@ class StoryHistoryModule extends BaseModule {
         });
     }
 
+    getBlock(gameId = this.currentGameId, blockId = null) {
+        if (!this.db || !gameId || blockId == null) return Promise.resolve(null);
+        const id = Math.max(1, Number(blockId || 1));
+        return new Promise((resolve, reject) => {
+            const request = this.tx(this.historyStore).get(`${gameId}:${id}`);
+            request.onsuccess = () => resolve(request.result || null);
+            request.onerror = () => reject(request.error);
+        });
+    }
+
     getBlocksRange(gameId = this.currentGameId, startBlockId = 1, endBlockId = Infinity) {
         if (!this.db || !gameId) return Promise.resolve([]);
         const start = Math.max(1, Number(startBlockId || 1));
@@ -259,9 +266,9 @@ class StoryHistoryModule extends BaseModule {
         });
     }
 
-    async getWindowForTurn(gameId = this.currentGameId, turnId, visibleLimit = this.visibleLimit) {
+    async getFirstBlockForTurn(gameId = this.currentGameId, turnId) {
-        if (!this.db || !gameId || turnId == null) return { blocks: [], targetBlockId: null };
+        if (!this.db || !gameId || turnId == null) return null;
-        const target = await new Promise((resolve, reject) => {
+        return new Promise((resolve, reject) => {
             const index = this.tx(this.historyStore).index('gameId');
             const request = index.openCursor(IDBKeyRange.only(gameId), 'next');
             request.onsuccess = () => {
@@ -278,15 +285,6 @@ class StoryHistoryModule extends BaseModule {
             };
             request.onerror = () => reject(request.error);
         });
-
-        if (!target?.blockId) return { blocks: [], targetBlockId: null };
-        const latest = Math.max(0, this.nextBlockId - 1);
-        const limit = Math.max(1, Number(visibleLimit || this.visibleLimit));
-        const halfBefore = Math.floor(limit / 2);
-        const maxStart = Math.max(1, latest - limit + 1);
-        const start = Math.max(1, Math.min(maxStart, target.blockId - halfBefore));
-        const blocks = await this.getBlocksRange(gameId, start, Math.min(latest, start + limit - 1));
-        return { blocks, targetBlockId: target.blockId };
     }
 
     async getRenderedLineCount(gameId = this.currentGameId, latestRenderedBlockId = this.latestRenderedBlockId) {