From 4005b767a9e409cad00d538172f74319af5215af Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Wed, 26 Aug 2026 22:56:09 -0500
Subject: [PATCH 01/15] feat: place spoken passages onto original PDF
 coordinates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The reader's passages come from the markdown LiteParse extracted; a native
page view has to draw the PDF itself. Reconciling the two is the whole
problem, and LiteParse's own word boxes (`emitWordBoxes`) are the bridge —
both sides descend from the same glyphs.

Placement is a monotonic affine-gap alignment of the page's words against
the words of the passages anchored to it, with a second pass over whatever
region a run of failures was bracketed into. Measured on "Attention Is All
You Need": 90% of passages placed, 82% of words boxed individually, under
70ms for the densest page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .gitignore                        |   1 +
 src/lib/domain/pdf-layout.spec.ts | 341 ++++++++++++++++
 src/lib/domain/pdf-layout.ts      | 620 ++++++++++++++++++++++++++++++
 vite.config.ts                    |   1 +
 4 files changed, 963 insertions(+)
 create mode 100644 src/lib/domain/pdf-layout.spec.ts
 create mode 100644 src/lib/domain/pdf-layout.ts

diff --git a/.gitignore b/.gitignore
index 6c5f3c9..e503f4a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,3 +43,4 @@ skills-lock.json
 
 # Local test fixtures (user-provided, not committed)
 test_documents/
+.probe/
diff --git a/src/lib/domain/pdf-layout.spec.ts b/src/lib/domain/pdf-layout.spec.ts
new file mode 100644
index 0000000..cd69004
--- /dev/null
+++ b/src/lib/domain/pdf-layout.spec.ts
@@ -0,0 +1,341 @@
+import { describe, expect, it } from 'vitest';
+import {
+	alignWordStreams,
+	chunkText,
+	matchKey,
+	mergeWordRects,
+	pageWordBoxes,
+	placeSegments,
+	segmentsForPage,
+	type PageWordBox,
+	type PlaceableSegment
+} from './pdf-layout';
+import type { SpeechSegment } from './types';
+
+/** Word boxes for a run of words laid out on one line, 10pt apart per
+ * character — enough geometry for the merge and hit-test rules to bite. */
+function line(text: string, y: number, startX = 0): PageWordBox[] {
+	const boxes: PageWordBox[] = [];
+	let x = startX;
+	for (const word of text.split(' ')) {
+		boxes.push({ text: word, x, y, width: word.length * 10, height: 12 });
+		x += word.length * 10 + 5;
+	}
+	return boxes;
+}
+
+function words(text: string): Array<{ start: number; end: number }> {
+	return [...text.matchAll(/\S+/g)].map((match) => ({
+		start: match.index ?? 0,
+		end: (match.index ?? 0) + match[0].length
+	}));
+}
+
+function placeable(id: string, text: string, extra: Partial<PlaceableSegment> = {}) {
+	return { id, text, words: words(text), page: 1, ...extra };
+}
+
+describe('matchKey', () => {
+	it('folds the differences between a page and its extraction', () => {
+		expect(matchKey('Attention,')).toBe('attention');
+		// The page sets a ligature where the markdown carries two letters.
+		expect(matchKey('figures')).toBe(matchKey('figures'));
+		expect(matchKey('Café')).toBe('cafe');
+		expect(matchKey('“quoted”')).toBe('quoted');
+	});
+
+	it('is empty for text carrying no letters or digits', () => {
+		expect(matchKey('—')).toBe('');
+		expect(matchKey('·')).toBe('');
+	});
+});
+
+describe('pageWordBoxes', () => {
+	it('drops rotated stamps, which are not prose', () => {
+		const boxes = pageWordBoxes([
+			{ text: 'arXiv:1706', x: 14, y: 380, width: 22, height: 160, rotation: 270 },
+			{ text: 'Abstract', x: 100, y: 70, width: 50, height: 12, rotation: 0 }
+		]);
+		expect(boxes.map((box) => box.text)).toEqual(['Abstract']);
+	});
+
+	it('falls back to the item box when a parse emitted no word boxes', () => {
+		const boxes = pageWordBoxes([
+			{ text: 'one two', x: 10, y: 20, width: 60, height: 12 },
+			{ text: '   ', x: 10, y: 40, width: 5, height: 12 }
+		]);
+		expect(boxes).toEqual([{ text: 'one two', x: 10, y: 20, width: 60, height: 12 }]);
+	});
+
+	it('prefers word boxes when the parse emitted them', () => {
+		const boxes = pageWordBoxes([
+			{
+				text: 'one two',
+				x: 10,
+				y: 20,
+				width: 60,
+				height: 12,
+				words: [
+					{ text: 'one', x: 10, y: 20, width: 25, height: 12 },
+					{ text: 'two', x: 40, y: 20, width: 25, height: 12 }
+				]
+			}
+		]);
+		expect(boxes.map((box) => box.text)).toEqual(['one', 'two']);
+	});
+});
+
+describe('chunkText', () => {
+	it('keys whitespace-separated chunks and remembers where they came from', () => {
+		expect(chunkText('The Transformer, again')).toEqual([
+			{ key: 'the', start: 0, end: 3 },
+			{ key: 'transformer', start: 4, end: 16 },
+			{ key: 'again', start: 17, end: 22 }
+		]);
+	});
+
+	it('drops chunks that carry no evidence', () => {
+		expect(chunkText('a — b').map((chunk) => chunk.key)).toEqual(['a', 'b']);
+	});
+});
+
+describe('alignWordStreams', () => {
+	it('maps each expected word onto the page word it came from', () => {
+		const alignment = alignWordStreams(
+			['the', 'dominant', 'sequence', 'transduction', 'models'],
+			['dominant', 'sequence', 'transduction']
+		);
+		expect([...alignment]).toEqual([1, 2, 3]);
+	});
+
+	it('skips page words the spoken layer never says', () => {
+		const alignment = alignWordStreams(
+			['figure', '1', 'the', 'transformer', 'model', 'architecture'],
+			['the', 'transformer']
+		);
+		expect([...alignment]).toEqual([2, 3]);
+	});
+
+	it('reports nothing for expected words the page does not have', () => {
+		const alignment = alignWordStreams(['alpha', 'gamma'], ['alpha', 'beta', 'gamma']);
+		expect([...alignment]).toEqual([0, -1, 1]);
+	});
+
+	it('accepts the fragment a hyphenated line break leaves behind', () => {
+		const alignment = alignWordStreams(
+			['achieves', 'englishto', 'translation'],
+			['achieves', 'englishtogerman', 'translation']
+		);
+		expect([...alignment]).toEqual([0, 1, 2]);
+	});
+
+	it('resumes after a long stretch that belongs to only one side', () => {
+		// The page's table, which the spoken layer narrates in its own words —
+		// charged per word, this gap would end the alignment here.
+		const page = [
+			'opening',
+			'sentence',
+			...Array.from({ length: 60 }, (_, index) => `cell${index}`),
+			'closing',
+			'sentence'
+		];
+		const alignment = alignWordStreams(page, ['opening', 'sentence', 'closing', 'sentence']);
+		expect([...alignment]).toEqual([0, 1, 62, 63]);
+	});
+
+	it('never reorders: a repeated phrase matches the run in sequence', () => {
+		const alignment = alignWordStreams(['a', 'b', 'a', 'b'], ['a', 'b']);
+		for (let index = 1; index < alignment.length; index += 1) {
+			expect(alignment[index]).toBeGreaterThan(alignment[index - 1]);
+		}
+	});
+
+	it('gives up rather than guessing on an oversized page', () => {
+		const huge = Array.from({ length: 2100 }, (_, index) => `w${index}`);
+		expect([...alignWordStreams(huge, huge)].every((value) => value === -1)).toBe(true);
+	});
+});
+
+describe('mergeWordRects', () => {
+	it('merges a run of boxes on one line into a single rectangle', () => {
+		const boxes = line('one two three', 100);
+		const last = boxes[boxes.length - 1];
+		expect(mergeWordRects(boxes)).toEqual([
+			{ x: 0, y: 100, width: last.x + last.width, height: 12 }
+		]);
+	});
+
+	it('starts a new rectangle on the next line', () => {
+		const merged = mergeWordRects([...line('one two', 100), ...line('three', 120)]);
+		expect(merged).toHaveLength(2);
+		expect(merged[1]).toEqual({ x: 0, y: 120, width: 50, height: 12 });
+	});
+
+	it('breaks at a column jump rather than sweeping across the gutter', () => {
+		const merged = mergeWordRects([
+			{ text: 'left', x: 40, y: 100, width: 40, height: 12 },
+			{ text: 'right', x: 300, y: 100, width: 40, height: 12 },
+			{ text: 'wrapped', x: 40, y: 100, width: 40, height: 12 }
+		]);
+		expect(merged).toHaveLength(2);
+	});
+});
+
+describe('placeSegments', () => {
+	const page = [
+		...line('The dominant sequence transduction models are based on', 100),
+		...line('complex recurrent or convolutional neural networks.', 120),
+		...line('We propose a new simple network architecture.', 140)
+	];
+
+	it('places a passage over the words it was extracted from', () => {
+		const [placement] = placeSegments(
+			page,
+			[placeable('s1', 'We propose a new simple network architecture.')],
+			1
+		);
+		expect(placement.segmentId).toBe('s1');
+		expect(placement.coverage).toBe(1);
+		const third = line('We propose a new simple network architecture.', 140);
+		const last = third[third.length - 1];
+		expect(placement.rects).toEqual([{ x: 0, y: 140, width: last.x + last.width, height: 12 }]);
+	});
+
+	it('boxes each word of the passage separately', () => {
+		const [placement] = placeSegments(page, [placeable('s1', 'We propose a new')], 1);
+		expect(placement.wordRects.map((rect) => rect?.x)).toEqual(
+			line('We propose a new', 140).map((box) => box.x)
+		);
+	});
+
+	it('leaves a hole for a word the page does not carry', () => {
+		const [placement] = placeSegments(page, [placeable('s1', 'We hereby propose a new')], 1);
+		expect(placement.wordRects[1]).toBeUndefined();
+		expect(placement.wordRects[0]).toBeDefined();
+		expect(placement.wordRects[2]).toBeDefined();
+	});
+
+	it('refuses a passage that only brushed the page', () => {
+		expect(
+			placeSegments(page, [placeable('s1', 'Entirely unrelated prose about a cat')], 1)
+		).toEqual([]);
+	});
+
+	it('keeps passages in document order across the page', () => {
+		const placements = placeSegments(
+			page,
+			[
+				placeable('s1', 'The dominant sequence transduction models'),
+				placeable('s2', 'We propose a new simple network architecture.')
+			],
+			1
+		);
+		expect(placements.map((placement) => placement.segmentId)).toEqual(['s1', 's2']);
+		expect(placements[0].rects[0].y).toBeLessThan(placements[1].rects[0].y);
+	});
+
+	it('looks for what the page prints when that differs from what is spoken', () => {
+		const table = [
+			...line('Layer Type Complexity per Layer', 200),
+			...line('Self-Attention Onnd Restricted', 220)
+		];
+		// The row is narrated with its header labels folded in; only its cells
+		// are on the page.
+		const spoken = 'Layer Type: Self-Attention. Complexity per Layer: Onnd.';
+		// Spoken as-is, the header labels pull the row up onto the header line.
+		const [narrated] = placeSegments(table, [placeable('row', spoken)], 1);
+		expect(narrated.rects[0].y).toBe(200);
+		const [placement] = placeSegments(
+			table,
+			[placeable('row', spoken, { matchText: 'Self-Attention Onnd Restricted' })],
+			1
+		);
+		expect(placement.rects[0].y).toBe(220);
+		// The words being spoken are not the words on the page.
+		expect(placement.wordRects.every((rect) => rect === undefined)).toBe(true);
+	});
+
+	it('finds a run of rows once its neighbours have staked out the region', () => {
+		const withTable = [
+			...line('Opening sentence above the table', 100),
+			...line('Alpha ninety Beta eighty', 130),
+			...line('Gamma seventy Delta sixty', 150),
+			...line('Closing sentence below the table', 180)
+		];
+		const placements = placeSegments(
+			withTable,
+			[
+				placeable('s1', 'Opening sentence above the table'),
+				placeable('r1', 'Alpha ninety Beta eighty'),
+				placeable('r2', 'Gamma seventy Delta sixty'),
+				placeable('s2', 'Closing sentence below the table')
+			],
+			1
+		);
+		expect(placements.map((placement) => placement.segmentId)).toEqual(['s1', 'r1', 'r2', 's2']);
+		expect(placements[1].rects[0].y).toBe(130);
+		expect(placements[2].rects[0].y).toBe(150);
+	});
+
+	it('has nothing to say about a page with no words', () => {
+		expect(placeSegments([], [placeable('s1', 'anything')], 1)).toEqual([]);
+	});
+});
+
+describe('segmentsForPage', () => {
+	function segment(id: string, text: string, page: number, blockId = 'b1'): SpeechSegment {
+		return {
+			id,
+			blockId,
+			text,
+			normalizedText: text,
+			start: 0,
+			end: text.length,
+			words: words(text),
+			estimatedDuration: 1,
+			anchor: { page }
+		};
+	}
+
+	it('is empty when nothing is anchored to the page', () => {
+		expect(segmentsForPage([segment('s1', 'one', 1)], 4)).toEqual([]);
+	});
+
+	it('reaches into the neighbouring pages for passages that straddle the break', () => {
+		const segments = [
+			segment('before', 'a sentence ending the previous page', 1),
+			segment('own', 'a sentence of its own', 2),
+			segment('after', 'a sentence opening the next page', 3)
+		];
+		expect(segmentsForPage(segments, 2).map((entry) => entry.id)).toEqual([
+			'before',
+			'own',
+			'after'
+		]);
+	});
+
+	it('stops spilling once the word budget runs out', () => {
+		const long = Array.from({ length: 80 }, (_, index) =>
+			segment(`p1-${index}`, 'ten words here that fill up the spill budget fast', 1)
+		);
+		const ids = segmentsForPage([...long, segment('own', 'the page itself', 2)], 2).map(
+			(entry) => entry.id
+		);
+		expect(ids).toContain('own');
+		expect(ids).not.toContain('p1-0');
+	});
+
+	it('carries the construct source through as what to look for on the page', () => {
+		const row = segment('row', 'Layer Type: Self-Attention.', 2);
+		row.start = 4;
+		row.end = 22;
+		const placeables = segmentsForPage([row], 2, new Map([['b1', 'xxx Self-Attention Onnd xxx']]));
+		expect(placeables[0].matchText).toBe('Self-Attention Onn');
+	});
+
+	it('leaves plain prose alone, so its words keep their boxes', () => {
+		const prose = segment('prose', 'a sentence of its own', 2);
+		const placeables = segmentsForPage([prose], 2, new Map([['b1', 'a sentence of its own']]));
+		expect(placeables[0].matchText).toBeUndefined();
+	});
+});
diff --git a/src/lib/domain/pdf-layout.ts b/src/lib/domain/pdf-layout.ts
new file mode 100644
index 0000000..81c638a
--- /dev/null
+++ b/src/lib/domain/pdf-layout.ts
@@ -0,0 +1,620 @@
+import type { SpeechSegment } from './types';
+
+/**
+ * Placing the spoken layer back onto the original page.
+ *
+ * The reader's passages come from the markdown LiteParse extracted; the page
+ * view draws the PDF itself. To highlight a passage where it actually sits on
+ * paper, the two have to be reconciled — and the only trustworthy bridge is
+ * that LiteParse can emit a box for every word it read (`emitWordBoxes`), so
+ * both sides descend from the same glyphs.
+ *
+ * Reconciliation is a monotonic sequence alignment: the page's words in
+ * reading order against the words of the passages anchored to that page.
+ * Content the spoken layer skips (equations, figure labels, running heads)
+ * falls out as gaps, and so does markdown the page renders differently
+ * (table pipes, heading hashes) — neither derails the words on either side of
+ * it. Nothing here touches the DOM or pdf.js: it is pure geometry over two
+ * token streams, so the hard part is testable.
+ *
+ * Coordinates throughout are PDF points with a **top-left** origin, matching
+ * LiteParse's boxes and the CSS the overlay ends up writing.
+ */
+
+export interface PageWordBox {
+	text: string;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+
+/** The slice of LiteParse's TextItem this module needs. */
+export interface PageTextItem {
+	text: string;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	/** Degrees off horizontal; rotated stamps (arXiv spines) are not prose. */
+	rotation?: number;
+	words?: PageWordBox[];
+}
+
+export interface PageRect {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+
+/** Where one passage landed on one page. */
+export interface SegmentPlacement {
+	segmentId: string;
+	page: number;
+	/** Line-merged rectangles covering the passage — what the overlay paints. */
+	rects: PageRect[];
+	/** Index-aligned to `SpeechSegment.words`; a hole is a word that found no
+	 * box (a substituted equation reading, a word the page hyphenated away). */
+	wordRects: Array<PageRect | undefined>;
+	/** Share of the passage's words that found a box, 0–1. */
+	coverage: number;
+}
+
+/** A passage reduced to what placement needs, so tests need no full segment. */
+export interface PlaceableSegment {
+	id: string;
+	text: string;
+	words: Array<{ start: number; end: number }>;
+	page: number;
+	/**
+	 * What to look for on the page, when that differs from what is spoken. A
+	 * table row is narrated as "Layer Type: Self-Attention. Complexity per
+	 * Layer: …" — prose assembled from the header labels, which the page never
+	 * printed in that form. Its cells, on the other hand, are right there.
+	 * Passages placed this way get no per-word boxes: the words being spoken
+	 * are not the words on the page, and only the region is meaningful.
+	 */
+	matchText?: string;
+}
+
+/**
+ * The comparison form of a word: compatibility-decomposed (so a `fi` ligature
+ * on the page meets the `fi` in the markdown), unaccented, lowercased, and
+ * stripped of everything that is not a letter or a digit. Punctuation must go
+ * — the page hyphenates and the markdown does not, and quotes differ on both
+ * sides of every extraction.
+ */
+export function matchKey(text: string): string {
+	return text
+		.normalize('NFKD')
+		.replace(/\p{M}+/gu, '')
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}]+/gu, '');
+}
+
+/** Every word LiteParse read on a page, in its reading order. Items without
+ * word boxes (older parses, OCR text) contribute their whole box, which still
+ * highlights at line granularity. */
+export function pageWordBoxes(items: PageTextItem[]): PageWordBox[] {
+	const boxes: PageWordBox[] = [];
+	for (const item of items) {
+		if (item.rotation !== undefined && Math.abs(item.rotation) > 1) continue;
+		if (item.words?.length) {
+			for (const word of item.words) if (word.text.trim()) boxes.push(word);
+		} else if (item.text.trim()) {
+			boxes.push({
+				text: item.text,
+				x: item.x,
+				y: item.y,
+				width: item.width,
+				height: item.height
+			});
+		}
+	}
+	return boxes;
+}
+
+interface Chunk {
+	key: string;
+	start: number;
+	end: number;
+}
+
+/** Whitespace-separated chunks with their character ranges, keyed for
+ * comparison. Splitting on whitespace (not on letter runs) keeps both streams
+ * tokenized the same way, so `don't` stays one token against the page's one
+ * box for it. Chunks that key to nothing — a lone bullet, a stray dash — are
+ * dropped: they carry no evidence and would only invite false matches. */
+export function chunkText(text: string): Chunk[] {
+	const chunks: Chunk[] = [];
+	for (const match of text.matchAll(/\S+/gu)) {
+		const start = match.index ?? 0;
+		const key = matchKey(match[0]);
+		if (key) chunks.push({ key, start, end: start + match[0].length });
+	}
+	return chunks;
+}
+
+/** Cheap enough to be exact for a page; the guard only exists so a pathological
+ * page (a word list, a dense table) cannot lock the main thread. */
+const MAX_ALIGNMENT_CELLS = 4_000_000;
+
+const SCORE_MATCH = 1;
+/** A hyphenated break leaves the page holding a fragment of the markdown's
+ * word (`englishto` for `englishtogerman`). Scoring that as most of a match
+ * keeps the alignment on the diagonal, where treating it as a mismatch would
+ * derail it. */
+const SCORE_PARTIAL = 0.5;
+const SCORE_MISMATCH = -1;
+/**
+ * Skips are priced as one decision, not per word: opening a run of unmatched
+ * words costs, continuing it barely does. This is what lets the two streams
+ * survive each other's bulk. A page carries equations, axis labels and
+ * running heads the spoken layer never says; the spoken layer carries whole
+ * paragraphs the page never printed (a table's narration, "A table with
+ * columns: …"). Charged per word, one such stretch would outweigh every match
+ * after it and the alignment would simply stop there — which is exactly what
+ * a flat gap penalty did: everything below Table 1 on a page went unplaced.
+ *
+ * Opening a gap also has to stay cheaper than a single match is worth, or the
+ * free ends win instead: an alignment that starts late and matches three
+ * words cleanly would outscore one that matches five with a skip in the
+ * middle, and the two words before the skip would be dropped for no reason.
+ */
+const SCORE_GAP_OPEN = -0.6;
+const SCORE_GAP_EXTEND = -0.02;
+
+function pairScore(left: string, right: string): number {
+	if (left === right) return SCORE_MATCH;
+	if (left.length >= 4 && right.length >= 4 && (left.startsWith(right) || right.startsWith(left))) {
+		return SCORE_PARTIAL;
+	}
+	return SCORE_MISMATCH;
+}
+
+/** Traceback states: a pair, an unmatched expected word, an unmatched page
+ * word. */
+const PAIRED = 0;
+const EXPECTED_GAP = 1;
+const PAGE_GAP = 2;
+
+/**
+ * Monotonic alignment of the expected words (the spoken layer's) against the
+ * page's, returning the page index each expected word landed on, or -1.
+ *
+ * Gotoh's affine-gap alignment with both ends free. Free ends because neither
+ * stream has to be consumed whole — the expected stream deliberately carries
+ * a little of the neighbouring pages. Affine gaps because both streams are
+ * full of material the other lacks, and skipping it has to stay cheap enough
+ * that the alignment resumes afterwards (see the gap constants above).
+ *
+ * Only pairs that actually agree are reported: the path threads through
+ * mismatches to stay on course, but a mismatch is not evidence of where a
+ * word sits.
+ */
+export function alignWordStreams(pageKeys: string[], expectedKeys: string[]): Int32Array {
+	const rows = expectedKeys.length;
+	const columns = pageKeys.length;
+	const result = new Int32Array(rows).fill(-1);
+	if (!rows || !columns || (rows + 1) * (columns + 1) > MAX_ALIGNMENT_CELLS) return result;
+
+	const width = columns + 1;
+	// Scores roll row by row; only the traceback needs the whole grid.
+	let pairedRow = new Float32Array(width);
+	let expectedGapRow = new Float32Array(width);
+	let pageGapRow = new Float32Array(width);
+	let nextPaired = new Float32Array(width);
+	let nextExpectedGap = new Float32Array(width);
+	let nextPageGap = new Float32Array(width);
+	// Which state each cell was reached from: for a pair, the predecessor
+	// state; for a gap, whether it opened (0) or extended (1).
+	const fromPaired = new Uint8Array((rows + 1) * width);
+	const fromExpectedGap = new Uint8Array((rows + 1) * width);
+	const fromPageGap = new Uint8Array((rows + 1) * width);
+
+	let bestScore = 0;
+	let bestRow = 0;
+	let bestColumn = 0;
+	let bestState = PAIRED;
+
+	for (let row = 1; row <= rows; row += 1) {
+		// Row 0 and column 0 stay at zero: an alignment may start anywhere in
+		// either stream without paying for the prefix it skipped.
+		nextPaired[0] = 0;
+		nextExpectedGap[0] = 0;
+		nextPageGap[0] = 0;
+		const base = row * width;
+		for (let column = 1; column <= columns; column += 1) {
+			const previous = Math.max(
+				pairedRow[column - 1],
+				expectedGapRow[column - 1],
+				pageGapRow[column - 1]
+			);
+			nextPaired[column] = previous + pairScore(expectedKeys[row - 1], pageKeys[column - 1]);
+			fromPaired[base + column] =
+				previous === pairedRow[column - 1]
+					? PAIRED
+					: previous === expectedGapRow[column - 1]
+						? EXPECTED_GAP
+						: PAGE_GAP;
+
+			const openExpected = pairedRow[column] + SCORE_GAP_OPEN + SCORE_GAP_EXTEND;
+			const extendExpected = expectedGapRow[column] + SCORE_GAP_EXTEND;
+			nextExpectedGap[column] = Math.max(openExpected, extendExpected);
+			fromExpectedGap[base + column] = extendExpected > openExpected ? 1 : 0;
+
+			const openPage = nextPaired[column - 1] + SCORE_GAP_OPEN + SCORE_GAP_EXTEND;
+			const extendPage = nextPageGap[column - 1] + SCORE_GAP_EXTEND;
+			nextPageGap[column] = Math.max(openPage, extendPage);
+			fromPageGap[base + column] = extendPage > openPage ? 1 : 0;
+
+			// Ending is free as well, so the alignment stops at its best point on
+			// either final edge rather than being dragged into the far corner.
+			if ((row === rows || column === columns) && nextPaired[column] > bestScore) {
+				bestScore = nextPaired[column];
+				bestRow = row;
+				bestColumn = column;
+				bestState = PAIRED;
+			}
+		}
+		[pairedRow, nextPaired] = [nextPaired, pairedRow];
+		[expectedGapRow, nextExpectedGap] = [nextExpectedGap, expectedGapRow];
+		[pageGapRow, nextPageGap] = [nextPageGap, pageGapRow];
+	}
+
+	let row = bestRow;
+	let column = bestColumn;
+	let state = bestState;
+	while (row > 0 && column > 0) {
+		const cell = row * width + column;
+		if (state === PAIRED) {
+			if (pairScore(expectedKeys[row - 1], pageKeys[column - 1]) > 0) {
+				result[row - 1] = column - 1;
+			}
+			state = fromPaired[cell];
+			row -= 1;
+			column -= 1;
+		} else if (state === EXPECTED_GAP) {
+			state = fromExpectedGap[cell] === 1 ? EXPECTED_GAP : PAIRED;
+			row -= 1;
+		} else {
+			state = fromPageGap[cell] === 1 ? PAGE_GAP : PAIRED;
+			column -= 1;
+		}
+	}
+	return result;
+}
+
+function unionRect(rects: PageRect[]): PageRect {
+	let left = Infinity;
+	let top = Infinity;
+	let right = -Infinity;
+	let bottom = -Infinity;
+	for (const rect of rects) {
+		left = Math.min(left, rect.x);
+		top = Math.min(top, rect.y);
+		right = Math.max(right, rect.x + rect.width);
+		bottom = Math.max(bottom, rect.y + rect.height);
+	}
+	return { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+/**
+ * Collapse a passage's word boxes into one rectangle per line, in reading
+ * order. Boxes join a run while they sit on the same line (vertical centres
+ * within half a line height) and do not jump backwards across the page —
+ * a backwards jump is a column break, which has to start a new rectangle or
+ * the highlight would sweep across the gutter.
+ */
+export function mergeWordRects(boxes: PageRect[]): PageRect[] {
+	const merged: PageRect[] = [];
+	let run: PageRect[] = [];
+	const flush = () => {
+		if (run.length) merged.push(unionRect(run));
+		run = [];
+	};
+	for (const box of boxes) {
+		const previous = run[run.length - 1];
+		if (previous) {
+			const sameLine =
+				Math.abs(box.y + box.height / 2 - (previous.y + previous.height / 2)) <
+				Math.max(box.height, previous.height) / 2;
+			if (!sameLine || box.x + box.width < previous.x) flush();
+		}
+		run.push(box);
+	}
+	flush();
+	return merged;
+}
+
+/**
+ * Below this, a placement is guesswork: a couple of stray words matched
+ * somewhere on the page while the passage itself is elsewhere. Painting those
+ * would put the highlight in the wrong place, which is worse than not
+ * painting it. The refinement pass is allowed to be less strict, because by
+ * then the passage is boxed in by its placed neighbours and cannot land far
+ * from where it belongs.
+ */
+const MIN_COVERAGE = 0.35;
+const MIN_REFINED_COVERAGE = 0.2;
+/** One refinement of each unclaimed gap is enough in practice; the limit is
+ * only here so a pathological page cannot recurse indefinitely. */
+const MAX_REFINEMENT_DEPTH = 2;
+
+interface ExpectedChunk extends Chunk {
+	segment: number;
+}
+
+/**
+ * Align a slice of the expected stream against a slice of the page, then look
+ * at what went unplaced.
+ *
+ * A run of passages that all failed together usually failed for one reason:
+ * the page renders them in a form the spoken layer rewrote — a table, whose
+ * rows are narrated as "Layer Type: Self-Attention. Complexity per Layer: …"
+ * against a page holding a grid of bare cells. Whole-page alignment cannot
+ * find those rows among a thousand competing words, but the run is bracketed
+ * by passages that *did* place, and the page words between those two brackets
+ * are exactly the table. Aligning the run against that much smaller stretch
+ * usually lands it.
+ */
+function assignRange(
+	boxes: PageWordBox[],
+	pageKeys: string[],
+	expected: ExpectedChunk[],
+	matches: Array<number[]>,
+	range: { boxLow: number; boxHigh: number; chunkLow: number; chunkHigh: number },
+	depth: number
+): void {
+	const { boxLow, boxHigh, chunkLow, chunkHigh } = range;
+	if (boxLow > boxHigh || chunkLow > chunkHigh) return;
+	const alignment = alignWordStreams(
+		pageKeys.slice(boxLow, boxHigh + 1),
+		expected.slice(chunkLow, chunkHigh + 1).map((chunk) => chunk.key)
+	);
+	for (let index = 0; index < alignment.length; index += 1) {
+		const box = alignment[index];
+		if (box >= 0) matches[chunkLow + index].push(boxLow + box);
+	}
+
+	const minimum = depth === 0 ? MIN_COVERAGE : MIN_REFINED_COVERAGE;
+	// Which of the passages in this range came out placed, so the gaps between
+	// them can be retried against the page they must lie on.
+	const segmentLow = expected[chunkLow].segment;
+	const segmentHigh = expected[chunkHigh].segment;
+	const placed = new Map<number, { first: number; last: number }>();
+	for (let segment = segmentLow; segment <= segmentHigh; segment += 1) {
+		let total = 0;
+		let first = Infinity;
+		let last = -Infinity;
+		for (let index = chunkLow; index <= chunkHigh; index += 1) {
+			if (expected[index].segment !== segment) continue;
+			total += 1;
+			const box = matches[index][matches[index].length - 1];
+			if (box === undefined) continue;
+			first = Math.min(first, box);
+			last = Math.max(last, box);
+		}
+		const covered = countMatched(expected, matches, chunkLow, chunkHigh, segment);
+		if (total && covered / total >= minimum) placed.set(segment, { first, last });
+	}
+	if (depth >= MAX_REFINEMENT_DEPTH) return;
+
+	let runStart: number | undefined;
+	for (let segment = segmentLow; segment <= segmentHigh + 1; segment += 1) {
+		if (segment <= segmentHigh && !placed.has(segment)) {
+			runStart ??= segment;
+			continue;
+		}
+		if (runStart === undefined) continue;
+		const runEnd = segment - 1;
+		const before = previousPlaced(placed, runStart - 1, segmentLow);
+		const after = nextPlaced(placed, runEnd + 1, segmentHigh);
+		const nextRange = {
+			boxLow: before === undefined ? boxLow : before + 1,
+			boxHigh: after === undefined ? boxHigh : after - 1,
+			chunkLow: firstChunkOf(expected, chunkLow, chunkHigh, runStart),
+			chunkHigh: lastChunkOf(expected, chunkLow, chunkHigh, runEnd)
+		};
+		runStart = undefined;
+		// No narrowing happened: retrying the same range would only repeat this
+		// pass's answer.
+		if (
+			nextRange.chunkLow === undefined ||
+			nextRange.chunkHigh === undefined ||
+			(nextRange.boxLow === boxLow && nextRange.boxHigh === boxHigh)
+		) {
+			continue;
+		}
+		assignRange(
+			boxes,
+			pageKeys,
+			expected,
+			matches,
+			nextRange as { boxLow: number; boxHigh: number; chunkLow: number; chunkHigh: number },
+			depth + 1
+		);
+	}
+}
+
+function countMatched(
+	expected: ExpectedChunk[],
+	matches: Array<number[]>,
+	low: number,
+	high: number,
+	segment: number
+): number {
+	let count = 0;
+	for (let index = low; index <= high; index += 1) {
+		if (expected[index].segment === segment && matches[index].length) count += 1;
+	}
+	return count;
+}
+
+function previousPlaced(
+	placed: Map<number, { first: number; last: number }>,
+	from: number,
+	low: number
+): number | undefined {
+	for (let segment = from; segment >= low; segment -= 1) {
+		const entry = placed.get(segment);
+		if (entry) return entry.last;
+	}
+	return undefined;
+}
+
+function nextPlaced(
+	placed: Map<number, { first: number; last: number }>,
+	from: number,
+	high: number
+): number | undefined {
+	for (let segment = from; segment <= high; segment += 1) {
+		const entry = placed.get(segment);
+		if (entry) return entry.first;
+	}
+	return undefined;
+}
+
+function firstChunkOf(
+	expected: ExpectedChunk[],
+	low: number,
+	high: number,
+	segment: number
+): number | undefined {
+	for (let index = low; index <= high; index += 1) {
+		if (expected[index].segment === segment) return index;
+	}
+	return undefined;
+}
+
+function lastChunkOf(
+	expected: ExpectedChunk[],
+	low: number,
+	high: number,
+	segment: number
+): number | undefined {
+	for (let index = high; index >= low; index -= 1) {
+		if (expected[index].segment === segment) return index;
+	}
+	return undefined;
+}
+
+/**
+ * Place every passage anchored to a page onto that page's words.
+ *
+ * `segments` should be given in document order and may include a little of the
+ * neighbouring pages: a paragraph that starts on one page and finishes on the
+ * next is one passage, and the alignment's free end gaps let the part that
+ * belongs elsewhere go unmatched rather than dragging the rest off course.
+ */
+export function placeSegments(
+	boxes: PageWordBox[],
+	segments: PlaceableSegment[],
+	page: number
+): SegmentPlacement[] {
+	const pageKeys = boxes.map((box) => matchKey(box.text));
+	const expected: ExpectedChunk[] = [];
+	segments.forEach((segment, index) => {
+		for (const chunk of chunkText(segment.matchText ?? segment.text)) {
+			expected.push({ ...chunk, segment: index });
+		}
+	});
+	if (!expected.length || !pageKeys.length) return [];
+	const matches: Array<number[]> = expected.map(() => []);
+	assignRange(
+		boxes,
+		pageKeys,
+		expected,
+		matches,
+		{ boxLow: 0, boxHigh: pageKeys.length - 1, chunkLow: 0, chunkHigh: expected.length - 1 },
+		0
+	);
+
+	const placements: SegmentPlacement[] = [];
+	segments.forEach((segment, index) => {
+		const matched: Array<{ chunk: Chunk; box: PageWordBox }> = [];
+		let total = 0;
+		expected.forEach((chunk, chunkIndex) => {
+			if (chunk.segment !== index) return;
+			total += 1;
+			// The last assignment wins: a refinement pass ran against a narrower
+			// stretch of the page and knows better than the whole-page sweep.
+			const box = matches[chunkIndex][matches[chunkIndex].length - 1];
+			if (box !== undefined) matched.push({ chunk, box: boxes[box] });
+		});
+		const coverage = total ? matched.length / total : 0;
+		if (!matched.length || coverage < MIN_REFINED_COVERAGE) return;
+		matched.sort((left, right) => left.chunk.start - right.chunk.start);
+		const wordRects = segment.matchText
+			? segment.words.map(() => undefined)
+			: segment.words.map((word) => {
+					const overlapping = matched
+						.filter(({ chunk }) => chunk.start < word.end && chunk.end > word.start)
+						.map(({ box }) => box);
+					return overlapping.length ? unionRect(overlapping) : undefined;
+				});
+		placements.push({
+			segmentId: segment.id,
+			page,
+			rects: mergeWordRects(matched.map(({ box }) => box)),
+			wordRects,
+			coverage
+		});
+	});
+	return placements;
+}
+
+/** How much of each neighbouring page's passages to align alongside a page's
+ * own, in words. A paragraph that straddles a page break is one passage list
+ * anchored to the earlier page, so the later page has to look back far enough
+ * to find the sentences that actually landed on it. */
+const SPILL_WORDS = 400;
+
+/** The passages to align against one page: everything anchored to it, plus a
+ * stretch of each neighbour so a paragraph straddling the page break is placed
+ * from whichever side is looking.
+ *
+ * `blockText` (block id → block text) is what lets a narrated construct be
+ * looked for as it appears on paper rather than as it is spoken: a segment's
+ * `start`/`end` index its block's text, so that slice is the construct's own
+ * source — a table row's cells, an equation's characters — while
+ * `segment.text` is the reading. Without it, tables and equations simply go
+ * unplaced.
+ */
+export function segmentsForPage(
+	segments: SpeechSegment[],
+	page: number,
+	blockText?: ReadonlyMap<string, string>,
+	spillWords = SPILL_WORDS
+): PlaceableSegment[] {
+	let first = -1;
+	let last = -1;
+	segments.forEach((segment, index) => {
+		if (segment.anchor.page !== page) return;
+		if (first < 0) first = index;
+		last = index;
+	});
+	if (first < 0) return [];
+	let from = first;
+	for (let budget = spillWords; from > 0 && budget > 0; from -= 1) {
+		budget -= segments[from - 1].words.length;
+	}
+	let to = last;
+	for (let budget = spillWords; to < segments.length - 1 && budget > 0; to += 1) {
+		budget -= segments[to + 1].words.length;
+	}
+	const placeable: PlaceableSegment[] = [];
+	for (let index = from; index <= to; index += 1) {
+		const segment = segments[index];
+		const source = blockText?.get(segment.blockId)?.slice(segment.start, segment.end);
+		placeable.push({
+			id: segment.id,
+			text: segment.text,
+			words: segment.words,
+			page: segment.anchor.page ?? page,
+			...(source && source !== segment.text ? { matchText: source } : {})
+		});
+	}
+	return placeable;
+}
diff --git a/vite.config.ts b/vite.config.ts
index 09f400c..d02cc67 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -77,6 +77,7 @@ export default defineConfig({
 				'src/lib/domain/importers.ts',
 				'src/lib/domain/model-catalog.ts',
 				'src/lib/domain/pages.ts',
+				'src/lib/domain/pdf-layout.ts',
 				'src/lib/domain/pdf-markdown.ts',
 				'src/lib/domain/segmenter.ts',
 				'src/lib/domain/study-tree.ts',

From 4268f24e565f3351fedaab0c1def2b65d35a73c5 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Wed, 26 Aug 2026 23:13:45 -0500
Subject: [PATCH 02/15] feat: read a PDF as its own pages, with the narration
 painted on
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A second reader view draws the original PDF and highlights the passage
being spoken where it actually sits on the paper, down to the word. The
markdown stays underneath as it always was — it is what the voice, the
assistant, and the study layer read — so the choice is presentation, not
a different import.

Geometry is recomputed per page from the stored bytes (LiteParse
`targetPages` + `emitWordBoxes`, tens of milliseconds a page) rather than
stored per document, as `DocumentPageInfo` anticipated. Pages draw and
place lazily as they come near the scrollport and hand their bitmaps back
when they leave.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte | 393 +++++++++++++++++++++++
 src/lib/services/pdf-layout.ts        | 191 +++++++++++
 src/lib/state/reader-chrome.svelte.ts |  33 ++
 src/routes/+layout.svelte             |  25 ++
 src/routes/read/+page.svelte          | 438 ++++++++++++++------------
 5 files changed, 876 insertions(+), 204 deletions(-)
 create mode 100644 src/lib/components/PdfPageView.svelte
 create mode 100644 src/lib/services/pdf-layout.ts

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
new file mode 100644
index 0000000..c6ba8e8
--- /dev/null
+++ b/src/lib/components/PdfPageView.svelte
@@ -0,0 +1,393 @@
+<script lang="ts">
+	import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+	import type { NormalizedDocument, SpeechSegment } from '$lib/domain/types';
+	import type { PageRect, SegmentPlacement } from '$lib/domain/pdf-layout';
+	import { openPdfRenderer } from '$lib/services/pdf-pages';
+	import { openPdfLayout } from '$lib/services/pdf-layout';
+	import { readerChrome } from '$lib/state/reader-chrome.svelte';
+
+	interface Props {
+		document: NormalizedDocument;
+		pageCount: number;
+		/** The live passages — placement is recomputed when these are rebound. */
+		segments: SpeechSegment[];
+		activeSegmentId?: string;
+		activeWordIndex?: number;
+		/** Whether playback should pull the page along with it. */
+		follow?: boolean;
+		onPlaySegment: (segmentId: string) => void;
+	}
+
+	let {
+		document: book,
+		pageCount,
+		segments,
+		activeSegmentId,
+		activeWordIndex,
+		follow = true,
+		onPlaySegment
+	}: Props = $props();
+
+	/** US Letter, for a document whose parse recorded no page sizes. */
+	const FALLBACK_WIDTH = 612;
+	const FALLBACK_HEIGHT = 792;
+	/** Pages this far outside the scrollport are drawn ahead of being reached,
+	 * and kept a while after leaving, so ordinary scrolling never waits. */
+	const PREPARE_MARGIN = '150% 0px';
+
+	let scroller = $state<HTMLElement>();
+	const canvases = new SvelteMap<number, HTMLCanvasElement>();
+	/** Pages near enough the scrollport to be worth drawing. */
+	const live = new SvelteSet<number>();
+	/** Page → CSS pixels per PDF point, read back from the rendered canvas so
+	 * the overlay follows the bitmap rather than a predicted size. */
+	const scales = new SvelteMap<number, number>();
+	const placements = new SvelteMap<number, Map<string, SegmentPlacement>>();
+	let hovered = $state<{ page: number; segmentId: string }>();
+
+	let sizes = $derived.by(() => {
+		const stored = new Map((book.pages ?? []).map((entry) => [entry.page, entry]));
+		return Array.from({ length: pageCount }, (_, index) => {
+			const page = index + 1;
+			const entry = stored.get(page);
+			return {
+				page,
+				width: entry?.width || FALLBACK_WIDTH,
+				height: entry?.height || FALLBACK_HEIGHT
+			};
+		});
+	});
+
+	/** The width a page is drawn at, in CSS pixels: the reader's canvas width,
+	 * capped so a page never overflows the column it sits in. */
+	let renderWidth = $derived(readerChrome.documentCanvasWidth);
+
+	let blockText = $derived(new Map(book.blocks.map((block) => [block.id, block.text])));
+
+	/** Which page each passage was placed on, once its page has been looked at.
+	 * Playback drives the highlight, and the passage it names may be anchored
+	 * to one page but printed on the next. */
+	let pageBySegment = $derived.by(() => {
+		const found = new SvelteMap<string, number>();
+		for (const [page, placed] of placements) {
+			for (const segmentId of placed.keys()) if (!found.has(segmentId)) found.set(segmentId, page);
+		}
+		return found;
+	});
+
+	let activePlacement = $derived.by(() => {
+		if (!activeSegmentId) return undefined;
+		const page = pageBySegment.get(activeSegmentId);
+		return page === undefined ? undefined : placements.get(page)?.get(activeSegmentId);
+	});
+
+	let activeWordRect = $derived(
+		activeWordIndex === undefined ? undefined : activePlacement?.wordRects[activeWordIndex]
+	);
+
+	function trackPage(page: number) {
+		return (node: HTMLElement) => {
+			const observer = new IntersectionObserver(
+				(entries) => {
+					for (const entry of entries) {
+						if (entry.isIntersecting) live.add(page);
+						else live.delete(page);
+					}
+				},
+				{ root: scroller ?? null, rootMargin: PREPARE_MARGIN }
+			);
+			observer.observe(node);
+			return () => {
+				observer.disconnect();
+				live.delete(page);
+			};
+		};
+	}
+
+	function trackCanvas(page: number) {
+		return (node: HTMLCanvasElement) => {
+			canvases.set(page, node);
+			return () => {
+				canvases.delete(page);
+				scales.delete(page);
+			};
+		};
+	}
+
+	// Draw the pages that are in play, at the current zoom. Re-runs on zoom
+	// because the bitmap is rendered at the display size, not scaled up from a
+	// smaller one — a PDF page enlarged from a stale raster is a blurry page.
+	$effect(() => {
+		const width = renderWidth;
+		const pages = new Set(live);
+		// A page that has scrolled well away gives its bitmap back: a long
+		// document would otherwise accumulate one full-size raster per page
+		// visited, which is where a page view runs out of memory.
+		for (const [page, canvas] of canvases) {
+			if (pages.has(page) || !scales.has(page)) continue;
+			canvas.width = 0;
+			canvas.height = 0;
+			scales.delete(page);
+		}
+		let cancelled = false;
+		void openPdfRenderer(book).then(async (renderer) => {
+			if (!renderer || cancelled) return;
+			for (const page of pages) {
+				if (cancelled) return;
+				const canvas = canvases.get(page);
+				if (!canvas || scales.get(page) === width / pageWidth(page)) continue;
+				try {
+					await renderer.renderPage(page, canvas, width);
+					if (!cancelled) scales.set(page, width / pageWidth(page));
+				} catch {
+					// A page that will not draw stays blank; the rest still read.
+				}
+			}
+		});
+		return () => {
+			cancelled = true;
+		};
+	});
+
+	// Place the passages on the pages in play. Independent of drawing: the
+	// highlight can arrive after the bitmap, or before it.
+	let placedAgainst: SpeechSegment[] | undefined;
+	$effect(() => {
+		const pages = [...live];
+		const currentSegments = segments;
+		// Rebinding the passages (a listening-mode switch, a narration swap)
+		// mints new segment ids, so everything placed against the old ones is
+		// stale — including whatever is mid-flight.
+		if (placedAgainst !== currentSegments) {
+			placedAgainst = currentSegments;
+			placements.clear();
+		}
+		const layout = openPdfLayout(book);
+		let cancelled = false;
+		for (const page of pages) {
+			if (placements.has(page)) continue;
+			void layout.placements(page, pageCount, currentSegments, blockText).then((placed) => {
+				if (!cancelled && placedAgainst === currentSegments) placements.set(page, placed);
+			});
+		}
+		return () => {
+			cancelled = true;
+		};
+	});
+
+	function pageWidth(page: number): number {
+		return sizes[page - 1]?.width || FALLBACK_WIDTH;
+	}
+
+	function pageScale(page: number): number {
+		return scales.get(page) ?? renderWidth / pageWidth(page);
+	}
+
+	function styleFor(rect: PageRect, page: number): string {
+		const scale = pageScale(page);
+		return `left:${rect.x * scale}px;top:${rect.y * scale}px;width:${rect.width * scale}px;height:${rect.height * scale}px`;
+	}
+
+	/** The passage under a point on a page, in PDF points. Rectangles are
+	 * tested with a little vertical slack: line boxes stop at the type's
+	 * bounds, and the gap between two lines belongs to one of them. */
+	function segmentAt(page: number, x: number, y: number): string | undefined {
+		const placed = placements.get(page);
+		if (!placed) return undefined;
+		for (const [segmentId, placement] of placed) {
+			for (const rect of placement.rects) {
+				if (
+					x >= rect.x &&
+					x <= rect.x + rect.width &&
+					y >= rect.y - rect.height * 0.25 &&
+					y <= rect.y + rect.height * 1.25
+				) {
+					return segmentId;
+				}
+			}
+		}
+		return undefined;
+	}
+
+	function pointerPoint(event: PointerEvent | MouseEvent, page: number): { x: number; y: number } {
+		const bounds = (event.currentTarget as HTMLElement).getBoundingClientRect();
+		const scale = pageScale(page);
+		return { x: (event.clientX - bounds.left) / scale, y: (event.clientY - bounds.top) / scale };
+	}
+
+	function handleHover(event: PointerEvent, page: number): void {
+		const { x, y } = pointerPoint(event, page);
+		const segmentId = segmentAt(page, x, y);
+		if (hovered?.segmentId === segmentId && hovered?.page === page) return;
+		hovered = segmentId ? { page, segmentId } : undefined;
+	}
+
+	function handleActivate(event: MouseEvent, page: number): void {
+		const { x, y } = pointerPoint(event, page);
+		const segmentId = segmentAt(page, x, y);
+		if (segmentId) onPlaySegment(segmentId);
+	}
+
+	/** Bring a page into view by number — the fallback for a passage whose
+	 * page has not been placed yet, and what the jump control uses. */
+	export function goToPage(page: number): void {
+		const element = scroller?.querySelector<HTMLElement>(`[data-page="${page}"]`);
+		element?.scrollIntoView({ block: 'start', behavior: 'auto' });
+	}
+
+	// Follow playback. A passage already comfortably on screen stays put:
+	// re-centring every sentence would drag the page under the reader's eyes.
+	$effect(() => {
+		if (!follow || !activeSegmentId || !scroller) return;
+		const page = pageBySegment.get(activeSegmentId);
+		const placement = activePlacement;
+		const target = page === undefined ? undefined : scroller.querySelector(`[data-page="${page}"]`);
+		if (page === undefined || !(target instanceof HTMLElement)) {
+			const anchored = segments.find((segment) => segment.id === activeSegmentId)?.anchor.page;
+			if (anchored) goToPage(anchored);
+			return;
+		}
+		const rect = placement?.rects[0];
+		if (!rect) return;
+		const scale = pageScale(page);
+		const top = target.offsetTop + rect.y * scale;
+		const height = rect.height * scale;
+		const settled = 72;
+		const visibleFrom = scroller.scrollTop + settled;
+		const visibleTo = scroller.scrollTop + scroller.clientHeight - settled;
+		if (top >= visibleFrom && top + height <= visibleTo) return;
+		const centered = top - (scroller.clientHeight - height) / 2;
+		const maximum = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+		const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+		const next = Math.max(0, Math.min(maximum, centered));
+		const longJump = Math.abs(next - scroller.scrollTop) > scroller.clientHeight * 1.5;
+		scroller.scrollTo({ top: next, behavior: reducedMotion || longJump ? 'auto' : 'smooth' });
+	});
+</script>
+
+<div class="page-stack" bind:this={scroller}>
+	{#each sizes as size (size.page)}
+		{@const scale = pageScale(size.page)}
+		{@const placed = placements.get(size.page)}
+		<div class="page-slot" data-page={size.page} {@attach trackPage(size.page)}>
+			<span class="page-number" aria-hidden="true">{size.page}</span>
+			<!-- The page is a picture of paper, and the passages on it are
+			     reached by pointer; the keyboard route to the same passages is
+			     the reading view, which the toolbar switches to. -->
+			<!-- svelte-ignore a11y_no_static_element_interactions -->
+			<div
+				class="page-sheet"
+				style:width={`${size.width * scale}px`}
+				style:height={`${size.height * scale}px`}
+				ondblclick={(event) => handleActivate(event, size.page)}
+				onpointermove={(event) => handleHover(event, size.page)}
+				onpointerleave={() => (hovered = undefined)}
+			>
+				<canvas {@attach trackCanvas(size.page)} aria-label={`Page ${size.page} of ${book.title}`}
+				></canvas>
+				{#if live.has(size.page)}
+					<div class="page-marks" aria-hidden="true">
+						{#if hovered?.page === size.page && hovered.segmentId !== activeSegmentId}
+							{#each placed?.get(hovered.segmentId)?.rects ?? [] as rect, index (index)}
+								<span class="mark hover" style={styleFor(rect, size.page)}></span>
+							{/each}
+						{/if}
+						{#if activeSegmentId && placed?.has(activeSegmentId)}
+							{#each placed.get(activeSegmentId)?.rects ?? [] as rect, index (index)}
+								<span class="mark passage" style={styleFor(rect, size.page)}></span>
+							{/each}
+							{#if activeWordRect}
+								<span class="mark word" style={styleFor(activeWordRect, size.page)}></span>
+							{/if}
+						{/if}
+					</div>
+				{/if}
+			</div>
+		</div>
+	{/each}
+</div>
+
+<style>
+	.page-stack {
+		display: flex;
+		flex: 1;
+		flex-direction: column;
+		align-items: center;
+		gap: 26px;
+		overflow: auto;
+		padding: calc(var(--app-header-height) + 22px) 20px calc(var(--player-height) + 32px);
+		scroll-padding-block: calc(var(--app-header-height) + 22px) calc(var(--player-height) + 32px);
+	}
+
+	.page-slot {
+		position: relative;
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+	}
+
+	.page-number {
+		margin-bottom: 6px;
+		color: var(--muted);
+		font-family: var(--font-ui);
+		font-size: 11px;
+		font-variant-numeric: tabular-nums;
+		letter-spacing: 0.06em;
+	}
+
+	/* The sheet keeps its size before anything is drawn into it, so the
+	   scrollbar is honest from the first frame and page jumps land. */
+	.page-sheet {
+		position: relative;
+		border: 1px solid var(--line);
+		border-radius: 3px;
+		background: white;
+		box-shadow: 0 6px 20px rgba(0, 0, 0, 0.18);
+	}
+
+	.page-sheet canvas {
+		display: block;
+		width: 100%;
+		height: 100%;
+	}
+
+	/* Multiply keeps the marks under the ink: a highlighted line stays as
+	   readable as an unhighlighted one, which is the whole point of reading
+	   the original. */
+	.page-marks {
+		position: absolute;
+		mix-blend-mode: multiply;
+		inset: 0;
+	}
+
+	.mark {
+		position: absolute;
+		border-radius: 2px;
+		transition:
+			left 90ms var(--ease),
+			top 90ms var(--ease),
+			width 90ms var(--ease);
+	}
+
+	/* Weighted for white paper under a multiply blend, not for the reader's
+	   own background — the same mix that reads as a wash in the reading view
+	   nearly disappears here. */
+	.mark.passage {
+		background: color-mix(in srgb, var(--primary) 30%, transparent);
+	}
+
+	.mark.hover {
+		background: color-mix(in srgb, var(--primary) 12%, transparent);
+	}
+
+	.mark.word {
+		background: var(--active-word-bg, rgba(112, 176, 143, 0.34));
+		box-shadow: 0 0 0 0.1em var(--active-word-bg, rgba(112, 176, 143, 0.34));
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.mark {
+			transition: none;
+		}
+	}
+</style>
diff --git a/src/lib/services/pdf-layout.ts b/src/lib/services/pdf-layout.ts
new file mode 100644
index 0000000..0b4ee33
--- /dev/null
+++ b/src/lib/services/pdf-layout.ts
@@ -0,0 +1,191 @@
+import type { NormalizedDocument, SpeechSegment } from '../domain/types';
+import {
+	pageWordBoxes,
+	placeSegments,
+	segmentsForPage,
+	type PageWordBox,
+	type SegmentPlacement
+} from '../domain/pdf-layout';
+import { getSource } from './repository';
+
+/**
+ * Read-time word geometry for a document's original PDF.
+ *
+ * The import already ran LiteParse over these bytes, but deliberately kept
+ * none of the boxes: storing a rectangle per word for every document in the
+ * library would dwarf the documents themselves (see `DocumentPageInfo`).
+ * Re-reading them is cheap when it is asked for by page — LiteParse's
+ * `targetPages` parses a window in tens of milliseconds — so the page view
+ * recomputes what it needs as the reader scrolls and keeps it in memory for
+ * the session.
+ */
+
+export interface PageLayout {
+	page: number;
+	/** PDF points, as LiteParse read them — the coordinate space of `boxes`. */
+	width: number;
+	height: number;
+	boxes: PageWordBox[];
+}
+
+/** Pages either side of the requested one to parse in the same pass. Reading
+ * is directional, so the window leans forward. */
+const WINDOW_BEHIND = 1;
+const WINDOW_AHEAD = 2;
+
+let liteparse: Promise<typeof import('@llamaindex/liteparse-wasm')> | undefined;
+
+/** The wasm module, initialized once per session. LiteParse's own init guard
+ * only dedupes after the first init resolves, so the promise is what callers
+ * share. */
+async function loadLiteparse(): Promise<typeof import('@llamaindex/liteparse-wasm')> {
+	liteparse ??= (async () => {
+		const [glue, wasm] = await Promise.all([
+			import('@llamaindex/liteparse-wasm'),
+			import('@llamaindex/liteparse-wasm/liteparse_wasm_bg.wasm?url')
+		]);
+		await glue.default({ module_or_path: wasm.default });
+		return glue;
+	})();
+	return liteparse;
+}
+
+/**
+ * One document's page geometry, parsed on demand and kept for the session.
+ * Requests for the same page while a parse is in flight join it rather than
+ * starting a second one — scrolling asks for the same page many times.
+ */
+class DocumentLayout {
+	readonly documentId: string;
+	#source: Promise<Uint8Array | null>;
+	#pages = new Map<number, PageLayout | null>();
+	#pending = new Map<number, Promise<PageLayout | null>>();
+	#placements = new Map<string, Map<string, SegmentPlacement>>();
+	#segments: SpeechSegment[] = [];
+
+	constructor(document: NormalizedDocument) {
+		this.documentId = document.id;
+		this.#source = (async () => {
+			const blob = await getSource(document);
+			if (!blob) return null;
+			return new Uint8Array(await blob.arrayBuffer());
+		})().catch(() => null);
+	}
+
+	/** Word boxes for one page, or null when the source is gone (OPFS
+	 * eviction) or LiteParse cannot read it. */
+	pageLayout(page: number, pageCount: number): Promise<PageLayout | null> {
+		const cached = this.#pages.get(page);
+		if (cached !== undefined) return Promise.resolve(cached);
+		const inFlight = this.#pending.get(page);
+		if (inFlight) return inFlight;
+		const from = Math.max(1, page - WINDOW_BEHIND);
+		const to = Math.max(from, Math.min(pageCount || page + WINDOW_AHEAD, page + WINDOW_AHEAD));
+		const work = this.#parseWindow(from, to).then(
+			() => this.#pages.get(page) ?? null,
+			() => null
+		);
+		for (let target = from; target <= to; target += 1) {
+			if (!this.#pages.has(target)) this.#pending.set(target, work);
+		}
+		void work.finally(() => {
+			for (let target = from; target <= to; target += 1) {
+				if (this.#pending.get(target) === work) this.#pending.delete(target);
+			}
+		});
+		return work;
+	}
+
+	async #parseWindow(from: number, to: number): Promise<void> {
+		const data = await this.#source;
+		if (!data) {
+			for (let page = from; page <= to; page += 1) this.#pages.set(page, null);
+			return;
+		}
+		const glue = await loadLiteparse();
+		const parser = new glue.LiteParse({
+			ocrEnabled: false,
+			outputFormat: 'markdown',
+			// Only the geometry is wanted here; images and links are the import's
+			// business and decoding them again would dominate the parse.
+			imageMode: 'off',
+			extractLinks: false,
+			skipDiagonalText: true,
+			emitWordBoxes: true,
+			quiet: true,
+			targetPages: from === to ? String(from) : `${from}-${to}`
+		});
+		let parsed: Awaited<ReturnType<typeof parser.parse>>;
+		try {
+			// LiteParse transfers the buffer to wasm; hand it a copy so the next
+			// window still has bytes to read.
+			parsed = await parser.parse(data.slice());
+		} finally {
+			parser.free();
+		}
+		const seen = new Set<number>();
+		for (const page of parsed.pages) {
+			seen.add(page.pageNum);
+			this.#pages.set(page.pageNum, {
+				page: page.pageNum,
+				width: page.width,
+				height: page.height,
+				boxes: pageWordBoxes(page.textItems ?? [])
+			});
+		}
+		// A page the parse skipped has no geometry and never will; recording the
+		// miss stops every scroll from asking again.
+		for (let page = from; page <= to; page += 1) if (!seen.has(page)) this.#pages.set(page, null);
+	}
+
+	/**
+	 * Where each passage sits on one page. Placement is pure but not free
+	 * (tens of milliseconds on a dense page), so results are kept per page and
+	 * dropped wholesale when the passages themselves change — a listening-mode
+	 * switch or a narration swap re-cuts every segment id.
+	 */
+	async placements(
+		page: number,
+		pageCount: number,
+		segments: SpeechSegment[],
+		blockText: ReadonlyMap<string, string>
+	): Promise<Map<string, SegmentPlacement>> {
+		if (segments !== this.#segments) {
+			this.#segments = segments;
+			this.#placements.clear();
+		}
+		const key = String(page);
+		const cached = this.#placements.get(key);
+		if (cached) return cached;
+		const layout = await this.pageLayout(page, pageCount);
+		const placed = new Map<string, SegmentPlacement>();
+		if (layout?.boxes.length) {
+			const placeable = segmentsForPage(segments, page, blockText);
+			for (const placement of placeSegments(layout.boxes, placeable, page)) {
+				placed.set(placement.segmentId, placement);
+			}
+		}
+		// The passages may have been rebound while this page was being parsed;
+		// caching against a stale set would pin placements for ids nothing uses.
+		if (segments === this.#segments) this.#placements.set(key, placed);
+		return placed;
+	}
+}
+
+let open: DocumentLayout | undefined;
+
+/** The layout source for a document, kept warm one at a time — opening
+ * another document releases the previous one, matching the page renderer. */
+export function openPdfLayout(document: NormalizedDocument): DocumentLayout {
+	if (open?.documentId !== document.id) open = new DocumentLayout(document);
+	return open;
+}
+
+/** Frees the warm layout source. Safe to call twice or with nothing open. */
+export function releasePdfLayout(documentId?: string): void {
+	if (!open) return;
+	if (documentId && open.documentId !== documentId) return;
+	open = undefined;
+}
+
+export type { DocumentLayout };
diff --git a/src/lib/state/reader-chrome.svelte.ts b/src/lib/state/reader-chrome.svelte.ts
index 0ae902c..7734a4d 100644
--- a/src/lib/state/reader-chrome.svelte.ts
+++ b/src/lib/state/reader-chrome.svelte.ts
@@ -1,11 +1,28 @@
 import { DEFAULT_LISTENING_MODE, isListeningMode } from '$lib/domain/listening-modes';
 import type { ListeningMode } from '$lib/domain/types';
 
+/**
+ * How a document is shown. 'reading' is the reflowed markdown — the only
+ * option for anything that was never a page. 'page' draws the original PDF
+ * and paints the spoken passage onto it, for readers who want the paper as
+ * the authors set it.
+ */
+export type ReaderView = 'reading' | 'page';
+
+export const READER_VIEWS: ReaderView[] = ['reading', 'page'];
+
+function isReaderView(value: unknown): value is ReaderView {
+	return READER_VIEWS.includes(value as ReaderView);
+}
+
 class ReaderChromeState {
 	/** Contents starts closed — the document is the point. */
 	outlineOpen = $state(false);
 	menuOpen = $state(false);
 	documentZoom = $state(1);
+	/** The preferred view, remembered across documents. A document with no
+	 * original pages falls back to reading without changing this. */
+	readerView = $state<ReaderView>('reading');
 	/** The listening mode new imports start in. Per-document overrides live on
 	 * the document itself and take precedence in the reader. */
 	defaultListeningMode = $state<ListeningMode>(DEFAULT_LISTENING_MODE);
@@ -30,10 +47,26 @@ class ReaderChromeState {
 		if (Number.isFinite(stored) && stored >= 0.8 && stored <= 1.6) this.documentZoom = stored;
 		const mode = window.localStorage.getItem('voicebook:listening-mode');
 		if (isListeningMode(mode)) this.defaultListeningMode = mode;
+		const view = window.localStorage.getItem('voicebook:reader-view');
+		if (isReaderView(view)) this.readerView = view;
 		this.assistantCaptions = window.localStorage.getItem('voicebook:assistant-captions') !== '0';
 		this.spokenChatReplies = window.localStorage.getItem('voicebook:spoken-chat-replies') !== '0';
 	}
 
+	/** Steps to the next view. A cycle rather than a flip, so a third view can
+	 * join without the control changing shape. */
+	cycleReaderView(): void {
+		const next = READER_VIEWS[(READER_VIEWS.indexOf(this.readerView) + 1) % READER_VIEWS.length];
+		this.setReaderView(next);
+	}
+
+	setReaderView(view: ReaderView): void {
+		this.readerView = view;
+		if (typeof window !== 'undefined') {
+			window.localStorage.setItem('voicebook:reader-view', view);
+		}
+	}
+
 	setAssistantCaptions(on: boolean): void {
 		this.assistantCaptions = on;
 		if (typeof window !== 'undefined') {
diff --git a/src/routes/+layout.svelte b/src/routes/+layout.svelte
index 70124ff..955ff4d 100644
--- a/src/routes/+layout.svelte
+++ b/src/routes/+layout.svelte
@@ -9,6 +9,7 @@
 	import {
 		PanelLeftClose,
 		PanelLeftOpen,
+		BookOpenText,
 		BrainCircuit,
 		CircleHelp,
 		Fullscreen,
@@ -72,6 +73,13 @@
 	let readerBook = $derived(
 		isReader ? appState.documents.find((document) => document.id === readerDocumentId) : undefined
 	);
+	/** The page view needs the original file, which only a PDF import keeps —
+	 * and only while the bytes are still on this device. */
+	let originalPagesAvailable = $derived(
+		readerBook?.sourceKind === 'pdf' && Boolean(readerBook.sourcePath || readerBook.sourceBlob)
+	);
+	const viewLabels = { reading: 'Reading view', page: 'Original pages' } as const;
+
 	let tourContext = $derived<TourContext>(
 		isReader
 			? 'reader'
@@ -278,6 +286,23 @@
 				>
 					<Icon icon={List} size={16} strokeWidth={1.6} />
 				</button>
+				{#if originalPagesAvailable}
+					<button
+						class="icon-button"
+						class:active={readerChrome.readerView === 'page'}
+						type="button"
+						data-tour="reader-view"
+						aria-label={`${viewLabels[readerChrome.readerView]}. Switch view`}
+						title={`${viewLabels[readerChrome.readerView]} · click to switch`}
+						onclick={() => readerChrome.cycleReaderView()}
+					>
+						{#if readerChrome.readerView === 'page'}
+							<Icon icon={FileText} size={16} strokeWidth={1.6} />
+						{:else}
+							<Icon icon={BookOpenText} size={16} strokeWidth={1.6} />
+						{/if}
+					</button>
+				{/if}
 				<div class="document-zoom" role="group" aria-label="Document zoom">
 					<div class="zoom-control" bind:this={zoomRoot}>
 						<button
diff --git a/src/routes/read/+page.svelte b/src/routes/read/+page.svelte
index 541a669..13766da 100644
--- a/src/routes/read/+page.svelte
+++ b/src/routes/read/+page.svelte
@@ -50,6 +50,7 @@
 	import ModelInstallPrompt from '$lib/components/ModelInstallPrompt.svelte';
 	import PageMarker from '$lib/components/PageMarker.svelte';
 	import PdfPagePeek from '$lib/components/PdfPagePeek.svelte';
+	import PdfPageView from '$lib/components/PdfPageView.svelte';
 	import SafeHtml from '$lib/components/SafeHtml.svelte';
 	import VolumeControl from '$lib/components/VolumeControl.svelte';
 	import type {
@@ -70,6 +71,7 @@
 	import { breadcrumbFor, outlineText } from '$lib/domain/document-lens';
 	import { generateExplanation } from '$lib/services/explain';
 	import { pageCount, pageStartMap } from '$lib/domain/pages';
+	import { releasePdfLayout } from '$lib/services/pdf-layout';
 	import { releasePdfRenderer } from '$lib/services/pdf-pages';
 	import { readerTourSeen, startTour } from '$lib/services/tours';
 	import { appState } from '$lib/state/app-state.svelte';
@@ -447,6 +449,17 @@
 		book?.sourceKind === 'pdf' && Boolean(book.sourcePath || book.sourceBlob)
 	);
 	let pagePeek = $state<{ page: number }>();
+	// The original-page view needs both the file and a page count to lay out;
+	// a document missing either reads as markdown whatever the preference says.
+	let pageViewActive = $derived(
+		readerChrome.readerView === 'page' && peekAvailable && documentPageCount !== undefined
+	);
+
+	/** Play the passage the reader picked out on the original page. */
+	function playPlacedSegment(segmentId: string): void {
+		const index = segmentIndexes.get(segmentId);
+		if (index !== undefined) void player.playFromSegment(index);
+	}
 
 	function childBlocks(block: DocumentBlock): DocumentBlock[] {
 		return (block.children ?? [])
@@ -572,6 +585,7 @@
 		activeOutlineBlockId = undefined;
 		pagePeek = undefined;
 		void releasePdfRenderer();
+		releasePdfLayout();
 		if (!next) {
 			openingTitle = undefined;
 			book = null;
@@ -2069,229 +2083,245 @@
 				</div>
 			{/if}
 
-			<article
-				class="reading-canvas"
-				class:scrollbar-active={scrollbarActive}
-				style:--document-zoom={readerChrome.documentZoom}
-				style:--document-canvas-width={`${readerChrome.documentCanvasWidth}px`}
-				aria-label={book.title}
-				onpointerover={trackHoveredSegment}
-				{@attach trackReadingCanvas}
-			>
-				<header class="document-heading" id={titleBlock?.id} tabindex="-1">
-					<span>{book.sourceKind.toUpperCase()} · Local library</span>
-					<h1>
-						{#if titleBlock}
-							{#each segmentsByBlock.get(titleBlock.id) ?? [] as segment (segment.id)}
-								{@render renderSegment(titleBlock, segment)}
-							{/each}
-						{:else}
-							{book.title}
-						{/if}
-					</h1>
-					<p>
-						{Math.max(1, Math.round(player.totalDuration / 60))} min read · {book.segments.length}
-						passages{#if documentPageCount}&nbsp;· {documentPageCount} pages{/if}
-					</p>
-				</header>
+			{#if pageViewActive && documentPageCount}
+				<PdfPageView
+					document={book}
+					pageCount={documentPageCount}
+					segments={book.segments}
+					{activeSegmentId}
+					activeWordIndex={player.currentWordIndex}
+					follow={player.autoFollow}
+					onPlaySegment={playPlacedSegment}
+				/>
+			{:else}
+				<article
+					class="reading-canvas"
+					class:scrollbar-active={scrollbarActive}
+					style:--document-zoom={readerChrome.documentZoom}
+					style:--document-canvas-width={`${readerChrome.documentCanvasWidth}px`}
+					aria-label={book.title}
+					onpointerover={trackHoveredSegment}
+					{@attach trackReadingCanvas}
+				>
+					<header class="document-heading" id={titleBlock?.id} tabindex="-1">
+						<span>{book.sourceKind.toUpperCase()} · Local library</span>
+						<h1>
+							{#if titleBlock}
+								{#each segmentsByBlock.get(titleBlock.id) ?? [] as segment (segment.id)}
+									{@render renderSegment(titleBlock, segment)}
+								{/each}
+							{:else}
+								{book.title}
+							{/if}
+						</h1>
+						<p>
+							{Math.max(1, Math.round(player.totalDuration / 60))} min read · {book.segments.length}
+							passages{#if documentPageCount}&nbsp;· {documentPageCount} pages{/if}
+						</p>
+					</header>
+
+					<div class="document-body" {@attach trackDocumentBody}>
+						{#each rootBlocks as block (block.id)}
+							{@const markerPage = pageStartsById.get(block.id)}
+							<!-- The document's start needs no separator above it. -->
+							{#if markerPage !== undefined && block.id !== rootBlocks[0]?.id}
+								<PageMarker page={markerPage} onPeek={peekAvailable ? openPagePeek : undefined} />
+							{/if}
+							{#if block.kind === 'list-item'}
+								<ul class="document-list legacy-list">{@render renderBlock(block)}</ul>
+							{:else}
+								{@render renderBlock(block)}
+							{/if}
+						{/each}
+					</div>
 
-				<div class="document-body" {@attach trackDocumentBody}>
-					{#each rootBlocks as block (block.id)}
-						{@const markerPage = pageStartsById.get(block.id)}
-						<!-- The document's start needs no separator above it. -->
-						{#if markerPage !== undefined && block.id !== rootBlocks[0]?.id}
-							<PageMarker page={markerPage} onPeek={peekAvailable ? openPagePeek : undefined} />
-						{/if}
-						{#if block.kind === 'list-item'}
-							<ul class="document-list legacy-list">{@render renderBlock(block)}</ul>
-						{:else}
-							{@render renderBlock(block)}
+					{#if narrationStartAction}
+						{@const selectedSegment = book.segments.find(
+							(segment) => segment.id === narrationStartAction?.segmentId
+						)}
+						{#if selectedSegment}
+							<div
+								class="selection-actions"
+								class:below={narrationStartAction.placement === 'below'}
+								style:left={`${narrationStartAction.left}px`}
+								style:top={`${narrationStartAction.top}px`}
+								role="group"
+								aria-label="Actions for the selected text"
+							>
+								<button
+									class="selection-action"
+									type="button"
+									aria-label={`Play the selected text: ${narrationStartAction.excerpt}`}
+									onpointerdown={(event) => event.preventDefault()}
+									onclick={playSelectedPassage}
+								>
+									<Icon icon={Play} size={12} fill="currentColor" />
+									Play selection
+								</button>
+								<span class="selection-actions-divider" aria-hidden="true"></span>
+								<button
+									class="selection-action"
+									type="button"
+									aria-label={`Explain the selected text: ${narrationStartAction.excerpt}`}
+									onpointerdown={(event) => event.preventDefault()}
+									onclick={openExplainBox}
+								>
+									<Icon icon={Sparkles} size={12} />
+									Explain
+								</button>
+								<span class="selection-actions-divider" aria-hidden="true"></span>
+								<button
+									class="selection-action"
+									type="button"
+									aria-label={`Highlight the selected text: ${narrationStartAction.excerpt}`}
+									onpointerdown={(event) => event.preventDefault()}
+									onclick={() => annotateSelection(false)}
+								>
+									<Icon icon={Highlighter} size={12} />
+									Highlight
+								</button>
+								<span class="selection-actions-divider" aria-hidden="true"></span>
+								<button
+									class="selection-action"
+									type="button"
+									aria-label={`Add a margin note to the selected text: ${narrationStartAction.excerpt}`}
+									onpointerdown={(event) => event.preventDefault()}
+									onclick={() => annotateSelection(true)}
+								>
+									<Icon icon={StickyNote} size={12} />
+									Note
+								</button>
+							</div>
 						{/if}
+					{/if}
+
+					{#each annotationMarkers as marker (marker.id)}
+						<button
+							class="annotation-marker"
+							class:has-note={marker.hasNote}
+							style:left={`${marker.left}px`}
+							style:top={`${marker.top}px`}
+							type="button"
+							aria-label={marker.label}
+							onclick={(event) =>
+								annotationEditor?.id === marker.id
+									? closeAnnotationEditor()
+									: openAnnotationEditor(marker.id, event.currentTarget.getBoundingClientRect())}
+						>
+							{#if marker.hasNote}
+								<Icon icon={StickyNote} size={12} aria-hidden="true" />
+							{:else}
+								<span class="annotation-dot" aria-hidden="true"></span>
+							{/if}
+						</button>
 					{/each}
-				</div>
 
-				{#if narrationStartAction}
-					{@const selectedSegment = book.segments.find(
-						(segment) => segment.id === narrationStartAction?.segmentId
-					)}
-					{#if selectedSegment}
+					{#if annotationEditor}
+						{@const editor = annotationEditor}
 						<div
-							class="selection-actions"
-							class:below={narrationStartAction.placement === 'below'}
-							style:left={`${narrationStartAction.left}px`}
-							style:top={`${narrationStartAction.top}px`}
-							role="group"
-							aria-label="Actions for the selected text"
+							class="annotation-editor"
+							class:below={editor.placement === 'below'}
+							style:left={`${editor.left}px`}
+							style:top={`${editor.top}px`}
+							role="dialog"
+							aria-label="Edit the annotation"
 						>
-							<button
-								class="selection-action"
-								type="button"
-								aria-label={`Play the selected text: ${narrationStartAction.excerpt}`}
-								onpointerdown={(event) => event.preventDefault()}
-								onclick={playSelectedPassage}
-							>
-								<Icon icon={Play} size={12} fill="currentColor" />
-								Play selection
-							</button>
-							<span class="selection-actions-divider" aria-hidden="true"></span>
-							<button
-								class="selection-action"
-								type="button"
-								aria-label={`Explain the selected text: ${narrationStartAction.excerpt}`}
-								onpointerdown={(event) => event.preventDefault()}
-								onclick={openExplainBox}
-							>
-								<Icon icon={Sparkles} size={12} />
-								Explain
-							</button>
-							<span class="selection-actions-divider" aria-hidden="true"></span>
-							<button
-								class="selection-action"
-								type="button"
-								aria-label={`Highlight the selected text: ${narrationStartAction.excerpt}`}
-								onpointerdown={(event) => event.preventDefault()}
-								onclick={() => annotateSelection(false)}
-							>
-								<Icon icon={Highlighter} size={12} />
-								Highlight
-							</button>
-							<span class="selection-actions-divider" aria-hidden="true"></span>
-							<button
-								class="selection-action"
-								type="button"
-								aria-label={`Add a margin note to the selected text: ${narrationStartAction.excerpt}`}
-								onpointerdown={(event) => event.preventDefault()}
-								onclick={() => annotateSelection(true)}
-							>
-								<Icon icon={StickyNote} size={12} />
-								Note
-							</button>
-						</div>
-					{/if}
-				{/if}
-
-				{#each annotationMarkers as marker (marker.id)}
-					<button
-						class="annotation-marker"
-						class:has-note={marker.hasNote}
-						style:left={`${marker.left}px`}
-						style:top={`${marker.top}px`}
-						type="button"
-						aria-label={marker.label}
-						onclick={(event) =>
-							annotationEditor?.id === marker.id
-								? closeAnnotationEditor()
-								: openAnnotationEditor(marker.id, event.currentTarget.getBoundingClientRect())}
-					>
-						{#if marker.hasNote}
-							<Icon icon={StickyNote} size={12} aria-hidden="true" />
-						{:else}
-							<span class="annotation-dot" aria-hidden="true"></span>
-						{/if}
-					</button>
-				{/each}
-
-				{#if annotationEditor}
-					{@const editor = annotationEditor}
-					<div
-						class="annotation-editor"
-						class:below={editor.placement === 'below'}
-						style:left={`${editor.left}px`}
-						style:top={`${editor.top}px`}
-						role="dialog"
-						aria-label="Edit the annotation"
-					>
-						<div class="annotation-editor-head">
-							<Icon icon={Highlighter} size={12} aria-hidden="true" />
-							<span class="annotation-excerpt">{annotationEditorExcerpt}</span>
-							<button
-								class="annotation-editor-close"
-								type="button"
-								aria-label="Close the annotation card"
-								onclick={() => closeAnnotationEditor()}
-							>
-								<Icon icon={X} size={13} />
-							</button>
-						</div>
-						<textarea
-							rows="2"
-							placeholder="Add a margin note…"
-							aria-label="Margin note text"
-							bind:value={annotationDraft}
-							{@attach focusExplainInput}></textarea>
-						<footer>
-							<button
-								class="annotation-remove"
-								type="button"
-								onclick={() => deleteAnnotation(editor.id)}
-							>
-								Remove
-							</button>
-							<button class="annotation-done" type="button" onclick={() => closeAnnotationEditor()}>
-								Done
-							</button>
-						</footer>
-					</div>
-				{/if}
-
-				{#if explainBox}
-					<div
-						class="explain-box"
-						class:below={explainBox.placement === 'below'}
-						style:left={`${explainBox.left}px`}
-						style:top={`${explainBox.top}px`}
-						role="dialog"
-						aria-label="Explain the selected passage"
-					>
-						<div class="explain-head">
-							<Icon icon={Sparkles} size={12} aria-hidden="true" />
-							<span class="explain-excerpt">{explainBox.selection}</span>
-							<button
-								class="explain-close"
-								type="button"
-								aria-label="Close the explain panel"
-								onclick={closeExplainBox}
-							>
-								<Icon icon={X} size={13} />
-							</button>
-						</div>
-						<div class="explain-row">
+							<div class="annotation-editor-head">
+								<Icon icon={Highlighter} size={12} aria-hidden="true" />
+								<span class="annotation-excerpt">{annotationEditorExcerpt}</span>
+								<button
+									class="annotation-editor-close"
+									type="button"
+									aria-label="Close the annotation card"
+									onclick={() => closeAnnotationEditor()}
+								>
+									<Icon icon={X} size={13} />
+								</button>
+							</div>
 							<textarea
-								rows="1"
-								placeholder="What are you wondering? (optional)"
-								aria-label="Your question about the selection"
-								disabled={explainStatus !== 'idle'}
-								bind:value={explainQuestion}
-								onkeydown={handleExplainKeydown}
+								rows="2"
+								placeholder="Add a margin note…"
+								aria-label="Margin note text"
+								bind:value={annotationDraft}
 								{@attach focusExplainInput}></textarea>
-							{#if explainStatus === 'idle'}
+							<footer>
 								<button
-									class="explain-run"
+									class="annotation-remove"
 									type="button"
-									aria-label="Explain aloud"
-									title="Explain aloud"
-									onclick={() => void runExplain()}
+									onclick={() => deleteAnnotation(editor.id)}
 								>
-									<Icon icon={Sparkles} size={13} />
+									Remove
 								</button>
-							{:else}
 								<button
-									class="explain-run thinking"
+									class="annotation-done"
 									type="button"
-									aria-label="Cancel"
-									title="Cancel"
+									onclick={() => closeAnnotationEditor()}
+								>
+									Done
+								</button>
+							</footer>
+						</div>
+					{/if}
+
+					{#if explainBox}
+						<div
+							class="explain-box"
+							class:below={explainBox.placement === 'below'}
+							style:left={`${explainBox.left}px`}
+							style:top={`${explainBox.top}px`}
+							role="dialog"
+							aria-label="Explain the selected passage"
+						>
+							<div class="explain-head">
+								<Icon icon={Sparkles} size={12} aria-hidden="true" />
+								<span class="explain-excerpt">{explainBox.selection}</span>
+								<button
+									class="explain-close"
+									type="button"
+									aria-label="Close the explain panel"
 									onclick={closeExplainBox}
 								>
-									<Icon icon={LoaderCircle} class="spin" size={13} />
+									<Icon icon={X} size={13} />
 								</button>
+							</div>
+							<div class="explain-row">
+								<textarea
+									rows="1"
+									placeholder="What are you wondering? (optional)"
+									aria-label="Your question about the selection"
+									disabled={explainStatus !== 'idle'}
+									bind:value={explainQuestion}
+									onkeydown={handleExplainKeydown}
+									{@attach focusExplainInput}></textarea>
+								{#if explainStatus === 'idle'}
+									<button
+										class="explain-run"
+										type="button"
+										aria-label="Explain aloud"
+										title="Explain aloud"
+										onclick={() => void runExplain()}
+									>
+										<Icon icon={Sparkles} size={13} />
+									</button>
+								{:else}
+									<button
+										class="explain-run thinking"
+										type="button"
+										aria-label="Cancel"
+										title="Cancel"
+										onclick={closeExplainBox}
+									>
+										<Icon icon={LoaderCircle} class="spin" size={13} />
+									</button>
+								{/if}
+							</div>
+							{#if explainError}
+								<p class="explain-error" role="alert">{explainError}</p>
 							{/if}
 						</div>
-						{#if explainError}
-							<p class="explain-error" role="alert">{explainError}</p>
-						{/if}
-					</div>
-				{/if}
-			</article>
+					{/if}
+				</article>
+			{/if}
 			<p class="sr-only" aria-live="polite">{narrationAnnouncement}</p>
 
 			{#if !player.autoFollow}

From 058726cf8cdf1b0b23fb4de9b25cb428de1ae316 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Wed, 26 Aug 2026 23:18:32 -0500
Subject: [PATCH 03/15] feat: carry reader ink and assistant focus onto the
 original pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Highlights, margin notes, and the passage the assistant is pointing at
were only visible in the reading view; on the page view they simply went
missing, which reads as lost work. They paint as their own rectangles
here, ordered back to front — persistent ink under live emphasis — since
there is no cascade to settle it for us.

Also covers the layout service, which is how the window-join bug surfaced:
a caller waiting on a read someone else started was handed that caller's
page instead of its own.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .gitignore                            |   3 +
 src/lib/components/PdfPageView.svelte |  72 +++++++++--
 src/lib/domain/pdf-layout.spec.ts     |   9 +-
 src/lib/services/pdf-layout.spec.ts   | 167 ++++++++++++++++++++++++++
 src/lib/services/pdf-layout.ts        | 142 +++++++++++++---------
 src/routes/read/+page.svelte          |   3 +
 tests/reader.e2e.ts                   |  72 +++++++++++
 7 files changed, 395 insertions(+), 73 deletions(-)
 create mode 100644 src/lib/services/pdf-layout.spec.ts

diff --git a/.gitignore b/.gitignore
index e503f4a..4387109 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,3 +44,6 @@ skills-lock.json
 # Local test fixtures (user-provided, not committed)
 test_documents/
 .probe/
+
+# Locally staged preview fixtures (never committed)
+static/attention.pdf
diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index c6ba8e8..51d0c8a 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -13,6 +13,12 @@
 		segments: SpeechSegment[];
 		activeSegmentId?: string;
 		activeWordIndex?: number;
+		/** Passages carrying a reader highlight or margin note. */
+		annotatedSegmentIds?: ReadonlySet<string>;
+		/** The stretch the assistant is discussing, and the one sentence inside
+		 * it that it is pointing at right now. */
+		assistantSegmentIds?: ReadonlySet<string>;
+		assistantPointId?: string;
 		/** Whether playback should pull the page along with it. */
 		follow?: boolean;
 		onPlaySegment: (segmentId: string) => void;
@@ -24,6 +30,9 @@
 		segments,
 		activeSegmentId,
 		activeWordIndex,
+		annotatedSegmentIds,
+		assistantSegmentIds,
+		assistantPointId,
 		follow = true,
 		onPlaySegment
 	}: Props = $props();
@@ -188,6 +197,38 @@
 		return `left:${rect.x * scale}px;top:${rect.y * scale}px;width:${rect.width * scale}px;height:${rect.height * scale}px`;
 	}
 
+	type MarkKind = 'annotated' | 'assistant' | 'point' | 'passage' | 'hover';
+
+	/**
+	 * Everything to paint over one page, back to front. The reading view puts
+	 * these on the same passage as competing backgrounds and lets specificity
+	 * decide; here they are separate rectangles, so the order they are emitted
+	 * in is what decides — live emphasis last, over persistent ink.
+	 */
+	function marksFor(page: number, placed?: Map<string, SegmentPlacement>) {
+		const marks: Array<{ key: string; kind: MarkKind; rect: PageRect }> = [];
+		if (!placed) return marks;
+		const add = (kind: MarkKind, segmentId: string) => {
+			const rects = placed.get(segmentId)?.rects ?? [];
+			rects.forEach((rect, index) =>
+				marks.push({ key: `${kind}:${segmentId}:${index}`, kind, rect })
+			);
+		};
+		for (const segmentId of annotatedSegmentIds ?? []) {
+			if (segmentId !== activeSegmentId) add('annotated', segmentId);
+		}
+		for (const segmentId of assistantSegmentIds ?? []) {
+			if (segmentId !== activeSegmentId && segmentId !== assistantPointId) {
+				add('assistant', segmentId);
+			}
+		}
+		if (assistantPointId && assistantPointId !== activeSegmentId) add('point', assistantPointId);
+		if (hovered?.page === page && hovered.segmentId !== activeSegmentId)
+			add('hover', hovered.segmentId);
+		if (activeSegmentId) add('passage', activeSegmentId);
+		return marks;
+	}
+
 	/** The passage under a point on a page, in PDF points. Rectangles are
 	 * tested with a little vertical slack: line boxes stop at the type's
 	 * bounds, and the gap between two lines belongs to one of them. */
@@ -287,18 +328,11 @@
 				></canvas>
 				{#if live.has(size.page)}
 					<div class="page-marks" aria-hidden="true">
-						{#if hovered?.page === size.page && hovered.segmentId !== activeSegmentId}
-							{#each placed?.get(hovered.segmentId)?.rects ?? [] as rect, index (index)}
-								<span class="mark hover" style={styleFor(rect, size.page)}></span>
-							{/each}
-						{/if}
-						{#if activeSegmentId && placed?.has(activeSegmentId)}
-							{#each placed.get(activeSegmentId)?.rects ?? [] as rect, index (index)}
-								<span class="mark passage" style={styleFor(rect, size.page)}></span>
-							{/each}
-							{#if activeWordRect}
-								<span class="mark word" style={styleFor(activeWordRect, size.page)}></span>
-							{/if}
+						{#each marksFor(size.page, placed) as mark (mark.key)}
+							<span class="mark {mark.kind}" style={styleFor(mark.rect, size.page)}></span>
+						{/each}
+						{#if activeWordRect && placed?.has(activeSegmentId ?? '')}
+							<span class="mark word" style={styleFor(activeWordRect, size.page)}></span>
 						{/if}
 					</div>
 				{/if}
@@ -380,6 +414,20 @@
 		background: color-mix(in srgb, var(--primary) 12%, transparent);
 	}
 
+	/* Persistent reader ink: the same bookmark gold the reading view paints
+	   under an annotated passage. */
+	.mark.annotated {
+		background: color-mix(in srgb, var(--bookmark) 34%, transparent);
+	}
+
+	.mark.assistant {
+		background: color-mix(in srgb, var(--primary) 14%, transparent);
+	}
+
+	.mark.point {
+		background: color-mix(in srgb, var(--primary) 30%, transparent);
+	}
+
 	.mark.word {
 		background: var(--active-word-bg, rgba(112, 176, 143, 0.34));
 		box-shadow: 0 0 0 0.1em var(--active-word-bg, rgba(112, 176, 143, 0.34));
diff --git a/src/lib/domain/pdf-layout.spec.ts b/src/lib/domain/pdf-layout.spec.ts
index cd69004..ff6ffaa 100644
--- a/src/lib/domain/pdf-layout.spec.ts
+++ b/src/lib/domain/pdf-layout.spec.ts
@@ -24,8 +24,9 @@ function line(text: string, y: number, startX = 0): PageWordBox[] {
 	return boxes;
 }
 
-function words(text: string): Array<{ start: number; end: number }> {
+function words(text: string): Array<{ text: string; start: number; end: number }> {
 	return [...text.matchAll(/\S+/g)].map((match) => ({
+		text: match[0],
 		start: match.index ?? 0,
 		end: (match.index ?? 0) + match[0].length
 	}));
@@ -173,9 +174,9 @@ describe('mergeWordRects', () => {
 
 	it('breaks at a column jump rather than sweeping across the gutter', () => {
 		const merged = mergeWordRects([
-			{ text: 'left', x: 40, y: 100, width: 40, height: 12 },
-			{ text: 'right', x: 300, y: 100, width: 40, height: 12 },
-			{ text: 'wrapped', x: 40, y: 100, width: 40, height: 12 }
+			{ x: 40, y: 100, width: 40, height: 12 },
+			{ x: 300, y: 100, width: 40, height: 12 },
+			{ x: 40, y: 100, width: 40, height: 12 }
 		]);
 		expect(merged).toHaveLength(2);
 	});
diff --git a/src/lib/services/pdf-layout.spec.ts b/src/lib/services/pdf-layout.spec.ts
new file mode 100644
index 0000000..dbc3d9a
--- /dev/null
+++ b/src/lib/services/pdf-layout.spec.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it, vi } from 'vitest';
+import { DocumentLayout, type PageLayout, type PageWindowReader } from './pdf-layout';
+import type { SpeechSegment } from '../domain/types';
+
+const BYTES = new Uint8Array([1, 2, 3]);
+
+/** A page of three words on one line, positioned so placement has something
+ * to bite on. */
+function page(number: number, words: string[]): PageLayout {
+	let x = 72;
+	return {
+		page: number,
+		width: 612,
+		height: 792,
+		boxes: words.map((text) => {
+			const box = { text, x, y: 100, width: text.length * 6, height: 12 };
+			x += text.length * 6 + 4;
+			return box;
+		})
+	};
+}
+
+function reader(pages: Record<number, string[]>): {
+	read: PageWindowReader;
+	calls: Array<[number, number]>;
+} {
+	const calls: Array<[number, number]> = [];
+	const read: PageWindowReader = async (_data, from, to) => {
+		calls.push([from, to]);
+		const out: PageLayout[] = [];
+		for (let number = from; number <= to; number += 1) {
+			if (pages[number]) out.push(page(number, pages[number]));
+		}
+		return out;
+	};
+	return { read, calls };
+}
+
+function layoutFor(pages: Record<number, string[]>, source: Uint8Array | null = BYTES) {
+	const { read, calls } = reader(pages);
+	return { layout: new DocumentLayout('doc', async () => source, read), calls };
+}
+
+function segment(id: string, text: string, pageNumber: number): SpeechSegment {
+	return {
+		id,
+		blockId: 'b1',
+		text,
+		normalizedText: text,
+		start: 0,
+		end: text.length,
+		words: [...text.matchAll(/\S+/g)].map((match) => ({
+			text: match[0],
+			start: match.index ?? 0,
+			end: (match.index ?? 0) + match[0].length
+		})),
+		estimatedDuration: 1,
+		anchor: { page: pageNumber }
+	};
+}
+
+describe('DocumentLayout', () => {
+	it('reads a window around the page asked for, leaning ahead', async () => {
+		const { layout, calls } = layoutFor({ 3: ['alpha'] });
+		await layout.pageLayout(3, 20);
+		expect(calls).toEqual([[2, 5]]);
+	});
+
+	it('does not read past the end of the document', async () => {
+		const { layout, calls } = layoutFor({ 5: ['alpha'] });
+		await layout.pageLayout(5, 5);
+		expect(calls).toEqual([[4, 5]]);
+	});
+
+	it('serves later pages of a window without reading again', async () => {
+		const { layout, calls } = layoutFor({ 2: ['alpha'], 3: ['beta'], 4: ['gamma'] });
+		await layout.pageLayout(2, 10);
+		const ahead = await layout.pageLayout(4, 10);
+		expect(ahead?.boxes[0].text).toBe('gamma');
+		expect(calls).toHaveLength(1);
+	});
+
+	it('joins a read already in flight rather than starting a second', async () => {
+		const { layout, calls } = layoutFor({ 1: ['alpha'], 2: ['beta'] });
+		const [first, second] = await Promise.all([layout.pageLayout(1, 10), layout.pageLayout(2, 10)]);
+		expect(first?.page).toBe(1);
+		expect(second?.page).toBe(2);
+		expect(calls).toHaveLength(1);
+	});
+
+	it('remembers a page the read had nothing for, and stops asking', async () => {
+		const { layout, calls } = layoutFor({ 1: ['alpha'] });
+		expect(await layout.pageLayout(2, 10)).toBeNull();
+		expect(await layout.pageLayout(2, 10)).toBeNull();
+		expect(calls).toHaveLength(1);
+	});
+
+	it('has no geometry when the file is gone from this device', async () => {
+		const { layout, calls } = layoutFor({ 1: ['alpha'] }, null);
+		expect(await layout.pageLayout(1, 10)).toBeNull();
+		expect(calls).toHaveLength(0);
+	});
+
+	it('survives a read that throws', async () => {
+		const failing: PageWindowReader = () => Promise.reject(new Error('wasm said no'));
+		const layout = new DocumentLayout('doc', async () => BYTES, failing);
+		expect(await layout.pageLayout(1, 10)).toBeNull();
+	});
+
+	it('places the passages anchored to a page', async () => {
+		const { layout } = layoutFor({ 1: ['the', 'harbour', 'master'] });
+		const placed = await layout.placements(
+			1,
+			1,
+			[segment('s1', 'The harbour master', 1)],
+			new Map()
+		);
+		expect(placed.get('s1')?.rects[0].y).toBe(100);
+	});
+
+	it('places each page once and keeps the answer', async () => {
+		const { layout, calls } = layoutFor({ 1: ['the', 'harbour', 'master'] });
+		const segments = [segment('s1', 'The harbour master', 1)];
+		const first = await layout.placements(1, 1, segments, new Map());
+		const again = await layout.placements(1, 1, segments, new Map());
+		expect(again).toBe(first);
+		expect(calls).toHaveLength(1);
+	});
+
+	it('throws its placements away when the passages are rebound', async () => {
+		const { layout, calls } = layoutFor({ 1: ['the', 'harbour', 'master'] });
+		const first = await layout.placements(
+			1,
+			1,
+			[segment('s1', 'The harbour master', 1)],
+			new Map()
+		);
+		const rebound = await layout.placements(
+			1,
+			1,
+			[segment('s1:n0', 'The harbour master', 1)],
+			new Map()
+		);
+		expect(rebound).not.toBe(first);
+		expect(rebound.has('s1:n0')).toBe(true);
+		// The geometry is still good, though — only the placement was stale.
+		expect(calls).toHaveLength(1);
+	});
+
+	it('does not cache a placement computed against passages already replaced', async () => {
+		const gate = vi.fn();
+		let release: (() => void) | undefined;
+		const read: PageWindowReader = async () =>
+			new Promise((resolve) => {
+				release = () => resolve([page(1, ['the', 'harbour', 'master'])]);
+				gate();
+			});
+		const layout = new DocumentLayout('doc', async () => BYTES, read);
+		const stale = layout.placements(1, 1, [segment('old', 'The harbour master', 1)], new Map());
+		await vi.waitFor(() => expect(gate).toHaveBeenCalled());
+		const fresh = layout.placements(1, 1, [segment('new', 'The harbour master', 1)], new Map());
+		release?.();
+		await stale;
+		const settled = await fresh;
+		expect(settled.has('new')).toBe(true);
+	});
+});
diff --git a/src/lib/services/pdf-layout.ts b/src/lib/services/pdf-layout.ts
index 0b4ee33..ff2fa85 100644
--- a/src/lib/services/pdf-layout.ts
+++ b/src/lib/services/pdf-layout.ts
@@ -50,26 +50,39 @@ async function loadLiteparse(): Promise<typeof import('@llamaindex/liteparse-was
 	return liteparse;
 }
 
+/** Reads one window of pages out of the document's bytes. Supplied by the
+ * module below; a parameter so the caching around it can be tested without a
+ * wasm runtime. */
+export type PageWindowReader = (
+	data: Uint8Array,
+	from: number,
+	to: number
+) => Promise<PageLayout[]>;
+
 /**
  * One document's page geometry, parsed on demand and kept for the session.
  * Requests for the same page while a parse is in flight join it rather than
  * starting a second one — scrolling asks for the same page many times.
  */
-class DocumentLayout {
+export class DocumentLayout {
 	readonly documentId: string;
 	#source: Promise<Uint8Array | null>;
+	#read: PageWindowReader;
 	#pages = new Map<number, PageLayout | null>();
-	#pending = new Map<number, Promise<PageLayout | null>>();
+	/** The in-flight window read covering each page, shared by every caller
+	 * waiting on it. */
+	#pending = new Map<number, Promise<void>>();
 	#placements = new Map<string, Map<string, SegmentPlacement>>();
 	#segments: SpeechSegment[] = [];
 
-	constructor(document: NormalizedDocument) {
-		this.documentId = document.id;
-		this.#source = (async () => {
-			const blob = await getSource(document);
-			if (!blob) return null;
-			return new Uint8Array(await blob.arrayBuffer());
-		})().catch(() => null);
+	constructor(
+		documentId: string,
+		loadSource: () => Promise<Uint8Array | null>,
+		read: PageWindowReader
+	) {
+		this.documentId = documentId;
+		this.#read = read;
+		this.#source = loadSource().catch(() => null);
 	}
 
 	/** Word boxes for one page, or null when the source is gone (OPFS
@@ -77,63 +90,40 @@ class DocumentLayout {
 	pageLayout(page: number, pageCount: number): Promise<PageLayout | null> {
 		const cached = this.#pages.get(page);
 		if (cached !== undefined) return Promise.resolve(cached);
+		// What a waiting caller wants is its OWN page out of the finished read,
+		// not the page whoever started the read had asked for.
+		const settle = (work: Promise<void>) =>
+			work.then(
+				() => this.#pages.get(page) ?? null,
+				() => null
+			);
 		const inFlight = this.#pending.get(page);
-		if (inFlight) return inFlight;
+		if (inFlight) return settle(inFlight);
 		const from = Math.max(1, page - WINDOW_BEHIND);
 		const to = Math.max(from, Math.min(pageCount || page + WINDOW_AHEAD, page + WINDOW_AHEAD));
-		const work = this.#parseWindow(from, to).then(
-			() => this.#pages.get(page) ?? null,
-			() => null
-		);
+		const work = this.#parseWindow(from, to);
 		for (let target = from; target <= to; target += 1) {
 			if (!this.#pages.has(target)) this.#pending.set(target, work);
 		}
-		void work.finally(() => {
-			for (let target = from; target <= to; target += 1) {
-				if (this.#pending.get(target) === work) this.#pending.delete(target);
-			}
-		});
-		return work;
+		void work
+			.catch(() => undefined)
+			.finally(() => {
+				for (let target = from; target <= to; target += 1) {
+					if (this.#pending.get(target) === work) this.#pending.delete(target);
+				}
+			});
+		return settle(work);
 	}
 
 	async #parseWindow(from: number, to: number): Promise<void> {
 		const data = await this.#source;
-		if (!data) {
-			for (let page = from; page <= to; page += 1) this.#pages.set(page, null);
-			return;
-		}
-		const glue = await loadLiteparse();
-		const parser = new glue.LiteParse({
-			ocrEnabled: false,
-			outputFormat: 'markdown',
-			// Only the geometry is wanted here; images and links are the import's
-			// business and decoding them again would dominate the parse.
-			imageMode: 'off',
-			extractLinks: false,
-			skipDiagonalText: true,
-			emitWordBoxes: true,
-			quiet: true,
-			targetPages: from === to ? String(from) : `${from}-${to}`
-		});
-		let parsed: Awaited<ReturnType<typeof parser.parse>>;
-		try {
-			// LiteParse transfers the buffer to wasm; hand it a copy so the next
-			// window still has bytes to read.
-			parsed = await parser.parse(data.slice());
-		} finally {
-			parser.free();
-		}
+		const parsed = data ? await this.#read(data, from, to) : [];
 		const seen = new Set<number>();
-		for (const page of parsed.pages) {
-			seen.add(page.pageNum);
-			this.#pages.set(page.pageNum, {
-				page: page.pageNum,
-				width: page.width,
-				height: page.height,
-				boxes: pageWordBoxes(page.textItems ?? [])
-			});
+		for (const layout of parsed) {
+			seen.add(layout.page);
+			this.#pages.set(layout.page, layout);
 		}
-		// A page the parse skipped has no geometry and never will; recording the
+		// A page the read skipped has no geometry and never will; recording the
 		// miss stops every scroll from asking again.
 		for (let page = from; page <= to; page += 1) if (!seen.has(page)) this.#pages.set(page, null);
 	}
@@ -172,12 +162,52 @@ class DocumentLayout {
 	}
 }
 
+/** The real reader: LiteParse over a page range, asked for geometry only. */
+const readWithLiteparse: PageWindowReader = async (data, from, to) => {
+	const glue = await loadLiteparse();
+	const parser = new glue.LiteParse({
+		ocrEnabled: false,
+		outputFormat: 'markdown',
+		// Only the geometry is wanted here; images and links are the import's
+		// business and decoding them again would dominate the parse.
+		imageMode: 'off',
+		extractLinks: false,
+		skipDiagonalText: true,
+		emitWordBoxes: true,
+		quiet: true,
+		targetPages: from === to ? String(from) : `${from}-${to}`
+	});
+	let parsed: Awaited<ReturnType<typeof parser.parse>>;
+	try {
+		// LiteParse transfers the buffer to wasm; hand it a copy so the next
+		// window still has bytes to read.
+		parsed = await parser.parse(data.slice());
+	} finally {
+		parser.free();
+	}
+	return parsed.pages.map((page) => ({
+		page: page.pageNum,
+		width: page.width,
+		height: page.height,
+		boxes: pageWordBoxes(page.textItems ?? [])
+	}));
+};
+
 let open: DocumentLayout | undefined;
 
 /** The layout source for a document, kept warm one at a time — opening
  * another document releases the previous one, matching the page renderer. */
 export function openPdfLayout(document: NormalizedDocument): DocumentLayout {
-	if (open?.documentId !== document.id) open = new DocumentLayout(document);
+	if (open?.documentId !== document.id) {
+		open = new DocumentLayout(
+			document.id,
+			async () => {
+				const blob = await getSource(document);
+				return blob ? new Uint8Array(await blob.arrayBuffer()) : null;
+			},
+			readWithLiteparse
+		);
+	}
 	return open;
 }
 
@@ -187,5 +217,3 @@ export function releasePdfLayout(documentId?: string): void {
 	if (documentId && open.documentId !== documentId) return;
 	open = undefined;
 }
-
-export type { DocumentLayout };
diff --git a/src/routes/read/+page.svelte b/src/routes/read/+page.svelte
index 13766da..982f1d6 100644
--- a/src/routes/read/+page.svelte
+++ b/src/routes/read/+page.svelte
@@ -2090,6 +2090,9 @@
 					segments={book.segments}
 					{activeSegmentId}
 					activeWordIndex={player.currentWordIndex}
+					annotatedSegmentIds={annotationPaint.segmentIds}
+					{assistantSegmentIds}
+					{assistantPointId}
 					follow={player.autoFollow}
 					onPlaySegment={playPlacedSegment}
 				/>
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index ec32946..96b69e9 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1785,6 +1785,78 @@ test('imports a PDF with page markers, page navigation, and the original-page vi
 	await expect(page.getByRole('dialog')).toHaveCount(0);
 });
 
+test('reads a PDF as its own pages, with the spoken passage painted on', async ({ page }) => {
+	await openReadyLibrary(page);
+	const pdf = await PDFDocument.create();
+	const font = await pdf.embedFont(StandardFonts.Helvetica);
+	const sourcePages = [
+		[
+			'Ledgers of the Coast',
+			'The harbour master kept a ledger of every tide that entered the bay.',
+			'Each entry recorded the hour, the depth, and the weather over the water.'
+		],
+		[
+			'The Second Winter',
+			'By the second winter the ledger had outgrown its binding entirely.',
+			'A cooper in the town sewed the loose pages into a heavier cover.'
+		]
+	];
+	for (const [heading, first, second] of sourcePages) {
+		const sheet = pdf.addPage([612, 792]);
+		sheet.drawText(heading, { x: 72, y: 720, size: 22, font });
+		sheet.drawText(first, { x: 72, y: 660, size: 12, font });
+		sheet.drawText(second, { x: 72, y: 640, size: 12, font });
+	}
+	await page.locator('#document-upload').setInputFiles({
+		name: 'ledgers.pdf',
+		mimeType: 'application/pdf',
+		buffer: Buffer.from(await pdf.save())
+	});
+	await expect(page.getByRole('heading', { name: 'Ledgers of the Coast' })).toBeVisible();
+
+	// The view control only appears for a document that still has its file.
+	const viewSwitch = page.getByRole('button', { name: /Switch view/ });
+	await expect(viewSwitch).toHaveAccessibleName(/Reading view/);
+	await viewSwitch.click();
+	await expect(page.locator('.reading-canvas')).toHaveCount(0);
+	await expect(viewSwitch).toHaveAccessibleName(/Original pages/);
+
+	// Every page is laid out up front, and the near ones actually draw.
+	await expect(page.locator('.page-slot')).toHaveCount(2);
+	const firstPage = page.locator('.page-slot[data-page="1"]');
+	await expect
+		.poll(
+			async () => firstPage.locator('canvas').evaluate((node: HTMLCanvasElement) => node.width),
+			{ timeout: 30_000 }
+		)
+		.toBeGreaterThan(400);
+
+	// Double-clicking a sentence on the paper plays it, and it lights up where
+	// it was printed rather than anywhere the reflowed text would have put it.
+	const sheet = firstPage.locator('.page-sheet');
+	const sheetBox = await sheet.boundingBox();
+	expect(sheetBox).not.toBeNull();
+	// The first body line's baseline sits at 660pt from the foot of a 792pt
+	// page, so its type occupies roughly 123–135pt from the head.
+	const scale = sheetBox!.width / 612;
+	await sheet.dblclick({ position: { x: 200 * scale, y: 129 * scale } });
+	const marks = firstPage.locator('.mark.passage');
+	await expect.poll(async () => marks.count(), { timeout: 30_000 }).toBeGreaterThan(0);
+	const painted = await marks.first().boundingBox();
+	expect(painted).not.toBeNull();
+	// Painted over the line that was clicked, not over the heading above it.
+	expect(painted!.y - sheetBox!.y).toBeGreaterThan(100 * scale);
+	expect(painted!.y - sheetBox!.y).toBeLessThan(160 * scale);
+	expect(painted!.x - sheetBox!.x).toBeGreaterThan(60 * scale);
+
+	// The preference survives leaving and reopening the document.
+	await page.getByRole('link', { name: 'Library' }).first().click();
+	await page.getByRole('link', { name: 'Ledgers of the Coast' }).first().click();
+	await expect(page.locator('.page-slot')).toHaveCount(2);
+	await page.getByRole('button', { name: /Switch view/ }).click();
+	await expect(page.locator('.reading-canvas')).toBeVisible();
+});
+
 test('recognizes a scanned PDF with on-device text recognition', async ({ page }) => {
 	// Import covers a ~7 MB engine download (local assets) plus recognition.
 	test.setTimeout(180_000);

From cb45ae0a6691748bbef2ebe31df67bf0e13bd17d Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Wed, 26 Aug 2026 23:22:41 -0500
Subject: [PATCH 04/15] fix: fit a page to the pane, and show which sentence a
 click will play
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

At 100% a page now sizes to the room it has, however narrow the window
is — a page you must scroll sideways to read is not a readable page.
Above 100% it overflows on purpose (that is what zooming into a figure is
for), and the stack centres safely so the left edge stays reachable.

The hover wash was mixed for the reader's own background and all but
vanished on white paper, leaving nothing to say the paper was clickable.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte | 46 +++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index 51d0c8a..ae6eaa9 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -67,9 +67,35 @@
 		});
 	});
 
-	/** The width a page is drawn at, in CSS pixels: the reader's canvas width,
-	 * capped so a page never overflows the column it sits in. */
-	let renderWidth = $derived(readerChrome.documentCanvasWidth);
+	/** The room the stack has for a page, in CSS pixels. */
+	let available = $state(0);
+
+	/**
+	 * The width a page is drawn at. At 100% a page fits the pane, however
+	 * narrow it is — a page you have to scroll sideways to read is not a
+	 * readable page. Above 100% it is meant to overflow: that is what zooming
+	 * into a figure is for, and the stack scrolls both ways to follow.
+	 */
+	let renderWidth = $derived.by(() => {
+		// The reading view's column width before zoom — the same measure, so the
+		// two views feel like one document at one size.
+		const column = readerChrome.documentCanvasWidth / readerChrome.documentZoom;
+		const fitted = available > 0 ? Math.min(column, available) : column;
+		return Math.max(280, fitted) * readerChrome.documentZoom;
+	});
+
+	function trackStack(node: HTMLElement) {
+		scroller = node;
+		const observer = new ResizeObserver(() => {
+			const style = getComputedStyle(node);
+			available = node.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
+		});
+		observer.observe(node);
+		return () => {
+			observer.disconnect();
+			if (scroller === node) scroller = undefined;
+		};
+	}
 
 	let blockText = $derived(new Map(book.blocks.map((block) => [block.id, block.text])));
 
@@ -306,7 +332,7 @@
 	});
 </script>
 
-<div class="page-stack" bind:this={scroller}>
+<div class="page-stack" {@attach trackStack}>
 	{#each sizes as size (size.page)}
 		{@const scale = pageScale(size.page)}
 		{@const placed = placements.get(size.page)}
@@ -318,6 +344,8 @@
 			<!-- svelte-ignore a11y_no_static_element_interactions -->
 			<div
 				class="page-sheet"
+				class:over-passage={hovered?.page === size.page}
+				title="Double-click to play from here"
 				style:width={`${size.width * scale}px`}
 				style:height={`${size.height * scale}px`}
 				ondblclick={(event) => handleActivate(event, size.page)}
@@ -346,7 +374,9 @@
 		display: flex;
 		flex: 1;
 		flex-direction: column;
-		align-items: center;
+		/* `safe` matters once a zoomed page is wider than the pane: plain
+		   centring would put its left edge out of reach of the scrollbar. */
+		align-items: safe center;
 		gap: 26px;
 		overflow: auto;
 		padding: calc(var(--app-header-height) + 22px) 20px calc(var(--player-height) + 32px);
@@ -379,6 +409,10 @@
 		box-shadow: 0 6px 20px rgba(0, 0, 0, 0.18);
 	}
 
+	.page-sheet.over-passage {
+		cursor: pointer;
+	}
+
 	.page-sheet canvas {
 		display: block;
 		width: 100%;
@@ -411,7 +445,7 @@
 	}
 
 	.mark.hover {
-		background: color-mix(in srgb, var(--primary) 12%, transparent);
+		background: color-mix(in srgb, var(--primary) 17%, transparent);
 	}
 
 	/* Persistent reader ink: the same bookmark gold the reading view paints

From d78855256e97ef5a423d74baca264514d650a9b0 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Wed, 26 Aug 2026 23:24:06 -0500
Subject: [PATCH 05/15] fix: let the contents panel and the assistant move the
 page view
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Outline navigation looked up the heading's element and gave up when it
found none — which, in the page view, is always: the document there is a
picture of paper. It now addresses the heading's page instead, so clicking
a section actually goes somewhere.

The page also follows the assistant's fingertip while nothing is playing,
which is exactly when "show me this passage" is asked.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte | 10 ++++++----
 src/routes/read/+page.svelte          | 12 +++++++++---
 tests/reader.e2e.ts                   | 10 ++++++++++
 3 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index ae6eaa9..0147536 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -305,12 +305,14 @@
 	// Follow playback. A passage already comfortably on screen stays put:
 	// re-centring every sentence would drag the page under the reader's eyes.
 	$effect(() => {
-		if (!follow || !activeSegmentId || !scroller) return;
-		const page = pageBySegment.get(activeSegmentId);
-		const placement = activePlacement;
+		// Playback leads; when it is not running, the assistant's fingertip does.
+		const followed = activeSegmentId ?? assistantPointId;
+		if (!follow || !followed || !scroller) return;
+		const page = pageBySegment.get(followed);
+		const placement = activePlacement ?? placements.get(page ?? -1)?.get(followed);
 		const target = page === undefined ? undefined : scroller.querySelector(`[data-page="${page}"]`);
 		if (page === undefined || !(target instanceof HTMLElement)) {
-			const anchored = segments.find((segment) => segment.id === activeSegmentId)?.anchor.page;
+			const anchored = segments.find((segment) => segment.id === followed)?.anchor.page;
 			if (anchored) goToPage(anchored);
 			return;
 		}
diff --git a/src/routes/read/+page.svelte b/src/routes/read/+page.svelte
index 982f1d6..c2848ef 100644
--- a/src/routes/read/+page.svelte
+++ b/src/routes/read/+page.svelte
@@ -449,6 +449,7 @@
 		book?.sourceKind === 'pdf' && Boolean(book.sourcePath || book.sourceBlob)
 	);
 	let pagePeek = $state<{ page: number }>();
+	let pageView = $state<ReturnType<typeof PdfPageView>>();
 	// The original-page view needs both the file and a page count to lay out;
 	// a document missing either reads as markdown whatever the preference says.
 	let pageViewActive = $derived(
@@ -872,14 +873,18 @@
 	}
 
 	function navigateToOutlineBlock(block: DocumentBlock): void {
-		const element = elementInReader(block.id);
-		if (!element) return;
+		// In the page view there is no element for a heading — the document is a
+		// picture of paper. Its page number is the address instead, and the
+		// passage that follows re-centres once it has been placed.
+		const element = pageViewActive ? undefined : elementInReader(block.id);
+		if (!element && !pageViewActive) return;
 
 		const compactOutline = window.matchMedia('(max-width: 820px)').matches;
 		outlineNavigationBlockId = block.id;
 		activeOutlineBlockId = block.id;
 		outlineAnnouncement = `Moved to ${block.text}`;
-		scrollReaderTo(element, compactOutline);
+		if (element) scrollReaderTo(element, compactOutline);
+		else if (block.anchor.page) pageView?.goToPage(block.anchor.page);
 		if (compactOutline) readerChrome.outlineOpen = false;
 
 		const index = firstSegmentIndex(block);
@@ -2085,6 +2090,7 @@
 
 			{#if pageViewActive && documentPageCount}
 				<PdfPageView
+					bind:this={pageView}
 					document={book}
 					pageCount={documentPageCount}
 					segments={book.segments}
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index 96b69e9..fd75b87 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1849,6 +1849,16 @@ test('reads a PDF as its own pages, with the spoken passage painted on', async (
 	expect(painted!.y - sheetBox!.y).toBeLessThan(160 * scale);
 	expect(painted!.x - sheetBox!.x).toBeGreaterThan(60 * scale);
 
+	// The contents panel addresses a page rather than an element here, so the
+	// heading it names still moves the stack.
+	await page.getByRole('button', { name: /Open document outline/ }).click();
+	await page.getByRole('button', { name: 'The Second Winter', exact: true }).click();
+	await expect
+		.poll(async () => page.locator('.page-stack').evaluate((node) => node.scrollTop), {
+			timeout: 10_000
+		})
+		.toBeGreaterThan(sheetBox!.height / 2);
+
 	// The preference survives leaving and reopening the document.
 	await page.getByRole('link', { name: 'Library' }).first().click();
 	await page.getByRole('link', { name: 'Ledgers of the Coast' }).first().click();

From 48a7832ca5febf8e8ce05252ebe00225ea645cd3 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Wed, 26 Aug 2026 23:26:21 -0500
Subject: [PATCH 06/15] fix: read a two-column page in reading order before
 placing anything
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

LiteParse hands back word boxes in raster order — every line of a
two-column page interleaved with the line beside it — while its markdown
reads the columns properly. A monotonic alignment between two streams
that disagree about order finds almost nothing: 57% of passages placed on
a two-column paper, against 90% on a single-column one.

A recursive XY-cut recovers the order, splitting at vertical gutters
before horizontal ones so a page breaks into columns before it breaks
into paragraphs. Two-column placement goes to 92%; the single-column
paper is unchanged at 91%.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/domain/pdf-layout.spec.ts |  59 ++++++++++++++++
 src/lib/domain/pdf-layout.ts      | 109 ++++++++++++++++++++++++++++++
 src/lib/services/pdf-layout.ts    |   4 +-
 3 files changed, 171 insertions(+), 1 deletion(-)

diff --git a/src/lib/domain/pdf-layout.spec.ts b/src/lib/domain/pdf-layout.spec.ts
index ff6ffaa..29fac74 100644
--- a/src/lib/domain/pdf-layout.spec.ts
+++ b/src/lib/domain/pdf-layout.spec.ts
@@ -6,6 +6,7 @@ import {
 	mergeWordRects,
 	pageWordBoxes,
 	placeSegments,
+	readingOrder,
 	segmentsForPage,
 	type PageWordBox,
 	type PlaceableSegment
@@ -86,6 +87,64 @@ describe('pageWordBoxes', () => {
 	});
 });
 
+describe('readingOrder', () => {
+	/** A two-column page: a full-width title, then lines that alternate
+	 * between the columns exactly as a raster scan hands them over. */
+	function twoColumnPage(): PageWordBox[] {
+		const boxes = [...line('A Title Across The Page', 40, 150)];
+		for (let index = 0; index < 6; index += 1) {
+			const y = 100 + index * 14;
+			boxes.push(...line(`left${index}a left${index}b`, y, 50));
+			boxes.push(...line(`right${index}a right${index}b`, y + 2, 320));
+		}
+		return boxes;
+	}
+
+	it('reads each column through before starting the next', () => {
+		const ordered = readingOrder(twoColumnPage(), 612).map((box) => box.text);
+		const leftEnd = ordered.indexOf('left5b');
+		const rightStart = ordered.indexOf('right0a');
+		expect(ordered[0]).toBe('A');
+		expect(leftEnd).toBeLessThan(rightStart);
+	});
+
+	it('keeps a full-width heading ahead of the columns beneath it', () => {
+		const ordered = readingOrder(twoColumnPage(), 612).map((box) => box.text);
+		expect(ordered.slice(0, 5)).toEqual(['A', 'Title', 'Across', 'The', 'Page']);
+	});
+
+	it('leaves a single column in the order it arrived', () => {
+		const single = [
+			...line('the first line of the paragraph', 100, 50),
+			...line('the second line of the paragraph', 114, 50),
+			...line('and a third', 128, 50)
+		];
+		expect(readingOrder(single, 612)).toEqual(single);
+	});
+
+	it('reads a line left to right even when its words arrive scrambled', () => {
+		const words = line('alpha beta gamma', 100, 50);
+		const scrambled = [words[2], words[0], words[1]];
+		expect(readingOrder(scrambled, 612).map((box) => box.text)).toEqual(['alpha', 'beta', 'gamma']);
+	});
+
+	it('does not read a running head as two columns', () => {
+		// One line with something at each margin is a header, not a page of
+		// columns — splitting it would put the folio before the title.
+		const header = [
+			{ text: 'Chapter', x: 50, y: 40, width: 40, height: 10 },
+			{ text: '12', x: 540, y: 40, width: 12, height: 10 }
+		];
+		expect(readingOrder(header, 612).map((box) => box.text)).toEqual(['Chapter', '12']);
+	});
+
+	it('has nothing to reorder on an empty or single-word page', () => {
+		expect(readingOrder([], 612)).toEqual([]);
+		const one = line('alone', 10, 10);
+		expect(readingOrder(one, 612)).toEqual(one);
+	});
+});
+
 describe('chunkText', () => {
 	it('keys whitespace-separated chunks and remembers where they came from', () => {
 		expect(chunkText('The Transformer, again')).toEqual([
diff --git a/src/lib/domain/pdf-layout.ts b/src/lib/domain/pdf-layout.ts
index 81c638a..ce3a663 100644
--- a/src/lib/domain/pdf-layout.ts
+++ b/src/lib/domain/pdf-layout.ts
@@ -115,6 +115,115 @@ export function pageWordBoxes(items: PageTextItem[]): PageWordBox[] {
 	return boxes;
 }
 
+/**
+ * Reading order for a page's words.
+ *
+ * LiteParse hands back word boxes in raster order — every line of a
+ * two-column page interleaved with the line beside it. Its *markdown* reads
+ * the columns properly, so the passages arrive in true reading order and the
+ * boxes do not, and a monotonic alignment between the two finds almost
+ * nothing. (Measured on a two-column paper: 57% of passages placed, against
+ * 90% on a single-column one.)
+ *
+ * A recursive XY-cut recovers the order. At each step the region is split at
+ * whitespace that runs all the way across it — vertical gutters first,
+ * because a page whose body is two columns must break into columns before it
+ * breaks into paragraphs, or the halves interleave again. A single-column
+ * page finds no gutter, splits into paragraphs, and comes out in the order it
+ * already had.
+ */
+export function readingOrder(boxes: PageWordBox[], pageWidth: number): PageWordBox[] {
+	if (boxes.length < 2) return boxes;
+	const line = medianHeight(boxes);
+	const columnGap = Math.max(10, pageWidth * 0.025);
+	const rowGap = Math.max(2, line * 0.8);
+	return cut(boxes, columnGap, rowGap, line, 0);
+}
+
+/** Typical line height on the page, used to size the gaps that count as
+ * whitespace. The median shrugs off headings and subscripts. */
+function medianHeight(boxes: PageWordBox[]): number {
+	const heights = boxes.map((box) => box.height).sort((left, right) => left - right);
+	return heights[heights.length >> 1] || 10;
+}
+
+/** Regions this deep are paragraphs; splitting further only costs time. */
+const MAX_CUT_DEPTH = 8;
+/** A vertical split needs a region tall enough to be a column. Without this,
+ * a single line with something at each margin — a running head, a page
+ * number — reads as two columns. */
+const MIN_COLUMN_LINES = 4;
+
+function cut(
+	boxes: PageWordBox[],
+	columnGap: number,
+	rowGap: number,
+	line: number,
+	depth: number
+): PageWordBox[] {
+	if (boxes.length < 2 || depth >= MAX_CUT_DEPTH) return byLine(boxes);
+	const height = extent(boxes, 'y');
+	if (height >= line * MIN_COLUMN_LINES) {
+		const columns = split(boxes, 'x', columnGap);
+		if (columns.length > 1) {
+			return columns.flatMap((column) => cut(column, columnGap, rowGap, line, depth + 1));
+		}
+	}
+	const rows = split(boxes, 'y', rowGap);
+	if (rows.length > 1) {
+		return rows.flatMap((row) => cut(row, columnGap, rowGap, line, depth + 1));
+	}
+	return byLine(boxes);
+}
+
+function extent(boxes: PageWordBox[], axis: 'x' | 'y'): number {
+	const size = axis === 'x' ? 'width' : 'height';
+	let low = Infinity;
+	let high = -Infinity;
+	for (const box of boxes) {
+		low = Math.min(low, box[axis]);
+		high = Math.max(high, box[axis] + box[size]);
+	}
+	return high - low;
+}
+
+/** Split a region wherever whitespace runs all the way across it on one axis,
+ * keeping the pieces in ascending order. */
+function split(boxes: PageWordBox[], axis: 'x' | 'y', minGap: number): PageWordBox[][] {
+	const size = axis === 'x' ? 'width' : 'height';
+	const ordered = [...boxes].sort((left, right) => left[axis] - right[axis]);
+	const groups: PageWordBox[][] = [];
+	let group: PageWordBox[] = [];
+	let reach = -Infinity;
+	for (const box of ordered) {
+		if (group.length && box[axis] - reach > minGap) {
+			groups.push(group);
+			group = [];
+		}
+		group.push(box);
+		reach = Math.max(reach, box[axis] + box[size]);
+	}
+	if (group.length) groups.push(group);
+	return groups;
+}
+
+/** The last word: rows of type, each read left to right. */
+function byLine(boxes: PageWordBox[]): PageWordBox[] {
+	const ordered = [...boxes].sort((left, right) => left.y - right.y || left.x - right.x);
+	const lines: PageWordBox[][] = [];
+	for (const box of ordered) {
+		const current = lines[lines.length - 1];
+		const previous = current?.[0];
+		const sameLine =
+			previous &&
+			Math.abs(box.y + box.height / 2 - (previous.y + previous.height / 2)) <
+				Math.max(box.height, previous.height) / 2;
+		if (sameLine) current.push(box);
+		else lines.push([box]);
+	}
+	return lines.flatMap((entries) => entries.sort((left, right) => left.x - right.x));
+}
+
 interface Chunk {
 	key: string;
 	start: number;
diff --git a/src/lib/services/pdf-layout.ts b/src/lib/services/pdf-layout.ts
index ff2fa85..3fa9029 100644
--- a/src/lib/services/pdf-layout.ts
+++ b/src/lib/services/pdf-layout.ts
@@ -2,6 +2,7 @@ import type { NormalizedDocument, SpeechSegment } from '../domain/types';
 import {
 	pageWordBoxes,
 	placeSegments,
+	readingOrder,
 	segmentsForPage,
 	type PageWordBox,
 	type SegmentPlacement
@@ -189,7 +190,8 @@ const readWithLiteparse: PageWindowReader = async (data, from, to) => {
 		page: page.pageNum,
 		width: page.width,
 		height: page.height,
-		boxes: pageWordBoxes(page.textItems ?? [])
+		// Raster order as read; reading order as written.
+		boxes: readingOrder(pageWordBoxes(page.textItems ?? []), page.width)
 	}));
 };
 

From 2083d6bd78fb8a708f6df9347e3db3e4af603a8e Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Wed, 26 Aug 2026 23:39:48 -0500
Subject: [PATCH 07/15] fix: stop the page view snapping back to the playhead
 while scrolling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Following was a plain effect over state that changes for reasons having
nothing to do with the playhead: every page that finishes placing as you
scroll updates `placements`, and each of those updates re-ran the scroll.
Reading ahead was impossible — the document pulled itself back within a
second or two, over and over.

Following is now edge-triggered, the way the reflowed canvas has always
done it: one passage becoming current earns at most one jump to its page
and one settle onto its line. And a wheel or touch scroll stops following
outright, again matching the reflowed canvas — that listener was simply
missing here, so "Follow narration" never appeared and there was no way
to opt out.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte | 62 ++++++++++++++++++++++++---
 src/routes/read/+page.svelte          |  1 +
 tests/reader.e2e.ts                   | 27 ++++++++++++
 3 files changed, 84 insertions(+), 6 deletions(-)

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index 0147536..c8145b2 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { on } from 'svelte/events';
 	import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 	import type { NormalizedDocument, SpeechSegment } from '$lib/domain/types';
 	import type { PageRect, SegmentPlacement } from '$lib/domain/pdf-layout';
@@ -22,6 +23,8 @@
 		/** Whether playback should pull the page along with it. */
 		follow?: boolean;
 		onPlaySegment: (segmentId: string) => void;
+		/** The reader scrolled by hand; whatever was following should stop. */
+		onManualScroll?: () => void;
 	}
 
 	let {
@@ -34,7 +37,8 @@
 		assistantSegmentIds,
 		assistantPointId,
 		follow = true,
-		onPlaySegment
+		onPlaySegment,
+		onManualScroll
 	}: Props = $props();
 
 	/** US Letter, for a document whose parse recorded no page sizes. */
@@ -91,8 +95,19 @@
 			available = node.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
 		});
 		observer.observe(node);
+		// Reading ahead of the narration wins over following it, the same way it
+		// does on the reflowed canvas.
+		const stopFollowing = () => {
+			owedFollow = undefined;
+			onManualScroll?.();
+		};
+		const removeListeners = [
+			on(node, 'wheel', stopFollowing, { passive: true }),
+			on(node, 'touchmove', stopFollowing, { passive: true })
+		];
 		return () => {
 			observer.disconnect();
+			for (const removeListener of removeListeners) removeListener();
 			if (scroller === node) scroller = undefined;
 		};
 	}
@@ -302,25 +317,60 @@
 		element?.scrollIntoView({ block: 'start', behavior: 'auto' });
 	}
 
-	// Follow playback. A passage already comfortably on screen stays put:
-	// re-centring every sentence would drag the page under the reader's eyes.
+	/**
+	 * Following is edge-triggered: one passage becoming current earns at most
+	 * one jump to its page and one settle onto its line, and nothing else moves
+	 * the scroll.
+	 *
+	 * This has to be a debt rather than a plain effect, because the effect's
+	 * inputs change constantly for reasons that have nothing to do with the
+	 * playhead — every page that finishes placing as the reader scrolls updates
+	 * `placements`. Re-running the scroll on those was the bug that made the
+	 * document snap back to the playhead each time you tried to read ahead.
+	 */
+	let owedFollow = $state<string>();
+	let jumpedToPage = false;
+	let followedLast: string | undefined;
+	// Undefined until the first run, so mounting counts as a change and an
+	// already-current passage is followed on open.
+	let followLast: boolean | undefined;
+
 	$effect(() => {
 		// Playback leads; when it is not running, the assistant's fingertip does.
 		const followed = activeSegmentId ?? assistantPointId;
+		if (followed !== followedLast || follow !== followLast) {
+			followedLast = followed;
+			followLast = follow;
+			// Re-enabling follow owes a scroll too: that is the whole point of the
+			// "Follow narration" button.
+			owedFollow = follow ? followed : undefined;
+			jumpedToPage = false;
+		}
+	});
+
+	$effect(() => {
+		const followed = owedFollow;
 		if (!follow || !followed || !scroller) return;
 		const page = pageBySegment.get(followed);
-		const placement = activePlacement ?? placements.get(page ?? -1)?.get(followed);
-		const target = page === undefined ? undefined : scroller.querySelector(`[data-page="${page}"]`);
+		const target = page === undefined ? null : scroller.querySelector(`[data-page="${page}"]`);
 		if (page === undefined || !(target instanceof HTMLElement)) {
+			// The passage has not been placed yet — its page may not even have
+			// been read. Go to where it is anchored, once, and settle onto the
+			// line itself if and when the placement arrives.
+			if (jumpedToPage) return;
 			const anchored = segments.find((segment) => segment.id === followed)?.anchor.page;
+			jumpedToPage = true;
 			if (anchored) goToPage(anchored);
 			return;
 		}
-		const rect = placement?.rects[0];
+		const rect = placements.get(page)?.get(followed)?.rects[0];
 		if (!rect) return;
+		owedFollow = undefined;
 		const scale = pageScale(page);
 		const top = target.offsetTop + rect.y * scale;
 		const height = rect.height * scale;
+		// A passage already comfortably on screen stays put: re-centring every
+		// sentence would drag the page under the reader's eyes.
 		const settled = 72;
 		const visibleFrom = scroller.scrollTop + settled;
 		const visibleTo = scroller.scrollTop + scroller.clientHeight - settled;
diff --git a/src/routes/read/+page.svelte b/src/routes/read/+page.svelte
index c2848ef..00238ee 100644
--- a/src/routes/read/+page.svelte
+++ b/src/routes/read/+page.svelte
@@ -2101,6 +2101,7 @@
 					{assistantPointId}
 					follow={player.autoFollow}
 					onPlaySegment={playPlacedSegment}
+					onManualScroll={() => (player.autoFollow = false)}
 				/>
 			{:else}
 				<article
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index fd75b87..be69fdf 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1849,6 +1849,33 @@ test('reads a PDF as its own pages, with the spoken passage painted on', async (
 	expect(painted!.y - sheetBox!.y).toBeLessThan(160 * scale);
 	expect(painted!.x - sheetBox!.x).toBeGreaterThan(60 * scale);
 
+	// Reading ahead of the narration must stay where it was put. Pages place
+	// as they scroll into view, and re-following the playhead on each of those
+	// updates snapped the document back to it every time.
+	const stack = page.locator('.page-stack');
+	await page.mouse.move(700, 400);
+	await page.mouse.wheel(0, 2400);
+	await expect.poll(async () => stack.evaluate((node) => node.scrollTop)).toBeGreaterThan(1200);
+	const settledAt = await stack.evaluate((node) => node.scrollTop);
+	// Long enough for the pages now in view to finish placing.
+	await page.waitForTimeout(2500);
+	expect(await stack.evaluate((node) => node.scrollTop)).toBe(settledAt);
+
+	// Following resumes on request, and brings the passage being spoken back
+	// into view.
+	await page.getByRole('button', { name: 'Follow narration' }).click();
+	await expect
+		.poll(
+			async () => {
+				const port = await stack.boundingBox();
+				const mark = await page.locator('.mark.passage').first().boundingBox();
+				if (!port || !mark) return false;
+				return mark.y >= port.y && mark.y + mark.height <= port.y + port.height;
+			},
+			{ timeout: 10_000 }
+		)
+		.toBe(true);
+
 	// The contents panel addresses a page rather than an element here, so the
 	// heading it names still moves the stack.
 	await page.getByRole('button', { name: /Open document outline/ }).click();

From bb0f9c650b51ac888676a26d3efe32f0927068d1 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Thu, 27 Aug 2026 00:33:42 -0500
Subject: [PATCH 08/15] fix: stop a heavy vector page from taking the page view
 down with it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A paper with a 163,000-operation figure on page 12 made the view unusable:
that page tried to draw over and over and never appeared, and eventually
the tab went black.

Three causes, all in how draws were scheduled:

- Nothing stopped a page being queued for drawing while it was already
  being drawn. Draws run one at a time, so a page that takes seconds
  collected a queue of duplicate requests, and every other page waited
  behind them.
- A draw could not be abandoned. Scrolling past a heavy page left it
  holding the queue against the pages actually on screen.
- Bitmaps were released the moment a page left the scrollport, so
  scrolling back and forth redrew everything each pass — 24 releases over
  three sweeps of a six-page document, where none is right.

Draws are now abortable (pdf.js `RenderTask.cancel`), never duplicated,
ordered nearest-the-reader-first, and released against a memory budget
rather than on leaving view. Layout no longer waits on the bitmap either:
a page drawn at another zoom is briefly soft instead of the wrong size.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte | 123 ++++++++++++++++++++++----
 src/lib/services/pdf-pages.ts         |  34 +++++--
 tests/reader.e2e.ts                   |  77 ++++++++++++++++
 3 files changed, 208 insertions(+), 26 deletions(-)

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index c8145b2..bc397d3 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -49,12 +49,17 @@
 	const PREPARE_MARGIN = '150% 0px';
 
 	let scroller = $state<HTMLElement>();
+	/** The page under the middle of the scrollport: what to draw first, and
+	 * what to measure distance from when releasing bitmaps. */
+	let focusPage = $state(1);
 	const canvases = new SvelteMap<number, HTMLCanvasElement>();
 	/** Pages near enough the scrollport to be worth drawing. */
 	const live = new SvelteSet<number>();
-	/** Page → CSS pixels per PDF point, read back from the rendered canvas so
-	 * the overlay follows the bitmap rather than a predicted size. */
-	const scales = new SvelteMap<number, number>();
+	/** Page → the width its bitmap was drawn for. Only the draw loop and the
+	 * memory budget care: layout never does, because the canvas is stretched to
+	 * whatever size its sheet is, so a page drawn at another zoom is briefly
+	 * soft rather than the wrong size. */
+	const drawnWidths = new SvelteMap<number, number>();
 	const placements = new SvelteMap<number, Map<string, SegmentPlacement>>();
 	let hovered = $state<{ page: number; segmentId: string }>();
 
@@ -95,6 +100,25 @@
 			available = node.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
 		});
 		observer.observe(node);
+		let measuring = false;
+		const measureFocus = () => {
+			if (measuring) return;
+			measuring = true;
+			requestAnimationFrame(() => {
+				measuring = false;
+				const middle = node.scrollTop + node.clientHeight / 2;
+				let nearest = focusPage;
+				let best = Infinity;
+				for (const slot of node.querySelectorAll<HTMLElement>('.page-slot')) {
+					const distance = Math.abs(slot.offsetTop + slot.offsetHeight / 2 - middle);
+					if (distance >= best) continue;
+					best = distance;
+					nearest = Number(slot.dataset.page);
+				}
+				if (Number.isFinite(nearest)) focusPage = nearest;
+			});
+		};
+		measureFocus();
 		// Reading ahead of the narration wins over following it, the same way it
 		// does on the reflowed canvas.
 		const stopFollowing = () => {
@@ -102,6 +126,7 @@
 			onManualScroll?.();
 		};
 		const removeListeners = [
+			on(node, 'scroll', measureFocus, { passive: true }),
 			on(node, 'wheel', stopFollowing, { passive: true }),
 			on(node, 'touchmove', stopFollowing, { passive: true })
 		];
@@ -159,38 +184,98 @@
 			canvases.set(page, node);
 			return () => {
 				canvases.delete(page);
-				scales.delete(page);
+				drawnWidths.delete(page);
 			};
 		};
 	}
 
-	// Draw the pages that are in play, at the current zoom. Re-runs on zoom
-	// because the bitmap is rendered at the display size, not scaled up from a
-	// smaller one — a PDF page enlarged from a stale raster is a blurry page.
+	/**
+	 * Bitmaps to keep, as a pixel budget rather than a page count: a page of A4
+	 * at 200% is four times the memory of one at 100%, and it is the megabytes
+	 * that crash a tab, not the number of pages. Roughly 200 MB of RGBA.
+	 */
+	const RENDERED_PIXEL_BUDGET = 48_000_000;
+
+	/** Pages being drawn right now: the width each draw is for, and the handle
+	 * that abandons it. Deliberately NOT a SvelteMap — the draw loop consults it
+	 * but must not be re-run by it, or recording the start of a draw would
+	 * restart the effect that started the draw. Every write here is paired with
+	 * a reactive one (`drawnWidths`) when the draw actually lands. */
+	// eslint-disable-next-line svelte/prefer-svelte-reactivity
+	const drawing = new Map<number, { width: number; controller: AbortController }>();
+
+	function drawnPixels(page: number): number {
+		const canvas = canvases.get(page);
+		return canvas ? canvas.width * canvas.height : 0;
+	}
+
+	/**
+	 * Draw the pages that are in play, at the current zoom. Re-runs on zoom
+	 * because the bitmap is rendered at the display size, not scaled up from a
+	 * smaller one — a PDF page enlarged from a stale raster is a blurry page.
+	 *
+	 * Three rules keep a heavy page from taking the view down with it, all
+	 * learned from one paper with a 163,000-operation vector figure on page 12:
+	 * a page already being drawn is never queued again, a page the reader has
+	 * left is abandoned mid-draw, and bitmaps are released against a memory
+	 * budget instead of the moment a page leaves the scrollport. Without the
+	 * last one, scrolling back and forth across that figure re-drew it every
+	 * pass; without the first two, those draws piled up in a queue that runs
+	 * one at a time, and every other page stopped appearing behind it.
+	 */
 	$effect(() => {
 		const width = renderWidth;
 		const pages = new Set(live);
-		// A page that has scrolled well away gives its bitmap back: a long
-		// document would otherwise accumulate one full-size raster per page
-		// visited, which is where a page view runs out of memory.
-		for (const [page, canvas] of canvases) {
-			if (pages.has(page) || !scales.has(page)) continue;
+
+		// Abandon draws nobody is waiting for any more: the reader has scrolled
+		// past the page, or has zoomed, which makes the size being drawn wrong.
+		for (const [page, draw] of drawing) {
+			if (!pages.has(page) || draw.width !== width) draw.controller.abort();
+		}
+
+		// Release bitmaps once they add up to more than the budget, furthest from
+		// the reader first. A page in view or mid-draw is never released.
+		const rendered = [...drawnWidths.keys()].filter(
+			(page) => !pages.has(page) && !drawing.has(page)
+		);
+		let held = [...drawnWidths.keys()].reduce((total, page) => total + drawnPixels(page), 0);
+		const focus = focusPage;
+		rendered.sort((left, right) => Math.abs(right - focus) - Math.abs(left - focus));
+		for (const page of rendered) {
+			if (held <= RENDERED_PIXEL_BUDGET) break;
+			const canvas = canvases.get(page);
+			if (!canvas) continue;
+			held -= drawnPixels(page);
 			canvas.width = 0;
 			canvas.height = 0;
-			scales.delete(page);
+			drawnWidths.delete(page);
 		}
+
 		let cancelled = false;
+		// Nearest the reader first: draws run one at a time, and a page of dense
+		// vector art can hold the queue for seconds. Whoever is waiting should be
+		// waiting for the page they are looking at.
+		const order = [...pages].sort(
+			(left, right) => Math.abs(left - focusPage) - Math.abs(right - focusPage)
+		);
 		void openPdfRenderer(book).then(async (renderer) => {
 			if (!renderer || cancelled) return;
-			for (const page of pages) {
+			for (const page of order) {
 				if (cancelled) return;
 				const canvas = canvases.get(page);
-				if (!canvas || scales.get(page) === width / pageWidth(page)) continue;
+				// Already drawn at this size, or already being drawn: queueing it
+				// again would only make the reader wait behind their own request.
+				if (!canvas || drawing.has(page) || drawnWidths.get(page) === width) continue;
+				const draw = { width, controller: new AbortController() };
+				drawing.set(page, draw);
 				try {
-					await renderer.renderPage(page, canvas, width);
-					if (!cancelled) scales.set(page, width / pageWidth(page));
+					await renderer.renderPage(page, canvas, width, draw.controller.signal);
+					drawnWidths.set(page, width);
 				} catch {
-					// A page that will not draw stays blank; the rest still read.
+					// Abandoned, or a page that will not draw: leave it blank rather
+					// than recording a size it was never drawn at. The rest still read.
+				} finally {
+					if (drawing.get(page) === draw) drawing.delete(page);
 				}
 			}
 		});
@@ -230,7 +315,7 @@
 	}
 
 	function pageScale(page: number): number {
-		return scales.get(page) ?? renderWidth / pageWidth(page);
+		return renderWidth / pageWidth(page);
 	}
 
 	function styleFor(rect: PageRect, page: number): string {
diff --git a/src/lib/services/pdf-pages.ts b/src/lib/services/pdf-pages.ts
index 74414a4..e9b8c7c 100644
--- a/src/lib/services/pdf-pages.ts
+++ b/src/lib/services/pdf-pages.ts
@@ -8,8 +8,18 @@ const MAX_PIXELS = 16 * 1024 * 1024;
 export interface PageRasterizer {
 	readonly pageCount: number;
 	/** Draws a page (1-based) into `canvas` sized for `cssWidth` CSS pixels at
-	 * the device pixel ratio. Sets the canvas buffer and style sizes. */
-	renderPage(page: number, canvas: HTMLCanvasElement, cssWidth: number): Promise<void>;
+	 * the device pixel ratio. Sets the canvas buffer and style sizes.
+	 *
+	 * Aborting `signal` abandons the draw — while it is still queued, or partway
+	 * through. A page of dense vector art can take seconds to paint, and renders
+	 * run one at a time, so a reader who has scrolled past one must not leave it
+	 * holding the queue against every page they are actually looking at. */
+	renderPage(
+		page: number,
+		canvas: HTMLCanvasElement,
+		cssWidth: number,
+		signal?: AbortSignal
+	): Promise<void>;
 	/** Renders a page (1-based) to an OffscreenCanvas at `scale`× the page's
 	 * natural point size — the OCR path's rasterizer. */
 	rasterize(page: number, scale: number): Promise<OffscreenCanvas>;
@@ -49,8 +59,10 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 	const renderInto = async (
 		pageNumber: number,
 		canvas: HTMLCanvasElement | OffscreenCanvas,
-		requestedScale: number
+		requestedScale: number,
+		signal?: AbortSignal
 	) => {
+		signal?.throwIfAborted();
 		const page = await pdf.getPage(pageNumber);
 		try {
 			const base = page.getViewport({ scale: 1 });
@@ -59,10 +71,17 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 			});
 			canvas.width = Math.floor(viewport.width);
 			canvas.height = Math.floor(viewport.height);
-			await page.render({
+			const task = page.render({
 				canvas: canvas as HTMLCanvasElement,
 				viewport
-			}).promise;
+			});
+			const abort = () => task.cancel();
+			signal?.addEventListener('abort', abort, { once: true });
+			try {
+				await task.promise;
+			} finally {
+				signal?.removeEventListener('abort', abort);
+			}
 			return viewport;
 		} finally {
 			page.cleanup();
@@ -71,13 +90,14 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 
 	return {
 		pageCount: pdf.numPages,
-		renderPage: (pageNumber, canvas, cssWidth) =>
+		renderPage: (pageNumber, canvas, cssWidth, signal) =>
 			serialize(async () => {
+				signal?.throwIfAborted();
 				const page = await pdf.getPage(pageNumber);
 				const width = page.getViewport({ scale: 1 }).width;
 				page.cleanup();
 				const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
-				const viewport = await renderInto(pageNumber, canvas, (cssWidth / width) * ratio);
+				const viewport = await renderInto(pageNumber, canvas, (cssWidth / width) * ratio, signal);
 				canvas.style.width = `${Math.round(viewport.width / ratio)}px`;
 				canvas.style.height = `${Math.round(viewport.height / ratio)}px`;
 			}),
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index be69fdf..653b6f5 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1894,6 +1894,83 @@ test('reads a PDF as its own pages, with the spoken passage painted on', async (
 	await expect(page.locator('.reading-canvas')).toBeVisible();
 });
 
+test('draws each original page once while the reader scrolls back and forth', async ({ page }) => {
+	await openReadyLibrary(page);
+	const pdf = await PDFDocument.create();
+	const font = await pdf.embedFont(StandardFonts.Helvetica);
+	// Each page says something of its own: pages that differ only by a number
+	// read as a running header, and the importer strips those.
+	const bodies = [
+		'The harbour master kept a ledger of every tide that entered the bay.',
+		'A cooper in the town sewed the loose pages into a heavier cover.',
+		'Winter storms are recorded in a hand that grows steadily smaller.',
+		'By spring the entries return to their usual patient width again.',
+		'The last volume breaks off in the middle of an ordinary morning.',
+		'Nobody wrote down why the record stops where it does.'
+	];
+	for (const [index, body] of bodies.entries()) {
+		const sheet = pdf.addPage([612, 792]);
+		sheet.drawText(`Section ${index + 1}`, { x: 72, y: 720, size: 20, font });
+		sheet.drawText(body, { x: 72, y: 680, size: 12, font });
+	}
+	await page.locator('#document-upload').setInputFiles({
+		name: 'survey.pdf',
+		mimeType: 'application/pdf',
+		buffer: Buffer.from(await pdf.save())
+	});
+	await expect(page.locator('.reading-canvas')).toBeVisible({ timeout: 60_000 });
+	await page.getByRole('button', { name: /Switch view/ }).click();
+	await expect(page.locator('.page-slot')).toHaveCount(6);
+	await expect
+		.poll(
+			async () =>
+				page
+					.locator('.page-slot[data-page="1"] canvas')
+					.evaluate((node: HTMLCanvasElement) => node.width),
+			{ timeout: 30_000 }
+		)
+		.toBeGreaterThan(400);
+
+	// Count the moments a page's bitmap is thrown away. Releasing one is only
+	// meant to happen under memory pressure, which six letter pages come
+	// nowhere near — releasing them as they leave the scrollport instead meant
+	// every sweep redrew the lot, and a page of dense vector art could not
+	// survive that.
+	await page.evaluate(() => {
+		let released = 0;
+		const widths = new Map<number, number>();
+		(window as unknown as { __released: () => number }).__released = () => released;
+		setInterval(() => {
+			for (const canvas of document.querySelectorAll<HTMLCanvasElement>('.page-slot canvas')) {
+				const number = Number(canvas.closest<HTMLElement>('.page-slot')?.dataset.page);
+				const was = widths.get(number);
+				if (was && was > 1 && canvas.width <= 1) released += 1;
+				widths.set(number, canvas.width);
+			}
+		}, 40);
+	});
+
+	await page.mouse.move(700, 400);
+	for (let sweep = 0; sweep < 3; sweep += 1) {
+		for (let step = 0; step < 12; step += 1) await page.mouse.wheel(0, 800);
+		await page.waitForTimeout(250);
+		for (let step = 0; step < 12; step += 1) await page.mouse.wheel(0, -800);
+		await page.waitForTimeout(250);
+	}
+	await page.waitForTimeout(1500);
+	expect(
+		await page.evaluate(() => (window as unknown as { __released: () => number }).__released())
+	).toBe(0);
+	// And every page is drawn, at the size it is shown.
+	const drawn = await page.evaluate(
+		() =>
+			[...document.querySelectorAll<HTMLCanvasElement>('.page-slot canvas')].filter(
+				(canvas) => canvas.width > 400
+			).length
+	);
+	expect(drawn).toBe(6);
+});
+
 test('recognizes a scanned PDF with on-device text recognition', async ({ page }) => {
 	// Import covers a ~7 MB engine download (local assets) plus recognition.
 	test.setTimeout(180_000);

From bfefe0ea76473447027439df4349a98cae4ddb50 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Thu, 27 Aug 2026 00:45:56 -0500
Subject: [PATCH 09/15] fix: count abandoned bitmaps against the page view's
 memory budget

A canvas is sized the moment its draw begins, so a draw that is abandoned
leaves a full-size bitmap behind with nothing recorded against it. The
budget counted the record rather than the pixels, so those went unseen and
accumulated: 300 MB after a few sweeps of a twenty-page paper at retina
scale, which is the shape of a tab going black.

An abandoned draw now gives its bitmap straight back, and the budget is
measured over the canvases themselves. Same sweeps: 134 MB, held at the
budget rather than climbing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte | 31 +++++++++++++++++++--------
 tests/reader.e2e.ts                   | 31 +++++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index bc397d3..57b1ddd 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -190,11 +190,14 @@
 	}
 
 	/**
-	 * Bitmaps to keep, as a pixel budget rather than a page count: a page of A4
-	 * at 200% is four times the memory of one at 100%, and it is the megabytes
-	 * that crash a tab, not the number of pages. Roughly 200 MB of RGBA.
+	 * Bitmaps to keep, as a pixel budget rather than a page count: a page at
+	 * 200% zoom is four times the memory of the same page at 100%, and on a
+	 * retina display four times again — it is the megabytes that take a tab
+	 * down, not the number of pages. About 130 MB of canvas, which on a retina
+	 * display is still half a dozen pages kept either side of the two or three
+	 * actually on screen.
 	 */
-	const RENDERED_PIXEL_BUDGET = 48_000_000;
+	const RENDERED_PIXEL_BUDGET = 32_000_000;
 
 	/** Pages being drawn right now: the width each draw is for, and the handle
 	 * that abandons it. Deliberately NOT a SvelteMap — the draw loop consults it
@@ -235,10 +238,16 @@
 
 		// Release bitmaps once they add up to more than the budget, furthest from
 		// the reader first. A page in view or mid-draw is never released.
-		const rendered = [...drawnWidths.keys()].filter(
-			(page) => !pages.has(page) && !drawing.has(page)
+		//
+		// Counted over the canvases, not over the pages recorded as drawn: a
+		// canvas is sized the moment its draw begins, so an abandoned draw leaves
+		// a full-size bitmap behind with nothing recorded against it. Budgeting
+		// by the record instead of the pixels let those accumulate unseen — 300 MB
+		// of them after a few sweeps of a twenty-page paper on a retina display.
+		const rendered = [...canvases.keys()].filter(
+			(page) => drawnPixels(page) > 1 && !pages.has(page) && !drawing.has(page)
 		);
-		let held = [...drawnWidths.keys()].reduce((total, page) => total + drawnPixels(page), 0);
+		let held = [...canvases.keys()].reduce((total, page) => total + drawnPixels(page), 0);
 		const focus = focusPage;
 		rendered.sort((left, right) => Math.abs(right - focus) - Math.abs(left - focus));
 		for (const page of rendered) {
@@ -272,8 +281,12 @@
 					await renderer.renderPage(page, canvas, width, draw.controller.signal);
 					drawnWidths.set(page, width);
 				} catch {
-					// Abandoned, or a page that will not draw: leave it blank rather
-					// than recording a size it was never drawn at. The rest still read.
+					// Abandoned, or a page that will not draw. Either way the canvas
+					// is holding a bitmap of a picture nobody will see, so give it
+					// back now rather than leaving it for the budget to find.
+					canvas.width = 0;
+					canvas.height = 0;
+					drawnWidths.delete(page);
 				} finally {
 					if (drawing.get(page) === draw) drawing.delete(page);
 				}
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index 653b6f5..cb2ff20 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1969,6 +1969,37 @@ test('draws each original page once while the reader scrolls back and forth', as
 			).length
 	);
 	expect(drawn).toBe(6);
+
+	// Zooming abandons whatever draws were in flight for the old size. The pages
+	// in view must come back at the new one — an abandoned draw that left its
+	// half-finished bitmap in place would show as a torn page here.
+	await page.getByRole('button', { name: /Document zoom/ }).click();
+	await page.getByRole('slider', { name: 'Document zoom' }).fill('140');
+	await page.keyboard.press('Escape');
+	await expect
+		.poll(
+			async () =>
+				page.evaluate(() => {
+					const slots = [...document.querySelectorAll<HTMLElement>('.page-slot')];
+					// A page renders its marks layer only while it is in play.
+					const inPlay = slots.filter((slot) => slot.querySelector('.page-marks'));
+					if (!inPlay.length) return null;
+					const widths = inPlay.map(
+						(slot) => slot.querySelector<HTMLCanvasElement>('canvas')?.width ?? 0
+					);
+					const sheet = inPlay[0].querySelector<HTMLElement>('.page-sheet');
+					const shown = Math.round(sheet?.getBoundingClientRect().width ?? 0);
+					const distinct = [...new Set(widths)];
+					return {
+						// One size, and it is the size the page is being shown at
+						// (the bitmap floors to a whole pixel).
+						sizes: distinct.length,
+						matchesSheet: distinct.every((width) => Math.abs(width - shown) <= 1)
+					};
+				}),
+			{ timeout: 20_000 }
+		)
+		.toEqual({ sizes: 1, matchesSheet: true });
 });
 
 test('recognizes a scanned PDF with on-device text recognition', async ({ page }) => {

From 250c8d9eefb8d9c227f8908e80e8ec95e48ee3f6 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Thu, 27 Aug 2026 01:12:56 -0500
Subject: [PATCH 10/15] fix: paint pages off-screen so zooming does not strobe
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Dragging the zoom slider made the pages flash black and back. Two causes,
one of them mine from the previous fix.

Pages were painted straight into the canvas the reader is looking at.
pdf.js clears it, then fills it in over however many frames the page
needs — a flash on every redraw, and a strobe while a slider reports every
percent it passes through. Worse, the previous commit had abandoned draws
hand their bitmap back immediately, which turned each of those aborts into
a blank page rather than a stale one.

Pages are now painted off-screen and handed over whole, so a canvas keeps
showing the picture it has until the next one is finished, and abandoning
a draw costs the reader nothing. The width drawn at also settles for a
beat before anything redraws, so one drag of the slider is one redraw
rather than twenty-five abandoned ones; layout still follows the slider
immediately, so the pages resize under it and are briefly soft instead of
absent.

Measured on the paper that prompted this, at retina scale, dragging
100%→150%: no blank frame in 392 samples of the pages on screen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte | 38 ++++++++++++++++++----
 src/lib/services/pdf-pages.ts         | 45 ++++++++++++++++++++++++++-
 tests/reader.e2e.ts                   | 31 +++++++++++++++---
 3 files changed, 103 insertions(+), 11 deletions(-)

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index 57b1ddd..889a43b 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -93,6 +93,33 @@
 		return Math.max(280, fitted) * readerChrome.documentZoom;
 	});
 
+	/**
+	 * The width to draw at, held still until the reader stops changing it. The
+	 * zoom slider reports every percent it passes through, and redrawing on each
+	 * would abandon and restart every page fifty times across one drag. Layout
+	 * follows `renderWidth` immediately, so the pages resize under the slider
+	 * as it moves — a little soft until the redraw lands, which is what a zoom
+	 * should feel like.
+	 */
+	let drawWidth = $state(0);
+	const ZOOM_SETTLE_MS = 160;
+	/** Plain, not reactive: the settle effect must depend on the width being
+	 * asked for, never on the width it last handed over. */
+	let widthSeen: number | undefined;
+
+	$effect(() => {
+		const width = renderWidth;
+		const first = widthSeen === undefined;
+		widthSeen = width;
+		// The first width is not a zoom — draw at it straight away.
+		if (first) {
+			drawWidth = width;
+			return;
+		}
+		const settle = setTimeout(() => (drawWidth = width), ZOOM_SETTLE_MS);
+		return () => clearTimeout(settle);
+	});
+
 	function trackStack(node: HTMLElement) {
 		scroller = node;
 		const observer = new ResizeObserver(() => {
@@ -227,8 +254,9 @@
 	 * one at a time, and every other page stopped appearing behind it.
 	 */
 	$effect(() => {
-		const width = renderWidth;
+		const width = drawWidth;
 		const pages = new Set(live);
+		if (!width) return;
 
 		// Abandon draws nobody is waiting for any more: the reader has scrolled
 		// past the page, or has zoomed, which makes the size being drawn wrong.
@@ -281,11 +309,9 @@
 					await renderer.renderPage(page, canvas, width, draw.controller.signal);
 					drawnWidths.set(page, width);
 				} catch {
-					// Abandoned, or a page that will not draw. Either way the canvas
-					// is holding a bitmap of a picture nobody will see, so give it
-					// back now rather than leaving it for the budget to find.
-					canvas.width = 0;
-					canvas.height = 0;
+					// Abandoned, or a page that will not draw. The canvas still shows
+					// whatever it showed before — the picture was painted off-screen —
+					// so there is nothing to clean up but the record.
 					drawnWidths.delete(page);
 				} finally {
 					if (drawing.get(page) === draw) drawing.delete(page);
diff --git a/src/lib/services/pdf-pages.ts b/src/lib/services/pdf-pages.ts
index e9b8c7c..10d9dc8 100644
--- a/src/lib/services/pdf-pages.ts
+++ b/src/lib/services/pdf-pages.ts
@@ -10,6 +10,12 @@ export interface PageRasterizer {
 	/** Draws a page (1-based) into `canvas` sized for `cssWidth` CSS pixels at
 	 * the device pixel ratio. Sets the canvas buffer and style sizes.
 	 *
+	 * The page is painted off-screen and handed over whole, so `canvas` keeps
+	 * whatever it was showing until the new picture is finished. Painting into
+	 * it directly means clearing it first and then filling it in over however
+	 * many frames the page takes — which reads as a flash on every redraw, and
+	 * as a strobe while a zoom slider is being dragged.
+	 *
 	 * Aborting `signal` abandons the draw — while it is still queued, or partway
 	 * through. A page of dense vector art can take seconds to paint, and renders
 	 * run one at a time, so a reader who has scrolled past one must not leave it
@@ -97,7 +103,17 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 				const width = page.getViewport({ scale: 1 }).width;
 				page.cleanup();
 				const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
-				const viewport = await renderInto(pageNumber, canvas, (cssWidth / width) * ratio, signal);
+				const offscreen = new OffscreenCanvas(1, 1);
+				const viewport = await renderInto(
+					pageNumber,
+					offscreen,
+					(cssWidth / width) * ratio,
+					signal
+				);
+				// Abandoned while it painted: the finished picture is no longer the
+				// one anybody asked for, so leave the canvas as it was.
+				signal?.throwIfAborted();
+				present(canvas, offscreen);
 				canvas.style.width = `${Math.round(viewport.width / ratio)}px`;
 				canvas.style.height = `${Math.round(viewport.height / ratio)}px`;
 			}),
@@ -115,6 +131,33 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 	};
 }
 
+/**
+ * Put a finished off-screen page onto a visible canvas in one step. A bitmap
+ * renderer takes ownership of the pixels outright; where that context is not
+ * available the pixels are copied instead, which costs a blit but still swaps
+ * the whole page at once.
+ */
+function present(canvas: HTMLCanvasElement, source: OffscreenCanvas): void {
+	const bitmap = source.transferToImageBitmap();
+	try {
+		const renderer = canvas.getContext('bitmaprenderer');
+		if (renderer) {
+			// Sized explicitly: transferring a bitmap swaps what the canvas shows
+			// without touching its width and height attributes, and those are what
+			// the page view measures its memory against.
+			canvas.width = bitmap.width;
+			canvas.height = bitmap.height;
+			renderer.transferFromImageBitmap(bitmap);
+			return;
+		}
+		canvas.width = bitmap.width;
+		canvas.height = bitmap.height;
+		canvas.getContext('2d')?.drawImage(bitmap, 0, 0);
+	} finally {
+		bitmap.close();
+	}
+}
+
 let openRenderer: { documentId: string; rasterizer: Promise<PageRasterizer | null> } | undefined;
 
 /**
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index cb2ff20..8b0cfef 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1970,12 +1970,35 @@ test('draws each original page once while the reader scrolls back and forth', as
 	);
 	expect(drawn).toBe(6);
 
-	// Zooming abandons whatever draws were in flight for the old size. The pages
-	// in view must come back at the new one — an abandoned draw that left its
-	// half-finished bitmap in place would show as a torn page here.
+	// Zooming abandons whatever draws were in flight for the old size. A page in
+	// view must never be left blank while that happens: the slider reports every
+	// percent it passes through, and clearing the pages on each one reads as a
+	// strobe.
+	await page.evaluate(() => {
+		let blank = 0;
+		let samples = 0;
+		(window as unknown as { __blank: () => number[] }).__blank = () => [blank, samples];
+		setInterval(() => {
+			for (const slot of document.querySelectorAll<HTMLElement>('.page-slot')) {
+				if (!slot.querySelector('.page-marks')) continue;
+				samples += 1;
+				const canvas = slot.querySelector<HTMLCanvasElement>('canvas');
+				if (!canvas || canvas.width <= 1) blank += 1;
+			}
+		}, 40);
+	});
 	await page.getByRole('button', { name: /Document zoom/ }).click();
-	await page.getByRole('slider', { name: 'Document zoom' }).fill('140');
+	const zoom = page.getByRole('slider', { name: 'Document zoom' });
+	for (let percent = 100; percent <= 140; percent += 4) {
+		await zoom.fill(String(percent));
+		await page.waitForTimeout(30);
+	}
 	await page.keyboard.press('Escape');
+	const [blank, samples] = await page.evaluate(() =>
+		(window as unknown as { __blank: () => number[] }).__blank()
+	);
+	expect(samples).toBeGreaterThan(0);
+	expect(blank).toBe(0);
 	await expect
 		.poll(
 			async () =>

From 8631c5360b9b07f2f78e1061180d1d659a73cdd2 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Thu, 27 Aug 2026 01:27:26 -0500
Subject: [PATCH 11/15] fix: let the drawing grow with its page, and take the
 glare off it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two things about zooming.

The canvas was pinned in pixels to the size it was last drawn at, so the
sheet and the highlights — which follow the current zoom — grew away from
the drawing and only met it again when the redraw landed. Measured across
one drag to 140%, the sheet led the drawing by up to 360px. The renderer
now reports the size it drew and leaves the canvas to its owner's layout:
the page view stretches one to fill its sheet, and the peek, which has no
layout of its own, sets the size itself. Same drag: 2px, which is the
sheet's border.

And a white page is a poor thing to hand someone reading in the dark. The
original pages now have a tone — paper as printed, dimmed, or inverted for
night — which follows the theme until the reader picks one. Toning is
applied to the whole sheet rather than the canvas, so a highlight is still
worked out against white paper the way a highlighter behaves and only then
follows the page into the dark.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPagePeek.svelte |  6 ++++-
 src/lib/components/PdfPageView.svelte | 20 ++++++++++++++-
 src/lib/icons.ts                      |  2 ++
 src/lib/services/pdf-pages.ts         | 17 +++++++++----
 src/lib/state/reader-chrome.svelte.ts | 36 +++++++++++++++++++++++++++
 src/routes/+layout.svelte             | 23 +++++++++++++++++
 tests/reader.e2e.ts                   | 25 +++++++++++++++++++
 7 files changed, 122 insertions(+), 7 deletions(-)

diff --git a/src/lib/components/PdfPagePeek.svelte b/src/lib/components/PdfPagePeek.svelte
index 7ac445f..3eb22a0 100644
--- a/src/lib/components/PdfPagePeek.svelte
+++ b/src/lib/components/PdfPagePeek.svelte
@@ -33,7 +33,11 @@
 				return;
 			}
 			try {
-				await renderer.renderPage(target, canvas!, cssWidth);
+				// The peek sizes its canvas from the drawing itself — it has no
+				// layout of its own to stretch into.
+				const size = await renderer.renderPage(target, canvas!, cssWidth);
+				canvas!.style.width = `${size.width}px`;
+				canvas!.style.height = `${size.height}px`;
 				if (token === renderToken) status = 'ready';
 			} catch {
 				if (token === renderToken) status = 'unavailable';
diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index 889a43b..c94c28d 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -5,6 +5,7 @@
 	import type { PageRect, SegmentPlacement } from '$lib/domain/pdf-layout';
 	import { openPdfRenderer } from '$lib/services/pdf-pages';
 	import { openPdfLayout } from '$lib/services/pdf-layout';
+	import { appearanceState } from '$lib/state/appearance.svelte';
 	import { readerChrome } from '$lib/state/reader-chrome.svelte';
 
 	interface Props {
@@ -79,6 +80,8 @@
 	/** The room the stack has for a page, in CSS pixels. */
 	let available = $state(0);
 
+	let tone = $derived(readerChrome.pageToneFor(appearanceState.themeSpec.dark));
+
 	/**
 	 * The width a page is drawn at. At 100% a page fits the pane, however
 	 * narrow it is — a page you have to scroll sideways to read is not a
@@ -508,7 +511,7 @@
 	});
 </script>
 
-<div class="page-stack" {@attach trackStack}>
+<div class="page-stack" data-tone={tone} {@attach trackStack}>
 	{#each sizes as size (size.page)}
 		{@const scale = pageScale(size.page)}
 		{@const placed = placements.get(size.page)}
@@ -585,6 +588,21 @@
 		box-shadow: 0 6px 20px rgba(0, 0, 0, 0.18);
 	}
 
+	/* Toning is applied to the whole sheet, marks included, so the highlights
+	   are still worked out against white paper the way a highlighter behaves
+	   and only then follow the page into the dark. */
+	[data-tone='dim'] .page-sheet {
+		filter: brightness(0.72) contrast(1.02);
+	}
+
+	/* Inverting and rotating the hue back keeps the figures' colors roughly
+	   themselves while the paper turns dark and the ink light. Not quite to
+	   black: pure black paper under white type is its own kind of glare. */
+	[data-tone='night'] .page-sheet {
+		box-shadow: none;
+		filter: invert(0.92) hue-rotate(180deg);
+	}
+
 	.page-sheet.over-passage {
 		cursor: pointer;
 	}
diff --git a/src/lib/icons.ts b/src/lib/icons.ts
index 5ea7160..e0f6b76 100644
--- a/src/lib/icons.ts
+++ b/src/lib/icons.ts
@@ -28,6 +28,7 @@ import {
 	CloudRainIcon,
 	CoffeeIcon,
 	CollapseIcon,
+	ContrastIcon,
 	CopyIcon,
 	CpuIcon,
 	DatabaseIcon,
@@ -119,6 +120,7 @@ export const Clock3 = Clock03Icon;
 export const Cloud = CloudIcon;
 export const CloudRain = CloudRainIcon;
 export const Coffee = CoffeeIcon;
+export const Contrast = ContrastIcon;
 export const Copy = CopyIcon;
 export const Cpu = CpuIcon;
 export const Database = DatabaseIcon;
diff --git a/src/lib/services/pdf-pages.ts b/src/lib/services/pdf-pages.ts
index 10d9dc8..6e3db2d 100644
--- a/src/lib/services/pdf-pages.ts
+++ b/src/lib/services/pdf-pages.ts
@@ -7,8 +7,13 @@ const MAX_PIXELS = 16 * 1024 * 1024;
 
 export interface PageRasterizer {
 	readonly pageCount: number;
-	/** Draws a page (1-based) into `canvas` sized for `cssWidth` CSS pixels at
-	 * the device pixel ratio. Sets the canvas buffer and style sizes.
+	/** Draws a page (1-based) into `canvas` at the device pixel ratio, for a
+	 * display width of `cssWidth`, and reports the CSS size the result wants to
+	 * be shown at. It does NOT set that size on the canvas: a caller whose
+	 * canvas is sized by its own layout (the page view stretches one to fill its
+	 * sheet) must be free to resize the drawing between draws, and pinning it in
+	 * pixels here left the picture at its old size while everything around it
+	 * had already grown.
 	 *
 	 * The page is painted off-screen and handed over whole, so `canvas` keeps
 	 * whatever it was showing until the new picture is finished. Painting into
@@ -25,7 +30,7 @@ export interface PageRasterizer {
 		canvas: HTMLCanvasElement,
 		cssWidth: number,
 		signal?: AbortSignal
-	): Promise<void>;
+	): Promise<{ width: number; height: number }>;
 	/** Renders a page (1-based) to an OffscreenCanvas at `scale`× the page's
 	 * natural point size — the OCR path's rasterizer. */
 	rasterize(page: number, scale: number): Promise<OffscreenCanvas>;
@@ -114,8 +119,10 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 				// one anybody asked for, so leave the canvas as it was.
 				signal?.throwIfAborted();
 				present(canvas, offscreen);
-				canvas.style.width = `${Math.round(viewport.width / ratio)}px`;
-				canvas.style.height = `${Math.round(viewport.height / ratio)}px`;
+				return {
+					width: Math.round(viewport.width / ratio),
+					height: Math.round(viewport.height / ratio)
+				};
 			}),
 		rasterize: (pageNumber, scale) =>
 			serialize(async () => {
diff --git a/src/lib/state/reader-chrome.svelte.ts b/src/lib/state/reader-chrome.svelte.ts
index 7734a4d..ba3f73f 100644
--- a/src/lib/state/reader-chrome.svelte.ts
+++ b/src/lib/state/reader-chrome.svelte.ts
@@ -11,6 +11,21 @@ export type ReaderView = 'reading' | 'page';
 
 export const READER_VIEWS: ReaderView[] = ['reading', 'page'];
 
+/**
+ * How bright the original pages are allowed to be. Paper is the page as
+ * printed; dimmed takes the glare off white paper without touching what the
+ * figures look like; night inverts it, so the paper is dark and the ink
+ * light. Unset follows the theme — a dark theme should not open a document
+ * by shining a white page at the reader.
+ */
+export type PageTone = 'paper' | 'dim' | 'night';
+
+export const PAGE_TONES: PageTone[] = ['paper', 'dim', 'night'];
+
+function isPageTone(value: unknown): value is PageTone {
+	return PAGE_TONES.includes(value as PageTone);
+}
+
 function isReaderView(value: unknown): value is ReaderView {
 	return READER_VIEWS.includes(value as ReaderView);
 }
@@ -23,6 +38,8 @@ class ReaderChromeState {
 	/** The preferred view, remembered across documents. A document with no
 	 * original pages falls back to reading without changing this. */
 	readerView = $state<ReaderView>('reading');
+	/** Undefined until the reader chooses: see `pageToneFor`. */
+	pageTone = $state<PageTone>();
 	/** The listening mode new imports start in. Per-document overrides live on
 	 * the document itself and take precedence in the reader. */
 	defaultListeningMode = $state<ListeningMode>(DEFAULT_LISTENING_MODE);
@@ -49,10 +66,29 @@ class ReaderChromeState {
 		if (isListeningMode(mode)) this.defaultListeningMode = mode;
 		const view = window.localStorage.getItem('voicebook:reader-view');
 		if (isReaderView(view)) this.readerView = view;
+		const tone = window.localStorage.getItem('voicebook:page-tone');
+		if (isPageTone(tone)) this.pageTone = tone;
 		this.assistantCaptions = window.localStorage.getItem('voicebook:assistant-captions') !== '0';
 		this.spokenChatReplies = window.localStorage.getItem('voicebook:spoken-chat-replies') !== '0';
 	}
 
+	/** The tone in force, given whether the current theme is a dark one. */
+	pageToneFor(darkTheme: boolean): PageTone {
+		return this.pageTone ?? (darkTheme ? 'dim' : 'paper');
+	}
+
+	cyclePageTone(darkTheme: boolean): void {
+		const current = this.pageToneFor(darkTheme);
+		this.setPageTone(PAGE_TONES[(PAGE_TONES.indexOf(current) + 1) % PAGE_TONES.length]);
+	}
+
+	setPageTone(tone: PageTone): void {
+		this.pageTone = tone;
+		if (typeof window !== 'undefined') {
+			window.localStorage.setItem('voicebook:page-tone', tone);
+		}
+	}
+
 	/** Steps to the next view. A cycle rather than a flip, so a third view can
 	 * join without the control changing shape. */
 	cycleReaderView(): void {
diff --git a/src/routes/+layout.svelte b/src/routes/+layout.svelte
index 955ff4d..7fac31a 100644
--- a/src/routes/+layout.svelte
+++ b/src/routes/+layout.svelte
@@ -11,6 +11,7 @@
 		PanelLeftOpen,
 		BookOpenText,
 		BrainCircuit,
+		Contrast,
 		CircleHelp,
 		Fullscreen,
 		RefreshCw,
@@ -21,6 +22,8 @@
 		FileUp,
 		Search,
 		Shrink,
+		Moon,
+		Sun,
 		Link2,
 		List,
 		Menu,
@@ -79,6 +82,8 @@
 		readerBook?.sourceKind === 'pdf' && Boolean(readerBook.sourcePath || readerBook.sourceBlob)
 	);
 	const viewLabels = { reading: 'Reading view', page: 'Original pages' } as const;
+	const toneLabels = { paper: 'Paper', dim: 'Dimmed paper', night: 'Night paper' } as const;
+	let pageTone = $derived(readerChrome.pageToneFor(appearanceState.themeSpec.dark));
 
 	let tourContext = $derived<TourContext>(
 		isReader
@@ -303,6 +308,24 @@
 						{/if}
 					</button>
 				{/if}
+				{#if originalPagesAvailable && readerChrome.readerView === 'page'}
+					<button
+						class="icon-button"
+						class:active={pageTone !== 'paper'}
+						type="button"
+						aria-label={`${toneLabels[pageTone]}. Change how bright the page is`}
+						title={`${toneLabels[pageTone]} · click to change`}
+						onclick={() => readerChrome.cyclePageTone(appearanceState.themeSpec.dark)}
+					>
+						{#if pageTone === 'night'}
+							<Icon icon={Moon} size={16} strokeWidth={1.6} />
+						{:else if pageTone === 'dim'}
+							<Icon icon={Contrast} size={16} strokeWidth={1.6} />
+						{:else}
+							<Icon icon={Sun} size={16} strokeWidth={1.6} />
+						{/if}
+					</button>
+				{/if}
 				<div class="document-zoom" role="group" aria-label="Document zoom">
 					<div class="zoom-control" bind:this={zoomRoot}>
 						<button
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index 8b0cfef..5b476a0 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1989,16 +1989,41 @@ test('draws each original page once while the reader scrolls back and forth', as
 	});
 	await page.getByRole('button', { name: /Document zoom/ }).click();
 	const zoom = page.getByRole('slider', { name: 'Document zoom' });
+	// The drawing has to grow with its sheet on every step of the drag. Pinned
+	// to the pixel size it was last drawn at, it stayed put while the sheet grew
+	// around it and then jumped when the redraw landed — with the highlights
+	// hanging in the gap, since those follow the sheet.
+	const lag: number[] = [];
 	for (let percent = 100; percent <= 140; percent += 4) {
 		await zoom.fill(String(percent));
 		await page.waitForTimeout(30);
+		lag.push(
+			await page.evaluate(() => {
+				const slot = document.querySelector('.page-slot[data-page="1"]');
+				const sheet = slot?.querySelector('.page-sheet')?.getBoundingClientRect().width ?? 0;
+				const canvas = slot?.querySelector('canvas')?.getBoundingClientRect().width ?? 0;
+				return Math.round(sheet - canvas);
+			})
+		);
 	}
+	// Only the sheet's own border sits between the two.
+	expect(Math.max(...lag)).toBeLessThanOrEqual(2);
 	await page.keyboard.press('Escape');
 	const [blank, samples] = await page.evaluate(() =>
 		(window as unknown as { __blank: () => number[] }).__blank()
 	);
 	expect(samples).toBeGreaterThan(0);
 	expect(blank).toBe(0);
+	// The page can be toned down instead of shining white paper out of a dark
+	// theme, and the control says which tone is in force.
+	const toneButton = page.getByRole('button', { name: /Change how bright/ });
+	await expect(toneButton).toHaveAccessibleName(/Dimmed paper/);
+	await toneButton.click();
+	await expect(toneButton).toHaveAccessibleName(/Night paper/);
+	await expect(page.locator('.page-stack')).toHaveAttribute('data-tone', 'night');
+	await toneButton.click();
+	await expect(page.locator('.page-stack')).toHaveAttribute('data-tone', 'paper');
+
 	await expect
 		.poll(
 			async () =>

From cba91121cb5412d8ce4999986628ab84e8a3e139 Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Thu, 27 Aug 2026 01:35:23 -0500
Subject: [PATCH 12/15] refactor: dim the original pages from the theme, not
 from a control of their own

The tone picker was a second place to say something the reader had already
said. A dark theme is a statement about the light they are reading in, so
the page follows it: white paper under a light theme, dimmed under a dark
one, live as the theme changes. The preference, its storage, its header
button and the icon added for it are all gone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte | 26 +++++++++----------
 src/lib/icons.ts                      |  2 --
 src/lib/state/reader-chrome.svelte.ts | 36 ---------------------------
 src/routes/+layout.svelte             | 23 -----------------
 tests/reader.e2e.ts                   | 25 ++++++++++++-------
 5 files changed, 28 insertions(+), 84 deletions(-)

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index c94c28d..a32c7d5 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -80,7 +80,13 @@
 	/** The room the stack has for a page, in CSS pixels. */
 	let available = $state(0);
 
-	let tone = $derived(readerChrome.pageToneFor(appearanceState.themeSpec.dark));
+	/**
+	 * Paper is white, and a white page is a poor thing to hand someone who has
+	 * chosen a dark theme to read in. Under one, the page is dimmed to match —
+	 * no preference to find or set, because the reader already said which kind
+	 * of light they are reading by.
+	 */
+	let dimmed = $derived(appearanceState.themeSpec.dark);
 
 	/**
 	 * The width a page is drawn at. At 100% a page fits the pane, however
@@ -511,7 +517,7 @@
 	});
 </script>
 
-<div class="page-stack" data-tone={tone} {@attach trackStack}>
+<div class="page-stack" class:dimmed {@attach trackStack}>
 	{#each sizes as size (size.page)}
 		{@const scale = pageScale(size.page)}
 		{@const placed = placements.get(size.page)}
@@ -588,21 +594,13 @@
 		box-shadow: 0 6px 20px rgba(0, 0, 0, 0.18);
 	}
 
-	/* Toning is applied to the whole sheet, marks included, so the highlights
-	   are still worked out against white paper the way a highlighter behaves
-	   and only then follow the page into the dark. */
-	[data-tone='dim'] .page-sheet {
+	/* Dimming the whole sheet, marks included, rather than the canvas alone:
+	   this way a highlight is still worked out against white paper the way a
+	   highlighter behaves, and only then follows the page into the dark. */
+	.dimmed .page-sheet {
 		filter: brightness(0.72) contrast(1.02);
 	}
 
-	/* Inverting and rotating the hue back keeps the figures' colors roughly
-	   themselves while the paper turns dark and the ink light. Not quite to
-	   black: pure black paper under white type is its own kind of glare. */
-	[data-tone='night'] .page-sheet {
-		box-shadow: none;
-		filter: invert(0.92) hue-rotate(180deg);
-	}
-
 	.page-sheet.over-passage {
 		cursor: pointer;
 	}
diff --git a/src/lib/icons.ts b/src/lib/icons.ts
index e0f6b76..5ea7160 100644
--- a/src/lib/icons.ts
+++ b/src/lib/icons.ts
@@ -28,7 +28,6 @@ import {
 	CloudRainIcon,
 	CoffeeIcon,
 	CollapseIcon,
-	ContrastIcon,
 	CopyIcon,
 	CpuIcon,
 	DatabaseIcon,
@@ -120,7 +119,6 @@ export const Clock3 = Clock03Icon;
 export const Cloud = CloudIcon;
 export const CloudRain = CloudRainIcon;
 export const Coffee = CoffeeIcon;
-export const Contrast = ContrastIcon;
 export const Copy = CopyIcon;
 export const Cpu = CpuIcon;
 export const Database = DatabaseIcon;
diff --git a/src/lib/state/reader-chrome.svelte.ts b/src/lib/state/reader-chrome.svelte.ts
index ba3f73f..7734a4d 100644
--- a/src/lib/state/reader-chrome.svelte.ts
+++ b/src/lib/state/reader-chrome.svelte.ts
@@ -11,21 +11,6 @@ export type ReaderView = 'reading' | 'page';
 
 export const READER_VIEWS: ReaderView[] = ['reading', 'page'];
 
-/**
- * How bright the original pages are allowed to be. Paper is the page as
- * printed; dimmed takes the glare off white paper without touching what the
- * figures look like; night inverts it, so the paper is dark and the ink
- * light. Unset follows the theme — a dark theme should not open a document
- * by shining a white page at the reader.
- */
-export type PageTone = 'paper' | 'dim' | 'night';
-
-export const PAGE_TONES: PageTone[] = ['paper', 'dim', 'night'];
-
-function isPageTone(value: unknown): value is PageTone {
-	return PAGE_TONES.includes(value as PageTone);
-}
-
 function isReaderView(value: unknown): value is ReaderView {
 	return READER_VIEWS.includes(value as ReaderView);
 }
@@ -38,8 +23,6 @@ class ReaderChromeState {
 	/** The preferred view, remembered across documents. A document with no
 	 * original pages falls back to reading without changing this. */
 	readerView = $state<ReaderView>('reading');
-	/** Undefined until the reader chooses: see `pageToneFor`. */
-	pageTone = $state<PageTone>();
 	/** The listening mode new imports start in. Per-document overrides live on
 	 * the document itself and take precedence in the reader. */
 	defaultListeningMode = $state<ListeningMode>(DEFAULT_LISTENING_MODE);
@@ -66,29 +49,10 @@ class ReaderChromeState {
 		if (isListeningMode(mode)) this.defaultListeningMode = mode;
 		const view = window.localStorage.getItem('voicebook:reader-view');
 		if (isReaderView(view)) this.readerView = view;
-		const tone = window.localStorage.getItem('voicebook:page-tone');
-		if (isPageTone(tone)) this.pageTone = tone;
 		this.assistantCaptions = window.localStorage.getItem('voicebook:assistant-captions') !== '0';
 		this.spokenChatReplies = window.localStorage.getItem('voicebook:spoken-chat-replies') !== '0';
 	}
 
-	/** The tone in force, given whether the current theme is a dark one. */
-	pageToneFor(darkTheme: boolean): PageTone {
-		return this.pageTone ?? (darkTheme ? 'dim' : 'paper');
-	}
-
-	cyclePageTone(darkTheme: boolean): void {
-		const current = this.pageToneFor(darkTheme);
-		this.setPageTone(PAGE_TONES[(PAGE_TONES.indexOf(current) + 1) % PAGE_TONES.length]);
-	}
-
-	setPageTone(tone: PageTone): void {
-		this.pageTone = tone;
-		if (typeof window !== 'undefined') {
-			window.localStorage.setItem('voicebook:page-tone', tone);
-		}
-	}
-
 	/** Steps to the next view. A cycle rather than a flip, so a third view can
 	 * join without the control changing shape. */
 	cycleReaderView(): void {
diff --git a/src/routes/+layout.svelte b/src/routes/+layout.svelte
index 7fac31a..955ff4d 100644
--- a/src/routes/+layout.svelte
+++ b/src/routes/+layout.svelte
@@ -11,7 +11,6 @@
 		PanelLeftOpen,
 		BookOpenText,
 		BrainCircuit,
-		Contrast,
 		CircleHelp,
 		Fullscreen,
 		RefreshCw,
@@ -22,8 +21,6 @@
 		FileUp,
 		Search,
 		Shrink,
-		Moon,
-		Sun,
 		Link2,
 		List,
 		Menu,
@@ -82,8 +79,6 @@
 		readerBook?.sourceKind === 'pdf' && Boolean(readerBook.sourcePath || readerBook.sourceBlob)
 	);
 	const viewLabels = { reading: 'Reading view', page: 'Original pages' } as const;
-	const toneLabels = { paper: 'Paper', dim: 'Dimmed paper', night: 'Night paper' } as const;
-	let pageTone = $derived(readerChrome.pageToneFor(appearanceState.themeSpec.dark));
 
 	let tourContext = $derived<TourContext>(
 		isReader
@@ -308,24 +303,6 @@
 						{/if}
 					</button>
 				{/if}
-				{#if originalPagesAvailable && readerChrome.readerView === 'page'}
-					<button
-						class="icon-button"
-						class:active={pageTone !== 'paper'}
-						type="button"
-						aria-label={`${toneLabels[pageTone]}. Change how bright the page is`}
-						title={`${toneLabels[pageTone]} · click to change`}
-						onclick={() => readerChrome.cyclePageTone(appearanceState.themeSpec.dark)}
-					>
-						{#if pageTone === 'night'}
-							<Icon icon={Moon} size={16} strokeWidth={1.6} />
-						{:else if pageTone === 'dim'}
-							<Icon icon={Contrast} size={16} strokeWidth={1.6} />
-						{:else}
-							<Icon icon={Sun} size={16} strokeWidth={1.6} />
-						{/if}
-					</button>
-				{/if}
 				<div class="document-zoom" role="group" aria-label="Document zoom">
 					<div class="zoom-control" bind:this={zoomRoot}>
 						<button
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index 5b476a0..6bc64b2 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1894,6 +1894,10 @@ test('reads a PDF as its own pages, with the spoken passage painted on', async (
 	await expect(page.locator('.reading-canvas')).toBeVisible();
 });
 
+/** Enough clicks of the header's theme button to reach any theme from any
+ * other — it steps through them one at a time. */
+const THEME_COUNT = 12;
+
 test('draws each original page once while the reader scrolls back and forth', async ({ page }) => {
 	await openReadyLibrary(page);
 	const pdf = await PDFDocument.create();
@@ -2014,15 +2018,18 @@ test('draws each original page once while the reader scrolls back and forth', as
 	);
 	expect(samples).toBeGreaterThan(0);
 	expect(blank).toBe(0);
-	// The page can be toned down instead of shining white paper out of a dark
-	// theme, and the control says which tone is in force.
-	const toneButton = page.getByRole('button', { name: /Change how bright/ });
-	await expect(toneButton).toHaveAccessibleName(/Dimmed paper/);
-	await toneButton.click();
-	await expect(toneButton).toHaveAccessibleName(/Night paper/);
-	await expect(page.locator('.page-stack')).toHaveAttribute('data-tone', 'night');
-	await toneButton.click();
-	await expect(page.locator('.page-stack')).toHaveAttribute('data-tone', 'paper');
+	// White paper is dimmed under a dark theme and left alone under a light one,
+	// following the theme the reader already chose rather than a control of its
+	// own.
+	const stack = page.locator('.page-stack');
+	await expect(stack).toHaveClass(/\bdimmed\b/);
+	const theme = page.getByRole('button', { name: /Switch to .* theme/ });
+	for (let click = 0; click < THEME_COUNT; click += 1) {
+		if ((await theme.getAttribute('aria-label'))?.includes('Theme: Sunny')) break;
+		await theme.click();
+	}
+	await expect(theme).toHaveAccessibleName(/Theme: Sunny/);
+	await expect(stack).not.toHaveClass(/\bdimmed\b/);
 
 	await expect
 		.poll(

From ec87450f8f3b403e823047001d7bb66ac470d1fa Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Thu, 27 Aug 2026 01:44:15 -0500
Subject: [PATCH 13/15] feat: turn the paper dark under a dark theme, sparing
 the photographs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Dimming only made a white page a grey page. Under a dark theme the page is
now inverted where it is drawn, with the hue rotated back so red warning
text stays red and a green curve on a plot stays green rather than turning
magenta.

What inverting ruins is pictures — a rendered figure or a photograph comes
out as a negative. Those are drawn as image objects, and the page's
operator list says exactly where each one lands, so they are put back
afterwards untouched. Line art, rules and type are not images and take the
inversion, which is what makes the page read as dark rather than merely
inverted. A page that is already dark is left alone.

Highlights blend by screen rather than multiply on a dark page, or they
would have nothing to darken.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte |  51 ++++---
 src/lib/services/pdf-pages.ts         | 194 +++++++++++++++++++++++---
 tests/reader.e2e.ts                   |  10 +-
 3 files changed, 213 insertions(+), 42 deletions(-)

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index a32c7d5..7235bfb 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -60,7 +60,7 @@
 	 * memory budget care: layout never does, because the canvas is stretched to
 	 * whatever size its sheet is, so a page drawn at another zoom is briefly
 	 * soft rather than the wrong size. */
-	const drawnWidths = new SvelteMap<number, number>();
+	const drawnWidths = new SvelteMap<number, { width: number; darken: boolean }>();
 	const placements = new SvelteMap<number, Map<string, SegmentPlacement>>();
 	let hovered = $state<{ page: number; segmentId: string }>();
 
@@ -82,11 +82,11 @@
 
 	/**
 	 * Paper is white, and a white page is a poor thing to hand someone who has
-	 * chosen a dark theme to read in. Under one, the page is dimmed to match —
-	 * no preference to find or set, because the reader already said which kind
-	 * of light they are reading by.
+	 * chosen a dark theme to read in. Under one the page is turned dark at the
+	 * point it is drawn — no preference to find or set, because the reader
+	 * already said which kind of light they are reading by.
 	 */
-	let dimmed = $derived(appearanceState.themeSpec.dark);
+	let darken = $derived(appearanceState.themeSpec.dark);
 
 	/**
 	 * The width a page is drawn at. At 100% a page fits the pane, however
@@ -241,7 +241,10 @@
 	 * restart the effect that started the draw. Every write here is paired with
 	 * a reactive one (`drawnWidths`) when the draw actually lands. */
 	// eslint-disable-next-line svelte/prefer-svelte-reactivity
-	const drawing = new Map<number, { width: number; controller: AbortController }>();
+	const drawing = new Map<
+		number,
+		{ width: number; darken: boolean; controller: AbortController }
+	>();
 
 	function drawnPixels(page: number): number {
 		const canvas = canvases.get(page);
@@ -264,13 +267,14 @@
 	 */
 	$effect(() => {
 		const width = drawWidth;
+		const dark = darken;
 		const pages = new Set(live);
 		if (!width) return;
 
 		// Abandon draws nobody is waiting for any more: the reader has scrolled
 		// past the page, or has zoomed, which makes the size being drawn wrong.
 		for (const [page, draw] of drawing) {
-			if (!pages.has(page) || draw.width !== width) draw.controller.abort();
+			if (!pages.has(page) || draw.width !== width || draw.darken !== dark) draw.controller.abort();
 		}
 
 		// Release bitmaps once they add up to more than the budget, furthest from
@@ -311,12 +315,18 @@
 				const canvas = canvases.get(page);
 				// Already drawn at this size, or already being drawn: queueing it
 				// again would only make the reader wait behind their own request.
-				if (!canvas || drawing.has(page) || drawnWidths.get(page) === width) continue;
-				const draw = { width, controller: new AbortController() };
+				const drawn = drawnWidths.get(page);
+				if (!canvas || drawing.has(page) || (drawn?.width === width && drawn.darken === darken)) {
+					continue;
+				}
+				const draw = { width, darken: dark, controller: new AbortController() };
 				drawing.set(page, draw);
 				try {
-					await renderer.renderPage(page, canvas, width, draw.controller.signal);
-					drawnWidths.set(page, width);
+					await renderer.renderPage(page, canvas, width, {
+						signal: draw.controller.signal,
+						darken
+					});
+					drawnWidths.set(page, { width, darken });
 				} catch {
 					// Abandoned, or a page that will not draw. The canvas still shows
 					// whatever it showed before — the picture was painted off-screen —
@@ -517,7 +527,7 @@
 	});
 </script>
 
-<div class="page-stack" class:dimmed {@attach trackStack}>
+<div class="page-stack" class:darkened={darken} {@attach trackStack}>
 	{#each sizes as size (size.page)}
 		{@const scale = pageScale(size.page)}
 		{@const placed = placements.get(size.page)}
@@ -594,11 +604,18 @@
 		box-shadow: 0 6px 20px rgba(0, 0, 0, 0.18);
 	}
 
-	/* Dimming the whole sheet, marks included, rather than the canvas alone:
-	   this way a highlight is still worked out against white paper the way a
-	   highlighter behaves, and only then follows the page into the dark. */
-	.dimmed .page-sheet {
-		filter: brightness(0.72) contrast(1.02);
+	/* The page arrives already dark from the renderer, so the sheet only has to
+	   stop being a white rectangle behind it while it draws, and drop the
+	   drop-shadow that belonged to paper. */
+	.darkened .page-sheet {
+		background: #131313;
+		box-shadow: none;
+	}
+
+	/* Highlights are painted over ink that is now light on dark, so they have to
+	   lighten rather than darken to show at all. */
+	.darkened .page-marks {
+		mix-blend-mode: screen;
 	}
 
 	.page-sheet.over-passage {
diff --git a/src/lib/services/pdf-pages.ts b/src/lib/services/pdf-pages.ts
index 6e3db2d..ca20b4e 100644
--- a/src/lib/services/pdf-pages.ts
+++ b/src/lib/services/pdf-pages.ts
@@ -29,7 +29,7 @@ export interface PageRasterizer {
 		page: number,
 		canvas: HTMLCanvasElement,
 		cssWidth: number,
-		signal?: AbortSignal
+		options?: { signal?: AbortSignal; darken?: boolean }
 	): Promise<{ width: number; height: number }>;
 	/** Renders a page (1-based) to an OffscreenCanvas at `scale`× the page's
 	 * natural point size — the OCR path's rasterizer. */
@@ -67,6 +67,23 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 		return result;
 	};
 
+	type Page = Awaited<ReturnType<typeof pdf.getPage>>;
+	const renderPageInto = async (
+		page: Page,
+		canvas: OffscreenCanvas,
+		viewport: ReturnType<Page['getViewport']>,
+		signal?: AbortSignal
+	) => {
+		const task = page.render({ canvas: canvas as unknown as HTMLCanvasElement, viewport });
+		const abort = () => task.cancel();
+		signal?.addEventListener('abort', abort, { once: true });
+		try {
+			await task.promise;
+		} finally {
+			signal?.removeEventListener('abort', abort);
+		}
+	};
+
 	const renderInto = async (
 		pageNumber: number,
 		canvas: HTMLCanvasElement | OffscreenCanvas,
@@ -101,28 +118,34 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 
 	return {
 		pageCount: pdf.numPages,
-		renderPage: (pageNumber, canvas, cssWidth, signal) =>
+		renderPage: (pageNumber, canvas, cssWidth, options = {}) =>
 			serialize(async () => {
+				const { signal, darken } = options;
 				signal?.throwIfAborted();
 				const page = await pdf.getPage(pageNumber);
-				const width = page.getViewport({ scale: 1 }).width;
-				page.cleanup();
-				const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
-				const offscreen = new OffscreenCanvas(1, 1);
-				const viewport = await renderInto(
-					pageNumber,
-					offscreen,
-					(cssWidth / width) * ratio,
-					signal
-				);
-				// Abandoned while it painted: the finished picture is no longer the
-				// one anybody asked for, so leave the canvas as it was.
-				signal?.throwIfAborted();
-				present(canvas, offscreen);
-				return {
-					width: Math.round(viewport.width / ratio),
-					height: Math.round(viewport.height / ratio)
-				};
+				try {
+					const base = page.getViewport({ scale: 1 });
+					const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
+					const viewport = page.getViewport({
+						scale: clampedScale(base.width, base.height, (cssWidth / base.width) * ratio)
+					});
+					const offscreen = new OffscreenCanvas(
+						Math.floor(viewport.width),
+						Math.floor(viewport.height)
+					);
+					await renderPageInto(page, offscreen, viewport, signal);
+					// Abandoned while it painted: the finished picture is no longer
+					// the one anybody asked for, so leave the canvas as it was.
+					signal?.throwIfAborted();
+					const shown = darken ? await darkened(pdfjs, page, offscreen, viewport) : offscreen;
+					present(canvas, shown);
+					return {
+						width: Math.round(viewport.width / ratio),
+						height: Math.round(viewport.height / ratio)
+					};
+				} finally {
+					page.cleanup();
+				}
 			}),
 		rasterize: (pageNumber, scale) =>
 			serialize(async () => {
@@ -138,6 +161,137 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 	};
 }
 
+/**
+ * Turning a printed page into a dark one.
+ *
+ * Dimming a white page only makes it a grey page; what a dark theme wants is
+ * paper that is actually dark with light ink on it. Inverting does that, and
+ * rotating the hue back through 180° keeps the colours roughly themselves, so
+ * red warning text stays red and a green curve on a plot stays green rather
+ * than turning magenta.
+ *
+ * What inverting ruins is photographs — a portrait or a rendered figure comes
+ * out as a negative. Those are drawn as image objects, and the page's operator
+ * list says exactly where each one lands, so they are put back afterwards
+ * untouched. Line art, rules and type are not images and take the inversion,
+ * which is what makes the page read as dark rather than merely inverted.
+ *
+ * A page that is already dark (a slide, a plate) is left alone: it has nothing
+ * to gain and everything to lose.
+ */
+async function darkened(
+	pdfjs: typeof import('pdfjs-dist'),
+	page: { getOperatorList: () => Promise<{ fnArray: number[]; argsArray: unknown[][] }> },
+	source: OffscreenCanvas,
+	viewport: { transform: number[] }
+): Promise<OffscreenCanvas> {
+	if (!isLightPage(source)) return source;
+	const target = new OffscreenCanvas(source.width, source.height);
+	const context = target.getContext('2d');
+	if (!context) return source;
+	context.filter = 'invert(1) hue-rotate(180deg)';
+	context.drawImage(source, 0, 0);
+	context.filter = 'none';
+	for (const rect of await imageRects(pdfjs, page, viewport, source)) {
+		context.drawImage(
+			source,
+			rect.x,
+			rect.y,
+			rect.width,
+			rect.height,
+			rect.x,
+			rect.y,
+			rect.width,
+			rect.height
+		);
+	}
+	return target;
+}
+
+/** Sampled down to a thumbnail: paper is overwhelmingly the lightest thing on
+ * a printed page, so a mean this high means there is paper to invert. */
+function isLightPage(source: OffscreenCanvas): boolean {
+	const size = 24;
+	const thumbnail = new OffscreenCanvas(size, size);
+	const context = thumbnail.getContext('2d', { willReadFrequently: true });
+	if (!context) return true;
+	context.drawImage(source, 0, 0, size, size);
+	const { data } = context.getImageData(0, 0, size, size);
+	let total = 0;
+	for (let index = 0; index < data.length; index += 4) {
+		total += 0.2126 * data[index] + 0.7152 * data[index + 1] + 0.0722 * data[index + 2];
+	}
+	return total / (size * size) > 140;
+}
+
+/** [a, b, c, d, e, f] ∘ [a, b, c, d, e, f]. */
+function concat(outer: number[], inner: number[]): number[] {
+	return [
+		outer[0] * inner[0] + outer[2] * inner[1],
+		outer[1] * inner[0] + outer[3] * inner[1],
+		outer[0] * inner[2] + outer[2] * inner[3],
+		outer[1] * inner[2] + outer[3] * inner[3],
+		outer[0] * inner[4] + outer[2] * inner[5] + outer[4],
+		outer[1] * inner[4] + outer[3] * inner[5] + outer[5]
+	];
+}
+
+function apply(x: number, y: number, matrix: number[]): [number, number] {
+	return [matrix[0] * x + matrix[2] * y + matrix[4], matrix[1] * x + matrix[3] * y + matrix[5]];
+}
+
+/** Where each image object on the page landed, in canvas pixels. Images are
+ * drawn into the unit square, so the current transform is the placement; the
+ * operator list has to be walked with a transform stack to know what it was. */
+async function imageRects(
+	pdfjs: typeof import('pdfjs-dist'),
+	page: { getOperatorList: () => Promise<{ fnArray: number[]; argsArray: unknown[][] }> },
+	viewport: { transform: number[] },
+	source: OffscreenCanvas
+): Promise<Array<{ x: number; y: number; width: number; height: number }>> {
+	const { OPS } = pdfjs;
+	const paints = new Set([
+		OPS.paintImageXObject,
+		OPS.paintImageXObjectRepeat,
+		OPS.paintInlineImageXObject,
+		OPS.paintImageMaskXObject
+	]);
+	let operators: { fnArray: number[]; argsArray: unknown[][] };
+	try {
+		operators = await page.getOperatorList();
+	} catch {
+		return [];
+	}
+	const rects: Array<{ x: number; y: number; width: number; height: number }> = [];
+	const stack: number[][] = [];
+	let transform = viewport.transform;
+	for (let index = 0; index < operators.fnArray.length; index += 1) {
+		const operator = operators.fnArray[index];
+		if (operator === OPS.save) stack.push(transform);
+		else if (operator === OPS.restore) transform = stack.pop() ?? transform;
+		else if (operator === OPS.transform) {
+			transform = concat(transform, operators.argsArray[index] as number[]);
+		} else if (paints.has(operator)) {
+			const corners = [
+				[0, 0],
+				[1, 0],
+				[0, 1],
+				[1, 1]
+			].map(([x, y]) => apply(x, y, transform));
+			const left = Math.floor(Math.min(...corners.map((point) => point[0])));
+			const top = Math.floor(Math.min(...corners.map((point) => point[1])));
+			const right = Math.ceil(Math.max(...corners.map((point) => point[0])));
+			const bottom = Math.ceil(Math.max(...corners.map((point) => point[1])));
+			const x = Math.max(0, left);
+			const y = Math.max(0, top);
+			const width = Math.min(source.width, right) - x;
+			const height = Math.min(source.height, bottom) - y;
+			if (width > 1 && height > 1) rects.push({ x, y, width, height });
+		}
+	}
+	return rects;
+}
+
 /**
  * Put a finished off-screen page onto a visible canvas in one step. A bitmap
  * renderer takes ownership of the pixels outright; where that context is not
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index 6bc64b2..6d2b4f7 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -2018,18 +2018,18 @@ test('draws each original page once while the reader scrolls back and forth', as
 	);
 	expect(samples).toBeGreaterThan(0);
 	expect(blank).toBe(0);
-	// White paper is dimmed under a dark theme and left alone under a light one,
-	// following the theme the reader already chose rather than a control of its
-	// own.
+	// The paper is turned dark under a dark theme and left as printed under a
+	// light one, following the theme the reader already chose rather than a
+	// control of its own.
 	const stack = page.locator('.page-stack');
-	await expect(stack).toHaveClass(/\bdimmed\b/);
+	await expect(stack).toHaveClass(/\bdarkened\b/);
 	const theme = page.getByRole('button', { name: /Switch to .* theme/ });
 	for (let click = 0; click < THEME_COUNT; click += 1) {
 		if ((await theme.getAttribute('aria-label'))?.includes('Theme: Sunny')) break;
 		await theme.click();
 	}
 	await expect(theme).toHaveAccessibleName(/Theme: Sunny/);
-	await expect(stack).not.toHaveClass(/\bdimmed\b/);
+	await expect(stack).not.toHaveClass(/\bdarkened\b/);
 
 	await expect
 		.poll(

From c0e7326de77fb50d062dc404badf0cf42c36847b Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Thu, 27 Aug 2026 01:55:10 -0500
Subject: [PATCH 14/15] feat: print the original pages onto the reader's own
 paper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A PDF page is white with black ink on it, which is a fact about the paper
it was made for, not about the room it is being read in. The reading view
has always drawn the same document on the theme's paper in the theme's
ink; the original pages now use those very colours, read off the stack as
`--reader` and `--reader-ink-strong`, so the two views agree by
construction and switching between them is a change of typesetting rather
than of lighting.

The transform is one duotone ramp: what was white becomes the theme's
paper, what was black becomes its ink, greys carry across proportionally.
Under Sunny that is a barely visible warming; under Cocoa the page is warm
dark brown with cream type; under Midnight it is a full inversion. Same
arithmetic in all ten themes — the light and dark cases stopped being
separate code and became the endpoints of the ramp.

Colour is left alone, because remapping it would be recolouring the
author's work rather than the paper under it: red warning text stays red,
a green curve on a plot stays green. The line between paper-and-ink and
colour is chroma, crossed gradually so a coloured glyph's soft edge does
not fringe. Photographs and rendered figures are lifted out and put back
whole, as before.

41ms for a retina page, against a render that costs several hundred.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/lib/components/PdfPageView.svelte |  53 ++++++++----
 src/lib/domain/page-tone.spec.ts      | 105 +++++++++++++++++++++++
 src/lib/domain/page-tone.ts           | 119 ++++++++++++++++++++++++++
 src/lib/services/pdf-pages.ts         |  78 ++++++++---------
 tests/reader.e2e.ts                   |  26 ++++++
 vite.config.ts                        |   1 +
 6 files changed, 321 insertions(+), 61 deletions(-)
 create mode 100644 src/lib/domain/page-tone.spec.ts
 create mode 100644 src/lib/domain/page-tone.ts

diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index 7235bfb..64375d7 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -5,6 +5,7 @@
 	import type { PageRect, SegmentPlacement } from '$lib/domain/pdf-layout';
 	import { openPdfRenderer } from '$lib/services/pdf-pages';
 	import { openPdfLayout } from '$lib/services/pdf-layout';
+	import { parseColor, type Rgb } from '$lib/domain/page-tone';
 	import { appearanceState } from '$lib/state/appearance.svelte';
 	import { readerChrome } from '$lib/state/reader-chrome.svelte';
 
@@ -60,7 +61,10 @@
 	 * memory budget care: layout never does, because the canvas is stretched to
 	 * whatever size its sheet is, so a page drawn at another zoom is briefly
 	 * soft rather than the wrong size. */
-	const drawnWidths = new SvelteMap<number, { width: number; darken: boolean }>();
+	const drawnWidths = new SvelteMap<
+		number,
+		{ width: number; tone: { paper: Rgb; ink: Rgb } | undefined }
+	>();
 	const placements = new SvelteMap<number, Map<string, SegmentPlacement>>();
 	let hovered = $state<{ page: number; segmentId: string }>();
 
@@ -81,12 +85,22 @@
 	let available = $state(0);
 
 	/**
-	 * Paper is white, and a white page is a poor thing to hand someone who has
-	 * chosen a dark theme to read in. Under one the page is turned dark at the
-	 * point it is drawn — no preference to find or set, because the reader
-	 * already said which kind of light they are reading by.
+	 * The paper and ink the reading view uses for this theme, read off the
+	 * stack itself so the two views agree by construction rather than by a
+	 * table someone has to remember to update. The page is printed onto these,
+	 * which under a light theme is a barely visible warming and under a dark
+	 * one is a full inversion — the same arithmetic either way.
 	 */
-	let darken = $derived(appearanceState.themeSpec.dark);
+	let tone = $derived.by((): { paper: Rgb; ink: Rgb } | undefined => {
+		// The theme is the dependency; the element is only where its value is
+		// legible, since these are CSS variables rather than state.
+		void appearanceState.theme;
+		if (!scroller) return undefined;
+		const style = getComputedStyle(scroller);
+		const paper = parseColor(style.getPropertyValue('--reader'));
+		const ink = parseColor(style.getPropertyValue('--reader-ink-strong'));
+		return paper && ink ? { paper, ink } : undefined;
+	});
 
 	/**
 	 * The width a page is drawn at. At 100% a page fits the pane, however
@@ -243,7 +257,7 @@
 	// eslint-disable-next-line svelte/prefer-svelte-reactivity
 	const drawing = new Map<
 		number,
-		{ width: number; darken: boolean; controller: AbortController }
+		{ width: number; tone: { paper: Rgb; ink: Rgb } | undefined; controller: AbortController }
 	>();
 
 	function drawnPixels(page: number): number {
@@ -267,14 +281,15 @@
 	 */
 	$effect(() => {
 		const width = drawWidth;
-		const dark = darken;
+		const toneNow = tone;
 		const pages = new Set(live);
 		if (!width) return;
 
 		// Abandon draws nobody is waiting for any more: the reader has scrolled
 		// past the page, or has zoomed, which makes the size being drawn wrong.
 		for (const [page, draw] of drawing) {
-			if (!pages.has(page) || draw.width !== width || draw.darken !== dark) draw.controller.abort();
+			if (!pages.has(page) || draw.width !== width || draw.tone !== toneNow)
+				draw.controller.abort();
 		}
 
 		// Release bitmaps once they add up to more than the budget, furthest from
@@ -316,17 +331,17 @@
 				// Already drawn at this size, or already being drawn: queueing it
 				// again would only make the reader wait behind their own request.
 				const drawn = drawnWidths.get(page);
-				if (!canvas || drawing.has(page) || (drawn?.width === width && drawn.darken === darken)) {
+				if (!canvas || drawing.has(page) || (drawn?.width === width && drawn.tone === toneNow)) {
 					continue;
 				}
-				const draw = { width, darken: dark, controller: new AbortController() };
+				const draw = { width, tone: toneNow, controller: new AbortController() };
 				drawing.set(page, draw);
 				try {
 					await renderer.renderPage(page, canvas, width, {
 						signal: draw.controller.signal,
-						darken
+						tone: toneNow
 					});
-					drawnWidths.set(page, { width, darken });
+					drawnWidths.set(page, { width, tone: toneNow });
 				} catch {
 					// Abandoned, or a page that will not draw. The canvas still shows
 					// whatever it showed before — the picture was painted off-screen —
@@ -527,7 +542,7 @@
 	});
 </script>
 
-<div class="page-stack" class:darkened={darken} {@attach trackStack}>
+<div class="page-stack" class:darkened={appearanceState.themeSpec.dark} {@attach trackStack}>
 	{#each sizes as size (size.page)}
 		{@const scale = pageScale(size.page)}
 		{@const placed = placements.get(size.page)}
@@ -600,15 +615,15 @@
 		position: relative;
 		border: 1px solid var(--line);
 		border-radius: 3px;
-		background: white;
+		/* The page arrives already printed on the theme's paper, so the sheet
+		   shows that colour behind it while it draws rather than flashing a
+		   white rectangle first. */
+		background: var(--reader);
 		box-shadow: 0 6px 20px rgba(0, 0, 0, 0.18);
 	}
 
-	/* The page arrives already dark from the renderer, so the sheet only has to
-	   stop being a white rectangle behind it while it draws, and drop the
-	   drop-shadow that belonged to paper. */
+	/* The drop-shadow belonged to white paper on a light ground. */
 	.darkened .page-sheet {
-		background: #131313;
 		box-shadow: none;
 	}
 
diff --git a/src/lib/domain/page-tone.spec.ts b/src/lib/domain/page-tone.spec.ts
new file mode 100644
index 0000000..8f39603
--- /dev/null
+++ b/src/lib/domain/page-tone.spec.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { parseColor, toneDistance, tonePixels, type Rgb } from './page-tone';
+
+const PAPER_DARK: Rgb = [24, 25, 29];
+const INK_LIGHT: Rgb = [244, 241, 233];
+const PAPER_WARM: Rgb = [255, 250, 241];
+const INK_DARK: Rgb = [35, 31, 25];
+
+/** One pixel through the ramp, as [r, g, b]. */
+function toned(pixel: [number, number, number], paper: Rgb, ink: Rgb): number[] {
+	const data = new Uint8ClampedArray([...pixel, 255]);
+	tonePixels(data, paper, ink);
+	return [data[0], data[1], data[2]];
+}
+
+describe('parseColor', () => {
+	it('reads the forms the theme sheet uses', () => {
+		expect(parseColor('#18191d')).toEqual([24, 25, 29]);
+		expect(parseColor('#FFF')).toEqual([255, 255, 255]);
+		expect(parseColor('  rgb(12, 34, 56)  ')).toEqual([12, 34, 56]);
+		expect(parseColor('rgba(12 34 56 / 0.5)')).toEqual([12, 34, 56]);
+	});
+
+	it('refuses what it cannot read rather than guessing', () => {
+		expect(parseColor('hsl(200 20% 30%)')).toBeNull();
+		expect(parseColor('rebeccapurple')).toBeNull();
+		expect(parseColor('#12')).toBeNull();
+		expect(parseColor('rgb(1, 2)')).toBeNull();
+	});
+});
+
+describe('toneDistance', () => {
+	it('is nothing when the paper is already white under black ink', () => {
+		expect(toneDistance([255, 255, 255], [0, 0, 0])).toBeCloseTo(0);
+	});
+
+	it('is at its largest for a full inversion', () => {
+		expect(toneDistance([0, 0, 0], [255, 255, 255])).toBeCloseTo(2);
+	});
+
+	it('separates a warm light theme from a dark one', () => {
+		expect(toneDistance(PAPER_WARM, INK_DARK)).toBeLessThan(0.2);
+		expect(toneDistance(PAPER_DARK, INK_LIGHT)).toBeGreaterThan(1.5);
+	});
+});
+
+describe('tonePixels', () => {
+	it('prints white paper as the theme’s paper', () => {
+		expect(toned([255, 255, 255], PAPER_DARK, INK_LIGHT)).toEqual([...PAPER_DARK]);
+	});
+
+	it('prints black ink as the theme’s ink', () => {
+		expect(toned([0, 0, 0], PAPER_DARK, INK_LIGHT)).toEqual([...INK_LIGHT]);
+	});
+
+	it('carries a mid grey to the middle of the ramp', () => {
+		const [red] = toned([128, 128, 128], PAPER_DARK, INK_LIGHT);
+		expect(red).toBeGreaterThan(Math.min(PAPER_DARK[0], INK_LIGHT[0]));
+		expect(red).toBeLessThan(Math.max(PAPER_DARK[0], INK_LIGHT[0]));
+	});
+
+	it('keeps the greys in order, so a rule stays lighter than the type', () => {
+		const type = toned([20, 20, 20], PAPER_DARK, INK_LIGHT)[0];
+		const rule = toned([160, 160, 160], PAPER_DARK, INK_LIGHT)[0];
+		// Under a dark theme the ramp runs the other way: darker ink prints
+		// lighter, and the order has to survive intact either way.
+		expect(type).toBeGreaterThan(rule);
+	});
+
+	it('leaves the author’s colour alone', () => {
+		expect(toned([220, 30, 30], PAPER_DARK, INK_LIGHT)).toEqual([220, 30, 30]);
+		expect(toned([40, 160, 90], PAPER_WARM, INK_DARK)).toEqual([40, 160, 90]);
+	});
+
+	it('fades the remap out across the edge of a coloured glyph', () => {
+		// A pixel half way between grey and colour comes out between the two,
+		// rather than snapping to one of them and fringing the letter. The grey
+		// it is compared against is the one of the same lightness, so only the
+		// chroma differs.
+		const [red] = toned([150, 128, 128], PAPER_DARK, INK_LIGHT);
+		const fully = toned([139, 139, 139], PAPER_DARK, INK_LIGHT)[0];
+		expect(red).toBeGreaterThan(Math.min(150, fully));
+		expect(red).toBeLessThan(Math.max(150, fully));
+	});
+
+	it('barely touches a page under a paper-white theme', () => {
+		const [red, green, blue] = toned([255, 255, 255], PAPER_WARM, INK_DARK);
+		expect(Math.abs(red - 255)).toBeLessThanOrEqual(1);
+		expect(Math.abs(green - 250)).toBeLessThanOrEqual(1);
+		expect(Math.abs(blue - 241)).toBeLessThanOrEqual(1);
+	});
+
+	it('leaves alpha alone', () => {
+		const data = new Uint8ClampedArray([255, 255, 255, 137]);
+		tonePixels(data, PAPER_DARK, INK_LIGHT);
+		expect(data[3]).toBe(137);
+	});
+
+	it('walks a whole buffer, not just its first pixel', () => {
+		const data = new Uint8ClampedArray([255, 255, 255, 255, 0, 0, 0, 255]);
+		tonePixels(data, PAPER_DARK, INK_LIGHT);
+		expect([data[0], data[1], data[2]]).toEqual([...PAPER_DARK]);
+		expect([data[4], data[5], data[6]]).toEqual([...INK_LIGHT]);
+	});
+});
diff --git a/src/lib/domain/page-tone.ts b/src/lib/domain/page-tone.ts
new file mode 100644
index 0000000..adc06f4
--- /dev/null
+++ b/src/lib/domain/page-tone.ts
@@ -0,0 +1,119 @@
+/**
+ * Printing a page onto the reader's paper.
+ *
+ * A PDF page is white with black ink on it, which is a fact about the paper it
+ * was made for, not about the room it is being read in. The reading view has
+ * always drawn the same document on the theme's paper in the theme's ink; this
+ * puts the original pages on that same paper, so moving between the two views
+ * is a change of typesetting rather than a change of lighting.
+ *
+ * The transform is a duotone ramp: what was white becomes the theme's paper,
+ * what was black becomes its ink, and the greys in between are carried across
+ * proportionally. Under a light theme that is a barely visible warming; under
+ * a dark one it is a full inversion, arrived at by the same arithmetic rather
+ * than by a special case.
+ *
+ * Colour is left alone. Red warning text stays red and a green curve on a plot
+ * stays green — remapping those would be recolouring the author's work rather
+ * than the paper it sits on. The line between "paper and ink" and "colour" is
+ * chroma, crossed gradually so that the anti-aliased edge of a coloured glyph
+ * does not fringe.
+ */
+
+export type Rgb = readonly [number, number, number];
+
+/** Below this chroma a pixel is paper, ink, or a grey between them, and is
+ * remapped in full. */
+const ACHROMATIC = 10;
+/** Above this it is the author's colour and is left as it is. Between the two
+ * the remap fades out, which is what keeps glyph edges clean. */
+const CHROMATIC = 44;
+
+/**
+ * Read a CSS colour into channels. Only the forms the theme sheet actually
+ * uses need to work — hex and `rgb()` — and anything else is refused rather
+ * than guessed at, so a mistyped variable shows up as an untoned page instead
+ * of a mysteriously wrong one.
+ */
+export function parseColor(value: string): Rgb | null {
+	const text = value.trim().toLowerCase();
+	const hex = /^#([0-9a-f]{3,8})$/.exec(text);
+	if (hex) {
+		const digits = hex[1];
+		if (digits.length === 3 || digits.length === 4) {
+			const [red, green, blue] = [...digits.slice(0, 3)].map((digit) =>
+				Number.parseInt(digit + digit, 16)
+			);
+			return [red, green, blue];
+		}
+		if (digits.length === 6 || digits.length === 8) {
+			return [
+				Number.parseInt(digits.slice(0, 2), 16),
+				Number.parseInt(digits.slice(2, 4), 16),
+				Number.parseInt(digits.slice(4, 6), 16)
+			];
+		}
+		return null;
+	}
+	const rgb = /^rgba?\(([^)]+)\)$/.exec(text);
+	if (!rgb) return null;
+	const parts = rgb[1]
+		.split(/[\s,/]+/)
+		.filter(Boolean)
+		.map(Number);
+	if (parts.length < 3 || parts.slice(0, 3).some((part) => !Number.isFinite(part))) return null;
+	return [parts[0], parts[1], parts[2]];
+}
+
+/**
+ * How far a page's own colouring is from the paper it is being printed onto —
+ * 0 when the ramp would change nothing, 1 at a full inversion. Used to decide
+ * whether the pass is worth running at all.
+ */
+export function toneDistance(paper: Rgb, ink: Rgb): number {
+	const lightness = (color: Rgb) =>
+		(0.2126 * color[0] + 0.7152 * color[1] + 0.0722 * color[2]) / 255;
+	return Math.abs(1 - lightness(paper)) + lightness(ink);
+}
+
+/**
+ * Repaint one page's pixels in place.
+ *
+ * `data` is RGBA as `getImageData` gives it. Every pixel is placed on the ramp
+ * by its own lightness — the midpoint of its lightest and darkest channel,
+ * which is what keeps a mid-grey mid-way rather than dragging it toward
+ * whichever channel happens to dominate — and then mixed back toward its
+ * original colour by how chromatic it is.
+ */
+export function tonePixels(data: Uint8ClampedArray, paper: Rgb, ink: Rgb): void {
+	const span = CHROMATIC - ACHROMATIC;
+	const rampRed = paper[0] - ink[0];
+	const rampGreen = paper[1] - ink[1];
+	const rampBlue = paper[2] - ink[2];
+	for (let index = 0; index < data.length; index += 4) {
+		const red = data[index];
+		const green = data[index + 1];
+		const blue = data[index + 2];
+		const high = red > green ? (red > blue ? red : blue) : green > blue ? green : blue;
+		const low = red < green ? (red < blue ? red : blue) : green < blue ? green : blue;
+		const chroma = high - low;
+		if (chroma >= CHROMATIC) continue;
+		const lightness = (high + low) / 510;
+		const tonedRed = ink[0] + rampRed * lightness;
+		const tonedGreen = ink[1] + rampGreen * lightness;
+		const tonedBlue = ink[2] + rampBlue * lightness;
+		if (chroma <= ACHROMATIC) {
+			data[index] = tonedRed;
+			data[index + 1] = tonedGreen;
+			data[index + 2] = tonedBlue;
+			continue;
+		}
+		// Part way across: fade the remap out so a coloured glyph's soft edge
+		// does not sit in a ring of paper-coloured fringe.
+		const keep = (chroma - ACHROMATIC) / span;
+		const take = 1 - keep;
+		data[index] = red * keep + tonedRed * take;
+		data[index + 1] = green * keep + tonedGreen * take;
+		data[index + 2] = blue * keep + tonedBlue * take;
+	}
+}
diff --git a/src/lib/services/pdf-pages.ts b/src/lib/services/pdf-pages.ts
index ca20b4e..37a1183 100644
--- a/src/lib/services/pdf-pages.ts
+++ b/src/lib/services/pdf-pages.ts
@@ -1,4 +1,5 @@
 import type { NormalizedDocument } from '../domain/types';
+import { toneDistance, tonePixels, type Rgb } from '../domain/page-tone';
 import { getSource } from './repository';
 
 /** Safari caps canvases around 4096×4096 / 16M pixels; render within that. */
@@ -29,7 +30,7 @@ export interface PageRasterizer {
 		page: number,
 		canvas: HTMLCanvasElement,
 		cssWidth: number,
-		options?: { signal?: AbortSignal; darken?: boolean }
+		options?: { signal?: AbortSignal; tone?: { paper: Rgb; ink: Rgb } }
 	): Promise<{ width: number; height: number }>;
 	/** Renders a page (1-based) to an OffscreenCanvas at `scale`× the page's
 	 * natural point size — the OCR path's rasterizer. */
@@ -120,7 +121,7 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 		pageCount: pdf.numPages,
 		renderPage: (pageNumber, canvas, cssWidth, options = {}) =>
 			serialize(async () => {
-				const { signal, darken } = options;
+				const { signal, tone } = options;
 				signal?.throwIfAborted();
 				const page = await pdf.getPage(pageNumber);
 				try {
@@ -137,8 +138,8 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 					// Abandoned while it painted: the finished picture is no longer
 					// the one anybody asked for, so leave the canvas as it was.
 					signal?.throwIfAborted();
-					const shown = darken ? await darkened(pdfjs, page, offscreen, viewport) : offscreen;
-					present(canvas, shown);
+					if (tone) await printOnto(pdfjs, page, offscreen, viewport, tone);
+					present(canvas, offscreen);
 					return {
 						width: Math.round(viewport.width / ratio),
 						height: Math.round(viewport.height / ratio)
@@ -162,50 +163,43 @@ export async function createPageRasterizer(data: Uint8Array): Promise<PageRaster
 }
 
 /**
- * Turning a printed page into a dark one.
+ * Reprint a drawn page onto the reader's paper, in place.
  *
- * Dimming a white page only makes it a grey page; what a dark theme wants is
- * paper that is actually dark with light ink on it. Inverting does that, and
- * rotating the hue back through 180° keeps the colours roughly themselves, so
- * red warning text stays red and a green curve on a plot stays green rather
- * than turning magenta.
+ * The ramp itself lives in domain/page-tone.ts; what belongs here is knowing
+ * which parts of the page it may touch. Photographs and rendered figures must
+ * be left exactly as the author made them — running paper-and-ink arithmetic
+ * over a photograph produces a negative — and the page's operator list says
+ * precisely where each image object lands, so those rectangles are lifted out
+ * beforehand and put back after.
  *
- * What inverting ruins is photographs — a portrait or a rendered figure comes
- * out as a negative. Those are drawn as image objects, and the page's operator
- * list says exactly where each one lands, so they are put back afterwards
- * untouched. Line art, rules and type are not images and take the inversion,
- * which is what makes the page read as dark rather than merely inverted.
+ * Line art, rules and type are not images and do take the ramp, which is what
+ * lets a page become genuinely dark rather than merely dimmed.
  *
- * A page that is already dark (a slide, a plate) is left alone: it has nothing
- * to gain and everything to lose.
+ * A page that is already dark is left alone: the ramp reads lightness as
+ * paper, so a dark plate would come back inverted.
  */
-async function darkened(
+async function printOnto(
 	pdfjs: typeof import('pdfjs-dist'),
 	page: { getOperatorList: () => Promise<{ fnArray: number[]; argsArray: unknown[][] }> },
-	source: OffscreenCanvas,
-	viewport: { transform: number[] }
-): Promise<OffscreenCanvas> {
-	if (!isLightPage(source)) return source;
-	const target = new OffscreenCanvas(source.width, source.height);
-	const context = target.getContext('2d');
-	if (!context) return source;
-	context.filter = 'invert(1) hue-rotate(180deg)';
-	context.drawImage(source, 0, 0);
-	context.filter = 'none';
-	for (const rect of await imageRects(pdfjs, page, viewport, source)) {
-		context.drawImage(
-			source,
-			rect.x,
-			rect.y,
-			rect.width,
-			rect.height,
-			rect.x,
-			rect.y,
-			rect.width,
-			rect.height
-		);
-	}
-	return target;
+	surface: OffscreenCanvas,
+	viewport: { transform: number[] },
+	tone: { paper: Rgb; ink: Rgb }
+): Promise<void> {
+	// Under a theme whose paper is already white under black ink there is
+	// nothing to do, and a full-page pixel pass is not free.
+	if (toneDistance(tone.paper, tone.ink) < 0.06) return;
+	if (!isLightPage(surface)) return;
+	const context = surface.getContext('2d', { willReadFrequently: true });
+	if (!context) return;
+	const pictures = (await imageRects(pdfjs, page, viewport, surface)).map((rect) => ({
+		rect,
+		pixels: context.getImageData(rect.x, rect.y, rect.width, rect.height)
+	}));
+	const page_ = context.getImageData(0, 0, surface.width, surface.height);
+	tonePixels(page_.data, tone.paper, tone.ink);
+	context.putImageData(page_, 0, 0);
+	for (const picture of pictures)
+		context.putImageData(picture.pixels, picture.rect.x, picture.rect.y);
 }
 
 /** Sampled down to a thumbnail: paper is overwhelmingly the lightest thing on
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index 6d2b4f7..a843fa1 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -2023,6 +2023,32 @@ test('draws each original page once while the reader scrolls back and forth', as
 	// control of its own.
 	const stack = page.locator('.page-stack');
 	await expect(stack).toHaveClass(/\bdarkened\b/);
+	// And the paper really is the theme's paper: a pixel of margin, well away
+	// from any type, comes back as the colour the reading view uses.
+	const marginPixel = async () =>
+		page.evaluate(() => {
+			const canvas = document.querySelector<HTMLCanvasElement>('.page-slot[data-page="1"] canvas');
+			const stack = document.querySelector<HTMLElement>('.page-stack');
+			if (!canvas || !stack) return null;
+			const scratch = document.createElement('canvas');
+			scratch.width = 1;
+			scratch.height = 1;
+			scratch.getContext('2d')?.drawImage(canvas, 8, 8, 1, 1, 0, 0, 1, 1);
+			const [red, green, blue] = scratch.getContext('2d')!.getImageData(0, 0, 1, 1).data;
+			return {
+				paper: [red, green, blue],
+				theme: getComputedStyle(stack).getPropertyValue('--reader')
+			};
+		});
+	const printed = await marginPixel();
+	expect(printed).not.toBeNull();
+	const themePaper = /#(\w{2})(\w{2})(\w{2})/.exec(printed!.theme.trim());
+	expect(themePaper).not.toBeNull();
+	for (let channel = 0; channel < 3; channel += 1) {
+		expect(
+			Math.abs(printed!.paper[channel] - Number.parseInt(themePaper![channel + 1], 16))
+		).toBeLessThanOrEqual(6);
+	}
 	const theme = page.getByRole('button', { name: /Switch to .* theme/ });
 	for (let click = 0; click < THEME_COUNT; click += 1) {
 		if ((await theme.getAttribute('aria-label'))?.includes('Theme: Sunny')) break;
diff --git a/vite.config.ts b/vite.config.ts
index d02cc67..aef449b 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -77,6 +77,7 @@ export default defineConfig({
 				'src/lib/domain/importers.ts',
 				'src/lib/domain/model-catalog.ts',
 				'src/lib/domain/pages.ts',
+				'src/lib/domain/page-tone.ts',
 				'src/lib/domain/pdf-layout.ts',
 				'src/lib/domain/pdf-markdown.ts',
 				'src/lib/domain/segmenter.ts',

From 6f854c7a373bf046a70bbaf9a72eeb1c0acbcedc Mon Sep 17 00:00:00 2001
From: NeoVand <mmv@mit.edu>
Date: Thu, 27 Aug 2026 02:04:04 -0500
Subject: [PATCH 15/15] fix: give the page view a keyboard route into its own
 scroll
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The pages are pictures with nothing to tab to, so the stack that scrolls
them had no way in from a keyboard — a keyboard reader could open the view
and then not move it. It takes focus itself now, which is the case WCAG
2.1.1 asks this for, and an axe pass over the view guards it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .gitignore                            |  3 ---
 src/lib/components/PdfPageView.svelte | 19 ++++++++++++++++++-
 tests/reader.e2e.ts                   |  5 +++++
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/.gitignore b/.gitignore
index 4387109..e503f4a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,6 +44,3 @@ skills-lock.json
 # Local test fixtures (user-provided, not committed)
 test_documents/
 .probe/
-
-# Locally staged preview fixtures (never committed)
-static/attention.pdf
diff --git a/src/lib/components/PdfPageView.svelte b/src/lib/components/PdfPageView.svelte
index 64375d7..fa18c82 100644
--- a/src/lib/components/PdfPageView.svelte
+++ b/src/lib/components/PdfPageView.svelte
@@ -542,7 +542,19 @@
 	});
 </script>
 
-<div class="page-stack" class:darkened={appearanceState.themeSpec.dark} {@attach trackStack}>
+<!-- Focusable because it scrolls: the pages themselves are pictures with
+     nothing to tab to, so without this a keyboard has no way to move the
+     document at all. The lint rule is about controls; a scroll container is
+     the case WCAG 2.1.1 requires this for. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<div
+	class="page-stack"
+	class:darkened={appearanceState.themeSpec.dark}
+	role="region"
+	aria-label={`${book.title}, original pages`}
+	tabindex="0"
+	{@attach trackStack}
+>
 	{#each sizes as size (size.page)}
 		{@const scale = pageScale(size.page)}
 		{@const placed = placements.get(size.page)}
@@ -593,6 +605,11 @@
 		scroll-padding-block: calc(var(--app-header-height) + 22px) calc(var(--player-height) + 32px);
 	}
 
+	.page-stack:focus-visible {
+		outline: 2px solid var(--primary);
+		outline-offset: -4px;
+	}
+
 	.page-slot {
 		position: relative;
 		display: flex;
diff --git a/tests/reader.e2e.ts b/tests/reader.e2e.ts
index a843fa1..329ee74 100644
--- a/tests/reader.e2e.ts
+++ b/tests/reader.e2e.ts
@@ -1876,6 +1876,11 @@ test('reads a PDF as its own pages, with the spoken passage painted on', async (
 		)
 		.toBe(true);
 
+	const pageViewA11y = await new AxeBuilder({ page }).analyze();
+	expect(
+		pageViewA11y.violations.filter((item) => ['critical', 'serious'].includes(item.impact ?? ''))
+	).toEqual([]);
+
 	// The contents panel addresses a page rather than an element here, so the
 	// heading it names still moves the stack.
 	await page.getByRole('button', { name: /Open document outline/ }).click();