chitai/TODO.md

TODO

Known issues and deferred work. Agent-facing notes belong in the AGENTS.md files; this is for things that are broken or missing and not yet scheduled.

Backend

Identifier extraction drops most ISBNs

backend/src/chitai/services/metadata_extractor.py — EpubExtractor._extract_identifiers

The EPUB path validates DC:identifier values verbatim:

for id in epub.get_metadata("DC", "identifier"):
    if is_valid_isbn(id[0]):
        ...

is_valid_isbn branches on len(isbn) being exactly 10 or 13, so anything carrying formatting fails. Two consequences:

• Hyphenated ISBNs are silently dropped. 978-0-486-28211-4 is 17 characters, so it never reaches the checksum. Most EPUBs write ISBNs hyphenated, so the majority are lost. The PDF path already does this correctly — _extract_isbns calls match.replace("-", "") before validating.
• urn:isbn: prefixes are dropped for the same reason. This is a common EPUB form.

Fix: normalise before validating — strip a leading urn:isbn:, then remove everything that isn't 0-9 or X. Reuse the PDF path's approach rather than duplicating it.

Note this only runs at upload, so fixing it changes nothing for books already imported. A backfill would need to re-read the files on disk.

Non-ISBN identifiers are discarded

Same function. Anything that isn't a valid ISBN is thrown away, including values EPUBs routinely carry: urn:uuid:…, calibre:…, Google Books volume IDs and ASINs.

The Identifier model is already generic (name + value, unique per book), so storing them needs no schema change — only the extractor decides what survives. The frontend already renders ISBN, ASIN and DOI as links and shows unknown types as plain values, so anything stored will display sensibly.

Worth adding at the same time:

• A DOI regex (10.\d{4,9}/\S+) alongside the ISBN scan in PdfExtractor._extract_isbns — academic PDFs carry one and it is the most useful identifier they have.
• Deriving ISBN-10 from ISBN-13 when only the latter is present. It is a pure checksum conversion and doubles the chance of an external lookup matching.

Frontend

Remove the epub.js locations-cache purge

frontend/src/lib/reader/legacy-cache.ts — purgeLegacyLocationCache

The epub.js reader cached generated locations in localStorage under ${bookId}-locations, a few hundred KB of JSON per long book. foliate computes progress from section byte sizes at open time, so nothing writes those keys any more, but existing browsers still hold them — and a reader near the 5–10 MB origin quota would make the new reader-settings write throw QuotaExceededError.

The reader clears them once per browser, behind a chitai:locations-purged flag. Delete the module, its call in epub-reader.svelte and the flag once deployments have had a release or two to run it — after roughly 2026-12.

Cover dimensions are unknown until load

book-cover.svelte renders covers at a fixed height with natural width so nothing is cropped or distorted. Because the intrinsic size is not known ahead of time, the text beside the cover settles once when the image loads. min-width bounds the movement but does not remove it.

Removing it properly means storing cover dimensions at ingest and emitting them as width/height attributes so the browser reserves exact space. That is a model change plus a migration.

No series navigation

Book has series and series_position, and the detail page shows both, but there is no way to reach the other volumes. The books list endpoint filters by author, publisher, tag, shelf and progress — a series filter would need adding in backend/src/chitai/services/filters/book.py and wiring through services/dependencies.py, following the existing AuthorFilter pattern.

Book pages are sparse for most books

EPUB metadata is thin: most imports arrive with a title, an author and nothing else. Two independent directions, neither started:

• Use what exists. "More by this author" (the list endpoint already accepts authors=), and exposing Book.created_at and BookProgress.updated_at — both are in the database, neither is on BookRead / BookProgressRead.
• Fetch from outside. Open Library or Google Books lookup by ISBN for descriptions and covers. This is what actually fixes the sparseness, but it needs outbound requests, rate limiting, a manual-vs-automatic decision, and a rule for not clobbering hand-edited metadata.