From e711d895ef2a9e52e3f7f68e8bda860776c0f864 Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Sun, 1 Nov 2026 02:12:22 +0600
Subject: [PATCH 01/12] feat(reader): recover media whose URL fails while a
 book is open

The reader kept an asset's drawn URL for the life of an open book. When the
library moved an adopted key to another copy (a book pruned its file, or the
library switched location after its check), or a signed link expired, the
element stayed broken until the book was reopened.

- Book.renewUrl(id, failed): drops that id's cached answer (only if it is the
  one that failed; concurrent failures share one new resolution) and resolves
  again. Implemented for bookFrom (host resolver: a new signed link), streamed
  and library books (OpenedLibraryBook.forgetUrl drops the index shard and
  refetches it with cache: no-cache), withLibraries (Library.forget), and the
  author wrapper. A resolution that threw (not "not available") is retried too.
- useAssetSrc / mediaRenewer: an element's error event renews once after a
  short backoff and swaps the src; a renewed URL that fails before it loaded is
  left (no loop); a load resets it, so an expiring link renews again later.
  Wired to page/background/openable/modal images, thumbnails, posters, video,
  audio (resuming position), <model-viewer>, and host renderers (onError).
- assetBytes (labs, PDFs) renews once on a failed fetch.
- createResolver: forget(id), and locate drops a shard whose path failed.
- tools/reader-media-recover-e2e.ts: a disk library, media adopted at two
  paths, the drawn copy deleted while the book is open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CONTRIBUTING.md                            |   1 +
 docs/guides/run-a-library-server.md        |   4 +
 packages/reader/src/ChalkReader.tsx        |  15 +-
 packages/reader/src/author/state.ts        |   2 +
 packages/reader/src/book.ts                |  59 ++++++--
 packages/reader/src/libraries.ts           |  14 ++
 packages/reader/src/library-stream.test.ts |  47 +++++-
 packages/reader/src/media-recover.test.ts  | 159 +++++++++++++++++++++
 packages/reader/src/panels/Thumbnails.tsx  |   6 +-
 packages/reader/src/present.tsx            |   5 +
 packages/reader/src/render/Embeds.tsx      |  40 ++++--
 packages/reader/src/render/Markers.tsx     |   6 +-
 packages/reader/src/render/PageView.tsx    |  10 +-
 packages/reader/src/render/assets.ts       |  94 +++++++++++-
 packages/reader/src/stream.ts              |  34 ++++-
 packages/store/src/library-book/load.ts    |  17 ++-
 packages/store/src/library.ts              |   2 +
 packages/store/src/registry-library.ts     |   7 +-
 packages/store/src/resolver.test.ts        |  16 +++
 packages/store/src/resolver.ts             |  11 ++
 tools/reader-media-recover-e2e.ts          | 131 +++++++++++++++++
 21 files changed, 615 insertions(+), 65 deletions(-)
 create mode 100644 packages/reader/src/media-recover.test.ts
 create mode 100644 tools/reader-media-recover-e2e.ts

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 23a5be3..b5559b0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,6 +51,7 @@ npx tsx tools/reader-library-e2e.mjs [url] [shots]   # libraries: gallery, uploa
 node tools/reader-stream-e2e.mjs [url] [shots]       # a streamed 60-page book: what is fetched, and when
 npx tsx tools/reader-library-book-e2e.ts <library> <token> [url] [--read-token t]   # a book published into a (test) library, opened from it
 npx tsx tools/reader-library-auth-e2e.ts [url] [--port 4923]   # signing in to a private library (a fake one in-process), refresh, sign-out
+npx tsx tools/reader-media-recover-e2e.ts <library> <token> <disk-dir>   # media adopted at two paths, one deleted while the book is open: the reader recovers (a disk test library, ADOPT_PREFIXES=books/, built showcase)
 npx tsx tools/question-current-e2e.ts <library> <token> [--read-token t]   # a corrected question reaches readers with no new links item (test library: writes)
 node tools/reader-insert-menu-e2e.mjs [url]          # author mode's right-click menu: what is added lands where you clicked
 node tools/reader-save-e2e.mjs [url]                 # author mode's Save: the filled button, Ctrl+S, onDirtyChange, the ref's save()
diff --git a/docs/guides/run-a-library-server.md b/docs/guides/run-a-library-server.md
index 0a70227..1d415c4 100644
--- a/docs/guides/run-a-library-server.md
+++ b/docs/guides/run-a-library-server.md
@@ -167,6 +167,10 @@ the asset with that path as its location. Nothing is copied.
   cache). If every copy is gone, readers get a 404 (they verify what they get, so other bytes at a path are
   refused). Adopting a path again HEADs it and reads nothing. The schema step that allows this (step 4: `locations`
   keyed by key, store and path, with `checked_at` and `missing`) runs by itself on the first start.
+  A book already open in the reader recovers too: a picture, video, audio or model whose URL fails to load is asked
+  for again once (the reader drops the index shard it held and fetches it past the browser's cache) and drawn from
+  the copy the library names now; the same goes for a signed link (`/v1/assets/{key}/link`) that expired while a
+  video played, when the host's resolver hands out links.
 - A key the library already has (uploaded, or adopted elsewhere) stays where it is; adopting it again only updates
   its title, tags and the other descriptive fields, and reads nothing.
 
diff --git a/packages/reader/src/ChalkReader.tsx b/packages/reader/src/ChalkReader.tsx
index ee224cb..390c2a0 100644
--- a/packages/reader/src/ChalkReader.tsx
+++ b/packages/reader/src/ChalkReader.tsx
@@ -12,7 +12,7 @@ import { AudioEmbed, LabFrame, ModelViewer, VideoEmbed, localLabStorage, type La
 import { Modal } from './render/Modal.js';
 import { FloatingWindow } from './render/FloatingWindow.js';
 import { aspectFor, type Box as WindowBox } from './render/windowGeometry.js';
-import { useAssetUrl } from './render/assets.js';
+import { useAssetSrc, useResume } from './render/assets.js';
 import { packOverlay, unpackOverlay, type BookPatch, type MergeReport, type PatchResult } from '@chalk-format/container';
 import type { Overlay } from '@chalk-format/model';
 import { useAnnotations } from './annotate/state.js';
@@ -887,10 +887,10 @@ function tooSmall(el: HTMLElement, lab: boolean): boolean {
 
 /** A full-size image, drawn as HTML so that it can be tapped when its author made it open (spec 1.3). */
 function OpenableImage({ book, o, label, onActivate }: { book: Book; o: Extract<LessonObject, { type: 'image' }>; label: string; onActivate?: ((el: HTMLElement) => void) | undefined }) {
-  const url = useAssetUrl(book, o.assetId);
+  const { url, onError, onLoad } = useAssetSrc(book, o.assetId);
   return (
     <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-image-open" label={label} id={o.id} {...(onActivate ? { onActivate } : {})}>
-      {url ? <img src={url} alt="" draggable={false} /> : <span className="chalk-placeholder" />}
+      {url ? <img src={url} alt="" draggable={false} onError={onError} onLoad={onLoad} /> : <span className="chalk-placeholder" />}
     </Box>
   );
 }
@@ -908,10 +908,11 @@ function SnipView({ book, pageId, renderHtmlObject }: { book: Book; pageId: stri
 
 /** Icon-mode media opened in the dialog, at a comfortable size. */
 function MediaInModal({ book, o, locale, theme, storage, onClose, fill }: { book: Book; o: LessonObject; locale: Locale; theme: 'light' | 'dark'; storage: LabStorage | null; onClose: () => void; fill?: boolean }) {
-  const url = useAssetUrl(book, o.type === 'image' ? o.assetId : o.type === 'embed' ? o.assetId : undefined);
+  const { url, onError, onLoad } = useAssetSrc(book, o.type === 'image' ? o.assetId : o.type === 'embed' ? o.assetId : undefined);
+  const resume = useResume(onError, onLoad);
   const pr = usePresenter();
   const mediaClass = fill ? 'chalk-window-media' : 'chalk-modal-media';
-  if (o.type === 'image') return url ? <img className={mediaClass} src={url} alt={pr.present(o).label ?? ''} /> : null;
+  if (o.type === 'image') return url ? <img className={mediaClass} src={url} alt={pr.present(o).label ?? ''} onError={onError} onLoad={onLoad} /> : null;
   if (o.type !== 'embed') return null;
   const big = fill ? { position: 'relative' as const, width: '100%', height: '100%' } : { position: 'relative' as const, width: '100%', aspectRatio: o.embed === 'model3d' ? '4 / 3' : '16 / 9' };
   if (isLabObject(o)) return <LabFrame book={book} o={o as LabObject} style={fill ? { position: 'relative', width: '100%', height: '100%' } : { position: 'relative', width: '100%', height: '100%', minHeight: 'min(70vh, 560px)' }} locale={locale} theme={theme} storage={storage} onStop={onClose} />;
@@ -919,8 +920,8 @@ function MediaInModal({ book, o, locale, theme, storage, onClose, fill }: { book
   const p = pr.present(o);
   // opened by a tap: the student asked, so it plays (with sound unless the author muted it)
   const R = pr.renderers.video;
-  if (o.embed === 'video' && R) return <div className={fill ? 'chalk-window-custom-media' : 'chalk-modal-custom'}>{R({ object: o, src: url ?? null, poster: null, presentation: p, where: 'popup', ...pr.env })}</div>;
-  if (o.embed === 'video') return url ? <video className={mediaClass} src={url} controls autoPlay playsInline loop={p.loop} muted={p.muted} /> : null;
+  if (o.embed === 'video' && R) return <div className={fill ? 'chalk-window-custom-media' : 'chalk-modal-custom'}>{R({ object: o, src: url ?? null, poster: null, presentation: p, where: 'popup', onError, ...pr.env })}</div>;
+  if (o.embed === 'video') return url ? <video className={mediaClass} src={url} controls autoPlay playsInline loop={p.loop} muted={p.muted} onError={resume.onError} onLoadedMetadata={resume.onLoadedMetadata} /> : null;
   if (o.embed === 'audio') return <ModalAudio book={book} o={o} locale={locale} />;
   return null;
 }
diff --git a/packages/reader/src/author/state.ts b/packages/reader/src/author/state.ts
index 102fe92..96ed8de 100644
--- a/packages/reader/src/author/state.ts
+++ b/packages/reader/src/author/state.ts
@@ -51,6 +51,8 @@ export function useAuthoring(base: Book, onChange?: (lesson: Lesson) => void, o:
       lesson,
       assetUrl: (id) => { const a = own.get(id); return a ? Promise.resolve(a.url) : base.assetUrl(id); },
       peekUrl: (id) => own.get(id)?.url ?? base.peekUrl(id),
+      // media the author added are this page's blob: URLs (nothing to renew); the rest the book renews
+      renewUrl: (id, failed) => { const a = own.get(id); return a ? Promise.resolve(a.url) : base.renewUrl ? base.renewUrl(id, failed) : base.assetUrl(id); },
       assetBytes: (id) => { const a = own.get(id); return a ? Promise.resolve({ type: a.type, bytes: a.bytes.slice().buffer as ArrayBuffer }) : base.assetBytes(id); },
     };
   }, [base, lesson, addedVersion]);
diff --git a/packages/reader/src/book.ts b/packages/reader/src/book.ts
index d5cef48..5a90398 100644
--- a/packages/reader/src/book.ts
+++ b/packages/reader/src/book.ts
@@ -18,6 +18,14 @@ export type Book = {
   assetBytes(assetId: string): Promise<{ type: string; bytes: ArrayBuffer } | null>;
   /** Already-resolved URL, or undefined while still unknown (lets renders avoid a flash). */
   peekUrl(assetId: string): string | null | undefined;
+  /**
+   * A URL drawn for an asset failed to load (`failed`), or resolving it failed (`failed` null): the book forgets that answer, and what
+   * told it where the asset is, and resolves it once more. Another element that failed on the same URL gets the same new answer (it is
+   * resolved once). The URL from the new answer on is what `assetUrl` and `peekUrl` give. A failed URL that is not the book's current one
+   * any more gets the current one; an asset whose answer was "not available" (not a failure) is not asked again. Optional: a book without
+   * it keeps its first answers.
+   */
+  renewUrl?(assetId: string, failed: string | null): Promise<string | null>;
   /** Free the blob: URLs. The book is unusable afterwards. */
   dispose(): void;
 };
@@ -41,6 +49,8 @@ export function bookFrom(lesson: Lesson, assets: AssetBundle, missingAssetIds: s
   const buffers = new Map<string, ArrayBuffer>();
   let disposed = false;
 
+  // ids whose resolution failed (the resolver threw): `renewUrl(id, null)` asks again only for these
+  const errored = new Set<string>();
   const blobUrl = (blob: Blob) => { const u = URL.createObjectURL(blob); owned.push(u); return u; };
   async function resolve(id: string): Promise<string | null> {
     const carried = assets.get(id);
@@ -50,19 +60,31 @@ export function bookFrom(lesson: Lesson, assets: AssetBundle, missingAssetIds: s
     if (r == null) return null;
     return typeof r === 'string' ? r : blobUrl(r);
   }
+  const assetUrl = (id: string): Promise<string | null> => {
+    if (disposed) return Promise.resolve(null);
+    const kept = urls.get(id);
+    if (kept) return kept;
+    errored.delete(id);
+    const u: Promise<string | null> = resolve(id).then((v) => ({ v, e: false }), () => ({ v: null, e: true })).then(({ v, e }) => {
+      // an answer renewed while this one was on its way is not overwritten by it
+      if (urls.get(id) === u) { settled.set(id, v); if (e) errored.add(id); }
+      return v;
+    });
+    urls.set(id, u);
+    return u;
+  };
+  const renewUrl = (id: string, failed: string | null): Promise<string | null> => {
+    // carried bytes (a blob: URL of this page) and a book with no resolver have nothing to renew
+    if (disposed || assets.has(id) || !resolveAsset) return assetUrl(id);
+    if (stale(urls, settled, errored, id, failed)) { urls.delete(id); settled.delete(id); }
+    return assetUrl(id);
+  };
   return {
     lesson,
     missingAssetIds,
-    assetUrl(id) {
-      if (disposed) return Promise.resolve(null);
-      let u = urls.get(id);
-      if (!u) {
-        u = resolve(id).catch(() => null).then((v) => { settled.set(id, v); return v; });
-        urls.set(id, u);
-      }
-      return u;
-    },
+    assetUrl,
     peekUrl: (id) => settled.get(id),
+    renewUrl,
     async assetBytes(id) {
       const carried = assets.get(id);
       if (carried) {
@@ -71,12 +93,25 @@ export function bookFrom(lesson: Lesson, assets: AssetBundle, missingAssetIds: s
         if (!b) { b = carried.bytes.slice().buffer as ArrayBuffer; buffers.set(id, b); }
         return { type: carried.type, bytes: b };
       }
-      const url = await this.assetUrl(id);
+      let url = await assetUrl(id);
       if (!url) return null;
-      const res = await fetch(url);
-      if (!res.ok) return null;
+      let res = await fetch(url).catch(() => null);
+      // the URL failed (it expired, the file moved): renewed once
+      if (!res?.ok) { const again = await renewUrl(id, url); if (again && again !== url) { url = again; res = await fetch(url).catch(() => null); } }
+      if (!res?.ok) return null;
       return { type: res.headers.get('content-type') ?? 'application/octet-stream', bytes: await res.arrayBuffer() };
     },
     dispose() { disposed = true; owned.forEach((u) => URL.revokeObjectURL(u)); owned.length = 0; urls.clear(); settled.clear(); buffers.clear(); },
   };
 }
+
+/**
+ * Whether a cached answer for `id` is the one that failed, so it is to be resolved again: a URL still being resolved (another element
+ * renewed it already) or a different current URL is not; nor is "not available" (null) unless its resolution failed.
+ */
+export function stale(urls: ReadonlyMap<string, Promise<string | null>>, settled: ReadonlyMap<string, string | null>, errored: ReadonlySet<string>, id: string, failed: string | null): boolean {
+  if (!urls.has(id)) return true;
+  if (!settled.has(id)) return false;
+  const now = settled.get(id);
+  return failed === null ? now === null && errored.has(id) : now === failed;
+}
diff --git a/packages/reader/src/libraries.ts b/packages/reader/src/libraries.ts
index 19dce4c..c36c66c 100644
--- a/packages/reader/src/libraries.ts
+++ b/packages/reader/src/libraries.ts
@@ -48,6 +48,20 @@ export function withLibraries(book: Book, libraries: readonly Library[], lookup:
     assetUrl: { value: async (id: string) => (await book.assetUrl(id)) ?? fromLibraries(id) },
     // what is known already: the book's URL, else a library's answer (a URL, or null for not found), else nothing yet
     peekUrl: { value: (id: string) => book.peekUrl(id) || (lookup.settled.has(id) ? lookup.settled.get(id) : undefined) },
+    renewUrl: {
+      value: async (id: string, failed: string | null) => {
+        // the book's own answer failed: the book renews it (the libraries still come after it)
+        const own = book.peekUrl(id);
+        if (own) return own === failed && book.renewUrl ? ((await book.renewUrl(id, failed)) ?? fromLibraries(id)) : own;
+        if (failed === null) return ((book.renewUrl ? await book.renewUrl(id, null) : null) ?? fromLibraries(id));
+        // a library's URL failed (the item moved): the libraries forget it and are asked again. "Not found" (null) is not a failure to retry
+        if (lookup.settled.get(id) === failed) {
+          lookup.urls.delete(id); lookup.settled.delete(id);
+          for (const lib of libraries) lib.forget?.(id);
+        }
+        return wrapped.assetUrl(id);
+      },
+    },
     assetBytes: {
       value: async (id: string) => {
         const own = await book.assetBytes(id).catch(() => null);
diff --git a/packages/reader/src/library-stream.test.ts b/packages/reader/src/library-stream.test.ts
index c683888..6f8744f 100644
--- a/packages/reader/src/library-stream.test.ts
+++ b/packages/reader/src/library-stream.test.ts
@@ -16,7 +16,7 @@ const lesson: Lesson = { id: 'lib-book', title: 'A book in a library', locale: '
 const at = (key: string) => { const h = key.slice(3); return `https://cdn.example/c1/${h.slice(0, 2)}/${h.slice(2, 4)}/${h}`; };
 
 /** A streamed book published into a fake library as the contract says (items by key, the book item last), and that library's fetch. */
-async function library(o: { token?: string; bearerStore?: boolean; verifyAlways?: boolean; tamper?: string; storeMedia?: string[]; rendition?: Uint8Array; firstStore?: object; question?: string; adopted?: boolean; adoptedStore?: object } = {}) {
+async function library(o: { token?: string; bearerStore?: boolean; verifyAlways?: boolean; tamper?: string; storeMedia?: string[]; rendition?: Uint8Array; firstStore?: object; question?: string; adopted?: boolean; adoptedStore?: object; copy?: { dir: string } } = {}) {
   const { index, files } = await publishStreamed(lesson, new Map([[pictureKey, { type: 'image/png', bytes: picture }]]));
   const items = new Map<string, { bytes: Uint8Array; type: string; tags: string[] }>();
   const put = async (bytes: Uint8Array, type: string, tags: string[] = []) => { const { key } = await assetKeyAndSha256(bytes); items.set(key, { bytes, type, tags }); return key; };
@@ -45,8 +45,8 @@ async function library(o: { token?: string; bearerStore?: boolean; verifyAlways?
       // files adopted in place (registry-api §3.1): everything but the book item, at the book's own paths, named by the index
       const shard = /^\/index\/([a-z2-7]{2})\.json$/.exec(u.pathname)?.[1];
       if (shard) {
-        asked.push(`index ${shard}`);
-        const entries = Object.fromEntries([...items].filter(([key]) => o.adopted && key !== bookKey && key.slice(3, 5) === shard).map(([key, i]) => [key.slice(3), { p: adoptedAt(key), t: i.type }]));
+        asked.push(`index ${shard}${init?.cache ? ` ${init.cache}` : ''}`);
+        const entries = Object.fromEntries([...items].filter(([key]) => o.adopted && key !== bookKey && key.slice(3, 5) === shard).map(([key, i]) => [key.slice(3), { p: adoptedAt(key, o.copy?.dir), t: i.type }]));
         return Object.keys(entries).length ? json({ v: 1, entries }) : new Response(null, { status: 404 });
       }
       const tags = u.searchParams.getAll('tag');
@@ -54,14 +54,14 @@ async function library(o: { token?: string; bearerStore?: boolean; verifyAlways?
       return json({ items: hits.map(([key, i]) => ({ key, sha256: '0'.repeat(64), type: i.type, size: i.bytes.byteLength, tags: i.tags, status: 'available', createdAt: '2026-10-30T00:00:00Z' })) });
     }
     if (o.bearerStore && (init?.headers as Record<string, string> | undefined)?.Authorization !== `Bearer ${o.token}`) return new Response(null, { status: 401 });
-    const hit = [...items].find(([key]) => (o.adopted && key !== bookKey ? adoptedAt(key) : at(key)) === u.href);
+    const hit = [...items].find(([key]) => (o.adopted && key !== bookKey ? adoptedAt(key, o.copy?.dir) : at(key)) === u.href);
     asked.push(hit ? (hit[0] === bookKey ? 'book' : hit[1].type.split('/')[1]!.replace('vnd.chalk.', '').replace('+json', '')) : u.href);
     if (hit && hit[0] === o.tamper) return new Response(enc.encode('not the picture') as unknown as BodyInit, { status: 200 });
     return hit ? new Response(hit[1].bytes as unknown as BodyInit, { status: 200, headers: { 'content-type': hit[1].type } }) : new Response(null, { status: 404 });
   }) as unknown as typeof globalThis.fetch;
   return { fetch, asked, pageKey, bookKey, put };
 }
-const adoptedAt = (key: string) => `https://cdn.example/chalk-books/demo/items/${key.slice(3)}`;
+const adoptedAt = (key: string, dir = 'demo') => `https://cdn.example/chalk-books/${dir}/items/${key.slice(3)}`;
 const settle = () => new Promise((r) => setTimeout(r, 20));
 
 describe('books in a library, in the reader', () => {
@@ -115,6 +115,43 @@ describe('books in a library, in the reader', () => {
     expect(lib.asked.filter((a) => a === 'page')).toHaveLength(20);
   });
 
+  it('a drawn URL that failed (the library moved the adopted file to another copy): renewed once, past the cached index shard', async () => {
+    const copy = { dir: 'demo' };
+    const lib = await library({ adopted: true, copy });
+    const b = await openLibraryStreamedBook({ library: 'https://lib.example/', slug: 'demo' }, { fetch: lib.fetch });
+    const first = await b.assetUrl(pictureKey);
+    expect(first).toBe(adoptedAt(pictureKey));
+    // the book pruned its file: the library names the other copy now; the shard the book holds still names the first
+    copy.dir = 'other-book';
+    expect(await b.assetUrl(pictureKey)).toBe(first);
+    lib.asked.length = 0;
+    const renewed = await b.renewUrl!(pictureKey, first);
+    expect(renewed).toBe(adoptedAt(pictureKey, 'other-book'));
+    // the shard asked again past the browser's cache, once
+    expect(lib.asked).toEqual([`index ${pictureKey.slice(3, 5)} no-cache`]);
+    expect(b.peekUrl(pictureKey)).toBe(renewed);
+    // another element that drew the old URL gets the new one, with nothing asked
+    expect(await b.renewUrl!(pictureKey, first!)).toBe(renewed);
+    expect(lib.asked).toHaveLength(1);
+    // two elements failing at once: resolved once
+    copy.dir = 'third';
+    const [x, y] = await Promise.all([b.renewUrl!(pictureKey, renewed), b.renewUrl!(pictureKey, renewed)]);
+    expect(x).toBe(adoptedAt(pictureKey, 'third'));
+    expect(y).toBe(x);
+    expect(lib.asked).toHaveLength(2);
+    b.dispose();
+  });
+
+  it('bytes of an adopted file that moved are fetched from the new copy (the index asked again once)', async () => {
+    const copy = { dir: 'demo' };
+    const lib = await library({ adopted: true, copy });
+    const b = await openLibraryStreamedBook({ library: 'https://lib.example/', slug: 'demo' }, { fetch: lib.fetch });
+    await b.assetUrl(pictureKey);
+    copy.dir = 'other-book';
+    expect(new Uint8Array((await b.assetBytes(pictureKey))!.bytes)).toEqual(picture);
+    b.dispose();
+  });
+
   it('adopted media of an indexed store that asks to be verified always are drawn from checked bytes, not a bare URL', async () => {
     const lib = await library({ adopted: true, adoptedStore: { verify: 'always' } });
     const b = await openLibraryStreamedBook({ library: 'https://lib.example/', slug: 'demo' }, { fetch: lib.fetch });
diff --git a/packages/reader/src/media-recover.test.ts b/packages/reader/src/media-recover.test.ts
new file mode 100644
index 0000000..acc6ac1
--- /dev/null
+++ b/packages/reader/src/media-recover.test.ts
@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Lesson } from '@chalk-format/model';
+import type { Library } from '@chalk-format/store';
+import { bookFrom, type Book } from './book.js';
+import { newLookup, withLibraries } from './libraries.js';
+import { mediaRenewer, RENEW_DELAY_MS } from './render/assets.js';
+
+const lesson: Lesson = { id: 'b', title: 'B', locale: 'bn', createdAt: '', updatedAt: '', snipPages: [], pages: [] };
+
+/** A host resolver handing out signed links (`/v1/assets/{key}/link`): each call a new one, as the library signs a new link each time. */
+function signer() {
+  let n = 0;
+  const resolve = vi.fn(async (id: string) => `https://lib.example/files/${id}?sig=${++n}`);
+  return { resolve };
+}
+
+describe('a book renews a URL that failed to draw', () => {
+  it("asks the host's resolver again: a new signed link replaces the expired one, for every element that drew it", async () => {
+    const s = signer();
+    const book = bookFrom(lesson, new Map(), [], s.resolve);
+    const first = await book.assetUrl('c1:pic');
+    expect(first).toMatch(/sig=1$/);
+    const renewed = await book.renewUrl!('c1:pic', first!);
+    expect(renewed).toMatch(/sig=2$/);
+    expect(book.peekUrl('c1:pic')).toBe(renewed);
+    expect(await book.assetUrl('c1:pic')).toBe(renewed);
+    // a second element that drew the expired link: the new one, not a third signature
+    expect(await book.renewUrl!('c1:pic', first!)).toBe(renewed);
+    expect(s.resolve).toHaveBeenCalledTimes(2);
+  });
+
+  it('two elements failing on the same URL at once: one new resolution', async () => {
+    const s = signer();
+    const book = bookFrom(lesson, new Map(), [], s.resolve);
+    const first = (await book.assetUrl('c1:pic'))!;
+    const [a, b] = await Promise.all([book.renewUrl!('c1:pic', first), book.renewUrl!('c1:pic', first)]);
+    expect(a).toBe(b);
+    expect(s.resolve).toHaveBeenCalledTimes(2);
+  });
+
+  it('asks again for an asset whose resolution failed, never for one that is not available', async () => {
+    let calls = 0;
+    const flaky = bookFrom(lesson, new Map(), [], async () => { if (++calls === 1) throw new Error('offline'); return 'https://lib.example/files/x'; });
+    expect(await flaky.assetUrl('c1:x')).toBeNull();
+    expect(await flaky.renewUrl!('c1:x', null)).toBe('https://lib.example/files/x');
+    let asked = 0;
+    const none = bookFrom(lesson, new Map(), [], () => { asked++; return null; });
+    expect(await none.assetUrl('c1:y')).toBeNull();
+    expect(await none.renewUrl!('c1:y', null)).toBeNull();
+    expect(asked).toBe(1);
+  });
+
+  it("hands out an asset's bytes from a renewed link when the first one has expired", async () => {
+    const s = signer();
+    const fetch = vi.spyOn(globalThis, 'fetch').mockImplementation(async (u) => (String(u).endsWith('sig=1') ? new Response('expired', { status: 403 }) : new Response(new Uint8Array([1, 2, 3]), { status: 200 })));
+    try {
+      const book = bookFrom(lesson, new Map(), [], s.resolve);
+      expect(new Uint8Array((await book.assetBytes('c1:pic'))!.bytes)).toEqual(new Uint8Array([1, 2, 3]));
+      expect(fetch).toHaveBeenCalledTimes(2);
+    } finally { fetch.mockRestore(); }
+  });
+
+  it('through the connected libraries: a URL a library gave that failed is forgotten there and asked again', async () => {
+    let dir = 'a';
+    const forget = vi.fn();
+    const lib = { id: 'l', name: 'L', kind: 'registry', writable: false, url: vi.fn(async (k: string) => `https://cdn.example/${dir}/${k}`), forget, get: async () => null } as unknown as Library;
+    const book = withLibraries(bookFrom(lesson, new Map()), [lib], newLookup());
+    const first = await book.assetUrl('c1:pic');
+    expect(first).toBe('https://cdn.example/a/c1:pic');
+    dir = 'b';
+    expect(await book.renewUrl!('c1:pic', first!)).toBe('https://cdn.example/b/c1:pic');
+    expect(forget).toHaveBeenCalledWith('c1:pic');
+    expect(book.peekUrl('c1:pic')).toBe('https://cdn.example/b/c1:pic');
+  });
+});
+
+describe('an element whose media failed to load', () => {
+  afterEach(() => { vi.useRealTimers(); });
+
+  /** A fake book whose resolver gives the URLs listed, one per call. */
+  const fakeBook = (answers: (string | null)[]) => {
+    const renewUrl = vi.fn(async () => answers.shift() ?? null);
+    return { book: { renewUrl } as unknown as Book, renewUrl };
+  };
+
+  it('the first URL 404s: after a short wait the book is asked once, and the src is swapped once', async () => {
+    vi.useFakeTimers();
+    const { book, renewUrl } = fakeBook(['https://cdn.example/b/pic']);
+    const set = vi.fn();
+    const r = mediaRenewer(book, 'c1:pic', set);
+    r.failed('https://cdn.example/a/pic');
+    r.failed('https://cdn.example/a/pic');   // the same failure reported twice (an <img> and its <source>)
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS - 1);
+    expect(renewUrl).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(renewUrl).toHaveBeenCalledTimes(1);
+    expect(renewUrl).toHaveBeenCalledWith('c1:pic', 'https://cdn.example/a/pic');
+    expect(set).toHaveBeenCalledTimes(1);
+    expect(set).toHaveBeenCalledWith('https://cdn.example/b/pic');
+  });
+
+  it('a second failure, of the renewed URL before it ever loaded, does not loop', async () => {
+    vi.useFakeTimers();
+    const { book, renewUrl } = fakeBook(['https://cdn.example/b/pic', 'https://cdn.example/c/pic']);
+    const set = vi.fn();
+    const r = mediaRenewer(book, 'c1:pic', set);
+    r.failed('https://cdn.example/a/pic');
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS);
+    r.failed('https://cdn.example/b/pic');
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS * 10);
+    expect(renewUrl).toHaveBeenCalledTimes(1);
+    expect(set).toHaveBeenCalledTimes(1);
+  });
+
+  it('a renewed URL that loaded may be renewed again later (a signed link that expires while a long video plays)', async () => {
+    vi.useFakeTimers();
+    const { book, renewUrl } = fakeBook(['https://lib.example/v?sig=2', 'https://lib.example/v?sig=3']);
+    const set = vi.fn();
+    const r = mediaRenewer(book, 'c1:video', set);
+    r.failed('https://lib.example/v?sig=1');
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS);
+    r.loaded();
+    r.failed('https://lib.example/v?sig=2');
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS);
+    expect(renewUrl).toHaveBeenCalledTimes(2);
+    expect(set.mock.calls).toEqual([['https://lib.example/v?sig=2'], ['https://lib.example/v?sig=3']]);
+  });
+
+  it('the same URL again changes nothing, and an element that went away is not updated', async () => {
+    vi.useFakeTimers();
+    const same = fakeBook(['https://cdn.example/a/pic']);
+    const set = vi.fn();
+    mediaRenewer(same.book, 'c1:pic', set).failed('https://cdn.example/a/pic');
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS);
+    expect(set).not.toHaveBeenCalled();
+    const gone = fakeBook(['https://cdn.example/b/pic']);
+    const r = mediaRenewer(gone.book, 'c1:pic', set);
+    r.failed('https://cdn.example/a/pic');
+    r.stop();
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS);
+    expect(gone.renewUrl).not.toHaveBeenCalled();
+    expect(set).not.toHaveBeenCalled();
+  });
+
+  it('with a real book: the expired link is swapped for a new one once', async () => {
+    vi.useFakeTimers();
+    const s = signer();
+    const book = bookFrom(lesson, new Map(), [], s.resolve);
+    const first = (await book.assetUrl('c1:pic'))!;
+    const set = vi.fn();
+    const r = mediaRenewer(book, 'c1:pic', set);
+    r.failed(first);
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS);
+    expect(set.mock.calls).toEqual([[expect.stringMatching(/sig=2$/)]]);
+    r.failed(set.mock.calls[0]![0] as string);
+    await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS * 5);
+    expect(s.resolve).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/packages/reader/src/panels/Thumbnails.tsx b/packages/reader/src/panels/Thumbnails.tsx
index 6506b7f..95ea563 100644
--- a/packages/reader/src/panels/Thumbnails.tsx
+++ b/packages/reader/src/panels/Thumbnails.tsx
@@ -3,7 +3,7 @@ import { getPageSize, type LessonPage } from '@chalk-format/model';
 import type { Book } from '../book.js';
 import type { Locale } from '../config.js';
 import { num, strings } from '../i18n.js';
-import { useAssetUrl } from '../render/assets.js';
+import { useAssetSrc } from '../render/assets.js';
 import { PageView, type HtmlObjectRenderer } from '../render/PageView.js';
 
 const THUMB_W = 116;
@@ -41,13 +41,13 @@ const Thumb = memo(function Thumb({ book, page, renderHtmlObject, pdfWorkerSrc }
   }, [seen]);
   const bg = page.background;
   const thumbId = bg.type === 'pdf_page' ? bg.thumbnailAssetId : undefined;
-  const url = useAssetUrl(book, seen ? thumbId : undefined);
+  const { url, onError, onLoad } = useAssetSrc(book, seen ? thumbId : undefined);
   const { width, height } = getPageSize(page);
   const scale = THUMB_W / width;
   return (
     <span ref={box} className="chalk-thumb-pic" style={{ width: THUMB_W, height: Math.round(height * scale) }}>
       {seen && (thumbId
-        ? url && <img src={url} alt="" draggable={false} />
+        ? url && <img src={url} alt="" draggable={false} onError={onError} onLoad={onLoad} />
         : <PageView book={book} page={page} scale={scale} live renderHtmlObject={renderHtmlObject} textLayer={false} pdfWorkerSrc={pdfWorkerSrc} />)}
     </span>
   );
diff --git a/packages/reader/src/present.tsx b/packages/reader/src/present.tsx
index a816d82..65e79b3 100644
--- a/packages/reader/src/present.tsx
+++ b/packages/reader/src/present.tsx
@@ -36,6 +36,11 @@ export type MediaRendererProps = {
   presentation: ResolvedPresentation;
   /** In the page (sized to the object's box) or in a dialog (sized by the dialog). */
   where: 'page' | 'popup';
+  /**
+   * Call when your player failed to load `src` (the library moved the file, a signed link expired): the reader asks for the media once
+   * more and renders you again with a new `src`. Once per failure, as for its own players.
+   */
+  onError?: () => void;
   locale: Locale;
   theme: 'light' | 'dark';
 };
diff --git a/packages/reader/src/render/Embeds.tsx b/packages/reader/src/render/Embeds.tsx
index ccfcdf6..2ff1fe3 100644
--- a/packages/reader/src/render/Embeds.tsx
+++ b/packages/reader/src/render/Embeds.tsx
@@ -7,7 +7,7 @@ import type { EmbedObject, LabObject } from '@chalk-format/model';
 import type { Book } from '../book.js';
 import type { Locale } from '../config.js';
 import { num, strings } from '../i18n.js';
-import { useAssetUrl } from './assets.js';
+import { useAssetSrc, useAssetUrl, useResume } from './assets.js';
 import { usePresenter } from '../present.js';
 import { Box, EmbedCard, type Activate } from './Markers.js';
 
@@ -48,7 +48,8 @@ export function VideoEmbed({ book, o, label, onOpen, notFound }: { book: Book; o
   const pr = usePresenter(), p = pr.present(o);
   const [playing, setPlaying] = useState(p.show === 'live');
   const { id, url } = mediaUrl(book, o);
-  const src = useAssetUrl(book, playing ? id : undefined) ?? (playing ? url : undefined);
+  const media = useAssetSrc(book, playing ? id : undefined), resume = useResume(media.onError, media.onLoad);
+  const src = media.url ?? (playing ? url : undefined);
   const poster = useAssetUrl(book, o.poster);
   const el = useRef<HTMLVideoElement>(null);
   const [tapped, setTapped] = useState(false);
@@ -56,12 +57,12 @@ export function VideoEmbed({ book, o, label, onOpen, notFound }: { book: Book; o
   usePlayWhileVisible(el, Boolean(src) && playing && p.autoplay && !tapped);
   if (!playing) return <EmbedCard book={book} o={o} label={label} notFound={notFound} onActivate={onOpen ?? (() => { setTapped(true); setPlaying(true); })} />;
   const R = pr.renderers.video;
-  if (R) return <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-video" label={p.label ?? label} id={o.id}>{R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where: 'page', ...pr.env })}</Box>;
+  if (R) return <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-video" label={p.label ?? label} id={o.id}>{R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where: 'page', onError: media.onError, ...pr.env })}</Box>;
   return (
     <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-video" label={p.label ?? label} id={o.id}>
       {/* browsers start a video by itself only without sound; a tap is the student asking, so then it plays as authored */}
       {src && <video ref={el} src={src} poster={poster ?? undefined} controls playsInline preload="metadata"
-        autoPlay={tapped} loop={p.loop} muted={p.muted || (p.autoplay && !tapped)} />}
+        autoPlay={tapped} loop={p.loop} muted={p.muted || (p.autoplay && !tapped)} onError={resume.onError} onLoadedMetadata={resume.onLoadedMetadata} />}
     </Box>
   );
 }
@@ -76,17 +77,18 @@ export function AudioEmbed({ book, o, locale }: { book: Book; o: EmbedObject; lo
   const R = pr.renderers.audio;
   // a host's own player gets the media at once; ours loads it on the first tap
   const [want, setWant] = useState(Boolean(R));
-  const src = useAssetUrl(book, want ? o.assetId : undefined) ?? (want ? o.url : undefined);
+  const media = useAssetSrc(book, want ? o.assetId : undefined), resume = useResume(media.onError, media.onLoad);
+  const src = media.url ?? (want ? o.url : undefined);
   // a tap before the media was loaded: play once it is there (once, so a later pause stays paused)
   const playWhenReady = useRef(false);
-  useEffect(() => { if (src && playWhenReady.current) { playWhenReady.current = false; void el.current?.play(); } }, [src]);
+  useEffect(() => { if (src && playWhenReady.current) { playWhenReady.current = false; void el.current?.play().catch(() => {}); } }, [src]);
   const fmt = (s: number) => num(locale, `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, '0')}`);
-  const toggle = () => { const a = el.current; if (!want || !a) { playWhenReady.current = true; setWant(true); return; } if (a.paused) void a.play(); else a.pause(); };
+  const toggle = () => { const a = el.current; if (!want || !a) { playWhenReady.current = true; setWant(true); return; } if (a.paused) void a.play().catch(() => {}); else a.pause(); };   // media that cannot be played (gone): the error event says so
   const style = { '--h': `${o.height}px` } as CSSProperties;
   const poster = useAssetUrl(book, o.poster);
   // whether it can be played at all: null is "no book or library has it"
   const avail = useAssetUrl(book, R ? undefined : o.assetId);
-  if (R) return <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-audio" label={p.label} id={o.id}>{R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where: 'page', ...pr.env })}</Box>;
+  if (R) return <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-audio" label={p.label} id={o.id}>{R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where: 'page', onError: media.onError, ...pr.env })}</Box>;
   return (
     <Box x={o.x} y={o.y} width={o.width} height={o.height} className={`chalk-audio ${avail === null && o.assetId ? 'is-missing' : ''}`} label={p.label} id={o.id}>
       {avail === null && o.assetId && <span className="chalk-card-missing">{t.notFound}</span>}
@@ -102,7 +104,8 @@ export function AudioEmbed({ book, o, locale }: { book: Book; o: EmbedObject; lo
         <audio ref={el} src={src} preload="metadata" loop={p.loop}
           onPlay={() => setState((s) => ({ ...s, playing: true }))} onPause={() => setState((s) => ({ ...s, playing: false }))}
           onTimeUpdate={(e) => { const a = e.currentTarget; setState((s) => ({ ...s, time: a.currentTime })); }}
-          onLoadedMetadata={(e) => { const a = e.currentTarget; setState((s) => ({ ...s, duration: a.duration })); }} />
+          onError={resume.onError}
+          onLoadedMetadata={(e) => { resume.onLoadedMetadata(e); const a = e.currentTarget; setState((s) => ({ ...s, duration: a.duration })); }} />
       )}
     </Box>
   );
@@ -110,18 +113,27 @@ export function AudioEmbed({ book, o, locale }: { book: Book; o: EmbedObject; lo
 
 /** A 3D model in <model-viewer>, loaded on first use: drag to turn, pinch or scroll to zoom. */
 export function ModelViewer({ book, o, style, where = 'page' }: { book: Book; o: EmbedObject; style: CSSProperties; where?: 'page' | 'popup' }) {
-  const src = useAssetUrl(book, o.assetId) ?? o.url;
+  const media = useAssetSrc(book, o.assetId);
+  const src = media.url ?? o.url;
   const poster = useAssetUrl(book, o.poster);
   const pr = usePresenter(), p = pr.present(o);
   const [loaded, setLoaded] = useState(false);
+  // <model-viewer> says a model failed or loaded with its own events (a custom element: listened to on the element)
+  const viewer = useRef<HTMLElement>(null);
+  const { onError: modelError, onLoad: modelLoad } = media;
+  useEffect(() => {
+    const v = viewer.current; if (!v) return;
+    v.addEventListener('error', modelError); v.addEventListener('load', modelLoad);
+    return () => { v.removeEventListener('error', modelError); v.removeEventListener('load', modelLoad); };
+  }, [loaded, src, modelError, modelLoad]);
   const R = pr.renderers.model3d;
   // <model-viewer> (and three.js) only loads when the reader draws the model itself
   useEffect(() => { if (R) return; let live = true; void import('@google/model-viewer').then(() => { if (live) setLoaded(true); }); return () => { live = false; }; }, [R]);
   return (
     <div className="chalk-live chalk-model" style={style} aria-label={p.label}>
-      {R && R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where, ...pr.env })}
+      {R && R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where, onError: media.onError, ...pr.env })}
       {!R && loaded && src && (
-        <model-viewer src={src} poster={poster ?? undefined} camera-controls="" touch-action="pan-y" shadow-intensity="0.7" exposure="1.05"
+        <model-viewer ref={viewer} src={src} poster={poster ?? undefined} camera-controls="" touch-action="pan-y" shadow-intensity="0.7" exposure="1.05"
           environment-image="neutral" interaction-prompt="none" {...(p.autoRotate ? { 'auto-rotate': '' } : {})} style={{ width: '100%', height: '100%', background: 'transparent' }} />
       )}
       {!R && !loaded && <span className="chalk-spinner" aria-hidden />}
@@ -142,7 +154,7 @@ export function LabFrame({ book, o, style, locale, theme, storage, onProgress, o
   const wrap = useRef<HTMLDivElement>(null), frameHost = useRef<HTMLDivElement>(null);
   const host = useRef<LabHost | null>(null);
   const [ready, setReady] = useState(false);
-  const poster = useAssetUrl(book, o.poster);
+  const { url: poster, onError: posterError, onLoad: posterLoad } = useAssetSrc(book, o.poster);
   const t = strings(locale);
   const props = useRef({ onProgress, onStop }); props.current = { onProgress, onStop };
 
@@ -201,7 +213,7 @@ export function LabFrame({ book, o, style, locale, theme, storage, onProgress, o
       <div ref={frameHost} className="chalk-lab-frame" />
       {!ready && (
         <div className="chalk-lab-wait" aria-hidden>
-          {poster && <img src={poster} alt="" />}
+          {poster && <img src={poster} alt="" onError={posterError} onLoad={posterLoad} />}
           <span className="chalk-spinner" />
         </div>
       )}
diff --git a/packages/reader/src/render/Markers.tsx b/packages/reader/src/render/Markers.tsx
index 7420d3b..524d174 100644
--- a/packages/reader/src/render/Markers.tsx
+++ b/packages/reader/src/render/Markers.tsx
@@ -2,7 +2,7 @@ import type { CSSProperties, ReactNode } from 'react';
 import { MEDIA_ICON_SIZE, SNIP_ICON_SIZE, type EmbedObject, type LessonObject } from '@chalk-format/model';
 import type { Book } from '../book.js';
 import { kindOf, usePresenter } from '../present.js';
-import { useAssetUrl } from './assets.js';
+import { useAssetSrc, useAssetUrl } from './assets.js';
 
 /** Called with the activated element, so the reader can see how big it is on screen. */
 export type Activate = (el: HTMLElement) => void;
@@ -26,7 +26,7 @@ export function Box({ x, y, width, height, className, children, label, title, on
 export function EmbedCard({ book, o, caption, onActivate, label, notFound }: { book: Book; o: EmbedObject; caption?: string | undefined; onActivate?: Activate | undefined; label?: string | undefined;
   /** The words for media no library has; given, the card checks for it. */
   notFound?: string | undefined }) {
-  const poster = useAssetUrl(book, o.poster);
+  const { url: poster, onError: posterError, onLoad: posterLoad } = useAssetSrc(book, o.poster);
   // the media itself (a lab: its file): null means no book or library has it
   const main = useAssetUrl(book, notFound ? (o.lab?.entry ?? o.assetId) : undefined);
   const missing = notFound !== undefined && main === null && Boolean(o.lab?.entry ?? o.assetId);
@@ -34,7 +34,7 @@ export function EmbedCard({ book, o, caption, onActivate, label, notFound }: { b
   const disc = Math.min(96, o.width * 0.22, o.height * 0.3);
   return (
     <Box x={o.x} y={o.y} width={o.width} height={o.height} className={`chalk-card ${missing ? 'is-missing' : ''}`} label={missing ? `${p.label ?? label ?? ''} · ${notFound}` : (p.label ?? label)} id={o.id} kind={kindOf(o)} style={pr.accent(o)} {...(onActivate && !missing ? { onActivate } : {})}>
-      {poster && <img src={poster} alt="" draggable={false} />}
+      {poster && <img src={poster} alt="" draggable={false} onError={posterError} onLoad={posterLoad} />}
       {missing && <span className="chalk-card-missing">{notFound}</span>}
       <span className="chalk-card-glyph" style={{ width: disc, height: disc }}>{pr.glyph(o, Math.min(44, o.width * 0.1, o.height * 0.14))}</span>
       {(p.label ?? caption) && <span className="chalk-card-caption">{p.label ?? caption}</span>}
diff --git a/packages/reader/src/render/PageView.tsx b/packages/reader/src/render/PageView.tsx
index 4ad8423..62c51e2 100644
--- a/packages/reader/src/render/PageView.tsx
+++ b/packages/reader/src/render/PageView.tsx
@@ -2,7 +2,7 @@ import { memo, type ReactNode } from 'react';
 import { getPageSize, type LessonObject, type LessonPage, type PageBackground } from '@chalk-format/model';
 import type { Book } from '../book.js';
 import { usePresenter, type Presenter } from '../present.js';
-import { useAssetUrl } from './assets.js';
+import { useAssetSrc } from './assets.js';
 import { inkPath } from './ink.js';
 import { TextLayer } from './TextLayer.js';
 import { renderPdfPage } from './pdf.js';
@@ -80,7 +80,7 @@ function runs(objects: readonly LessonObject[], pr: Presenter): Run[] {
 
 function Background({ book, bg, width, height, scale, pdfWorkerSrc }: { book: Book; bg: PageBackground; width: number; height: number; scale: number; pdfWorkerSrc?: string | null | undefined }) {
   const imageId = bg.type === 'image' ? bg.assetId : bg.type === 'pdf_page' ? bg.renderedImageAssetId : undefined;
-  const url = useAssetUrl(book, imageId);
+  const { url, onError, onLoad } = useAssetSrc(book, imageId);
   // a PDF page with no rendered image: draw it from the PDF, at the width it is shown (rounded up to 400 px steps)
   const pdf = bg.type === 'pdf_page' && !imageId && pdfWorkerSrc ? bg : null;
   const want = pdf ? Math.min(2400, Math.ceil((width * scale * (globalThis.devicePixelRatio || 1)) / 400) * 400) : 0;
@@ -94,7 +94,7 @@ function Background({ book, bg, width, height, scale, pdfWorkerSrc }: { book: Bo
   const color = bg.type === 'color' ? bg.color : '#fff';
   return (
     <div className="chalk-bg" style={{ width, height, background: color }}>
-      {imageId && url && <img src={url} alt="" draggable={false} width={width} height={height} decoding="async" />}
+      {imageId && url && <img src={url} alt="" draggable={false} width={width} height={height} decoding="async" onError={onError} onLoad={onLoad} />}
       {pdfUrl && <img src={pdfUrl} alt="" draggable={false} width={width} height={height} decoding="async" />}
       {bg.type === 'pdf_page' && !imageId && !pdfUrl && <div className="chalk-bg-missing">PDF</div>}
     </div>
@@ -132,8 +132,8 @@ function VectorObject({ o, book }: { o: LessonObject; book: Book }) {
 }
 
 function ImageObject({ o, book }: { o: Extract<LessonObject, { type: 'image' }>; book: Book }) {
-  const url = useAssetUrl(book, o.assetId);
-  if (url) return <image href={url} x={o.x} y={o.y} width={o.width} height={o.height} preserveAspectRatio="none" />;
+  const { url, onError, onLoad } = useAssetSrc(book, o.assetId);
+  if (url) return <image href={url} x={o.x} y={o.y} width={o.width} height={o.height} preserveAspectRatio="none" onError={onError} onLoad={onLoad} />;
   // still coming (undefined), or nowhere to be found (null): a dashed box for the latter, so it reads as missing
   return <rect x={o.x} y={o.y} width={o.width} height={o.height} className={`chalk-placeholder ${url === null ? 'is-missing' : ''}`} />;
 }
diff --git a/packages/reader/src/render/assets.ts b/packages/reader/src/render/assets.ts
index ea96307..fa23aa1 100644
--- a/packages/reader/src/render/assets.ts
+++ b/packages/reader/src/render/assets.ts
@@ -1,17 +1,97 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Book } from '../book.js';
 
+/** How long an element waits after its media failed before asking the book for the asset again (a moment for the library to settle). */
+export const RENEW_DELAY_MS = 400;
+
 /** The URL to draw an asset with: undefined while resolving, null if it is not available. */
 export function useAssetUrl(book: Book, assetId: string | undefined): string | null | undefined {
+  return useAssetSrc(book, assetId).url;
+}
+
+export type AssetSrc = {
+  /** The URL to draw the asset with: undefined while resolving, null if it is not available. */
+  url: string | null | undefined;
+  /**
+   * The element drawing `url` failed to load it (an `error` event: the library moved the file, a signed link expired). The book is asked
+   * for the asset once more after a short wait, and a new URL replaces this one. Once per failure: a renewed URL that fails before it ever
+   * loaded is not renewed again (no loop).
+   */
+  onError: () => void;
+  /** The element loaded its media: a later failure (a link that expires while a long video plays) may renew it again. */
+  onLoad: () => void;
+};
+
+/**
+ * One element's recovery from media that failed to load: `failed(url)` asks the book for the asset again after `delay`, once, and hands a
+ * new answer to `set`; `loaded()` allows the next failure to renew again. A renewed URL that fails before it ever loaded is left as it is
+ * (no loop). `stop()` cancels a renewal on its way (the element went away, or draws another asset).
+ */
+export function mediaRenewer(book: Book, assetId: string, set: (url: string | null) => void, delay = RENEW_DELAY_MS) {
+  let budget = true, live = true, timer: ReturnType<typeof setTimeout> | undefined;
+  return {
+    failed(url: string | null) {
+      if (!live || !budget || !book.renewUrl) return;
+      budget = false;
+      timer = setTimeout(() => {
+        void book.renewUrl!(assetId, url).catch(() => null).then((u) => {
+          // the same answer again: nothing changes (the element stays as it is)
+          if (live && u !== url) set(u);
+        });
+      }, delay);
+    },
+    loaded() { budget = true; },
+    stop() { live = false; clearTimeout(timer); },
+  };
+}
+
+/**
+ * The URL to draw an asset with, and the element's way to recover when it fails to load. A resolution that failed (the media could not be
+ * fetched, rather than "not available") is asked again once too.
+ */
+export function useAssetSrc(book: Book, assetId: string | undefined): AssetSrc {
   const [url, setUrl] = useState<string | null | undefined>(() => (assetId ? book.peekUrl(assetId) : null));
+  const now = useRef(url); now.current = url;
+  const renewer = useRef<ReturnType<typeof mediaRenewer> | null>(null);
+
   useEffect(() => {
     if (!assetId) { setUrl(null); return; }
-    const known = book.peekUrl(assetId);
-    if (known !== undefined) { setUrl(known); return; }
     let live = true;
-    setUrl(undefined);
-    void book.assetUrl(assetId).then((u) => { if (live) setUrl(u); });
-    return () => { live = false; };
+    const r = mediaRenewer(book, assetId, setUrl);
+    renewer.current = r;
+    const known = book.peekUrl(assetId);
+    if (known !== undefined) { setUrl(known); if (known === null) r.failed(null); }
+    else {
+      setUrl(undefined);
+      void book.assetUrl(assetId).then((u) => { if (!live) return; setUrl(u); if (u === null) r.failed(null); });
+    }
+    return () => { live = false; r.stop(); if (renewer.current === r) renewer.current = null; };
   }, [book, assetId]);
-  return url;
+
+  const onError = useCallback(() => { const u = now.current; if (u) renewer.current?.failed(u); }, []);
+  const onLoad = useCallback(() => { renewer.current?.loaded(); }, []);
+  return { url, onError, onLoad };
+}
+
+/**
+ * A video's or audio's handlers around `useAssetSrc`: on an error (a signed link that expired while it played) where it was and whether it
+ * played are kept, the URL is renewed, and the new one starts from there.
+ */
+export function useResume(onError: () => void, onLoad: () => void) {
+  const at = useRef<{ time: number; playing: boolean } | null>(null);
+  return {
+    onError: (e: { currentTarget: HTMLMediaElement }) => {
+      const m = e.currentTarget;
+      at.current = { time: m.currentTime, playing: !m.paused || m.autoplay };
+      onError();
+    },
+    onLoadedMetadata: (e: { currentTarget: HTMLMediaElement }) => {
+      onLoad();
+      const r = at.current, m = e.currentTarget;
+      if (!r) return;
+      at.current = null;
+      if (r.time > 0) m.currentTime = r.time;
+      if (r.playing) void m.play().catch(() => {});
+    },
+  };
 }
diff --git a/packages/reader/src/stream.ts b/packages/reader/src/stream.ts
index 243c74b..48fcf86 100644
--- a/packages/reader/src/stream.ts
+++ b/packages/reader/src/stream.ts
@@ -1,7 +1,7 @@
 import { parseStreamIndex, parseStreamPage, parseStreamText } from '@chalk-format/container';
 import { isImageType, resolutionKey, sniffMediaType, type Lesson, type LessonPage, type StreamIndex, type StreamPage, type StreamText } from '@chalk-format/model';
 import { openLibraryBook, type OpenedLibraryBook, type TokenSource } from '@chalk-format/store';
-import type { AssetResolver, Book } from './book.js';
+import { stale, type AssetResolver, type Book } from './book.js';
 
 /**
  * A streamed book (spec 1.4): the index first, then pages as the reader asks for them. Until its file arrives a
@@ -123,6 +123,8 @@ export async function openLibraryStreamedBook(source: LibrarySource, o: { resolv
       if (!resolutionKey(id) || lib.storeFor(type) || !lib.storesFor(type).length) return null;
       return new Blob([(await lib.fetchItem(id, { signal, type })) as BlobPart], { type });
     },
+    // a URL the library named failed to draw (the library moved an adopted key to another copy): where it is is asked again
+    forget: (id) => lib.forgetUrl(id),
     library: lib,
   }, o);
 }
@@ -143,6 +145,8 @@ type StreamFiles = {
   fallbackUrl?(id: string, signal: AbortSignal): Promise<string | Blob | null>;
   /** External media's bytes, fetched and checked by the source; undefined for an id it cannot name. */
   assetBytes?(id: string, signal: AbortSignal): Promise<ArrayBuffer | undefined>;
+  /** Forget what the source knows about where an external asset is (a URL it gave failed to load). */
+  forget?(id: string): void;
   library?: OpenedLibraryBook;
 };
 
@@ -196,6 +200,8 @@ function streamedBook(src: StreamFiles, o: { resolveAsset?: AssetResolver; fetch
 
   // assets: the book's own files by URL (cacheable), external ones through the host
   const urls = new Map<string, Promise<string | null>>(), settled = new Map<string, string | null>(), owned: string[] = [];
+  // ids whose resolution failed (a fetch, not "not available"): `renewUrl(id, null)` asks again only for these
+  const errored = new Set<string>();
   const resolveUrl = async (id: string): Promise<string | null> => {
     const p = assetPath.get(id);
     if (p) return at(p);
@@ -214,22 +220,38 @@ function streamedBook(src: StreamFiles, o: { resolveAsset?: AssetResolver; fetch
     get lesson() { return lesson; },
     missingAssetIds: [],
     assetUrl(id) {
-      let u = urls.get(id);
-      if (!u) { u = resolveUrl(id).catch(() => null).then((v) => { settled.set(id, v); return v; }); urls.set(id, u); }
+      const kept = urls.get(id);
+      if (kept) return kept;
+      errored.delete(id);
+      const u: Promise<string | null> = resolveUrl(id).then((v) => ({ v, e: false }), () => ({ v: null, e: true })).then(({ v, e }) => {
+        // an answer renewed while this one was on its way is not overwritten by it
+        if (urls.get(id) === u) { settled.set(id, v); if (e) errored.add(id); }
+        return v;
+      });
+      urls.set(id, u);
       return u;
     },
     peekUrl(id) { const p = assetPath.get(id); return p ? at(p) : settled.get(id); },
+    renewUrl(id, failed) {
+      // the book's own files have one URL each; a disposed book renews nothing
+      if (assetPath.has(id) || abort.signal.aborted) return book.assetUrl(id);
+      if (stale(urls, settled, errored, id, failed)) { urls.delete(id); settled.delete(id); src.forget?.(id); }
+      return book.assetUrl(id);
+    },
     async assetBytes(id) {
       if (src.assetBytes && !assetPath.has(id)) {
         // the source's answer is final for an id it can name: bytes that failed their key check are not fetched again unchecked
         const bytes = await src.assetBytes(id, abort.signal).catch(() => null);
         if (bytes !== undefined) return bytes && { type: assetType.get(id) ?? 'application/octet-stream', bytes };
       }
-      const url = await book.assetUrl(id);
+      let url = await book.assetUrl(id);
       if (!url) return null;
       // a blob: URL holds bytes already here (checked ones from a store, or the host's): the host's fetch may not know the scheme
-      const r = await (url.startsWith('blob:') ? globalThis.fetch(url, { signal: abort.signal }) : doFetch(url, { signal: abort.signal }));
-      if (!r.ok) return null;
+      const get = (u: string) => (u.startsWith('blob:') ? globalThis.fetch(u, { signal: abort.signal }) : doFetch(u, { signal: abort.signal })).catch((e: unknown) => { if (abort.signal.aborted) throw e; return null; });
+      let r = await get(url);
+      // the URL failed (a link expired, the file moved): renewed once
+      if (!r?.ok) { const again = await book.renewUrl!(id, url); if (again && again !== url) { url = again; r = await get(url); } }
+      if (!r?.ok) return null;
       return { type: assetType.get(id) ?? r.headers.get('content-type') ?? 'application/octet-stream', bytes: await r.arrayBuffer() };
     },
     want(list) {
diff --git a/packages/store/src/library-book/load.ts b/packages/store/src/library-book/load.ts
index 6e6a236..2faacf9 100644
--- a/packages/store/src/library-book/load.ts
+++ b/packages/store/src/library-book/load.ts
@@ -73,6 +73,12 @@ export type OpenedLibraryBook = {
    * when the item is in an indexed store that needs a token or asks to be verified always: then its bytes are to be fetched (`fetchItem`).
    */
   urlFor(id: string, type?: string, init?: { signal?: AbortSignal }): Promise<string | null>;
+  /**
+   * Forgets where the library said an item is: the indexed stores' shard naming it is dropped, and fetched again past the browser's cache
+   * the next time (`urlFor`, `fetchItem`). For a URL that failed to draw: the library moves an adopted key to another copy when one is
+   * deleted, or when it finds another (registry-api §3.1), and an open book must see that.
+   */
+  forgetUrl(id: string): void;
   /**
    * The library's store for a type: the first of `GET /v1/stores` (derived or api) whose `media` take it. Items and media come from these first;
    * the book's suggested stores only when the library's fails (`fetchItem`).
@@ -213,13 +219,16 @@ export async function openLibraryBook(o: OpenLibraryBookOptions): Promise<Opened
   // adopted key to another copy when its owner deletes one (registry-api §3.1), and an open book must see that
   const SHARD_MS = 60_000;
   const shards = new Map<string, { at: number; shard: Promise<Map<string, string>> }>();
+  // shards dropped because a URL they named failed: fetched again past the browser's cache (the library lets it keep one a minute)
+  const stale = new Set<string>();
+  const dropShard = (id: string) => { shards.delete(id); stale.add(id); };
   const indexedFor = (type: string) => stores.filter((d) => d.kind === 'indexed' && d.base && takes(d.media, type));
   const inIndex = async (key: string, type: string, signal?: AbortSignal): Promise<{ url: string; store: StoreDescriptor; forget: () => void } | null> => {
     for (const s of indexedFor(type)) {
       const id = `${s.id}|${shardOf(key)}`, kept = shards.get(id);
       let shard = kept && Date.now() - kept.at < SHARD_MS ? kept.shard : undefined;
       if (!shard) {
-        const url = shardUrl(s, key), init = signal ? { signal } : {};
+        const url = shardUrl(s, key), init: RequestInit = { ...(signal ? { signal } : {}), ...(stale.delete(id) ? { cache: 'no-cache' as const } : {}) };
         shard = (s.auth === 'bearer' ? fetchWithToken(doFetch, o.token, url, init) : doFetch(url, init)).then(async (r) => {
           if (r.status === 404) return new Map<string, string>();
           if (!r.ok) throw new Error(`index ${r.status}`);
@@ -231,7 +240,7 @@ export async function openLibraryBook(o: OpenLibraryBookOptions): Promise<Opened
         shard.catch(() => { if (shards.get(id) === entry) shards.delete(id); });   // a failed shard is asked again next time
       }
       const url = await shard.then((m) => m.get(hashPart(key))).catch(() => undefined);
-      if (url) return { url, store: s, forget: () => shards.delete(id) };
+      if (url) return { url, store: s, forget: () => dropShard(id) };
     }
     return null;
   };
@@ -327,6 +336,10 @@ export async function openLibraryBook(o: OpenLibraryBookOptions): Promise<Opened
       if (adopted) return adopted.store.auth !== 'bearer' && adopted.store.verify !== 'always' ? adopted.url : null;
       return book.urlOf(id, t);
     },
+    forgetUrl(id) {
+      const k = resolutionKey(id);
+      if (k) for (const s of stores) if (s.kind === 'indexed') dropShard(`${s.id}|${shardOf(k)}`);
+    },
     storeFor: (type) => storeFor(type),
     storesFor,
     async headersFor(type) { const s = storeFor(type); return s ? headersOf(s) : {}; },
diff --git a/packages/store/src/library.ts b/packages/store/src/library.ts
index 94756a3..f19b360 100644
--- a/packages/store/src/library.ts
+++ b/packages/store/src/library.ts
@@ -69,6 +69,8 @@ export interface Library {
   get(key: string): Promise<{ bytes: Uint8Array; type: string } | null>;
   /** A URL to draw or stream the item from (no download first), or null. */
   url(key: string): Promise<string | null>;
+  /** Forget what this library said about where an item is, so the next `url` asks again: a URL it gave failed to draw (the item moved). */
+  forget?(key: string): void;
   /** Which of these keys the library has. */
   has(keys: readonly string[]): Promise<Set<string>>;
   /** Add an item; the same bytes give the same key, so adding twice adds once. */
diff --git a/packages/store/src/registry-library.ts b/packages/store/src/registry-library.ts
index a0a2f66..cdf9e19 100644
--- a/packages/store/src/registry-library.ts
+++ b/packages/store/src/registry-library.ts
@@ -33,10 +33,12 @@ export function registryLibrary(o: {
   // files the library adopted in place (registry-api §3.1) are not at the derived path: its public indexed store
   // (spec 1.2 §5.3) says where they are. A shard is kept a minute, as the library's own Cache-Control says.
   const shards = new Map<string, { at: number; shard: Promise<IndexShard | null> }>();
+  // shards forgotten because a URL they named failed: fetched again past the browser's cache
+  const stale = new Set<string>();
   const indexed = async (key: string) => {
     for (const s of (await allStores()).filter((d) => d.kind === 'indexed' && (d.auth ?? 'none') === 'none' && d.base)) {
       const id = `${s.id}|${shardOf(key)}`, hit = shards.get(id);
-      const shard = hit && Date.now() - hit.at < 60_000 ? hit.shard : doFetch(shardUrl(s, key)).then(async (r) => (r.ok ? indexShardSchema.parse(await r.json()) : null)).catch(() => null);
+      const shard = hit && Date.now() - hit.at < 60_000 ? hit.shard : doFetch(shardUrl(s, key), stale.delete(id) ? { cache: 'no-cache' } : {}).then(async (r) => (r.ok ? indexShardSchema.parse(await r.json()) : null)).catch(() => null);
       if (shard !== hit?.shard) shards.set(id, { at: Date.now(), shard });
       const e = (await shard)?.entries[hashPart(key)];
       if (e) return /^[a-z][a-z0-9+.-]*:/i.test(e.p) ? e.p : s.base + e.p;
@@ -64,6 +66,9 @@ export function registryLibrary(o: {
       const s = await deliveryStore();
       return s ? (await indexed(key)) ?? at(s, key) : null;
     },
+    forget(key) {
+      for (const id of [...shards.keys()]) if (id.endsWith(`|${shardOf(key)}`)) { shards.delete(id); stale.add(id); }
+    },
     async get(key) {
       const pub = await deliveryStore();
       const s = pub ?? (o.token ? await tokenStore() : null);
diff --git a/packages/store/src/resolver.test.ts b/packages/store/src/resolver.test.ts
index 1599552..17075d7 100644
--- a/packages/store/src/resolver.test.ts
+++ b/packages/store/src/resolver.test.ts
@@ -136,6 +136,22 @@ describe('the resolver (spec 1.2 §6)', () => {
     expect(n.calls.filter((c) => c.includes('/index/'))).toHaveLength(2);
   });
 
+  it('a URL locate gave that failed later: forget(id) makes the next locate ask the index again', async () => {
+    const lan: StoreDescriptor = { id: 'lan', kind: 'indexed', base: 'http://lan/chalk/' };
+    const files: Record<string, Uint8Array | object> = {
+      [`http://lan/chalk/index/${shardOf(K.png)}.json`]: { v: 1, entries: { [K.png.slice(3)]: { p: 'a/gauge.png' } } },
+      'http://lan/chalk/a/gauge.png': PNG,
+    };
+    const n = net(files);
+    const r = createResolver({ hostStores: [lan], fetch: n.fetch });
+    expect((await r.locate(K.png, 'image/png'))?.url).toBe('http://lan/chalk/a/gauge.png');
+    delete files['http://lan/chalk/a/gauge.png'];
+    files[`http://lan/chalk/index/${shardOf(K.png)}.json`] = { v: 1, entries: { [K.png.slice(3)]: { p: 'b/gauge.png' } } };
+    files['http://lan/chalk/b/gauge.png'] = PNG;
+    r.forget(K.png);
+    expect((await r.locate(K.png, 'image/png'))?.url).toBe('http://lan/chalk/b/gauge.png');
+  });
+
   it('asks only one store at a time, and once per key while a request is open', async () => {
     const n = net({ [at(cdn, K.png)]: PNG });
     const r = createResolver({ hostStores: [cdn], fetch: n.fetch });
diff --git a/packages/store/src/resolver.ts b/packages/store/src/resolver.ts
index aa2a77b..eadb507 100644
--- a/packages/store/src/resolver.ts
+++ b/packages/store/src/resolver.ts
@@ -155,6 +155,8 @@ export function createResolver(o: ResolverOptions = {}) {
           const url = await urlIn(s, key);
           if (!url) continue;
           const r = await gate(() => doFetch(url, { method: 'HEAD', headers: headersFor(s) }));
+          // a path an index named that is gone: its shard is forgotten (the key moved), as in `resolve`
+          if (!r.ok && s.kind === 'indexed') shards.delete(`${s.id}|${shardOf(key)}`);
           if (r.ok) { const headers = headersFor(s); return Object.keys(headers).length ? { url, from: s.id, headers } : { url, from: s.id }; }
           if (r.status >= 500) markDown(s);
         } catch { markDown(s); }
@@ -162,6 +164,15 @@ export function createResolver(o: ResolverOptions = {}) {
       return null;
     },
 
+    /**
+     * Forget where the indexed stores said a key is: a URL `locate` gave failed later (the store moved the key, registry-api §3.1). The
+     * next `resolve` or `locate` asks the index again.
+     */
+    forget(id: string): void {
+      const key = resolutionKey(id);
+      if (key) for (const sk of [...shards.keys()]) if (sk.endsWith(`|${shardOf(key)}`)) shards.delete(sk);
+    },
+
     /** The ordered stores for a type (for diagnostics and tests). */
     plan: (type: string) => plan(type).map((s) => s.id),
   };
diff --git a/tools/reader-media-recover-e2e.ts b/tools/reader-media-recover-e2e.ts
new file mode 100644
index 0000000..a9d154d
--- /dev/null
+++ b/tools/reader-media-recover-e2e.ts
@@ -0,0 +1,131 @@
+// Media that move while a library book is open (registry-api §3.1: a key adopted at two paths, the copy the reader named deleted): the
+// reader recovers. Publishes a small book into a disk library whose media are adopted in place, each at two paths (two books' copies), and
+// opens it in the built showcase with `?library=…&book=…`:
+//   - the picture on page 1 is drawn from the copy the library names first;
+//   - the video's card has resolved its URL; that copy is deleted; a tap plays it: the <video> fails on the old URL, the reader asks the
+//     library again (past its cached index shard) and swaps the src once, to the other copy, which plays;
+//   - the audio's copies are both deleted: a tap tries the old URL, asks once more, and stops (no loop).
+//
+//   npx tsx tools/reader-media-recover-e2e.ts <library-url> <author-token> <library-disk-dir> [--dist apps/reader/dist] [--shots <dir>]
+//
+// The library must be a disk library (STORAGE=disk) that adopts from `books/` (ADOPT_PREFIXES=books/) and reads publicly. The showcase is
+// built first (`pnpm --filter @chalk-format/reader-app build`) and served to the browser from its files (no port is opened for it). Use a
+// test library: this writes into it, and deletes files it wrote in its folder.
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { chromium } from 'playwright-core';
+import { publishStreamed } from '../packages/container/src/index.ts';
+import { assetKeyAndSha256, type Lesson } from '../packages/model/src/index.ts';
+import { createRegistryClient } from '../packages/store/src/index.ts';
+
+const args = process.argv.slice(2);
+const opt = (n: string) => { const i = args.indexOf(n); if (i < 0) return undefined; const v = args[i + 1]; args.splice(i, 2); return v; };
+const DIST = path.resolve(opt('--dist') ?? path.join(import.meta.dirname, '../apps/reader/dist'));
+const SHOTS = opt('--shots');
+const [LIBRARY, TOKEN, DISK_DIR] = args;
+if (!LIBRARY || !TOKEN || !DISK_DIR) { console.error('usage: reader-media-recover-e2e.ts <library-url> <author-token> <library-disk-dir> [--dist dir] [--shots dir]'); process.exit(2); }
+if (SHOTS) mkdirSync(SHOTS, { recursive: true });
+
+let failed = false;
+const check = (name: string, ok: boolean, detail = '') => { if (!ok) failed = true; console.log(ok ? 'ok  ' : 'FAIL', name, detail); };
+
+// ---- the book: one page with a picture, a video and an audio. Each run its own bytes (the same bytes would be the same items, with
+// the copies and tags of an earlier run): the slug is appended to each file, which every decoder ignores ----
+const slug = `e2e-recover-${Date.now().toString(36)}`;
+const enc = new TextEncoder();
+const media = async (file: string, type: string, name: string) => {
+  const bytes = new Uint8Array([...readFileSync(path.join(import.meta.dirname, '../apps/reader/showcase/media', file)), ...enc.encode(slug)]);
+  const { key, sha256 } = await assetKeyAndSha256(bytes);
+  // the copy adopted last is the one the library names first (newest verified first): `copies[1]`
+  return { bytes, key, sha256, type, copies: [`books/${slug}-b/${name}`, `books/${slug}-a/${name}`] };
+};
+const pic = await media('pendulum-poster.png', 'image/png', 'pic.png');
+const video = await media('pendulum.webm', 'video/webm', 'clip.webm');
+const audio = await media('tuning-fork.mp3', 'audio/mpeg', 'tone.mp3');
+const lesson: Lesson = {
+  id: slug, title: `Media that move (${slug})`, locale: 'en', createdAt: '', updatedAt: '', snipPages: [],
+  pages: [{ id: 'p0', title: 'Page 1', width: 1000, height: 1300, background: { type: 'blank' }, textLayer: [{ text: slug, x: 60, y: 50, width: 400, fontSize: 24 }], objects: [
+    { id: 'img', type: 'image', x: 60, y: 80, width: 400, height: 300, assetId: pic.key },
+    { id: 'vid', type: 'embed', embed: 'video', x: 500, y: 80, width: 440, height: 300, assetId: video.key, presentation: { show: 'card', open: 'inline' } },
+    { id: 'aud', type: 'embed', embed: 'audio', x: 60, y: 500, width: 600, height: 80, assetId: audio.key },
+  ] }],
+} as Lesson;
+const { index, files } = await publishStreamed(lesson, new Map([pic, video, audio].map((m) => [m.key, { type: m.type, bytes: m.bytes }])));
+
+const lib = createRegistryClient(LIBRARY, { token: TOKEN });
+const stores = (await lib.stores()).items.filter((d) => d.auth !== 'bearer');
+const tags = (kind: string) => ['origin:chalkbook', `book:${slug}`, 'book-revision:1', `kind:${kind}`, 'state:current'];
+const add = async (bytes: Uint8Array, type: string, t: string[]) => (await lib.add(bytes, { type, tags: t })).key;
+// the media: adopted in place at two books' paths, never uploaded (so only the index knows where they are)
+for (const m of [pic, video, audio]) {
+  for (const p of m.copies) {
+    mkdirSync(path.dirname(path.join(DISK_DIR, p)), { recursive: true });
+    writeFileSync(path.join(DISK_DIR, p), m.bytes);
+    await lib.adopt({ key: m.key, sha256: m.sha256, type: m.type, size: m.bytes.byteLength, path: p });
+    await new Promise((r) => setTimeout(r, 30));
+  }
+}
+const pages = await Promise.all(index.pages.map(async ({ file, ...p }) => ({ ...p, key: await add(files.get(file)!, 'application/vnd.chalk.page+json', tags('page')) })));
+const textBytes = files.get(index.text!.file)!;
+const textKey = await add(textBytes, 'application/vnd.chalk.text+json', tags('text'));
+const { text: _text, ...rest } = index;
+const book = { ...rest, pages, text: { key: textKey, bytes: textBytes.byteLength }, assets: index.assets.map(({ path: _p, ...a }) => a), assetSources: stores };
+await add(enc.encode(JSON.stringify(book)), 'application/vnd.chalk.book+json', tags('book'));
+console.log(`published ${slug}`);
+
+// ---- the browser: the built showcase served from its files, the library for real (the token given, so no sign-in form) ----
+// a loopback address with no server behind it: every request to it is answered from the files
+const ORIGIN = 'http://127.0.0.2';
+const TYPES: Record<string, string> = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.woff2': 'font/woff2', '.wasm': 'application/wasm', '.mjs': 'text/javascript' };
+// the page's origin is not the library's: local network access checks are off (a test library on this machine)
+const b = await chromium.launch({ args: ['--disable-features=LocalNetworkAccessChecks,BlockInsecurePrivateNetworkRequests,PrivateNetworkAccessSendPreflights', '--autoplay-policy=no-user-gesture-required'] });
+const ctx = await b.newContext({ viewport: { width: 1100, height: 900 } });
+await ctx.route(`${ORIGIN}/**`, async (route) => {
+  const u = new URL(route.request().url());
+  const file = path.join(DIST, u.pathname === '/' ? 'index.html' : decodeURIComponent(u.pathname));
+  try { await route.fulfill({ body: readFileSync(file), contentType: TYPES[path.extname(file)] ?? 'application/octet-stream' }); }
+  catch { await route.fulfill({ body: readFileSync(path.join(DIST, 'index.html')), contentType: 'text/html' }); }
+});
+const p = await ctx.newPage();
+const errors: string[] = []; p.on('pageerror', (e) => errors.push(e.message));
+p.on('console', (m) => { if (m.type() === 'error' && process.env.E2E_DEBUG) console.log('console:', m.text()); });
+const asked: { url: string; status: number }[] = [];
+p.on('response', (r) => { if (r.url().includes(`/books/${slug}`) || r.url().includes('/index/')) asked.push({ url: r.url(), status: r.status() }); });
+const askedFor = (copy: string) => asked.filter((a) => a.url.endsWith(copy));
+
+await p.goto(`${ORIGIN}/?${new URLSearchParams({ library: LIBRARY, book: slug, token: TOKEN })}`);
+await p.waitForFunction(() => document.querySelectorAll('.chalk-page image, .chalk-page img').length > 0, null, { timeout: 30000 }).catch(() => {});
+await p.waitForTimeout(1500);
+const drawn = await p.evaluate(() => [...document.querySelectorAll<SVGImageElement>('.chalk-page image')].map((i) => i.href.baseVal));
+check('the picture is drawn from the copy the library names first', drawn.some((u) => u.endsWith(pic.copies[1]!)) && askedFor(pic.copies[1]!).some((a) => a.status === 200), JSON.stringify(drawn));
+if (SHOTS) await p.screenshot({ path: `${SHOTS}/recover-before.png` });
+
+// ---- the video: its card has its URL; the book that owned that copy prunes it; a tap plays it from the other copy ----
+check('the video was not fetched before it is played', askedFor(video.copies[1]!).length === 0 && askedFor(video.copies[0]!).length === 0);
+rmSync(path.join(DISK_DIR, video.copies[1]!));
+asked.length = 0;
+await p.click('.chalk-card');
+await p.waitForFunction((other) => { const v = document.querySelector<HTMLVideoElement>('.chalk-video video'); return !!v && v.src.endsWith(other) && v.readyState >= 1; }, video.copies[0]!, { timeout: 15000 }).catch(() => {});
+await p.waitForTimeout(1000);
+const v = await p.evaluate(() => { const e = document.querySelector<HTMLVideoElement>('.chalk-video video'); return e ? { src: e.src, ready: e.readyState, error: e.error?.code ?? null } : null; });
+check('the video first tried the URL it had, which is gone', askedFor(video.copies[1]!).some((a) => a.status === 404), JSON.stringify(askedFor(video.copies[1]!)));
+check('the reader asked the library\'s index again', asked.some((a) => a.url.includes('/index/') && a.status === 200));
+check('the video plays from the other copy', !!v && v.src.endsWith(video.copies[0]!) && v.ready >= 1 && v.error === null && askedFor(video.copies[0]!).some((a) => a.status < 300), JSON.stringify(v));
+check('the old URL was not asked again and again', askedFor(video.copies[1]!).length <= 2, String(askedFor(video.copies[1]!).length));
+if (SHOTS) await p.screenshot({ path: `${SHOTS}/recover-video.png` });
+
+// ---- the audio: every copy gone; a tap tries once more and stops ----
+for (const c of audio.copies) rmSync(path.join(DISK_DIR, c));
+asked.length = 0;
+await p.click('.chalk-audio-play');
+await p.waitForTimeout(4000);
+const tries = asked.filter((a) => a.url.endsWith('/tone.mp3'));
+check('with every copy gone, the audio is tried, renewed once, and left (no loop)', tries.length >= 1 && tries.length <= 3 && tries.every((a) => a.status === 404), JSON.stringify(tries));
+const later = asked.length;
+await p.waitForTimeout(2000);
+check('…and nothing more is asked', asked.length === later, `${asked.length - later} more requests`);
+check('no errors in the page', errors.length === 0, errors.join(' | '));
+
+await b.close();
+console.log(failed ? '\nSOME CHECKS FAILED' : '\nall checks passed');
+process.exit(failed ? 1 : 0);

From 1f25779af52c16b5d8310b595d113294bf6369db Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Sun, 1 Nov 2026 02:22:48 +0600
Subject: [PATCH 02/12] fix(reader): renewal at most once a minute per element;
 a paused player stays paused; onLoad for host players; no-cache shard in
 createResolver; forgetUrl optional

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/reader/src/ChalkReader.tsx       |  2 +-
 packages/reader/src/media-recover.test.ts | 11 +++++++++-
 packages/reader/src/present.tsx           |  2 ++
 packages/reader/src/render/Embeds.tsx     |  6 +++---
 packages/reader/src/render/assets.ts      | 25 +++++++++++++++--------
 packages/reader/src/stream.ts             |  2 +-
 packages/store/src/library-book/load.ts   |  2 +-
 packages/store/src/resolver.test.ts       |  4 ++++
 packages/store/src/resolver.ts            | 17 ++++++++-------
 9 files changed, 49 insertions(+), 22 deletions(-)

diff --git a/packages/reader/src/ChalkReader.tsx b/packages/reader/src/ChalkReader.tsx
index 390c2a0..9fda5d0 100644
--- a/packages/reader/src/ChalkReader.tsx
+++ b/packages/reader/src/ChalkReader.tsx
@@ -920,7 +920,7 @@ function MediaInModal({ book, o, locale, theme, storage, onClose, fill }: { book
   const p = pr.present(o);
   // opened by a tap: the student asked, so it plays (with sound unless the author muted it)
   const R = pr.renderers.video;
-  if (o.embed === 'video' && R) return <div className={fill ? 'chalk-window-custom-media' : 'chalk-modal-custom'}>{R({ object: o, src: url ?? null, poster: null, presentation: p, where: 'popup', onError, ...pr.env })}</div>;
+  if (o.embed === 'video' && R) return <div className={fill ? 'chalk-window-custom-media' : 'chalk-modal-custom'}>{R({ object: o, src: url ?? null, poster: null, presentation: p, where: 'popup', onError, onLoad, ...pr.env })}</div>;
   if (o.embed === 'video') return url ? <video className={mediaClass} src={url} controls autoPlay playsInline loop={p.loop} muted={p.muted} onError={resume.onError} onLoadedMetadata={resume.onLoadedMetadata} /> : null;
   if (o.embed === 'audio') return <ModalAudio book={book} o={o} locale={locale} />;
   return null;
diff --git a/packages/reader/src/media-recover.test.ts b/packages/reader/src/media-recover.test.ts
index acc6ac1..4524b05 100644
--- a/packages/reader/src/media-recover.test.ts
+++ b/packages/reader/src/media-recover.test.ts
@@ -3,7 +3,7 @@ import type { Lesson } from '@chalk-format/model';
 import type { Library } from '@chalk-format/store';
 import { bookFrom, type Book } from './book.js';
 import { newLookup, withLibraries } from './libraries.js';
-import { mediaRenewer, RENEW_DELAY_MS } from './render/assets.js';
+import { mediaRenewer, RENEW_AGAIN_MS, RENEW_DELAY_MS } from './render/assets.js';
 
 const lesson: Lesson = { id: 'b', title: 'B', locale: 'bn', createdAt: '', updatedAt: '', snipPages: [], pages: [] };
 
@@ -120,12 +120,21 @@ describe('an element whose media failed to load', () => {
     r.failed('https://lib.example/v?sig=1');
     await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS);
     r.loaded();
+    await vi.advanceTimersByTimeAsync(RENEW_AGAIN_MS);
     r.failed('https://lib.example/v?sig=2');
     await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS);
     expect(renewUrl).toHaveBeenCalledTimes(2);
     expect(set.mock.calls).toEqual([['https://lib.example/v?sig=2'], ['https://lib.example/v?sig=3']]);
   });
 
+  it('media that load and then fail every time are not renewed again and again (a minute between renewals)', async () => {
+    vi.useFakeTimers();
+    const { book, renewUrl } = fakeBook(['https://lib.example/v?sig=2', 'https://lib.example/v?sig=3', 'https://lib.example/v?sig=4']);
+    const r = mediaRenewer(book, 'c1:video', vi.fn());
+    for (let i = 1; i <= 5; i++) { r.failed(`https://lib.example/v?sig=${i}`); await vi.advanceTimersByTimeAsync(RENEW_DELAY_MS); r.loaded(); }
+    expect(renewUrl).toHaveBeenCalledTimes(1);
+  });
+
   it('the same URL again changes nothing, and an element that went away is not updated', async () => {
     vi.useFakeTimers();
     const same = fakeBook(['https://cdn.example/a/pic']);
diff --git a/packages/reader/src/present.tsx b/packages/reader/src/present.tsx
index 65e79b3..611a85e 100644
--- a/packages/reader/src/present.tsx
+++ b/packages/reader/src/present.tsx
@@ -41,6 +41,8 @@ export type MediaRendererProps = {
    * more and renders you again with a new `src`. Once per failure, as for its own players.
    */
   onError?: () => void;
+  /** Call when your player has loaded `src`: a later failure (a link that expires again while a long video plays) may then be renewed again. */
+  onLoad?: () => void;
   locale: Locale;
   theme: 'light' | 'dark';
 };
diff --git a/packages/reader/src/render/Embeds.tsx b/packages/reader/src/render/Embeds.tsx
index 2ff1fe3..503a951 100644
--- a/packages/reader/src/render/Embeds.tsx
+++ b/packages/reader/src/render/Embeds.tsx
@@ -57,7 +57,7 @@ export function VideoEmbed({ book, o, label, onOpen, notFound }: { book: Book; o
   usePlayWhileVisible(el, Boolean(src) && playing && p.autoplay && !tapped);
   if (!playing) return <EmbedCard book={book} o={o} label={label} notFound={notFound} onActivate={onOpen ?? (() => { setTapped(true); setPlaying(true); })} />;
   const R = pr.renderers.video;
-  if (R) return <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-video" label={p.label ?? label} id={o.id}>{R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where: 'page', onError: media.onError, ...pr.env })}</Box>;
+  if (R) return <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-video" label={p.label ?? label} id={o.id}>{R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where: 'page', onError: media.onError, onLoad: media.onLoad, ...pr.env })}</Box>;
   return (
     <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-video" label={p.label ?? label} id={o.id}>
       {/* browsers start a video by itself only without sound; a tap is the student asking, so then it plays as authored */}
@@ -88,7 +88,7 @@ export function AudioEmbed({ book, o, locale }: { book: Book; o: EmbedObject; lo
   const poster = useAssetUrl(book, o.poster);
   // whether it can be played at all: null is "no book or library has it"
   const avail = useAssetUrl(book, R ? undefined : o.assetId);
-  if (R) return <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-audio" label={p.label} id={o.id}>{R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where: 'page', onError: media.onError, ...pr.env })}</Box>;
+  if (R) return <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-audio" label={p.label} id={o.id}>{R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where: 'page', onError: media.onError, onLoad: media.onLoad, ...pr.env })}</Box>;
   return (
     <Box x={o.x} y={o.y} width={o.width} height={o.height} className={`chalk-audio ${avail === null && o.assetId ? 'is-missing' : ''}`} label={p.label} id={o.id}>
       {avail === null && o.assetId && <span className="chalk-card-missing">{t.notFound}</span>}
@@ -131,7 +131,7 @@ export function ModelViewer({ book, o, style, where = 'page' }: { book: Book; o:
   useEffect(() => { if (R) return; let live = true; void import('@google/model-viewer').then(() => { if (live) setLoaded(true); }); return () => { live = false; }; }, [R]);
   return (
     <div className="chalk-live chalk-model" style={style} aria-label={p.label}>
-      {R && R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where, onError: media.onError, ...pr.env })}
+      {R && R({ object: o, src: src ?? null, poster: poster ?? null, presentation: p, where, onError: media.onError, onLoad: media.onLoad, ...pr.env })}
       {!R && loaded && src && (
         <model-viewer ref={viewer} src={src} poster={poster ?? undefined} camera-controls="" touch-action="pan-y" shadow-intensity="0.7" exposure="1.05"
           environment-image="neutral" interaction-prompt="none" {...(p.autoRotate ? { 'auto-rotate': '' } : {})} style={{ width: '100%', height: '100%', background: 'transparent' }} />
diff --git a/packages/reader/src/render/assets.ts b/packages/reader/src/render/assets.ts
index fa23aa1..6d709eb 100644
--- a/packages/reader/src/render/assets.ts
+++ b/packages/reader/src/render/assets.ts
@@ -3,6 +3,12 @@ import type { Book } from '../book.js';
 
 /** How long an element waits after its media failed before asking the book for the asset again (a moment for the library to settle). */
 export const RENEW_DELAY_MS = 400;
+/**
+ * The least time between two renewals of one element, even when the renewed media loaded in between: media that load and then fail
+ * every time (bytes a browser cannot decode, under URLs that change each time) are not asked for again and again. A signed link lasts
+ * minutes (registry-api §7.1: 5 to 15), so one that expires again later is still renewed.
+ */
+export const RENEW_AGAIN_MS = 60_000;
 
 /** The URL to draw an asset with: undefined while resolving, null if it is not available. */
 export function useAssetUrl(book: Book, assetId: string | undefined): string | null | undefined {
@@ -18,21 +24,22 @@ export type AssetSrc = {
    * loaded is not renewed again (no loop).
    */
   onError: () => void;
-  /** The element loaded its media: a later failure (a link that expires while a long video plays) may renew it again. */
+  /** The element loaded its media: a later failure (a link that expires while a long video plays) may renew it again, a minute after the last renewal at the earliest. */
   onLoad: () => void;
 };
 
 /**
  * One element's recovery from media that failed to load: `failed(url)` asks the book for the asset again after `delay`, once, and hands a
- * new answer to `set`; `loaded()` allows the next failure to renew again. A renewed URL that fails before it ever loaded is left as it is
- * (no loop). `stop()` cancels a renewal on its way (the element went away, or draws another asset).
+ * new answer to `set`; `loaded()` allows the next failure to renew again, `again` after the last renewal at the earliest. A renewed URL
+ * that fails before it ever loaded is left as it is (no loop). `stop()` cancels a renewal on its way (the element went away, or draws
+ * another asset).
  */
-export function mediaRenewer(book: Book, assetId: string, set: (url: string | null) => void, delay = RENEW_DELAY_MS) {
-  let budget = true, live = true, timer: ReturnType<typeof setTimeout> | undefined;
+export function mediaRenewer(book: Book, assetId: string, set: (url: string | null) => void, delay = RENEW_DELAY_MS, again = RENEW_AGAIN_MS) {
+  let budget = true, live = true, last = -Infinity, timer: ReturnType<typeof setTimeout> | undefined;
   return {
     failed(url: string | null) {
-      if (!live || !budget || !book.renewUrl) return;
-      budget = false;
+      if (!live || !budget || !book.renewUrl || Date.now() - last < again) return;
+      budget = false; last = Date.now();
       timer = setTimeout(() => {
         void book.renewUrl!(assetId, url).catch(() => null).then((u) => {
           // the same answer again: nothing changes (the element stays as it is)
@@ -82,7 +89,9 @@ export function useResume(onError: () => void, onLoad: () => void) {
   return {
     onError: (e: { currentTarget: HTMLMediaElement }) => {
       const m = e.currentTarget;
-      at.current = { time: m.currentTime, playing: !m.paused || m.autoplay };
+      at.current = { time: m.currentTime, playing: !m.paused };
+      // a paused player stays paused under its new URL: its autoplay (set when it was tapped) would start it again
+      if (m.paused) m.autoplay = false;
       onError();
     },
     onLoadedMetadata: (e: { currentTarget: HTMLMediaElement }) => {
diff --git a/packages/reader/src/stream.ts b/packages/reader/src/stream.ts
index 48fcf86..032e996 100644
--- a/packages/reader/src/stream.ts
+++ b/packages/reader/src/stream.ts
@@ -124,7 +124,7 @@ export async function openLibraryStreamedBook(source: LibrarySource, o: { resolv
       return new Blob([(await lib.fetchItem(id, { signal, type })) as BlobPart], { type });
     },
     // a URL the library named failed to draw (the library moved an adopted key to another copy): where it is is asked again
-    forget: (id) => lib.forgetUrl(id),
+    forget: (id) => lib.forgetUrl?.(id),
     library: lib,
   }, o);
 }
diff --git a/packages/store/src/library-book/load.ts b/packages/store/src/library-book/load.ts
index 2faacf9..198d76c 100644
--- a/packages/store/src/library-book/load.ts
+++ b/packages/store/src/library-book/load.ts
@@ -78,7 +78,7 @@ export type OpenedLibraryBook = {
    * the next time (`urlFor`, `fetchItem`). For a URL that failed to draw: the library moves an adopted key to another copy when one is
    * deleted, or when it finds another (registry-api §3.1), and an open book must see that.
    */
-  forgetUrl(id: string): void;
+  forgetUrl?(id: string): void;
   /**
    * The library's store for a type: the first of `GET /v1/stores` (derived or api) whose `media` take it. Items and media come from these first;
    * the book's suggested stores only when the library's fails (`fetchItem`).
diff --git a/packages/store/src/resolver.test.ts b/packages/store/src/resolver.test.ts
index 17075d7..a978b80 100644
--- a/packages/store/src/resolver.test.ts
+++ b/packages/store/src/resolver.test.ts
@@ -150,6 +150,10 @@ describe('the resolver (spec 1.2 §6)', () => {
     files['http://lan/chalk/b/gauge.png'] = PNG;
     r.forget(K.png);
     expect((await r.locate(K.png, 'image/png'))?.url).toBe('http://lan/chalk/b/gauge.png');
+    // asked past the browser's cache, which may keep the old shard a minute
+    const shardCalls = vi.mocked(n.fetch).mock.calls.filter(([u]) => String(u).includes('/index/'));
+    expect(shardCalls).toHaveLength(2);
+    expect((shardCalls[1]![1] as RequestInit).cache).toBe('no-cache');
   });
 
   it('asks only one store at a time, and once per key while a request is open', async () => {
diff --git a/packages/store/src/resolver.ts b/packages/store/src/resolver.ts
index eadb507..5b73670 100644
--- a/packages/store/src/resolver.ts
+++ b/packages/store/src/resolver.ts
@@ -46,6 +46,9 @@ export function createResolver(o: ResolverOptions = {}) {
   const book = (o.bookStores ?? []).filter(known).map((d) => ({ ...d, auth: 'none' as const }));
   const plans = new Map<string, StoreDescriptor[]>();
   const shards = new Map<string, Promise<IndexShard | null>>();
+  // shards dropped because a path they named failed: fetched again past the browser's cache (a library lets it keep one a minute)
+  const stale = new Set<string>();
+  const drop = (sk: string) => { shards.delete(sk); stale.add(sk); };
   const downAt = new Map<string, number>();
   const inflight = new Map<string, Promise<Resolved | null>>();
 
@@ -86,7 +89,7 @@ export function createResolver(o: ResolverOptions = {}) {
     const sk = `${s.id}|${shardOf(key)}`;
     let shard = shards.get(sk);
     if (!shard) {
-      shard = doFetch(shardUrl(s, key), { headers: headersFor(s) }).then(async (r) => {
+      shard = doFetch(shardUrl(s, key), { headers: headersFor(s), ...(stale.delete(sk) ? { cache: 'no-cache' as const } : {}) }).then(async (r) => {
         if (r.status === 404) return { v: 1 as const, entries: {} };
         if (!r.ok) throw new Error(`shard ${r.status}`);
         return indexShardSchema.parse(await r.json());
@@ -110,12 +113,12 @@ export function createResolver(o: ResolverOptions = {}) {
         if (!url) continue;
         // a path an index named that fails is forgotten with its shard: the store may have moved the key (a library's adopted file whose
         // owner deleted one copy, registry-api §3.1), and the next resolve asks the index again
-        const stale = () => { if (s.kind === 'indexed') shards.delete(`${s.id}|${shardOf(key)}`); };
+        const forgetShard = () => { if (s.kind === 'indexed') drop(`${s.id}|${shardOf(key)}`); };
         const r = await gate(() => doFetch(url, { headers: headersFor(s) }));
-        if (r.status === 404 || r.status === 410) { stale(); continue; }
-        if (!r.ok) { if (r.status >= 500) markDown(s); stale(); continue; }
+        if (r.status === 404 || r.status === 410) { forgetShard(); continue; }
+        if (!r.ok) { if (r.status >= 500) markDown(s); forgetShard(); continue; }
         const bytes = await r.arrayBuffer();
-        if (mustVerify(s, type) && !(await verifyAssetBytes(id, new Uint8Array(bytes)))) { stale(); continue; }   // not what the id names: next store
+        if (mustVerify(s, type) && !(await verifyAssetBytes(id, new Uint8Array(bytes)))) { forgetShard(); continue; }   // not what the id names: next store
         // cached once obtained: verified, or from a store the host trusts (verify 'none')
         await o.cache?.put(key, { bytes, type });
         return { bytes, type, from: s.id };
@@ -156,7 +159,7 @@ export function createResolver(o: ResolverOptions = {}) {
           if (!url) continue;
           const r = await gate(() => doFetch(url, { method: 'HEAD', headers: headersFor(s) }));
           // a path an index named that is gone: its shard is forgotten (the key moved), as in `resolve`
-          if (!r.ok && s.kind === 'indexed') shards.delete(`${s.id}|${shardOf(key)}`);
+          if (!r.ok && s.kind === 'indexed') drop(`${s.id}|${shardOf(key)}`);
           if (r.ok) { const headers = headersFor(s); return Object.keys(headers).length ? { url, from: s.id, headers } : { url, from: s.id }; }
           if (r.status >= 500) markDown(s);
         } catch { markDown(s); }
@@ -170,7 +173,7 @@ export function createResolver(o: ResolverOptions = {}) {
      */
     forget(id: string): void {
       const key = resolutionKey(id);
-      if (key) for (const sk of [...shards.keys()]) if (sk.endsWith(`|${shardOf(key)}`)) shards.delete(sk);
+      if (key) for (const s of [...host, ...book]) if (s.kind === 'indexed') drop(`${s.id}|${shardOf(key)}`);
     },
 
     /** The ordered stores for a type (for diagnostics and tests). */

From 22e25a0a8881982aee3eabd97ea29d7050b2606f Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Sun, 1 Nov 2026 02:26:58 +0600
Subject: [PATCH 03/12] fix(reader): a tapped video that fails before it starts
 still plays under its renewed URL; Resolver.forget optional in the type

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/reader/src/render/assets.ts | 8 +++++---
 packages/store/src/resolver.ts       | 3 ++-
 tools/reader-media-recover-e2e.ts    | 4 ++--
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/packages/reader/src/render/assets.ts b/packages/reader/src/render/assets.ts
index 6d709eb..f19d68a 100644
--- a/packages/reader/src/render/assets.ts
+++ b/packages/reader/src/render/assets.ts
@@ -89,9 +89,11 @@ export function useResume(onError: () => void, onLoad: () => void) {
   return {
     onError: (e: { currentTarget: HTMLMediaElement }) => {
       const m = e.currentTarget;
-      at.current = { time: m.currentTime, playing: !m.paused };
-      // a paused player stays paused under its new URL: its autoplay (set when it was tapped) would start it again
-      if (m.paused) m.autoplay = false;
+      // playing, or asked to play (a tap sets autoplay) and failed before it started; a player paused after it played stays paused under
+      // its new URL, so its autoplay is cleared (it would start it again)
+      const playing = !m.paused || (m.autoplay && m.played.length === 0);
+      at.current = { time: m.currentTime, playing };
+      if (!playing) m.autoplay = false;
       onError();
     },
     onLoadedMetadata: (e: { currentTarget: HTMLMediaElement }) => {
diff --git a/packages/store/src/resolver.ts b/packages/store/src/resolver.ts
index 5b73670..7566c1f 100644
--- a/packages/store/src/resolver.ts
+++ b/packages/store/src/resolver.ts
@@ -181,7 +181,8 @@ export function createResolver(o: ResolverOptions = {}) {
   };
 }
 
-export type Resolver = ReturnType<typeof createResolver>;
+// `forget` is optional in the type: a resolver written before it (a host's own, a mock) still is one
+export type Resolver = Omit<ReturnType<typeof createResolver>, 'forget'> & { forget?(id: string): void };
 
 /** Kinds this resolver knows; others are skipped (spec 1.2 §5.1). */
 function known(d: StoreDescriptor): boolean {
diff --git a/tools/reader-media-recover-e2e.ts b/tools/reader-media-recover-e2e.ts
index a9d154d..afea104 100644
--- a/tools/reader-media-recover-e2e.ts
+++ b/tools/reader-media-recover-e2e.ts
@@ -107,10 +107,10 @@ asked.length = 0;
 await p.click('.chalk-card');
 await p.waitForFunction((other) => { const v = document.querySelector<HTMLVideoElement>('.chalk-video video'); return !!v && v.src.endsWith(other) && v.readyState >= 1; }, video.copies[0]!, { timeout: 15000 }).catch(() => {});
 await p.waitForTimeout(1000);
-const v = await p.evaluate(() => { const e = document.querySelector<HTMLVideoElement>('.chalk-video video'); return e ? { src: e.src, ready: e.readyState, error: e.error?.code ?? null } : null; });
+const v = await p.evaluate(() => { const e = document.querySelector<HTMLVideoElement>('.chalk-video video'); return e ? { src: e.src, ready: e.readyState, error: e.error?.code ?? null, playing: !e.paused } : null; });
 check('the video first tried the URL it had, which is gone', askedFor(video.copies[1]!).some((a) => a.status === 404), JSON.stringify(askedFor(video.copies[1]!)));
 check('the reader asked the library\'s index again', asked.some((a) => a.url.includes('/index/') && a.status === 200));
-check('the video plays from the other copy', !!v && v.src.endsWith(video.copies[0]!) && v.ready >= 1 && v.error === null && askedFor(video.copies[0]!).some((a) => a.status < 300), JSON.stringify(v));
+check('the video plays from the other copy (the tap still counts)', !!v && v.src.endsWith(video.copies[0]!) && v.ready >= 1 && v.error === null && v.playing && askedFor(video.copies[0]!).some((a) => a.status < 300), JSON.stringify(v));
 check('the old URL was not asked again and again', askedFor(video.copies[1]!).length <= 2, String(askedFor(video.copies[1]!).length));
 if (SHOTS) await p.screenshot({ path: `${SHOTS}/recover-video.png` });
 

From 7160af0294e45e21473b503d7d7a3d7f35032886 Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Sun, 1 Nov 2026 02:54:07 +0600
Subject: [PATCH 04/12] fix(reader): a player the student paused (even before
 it started) stays paused under its renewed URL

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/reader/src/ChalkReader.tsx   |  2 +-
 packages/reader/src/render/Embeds.tsx |  4 ++--
 packages/reader/src/render/assets.ts  | 10 +++++++---
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/packages/reader/src/ChalkReader.tsx b/packages/reader/src/ChalkReader.tsx
index 9fda5d0..26afb27 100644
--- a/packages/reader/src/ChalkReader.tsx
+++ b/packages/reader/src/ChalkReader.tsx
@@ -921,7 +921,7 @@ function MediaInModal({ book, o, locale, theme, storage, onClose, fill }: { book
   // opened by a tap: the student asked, so it plays (with sound unless the author muted it)
   const R = pr.renderers.video;
   if (o.embed === 'video' && R) return <div className={fill ? 'chalk-window-custom-media' : 'chalk-modal-custom'}>{R({ object: o, src: url ?? null, poster: null, presentation: p, where: 'popup', onError, onLoad, ...pr.env })}</div>;
-  if (o.embed === 'video') return url ? <video className={mediaClass} src={url} controls autoPlay playsInline loop={p.loop} muted={p.muted} onError={resume.onError} onLoadedMetadata={resume.onLoadedMetadata} /> : null;
+  if (o.embed === 'video') return url ? <video className={mediaClass} src={url} controls autoPlay playsInline loop={p.loop} muted={p.muted} onError={resume.onError} onLoadedMetadata={resume.onLoadedMetadata} onPlay={resume.onPlay} onPause={resume.onPause} /> : null;
   if (o.embed === 'audio') return <ModalAudio book={book} o={o} locale={locale} />;
   return null;
 }
diff --git a/packages/reader/src/render/Embeds.tsx b/packages/reader/src/render/Embeds.tsx
index 503a951..5ea556d 100644
--- a/packages/reader/src/render/Embeds.tsx
+++ b/packages/reader/src/render/Embeds.tsx
@@ -62,7 +62,7 @@ export function VideoEmbed({ book, o, label, onOpen, notFound }: { book: Book; o
     <Box x={o.x} y={o.y} width={o.width} height={o.height} className="chalk-video" label={p.label ?? label} id={o.id}>
       {/* browsers start a video by itself only without sound; a tap is the student asking, so then it plays as authored */}
       {src && <video ref={el} src={src} poster={poster ?? undefined} controls playsInline preload="metadata"
-        autoPlay={tapped} loop={p.loop} muted={p.muted || (p.autoplay && !tapped)} onError={resume.onError} onLoadedMetadata={resume.onLoadedMetadata} />}
+        autoPlay={tapped} loop={p.loop} muted={p.muted || (p.autoplay && !tapped)} onError={resume.onError} onLoadedMetadata={resume.onLoadedMetadata} onPlay={resume.onPlay} onPause={resume.onPause} />}
     </Box>
   );
 }
@@ -102,7 +102,7 @@ export function AudioEmbed({ book, o, locale }: { book: Book; o: EmbedObject; lo
       </div>
       {src && (
         <audio ref={el} src={src} preload="metadata" loop={p.loop}
-          onPlay={() => setState((s) => ({ ...s, playing: true }))} onPause={() => setState((s) => ({ ...s, playing: false }))}
+          onPlay={() => { resume.onPlay(); setState((s) => ({ ...s, playing: true })); }} onPause={() => { resume.onPause(); setState((s) => ({ ...s, playing: false })); }}
           onTimeUpdate={(e) => { const a = e.currentTarget; setState((s) => ({ ...s, time: a.currentTime })); }}
           onError={resume.onError}
           onLoadedMetadata={(e) => { resume.onLoadedMetadata(e); const a = e.currentTarget; setState((s) => ({ ...s, duration: a.duration })); }} />
diff --git a/packages/reader/src/render/assets.ts b/packages/reader/src/render/assets.ts
index f19d68a..cd0d8a3 100644
--- a/packages/reader/src/render/assets.ts
+++ b/packages/reader/src/render/assets.ts
@@ -86,12 +86,16 @@ export function useAssetSrc(book: Book, assetId: string | undefined): AssetSrc {
  */
 export function useResume(onError: () => void, onLoad: () => void) {
   const at = useRef<{ time: number; playing: boolean } | null>(null);
+  // the student paused it (a `pause` event, the browser's controls included); playing again clears it
+  const paused = useRef(false);
   return {
+    onPlay: () => { paused.current = false; },
+    onPause: () => { paused.current = true; },
     onError: (e: { currentTarget: HTMLMediaElement }) => {
       const m = e.currentTarget;
-      // playing, or asked to play (a tap sets autoplay) and failed before it started; a player paused after it played stays paused under
-      // its new URL, so its autoplay is cleared (it would start it again)
-      const playing = !m.paused || (m.autoplay && m.played.length === 0);
+      // playing, or asked to play (a tap sets autoplay) and failed before it started; a player the student paused stays paused under its
+      // new URL, so its autoplay is cleared (it would start it again)
+      const playing = !m.paused || (m.autoplay && !paused.current);
       at.current = { time: m.currentTime, playing };
       if (!playing) m.autoplay = false;
       onError();

From dc861fae0481c2b0eba7dc1e44654e8fc6f95158 Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Sun, 1 Nov 2026 02:57:22 +0600
Subject: [PATCH 05/12] fix(reader): a pause while a URL is being renewed keeps
 the renewed media paused

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/reader/src/render/Embeds.tsx | 2 +-
 packages/reader/src/render/assets.ts  | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/reader/src/render/Embeds.tsx b/packages/reader/src/render/Embeds.tsx
index 5ea556d..cf2daeb 100644
--- a/packages/reader/src/render/Embeds.tsx
+++ b/packages/reader/src/render/Embeds.tsx
@@ -102,7 +102,7 @@ export function AudioEmbed({ book, o, locale }: { book: Book; o: EmbedObject; lo
       </div>
       {src && (
         <audio ref={el} src={src} preload="metadata" loop={p.loop}
-          onPlay={() => { resume.onPlay(); setState((s) => ({ ...s, playing: true })); }} onPause={() => { resume.onPause(); setState((s) => ({ ...s, playing: false })); }}
+          onPlay={() => { resume.onPlay(); setState((s) => ({ ...s, playing: true })); }} onPause={(e) => { resume.onPause(e); setState((s) => ({ ...s, playing: false })); }}
           onTimeUpdate={(e) => { const a = e.currentTarget; setState((s) => ({ ...s, time: a.currentTime })); }}
           onError={resume.onError}
           onLoadedMetadata={(e) => { resume.onLoadedMetadata(e); const a = e.currentTarget; setState((s) => ({ ...s, duration: a.duration })); }} />
diff --git a/packages/reader/src/render/assets.ts b/packages/reader/src/render/assets.ts
index cd0d8a3..73c248d 100644
--- a/packages/reader/src/render/assets.ts
+++ b/packages/reader/src/render/assets.ts
@@ -90,7 +90,8 @@ export function useResume(onError: () => void, onLoad: () => void) {
   const paused = useRef(false);
   return {
     onPlay: () => { paused.current = false; },
-    onPause: () => { paused.current = true; },
+    // a pause while the URL is being renewed counts too: the renewed media do not start
+    onPause: (e: { currentTarget: HTMLMediaElement }) => { paused.current = true; if (at.current) { at.current.playing = false; e.currentTarget.autoplay = false; } },
     onError: (e: { currentTarget: HTMLMediaElement }) => {
       const m = e.currentTarget;
       // playing, or asked to play (a tap sets autoplay) and failed before it started; a player the student paused stays paused under its

From ef90ce5362f406941425d8a45097cabdf69dcca2 Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Sun, 1 Nov 2026 23:57:52 +0600
Subject: [PATCH 06/12] spec(registry): book highlights (lines and question
 links) as editable records of a registry

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 spec/1.2/registry-api.md | 78 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/spec/1.2/registry-api.md b/spec/1.2/registry-api.md
index eff0810..a6727de 100644
--- a/spec/1.2/registry-api.md
+++ b/spec/1.2/registry-api.md
@@ -308,3 +308,81 @@ credential, `401` without one.
 A registry MAY require a token for reading too (the reference server: `PUBLIC_READ=false`). It then names, at
 `GET v1/stores`, a store with `"auth": "bearer"` (1.2 §5.1) for the bytes, and readers send the same bearer
 credential to it (§7.1). `GET v1/stores` itself and the discovery documents of §10.3 stay public.
+
+## 11. Book highlights (optional)
+
+A registry MAY keep the **highlights** of its books: the lines of a book's text and which question each line leads to. Unlike
+assets these are records that change one by one: an editor adds, moves and removes links, a matcher suggests them, and
+readers (a reading app, a mobile app) ask for the lines of the pages they show. A registry that lacks this answers `404`.
+Paths are under `v1/books/{slug}/` (`{slug}` as in spec 1.8 §2). Reads need `reader`, writes `author` (§10.1). Ids are
+UUID strings. Unknown ids of the book are `404 not_found`; a write that names a line the book no longer has (retired)
+is `409 conflict`.
+
+### 11.1 Records
+
+A **line** (one sentence of the text layer):
+
+```json
+{ "id": "…uuid…", "key": "p12/3b0fbd6c9c/0", "pageId": "p12", "pageNo": 12, "idx": 4, "block": 1, "kind": "body",
+  "text": "…", "textHash": "…", "chapterNo": 1, "chapterTitle": "…", "section": "…",
+  "rects": [{ "x": 120, "y": 530, "w": 610, "fs": 19 }], "retiredAt": null }
+```
+
+`key` is the line's lasting name (unique in the book; the indexer derives it from the page and the words), `rects` one box
+per printed line in page units (`y` the top; a box is `fs × 1.25` high). A line the text layer no longer has is
+**retired** (`retiredAt` set), never deleted, so the links on it are kept.
+
+A **link** (a question tied to a line):
+
+```json
+{ "id": "…uuid…", "questionId": "…uuid…", "lineId": "…uuid…", "role": "answers_from", "scope": "sentence",
+  "method": "auto", "status": "suggested", "score": 0.82, "rationale": "…", "questionType": "mcq",
+  "reviewedBy": null, "reviewedAt": null, "createdAt": "…" }
+```
+
+- `role`: `answers_from`, `tests_concept`, `uses_figure`, `formula_source` (spec 1.8 §3.4). `scope`: `sentence`,
+  `paragraph`, `section`. One link per (`questionId`, `lineId`, `role`).
+- `status`: `suggested`, `confirmed` or `rejected`. **A rejected link is a memory, not a link:** it records that the pair
+  was taken off, so a matcher does not put it back. Reads leave rejected links out unless they say otherwise.
+- `method`: `auto` (a matcher's) or `human`. A link is a **person's decision** when `method` is `human`, `reviewedBy` is
+  set, or it is `confirmed`. A question with any person's decision is never touched by a matcher (§11.4 `place`).
+- `questionId` names the question manifest's lasting id (spec 1.7, the `question:<id>` tag; resolve the current version
+  with §4.1). `questionType` is the question's kind as the writer gives it (`mcq`, `cq`, …), so readers can filter
+  without fetching every manifest.
+
+### 11.2 Reading (`reader`)
+
+| Request | Answer |
+|---|---|
+| `GET lines?pages=6,7` (`&linked=1`, `&status=confirmed`) | `{ "pages": { "6": [line + counts] } }`: the live lines of those pages (at most 50) in reading order, each with `links` (not rejected; with `status=confirmed` only confirmed), `suggested`, and `typeCounts` (`{ "<type>": { "confirmed", "suggested" } }`). `linked=1` leaves out lines with no link |
+| `GET lines/all` (`?chapter=`, `&retired=1`) | `{ "items": [line] }`: every line of the book (live only unless `retired=1`) |
+| `GET chapters` | `{ "items": [{ "no", "title" }] }` |
+| `GET pages/counts` | `{ "counts": { "<pageNo>": n } }`: questions with a live link on each page's live lines |
+| `GET links?line=` (`&paragraph=1`, `&status=confirmed`) | `{ "items": [link + line] }` of the line (or every live line of its paragraph): confirmed first, then by score, newest first |
+| `GET links?question=` | `{ "items": [link + line] }`: the question's live links on live lines of the book, in book order |
+| `GET links?chapter=&status=&method=&limit=&offset=` | `{ "items": [link + line], "total" }`: for review, in book order (default: not rejected; `limit` ≤ 200) |
+| `GET links/all` (`?rejected=1`) | `{ "items": [link + line key] }`: every link of the book |
+| `GET links/orphaned` | `{ "items": [link + line] }`: a person's live links on retired lines |
+| `POST v1/highlights/questions` `{ "questionIds": [...] }` (≤ 5000) | `{ "items": { "<id>": { "live", "human", "any" } } }`: over every book, how many live links each question has, whether a person decided on any of its links, whether it has any row |
+| `GET v1/highlights/tagged` | `{ "questionIds": [...] }`: every question with a live link in any book |
+
+`link + line` is the link with `"line": { "id", "key", "pageId", "pageNo", "idx", "block", "text", "chapterNo", "retiredAt" }`.
+
+### 11.3 Writing (`author`)
+
+Every write names the person (or job) in `by`, kept as `reviewedBy`. Each request is one transaction.
+
+| Request | What it does |
+|---|---|
+| `POST lines/sync` `{ "lines": [line without id] }` | Makes the book's lines what the text layer has: by `key`, adds new ones, updates changed ones (a retired one comes back), retires the ones not sent; then rejects the links on retired lines that are not a person's decision (`rationale` says why). → `{ "added", "changed", "retired", "revived", "linksRetired" }` |
+| `POST links` `{ questionId, lineId, role?, scope?, questionType?, by }` | A person's link: `human`, `confirmed`. An existing row for the pair becomes it. → the link |
+| `PATCH links/{id}` `{ status?, role?, scope?, lineId?, by }` | Changes one link. Changing role, scope or line, or rejecting, makes it `human`; a move confirms it unless `status` is given. Moving onto a pair that exists merges into that row (confirmed, `human`) and drops this one. → the link kept |
+| `DELETE links/{id}` `{ by }` | Takes it off: the row stays, `rejected`, `human`. → `{ "removed": 1 }` |
+| `POST lines/{id}/links/remove` `{ paragraph?, by }` | Takes off every live link of the line (or its paragraph). → `{ "removed": n }` |
+| `POST lines/{id}/links/move` `{ to, by }` | Moves the live links of a line to another: a pair the other line has is kept (confirmed if it was rejected, `human`) and this one dropped; rejected rows stay. → `{ "moved": n }` |
+| `PUT questions/{questionId}/lines` `{ role, add: [lineId], remove: [lineId], scope?, questionType?, by }` | A question's highlight under one role (≤ 200 lines named): `add`ed lines become the person's confirmed links, `remove`d ones rejected rows (whatever they were), the kept ones the person's. → `{ "items": [link + line] }` as `GET links?question=` |
+| `POST links/place` `{ questionId, questionType?, proposals: [{ lineId, role, scope?, score?, rationale? }] }` | A matcher's suggestions, written only if the question still has no live link and no person's decision in any book; lines retired since, and lines the question already has a row on, are skipped. → `{ "placed": n }` (0: not placed) |
+| `POST import` `{ lines: [line], links: [link] }` | Copies records with their ids (moving from another system). Upsert by id. → `{ "lines", "links" }` |
+
+Writes that touch a question (`links`, `questions/…/lines`, `place`, `move`) are serialised per question, so a matcher
+never places a question a person is tagging at the same moment.

From 14c6c1d4f4b4e53a10cf6cdb5268ceaf72b02d4a Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Sun, 1 Nov 2026 23:57:52 +0600
Subject: [PATCH 07/12] =?UTF-8?q?feat(library-server):=20book=20highlights?=
 =?UTF-8?q?:=20the=20lines=20of=20books=20and=20their=20question=20links?=
 =?UTF-8?q?=20as=20editable=20records=20(registry-api=20=C2=A711)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two tables (migration step 5) and the endpoints of §11: reading the lines of pages with their link counts, a line's or a
question's links, review lists, and the writes an editor and a matcher make (tag, change, move, take off, a question's
highlight, the matcher's place, the indexer's sync, an import with ids). A link taken off stays as a rejected row so a
matcher never puts it back; a question with a person's decision is never placed by a matcher. Writes to one question
are serialised. Db gains begin() for transactions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/library-server/README.md             |   5 +
 packages/library-server/src/adopt.test.ts     |   2 +-
 packages/library-server/src/app.test.ts       |   2 +-
 packages/library-server/src/app.ts            |   4 +-
 packages/library-server/src/db.ts             |  52 ++
 .../library-server/src/highlights.test.ts     | 172 +++++++
 packages/library-server/src/highlights.ts     | 467 ++++++++++++++++++
 packages/library-server/src/index.ts          |   1 +
 8 files changed, 702 insertions(+), 3 deletions(-)
 create mode 100644 packages/library-server/src/highlights.test.ts
 create mode 100644 packages/library-server/src/highlights.ts

diff --git a/packages/library-server/README.md b/packages/library-server/README.md
index ff61081..75eef8d 100644
--- a/packages/library-server/README.md
+++ b/packages/library-server/README.md
@@ -23,6 +23,11 @@ DATABASE_URL=pglite:./.data/db npx tsx src/cli.ts key add ci --roles author
 
 (PGlite allows one process at a time: stop `serve` first, or use the admin API.) Docker, from the repository root: `docker build -f packages/library-server/Dockerfile -t chalk-library-server .`
 
+It also keeps the **highlights** of books (registry API §11): the lines of a book's text and the questions linked to
+them, as records an editor and a matcher change one by one (`v1/books/<slug>/lines`, `…/links`), so reading apps get
+them from the library. They are migration step 5 of its database (two tables, `book_lines` and `book_links`), applied
+when the server starts.
+
 Every setting, Postgres and S3 setup, bucket CORS, deploying and security:
 [docs/guides/run-a-library-server.md](../../docs/guides/run-a-library-server.md). Using libraries in the
 reader and the editor: [docs/guides/media-libraries.md](../../docs/guides/media-libraries.md).
diff --git a/packages/library-server/src/adopt.test.ts b/packages/library-server/src/adopt.test.ts
index bcc3684..71c4c10 100644
--- a/packages/library-server/src/adopt.test.ts
+++ b/packages/library-server/src/adopt.test.ts
@@ -356,7 +356,7 @@ describe('adopting: off by default, and a private library', () => {
     mkdirSync(join(dir, 'chalk-books', 'race'), { recursive: true }); writeFileSync(join(dir, ...path.split('/')), bytes);
     // after every statement the app runs, look at what a reader would see
     const states: string[] = [];
-    const watched: Db = { close: () => db.close(), async query<T>(sql: string, params?: unknown[]) {
+    const watched: Db = { close: () => db.close(), begin: (fn) => db.begin(fn), async query<T>(sql: string, params?: unknown[]) {
       const r = await db.query<T>(sql, params);
       const [x] = await db.query<{ status: string; path: string | null }>("SELECT a.status, l.path FROM assets a LEFT JOIN locations l ON l.key = a.key AND l.store = 'library' WHERE a.key = $1", [k.key]);
       if (x) states.push(`${x.status}:${x.path ?? '-'}`);
diff --git a/packages/library-server/src/app.test.ts b/packages/library-server/src/app.test.ts
index 3081e43..cefe7d2 100644
--- a/packages/library-server/src/app.test.ts
+++ b/packages/library-server/src/app.test.ts
@@ -180,7 +180,7 @@ describe('the reference library (disk + PGlite)', () => {
 
   it('POST /v1/assets/current runs one SQL statement however many tags, and uses the tags index', async () => {
     const seen: string[] = [];
-    const counting: Db = { query: (sql, params) => { seen.push(sql); return db.query(sql, params); }, close: async () => {} };
+    const counting: Db = { query: (sql, params) => { seen.push(sql); return db.query(sql, params); }, begin: (fn) => db.begin(fn), close: async () => {} };
     const app2 = createLibraryApp({ db: counting, storage: diskStorage(dir, { uploadBase: BASE }), publicUrl: `${BASE}/files/`, callers: tokenCallers('teacher:t-1') });
     seen.length = 0;
     const res = await app2.fetch(new Request(`${BASE}/v1/assets/current`, { method: 'POST', headers: { Authorization: 'Bearer t-1', 'Content-Type': 'application/json' }, body: JSON.stringify({ tags: Array.from({ length: 300 }, (_, i) => `question:n-${i}`) }) }));
diff --git a/packages/library-server/src/app.ts b/packages/library-server/src/app.ts
index 9e38c52..e0ef0ab 100644
--- a/packages/library-server/src/app.ts
+++ b/packages/library-server/src/app.ts
@@ -13,6 +13,7 @@ import { createAuth, type AuthOptions } from './auth/service.js';
 import type { Db } from './db.js';
 import { adoptedStore, adoptPrefixes, assetAt, registerAdopt } from './adopt.js';
 import { baseOf, registerDelivery, type DeliveryOptions } from './delivery.js';
+import { registerHighlights } from './highlights.js';
 import { servedType, type DiskStorage, type Storage } from './storage.js';
 
 /**
@@ -100,7 +101,7 @@ export function createLibraryApp(o: LibraryOptions) {
   // what this address is, for someone who opens it in a browser
   app.get('/', (c) => c.json({
     name: o.name ?? 'Chalk library', api: 'Chalk registry API v1 (spec/1.2/registry-api.md)',
-    endpoints: ['GET /v1/stores', 'GET /v1/search?q=', 'GET /v1/assets/{key}', 'POST /v1/assets/check', 'POST /v1/assets/current', 'POST /v1/uploads', 'POST /v1/assets', 'GET /v1/files/{key}', 'GET /v1/assets/{key}/link', 'POST /v1/auth/token',
+    endpoints: ['GET /v1/stores', 'GET /v1/search?q=', 'GET /v1/assets/{key}', 'POST /v1/assets/check', 'POST /v1/assets/current', 'POST /v1/uploads', 'POST /v1/assets', 'GET /v1/files/{key}', 'GET /v1/assets/{key}/link', 'GET /v1/books/{slug}/lines?pages=', 'GET /v1/books/{slug}/links?line=', 'POST /v1/auth/token',
       'GET /.well-known/openid-configuration', 'GET /healthz'],
   }));
 
@@ -185,6 +186,7 @@ export function createLibraryApp(o: LibraryOptions) {
   const adopting = { db, storage, prefixes: adoptPrefixes(o.adoptPrefixes), publicUrl: o.publicUrl, publicRead: o.publicRead !== false, maxBytes, types, fail, ensureStore, describe,
     recordOf: async (key: string) => record((await rowOf(key))!, true), sha256Of, base: (c: Context) => baseOf(c, (o as DeliveryOptions).serverUrl) };
   registerAdopt(app, adopting);
+  registerHighlights(app, { db, fail }); // §11: the lines of books and the questions linked to them
 
   // ---- §4 reading ----
   app.get('/v1/assets/:key', async (c) => {
diff --git a/packages/library-server/src/db.ts b/packages/library-server/src/db.ts
index cbaa99b..ddad91c 100644
--- a/packages/library-server/src/db.ts
+++ b/packages/library-server/src/db.ts
@@ -7,6 +7,8 @@ import { mkdirSync, readFileSync } from 'node:fs';
  */
 export interface Db {
   query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+  /** Runs `fn` in one transaction: its queries all happen or none does (an error rolls back). */
+  begin<T>(fn: (query: Db['query']) => Promise<T>): Promise<T>;
   close(): Promise<void>;
 }
 
@@ -33,6 +35,7 @@ export async function openDb(url: string, o: { schema?: string } = {}): Promise<
     const pg = new PGlite({ ...(dir ? { dataDir: dir } : {}), extensions: { pg_trgm } });
     db = {
       async query<T>(sql: string, params: unknown[] = []) { return (await pg.query<T>(sql, params)).rows; },
+      begin: (fn) => pg.transaction((tx) => fn(async <T>(sql: string, params: unknown[] = []) => (await tx.query<T>(sql, params)).rows)),
       async close() { await pg.close(); },
     };
     await migrate(db, (sql) => pg.transaction((tx) => tx.exec(sql)).then(() => undefined));
@@ -47,6 +50,7 @@ export async function openDb(url: string, o: { schema?: string } = {}): Promise<
     const sql = postgres(url, { max: 10, onnotice: () => {}, connection: { search_path: `${schema}, public` } });
     db = {
       async query<T>(text: string, params: unknown[] = []) { return (await sql.unsafe(text, params as never[])) as unknown as T[]; },
+      begin: <T>(fn: (query: Db['query']) => Promise<T>) => sql.begin((tx) => fn(async <R>(text: string, params: unknown[] = []) => (await tx.unsafe(text, params as never[])) as unknown as R[])) as Promise<T>,
       async close() { await sql.end(); },
     };
     await migrate(db, (text) => sql.begin((tx) => tx.unsafe(text).simple()).then(() => undefined));
@@ -74,8 +78,56 @@ ALTER TABLE locations ADD PRIMARY KEY (key, store, path);
 ALTER TABLE locations ADD COLUMN IF NOT EXISTS checked_at timestamptz;
 ALTER TABLE locations ADD COLUMN IF NOT EXISTS missing boolean NOT NULL DEFAULT false;
 INSERT INTO chalk_library_schema (version) VALUES (4);`);
+  // step 5: the highlights of books (registry-api §11), editable records: the lines of a book and the questions linked to them
+  if (!done.has(5)) await exec(`${HIGHLIGHTS_SQL}\nINSERT INTO chalk_library_schema (version) VALUES (5);`);
 }
 
+/** Step 5: book highlights (spec/1.2/registry-api.md §11). Questions are named by their lasting id only (no foreign key: they are manifests). */
+const HIGHLIGHTS_SQL = `
+CREATE TABLE IF NOT EXISTS book_lines (
+  id             uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  book           text NOT NULL,
+  key            text NOT NULL,                   -- the line's lasting name in the book: "<page id>/<hash>/<n>"
+  page_id        text NOT NULL,
+  page_no        integer NOT NULL,
+  idx            integer NOT NULL,                -- place on the page, from 0
+  block          integer NOT NULL,                -- the paragraph
+  kind           text NOT NULL,                   -- body, heading, formula, caption
+  text           text NOT NULL,
+  text_hash      text NOT NULL,
+  chapter_no     integer,
+  chapter_title  text,
+  section        text,
+  rects          jsonb NOT NULL DEFAULT '[]',     -- [{x, y, w, fs}] in page units, one per printed line
+  retired_at     timestamptz,                     -- the text layer no longer has it: kept, so its links are kept
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  updated_at     timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (book, key)
+);
+CREATE INDEX IF NOT EXISTS book_lines_page ON book_lines (book, page_no, idx);
+CREATE INDEX IF NOT EXISTS book_lines_chapter ON book_lines (book, chapter_no);
+CREATE TABLE IF NOT EXISTS book_links (
+  id             uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  book           text NOT NULL,
+  question_id    uuid NOT NULL,                   -- the question manifest's lasting id (spec 1.7)
+  line_id        uuid NOT NULL REFERENCES book_lines (id) ON DELETE CASCADE,
+  role           text NOT NULL DEFAULT 'answers_from',
+  scope          text NOT NULL DEFAULT 'sentence',
+  method         text NOT NULL DEFAULT 'auto',    -- auto (a matcher's) or human
+  status         text NOT NULL DEFAULT 'suggested', -- suggested, confirmed, rejected (a removal remembered)
+  score          real,
+  rationale      text,
+  question_type  text,
+  reviewed_by    text,
+  reviewed_at    timestamptz,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (question_id, line_id, role)
+);
+CREATE INDEX IF NOT EXISTS book_links_line ON book_links (line_id);
+CREATE INDEX IF NOT EXISTS book_links_book ON book_links (book, status);
+CREATE INDEX IF NOT EXISTS book_links_question ON book_links (question_id);
+`;
+
 /**
  * Step 2: the library as its own identity provider (spec/1.2/registry-api.md §10). Not part of the reference
  * registry schema: another registry may issue tokens however it likes. Secrets are kept only as hashes.
diff --git a/packages/library-server/src/highlights.test.ts b/packages/library-server/src/highlights.test.ts
new file mode 100644
index 0000000..3c774dc
--- /dev/null
+++ b/packages/library-server/src/highlights.test.ts
@@ -0,0 +1,172 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createLibraryApp, diskStorage, openDb, planLines, tokenCallers, type Db } from './index.js';
+
+const BASE = 'http://library.test';
+const BOOK = 'physics-9-10-bn';
+const Q1 = '11111111-1111-4111-8111-111111111111';
+const Q2 = '22222222-2222-4222-8222-222222222222';
+
+type Line = { key: string; pageId: string; pageNo: number; idx: number; block: number; kind: string; text: string; textHash: string; chapterNo: number; chapterTitle: string; section: null; rects: { x: number; y: number; w: number; fs: number }[] };
+const line = (pageNo: number, idx: number, block = 0, text = `line ${pageNo}.${idx}`): Line => ({
+  key: `p${pageNo}/${idx}/0`, pageId: `p${pageNo}`, pageNo, idx, block, kind: 'body', text, textHash: `h${pageNo}.${idx}`, chapterNo: 1, chapterTitle: 'Physical quantities', section: null,
+  rects: [{ x: 100, y: 100 + idx * 30, w: 500, fs: 18 }],
+});
+
+describe('book highlights (registry-api §11)', () => {
+  let db: Db, app: ReturnType<typeof createLibraryApp>;
+  const call = async (method: string, path: string, body?: unknown, token = 'author-t') => {
+    const res = await app.fetch(new Request(`${BASE}${path}`, { method, headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) }));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- answers of many shapes, checked by the assertions
+    const answer = (await res.json()) as any;
+    return { status: res.status, body: answer };
+  };
+  const b = (p: string) => `/v1/books/${BOOK}${p}`;
+  const ids = async () => Object.fromEntries(((await call('GET', b('/lines/all?retired=1'))).body.items as { id: string; key: string }[]).map((l) => [l.key, l.id]));
+
+  beforeAll(async () => { db = await openDb('pglite:'); }, 60_000);
+  afterAll(async () => { await db.close(); });
+  beforeEach(async () => {
+    await db.query('DELETE FROM book_links'); await db.query('DELETE FROM book_lines');
+    app = createLibraryApp({ db, storage: diskStorage(mkdtempSync(join(tmpdir(), 'chalk-hl-')), { uploadBase: BASE }), publicUrl: `${BASE}/files/`, callers: tokenCallers('author:author-t'), publicRead: false });
+    await call('POST', b('/lines/sync'), { lines: [line(6, 0), line(6, 1), line(6, 2, 1), line(7, 0)] });
+  });
+
+  it('reads need a token on a private library, writes need author', async () => {
+    expect((await call('GET', b('/lines?pages=6'), undefined, '')).status).toBe(401);
+    expect((await call('POST', b('/lines/sync'), { lines: [] }, '')).status).toBe(401);
+    expect((await call('GET', '/v1/books/-bad/lines?pages=6')).status).toBe(400);
+  });
+
+  it('sync adds, changes, retires and revives lines by key; a re-run changes nothing', async () => {
+    const again = await call('POST', b('/lines/sync'), { lines: [line(6, 0), line(6, 1), line(6, 2, 1), line(7, 0)] });
+    expect(again.body).toEqual({ added: 0, changed: 0, retired: 0, revived: 0, linksRetired: 0 });
+    const moved = { ...line(6, 1), idx: 5 };
+    const r = await call('POST', b('/lines/sync'), { lines: [line(6, 0), moved, line(8, 0)] });
+    expect(r.body).toMatchObject({ added: 1, changed: 1, retired: 2, revived: 0 });
+    const back = await call('POST', b('/lines/sync'), { lines: [line(6, 0), moved, line(8, 0), line(7, 0)] });
+    expect(back.body).toMatchObject({ added: 0, revived: 1, retired: 0 });
+  });
+
+  it('planLines matches the dashboard\'s plan: no change, a moved line, a missing one', () => {
+    const stored = [{ id: 'a', key: 'p6/0/0', retiredAt: null, pageNo: 6, idx: 0, block: 0, kind: 'body', chapterNo: 1, chapterTitle: 'Physical quantities', section: null, rects: line(6, 0).rects }];
+    expect(planLines(stored, [line(6, 0)])).toMatchObject({ write: [], retire: [] });
+    expect(planLines(stored, [])).toMatchObject({ retire: ['p6/0/0'] });
+  });
+
+  it('a person tags a line: confirmed and theirs; the page shows counts by kind; a reader may ask for linked lines only', async () => {
+    const L = await ids();
+    const add = await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/0/0'], questionType: 'mcq', by: 'rafi' });
+    expect(add.status).toBe(201);
+    expect(add.body).toMatchObject({ questionId: Q1, method: 'human', status: 'confirmed', reviewedBy: 'rafi', questionType: 'mcq', line: { key: 'p6/0/0', pageNo: 6 } });
+    const page = (await call('GET', b('/lines?pages=6,7'))).body.pages;
+    expect(page['6']).toHaveLength(3);
+    expect(page['6'][0]).toMatchObject({ id: L['p6/0/0'], links: 1, suggested: 0, typeCounts: { mcq: { confirmed: 1, suggested: 0 } } });
+    expect(page['6'][0].textHash).toBeUndefined();
+    expect((await call('GET', b('/lines?pages=6&linked=1'))).body.pages['6']).toHaveLength(1);
+    expect((await call('GET', b('/pages/counts'))).body.counts).toEqual({ '6': 1 });
+    expect((await call('GET', b('/chapters'))).body.items).toEqual([{ no: 1, title: 'Physical quantities' }]);
+  });
+
+  it('taking a link off keeps it as a rejected row the readers never see', async () => {
+    const L = await ids();
+    const add = await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/0/0'], by: 'rafi' });
+    expect((await call('DELETE', b(`/links/${add.body.id}`), { by: 'rafi' })).body).toEqual({ removed: 1 });
+    expect((await call('GET', b(`/links?line=${L['p6/0/0']}`))).body.items).toEqual([]);
+    expect((await call('GET', b('/lines?pages=6'))).body.pages['6'][0].links).toBe(0);
+    const all = (await call('GET', b('/links/all?rejected=1'))).body.items;
+    expect(all).toHaveLength(1);
+    expect(all[0]).toMatchObject({ status: 'rejected', method: 'human' });
+    // the matcher may not place a question a person took a tag off
+    expect((await call('POST', b('/links/place'), { questionId: Q1, proposals: [{ lineId: L['p6/1/0'], role: 'answers_from' }] })).body).toEqual({ placed: 0 });
+  });
+
+  it('the matcher places a question only while it is in the pool; one row per line; retired lines skipped', async () => {
+    const L = await ids();
+    const place = await call('POST', b('/links/place'), { questionId: Q2, questionType: 'cq', proposals: [
+      { lineId: L['p6/0/0'], role: 'answers_from', score: 0.9, rationale: 'same words' }, { lineId: L['p6/0/0'], role: 'tests_concept' }, { lineId: L['p6/1/0'], role: 'answers_from', score: 0.5 }] });
+    expect(place.body).toEqual({ placed: 2 });
+    expect((await call('POST', b('/links/place'), { questionId: Q2, proposals: [{ lineId: L['p7/0/0'], role: 'answers_from' }] })).body).toEqual({ placed: 0 });
+    const q = (await call('POST', '/v1/highlights/questions', { questionIds: [Q1, Q2] })).body.items;
+    expect(q).toEqual({ [Q1]: { live: 0, human: false, any: false }, [Q2]: { live: 2, human: false, any: true } });
+    expect((await call('GET', '/v1/highlights/tagged')).body.questionIds).toEqual([Q2]);
+    // confirmed first, then by score
+    const on = (await call('GET', b(`/links?line=${L['p6/0/0']}&paragraph=1`))).body.items;
+    expect(on.map((l: { line: { key: string } }) => l.line.key)).toEqual(['p6/0/0', 'p6/1/0'].slice(0, on.length));
+  });
+
+  it('a re-index retires the matcher\'s links on lines that went, and keeps a person\'s (listed as orphaned)', async () => {
+    const L = await ids();
+    await call('POST', b('/links/place'), { questionId: Q2, proposals: [{ lineId: L['p7/0/0'], role: 'answers_from' }] });
+    await call('POST', b('/links'), { questionId: Q1, lineId: L['p7/0/0'], by: 'rafi' });
+    const r = await call('POST', b('/lines/sync'), { lines: [line(6, 0), line(6, 1), line(6, 2, 1)] });
+    expect(r.body).toMatchObject({ retired: 1, linksRetired: 1 });
+    const orphaned = (await call('GET', b('/links/orphaned'))).body.items;
+    expect(orphaned).toHaveLength(1);
+    expect(orphaned[0]).toMatchObject({ questionId: Q1, line: { key: 'p7/0/0' } });
+    expect(orphaned[0].line.retiredAt).not.toBeNull();
+    expect((await call('POST', b('/links'), { questionId: Q1, lineId: L['p7/0/0'], by: 'rafi' })).status).toBe(409);
+  });
+
+  it('moving a link onto a pair the question already has merges into it', async () => {
+    const L = await ids();
+    const a = await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/0/0'], by: 'rafi' });
+    const other = await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/1/0'], by: 'rafi' });
+    const moved = await call('PATCH', b(`/links/${a.body.id}`), { lineId: L['p6/1/0'], by: 'mim' });
+    expect(moved.body).toMatchObject({ id: other.body.id, status: 'confirmed', reviewedBy: 'mim' });
+    expect((await call('GET', b('/links/all?rejected=1'))).body.items).toHaveLength(1);
+    const role = await call('PATCH', b(`/links/${other.body.id}`), { role: 'formula_source', by: 'mim' });
+    expect(role.body).toMatchObject({ role: 'formula_source', method: 'human' });
+    expect((await call('PATCH', b('/links/33333333-3333-4333-8333-333333333333'), { by: 'mim' })).status).toBe(404);
+  });
+
+  it('moves and takes off every link of a line (or its paragraph)', async () => {
+    const L = await ids();
+    await call('POST', b('/links/place'), { questionId: Q2, proposals: [{ lineId: L['p6/0/0'], role: 'answers_from' }] });
+    await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/0/0'], by: 'rafi' });
+    await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/2/0'], by: 'rafi' });
+    expect((await call('POST', b(`/lines/${L['p6/0/0']}/links/move`), { to: L['p6/2/0'], by: 'mim' })).body).toEqual({ moved: 1 });
+    const at = (await call('GET', b(`/links?line=${L['p6/2/0']}`))).body.items;
+    expect(at.map((l: { questionId: string }) => l.questionId).sort()).toEqual([Q1, Q2]);
+    // p6/0 and p6/1 are one paragraph (block 0); p6/2 is another
+    expect((await call('POST', b(`/lines/${L['p6/1/0']}/links/remove`), { paragraph: true, by: 'mim' })).body).toEqual({ removed: 0 });
+    expect((await call('POST', b(`/lines/${L['p6/2/0']}/links/remove`), { by: 'mim' })).body).toEqual({ removed: 2 });
+  });
+
+  it('a question\'s highlight grows, shrinks and moves; a line taken off is remembered', async () => {
+    const L = await ids();
+    await call('POST', b('/links/place'), { questionId: Q1, proposals: [{ lineId: L['p6/0/0'], role: 'answers_from' }, { lineId: L['p6/1/0'], role: 'answers_from' }] });
+    const r = await call('PUT', b(`/questions/${Q1}/lines`), { role: 'answers_from', add: [L['p6/2/0']], remove: [L['p6/0/0'], L['p7/0/0']], questionType: 'mcq', by: 'rafi' });
+    expect(r.status).toBe(200);
+    expect(r.body.items.map((l: { line: { key: string } }) => l.line.key)).toEqual(['p6/1/0', 'p6/2/0']);
+    expect(r.body.items.every((l: { method: string; status: string }) => l.method === 'human' && l.status === 'confirmed')).toBe(true);
+    const rejected = (await call('GET', b('/links/all?rejected=1'))).body.items.filter((l: { status: string }) => l.status === 'rejected');
+    expect(rejected.map((l: { line: { key: string } }) => l.line.key).sort()).toEqual(['p6/0/0', 'p7/0/0']);
+    expect((await call('GET', b(`/links?question=${Q1}`))).body.items).toHaveLength(2);
+    expect((await call('PUT', b(`/questions/${Q1}/lines`), { role: 'answers_from', add: [], remove: [], by: 'rafi' })).status).toBe(400);
+    expect((await call('PUT', b(`/questions/${Q1}/lines`), { role: 'answers_from', add: [L['p6/0/0']], remove: [L['p6/0/0']], by: 'rafi' })).status).toBe(400);
+  });
+
+  it('review lists links in book order with a total', async () => {
+    const L = await ids();
+    await call('POST', b('/links/place'), { questionId: Q2, proposals: [{ lineId: L['p7/0/0'], role: 'answers_from' }, { lineId: L['p6/0/0'], role: 'answers_from' }] });
+    const r = (await call('GET', b('/links?status=suggested&limit=1'))).body;
+    expect(r.total).toBe(2);
+    expect(r.items).toHaveLength(1);
+    expect(r.items[0].line.key).toBe('p6/0/0');
+  });
+
+  it('import copies lines and links with their ids', async () => {
+    const lineId = '44444444-4444-4444-8444-444444444444', linkId = '55555555-5555-4555-8555-555555555555';
+    const r = await call('POST', '/v1/books/other-book/import', {
+      lines: [{ ...line(3, 0), id: lineId, retiredAt: null }],
+      links: [{ id: linkId, questionId: Q1, lineId, role: 'answers_from', scope: 'sentence', method: 'auto', status: 'suggested', score: 0.7, rationale: 'x', questionType: 'mcq', reviewedBy: null, reviewedAt: null, createdAt: '2026-10-30T00:00:00Z' }],
+    });
+    expect(r.body).toEqual({ lines: 1, links: 1 });
+    const got = (await call('GET', `/v1/books/other-book/links?line=${lineId}`)).body.items;
+    expect(got[0]).toMatchObject({ id: linkId, score: 0.7, questionType: 'mcq' });
+    expect((await call('POST', '/v1/books/other-book/import', { lines: [], links: [{ id: linkId, questionId: Q1, lineId: '66666666-6666-4666-8666-666666666666', role: 'answers_from', scope: 'sentence', method: 'auto', status: 'suggested' }] })).status).toBe(404);
+  });
+});
diff --git a/packages/library-server/src/highlights.ts b/packages/library-server/src/highlights.ts
new file mode 100644
index 0000000..ae61ce4
--- /dev/null
+++ b/packages/library-server/src/highlights.ts
@@ -0,0 +1,467 @@
+import type { Context, Hono } from 'hono';
+import { z } from 'zod';
+import { requireRole, type AuthVariables } from './auth/guard.js';
+import type { Db } from './db.js';
+
+/**
+ * The highlights of books (spec/1.2/registry-api.md §11): the lines of a book's text and the questions linked to them,
+ * as records that change one by one. An editor adds, moves and takes off links; a matcher suggests them; reading apps
+ * ask for the lines of the pages they show. Reads need `reader`, writes `author`.
+ *
+ * A rejected link is kept: it is the memory that a pair was taken off, so a matcher never puts it back. A link is a
+ * person's decision when its method is `human`, it was reviewed, or it is confirmed; a question with one is never
+ * placed by a matcher (`links/place`).
+ */
+
+type Query = Db['query'];
+type Fail = (c: Context, status: number, code: string, message: string) => Response;
+
+const SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const ROLES = ['answers_from', 'tests_concept', 'uses_figure', 'formula_source'] as const;
+const STATUSES = ['suggested', 'confirmed', 'rejected'] as const;
+const SCOPES = ['sentence', 'paragraph', 'section'] as const;
+/** The most lines one change of a question's highlight may name: a highlight is a few lines, not a chapter. */
+export const MAX_LINE_CHANGES = 200;
+
+const uuid = z.string().uuid();
+const by = z.string().min(1).max(200);
+const role = z.enum(ROLES);
+const scope = z.enum(SCOPES);
+const questionType = z.string().min(1).max(40).optional();
+const rect = z.object({ x: z.number(), y: z.number(), w: z.number(), fs: z.number() });
+const lineIn = z.object({
+  key: z.string().min(1).max(300), pageId: z.string().min(1).max(200), pageNo: z.number().int().min(0), idx: z.number().int().min(0), block: z.number().int().min(0),
+  kind: z.string().min(1).max(40), text: z.string().max(20_000), textHash: z.string().min(1).max(200),
+  chapterNo: z.number().int().nullable().optional(), chapterTitle: z.string().max(500).nullable().optional(), section: z.string().max(2000).nullable().optional(),
+  rects: z.array(rect).max(200),
+});
+const syncSchema = z.object({ lines: z.array(lineIn).max(200_000) });
+const addSchema = z.object({ questionId: uuid, lineId: uuid, role: role.optional(), scope: scope.optional(), questionType, by });
+const patchSchema = z.object({ status: z.enum(STATUSES).optional(), role: role.optional(), scope: scope.optional(), lineId: uuid.optional(), by });
+const bySchema = z.object({ by });
+const removeSchema = z.object({ paragraph: z.boolean().optional(), by });
+const moveSchema = z.object({ to: uuid, by });
+const linesSchema = z.object({ role, add: z.array(uuid), remove: z.array(uuid), scope: scope.optional(), questionType, by });
+const placeSchema = z.object({
+  questionId: uuid, questionType,
+  proposals: z.array(z.object({ lineId: uuid, role, scope: scope.optional(), score: z.number().nullable().optional(), rationale: z.string().max(2000).nullable().optional() })).max(500),
+});
+const importSchema = z.object({
+  lines: z.array(lineIn.extend({ id: uuid, retiredAt: z.string().nullable().optional() })).max(200_000),
+  links: z.array(z.object({
+    id: uuid, questionId: uuid, lineId: uuid, role: z.string().min(1).max(40), scope: z.string().min(1).max(40), method: z.string().min(1).max(20), status: z.enum(STATUSES),
+    score: z.number().nullable().optional(), rationale: z.string().nullable().optional(), questionType: z.string().nullable().optional(),
+    reviewedBy: z.string().nullable().optional(), reviewedAt: z.string().nullable().optional(), createdAt: z.string().optional(),
+  })).max(500_000),
+});
+const questionsSchema = z.object({ questionIds: z.array(uuid).max(5000) });
+
+/** A person's decision, on the links table as `k`. */
+const HUMAN = `(k.method = 'human' OR k.reviewed_by IS NOT NULL OR k.status = 'confirmed')`;
+
+const LINE_COLS = `l.id, l.key, l.page_id AS "pageId", l.page_no AS "pageNo", l.idx, l.block, l.kind, l.text, l.text_hash AS "textHash",
+  l.chapter_no AS "chapterNo", l.chapter_title AS "chapterTitle", l.section, l.rects, l.retired_at AS "retiredAt"`;
+const LINK_COLS = `k.id, k.question_id AS "questionId", k.line_id AS "lineId", k.role, k.scope, k.method, k.status, k.score, k.rationale,
+  k.question_type AS "questionType", k.reviewed_by AS "reviewedBy", k.reviewed_at AS "reviewedAt", k.created_at AS "createdAt",
+  jsonb_build_object('id', l.id, 'key', l.key, 'pageId', l.page_id, 'pageNo', l.page_no, 'idx', l.idx, 'block', l.block, 'text', l.text,
+    'chapterNo', l.chapter_no, 'retiredAt', l.retired_at) AS line`;
+const LINKS_FROM = `FROM book_links k JOIN book_lines l ON l.id = k.line_id`;
+
+type LineRow = { id: string; key: string; retiredAt: string | Date | null; pageNo: number; idx: number; block: number; kind: string; chapterNo: number | null; chapterTitle: string | null; section: string | null; rects: unknown };
+
+class HighlightError extends Error {
+  constructor(readonly status: 400 | 404 | 409, readonly code: string, message: string) { super(message); }
+}
+const notFound = (what: string) => new HighlightError(404, 'not_found', what);
+const retired = () => new HighlightError(409, 'conflict', 'that line is no longer in the book');
+
+/** Takes the lock of a question for the rest of the transaction: writes to one question happen one after another. */
+const lockQuestion = (q: Query, id: string) => q(`SELECT pg_advisory_xact_lock(hashtext($1))`, [`chalk-highlights:q:${id}`]);
+
+async function linkView(q: Query, id: string) {
+  return (await q(`SELECT ${LINK_COLS} ${LINKS_FROM} WHERE k.id = $1`, [id]))[0]!;
+}
+
+/** The line, if the book has it; `live` also refuses a retired one. */
+async function lineOf(q: Query, book: string, id: string, live: boolean) {
+  const [l] = await q<{ id: string; retired: boolean }>(`SELECT id, retired_at IS NOT NULL AS retired FROM book_lines WHERE id = $1 AND book = $2`, [id, book]);
+  if (!l) throw notFound('that line is not in this book');
+  if (live && l.retired) throw retired();
+  return l;
+}
+
+/** The lines a change on one line covers: the line, or (`paragraph`) every live line of its paragraph. */
+async function covered(q: Query, book: string, lineId: string, paragraph: boolean): Promise<string[]> {
+  const rows = paragraph
+    ? await q<{ id: string }>(`SELECT x.id FROM book_lines x JOIN book_lines l ON l.id = $2 AND l.book = $1
+        WHERE x.book = $1 AND x.page_no = l.page_no AND x.block = l.block AND x.retired_at IS NULL`, [book, lineId])
+    : await q<{ id: string }>(`SELECT id FROM book_lines WHERE book = $1 AND id = $2`, [book, lineId]);
+  return rows.map((r) => r.id);
+}
+
+/** Boxes compared by their numbers: jsonb keeps an object's keys in its own order, so the JSON text of the same box differs. */
+const boxes = (v: unknown) => JSON.stringify(Array.isArray(v) ? v.map((r: { x?: unknown; y?: unknown; w?: unknown; fs?: unknown }) => [r.x, r.y, r.w, r.fs]) : v);
+const sameRects = (a: unknown, b: unknown) => boxes(a) === boxes(b);
+
+/** What a sync would do: lines matched by key; one not sent any more is retired, not deleted. */
+export function planLines(stored: LineRow[], lines: z.infer<typeof lineIn>[]) {
+  const have = new Map(stored.map((r) => [r.key, r]));
+  const want = new Set(lines.map((r) => r.key));
+  const write: z.infer<typeof lineIn>[] = [];
+  let added = 0, revived = 0;
+  for (const r of lines) {
+    const h = have.get(r.key);
+    if (!h) { write.push(r); added++; continue; }
+    if (h.retiredAt || h.pageNo !== r.pageNo || h.idx !== r.idx || h.block !== r.block || h.kind !== r.kind || h.chapterNo !== (r.chapterNo ?? null)
+      || h.chapterTitle !== (r.chapterTitle ?? null) || h.section !== (r.section ?? null) || !sameRects(h.rects, r.rects)) {
+      write.push(r);
+      if (h.retiredAt) revived++;
+    }
+  }
+  const retire = stored.filter((s) => !want.has(s.key) && !s.retiredAt).map((s) => s.key);
+  return { write, added, changed: write.length - added - revived, revived, retire };
+}
+
+const CHUNK = 1000;
+const chunks = <T>(list: T[]) => Array.from({ length: Math.ceil(list.length / CHUNK) }, (_, i) => list.slice(i * CHUNK, (i + 1) * CHUNK));
+const LINE_RECORDSET = `x(id uuid, key text, "pageId" text, "pageNo" int, idx int, block int, kind text, text text, "textHash" text,
+  "chapterNo" int, "chapterTitle" text, section text, rects jsonb, "retiredAt" timestamptz)`;
+
+export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: { db: Db; fail: Fail }) {
+  const { db, fail } = o;
+  const run = async (c: Context, role: 'reader' | 'author', fn: (book: string) => Promise<Response>) => {
+    const denied = requireRole(c, role); if (denied) return denied;
+    const book = c.req.param('slug') ?? '';
+    if (!SLUG.test(book)) return fail(c, 400, 'invalid', 'not a book slug');
+    try { return await fn(book); } catch (err) {
+      if (err instanceof HighlightError) return fail(c, err.status, err.code, err.message);
+      throw err;
+    }
+  };
+  const parse = async <T>(c: Context, schema: z.ZodType<T>): Promise<T> => {
+    const r = schema.safeParse(await c.req.json().catch(() => null));
+    if (!r.success) throw new HighlightError(400, 'invalid', r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '));
+    return r.data;
+  };
+  const int = (v: string | undefined) => (v !== undefined && /^\d{1,9}$/.test(v) ? Number(v) : undefined);
+  const statusFilter = (c: Context) => (c.req.query('status') === 'confirmed' ? `k.status = 'confirmed'` : `k.status <> 'rejected'`);
+
+  // ---- §11.2 reading ----
+
+  app.get('/v1/books/:slug/lines', (c) => run(c, 'reader', async (book) => {
+    const pages = [...new Set((c.req.query('pages') ?? '').split(',').map((s) => int(s.trim())).filter((n): n is number => n !== undefined))];
+    if (pages.length > 50) throw new HighlightError(400, 'invalid', 'at most 50 pages at once');
+    const out: Record<string, unknown[]> = Object.fromEntries(pages.map((p) => [String(p), []]));
+    if (!pages.length) return c.json({ pages: out });
+    const lines = await db.query<Record<string, unknown> & { id: string; pageNo: number }>(
+      `SELECT ${LINE_COLS} FROM book_lines l WHERE l.book = $1 AND l.page_no = ANY($2::int[]) AND l.retired_at IS NULL ORDER BY l.page_no, l.idx`, [book, pages]);
+    const links = await db.query<{ lineId: string; status: string; type: string | null }>(
+      `SELECT k.line_id AS "lineId", k.status, k.question_type AS type ${LINKS_FROM} WHERE k.book = $1 AND l.page_no = ANY($2::int[]) AND l.retired_at IS NULL AND ${statusFilter(c)}`, [book, pages]);
+    const byLine = new Map<string, { links: number; suggested: number; typeCounts: Record<string, { confirmed: number; suggested: number }> }>();
+    for (const k of links) {
+      const s = byLine.get(k.lineId) ?? { links: 0, suggested: 0, typeCounts: {} };
+      s.links++;
+      if (k.status === 'suggested') s.suggested++;
+      if (k.type) {
+        const t = (s.typeCounts[k.type] ??= { confirmed: 0, suggested: 0 });
+        if (k.status === 'confirmed') t.confirmed++; else t.suggested++;
+      }
+      byLine.set(k.lineId, s);
+    }
+    const linked = c.req.query('linked') === '1';
+    for (const l of lines) {
+      const s = byLine.get(l.id) ?? { links: 0, suggested: 0, typeCounts: {} };
+      if (linked && !s.links) continue;
+      const rest: Record<string, unknown> = { ...l };
+      delete rest.textHash;
+      delete rest.retiredAt;
+      out[String(l.pageNo)]!.push({ ...rest, ...s });
+    }
+    return c.json({ pages: out });
+  }));
+
+  app.get('/v1/books/:slug/lines/all', (c) => run(c, 'reader', async (book) => {
+    const chapter = int(c.req.query('chapter'));
+    const items = await db.query(
+      `SELECT ${LINE_COLS} FROM book_lines l WHERE l.book = $1 ${c.req.query('retired') === '1' ? '' : 'AND l.retired_at IS NULL'} ${chapter === undefined ? '' : 'AND l.chapter_no = $2'}
+       ORDER BY l.page_no, l.idx, l.key`, chapter === undefined ? [book] : [book, chapter]);
+    return c.json({ items });
+  }));
+
+  app.get('/v1/books/:slug/chapters', (c) => run(c, 'reader', async (book) => {
+    const items = await db.query(`SELECT DISTINCT chapter_no AS no, chapter_title AS title FROM book_lines WHERE book = $1 AND chapter_no IS NOT NULL ORDER BY chapter_no`, [book]);
+    return c.json({ items });
+  }));
+
+  app.get('/v1/books/:slug/pages/counts', (c) => run(c, 'reader', async (book) => {
+    const rows = await db.query<{ pageNo: number; n: number }>(
+      `SELECT l.page_no AS "pageNo", count(DISTINCT k.question_id)::int AS n ${LINKS_FROM} WHERE k.book = $1 AND l.retired_at IS NULL AND k.status <> 'rejected' GROUP BY l.page_no`, [book]);
+    return c.json({ counts: Object.fromEntries(rows.map((r) => [String(r.pageNo), r.n])) });
+  }));
+
+  app.get('/v1/books/:slug/links', (c) => run(c, 'reader', async (book) => {
+    const line = c.req.query('line'), question = c.req.query('question');
+    if (line !== undefined) {
+      if (!uuid.safeParse(line).success) throw new HighlightError(400, 'invalid', 'line: not a uuid');
+      const where = c.req.query('paragraph') === '1'
+        ? `l.id IN (SELECT x.id FROM book_lines x JOIN book_lines y ON y.id = $2 AND y.book = $1 WHERE x.book = $1 AND x.page_no = y.page_no AND x.block = y.block AND x.retired_at IS NULL)`
+        : `l.id = $2`;
+      const items = await db.query(`SELECT ${LINK_COLS} ${LINKS_FROM} WHERE k.book = $1 AND ${where} AND ${statusFilter(c)}
+        ORDER BY (k.status = 'confirmed') DESC, k.score DESC, k.created_at DESC`, [book, line]);
+      return c.json({ items });
+    }
+    if (question !== undefined) {
+      if (!uuid.safeParse(question).success) throw new HighlightError(400, 'invalid', 'question: not a uuid');
+      return c.json({ items: await linksOfQuestion(db.query, book, question) });
+    }
+    // review: by chapter, status and method, in book order
+    const where = ['k.book = $1'], params: unknown[] = [book];
+    const chapter = int(c.req.query('chapter'));
+    if (chapter) { params.push(chapter); where.push(`l.chapter_no = $${params.length}`); }
+    const status = c.req.query('status');
+    if (status && (STATUSES as readonly string[]).includes(status)) { params.push(status); where.push(`k.status = $${params.length}`); } else where.push(`k.status <> 'rejected'`);
+    const method = c.req.query('method');
+    if (method) { params.push(method); where.push(`k.method = $${params.length}`); }
+    const cond = where.join(' AND ');
+    const limit = Math.min(int(c.req.query('limit')) ?? 50, 200), offset = int(c.req.query('offset')) ?? 0;
+    const [counted, items] = await Promise.all([
+      db.query<{ total: number }>(`SELECT count(*)::int AS total ${LINKS_FROM} WHERE ${cond}`, params),
+      db.query(`SELECT ${LINK_COLS} ${LINKS_FROM} WHERE ${cond} ORDER BY l.page_no, l.idx, k.created_at DESC LIMIT ${limit} OFFSET ${offset}`, params),
+    ]);
+    return c.json({ items, total: counted[0]?.total ?? 0 });
+  }));
+
+  app.get('/v1/books/:slug/links/all', (c) => run(c, 'reader', async (book) => {
+    const items = await db.query(`SELECT ${LINK_COLS} ${LINKS_FROM} WHERE k.book = $1 ${c.req.query('rejected') === '1' ? '' : `AND k.status <> 'rejected'`} ORDER BY k.question_id, l.key, k.role`, [book]);
+    return c.json({ items });
+  }));
+
+  app.get('/v1/books/:slug/links/orphaned', (c) => run(c, 'reader', async (book) => {
+    const items = await db.query(`SELECT ${LINK_COLS} ${LINKS_FROM} WHERE k.book = $1 AND ${HUMAN} AND k.status <> 'rejected' AND l.retired_at IS NOT NULL ORDER BY l.page_no, l.idx`, [book]);
+    return c.json({ items });
+  }));
+
+  app.post('/v1/highlights/questions', async (c) => {
+    const denied = requireRole(c, 'reader'); if (denied) return denied;
+    const r = questionsSchema.safeParse(await c.req.json().catch(() => null));
+    if (!r.success) return fail(c, 400, 'invalid', r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '));
+    const rows = await db.query<{ id: string; live: number; human: boolean }>(
+      `SELECT k.question_id AS id, (count(*) FILTER (WHERE k.status <> 'rejected'))::int AS live, bool_or(${HUMAN}) AS human
+       FROM book_links k WHERE k.question_id = ANY($1::uuid[]) GROUP BY k.question_id`, [r.data.questionIds]);
+    const found = new Map(rows.map((x) => [x.id, x]));
+    return c.json({ items: Object.fromEntries(r.data.questionIds.map((id) => [id, { live: found.get(id)?.live ?? 0, human: found.get(id)?.human ?? false, any: found.has(id) }])) });
+  });
+
+  app.get('/v1/highlights/tagged', async (c) => {
+    const denied = requireRole(c, 'reader'); if (denied) return denied;
+    const rows = await db.query<{ id: string }>(`SELECT DISTINCT question_id AS id FROM book_links WHERE status <> 'rejected' ORDER BY 1`);
+    return c.json({ questionIds: rows.map((r) => r.id) });
+  });
+
+  // ---- §11.3 writing ----
+
+  app.post('/v1/books/:slug/lines/sync', (c) => run(c, 'author', async (book) => {
+    const { lines } = await parse(c, syncSchema);
+    const result = await db.begin(async (q) => {
+      // one sync of a book at a time
+      await q(`SELECT pg_advisory_xact_lock(hashtext($1))`, [`chalk-highlights:sync:${book}`]);
+      const stored = await q<LineRow>(`SELECT ${LINE_COLS} FROM book_lines l WHERE l.book = $1`, [book]);
+      const plan = planLines(stored, lines);
+      for (const part of chunks(plan.write)) {
+        await q(`INSERT INTO book_lines (book, key, page_id, page_no, idx, block, kind, text, text_hash, chapter_no, chapter_title, section, rects)
+          SELECT $1, x.key, x."pageId", x."pageNo", x.idx, x.block, x.kind, x.text, x."textHash", x."chapterNo", x."chapterTitle", x.section, coalesce(x.rects, '[]')
+          FROM jsonb_to_recordset($2::jsonb) AS ${LINE_RECORDSET}
+          ON CONFLICT (book, key) DO UPDATE SET page_id = EXCLUDED.page_id, page_no = EXCLUDED.page_no, idx = EXCLUDED.idx, block = EXCLUDED.block, kind = EXCLUDED.kind,
+            chapter_no = EXCLUDED.chapter_no, chapter_title = EXCLUDED.chapter_title, section = EXCLUDED.section, rects = EXCLUDED.rects, retired_at = NULL, updated_at = now()`,
+        [book, JSON.stringify(part)]);
+      }
+      for (const part of chunks(plan.retire)) await q(`UPDATE book_lines SET retired_at = now(), updated_at = now() WHERE book = $1 AND retired_at IS NULL AND key = ANY($2::text[])`, [book, part]);
+      // a person's link on a line that is gone is kept (links/orphaned lists it); a matcher's alone is turned down, and its question can be placed again
+      const gone = await q(`UPDATE book_links k SET status = 'rejected', rationale = 'retired: the line is no longer in the book after re-indexing'
+        WHERE k.book = $1 AND NOT ${HUMAN} AND k.status <> 'rejected' AND k.line_id IN (SELECT id FROM book_lines WHERE book = $1 AND retired_at IS NOT NULL) RETURNING k.id`, [book]);
+      return { added: plan.added, changed: plan.changed, retired: plan.retire.length, revived: plan.revived, linksRetired: gone.length };
+    });
+    return c.json(result);
+  }));
+
+  app.post('/v1/books/:slug/links', (c) => run(c, 'author', async (book) => {
+    const b = await parse(c, addSchema);
+    const id = await db.begin(async (q) => {
+      await lockQuestion(q, b.questionId);
+      await lineOf(q, book, b.lineId, true);
+      const [row] = await q<{ id: string }>(`INSERT INTO book_links (book, question_id, line_id, role, scope, method, status, question_type, reviewed_by, reviewed_at)
+        VALUES ($1, $2, $3, $4, $5, 'human', 'confirmed', $6, $7, now())
+        ON CONFLICT (question_id, line_id, role) DO UPDATE SET status = 'confirmed', scope = EXCLUDED.scope, method = 'human',
+          question_type = coalesce(EXCLUDED.question_type, book_links.question_type), reviewed_by = EXCLUDED.reviewed_by, reviewed_at = now()
+        RETURNING id`, [book, b.questionId, b.lineId, b.role ?? 'answers_from', b.scope ?? 'sentence', b.questionType ?? null, b.by]);
+      return row!.id;
+    });
+    return c.json(await linkView(db.query, id), 201);
+  }));
+
+  app.patch('/v1/books/:slug/links/:id', (c) => run(c, 'author', async (book) => {
+    const p = await parse(c, patchSchema);
+    const linkId = c.req.param('id');
+    if (!uuid.safeParse(linkId).success) throw notFound('link not found');
+    const kept = await db.begin(async (q) => {
+      const [cur0] = await q<{ questionId: string }>(`SELECT question_id AS "questionId" FROM book_links WHERE id = $1 AND book = $2`, [linkId, book]);
+      if (!cur0) throw notFound('link not found');
+      await lockQuestion(q, cur0.questionId);
+      const [cur] = await q<{ lineId: string; role: string }>(`SELECT line_id AS "lineId", role FROM book_links WHERE id = $1`, [linkId]);
+      if (!cur) throw notFound('link not found');
+      const set: Record<string, unknown> = { reviewed_by: p.by };
+      if (p.status) set.status = p.status;
+      if (p.role) set.role = p.role;
+      if (p.scope) set.scope = p.scope;
+      // a person who changes what it says (role, scope or line) makes it theirs; confirming a suggestion leaves it the matcher's; turning one down is a person's decision
+      if (p.role || p.scope || p.lineId || p.status === 'rejected') set.method = 'human';
+      if (p.lineId && p.lineId !== cur.lineId) {
+        await lineOf(q, book, p.lineId, true);
+        set.line_id = p.lineId;
+        if (p.status === undefined) set.status = 'confirmed';
+      }
+      const target = (set.line_id as string | undefined) ?? cur.lineId, targetRole = (set.role as string | undefined) ?? cur.role;
+      const [other] = await q<{ id: string }>(`SELECT id FROM book_links WHERE question_id = $1 AND line_id = $2 AND role = $3 AND id <> $4`, [cur0.questionId, target, targetRole, linkId]);
+      if (other) {
+        // the question already has that role on that line: that row is kept, confirmed and the person's, and this one goes
+        await q(`UPDATE book_links SET status = 'confirmed', method = 'human', reviewed_by = $2, reviewed_at = now() WHERE id = $1`, [other.id, p.by]);
+        await q(`DELETE FROM book_links WHERE id = $1`, [linkId]);
+        return other.id;
+      }
+      const cols = Object.keys(set);
+      await q(`UPDATE book_links SET ${cols.map((k, i) => `${k} = $${i + 2}`).join(', ')}, reviewed_at = now() WHERE id = $1`, [linkId, ...cols.map((k) => set[k])]);
+      return linkId;
+    });
+    return c.json(await linkView(db.query, kept));
+  }));
+
+  app.delete('/v1/books/:slug/links/:id', (c) => run(c, 'author', async (book) => {
+    const { by: who } = await parse(c, bySchema);
+    const linkId = c.req.param('id');
+    if (!uuid.safeParse(linkId).success) throw notFound('link not found');
+    const done = await db.query(`UPDATE book_links SET status = 'rejected', method = 'human', reviewed_by = $3, reviewed_at = now() WHERE id = $1 AND book = $2 RETURNING id`, [linkId, book, who]);
+    if (!done.length) throw notFound('link not found');
+    return c.json({ removed: 1 });
+  }));
+
+  app.post('/v1/books/:slug/lines/:id/links/remove', (c) => run(c, 'author', async (book) => {
+    const b = await parse(c, removeSchema);
+    const lineId = c.req.param('id');
+    if (!uuid.safeParse(lineId).success) throw notFound('that line is not in this book');
+    const ids = await covered(db.query, book, lineId, Boolean(b.paragraph));
+    if (!ids.length) throw notFound('that line is not in this book');
+    const gone = await db.query(`UPDATE book_links SET status = 'rejected', method = 'human', reviewed_by = $2, reviewed_at = now()
+      WHERE line_id = ANY($1::uuid[]) AND status <> 'rejected' RETURNING id`, [ids, b.by]);
+    return c.json({ removed: gone.length });
+  }));
+
+  app.post('/v1/books/:slug/lines/:id/links/move', (c) => run(c, 'author', async (book) => {
+    const b = await parse(c, moveSchema);
+    const from = c.req.param('id');
+    if (!uuid.safeParse(from).success) throw notFound('that line is not in this book');
+    if (from === b.to) return c.json({ moved: 0 });
+    const moved = await db.begin(async (q) => {
+      await lineOf(q, book, b.to, true);
+      await lineOf(q, book, from, false);
+      // the questions involved, locked in one order
+      await q(`SELECT pg_advisory_xact_lock(hashtext('chalk-highlights:q:' || x.question_id::text)) FROM (SELECT DISTINCT question_id FROM book_links WHERE line_id = $1 ORDER BY 1) x`, [from]);
+      // the other line already has that tag: it is kept, becomes the person's, and is confirmed if it had been turned down; rejected rows of the old line stay there
+      await q(`UPDATE book_links x SET status = CASE WHEN x.status = 'rejected' THEN 'confirmed' ELSE x.status END, method = 'human', reviewed_by = $3, reviewed_at = now()
+        FROM book_links l WHERE l.line_id = $1 AND l.status <> 'rejected' AND x.line_id = $2 AND x.question_id = l.question_id AND x.role = l.role`, [from, b.to, b.by]);
+      await q(`DELETE FROM book_links l WHERE l.line_id = $1 AND l.status <> 'rejected'
+        AND EXISTS (SELECT 1 FROM book_links x WHERE x.line_id = $2 AND x.question_id = l.question_id AND x.role = l.role)`, [from, b.to]);
+      const rows = await q(`UPDATE book_links SET line_id = $2, method = 'human', reviewed_by = $3, reviewed_at = now() WHERE line_id = $1 AND status <> 'rejected' RETURNING id`, [from, b.to, b.by]);
+      return rows.length;
+    });
+    return c.json({ moved });
+  }));
+
+  app.put('/v1/books/:slug/questions/:question/lines', (c) => run(c, 'author', async (book) => {
+    const b = await parse(c, linesSchema);
+    const questionId = c.req.param('question');
+    if (!uuid.safeParse(questionId).success) throw new HighlightError(400, 'invalid', 'question: not a uuid');
+    const add = [...new Set(b.add)], remove = [...new Set(b.remove)];
+    if (!add.length && !remove.length) throw new HighlightError(400, 'invalid', 'name a line to add or take off');
+    if (add.length + remove.length > MAX_LINE_CHANGES) throw new HighlightError(400, 'invalid', `at most ${MAX_LINE_CHANGES} lines at once`);
+    if (add.some((s) => remove.includes(s))) throw new HighlightError(400, 'invalid', 'a line cannot be added and taken off at once');
+    await db.begin(async (q) => {
+      await lockQuestion(q, questionId);
+      const named = [...add, ...remove];
+      const lines = await q<{ id: string; retired: boolean }>(`SELECT id, retired_at IS NOT NULL AS retired FROM book_lines WHERE book = $1 AND id = ANY($2::uuid[])`, [book, named]);
+      if (lines.length !== named.length) throw notFound('that line is not in this book');
+      if (lines.some((l) => l.retired && add.includes(l.id))) throw retired();
+      // the lines the highlight keeps become the person's
+      await q(`UPDATE book_links SET method = 'human', status = 'confirmed', reviewed_by = $4, reviewed_at = now()
+        WHERE book = $1 AND question_id = $2 AND role = $3 AND status <> 'rejected' AND NOT (line_id = ANY($5::uuid[]))`, [book, questionId, b.role, b.by, remove]);
+      // a line taken off is the person's removal whatever its row was meanwhile (or none), so a matcher never places the question again
+      for (const lineId of remove) await q(`INSERT INTO book_links (book, question_id, line_id, role, scope, method, status, question_type, reviewed_by, reviewed_at)
+        VALUES ($1, $2, $3, $4, $5, 'human', 'rejected', $6, $7, now())
+        ON CONFLICT (question_id, line_id, role) DO UPDATE SET status = 'rejected', method = 'human', reviewed_by = EXCLUDED.reviewed_by, reviewed_at = now()`,
+      [book, questionId, lineId, b.role, b.scope ?? 'sentence', b.questionType ?? null, b.by]);
+      for (const lineId of add) await q(`INSERT INTO book_links (book, question_id, line_id, role, scope, method, status, question_type, reviewed_by, reviewed_at)
+        VALUES ($1, $2, $3, $4, $5, 'human', 'confirmed', $6, $7, now())
+        ON CONFLICT (question_id, line_id, role) DO UPDATE SET status = 'confirmed', method = 'human', reviewed_by = EXCLUDED.reviewed_by, reviewed_at = now(),
+          question_type = coalesce(EXCLUDED.question_type, book_links.question_type)${b.scope ? ', scope = EXCLUDED.scope' : ''}`,
+      [book, questionId, lineId, b.role, b.scope ?? 'sentence', b.questionType ?? null, b.by]);
+    });
+    return c.json({ items: await linksOfQuestion(db.query, book, questionId) });
+  }));
+
+  app.post('/v1/books/:slug/links/place', (c) => run(c, 'author', async (book) => {
+    const b = await parse(c, placeSchema);
+    if (!b.proposals.length) return c.json({ placed: 0 });
+    const placed = await db.begin(async (q) => {
+      await lockQuestion(q, b.questionId);
+      // still in the pool: no live link and no person's decision, in any book
+      const [busy] = await q(`SELECT 1 FROM book_links k WHERE k.question_id = $1 AND (k.status <> 'rejected' OR ${HUMAN}) LIMIT 1`, [b.questionId]);
+      if (busy) return 0;
+      const have = new Set((await q<{ id: string }>(`SELECT line_id AS id FROM book_links WHERE question_id = $1`, [b.questionId])).map((r) => r.id));
+      const live = new Set((await q<{ id: string }>(`SELECT id FROM book_lines WHERE book = $1 AND retired_at IS NULL AND id = ANY($2::uuid[])`, [book, b.proposals.map((p) => p.lineId)])).map((r) => r.id));
+      const once = new Set<string>(); // one row per line, whatever the roles asked for
+      let n = 0;
+      for (const p of b.proposals) {
+        if (!live.has(p.lineId) || have.has(p.lineId) || once.has(p.lineId)) continue;
+        once.add(p.lineId);
+        n += (await q(`INSERT INTO book_links (book, question_id, line_id, role, scope, score, method, status, rationale, question_type)
+          VALUES ($1, $2, $3, $4, $5, $6, 'auto', 'suggested', $7, $8) ON CONFLICT DO NOTHING RETURNING id`,
+        [book, b.questionId, p.lineId, p.role, p.scope ?? 'sentence', p.score ?? null, p.rationale ?? null, b.questionType ?? null])).length;
+      }
+      return n;
+    });
+    return c.json({ placed });
+  }));
+
+  app.post('/v1/books/:slug/import', (c) => run(c, 'author', async (book) => {
+    const b = await parse(c, importSchema);
+    await db.begin(async (q) => {
+      for (const part of chunks(b.lines)) {
+        await q(`INSERT INTO book_lines (id, book, key, page_id, page_no, idx, block, kind, text, text_hash, chapter_no, chapter_title, section, rects, retired_at)
+          SELECT x.id, $1, x.key, x."pageId", x."pageNo", x.idx, x.block, x.kind, x.text, x."textHash", x."chapterNo", x."chapterTitle", x.section, coalesce(x.rects, '[]'), x."retiredAt"
+          FROM jsonb_to_recordset($2::jsonb) AS ${LINE_RECORDSET}
+          ON CONFLICT (id) DO UPDATE SET key = EXCLUDED.key, page_id = EXCLUDED.page_id, page_no = EXCLUDED.page_no, idx = EXCLUDED.idx, block = EXCLUDED.block, kind = EXCLUDED.kind,
+            text = EXCLUDED.text, text_hash = EXCLUDED.text_hash, chapter_no = EXCLUDED.chapter_no, chapter_title = EXCLUDED.chapter_title, section = EXCLUDED.section,
+            rects = EXCLUDED.rects, retired_at = EXCLUDED.retired_at, updated_at = now()
+          WHERE book_lines.book = $1`, [book, JSON.stringify(part)]);
+      }
+      for (const part of chunks(b.links)) {
+        const bad = await q<{ id: string }>(`SELECT x."lineId" AS id FROM jsonb_to_recordset($2::jsonb) AS x("lineId" uuid)
+          WHERE NOT EXISTS (SELECT 1 FROM book_lines l WHERE l.id = x."lineId" AND l.book = $1) LIMIT 1`, [book, JSON.stringify(part)]);
+        if (bad.length) throw notFound(`line ${bad[0]!.id} is not in this book`);
+        await q(`INSERT INTO book_links (id, book, question_id, line_id, role, scope, method, status, score, rationale, question_type, reviewed_by, reviewed_at, created_at)
+          SELECT x.id, $1, x."questionId", x."lineId", x.role, x.scope, x.method, x.status, x.score, x.rationale, x."questionType", x."reviewedBy", x."reviewedAt", coalesce(x."createdAt", now())
+          FROM jsonb_to_recordset($2::jsonb) AS x(id uuid, "questionId" uuid, "lineId" uuid, role text, scope text, method text, status text, score real, rationale text,
+            "questionType" text, "reviewedBy" text, "reviewedAt" timestamptz, "createdAt" timestamptz)
+          ON CONFLICT (id) DO UPDATE SET question_id = EXCLUDED.question_id, line_id = EXCLUDED.line_id, role = EXCLUDED.role, scope = EXCLUDED.scope, method = EXCLUDED.method,
+            status = EXCLUDED.status, score = EXCLUDED.score, rationale = EXCLUDED.rationale, question_type = EXCLUDED.question_type, reviewed_by = EXCLUDED.reviewed_by,
+            reviewed_at = EXCLUDED.reviewed_at, created_at = EXCLUDED.created_at
+          WHERE book_links.book = $1`, [book, JSON.stringify(part)]);
+      }
+    });
+    return c.json({ lines: b.lines.length, links: b.links.length });
+  }));
+}
+
+/** A question's live links on live lines of the book, in book order (what `GET links?question=` and `PUT questions/…/lines` answer). */
+function linksOfQuestion(q: Query, book: string, questionId: string) {
+  return q(`SELECT ${LINK_COLS} ${LINKS_FROM} WHERE k.book = $1 AND k.question_id = $2 AND k.status <> 'rejected' AND l.retired_at IS NULL ORDER BY l.page_no, l.idx, k.role`, [book, questionId]);
+}
diff --git a/packages/library-server/src/index.ts b/packages/library-server/src/index.ts
index af9a239..f0c841b 100644
--- a/packages/library-server/src/index.ts
+++ b/packages/library-server/src/index.ts
@@ -4,6 +4,7 @@ export { s3Storage, diskStorage, servedType, type Storage, type S3Options, type
 export { registerDelivery, FILE_SECONDS, LINK_SECONDS, type DeliveryOptions } from './delivery.js';
 export { scanStorage } from './scan.js';
 export { adoptPrefixes, locate } from './adopt.js';
+export { registerHighlights, planLines, MAX_LINE_CHANGES } from './highlights.js';
 export { libraryFromEnv, tokenCallers } from './config.js';
 export { checkLibrary, type Check } from './conformance.js';
 export { createAuth, checkKeySetup, AuthError, type Auth, type AuthOptions, type TokenResponse, type UserRecord, type ApiKeyRecord } from './auth/service.js';

From 6ff3f3c32163144945549aed5dc9c782beeda802 Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Mon, 2 Nov 2026 00:17:18 +0600
Subject: [PATCH 08/12] fix(library-server): highlights: take the question's
 lock to remove a link, lock lines while placing, one lock per id whatever its
 case, sync writes new words

Codex review round 1 (PR #44).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../library-server/src/highlights.test.ts     | 17 +++++++++++-
 packages/library-server/src/highlights.ts     | 26 +++++++++++++------
 2 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/packages/library-server/src/highlights.test.ts b/packages/library-server/src/highlights.test.ts
index 3c774dc..c81d724 100644
--- a/packages/library-server/src/highlights.test.ts
+++ b/packages/library-server/src/highlights.test.ts
@@ -40,6 +40,20 @@ describe('book highlights (registry-api §11)', () => {
     expect((await call('GET', '/v1/books/-bad/lines?pages=6')).status).toBe(400);
   });
 
+  it('sync writes a line\'s new words under the same key', async () => {
+    await call('POST', b('/lines/sync'), { lines: [{ ...line(6, 0), text: 'corrected words', textHash: 'h-new' }, line(6, 1), line(6, 2, 1), line(7, 0)] });
+    const l = ((await call('GET', b('/lines/all'))).body.items as { key: string; text: string; textHash: string }[]).find((x) => x.key === 'p6/0/0')!;
+    expect(l).toMatchObject({ text: 'corrected words', textHash: 'h-new' });
+  });
+
+  it('a question\'s lock is the same whatever the case of its id: an upper-case id is serialised with the lower-case one', async () => {
+    const L = await ids();
+    const add = await call('POST', b('/links'), { questionId: Q1.toUpperCase(), lineId: L['p6/0/0'], by: 'rafi' });
+    expect(add.body.questionId).toBe(Q1);
+    expect((await call('DELETE', b(`/links/${add.body.id}`), { by: 'rafi' })).body).toEqual({ removed: 1 });
+    expect((await call('DELETE', b('/links/33333333-3333-4333-8333-333333333333'), { by: 'rafi' })).status).toBe(404);
+  });
+
   it('sync adds, changes, retires and revives lines by key; a re-run changes nothing', async () => {
     const again = await call('POST', b('/lines/sync'), { lines: [line(6, 0), line(6, 1), line(6, 2, 1), line(7, 0)] });
     expect(again.body).toEqual({ added: 0, changed: 0, retired: 0, revived: 0, linksRetired: 0 });
@@ -51,9 +65,10 @@ describe('book highlights (registry-api §11)', () => {
   });
 
   it('planLines matches the dashboard\'s plan: no change, a moved line, a missing one', () => {
-    const stored = [{ id: 'a', key: 'p6/0/0', retiredAt: null, pageNo: 6, idx: 0, block: 0, kind: 'body', chapterNo: 1, chapterTitle: 'Physical quantities', section: null, rects: line(6, 0).rects }];
+    const stored = [{ id: 'a', key: 'p6/0/0', pageId: 'p6', text: 'line 6.0', textHash: 'h6.0', retiredAt: null, pageNo: 6, idx: 0, block: 0, kind: 'body', chapterNo: 1, chapterTitle: 'Physical quantities', section: null, rects: line(6, 0).rects }];
     expect(planLines(stored, [line(6, 0)])).toMatchObject({ write: [], retire: [] });
     expect(planLines(stored, [])).toMatchObject({ retire: ['p6/0/0'] });
+    expect(planLines(stored, [{ ...line(6, 0), text: 'corrected words' }])).toMatchObject({ changed: 1 });
   });
 
   it('a person tags a line: confirmed and theirs; the page shows counts by kind; a reader may ask for linked lines only', async () => {
diff --git a/packages/library-server/src/highlights.ts b/packages/library-server/src/highlights.ts
index ae61ce4..1ec0e86 100644
--- a/packages/library-server/src/highlights.ts
+++ b/packages/library-server/src/highlights.ts
@@ -67,7 +67,7 @@ const LINK_COLS = `k.id, k.question_id AS "questionId", k.line_id AS "lineId", k
     'chapterNo', l.chapter_no, 'retiredAt', l.retired_at) AS line`;
 const LINKS_FROM = `FROM book_links k JOIN book_lines l ON l.id = k.line_id`;
 
-type LineRow = { id: string; key: string; retiredAt: string | Date | null; pageNo: number; idx: number; block: number; kind: string; chapterNo: number | null; chapterTitle: string | null; section: string | null; rects: unknown };
+type LineRow = { id: string; key: string; pageId: string; text: string; textHash: string; retiredAt: string | Date | null; pageNo: number; idx: number; block: number; kind: string; chapterNo: number | null; chapterTitle: string | null; section: string | null; rects: unknown };
 
 class HighlightError extends Error {
   constructor(readonly status: 400 | 404 | 409, readonly code: string, message: string) { super(message); }
@@ -75,8 +75,11 @@ class HighlightError extends Error {
 const notFound = (what: string) => new HighlightError(404, 'not_found', what);
 const retired = () => new HighlightError(409, 'conflict', 'that line is no longer in the book');
 
-/** Takes the lock of a question for the rest of the transaction: writes to one question happen one after another. */
-const lockQuestion = (q: Query, id: string) => q(`SELECT pg_advisory_xact_lock(hashtext($1))`, [`chalk-highlights:q:${id}`]);
+/**
+ * Takes the lock of a question for the rest of the transaction: writes to one question happen one after another. The id is taken in its
+ * canonical form (lower case, as Postgres prints a uuid), so two spellings of one id share the lock.
+ */
+const lockQuestion = (q: Query, id: string) => q(`SELECT pg_advisory_xact_lock(hashtext($1))`, [`chalk-highlights:q:${id.toLowerCase()}`]);
 
 async function linkView(q: Query, id: string) {
   return (await q(`SELECT ${LINK_COLS} ${LINKS_FROM} WHERE k.id = $1`, [id]))[0]!;
@@ -112,7 +115,7 @@ export function planLines(stored: LineRow[], lines: z.infer<typeof lineIn>[]) {
   for (const r of lines) {
     const h = have.get(r.key);
     if (!h) { write.push(r); added++; continue; }
-    if (h.retiredAt || h.pageNo !== r.pageNo || h.idx !== r.idx || h.block !== r.block || h.kind !== r.kind || h.chapterNo !== (r.chapterNo ?? null)
+    if (h.retiredAt || h.pageId !== r.pageId || h.text !== r.text || h.textHash !== r.textHash || h.pageNo !== r.pageNo || h.idx !== r.idx || h.block !== r.block || h.kind !== r.kind || h.chapterNo !== (r.chapterNo ?? null)
       || h.chapterTitle !== (r.chapterTitle ?? null) || h.section !== (r.section ?? null) || !sameRects(h.rects, r.rects)) {
       write.push(r);
       if (h.retiredAt) revived++;
@@ -272,7 +275,7 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
           SELECT $1, x.key, x."pageId", x."pageNo", x.idx, x.block, x.kind, x.text, x."textHash", x."chapterNo", x."chapterTitle", x.section, coalesce(x.rects, '[]')
           FROM jsonb_to_recordset($2::jsonb) AS ${LINE_RECORDSET}
           ON CONFLICT (book, key) DO UPDATE SET page_id = EXCLUDED.page_id, page_no = EXCLUDED.page_no, idx = EXCLUDED.idx, block = EXCLUDED.block, kind = EXCLUDED.kind,
-            chapter_no = EXCLUDED.chapter_no, chapter_title = EXCLUDED.chapter_title, section = EXCLUDED.section, rects = EXCLUDED.rects, retired_at = NULL, updated_at = now()`,
+            text = EXCLUDED.text, text_hash = EXCLUDED.text_hash, chapter_no = EXCLUDED.chapter_no, chapter_title = EXCLUDED.chapter_title, section = EXCLUDED.section, rects = EXCLUDED.rects, retired_at = NULL, updated_at = now()`,
         [book, JSON.stringify(part)]);
       }
       for (const part of chunks(plan.retire)) await q(`UPDATE book_lines SET retired_at = now(), updated_at = now() WHERE book = $1 AND retired_at IS NULL AND key = ANY($2::text[])`, [book, part]);
@@ -339,8 +342,13 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
     const { by: who } = await parse(c, bySchema);
     const linkId = c.req.param('id');
     if (!uuid.safeParse(linkId).success) throw notFound('link not found');
-    const done = await db.query(`UPDATE book_links SET status = 'rejected', method = 'human', reviewed_by = $3, reviewed_at = now() WHERE id = $1 AND book = $2 RETURNING id`, [linkId, book, who]);
-    if (!done.length) throw notFound('link not found');
+    // under the question's lock: taking a link off is a person's decision, so a matcher placing the question at the same moment must see it
+    await db.begin(async (q) => {
+      const [cur] = await q<{ questionId: string }>(`SELECT question_id AS "questionId" FROM book_links WHERE id = $1 AND book = $2`, [linkId, book]);
+      if (!cur) throw notFound('link not found');
+      await lockQuestion(q, cur.questionId);
+      await q(`UPDATE book_links SET status = 'rejected', method = 'human', reviewed_by = $2, reviewed_at = now() WHERE id = $1`, [linkId, who]);
+    });
     return c.json({ removed: 1 });
   }));
 
@@ -416,7 +424,9 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
       const [busy] = await q(`SELECT 1 FROM book_links k WHERE k.question_id = $1 AND (k.status <> 'rejected' OR ${HUMAN}) LIMIT 1`, [b.questionId]);
       if (busy) return 0;
       const have = new Set((await q<{ id: string }>(`SELECT line_id AS id FROM book_links WHERE question_id = $1`, [b.questionId])).map((r) => r.id));
-      const live = new Set((await q<{ id: string }>(`SELECT id FROM book_lines WHERE book = $1 AND retired_at IS NULL AND id = ANY($2::uuid[])`, [book, b.proposals.map((p) => p.lineId)])).map((r) => r.id));
+      // FOR SHARE: a sync that retires one of these lines waits for this transaction (and then turns the new suggestions down), and one
+      // that already retired it is waited for, so no suggestion lands on a line that is gone
+      const live = new Set((await q<{ id: string }>(`SELECT id FROM book_lines WHERE book = $1 AND retired_at IS NULL AND id = ANY($2::uuid[]) FOR SHARE`, [book, b.proposals.map((p) => p.lineId)])).map((r) => r.id));
       const once = new Set<string>(); // one row per line, whatever the roles asked for
       let n = 0;
       for (const p of b.proposals) {

From 05bc7af1eb3dd7e5f6d9d63c692822c15e5c7d77 Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Mon, 2 Nov 2026 00:22:30 +0600
Subject: [PATCH 09/12] fix(library-server): highlights: every id is compared
 in lower case, from the body and from the URL

Codex review round 2 (PR #44).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/library-server/src/highlights.test.ts | 12 ++++++++++++
 packages/library-server/src/highlights.ts      | 17 ++++++++++-------
 spec/1.2/registry-api.md                       |  2 +-
 3 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/packages/library-server/src/highlights.test.ts b/packages/library-server/src/highlights.test.ts
index c81d724..269f37c 100644
--- a/packages/library-server/src/highlights.test.ts
+++ b/packages/library-server/src/highlights.test.ts
@@ -54,6 +54,18 @@ describe('book highlights (registry-api §11)', () => {
     expect((await call('DELETE', b('/links/33333333-3333-4333-8333-333333333333'), { by: 'rafi' })).status).toBe(404);
   });
 
+  it('ids are compared in lower case wherever they come in: a line moved onto itself, a retired line, a placement, a question\'s state', async () => {
+    const L = await ids();
+    const up = (id: string) => id.toUpperCase();
+    await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/0/0'], by: 'rafi' });
+    expect((await call('POST', b(`/lines/${L['p6/0/0']}/links/move`), { to: up(L['p6/0/0']!), by: 'rafi' })).body).toEqual({ moved: 0 });
+    expect((await call('GET', b(`/links?line=${up(L['p6/0/0']!)}`))).body.items).toHaveLength(1);
+    expect((await call('POST', '/v1/highlights/questions', { questionIds: [up(Q1)] })).body.items).toEqual({ [Q1]: { live: 1, human: true, any: true } });
+    expect((await call('POST', b('/links/place'), { questionId: up(Q2), proposals: [{ lineId: up(L['p6/1/0']!), role: 'answers_from' }] })).body).toEqual({ placed: 1 });
+    await call('POST', b('/lines/sync'), { lines: [line(6, 0), line(6, 1), line(6, 2, 1)] });
+    expect((await call('POST', b('/links'), { questionId: Q1, lineId: up(L['p7/0/0']!), by: 'rafi' })).status).toBe(409);
+  });
+
   it('sync adds, changes, retires and revives lines by key; a re-run changes nothing', async () => {
     const again = await call('POST', b('/lines/sync'), { lines: [line(6, 0), line(6, 1), line(6, 2, 1), line(7, 0)] });
     expect(again.body).toEqual({ added: 0, changed: 0, retired: 0, revived: 0, linksRetired: 0 });
diff --git a/packages/library-server/src/highlights.ts b/packages/library-server/src/highlights.ts
index 1ec0e86..2a1db57 100644
--- a/packages/library-server/src/highlights.ts
+++ b/packages/library-server/src/highlights.ts
@@ -23,7 +23,10 @@ const SCOPES = ['sentence', 'paragraph', 'section'] as const;
 /** The most lines one change of a question's highlight may name: a highlight is a few lines, not a chapter. */
 export const MAX_LINE_CHANGES = 200;
 
-const uuid = z.string().uuid();
+/** A uuid, in its canonical form (lower case, as Postgres prints one): every id is compared as the database stores it. */
+const uuid = z.string().uuid().transform((s) => s.toLowerCase());
+/** An id from the URL (a path part or a query parameter) in the same canonical form; anything else is left as it is and fails its check. */
+const idOf = (v: string | undefined) => v?.toLowerCase();
 const by = z.string().min(1).max(200);
 const role = z.enum(ROLES);
 const scope = z.enum(SCOPES);
@@ -203,7 +206,7 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
   }));
 
   app.get('/v1/books/:slug/links', (c) => run(c, 'reader', async (book) => {
-    const line = c.req.query('line'), question = c.req.query('question');
+    const line = idOf(c.req.query('line')), question = idOf(c.req.query('question'));
     if (line !== undefined) {
       if (!uuid.safeParse(line).success) throw new HighlightError(400, 'invalid', 'line: not a uuid');
       const where = c.req.query('paragraph') === '1'
@@ -304,7 +307,7 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
 
   app.patch('/v1/books/:slug/links/:id', (c) => run(c, 'author', async (book) => {
     const p = await parse(c, patchSchema);
-    const linkId = c.req.param('id');
+    const linkId = idOf(c.req.param('id'))!;
     if (!uuid.safeParse(linkId).success) throw notFound('link not found');
     const kept = await db.begin(async (q) => {
       const [cur0] = await q<{ questionId: string }>(`SELECT question_id AS "questionId" FROM book_links WHERE id = $1 AND book = $2`, [linkId, book]);
@@ -340,7 +343,7 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
 
   app.delete('/v1/books/:slug/links/:id', (c) => run(c, 'author', async (book) => {
     const { by: who } = await parse(c, bySchema);
-    const linkId = c.req.param('id');
+    const linkId = idOf(c.req.param('id'))!;
     if (!uuid.safeParse(linkId).success) throw notFound('link not found');
     // under the question's lock: taking a link off is a person's decision, so a matcher placing the question at the same moment must see it
     await db.begin(async (q) => {
@@ -354,7 +357,7 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
 
   app.post('/v1/books/:slug/lines/:id/links/remove', (c) => run(c, 'author', async (book) => {
     const b = await parse(c, removeSchema);
-    const lineId = c.req.param('id');
+    const lineId = idOf(c.req.param('id'))!;
     if (!uuid.safeParse(lineId).success) throw notFound('that line is not in this book');
     const ids = await covered(db.query, book, lineId, Boolean(b.paragraph));
     if (!ids.length) throw notFound('that line is not in this book');
@@ -365,7 +368,7 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
 
   app.post('/v1/books/:slug/lines/:id/links/move', (c) => run(c, 'author', async (book) => {
     const b = await parse(c, moveSchema);
-    const from = c.req.param('id');
+    const from = idOf(c.req.param('id'))!;
     if (!uuid.safeParse(from).success) throw notFound('that line is not in this book');
     if (from === b.to) return c.json({ moved: 0 });
     const moved = await db.begin(async (q) => {
@@ -386,7 +389,7 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
 
   app.put('/v1/books/:slug/questions/:question/lines', (c) => run(c, 'author', async (book) => {
     const b = await parse(c, linesSchema);
-    const questionId = c.req.param('question');
+    const questionId = idOf(c.req.param('question'))!;
     if (!uuid.safeParse(questionId).success) throw new HighlightError(400, 'invalid', 'question: not a uuid');
     const add = [...new Set(b.add)], remove = [...new Set(b.remove)];
     if (!add.length && !remove.length) throw new HighlightError(400, 'invalid', 'name a line to add or take off');
diff --git a/spec/1.2/registry-api.md b/spec/1.2/registry-api.md
index a6727de..1ee6f24 100644
--- a/spec/1.2/registry-api.md
+++ b/spec/1.2/registry-api.md
@@ -315,7 +315,7 @@ A registry MAY keep the **highlights** of its books: the lines of a book's text
 assets these are records that change one by one: an editor adds, moves and removes links, a matcher suggests them, and
 readers (a reading app, a mobile app) ask for the lines of the pages they show. A registry that lacks this answers `404`.
 Paths are under `v1/books/{slug}/` (`{slug}` as in spec 1.8 §2). Reads need `reader`, writes `author` (§10.1). Ids are
-UUID strings. Unknown ids of the book are `404 not_found`; a write that names a line the book no longer has (retired)
+UUID strings, compared and answered in lower case. Unknown ids of the book are `404 not_found`; a write that names a line the book no longer has (retired)
 is `409 conflict`.
 
 ### 11.1 Records

From 7357c5010a47bf75c3c77c3c6a7244060d7571cb Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Mon, 2 Nov 2026 00:28:19 +0600
Subject: [PATCH 10/12] fix(library-server): highlights: question kinds are
 plain names counted as own keys; bulk remove and move lock their questions
 and touch only those

Codex review round 3 (PR #44).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../library-server/src/highlights.test.ts     |  9 ++++
 packages/library-server/src/highlights.ts     | 54 +++++++++++++------
 2 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/packages/library-server/src/highlights.test.ts b/packages/library-server/src/highlights.test.ts
index 269f37c..f0837ce 100644
--- a/packages/library-server/src/highlights.test.ts
+++ b/packages/library-server/src/highlights.test.ts
@@ -66,6 +66,15 @@ describe('book highlights (registry-api §11)', () => {
     expect((await call('POST', b('/links'), { questionId: Q1, lineId: up(L['p7/0/0']!), by: 'rafi' })).status).toBe(409);
   });
 
+  it('a question kind is a plain name: __proto__ is refused, and kinds are counted as own keys', async () => {
+    const L = await ids();
+    expect((await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/0/0'], questionType: '__proto__', by: 'rafi' })).status).toBe(400);
+    expect((await call('POST', b('/links'), { questionId: Q1, lineId: L['p6/0/0'], questionType: 'constructor', by: 'rafi' })).status).toBe(201);
+    const page = (await call('GET', b('/lines?pages=6'))).body.pages['6'];
+    expect(page[0].typeCounts).toEqual({ constructor: { confirmed: 1, suggested: 0 } });
+    expect(({} as Record<string, unknown>).confirmed).toBeUndefined();
+  });
+
   it('sync adds, changes, retires and revives lines by key; a re-run changes nothing', async () => {
     const again = await call('POST', b('/lines/sync'), { lines: [line(6, 0), line(6, 1), line(6, 2, 1), line(7, 0)] });
     expect(again.body).toEqual({ added: 0, changed: 0, retired: 0, revived: 0, linksRetired: 0 });
diff --git a/packages/library-server/src/highlights.ts b/packages/library-server/src/highlights.ts
index 2a1db57..ff1e99e 100644
--- a/packages/library-server/src/highlights.ts
+++ b/packages/library-server/src/highlights.ts
@@ -30,7 +30,9 @@ const idOf = (v: string | undefined) => v?.toLowerCase();
 const by = z.string().min(1).max(200);
 const role = z.enum(ROLES);
 const scope = z.enum(SCOPES);
-const questionType = z.string().min(1).max(40).optional();
+/** A question's kind as the writer names it (`mcq`, `cq`, …): a plain lower-case name, so it is safe as a key of the counts it is grouped by. */
+const TYPE_NAME = /^[a-z][a-z0-9_]{0,39}$/;
+const questionType = z.string().regex(TYPE_NAME).optional();
 const rect = z.object({ x: z.number(), y: z.number(), w: z.number(), fs: z.number() });
 const lineIn = z.object({
   key: z.string().min(1).max(300), pageId: z.string().min(1).max(200), pageNo: z.number().int().min(0), idx: z.number().int().min(0), block: z.number().int().min(0),
@@ -53,7 +55,7 @@ const importSchema = z.object({
   lines: z.array(lineIn.extend({ id: uuid, retiredAt: z.string().nullable().optional() })).max(200_000),
   links: z.array(z.object({
     id: uuid, questionId: uuid, lineId: uuid, role: z.string().min(1).max(40), scope: z.string().min(1).max(40), method: z.string().min(1).max(20), status: z.enum(STATUSES),
-    score: z.number().nullable().optional(), rationale: z.string().nullable().optional(), questionType: z.string().nullable().optional(),
+    score: z.number().nullable().optional(), rationale: z.string().nullable().optional(), questionType: z.string().regex(TYPE_NAME).nullable().optional(),
     reviewedBy: z.string().nullable().optional(), reviewedAt: z.string().nullable().optional(), createdAt: z.string().optional(),
   })).max(500_000),
 });
@@ -84,6 +86,16 @@ const retired = () => new HighlightError(409, 'conflict', 'that line is no longe
  */
 const lockQuestion = (q: Query, id: string) => q(`SELECT pg_advisory_xact_lock(hashtext($1))`, [`chalk-highlights:q:${id.toLowerCase()}`]);
 
+/**
+ * Locks every question with a link on these lines, in id order (so two bulk changes never wait on each other crosswise), and gives their ids:
+ * a bulk change then touches only those questions' links.
+ */
+async function lockQuestionsOf(q: Query, lineIds: string[]): Promise<string[]> {
+  const ids = (await q<{ id: string }>(`SELECT DISTINCT question_id::text AS id FROM book_links WHERE line_id = ANY($1::uuid[]) ORDER BY 1`, [lineIds])).map((r) => r.id);
+  for (const id of ids) await lockQuestion(q, id);
+  return ids;
+}
+
 async function linkView(q: Query, id: string) {
   return (await q(`SELECT ${LINK_COLS} ${LINKS_FROM} WHERE k.id = $1`, [id]))[0]!;
 }
@@ -163,20 +175,23 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
       `SELECT ${LINE_COLS} FROM book_lines l WHERE l.book = $1 AND l.page_no = ANY($2::int[]) AND l.retired_at IS NULL ORDER BY l.page_no, l.idx`, [book, pages]);
     const links = await db.query<{ lineId: string; status: string; type: string | null }>(
       `SELECT k.line_id AS "lineId", k.status, k.question_type AS type ${LINKS_FROM} WHERE k.book = $1 AND l.page_no = ANY($2::int[]) AND l.retired_at IS NULL AND ${statusFilter(c)}`, [book, pages]);
-    const byLine = new Map<string, { links: number; suggested: number; typeCounts: Record<string, { confirmed: number; suggested: number }> }>();
+    // the kinds are counted in a Map and only then made an object (Object.fromEntries defines own keys), so no kind can reach a prototype
+    const byLine = new Map<string, { links: number; suggested: number; types: Map<string, { confirmed: number; suggested: number }> }>();
     for (const k of links) {
-      const s = byLine.get(k.lineId) ?? { links: 0, suggested: 0, typeCounts: {} };
+      const s = byLine.get(k.lineId) ?? { links: 0, suggested: 0, types: new Map() };
       s.links++;
       if (k.status === 'suggested') s.suggested++;
       if (k.type) {
-        const t = (s.typeCounts[k.type] ??= { confirmed: 0, suggested: 0 });
+        const t = s.types.get(k.type) ?? { confirmed: 0, suggested: 0 };
         if (k.status === 'confirmed') t.confirmed++; else t.suggested++;
+        s.types.set(k.type, t);
       }
       byLine.set(k.lineId, s);
     }
     const linked = c.req.query('linked') === '1';
     for (const l of lines) {
-      const s = byLine.get(l.id) ?? { links: 0, suggested: 0, typeCounts: {} };
+      const counted = byLine.get(l.id);
+      const s = { links: counted?.links ?? 0, suggested: counted?.suggested ?? 0, typeCounts: Object.fromEntries(counted?.types ?? []) };
       if (linked && !s.links) continue;
       const rest: Record<string, unknown> = { ...l };
       delete rest.textHash;
@@ -359,11 +374,15 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
     const b = await parse(c, removeSchema);
     const lineId = idOf(c.req.param('id'))!;
     if (!uuid.safeParse(lineId).success) throw notFound('that line is not in this book');
-    const ids = await covered(db.query, book, lineId, Boolean(b.paragraph));
-    if (!ids.length) throw notFound('that line is not in this book');
-    const gone = await db.query(`UPDATE book_links SET status = 'rejected', method = 'human', reviewed_by = $2, reviewed_at = now()
-      WHERE line_id = ANY($1::uuid[]) AND status <> 'rejected' RETURNING id`, [ids, b.by]);
-    return c.json({ removed: gone.length });
+    const removed = await db.begin(async (q) => {
+      const ids = await covered(q, book, lineId, Boolean(b.paragraph));
+      if (!ids.length) throw notFound('that line is not in this book');
+      const locked = await lockQuestionsOf(q, ids);
+      const gone = await q(`UPDATE book_links SET status = 'rejected', method = 'human', reviewed_by = $2, reviewed_at = now()
+        WHERE line_id = ANY($1::uuid[]) AND status <> 'rejected' AND question_id = ANY($3::uuid[]) RETURNING id`, [ids, b.by, locked]);
+      return gone.length;
+    });
+    return c.json({ removed });
   }));
 
   app.post('/v1/books/:slug/lines/:id/links/move', (c) => run(c, 'author', async (book) => {
@@ -374,14 +393,15 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
     const moved = await db.begin(async (q) => {
       await lineOf(q, book, b.to, true);
       await lineOf(q, book, from, false);
-      // the questions involved, locked in one order
-      await q(`SELECT pg_advisory_xact_lock(hashtext('chalk-highlights:q:' || x.question_id::text)) FROM (SELECT DISTINCT question_id FROM book_links WHERE line_id = $1 ORDER BY 1) x`, [from]);
+      // the questions involved, locked in one order; only their links move (one that arrives meanwhile, of another question, stays where it is)
+      const locked = await lockQuestionsOf(q, [from]);
       // the other line already has that tag: it is kept, becomes the person's, and is confirmed if it had been turned down; rejected rows of the old line stay there
       await q(`UPDATE book_links x SET status = CASE WHEN x.status = 'rejected' THEN 'confirmed' ELSE x.status END, method = 'human', reviewed_by = $3, reviewed_at = now()
-        FROM book_links l WHERE l.line_id = $1 AND l.status <> 'rejected' AND x.line_id = $2 AND x.question_id = l.question_id AND x.role = l.role`, [from, b.to, b.by]);
-      await q(`DELETE FROM book_links l WHERE l.line_id = $1 AND l.status <> 'rejected'
-        AND EXISTS (SELECT 1 FROM book_links x WHERE x.line_id = $2 AND x.question_id = l.question_id AND x.role = l.role)`, [from, b.to]);
-      const rows = await q(`UPDATE book_links SET line_id = $2, method = 'human', reviewed_by = $3, reviewed_at = now() WHERE line_id = $1 AND status <> 'rejected' RETURNING id`, [from, b.to, b.by]);
+        FROM book_links l WHERE l.line_id = $1 AND l.status <> 'rejected' AND l.question_id = ANY($4::uuid[]) AND x.line_id = $2 AND x.question_id = l.question_id AND x.role = l.role`, [from, b.to, b.by, locked]);
+      await q(`DELETE FROM book_links l WHERE l.line_id = $1 AND l.status <> 'rejected' AND l.question_id = ANY($3::uuid[])
+        AND EXISTS (SELECT 1 FROM book_links x WHERE x.line_id = $2 AND x.question_id = l.question_id AND x.role = l.role)`, [from, b.to, locked]);
+      const rows = await q(`UPDATE book_links SET line_id = $2, method = 'human', reviewed_by = $3, reviewed_at = now()
+        WHERE line_id = $1 AND status <> 'rejected' AND question_id = ANY($4::uuid[]) RETURNING id`, [from, b.to, b.by, locked]);
       return rows.length;
     });
     return c.json({ moved });

From 968d7738b1885dd1af33c42039d9c7a602e06ef3 Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Mon, 2 Nov 2026 00:37:10 +0600
Subject: [PATCH 11/12] fix(library-server): highlights: import refuses ids of
 another book; moving a line onto itself still checks the line

Codex review round 4 (PR #44).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/library-server/src/highlights.test.ts |  6 ++++++
 packages/library-server/src/highlights.ts      | 10 +++++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/packages/library-server/src/highlights.test.ts b/packages/library-server/src/highlights.test.ts
index f0837ce..81d8a6f 100644
--- a/packages/library-server/src/highlights.test.ts
+++ b/packages/library-server/src/highlights.test.ts
@@ -204,5 +204,11 @@ describe('book highlights (registry-api §11)', () => {
     const got = (await call('GET', `/v1/books/other-book/links?line=${lineId}`)).body.items;
     expect(got[0]).toMatchObject({ id: linkId, score: 0.7, questionType: 'mcq' });
     expect((await call('POST', '/v1/books/other-book/import', { lines: [], links: [{ id: linkId, questionId: Q1, lineId: '66666666-6666-4666-8666-666666666666', role: 'answers_from', scope: 'sentence', method: 'auto', status: 'suggested' }] })).status).toBe(404);
+    // the same ids sent for another book are refused, not reported as copied
+    const again = await call('POST', '/v1/books/third-book/import', { lines: [{ ...line(3, 0), id: lineId, retiredAt: null }], links: [] });
+    expect(again.status).toBe(409);
+    expect(again.body.error.message).toMatch(/another book/);
+    // moving a line onto itself still checks the line
+    expect((await call('POST', b('/lines/77777777-7777-4777-8777-777777777777/links/move'), { to: '77777777-7777-4777-8777-777777777777', by: 'x' })).status).toBe(404);
   });
 });
diff --git a/packages/library-server/src/highlights.ts b/packages/library-server/src/highlights.ts
index ff1e99e..f005173 100644
--- a/packages/library-server/src/highlights.ts
+++ b/packages/library-server/src/highlights.ts
@@ -389,10 +389,11 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
     const b = await parse(c, moveSchema);
     const from = idOf(c.req.param('id'))!;
     if (!uuid.safeParse(from).success) throw notFound('that line is not in this book');
-    if (from === b.to) return c.json({ moved: 0 });
     const moved = await db.begin(async (q) => {
       await lineOf(q, book, b.to, true);
       await lineOf(q, book, from, false);
+      // checked after both lines are known: moving a line onto itself still answers 404 for a line the book lacks and 409 for a retired one
+      if (from === b.to) return 0;
       // the questions involved, locked in one order; only their links move (one that arrives meanwhile, of another question, stays where it is)
       const locked = await lockQuestionsOf(q, [from]);
       // the other line already has that tag: it is kept, becomes the person's, and is confirmed if it had been turned down; rejected rows of the old line stay there
@@ -467,6 +468,13 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
   app.post('/v1/books/:slug/import', (c) => run(c, 'author', async (book) => {
     const b = await parse(c, importSchema);
     await db.begin(async (q) => {
+      // an id that is another book's is refused, not skipped: the answer must not count records it did not write
+      const elsewhere = async (table: 'book_lines' | 'book_links', ids: string[]) =>
+        ids.length ? (await q<{ id: string }>(`SELECT id FROM ${table} WHERE id = ANY($1::uuid[]) AND book <> $2 LIMIT 1`, [ids, book]))[0]?.id : undefined;
+      const lineClash = await elsewhere('book_lines', b.lines.map((l) => l.id));
+      if (lineClash) throw new HighlightError(409, 'conflict', `line ${lineClash} belongs to another book`);
+      const linkClash = await elsewhere('book_links', b.links.map((l) => l.id));
+      if (linkClash) throw new HighlightError(409, 'conflict', `link ${linkClash} belongs to another book`);
       for (const part of chunks(b.lines)) {
         await q(`INSERT INTO book_lines (id, book, key, page_id, page_no, idx, block, kind, text, text_hash, chapter_no, chapter_title, section, rects, retired_at)
           SELECT x.id, $1, x.key, x."pageId", x."pageNo", x.idx, x.block, x.kind, x.text, x."textHash", x."chapterNo", x."chapterTitle", x.section, coalesce(x.rects, '[]'), x."retiredAt"

From b21c898848efab0243b8c6206ed0e466f05713ef Mon Sep 17 00:00:00 2001
From: sawradip <sawradip0@gmail.com>
Date: Mon, 2 Nov 2026 00:39:43 +0600
Subject: [PATCH 12/12] fix(library-server): highlights: the review list's
 chapter 0 is a chapter

Codex review round 5 (PR #44).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/library-server/src/highlights.test.ts | 3 +++
 packages/library-server/src/highlights.ts      | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/library-server/src/highlights.test.ts b/packages/library-server/src/highlights.test.ts
index 81d8a6f..d4d5be0 100644
--- a/packages/library-server/src/highlights.test.ts
+++ b/packages/library-server/src/highlights.test.ts
@@ -192,6 +192,9 @@ describe('book highlights (registry-api §11)', () => {
     expect(r.total).toBe(2);
     expect(r.items).toHaveLength(1);
     expect(r.items[0].line.key).toBe('p6/0/0');
+    // chapter 0 is a chapter like any other (the lines here are in chapter 1)
+    expect((await call('GET', b('/links?chapter=0'))).body.total).toBe(0);
+    expect((await call('GET', b('/links?chapter=1'))).body.total).toBe(2);
   });
 
   it('import copies lines and links with their ids', async () => {
diff --git a/packages/library-server/src/highlights.ts b/packages/library-server/src/highlights.ts
index f005173..3ac9706 100644
--- a/packages/library-server/src/highlights.ts
+++ b/packages/library-server/src/highlights.ts
@@ -238,7 +238,7 @@ export function registerHighlights(app: Hono<{ Variables: AuthVariables }>, o: {
     // review: by chapter, status and method, in book order
     const where = ['k.book = $1'], params: unknown[] = [book];
     const chapter = int(c.req.query('chapter'));
-    if (chapter) { params.push(chapter); where.push(`l.chapter_no = $${params.length}`); }
+    if (chapter !== undefined) { params.push(chapter); where.push(`l.chapter_no = $${params.length}`); }
     const status = c.req.query('status');
     if (status && (STATUSES as readonly string[]).includes(status)) { params.push(status); where.push(`k.status = $${params.length}`); } else where.push(`k.status <> 'rejected'`);
     const method = c.req.query('method');