diff --git a/backend/api/v1/api.py b/backend/api/v1/api.py
index d63a244..70c633a 100644
--- a/backend/api/v1/api.py
+++ b/backend/api/v1/api.py
@@ -1,5 +1,5 @@
from fastapi import APIRouter
-from api.v1.endpoints import health, stories, shelf, gutenberg, auth, manga
+from api.v1.endpoints import health, stories, shelf, gutenberg, auth, manga, standard_ebooks
api_router = APIRouter()
@@ -8,5 +8,6 @@
api_router.include_router(shelf.router, tags=["shelf"])
api_router.include_router(gutenberg.router, tags=["gutenberg"])
api_router.include_router(manga.router, tags=["manga"])
+api_router.include_router(standard_ebooks.router, tags=["standard-ebooks"])
api_router.include_router(auth.router, tags=["auth"])
diff --git a/backend/api/v1/endpoints/gutenberg.py b/backend/api/v1/endpoints/gutenberg.py
index 3bf40f1..ffa10f9 100644
--- a/backend/api/v1/endpoints/gutenberg.py
+++ b/backend/api/v1/endpoints/gutenberg.py
@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import Literal, Optional
from fastapi import APIRouter, Depends, Path, Query, status
from core.operator_auth import require_ingestion_api_key
@@ -23,8 +23,12 @@ async def ingest_gutenberg_book(
async def get_gutenberg_stories(
topic: Optional[str] = Query(default=None, max_length=50, description="Topic or genre filter for Gutenberg"),
search: Optional[str] = Query(default=None, max_length=200, description="Search term across title and author"),
+ sort: Literal["catalog", "popular", "recent"] = Query(
+ default="catalog",
+ description="Select the catalog snapshot, popular titles, or recent Gutenberg additions",
+ ),
):
- return await gutenberg_service.get_gutenberg_stories(topic=topic, search=search)
+ return await gutenberg_service.get_gutenberg_stories(topic=topic, search=search, sort=sort)
@router.get("/public/gutenberg/{gutenberg_id}", response_model=StoryDTO)
diff --git a/backend/api/v1/endpoints/standard_ebooks.py b/backend/api/v1/endpoints/standard_ebooks.py
new file mode 100644
index 0000000..249db48
--- /dev/null
+++ b/backend/api/v1/endpoints/standard_ebooks.py
@@ -0,0 +1,24 @@
+from typing import Optional
+from fastapi import APIRouter, Query
+
+from schemas import ChapterDTO, StoryDTO
+from services import standard_ebooks as standard_ebooks_service
+
+router = APIRouter()
+
+
+@router.get("/public/standard-ebooks", response_model=list[StoryDTO])
+async def get_standard_ebooks_stories(
+ topic: Optional[str] = Query(default=None, description="Filter Standard Ebooks by subject (e.g. fiction, horror)"),
+ search: Optional[str] = Query(default=None, description="Search keyword for title or author"),
+):
+ """Retrieve curated public-domain classics from Standard Ebooks."""
+ return await standard_ebooks_service.get_standard_ebooks_stories(topic=topic, search=search)
+
+
+@router.get("/public/standard-ebooks/chapters", response_model=list[ChapterDTO])
+async def get_standard_ebooks_chapters(
+ book_id: str = Query(..., description="Standard Ebooks slug path (e.g. bram-stoker/dracula)"),
+):
+ """Retrieve structured semantic XHTML chapters for a Standard Ebooks work."""
+ return await standard_ebooks_service.get_standard_ebooks_chapters(book_id=book_id)
diff --git a/backend/services/gutenberg.py b/backend/services/gutenberg.py
index 7dffcee..8226834 100644
--- a/backend/services/gutenberg.py
+++ b/backend/services/gutenberg.py
@@ -6,14 +6,17 @@
import io
import logging
import os
+import re
import tempfile
import time
+import weakref
import xml.etree.ElementTree as ET
import zlib
from collections import OrderedDict
from datetime import datetime, timezone
from pathlib import Path
from typing import NamedTuple, Optional, Tuple, List
+from urllib.parse import urlparse
from uuid import UUID, uuid5
import httpx
@@ -31,6 +34,12 @@
GUTENBERG_CATALOG_URL = "https://www.gutenberg.org/cache/epub/feeds/pg_catalog.csv.gz"
GUTENBERG_CATALOG_TTL_SECONDS = 7 * 24 * 60 * 60
GUTENBERG_CATALOG_REFRESH_RETRY_SECONDS = 60 * 60
+GUTENBERG_RECENT_FEED_URL = "https://www.gutenberg.org/cache/epub/feeds/today.rss"
+GUTENBERG_RECENT_FEED_TTL_SECONDS = 12 * 60 * 60
+GUTENBERG_RECENT_FEED_MAX_STALE_SECONDS = 48 * 60 * 60
+GUTENBERG_RECENT_FEED_MAX_BYTES = 1024 * 1024
+GUTENBERG_RECENT_FEED_MAX_ITEMS = 30
+GUTENBERG_RECENT_METADATA_TIMEOUT_SECONDS = 30.0
GUTENBERG_CATALOG_MAX_COMPRESSED_BYTES = 12 * 1024 * 1024
GUTENBERG_CATALOG_MAX_UNCOMPRESSED_BYTES = 40 * 1024 * 1024
GUTENBERG_MAX_METADATA_BYTES = 2 * 1024 * 1024
@@ -38,14 +47,46 @@
GUTENBERG_CHAPTER_CACHE_TTL_SECONDS = 600.0
GUTENBERG_CHAPTER_CACHE_MAX_ENTRIES = 32
GUTENBERG_CHAPTER_CACHE_MAX_BYTES = 16 * 1024 * 1024
-GUTENBERG_MAX_CONCURRENT_FETCHES = 3
+GUTENBERG_MAX_CONCURRENT_FETCHES = 4
_GUTENBERG_CHAPTER_CACHE: OrderedDict[int, tuple[float, list[ChapterDTO]]] = OrderedDict()
-_GUTENBERG_FETCH_SEMAPHORE = asyncio.Semaphore(GUTENBERG_MAX_CONCURRENT_FETCHES)
-_GUTENBERG_METADATA_SEMAPHORE = asyncio.Semaphore(GUTENBERG_MAX_CONCURRENT_FETCHES)
-_GUTENBERG_CATALOG_LOCK = asyncio.Lock()
+_LOOP_PRIMITIVES: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary()
+
+
+def _loop_primitive(key: str, factory):
+ loop = asyncio.get_running_loop()
+ bucket = _LOOP_PRIMITIVES.setdefault(loop, {})
+ if key not in bucket:
+ bucket[key] = factory()
+ return bucket[key]
+
+
+def _get_fetch_semaphore() -> asyncio.Semaphore:
+ return _loop_primitive(
+ "fetch_semaphore",
+ lambda: asyncio.Semaphore(GUTENBERG_MAX_CONCURRENT_FETCHES),
+ )
+
+
+def _get_metadata_semaphore() -> asyncio.Semaphore:
+ return _loop_primitive(
+ "metadata_semaphore",
+ lambda: asyncio.Semaphore(GUTENBERG_MAX_CONCURRENT_FETCHES),
+ )
+
+
+def _get_catalog_lock() -> asyncio.Lock:
+ return _loop_primitive("catalog_lock", asyncio.Lock)
+
+
+def _get_recent_feed_lock() -> asyncio.Lock:
+ return _loop_primitive("recent_feed_lock", asyncio.Lock)
+
+
_GUTENBERG_CATALOG_CACHE: Optional[Tuple[float, List["GutenbergCatalogEntry"]]] = None
_GUTENBERG_CATALOG_STALE_CACHE: Optional[Tuple[float, List["GutenbergCatalogEntry"]]] = None
_GUTENBERG_CATALOG_LAST_REFRESH_ATTEMPT = 0.0
+_GUTENBERG_RECENT_FEED_CACHE: Optional[Tuple[float, List[dict]]] = None
+_GUTENBERG_RECENT_FEED_LAST_REFRESH_ATTEMPT = 0.0
GUTENBERG_AUTHORS_CACHE_TTL_SECONDS = 3600.0
_GUTENBERG_AUTHORS_CACHE: Optional[Tuple[float, List["GutenbergCatalogEntry"], List[WriterDTO]]] = None
@@ -209,7 +250,7 @@ async def _load_gutenberg_catalog(client: httpx.AsyncClient) -> list[GutenbergCa
):
return _GUTENBERG_CATALOG_STALE_CACHE[1]
- async with _GUTENBERG_CATALOG_LOCK:
+ async with _get_catalog_lock():
now = time.monotonic()
if _GUTENBERG_CATALOG_CACHE and now - _GUTENBERG_CATALOG_CACHE[0] < GUTENBERG_CATALOG_TTL_SECONDS:
return _GUTENBERG_CATALOG_CACHE[1]
@@ -253,6 +294,12 @@ async def _load_gutenberg_catalog(client: httpx.AsyncClient) -> list[GutenbergCa
return entries
+def _clean_gutenberg_title(raw_title: str) -> str:
+ cleaned = re.sub(r"\s*:\s*\$[a-z]\b\s*", ": ", raw_title or "", flags=re.IGNORECASE)
+ cleaned = re.sub(r"\s*\$[a-z]\b\s*", " ", cleaned, flags=re.IGNORECASE)
+ return re.sub(r"\s+", " ", cleaned).strip()
+
+
def _search_gutenberg_catalog(
entries: list[GutenbergCatalogEntry],
params: dict,
@@ -261,7 +308,8 @@ def _search_gutenberg_catalog(
topic = str(params.get("topic") or "").strip().casefold()
matching = []
for entry in entries:
- title = entry.title.casefold()
+ cleaned_title = _clean_gutenberg_title(entry.title)
+ title = cleaned_title.casefold()
authors = entry.authors.casefold()
display_authors = " ".join(
_display_catalog_author(author).casefold()
@@ -272,16 +320,40 @@ def _search_gutenberg_catalog(
continue
if topic and topic not in subjects:
continue
+
+ lang_rank = 0 if entry.language.strip().casefold() == "en" else 1
if search:
- rank = 0 if title == search else 1 if title.startswith(search) else 2 if search in title else 3
+ text_rank = (
+ 0 if title == search
+ else 1 if title.startswith(search)
+ else 2 if search in title
+ else 3
+ )
+ sort_key = (text_rank, lang_rank, entry.gutenberg_id)
else:
- rank = 0
- matching.append((rank, entry.gutenberg_id, entry))
-
- if not search and not topic:
- return [entry for _, _, entry in matching[-12:]]
- matching.sort(key=lambda item: (item[0], -item[1] if topic and not search else item[1]))
- return [entry for _, _, entry in matching[:12]]
+ is_short_story = "short stories" in subjects and "short" not in topic
+ is_curated_novel = any(
+ tag in subjects
+ for tag in ("category: novels", "best books ever", "harvard classics")
+ )
+ browse_tier = 2 if is_short_story else (0 if is_curated_novel else 1)
+ sort_key = (lang_rank, browse_tier, entry.gutenberg_id)
+
+ matching.append((sort_key, entry))
+
+ matching.sort(key=lambda item: item[0])
+ deduplicated: list[GutenbergCatalogEntry] = []
+ seen_works: set[tuple[str, str]] = set()
+ for _, entry in matching:
+ primary_author = _display_catalog_author(entry.authors.split(";")[0]).casefold()
+ work_key = (_clean_gutenberg_title(entry.title).casefold(), primary_author)
+ if work_key in seen_works:
+ continue
+ seen_works.add(work_key)
+ deduplicated.append(entry)
+ if len(deduplicated) >= 24:
+ break
+ return deduplicated
def _gutenberg_book_from_rdf(payload: bytes, expected_id: int) -> Optional[dict]:
@@ -296,7 +368,9 @@ def _gutenberg_book_from_rdf(payload: bytes, expected_id: int) -> Optional[dict]
if ebook is None or ebook.get(f"{{{_RDF_NAMESPACES['rdf']}}}about") != f"ebooks/{expected_id}":
return None
- title = ebook.findtext("dc:title", default="", namespaces=_RDF_NAMESPACES).strip()
+ title = _clean_gutenberg_title(
+ ebook.findtext("dc:title", default="", namespaces=_RDF_NAMESPACES)
+ )
author_name = ebook.findtext(
"dc:creator/pg:agent/pg:name", default="", namespaces=_RDF_NAMESPACES
).strip()
@@ -364,10 +438,141 @@ async def _fetch_gutendex_books(client: httpx.AsyncClient, params: dict) -> Opti
return None
+def _gutenberg_recent_ids_from_feed(payload: bytes) -> list[int]:
+ if len(payload) > GUTENBERG_RECENT_FEED_MAX_BYTES:
+ raise HTTPException(status_code=502, detail="Gutenberg recent-books feed exceeds the supported size")
+ try:
+ root = ET.fromstring(payload)
+ except ET.ParseError as error:
+ raise HTTPException(status_code=502, detail="Gutenberg recent-books feed is invalid") from error
+
+ def local_name(tag: str) -> str:
+ return tag.rsplit("}", 1)[-1].casefold()
+
+ def child_text(element: ET.Element, name: str) -> str:
+ return next(
+ (
+ (child.text or child.attrib.get("href") or "").strip()
+ for child in element
+ if local_name(child.tag) == name
+ ),
+ "",
+ )
+
+ ids: list[int] = []
+ for item in (element for element in root.iter() if local_name(element.tag) == "item"):
+ link = child_text(item, "link") or child_text(item, "guid")
+ parsed_link = urlparse(link)
+ if parsed_link.scheme != "https" or parsed_link.hostname not in {"www.gutenberg.org", "gutenberg.org"}:
+ continue
+ path_parts = [part for part in parsed_link.path.split("/") if part]
+ if len(path_parts) < 2 or path_parts[0] != "ebooks" or not path_parts[1].isdigit():
+ continue
+ gutenberg_id = int(path_parts[1])
+ if gutenberg_id > 0 and gutenberg_id not in ids:
+ ids.append(gutenberg_id)
+ if len(ids) >= GUTENBERG_RECENT_FEED_MAX_ITEMS:
+ break
+ if not ids:
+ raise HTTPException(status_code=502, detail="Gutenberg recent-books feed contains no valid book links")
+ return ids
+
+
+async def _download_gutenberg_recent_feed(client: httpx.AsyncClient) -> bytes:
+ try:
+ async with client.stream("GET", GUTENBERG_RECENT_FEED_URL, headers=PROVIDER_HEADERS, timeout=15.0) as response:
+ if response.status_code != 200:
+ raise HTTPException(status_code=502, detail="Gutenberg recent-books feed returned an error")
+ content_length = response.headers.get("content-length")
+ if content_length and content_length.isdigit() and int(content_length) > GUTENBERG_RECENT_FEED_MAX_BYTES:
+ raise HTTPException(status_code=502, detail="Gutenberg recent-books feed exceeds the supported size")
+ chunks = bytearray()
+ async for chunk in response.aiter_bytes():
+ if len(chunks) + len(chunk) > GUTENBERG_RECENT_FEED_MAX_BYTES:
+ raise HTTPException(status_code=502, detail="Gutenberg recent-books feed exceeds the supported size")
+ chunks.extend(chunk)
+ except HTTPException:
+ raise
+ except httpx.HTTPError as error:
+ raise HTTPException(status_code=502, detail="Gutenberg recent-books feed is unavailable") from error
+ payload = bytes(chunks)
+ _gutenberg_recent_ids_from_feed(payload)
+ return payload
+
+
+def _matches_gutenberg_book(book: dict, params: dict) -> bool:
+ search = str(params.get("search") or "").strip().casefold()
+ topic = str(params.get("topic") or "").strip().casefold()
+ authors = book.get("authors") or []
+ author_names = " ".join(str(author.get("name") or "") for author in authors if isinstance(author, dict))
+ searchable = f"{book.get('title') or ''} {author_names}".casefold()
+ if search and search not in searchable:
+ return False
+ if topic:
+ subjects = " ".join(str(subject) for subject in book.get("subjects") or []).casefold()
+ if topic not in subjects:
+ return False
+ return True
+
+
+async def _load_gutenberg_recent_books(client: httpx.AsyncClient) -> list[dict]:
+ global _GUTENBERG_RECENT_FEED_CACHE, _GUTENBERG_RECENT_FEED_LAST_REFRESH_ATTEMPT
+
+ now = time.monotonic()
+ if _GUTENBERG_RECENT_FEED_CACHE and now - _GUTENBERG_RECENT_FEED_CACHE[0] < GUTENBERG_RECENT_FEED_TTL_SECONDS:
+ return _GUTENBERG_RECENT_FEED_CACHE[1]
+
+ async with _get_recent_feed_lock():
+ now = time.monotonic()
+ if _GUTENBERG_RECENT_FEED_CACHE and now - _GUTENBERG_RECENT_FEED_CACHE[0] < GUTENBERG_RECENT_FEED_TTL_SECONDS:
+ return _GUTENBERG_RECENT_FEED_CACHE[1]
+ if (
+ _GUTENBERG_RECENT_FEED_CACHE
+ and now - _GUTENBERG_RECENT_FEED_CACHE[0] < GUTENBERG_RECENT_FEED_MAX_STALE_SECONDS
+ and now - _GUTENBERG_RECENT_FEED_LAST_REFRESH_ATTEMPT < GUTENBERG_CATALOG_REFRESH_RETRY_SECONDS
+ ):
+ return _GUTENBERG_RECENT_FEED_CACHE[1]
+
+ _GUTENBERG_RECENT_FEED_LAST_REFRESH_ATTEMPT = now
+ try:
+ payload = await _download_gutenberg_recent_feed(client)
+ ids = _gutenberg_recent_ids_from_feed(payload)
+
+ async def fetch_book(gutenberg_id: int) -> Optional[dict]:
+ book = await _fetch_gutenberg_rdf_book(client, gutenberg_id)
+ if book is None or not _has_plain_text_format(book):
+ return None
+ return book
+
+ try:
+ results = await asyncio.wait_for(
+ asyncio.gather(*(fetch_book(gutenberg_id) for gutenberg_id in ids), return_exceptions=True),
+ timeout=GUTENBERG_RECENT_METADATA_TIMEOUT_SECONDS,
+ )
+ except asyncio.TimeoutError as error:
+ raise HTTPException(status_code=502, detail="Gutenberg recent metadata service timed out") from error
+ books = [result for result in results if isinstance(result, dict)]
+ errors = [result for result in results if isinstance(result, HTTPException)]
+ if not books and errors:
+ raise errors[0]
+ if errors:
+ logger.warning("Recent Gutenberg discovery skipped %d unavailable metadata record(s)", len(errors))
+ _GUTENBERG_RECENT_FEED_CACHE = (time.monotonic(), books)
+ return books
+ except HTTPException:
+ if (
+ _GUTENBERG_RECENT_FEED_CACHE
+ and time.monotonic() - _GUTENBERG_RECENT_FEED_CACHE[0] < GUTENBERG_RECENT_FEED_MAX_STALE_SECONDS
+ ):
+ logger.warning("Gutenberg recent-books refresh failed; serving the cached feed metadata")
+ return _GUTENBERG_RECENT_FEED_CACHE[1]
+ raise
+
+
async def _fetch_gutenberg_rdf_book(client: httpx.AsyncClient, gutenberg_id: int) -> Optional[dict]:
metadata_url = f"https://www.gutenberg.org/cache/epub/{gutenberg_id}/pg{gutenberg_id}.rdf"
try:
- async with _GUTENBERG_METADATA_SEMAPHORE:
+ async with _get_metadata_semaphore():
response = await client.get(metadata_url, headers=PROVIDER_HEADERS)
except httpx.HTTPError as error:
raise HTTPException(status_code=502, detail="Gutenberg catalog service is unavailable") from error
@@ -616,7 +821,7 @@ async def get_gutenberg_chapters(gutenberg_id: int) -> list[ChapterDTO]:
if cached is not None:
return cached
- async with _GUTENBERG_FETCH_SEMAPHORE:
+ async with _get_fetch_semaphore():
cached = _cached_gutenberg_chapters(gutenberg_id)
if cached is not None:
return cached
@@ -663,7 +868,7 @@ async def ingest_gutenberg_book(
raise HTTPException(status_code=422, detail="Unable to extract readable chapters from Gutenberg text")
authors = book.get("authors", [])
- title = str(book.get("title", "")).strip()
+ title = _clean_gutenberg_title(str(book.get("title", "")))
author_name = str(authors[0].get("name", "")).strip() if authors else ""
if not title or not author_name:
raise HTTPException(status_code=422, detail="Gutenberg metadata is incomplete")
@@ -777,7 +982,7 @@ def _story_from_gutenberg_metadata(
chapters: Optional[list[ChapterDTO]] = None,
) -> Optional[StoryDTO]:
book_id = book.get("id")
- title = str(book.get("title", "")).strip()
+ title = _clean_gutenberg_title(str(book.get("title", "")))
authors = book.get("authors", [])
author_name = str(authors[0].get("name", "")).strip() if authors else ""
if not book_id or not title or not author_name:
@@ -852,6 +1057,7 @@ async def get_gutenberg_story_by_id(gutenberg_id: int) -> StoryDTO:
async def get_gutenberg_stories(
topic: Optional[str] = None,
search: Optional[str] = None,
+ sort: str = "catalog",
) -> list[StoryDTO]:
params = {}
if topic and topic.lower() != "all":
@@ -861,8 +1067,22 @@ async def get_gutenberg_stories(
async with httpx.AsyncClient(timeout=15.0, follow_redirects=True) as client:
try:
- raw_books = await _fetch_gutenberg_catalog_books(client, params)
+ if sort == "recent":
+ raw_books = [
+ book for book in await _load_gutenberg_recent_books(client)
+ if _matches_gutenberg_book(book, params)
+ ]
+ elif sort == "popular":
+ popular_params = {**params, "sort": "popular"}
+ raw_books = await _fetch_gutendex_books(client, popular_params)
+ if raw_books is None:
+ raw_books = await _fetch_gutenberg_catalog_books(client, params)
+ logger.warning("Gutendex popular catalog unavailable; used official Gutenberg metadata")
+ else:
+ raw_books = await _fetch_gutenberg_catalog_books(client, params)
except HTTPException as official_error:
+ if sort == "recent":
+ raise
# Keep the catalog available during a Gutenberg feed outage, but
# always prefer its own CSV/RDF metadata when the official source works.
raw_books = await _fetch_gutendex_books(client, params)
@@ -878,7 +1098,11 @@ def _map_book(book: dict) -> Optional[StoryDTO]:
book_id = book.get("id")
if not book_id or not _has_plain_text_format(book):
return None
- return _story_from_gutenberg_metadata(book)
+ story = _story_from_gutenberg_metadata(book)
+ if story is not None and sort == "recent":
+ story.is_recent_submission = True
+ story.badge_text = "NEW ON GUTENBERG"
+ return story
# Full text is fetched on demand by /public/gutenberg/{id}/chapters.
return [story for book in raw_books if (story := _map_book(book)) is not None]
diff --git a/backend/services/standard_ebooks.py b/backend/services/standard_ebooks.py
new file mode 100644
index 0000000..9deb24f
--- /dev/null
+++ b/backend/services/standard_ebooks.py
@@ -0,0 +1,569 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+from urllib.parse import quote, urlencode
+from uuid import UUID, uuid5, NAMESPACE_URL
+import asyncio
+import logging
+import re
+import time
+import xml.etree.ElementTree as ET
+
+import httpx
+from fastapi import HTTPException
+
+from schemas.schemas import ChapterDTO, StoryDTO
+
+
+logger = logging.getLogger(__name__)
+
+STANDARD_EBOOKS_BASE_URL = "https://standardebooks.org"
+STANDARD_EBOOKS_NAMESPACE = uuid5(NAMESPACE_URL, "https://standardebooks.org/ebooks")
+STANDARD_EBOOKS_CATALOG_TTL_SECONDS = 1800
+STANDARD_EBOOKS_DETAIL_TTL_SECONDS = 3600
+STANDARD_EBOOKS_CHAPTER_TTL_SECONDS = 900
+STANDARD_EBOOKS_MAX_SINGLE_PAGE_BYTES = 12 * 1024 * 1024
+STANDARD_EBOOKS_USER_AGENT = "FableReader/1.0 (+https://standardebooks.org)"
+
+XHTML_NS = "http://www.w3.org/1999/xhtml"
+EPUB_NS = "http://www.idpf.org/2007/ops"
+EPUB_TYPE_ATTR = f"{{{EPUB_NS}}}type"
+
+_SLUG_PATTERN = re.compile(r"^[a-z0-9-]+(?:/[a-z0-9-]+){1,3}$")
+_WORD_COUNT_PATTERN = re.compile(r"([\d,]+)\s+words?\s*\(", re.IGNORECASE)
+
+_NON_STORY_EPUB_TYPES = frozenset({
+ "frontmatter",
+ "backmatter",
+ "titlepage",
+ "toc",
+ "imprint",
+ "colophon",
+ "uncopyright",
+ "halftitlepage",
+ "copyright-page",
+ "endnotes",
+ "loi",
+})
+
+_BLOCK_TAGS = frozenset({"p", "blockquote", "li", "h3", "h4", "h5", "h6"})
+
+_STANDARD_EBOOKS_CATALOG_CACHE: dict[tuple[str, str], tuple[float, list[StoryDTO]]] = {}
+_STANDARD_EBOOKS_DETAIL_CACHE: dict[str, tuple[float, tuple[str, str, int]]] = {}
+_STANDARD_EBOOKS_CHAPTER_CACHE: dict[str, tuple[float, list[ChapterDTO]]] = {}
+
+
+def _local_tag(tag: str) -> str:
+ return tag.rsplit("}", 1)[-1]
+
+
+def _normalize_slug(book_id: str) -> str:
+ slug = (book_id or "").strip().strip("/")
+ if slug.startswith("ebooks/"):
+ slug = slug[len("ebooks/"):]
+ if not _SLUG_PATTERN.match(slug):
+ raise HTTPException(status_code=400, detail="Invalid Standard Ebooks book identifier")
+ return slug
+
+
+def _standard_ebooks_client() -> httpx.AsyncClient:
+ return httpx.AsyncClient(
+ timeout=httpx.Timeout(25.0, connect=10.0),
+ follow_redirects=True,
+ headers={
+ "User-Agent": STANDARD_EBOOKS_USER_AGENT,
+ "Accept": "application/xhtml+xml, application/xml, text/html;q=0.9",
+ },
+ )
+
+
+def _collapse_whitespace(text: str) -> str:
+ cleaned = (text or "").replace("\u2060", "").replace("\xa0", " ")
+ return re.sub(r"\s+", " ", cleaned).strip()
+
+
+def _parse_word_count_minutes(root: ET.Element) -> int:
+ for elem in root.iter():
+ if _local_tag(elem.tag) != "p":
+ continue
+ text = "".join(elem.itertext())
+ if "reading ease" not in text.lower():
+ continue
+ match = _WORD_COUNT_PATTERN.search(text)
+ if match:
+ try:
+ words = int(match.group(1).replace(",", ""))
+ return max(1, round(words / 230))
+ except ValueError:
+ return 0
+ return 0
+
+
+def _pick_genre_from_tags(tags: list[str], fallback: str = "Classics") -> str:
+ cleaned = [t.strip() for t in tags if t.strip()]
+ specific = [t for t in cleaned if t.casefold() != "fiction"]
+ if specific:
+ return specific[0]
+ if cleaned:
+ return cleaned[0]
+ return fallback
+
+
+def parse_listing_xhtml(xml_bytes: bytes) -> list[dict[str, str]]:
+ """Extracts catalog card metadata (slug, title, author, coverUrl) from a Standard Ebooks listing page."""
+ try:
+ root = ET.fromstring(xml_bytes)
+ except ET.ParseError as exc:
+ raise HTTPException(status_code=502, detail="Invalid catalog response from Standard Ebooks") from exc
+
+ entries: list[dict[str, str]] = []
+ seen_slugs: set[str] = set()
+
+ for item in root.iter():
+ typeof_attr = item.attrib.get("typeof", "")
+ about_attr = item.attrib.get("about", "")
+ if "schema:Book" not in typeof_attr or not about_attr.startswith("/ebooks/"):
+ continue
+ slug = about_attr[len("/ebooks/"):].strip("/")
+ if not _SLUG_PATTERN.match(slug) or slug in seen_slugs:
+ continue
+
+ title_el = item.find('.//*[@property="schema:name"]')
+ title = _collapse_whitespace("".join(title_el.itertext())) if title_el is not None else ""
+ if not title:
+ continue
+
+ author_names: list[str] = []
+ for author_box in item.findall('.//*[@property="schema:author"]'):
+ name_el = author_box.find('.//*[@property="schema:name"]')
+ if name_el is not None:
+ name = _collapse_whitespace("".join(name_el.itertext()))
+ if name:
+ author_names.append(name)
+ author = ", ".join(author_names) if author_names else "Standard Ebooks"
+
+ cover_src = ""
+ for img_el in item.iter():
+ if _local_tag(img_el.tag) == "img":
+ cover_src = (img_el.attrib.get("src") or "").strip()
+ if cover_src:
+ break
+ if cover_src.startswith("/"):
+ cover_url = f"{STANDARD_EBOOKS_BASE_URL}{cover_src}"
+ elif cover_src.startswith("https://"):
+ cover_url = cover_src
+ else:
+ continue
+
+ seen_slugs.add(slug)
+ entries.append({
+ "slug": slug,
+ "title": title,
+ "author": author,
+ "cover_url": cover_url,
+ })
+
+ return entries
+
+
+def parse_book_detail_xhtml(xml_bytes: bytes, fallback_title: str = "") -> tuple[str, str, int]:
+ """Extracts (synopsis, genre, read_time_minutes) from a Standard Ebooks work page."""
+ try:
+ root = ET.fromstring(xml_bytes)
+ except ET.ParseError:
+ synopsis = f"{fallback_title} — formatted by Standard Ebooks." if fallback_title else ""
+ return synopsis, "Classics", 0
+
+ paragraphs: list[str] = []
+ desc_el = root.find('.//*[@property="schema:description"]')
+ if desc_el is not None:
+ for child in desc_el:
+ if _local_tag(child.tag) == "p":
+ p_text = _collapse_whitespace("".join(child.itertext()))
+ if p_text:
+ paragraphs.append(p_text)
+ if not paragraphs:
+ text = _collapse_whitespace("".join(desc_el.itertext()))
+ if text:
+ paragraphs.append(text)
+
+ synopsis = "\n\n".join(paragraphs)
+ if not synopsis and fallback_title:
+ synopsis = f"{fallback_title} — public-domain classic curated by Standard Ebooks."
+
+ tags: list[str] = []
+ for elem in root.iter():
+ if _local_tag(elem.tag) == "ul" and "tags" in elem.attrib.get("class", "").split():
+ for link in elem.iter():
+ if _local_tag(link.tag) == "a":
+ tag_text = _collapse_whitespace("".join(link.itertext()))
+ if tag_text:
+ tags.append(tag_text)
+ break
+
+ genre = _pick_genre_from_tags(tags)
+ read_minutes = _parse_word_count_minutes(root)
+ return synopsis, genre, read_minutes
+
+
+def _epub_types(elem: ET.Element) -> set[str]:
+ raw = elem.attrib.get(EPUB_TYPE_ATTR, "") or ""
+ return {tok.strip().lower() for tok in raw.split() if tok.strip()}
+
+
+def _is_bodymatter_element(elem: ET.Element) -> bool:
+ types = _epub_types(elem)
+ if _local_tag(elem.tag) not in ("section", "article"):
+ return False
+ if types & _NON_STORY_EPUB_TYPES:
+ return False
+ if "bodymatter" in types:
+ return True
+ # Allow explicit chapter/short-story/prologue/epilogue/part nodes if bodymatter wasn't tagged
+ return bool(types & {"chapter", "prologue", "epilogue", "part", "se:short-story"})
+
+
+def _extract_heading_title(container: ET.Element, fallback_number: int) -> str:
+ title_parts: list[str] = []
+ header_el = None
+ for child in container:
+ if _local_tag(child.tag) == "header":
+ header_el = child
+ break
+
+ if header_el is not None:
+ for sub in header_el.iter():
+ tag = _local_tag(sub.tag)
+ if tag in ("h1", "h2", "h3", "h4"):
+ txt = _collapse_whitespace("".join(sub.itertext()))
+ if txt and txt not in title_parts:
+ title_parts.append(txt)
+ elif tag == "p":
+ sub_types = _epub_types(sub)
+ if sub_types & {"title", "subtitle", "se:bridgehead", "bridgehead"} or "title" in sub.attrib.get("class", "").lower():
+ txt = _collapse_whitespace("".join(sub.itertext()))
+ if txt and txt not in title_parts:
+ title_parts.append(txt)
+ else:
+ for child in container:
+ tag = _local_tag(child.tag)
+ if tag == "hgroup":
+ for sub in child.iter():
+ if _local_tag(sub.tag) in ("h1", "h2", "h3", "h4", "p"):
+ txt = _collapse_whitespace("".join(sub.itertext()))
+ if txt and txt not in title_parts:
+ title_parts.append(txt)
+ break
+ if tag in ("h1", "h2", "h3", "h4"):
+ txt = _collapse_whitespace("".join(child.itertext()))
+ if txt:
+ title_parts.append(txt)
+ break
+
+ if title_parts:
+ if len(title_parts) > 1:
+ normalized = [part.rstrip(".:;") or part for part in title_parts[:-1]] + [title_parts[-1]]
+ return ": ".join(normalized)[:160]
+ return title_parts[0][:160]
+ elem_id = (container.attrib.get("id") or "").replace("-", " ").strip().title()
+ return elem_id or f"Chapter {fallback_number}"
+
+
+def _inline_text_without_noterefs(elem: ET.Element) -> str:
+ """Flattens element text while preserving line breaks and omitting footnote superscripts."""
+ chunks: list[str] = []
+
+ def walk(node: ET.Element) -> None:
+ tag = _local_tag(node.tag)
+ if tag == "a" and "noteref" in _epub_types(node):
+ if node.tail:
+ chunks.append(node.tail)
+ return
+ if tag == "br":
+ chunks.append("\n")
+ if node.tail:
+ chunks.append(node.tail)
+ return
+ if node.text:
+ chunks.append(node.text)
+ for child in node:
+ walk(child)
+ if node.tail and node is not elem:
+ chunks.append(node.tail)
+
+ walk(elem)
+ raw = "".join(chunks).replace("\u2060", "").replace("\xa0", " ")
+ lines = [re.sub(r"[ \t\r]+", " ", line).strip() for line in raw.split("\n")]
+ return "\n".join(line for line in lines if line)
+
+
+def _extract_prose_blocks(container: ET.Element) -> str:
+ paragraphs: list[str] = []
+ skipped_primary_heading = False
+
+ def collect(node: ET.Element) -> None:
+ tag = _local_tag(node.tag)
+ if tag in ("header", "hgroup", "nav"):
+ return
+ if tag in ("p", "h3", "h4", "h5", "h6", "li"):
+ block_text = _inline_text_without_noterefs(node)
+ if block_text:
+ paragraphs.append(block_text)
+ return
+ if tag == "blockquote":
+ has_block_children = any(_local_tag(ch.tag) in _BLOCK_TAGS for ch in node)
+ if has_block_children:
+ for ch in node:
+ collect(ch)
+ else:
+ block_text = _inline_text_without_noterefs(node)
+ if block_text:
+ paragraphs.append(block_text)
+ return
+ for ch in node:
+ collect(ch)
+
+ for child in container:
+ tag = _local_tag(child.tag)
+ # Skip direct section heading (e.g.,
I ) already promoted into chapter.title
+ if not skipped_primary_heading and not paragraphs and tag in ("h1", "h2", "h3", "h4"):
+ skipped_primary_heading = True
+ continue
+ collect(child)
+
+ return "\n\n".join(paragraphs)
+
+
+def _collect_chapter_containers(root: ET.Element) -> list[tuple[Optional[str], ET.Element]]:
+ """
+ Collects chapter-level / nodes in reading order.
+ - Anthologies () yield each story as one chapter.
+ - Multi-part novels () flatten their child sections, preserving part prefix.
+ - Standard novels yield leaf elements under /.
+ """
+ ns_map = {"x": XHTML_NS}
+ main_el = root.find(".//x:main", ns_map)
+ body_el = root.find(".//x:body", ns_map)
+ if main_el is None or len(main_el) == 0:
+ main_el = body_el if body_el is not None and len(body_el) > 0 else root
+
+ items: list[tuple[Optional[str], ET.Element]] = []
+ for child in main_el:
+ if not _is_bodymatter_element(child):
+ continue
+ tag = _local_tag(child.tag)
+ types = _epub_types(child)
+ if tag == "article":
+ items.append((None, child))
+ continue
+
+ nested_sections = [
+ sub for sub in child
+ if _is_bodymatter_element(sub)
+ ]
+ if ("part" in types or "volume" in types or "division" in types) and nested_sections:
+ part_title = _extract_heading_title(child, len(items) + 1)
+ for sub in nested_sections:
+ items.append((part_title, sub))
+ else:
+ items.append((None, child))
+
+ return items
+
+
+def parse_single_page_chapters(xml_bytes: bytes, book_slug: str, story_id: Optional[UUID] = None) -> list[ChapterDTO]:
+ """Parses Standard Ebooks `/text/single-page` XHTML into ordered `ChapterDTO` objects."""
+ try:
+ root = ET.fromstring(xml_bytes)
+ except ET.ParseError as exc:
+ raise HTTPException(status_code=502, detail="Unable to parse Standard Ebooks text document") from exc
+
+ resolved_story_id = story_id or uuid5(STANDARD_EBOOKS_NAMESPACE, f"book:{book_slug}")
+ now = datetime.now(timezone.utc)
+ containers = _collect_chapter_containers(root)
+
+ chapters: list[ChapterDTO] = []
+ chapter_idx = 1
+ for part_prefix, container in containers:
+ content = _extract_prose_blocks(container)
+ word_count = len(content.split())
+ if word_count == 0:
+ continue
+
+ raw_title = _extract_heading_title(container, chapter_idx)
+ if part_prefix and not raw_title.startswith(part_prefix):
+ title = f"{part_prefix} — {raw_title}"[:160]
+ else:
+ title = raw_title[:160]
+
+ chapters.append(
+ ChapterDTO(
+ id=uuid5(STANDARD_EBOOKS_NAMESPACE, f"book:{book_slug}:chapter:{chapter_idx}"),
+ story_id=resolved_story_id,
+ chapter_number=chapter_idx,
+ title=title,
+ content=content,
+ word_count=word_count,
+ created_at_utc=now,
+ )
+ )
+ chapter_idx += 1
+
+ return chapters
+
+
+async def _fetch_book_detail_metadata(
+ client: httpx.AsyncClient,
+ semaphore: asyncio.Semaphore,
+ slug: str,
+ title: str,
+) -> tuple[str, str, int]:
+ now = time.monotonic()
+ cached = _STANDARD_EBOOKS_DETAIL_CACHE.get(slug)
+ if cached and (now - cached[0]) < STANDARD_EBOOKS_DETAIL_TTL_SECONDS:
+ return cached[1]
+
+ async with semaphore:
+ try:
+ response = await client.get(f"{STANDARD_EBOOKS_BASE_URL}/ebooks/{slug}", timeout=8.0)
+ if response.status_code != 200:
+ fallback = (f"{title} — public-domain classic from Standard Ebooks.", "Classics", 0)
+ return fallback
+ detail = parse_book_detail_xhtml(response.content, fallback_title=title)
+ _STANDARD_EBOOKS_DETAIL_CACHE[slug] = (time.monotonic(), detail)
+ return detail
+ except httpx.HTTPError:
+ return (f"{title} — public-domain classic from Standard Ebooks.", "Classics", 0)
+
+
+async def get_standard_ebooks_stories(
+ topic: Optional[str] = None,
+ search: Optional[str] = None,
+) -> list[StoryDTO]:
+ """Fetches public-domain catalog titles from Standard Ebooks."""
+ normalized_topic = (topic or "").strip().lower()
+ normalized_search = (search or "").strip()
+ cache_key = (normalized_topic, normalized_search.casefold())
+
+ now = time.monotonic()
+ cached = _STANDARD_EBOOKS_CATALOG_CACHE.get(cache_key)
+ if cached and (now - cached[0]) < STANDARD_EBOOKS_CATALOG_TTL_SECONDS:
+ return list(cached[1])
+
+ async with _standard_ebooks_client() as client:
+ entries: list[dict[str, str]] = []
+ try:
+ if normalized_search:
+ query = urlencode({"query": normalized_search, "page": 1, "per-page": 12})
+ response = await client.get(f"{STANDARD_EBOOKS_BASE_URL}/ebooks?{query}")
+ if response.status_code == 200:
+ entries = parse_listing_xhtml(response.content)
+ elif normalized_topic:
+ slug_topic = quote(normalized_topic.replace(" ", "-"), safe="-")
+ response = await client.get(
+ f"{STANDARD_EBOOKS_BASE_URL}/subjects/{slug_topic}?sort=popularity&page=1&per-page=12"
+ )
+ if response.status_code == 200:
+ entries = parse_listing_xhtml(response.content)
+ if not entries:
+ query = urlencode({"query": normalized_topic, "sort": "popularity", "page": 1, "per-page": 12})
+ fallback_resp = await client.get(f"{STANDARD_EBOOKS_BASE_URL}/ebooks?{query}")
+ if fallback_resp.status_code == 200:
+ entries = parse_listing_xhtml(fallback_resp.content)
+ else:
+ response = await client.get(f"{STANDARD_EBOOKS_BASE_URL}/ebooks?sort=popularity&page=1&per-page=12")
+ if response.status_code == 200:
+ entries = parse_listing_xhtml(response.content)
+ else:
+ raise HTTPException(status_code=502, detail="Standard Ebooks catalog service is unavailable")
+ except HTTPException:
+ raise
+ except httpx.HTTPError as exc:
+ logger.warning("Standard Ebooks catalog fetch failed: %s", exc)
+ raise HTTPException(status_code=502, detail="Standard Ebooks catalog service is unavailable") from exc
+
+ entries = entries[:12]
+ semaphore = asyncio.Semaphore(6)
+ details = await asyncio.gather(
+ *(
+ _fetch_book_detail_metadata(client, semaphore, entry["slug"], entry["title"])
+ for entry in entries
+ )
+ )
+
+ stories: list[StoryDTO] = []
+ timestamp = datetime.now(timezone.utc)
+ for entry, (synopsis, genre, read_minutes) in zip(entries, details):
+ slug = entry["slug"]
+ stories.append(
+ StoryDTO(
+ id=uuid5(STANDARD_EBOOKS_NAMESPACE, f"book:{slug}"),
+ title=entry["title"][:120],
+ author=entry["author"][:80],
+ genre=genre,
+ chapter="",
+ synopsis=synopsis,
+ content="",
+ read_time_minutes=read_minutes,
+ is_bookmarked=False,
+ is_completed=False,
+ created_at_utc=timestamp,
+ updated_at_utc=timestamp,
+ cover_image_url=entry["cover_url"],
+ total_pages=0,
+ current_page=1,
+ progress_percent=0,
+ saves_count="0",
+ reads_count="0",
+ badge_text=None,
+ total_chapters=0,
+ content_format="PROSE",
+ source_provider="STANDARD_EBOOKS",
+ provider_id=slug,
+ provider_download_count=None,
+ chapters=None,
+ )
+ )
+
+ _STANDARD_EBOOKS_CATALOG_CACHE[cache_key] = (time.monotonic(), stories)
+ return list(stories)
+
+
+async def get_standard_ebooks_chapters(book_id: str) -> list[ChapterDTO]:
+ """Fetches and parses the semantic XHTML chapter tree for a Standard Ebooks work."""
+ slug = _normalize_slug(book_id)
+ now = time.monotonic()
+ cached = _STANDARD_EBOOKS_CHAPTER_CACHE.get(slug)
+ if cached and (now - cached[0]) < STANDARD_EBOOKS_CHAPTER_TTL_SECONDS:
+ return list(cached[1])
+
+ url = f"{STANDARD_EBOOKS_BASE_URL}/ebooks/{slug}/text/single-page"
+ try:
+ async with _standard_ebooks_client() as client:
+ async with client.stream("GET", url) as response:
+ if response.status_code == 404:
+ raise HTTPException(status_code=404, detail="Standard Ebooks title not found")
+ if response.status_code != 200:
+ raise HTTPException(status_code=502, detail="Unable to download text from Standard Ebooks")
+
+ chunks: list[bytes] = []
+ total_bytes = 0
+ async for chunk in response.aiter_bytes():
+ total_bytes += len(chunk)
+ if total_bytes > STANDARD_EBOOKS_MAX_SINGLE_PAGE_BYTES:
+ raise HTTPException(status_code=413, detail="Standard Ebooks document exceeds size limit")
+ chunks.append(chunk)
+ payload = b"".join(chunks)
+ except HTTPException:
+ raise
+ except httpx.HTTPError as exc:
+ logger.warning("Standard Ebooks text fetch failed for %s: %s", slug, exc)
+ raise HTTPException(status_code=502, detail="Standard Ebooks text service is unavailable") from exc
+
+ chapters = parse_single_page_chapters(payload, slug)
+ if not chapters:
+ raise HTTPException(status_code=422, detail="No readable chapters found in Standard Ebooks work")
+
+ _STANDARD_EBOOKS_CHAPTER_CACHE[slug] = (time.monotonic(), chapters)
+ return list(chapters)
diff --git a/backend/services/text_parser.py b/backend/services/text_parser.py
index 9014f06..fba14b3 100644
--- a/backend/services/text_parser.py
+++ b/backend/services/text_parser.py
@@ -11,6 +11,216 @@ def _normalize_paragraphs(text: str) -> str:
return "\n\n".join(paragraphs)
+_NUMBER_WORD_PATTERN = (
+ r"(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine|Ten|"
+ r"Eleven|Twelve|Thirteen|Fourteen|Fifteen|Sixteen|Seventeen|Eighteen|Nineteen|"
+ r"Twenty(?:[-\s]+(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine))?|"
+ r"Thirty(?:[-\s]+(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine))?|"
+ r"Forty(?:[-\s]+(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine))?|"
+ r"Fifty(?:[-\s]+(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine))?|"
+ r"Sixty(?:[-\s]+(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine))?|"
+ r"Seventy(?:[-\s]+(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine))?|"
+ r"Eighty(?:[-\s]+(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine))?|"
+ r"Ninety(?:[-\s]+(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine))?|"
+ r"(?:The\s+)?(?:First|Second|Third|Fourth|Fifth|Sixth|Seventh|Eighth|Ninth|Tenth|"
+ r"Eleventh|Twelfth|Thirteenth|Fourteenth|Fifteenth|Sixteenth|Seventeenth|"
+ r"Eighteenth|Nineteenth|Twentieth|Last))"
+)
+
+_EXPLICIT_HEADING_PATTERN = (
+ rf"(?:^|\n{{2,}})[ \t]*[*_]?"
+ rf"((?:CHAPTER|Chapter|STAVE|Stave|LETTER|Letter|BOOK|Book|ACT|Act|PART|Part|CANTO|Canto)"
+ rf"[ \t]+(?:[0-9IVXLCDM]+|{_NUMBER_WORD_PATTERN})[^\n]*?)"
+ rf"[*_]?[ \t]*(?=\n|$)"
+)
+
+_TOC_LINE_PATTERN = re.compile(
+ r"^[ \t]*[*_]?(?:CHAPTER|Chapter|STAVE|Stave|LETTER|Letter|BOOK|Book|ACT|Act|PART|Part|CANTO|Canto)\b",
+ re.MULTILINE,
+)
+
+_TOC_ROMAN_LINE_PATTERN = re.compile(
+ r"^[ \t]*[IVXLCDM]{1,7}\.[ \t]+[A-Z]",
+ re.MULTILINE,
+)
+
+_TOC_BARE_ROMAN_PATTERN = re.compile(
+ r"^[ \t]*[IVXLCDM]{1,6}\.?[ \t]*\n(?:[ \t]*\n)*[ \t]*[IVXLCDM]{1,6}\.?[ \t]*$",
+ re.MULTILINE,
+)
+
+
+def _is_toc_listing(body: str) -> bool:
+ stripped = body.strip()
+ if len(stripped) < 50:
+ return True
+ words = len(stripped.split())
+ toc_lines = len(_TOC_LINE_PATTERN.findall(stripped))
+ roman_toc_lines = len(_TOC_ROMAN_LINE_PATTERN.findall(stripped))
+ head_block = "\n".join(stripped.splitlines()[:20])
+ has_adjacent_bare_romans = bool(_TOC_BARE_ROMAN_PATTERN.search(head_block))
+ if (toc_lines >= 2 or roman_toc_lines >= 2 or has_adjacent_bare_romans) and words < 450:
+ return True
+ return False
+
+
+def _clean_chapter_title(raw_title: str) -> str:
+ return re.sub(r"[ \t]+", " ", raw_title.strip().strip("*_").rstrip("]").strip())
+
+
+def _normalize_heading_key(text: str) -> str:
+ normalized = text.replace("’", "'").replace("‘", "'").replace("“", '"').replace("”", '"')
+ return re.sub(r"\s+", " ", normalized).strip().casefold()
+
+
+def _extract_roman_sections(raw_text: str) -> list[dict]:
+ """Extracts either titled Roman chapters ('I. Title') or standalone Roman markers ('\\n\\nI\\n\\n')."""
+ roman_titled_pattern = (
+ r"(?:^|\n{2,})[ \t]*([IVXLCDM]{1,7}\.[ \t]+[^\n]{2,80})[ \t]*(?=\n|$)"
+ r"|"
+ r"(?:^|\n{2,})[ \t]*([IVXLCDM]{1,7}\.[ \t]*\n[ \t]*[A-Z][^\n]{1,80})[ \t]*(?=\n{2,})"
+ )
+ roman_titled_splits = re.split(roman_titled_pattern, raw_text)
+ if len(roman_titled_splits) > 3:
+ extracted: list[dict] = []
+ chapter_idx = 1
+ for i in range(1, len(roman_titled_splits), 3):
+ raw_heading = roman_titled_splits[i] or roman_titled_splits[i + 1] or ""
+ ch_body = roman_titled_splits[i + 2].strip() if i + 2 < len(roman_titled_splits) else ""
+ ch_title = _clean_chapter_title(raw_heading.replace("\n", " "))
+ if ch_title and not _is_toc_listing(ch_body):
+ normalized_body = _normalize_paragraphs(ch_body)
+ words = len(normalized_body.split())
+ if words > 0:
+ extracted.append({
+ "chapter_number": chapter_idx,
+ "title": ch_title,
+ "content": normalized_body,
+ "word_count": words,
+ })
+ chapter_idx += 1
+ if len(extracted) >= 2:
+ return extracted
+
+ roman_pattern = r'(?:^|\n{2,})[ \t]*([IVXLCDM]{1,7})\.?[ \t]*\n{2,}'
+ roman_splits = re.split(roman_pattern, raw_text)
+ if len(roman_splits) > 2:
+ extracted = []
+ chapter_idx = 1
+ for i in range(1, len(roman_splits), 2):
+ ch_title = f"Chapter {roman_splits[i].strip()}"
+ ch_body = roman_splits[i + 1].strip() if i + 1 < len(roman_splits) else ""
+ if len(ch_body.strip()) >= 50:
+ normalized_body = _normalize_paragraphs(ch_body)
+ words = len(normalized_body.split())
+ if words > 0:
+ extracted.append({
+ "chapter_number": chapter_idx,
+ "title": ch_title,
+ "content": normalized_body,
+ "word_count": words,
+ })
+ chapter_idx += 1
+ if len(extracted) >= 2:
+ return extracted
+
+ return []
+
+
+def _extract_chapters_from_contents(clean_text: str) -> list[dict]:
+ """
+ Fallback for books whose chapters are unnumbered named sections declared under a Contents block
+ (e.g., Dr. Jekyll and Mr. Hyde: 'STORY OF THE DOOR', 'SEARCH FOR MR. HYDE', ...).
+ """
+ if len(clean_text.split()) < 3000:
+ return []
+
+ search_limit = min(len(clean_text), max(12000, len(clean_text) // 4))
+ toc_header = re.search(
+ r"(?:^|\n)[ \t]*(?:TABLE OF )?CONTENTS[.:]?[ \t]*\n",
+ clean_text[:search_limit],
+ re.IGNORECASE,
+ )
+ if not toc_header:
+ return []
+
+ lines_with_offsets: list[tuple[int, str]] = []
+ pos = toc_header.end()
+ for line in clean_text[pos:].splitlines(keepends=True):
+ lines_with_offsets.append((pos, line.rstrip("\r\n")))
+ pos += len(line)
+ if pos - toc_header.end() > 8000:
+ break
+
+ candidates: list[str] = []
+ seen_keys: set[str] = set()
+ first_key = ""
+ toc_end_offset = toc_header.end()
+ blank_streak = 0
+
+ for offset, raw_line in lines_with_offsets:
+ stripped = re.sub(r"\s+", " ", raw_line).strip()
+ if not stripped:
+ blank_streak += 1
+ if blank_streak >= 3 and len(candidates) >= 3:
+ toc_end_offset = offset
+ break
+ continue
+ blank_streak = 0
+ key = _normalize_heading_key(stripped)
+ # Body repeats the first TOC entry -> TOC ended right before this heading
+ if first_key and key == first_key:
+ toc_end_offset = offset
+ break
+ if len(stripped) > 90 or len(stripped) < 3 or len(candidates) >= 60:
+ toc_end_offset = offset
+ break
+ if key not in seen_keys:
+ seen_keys.add(key)
+ candidates.append(stripped)
+ if not first_key:
+ first_key = key
+ toc_end_offset = offset + len(raw_line) + 1
+
+ if len(candidates) < 3:
+ return []
+
+ candidate_by_key = {_normalize_heading_key(title): title for title in candidates}
+ body_text = clean_text[toc_end_offset:]
+
+ matched_positions: list[tuple[int, int, str]] = []
+ cursor = 0
+ for line in body_text.splitlines(keepends=True):
+ line_len = len(line)
+ stripped = re.sub(r"\s+", " ", line).strip()
+ key = _normalize_heading_key(stripped)
+ if key in candidate_by_key and key not in {m[2] for m in matched_positions}:
+ matched_positions.append((cursor, cursor + line_len, stripped))
+ cursor += line_len
+
+ if len(matched_positions) < 3 or len(matched_positions) < max(3, int(len(candidates) * 0.6)):
+ return []
+
+ extracted: list[dict] = []
+ chapter_idx = 1
+ for idx, (start_off, header_end, heading_title) in enumerate(matched_positions):
+ next_start = matched_positions[idx + 1][0] if idx + 1 < len(matched_positions) else len(body_text)
+ ch_body = body_text[header_end:next_start].strip()
+ if len(ch_body) >= 50:
+ normalized_body = _normalize_paragraphs(ch_body)
+ words = len(normalized_body.split())
+ if words > 0:
+ extracted.append({
+ "chapter_number": chapter_idx,
+ "title": heading_title.title() if heading_title.isupper() else heading_title,
+ "content": normalized_body,
+ "word_count": words,
+ })
+ chapter_idx += 1
+
+ return extracted if len(extracted) >= 3 else []
+
+
def extract_chapters_from_text(raw_text: str) -> list[dict]:
"""
Parses raw full-length text from Project Gutenberg or external literary sites,
@@ -24,18 +234,36 @@ def extract_chapters_from_text(raw_text: str) -> list[dict]:
end_pos = end_match.start() if end_match else len(normalized_raw)
clean_text = normalized_raw[start_pos:end_pos].strip()
- # Match standard Chapter markers or Roman numeral story headers
- pattern = r'(?:^|\n{2,})(CHAPTER\s+[0-9IVXLCDM]+[^\n]*|Chapter\s+[0-9IVXLCDM]+[^\n]*|ACT\s+[0-9IVXLCDM]+[^\n]*|BOOK\s+[0-9IVXLCDM]+[^\n]*|[IVXLCDM]+\.\s+[A-Z][^\n]{2,80})'
- splits = re.split(pattern, clean_text)
-
extracted: list[dict] = []
+
+ # 1. Explicit structural headings (CHAPTER I, _Chapter One_, STAVE I, PART I, BOOK II, etc.)
+ splits = re.split(_EXPLICIT_HEADING_PATTERN, clean_text, flags=re.IGNORECASE)
if len(splits) > 2:
- chapter_idx = 1
+ raw_parts: list[tuple[str, str]] = []
for i in range(1, len(splits), 2):
- ch_title = splits[i].strip().rstrip("]").strip()
- ch_body = splits[i+1].strip() if i+1 < len(splits) else ""
- # Filter out table of contents listings
- if len(ch_body.strip()) >= 50 and ch_body.count("CHAPTER ") < 3 and ch_body.count("Chapter ") < 3:
+ ch_title = _clean_chapter_title(splits[i])
+ ch_body = splits[i + 1].strip() if i + 1 < len(splits) else ""
+ if not _is_toc_listing(ch_body):
+ raw_parts.append((ch_title, ch_body))
+
+ chapter_idx = 1
+ for ch_title, ch_body in raw_parts:
+ # Subdivide coarse PART/BOOK containers if they contain Roman-numeral subchapters
+ sub_chapters = (
+ _extract_roman_sections(ch_body)
+ if len(raw_parts) <= 10 and ch_title.upper().startswith(("PART ", "BOOK ", "VOLUME "))
+ else []
+ )
+ if len(sub_chapters) >= 2:
+ for sub in sub_chapters:
+ extracted.append({
+ "chapter_number": chapter_idx,
+ "title": f"{ch_title} — {sub['title']}",
+ "content": sub["content"],
+ "word_count": sub["word_count"],
+ })
+ chapter_idx += 1
+ else:
normalized_body = _normalize_paragraphs(ch_body)
words = len(normalized_body.split())
if words > 0:
@@ -43,32 +271,19 @@ def extract_chapters_from_text(raw_text: str) -> list[dict]:
"chapter_number": chapter_idx,
"title": ch_title,
"content": normalized_body,
- "word_count": words
+ "word_count": words,
})
chapter_idx += 1
- # Fallback to Roman numeral markers (\n\nI\n\n, \n\nII\n\n)
- if not extracted:
- roman_pattern = r'\n{2,}([IVXLCDM]+)\s*\n{2,}'
- roman_splits = re.split(roman_pattern, clean_text)
- if len(roman_splits) > 2:
- chapter_idx = 1
- for i in range(1, len(roman_splits), 2):
- ch_title = f"Chapter {roman_splits[i].strip()}"
- ch_body = roman_splits[i+1].strip() if i+1 < len(roman_splits) else ""
- if len(ch_body.strip()) >= 50:
- normalized_body = _normalize_paragraphs(ch_body)
- words = len(normalized_body.split())
- if words > 0:
- extracted.append({
- "chapter_number": chapter_idx,
- "title": ch_title,
- "content": normalized_body,
- "word_count": words
- })
- chapter_idx += 1
-
- # Single-chapter tale fallback
+ # 2 & 3. Roman numeral headings ("I. Title") or standalone Roman markers ("\n\nI\n\n")
+ if len(extracted) < 2:
+ extracted = _extract_roman_sections(clean_text)
+
+ # 4. Contents-guided unnumbered chapter headings (e.g., Dr. Jekyll and Mr. Hyde)
+ if len(extracted) < 2:
+ extracted = _extract_chapters_from_contents(clean_text)
+
+ # 5. Single-chapter tale fallback
if not extracted:
normalized_body = _normalize_paragraphs(clean_text)
words = len(normalized_body.split())
@@ -76,7 +291,7 @@ def extract_chapters_from_text(raw_text: str) -> list[dict]:
"chapter_number": 1,
"title": "Chapter I: The Complete Tale",
"content": normalized_body,
- "word_count": words
+ "word_count": words,
})
return extracted
diff --git a/backend/test_main.py b/backend/test_main.py
index 75f7a9d..614b492 100644
--- a/backend/test_main.py
+++ b/backend/test_main.py
@@ -281,6 +281,137 @@ def test_extract_chapters_from_text():
assert chapters[1]["chapter_number"] == 2
assert "CHAPTER II" in chapters[1]["title"]
+
+def test_extract_chapters_handles_centered_italic_spelled_out_and_staves():
+ from main import extract_chapters_from_text
+
+ # 1. Centered headers and body text mentioning "Chapter" 3+ times must stay split.
+ centered = (
+ " CHAPTER I\n\n"
+ "First chapter text references Chapter 1, Chapter 2, and Chapter 3 inside the narrative "
+ "along with enough prose words to exceed the minimum length check cleanly.\n\n"
+ " CHAPTER II\n\n"
+ "Second chapter picks up the plot immediately with plenty of narrative detail here."
+ )
+ centered_chaps = extract_chapters_from_text(centered)
+ assert [c["title"] for c in centered_chaps] == ["CHAPTER I", "CHAPTER II"]
+
+ # 2. Italic spelled-out headers (_Chapter One_, _Chapter Two_) and TOC skipping.
+ spelled_out = (
+ "CONTENTS\n\n"
+ "Chapter One\nChapter Two\nChapter Three\n\n"
+ "_Chapter One_\n\n"
+ "The hero stood at the threshold of a distant crimson sea waiting for the tide.\n\n"
+ "_Chapter Two_\n\n"
+ "Across the moonlit citadel the ancient bells rang out across the courtyard."
+ )
+ spelled_chaps = extract_chapters_from_text(spelled_out)
+ assert [c["title"] for c in spelled_chaps] == ["Chapter One", "Chapter Two"]
+
+ # 3. Stave headings (A Christmas Carol style)
+ staves = (
+ "CONTENTS\n\n"
+ "Stave I: Marley's Ghost\n"
+ "Stave II: The First Spirit\n\n"
+ "STAVE I: MARLEY'S GHOST\n\n"
+ "Marley was dead to begin with, and there was no doubt whatever about that in London.\n\n"
+ "STAVE II: THE FIRST OF THE THREE SPIRITS\n\n"
+ "When Scrooge awoke it was so dark that he could scarcely distinguish the window."
+ )
+ stave_chaps = extract_chapters_from_text(staves)
+ assert [c["title"] for c in stave_chaps] == [
+ "STAVE I: MARLEY'S GHOST",
+ "STAVE II: THE FIRST OF THE THREE SPIRITS",
+ ]
+
+ # 4. Indented Roman numerals with subtitle on the following line (Time Machine style)
+ roman_indented = (
+ " I.\n"
+ " Introduction\n\n"
+ "The Time Traveller was expounding a recondite matter to all of us after dinner.\n\n"
+ " II.\n"
+ " The Machine\n\n"
+ "The thing the Time Traveller held in his hand was a glittering metallic framework."
+ )
+ roman_chaps = extract_chapters_from_text(roman_indented)
+ assert [c["title"] for c in roman_chaps] == ["I. Introduction", "II. The Machine"]
+
+
+def test_extract_chapters_handles_contents_unnumbered_chapters_and_nested_parts():
+ from main import extract_chapters_from_text
+
+ # 1. Contents-guided unnumbered chapters (Jekyll & Hyde style >= 3,000 words)
+ filler_prose = " ".join(["London fog crept silently down the narrow lane while candles flickered."] * 105)
+ unnumbered = (
+ "Contents\n\n"
+ " STORY OF THE DOOR\n"
+ " SEARCH FOR MR. HYDE\n"
+ " THE CAREW MURDER CASE\n\n\n\n"
+ "STORY OF THE DOOR\n\n"
+ f"{filler_prose}\n\n"
+ "SEARCH FOR MR. HYDE\n\n"
+ f"{filler_prose}\n\n"
+ "THE CAREW MURDER CASE\n\n"
+ f"{filler_prose}\n"
+ )
+ unnumbered_chaps = extract_chapters_from_text(unnumbered)
+ assert [c["title"] for c in unnumbered_chaps] == [
+ "Story Of The Door",
+ "Search For Mr. Hyde",
+ "The Carew Murder Case",
+ ]
+
+ # 2. Nested PART + Roman subchapters while filtering bare-Roman TOC blocks (O Pioneers! style)
+ nested_parts = (
+ "Contents\n\n"
+ " PART I. The Wild Land\n I\n II\n\n"
+ " PART II. Neighboring Fields\n I\n II\n\n"
+ "Dedication to old Nebraska pioneers.\n\n\n"
+ "PART I. The Wild Land\n\n"
+ "I\n\n"
+ "On the divide the wind swept across the brown prairies where Alexandra walked carefully.\n\n"
+ "II\n\n"
+ "After supper Emil ran along the pasture fence while the winter stars emerged overhead.\n\n"
+ "PART II. Neighboring Fields\n\n"
+ "I\n\n"
+ "Years later the lush cornfields bordered the white farmhouse along the timber claim.\n\n"
+ "II\n\n"
+ "Carl Linstrum returned at dusk and paused beside the mulberry hedge at the gate."
+ )
+ part_chaps = extract_chapters_from_text(nested_parts)
+ assert [c["title"] for c in part_chaps] == [
+ "PART I. The Wild Land — Chapter I",
+ "PART I. The Wild Land — Chapter II",
+ "PART II. Neighboring Fields — Chapter I",
+ "PART II. Neighboring Fields — Chapter II",
+ ]
+
+
+def test_extract_chapters_from_text_recognizes_spelled_out_chapter_headings():
+ from main import extract_chapters_from_text
+
+ raw_sample = """
+*** START OF THE PROJECT GUTENBERG EBOOK TEST ***
+
+chapter the first
+The first part contains enough prose to distinguish a real chapter from a contents listing.
+It continues with another paragraph so the reader receives a substantial chapter body.
+
+CHAPTER TWO. THE JOURNEY
+The second part also contains enough prose to qualify as a chapter of this full-length work.
+Readers can follow the chapter sequence instead of seeing the entire novel as one section.
+
+*** END OF THE PROJECT GUTENBERG EBOOK TEST ***
+"""
+
+ chapters = extract_chapters_from_text(raw_sample)
+
+ assert len(chapters) == 2
+ assert [chapter["chapter_number"] for chapter in chapters] == [1, 2]
+ assert chapters[0]["title"].casefold() == "chapter the first"
+ assert chapters[1]["title"].casefold() == "chapter two. the journey"
+
+
def test_get_genres_endpoint():
created = client.post("/api/v1/stories", headers=auth_headers(), json={
"title": "Genre Count Story",
diff --git a/backend/test_provider_http.py b/backend/test_provider_http.py
index f9f3ede..20c101d 100644
--- a/backend/test_provider_http.py
+++ b/backend/test_provider_http.py
@@ -146,6 +146,79 @@ async def no_matches(_client, params):
assert response.json() == []
+def _gutenberg_http_book(gutenberg_id, title, author="Austen, Jane"):
+ return {
+ "id": gutenberg_id,
+ "title": title,
+ "authors": [{"name": author}],
+ "subjects": ["Fiction"],
+ "summaries": [],
+ "download_count": 12345,
+ "formats": {
+ "text/plain; charset=utf-8": f"https://www.gutenberg.org/ebooks/{gutenberg_id}.txt.utf-8",
+ "image/jpeg": f"https://www.gutenberg.org/cache/epub/{gutenberg_id}/pg{gutenberg_id}.cover.medium.jpg",
+ },
+ }
+
+
+def test_gutenberg_recent_http_collection_marks_recent_titles_and_keeps_chapters_lazy(monkeypatch):
+ from services import gutenberg
+
+ async def recent_books(_client):
+ return [_gutenberg_http_book(79999, "Newly Added Novel")]
+
+ monkeypatch.setattr(gutenberg, "_load_gutenberg_recent_books", recent_books)
+ response = client.get("/api/v1/public/gutenberg?sort=recent")
+
+ assert response.status_code == 200
+ books = response.json()
+ assert len(books) == 1
+ assert books[0]["providerId"] == "79999"
+ assert books[0]["title"] == "Newly Added Novel"
+ assert books[0]["author"] == "Jane Austen"
+ assert books[0]["sourceProvider"] == "GUTENBERG"
+ assert books[0]["isRecentSubmission"] is True
+ assert books[0]["badgeText"] == "NEW ON GUTENBERG"
+ assert books[0]["totalChapters"] == 0
+ assert books[0]["content"] == ""
+
+
+def test_gutenberg_popular_http_collection_uses_gutendex_popularity_order(monkeypatch):
+ from services import gutenberg
+
+ async def popular_books(_client, params):
+ assert params == {"topic": "fiction", "sort": "popular"}
+ return [
+ _gutenberg_http_book(1342, "Pride and Prejudice"),
+ _gutenberg_http_book(11, "Alice's Adventures in Wonderland", "Carroll, Lewis"),
+ ]
+
+ monkeypatch.setattr(gutenberg, "_fetch_gutendex_books", popular_books)
+ response = client.get("/api/v1/public/gutenberg?topic=fiction&sort=popular")
+
+ assert response.status_code == 200
+ books = response.json()
+ assert [book["title"] for book in books] == [
+ "Pride and Prejudice",
+ "Alice's Adventures in Wonderland",
+ ]
+ assert [book["providerId"] for book in books] == ["1342", "11"]
+ assert all(book["sourceProvider"] == "GUTENBERG" for book in books)
+
+
+def test_gutenberg_recent_feed_accepts_only_official_ebook_links():
+ from services.gutenberg import _gutenberg_recent_ids_from_feed
+
+ feed = b"""
+
+ Latest Book https://www.gutenberg.org/ebooks/79999
+ External Link https://example.org/ebooks/88888
+ Duplicate https://www.gutenberg.org/ebooks/79999
+ """
+
+ assert _gutenberg_recent_ids_from_feed(feed) == [79999]
+
+
def test_gutenberg_chapters_http_endpoint_falls_back_and_returns_provider_text(monkeypatch):
from contextlib import asynccontextmanager
@@ -249,3 +322,86 @@ async def unavailable_stream(self, method, url, headers=None, **kwargs):
assert response.json()["detail"] == "Gutenberg text service is unavailable"
assert "private primary transport detail" not in response.text
assert "private fallback transport detail" not in response.text
+
+
+def test_standard_ebooks_http_endpoints_return_catalog_and_chapters(monkeypatch):
+ from contextlib import asynccontextmanager
+ import httpx
+ from services import standard_ebooks
+
+ monkeypatch.setattr(standard_ebooks, "_STANDARD_EBOOKS_CATALOG_CACHE", {})
+ monkeypatch.setattr(standard_ebooks, "_STANDARD_EBOOKS_DETAIL_CACHE", {})
+ monkeypatch.setattr(standard_ebooks, "_STANDARD_EBOOKS_CHAPTER_CACHE", {})
+
+ listing_xml = b"""
+
+
+
+ Frankenstein
+ Mary Shelley
+
+
+
+ """
+
+ detail_xml = b"""
+
+
+ Victor Frankenstein assembles a creature.
+
+
+ """
+
+ single_page_xml = b"""
+
+
+
+ Letter I
+ To Mrs. Saville, England. You will rejoice to hear that no disaster has accompanied me.
+
+
+ Chapter I
+ I am by birth a Genevese, and my family is one of the most distinguished of that republic.
+
+
+ """
+
+ async def mock_get(self, url, params=None, headers=None, **kwargs):
+ url_str = str(url)
+ if url_str.endswith("/subjects/fiction?sort=popularity&page=1&per-page=12"):
+ return httpx.Response(200, content=listing_xml)
+ if url_str.endswith("/ebooks/mary-shelley/frankenstein"):
+ return httpx.Response(200, content=detail_xml)
+ return httpx.Response(404, content=b"")
+
+ @asynccontextmanager
+ async def mock_stream(self, method, url, headers=None, **kwargs):
+ if str(url).endswith("/ebooks/mary-shelley/frankenstein/text/single-page"):
+ yield httpx.Response(200, content=single_page_xml)
+ else:
+ yield httpx.Response(404, content=b"")
+
+ monkeypatch.setattr(httpx.AsyncClient, "get", mock_get)
+ monkeypatch.setattr(httpx.AsyncClient, "stream", mock_stream)
+
+ catalog_resp = client.get("/api/v1/public/standard-ebooks?topic=fiction")
+ assert catalog_resp.status_code == 200
+ stories = catalog_resp.json()
+ assert len(stories) == 1
+ assert stories[0]["sourceProvider"] == "STANDARD_EBOOKS"
+ assert stories[0]["providerId"] == "mary-shelley/frankenstein"
+ assert stories[0]["genre"] == "Horror"
+
+ chapters_resp = client.get(
+ "/api/v1/public/standard-ebooks/chapters",
+ params={"book_id": "mary-shelley/frankenstein"},
+ )
+ assert chapters_resp.status_code == 200
+ chapters = chapters_resp.json()
+ assert [c["title"] for c in chapters] == ["Letter I", "Chapter I"]
+
+ bad_resp = client.get(
+ "/api/v1/public/standard-ebooks/chapters",
+ params={"book_id": "../etc/passwd"},
+ )
+ assert bad_resp.status_code == 400
diff --git a/backend/test_provider_services.py b/backend/test_provider_services.py
index 90a1684..f6345db 100644
--- a/backend/test_provider_services.py
+++ b/backend/test_provider_services.py
@@ -105,3 +105,192 @@ async def unavailable_catalog():
monkeypatch.setattr(gutenberg, "get_gutenberg_authors", unavailable_catalog)
assert await story_service.get_top_authors() == []
+
+
+def test_gutenberg_fiction_browse_prefers_english_classic_novels_over_recent_shorts():
+ from services import gutenberg
+
+ entries = [
+ gutenberg.GutenbergCatalogEntry(
+ gutenberg_id=79931,
+ title="Recent Short Story",
+ authors="Author, Recent",
+ subjects="Fiction; Short stories",
+ bookshelves="",
+ language="en",
+ ),
+ gutenberg.GutenbergCatalogEntry(
+ gutenberg_id=45,
+ title="Anne of Green Gables",
+ authors="Montgomery, L. M.",
+ subjects="Fiction",
+ bookshelves="Category: Novels",
+ language="en",
+ ),
+ gutenberg.GutenbergCatalogEntry(
+ gutenberg_id=20,
+ title="Roman Historique",
+ authors="Auteur, Autre",
+ subjects="Fiction",
+ bookshelves="Category: Novels",
+ language="fr",
+ ),
+ ]
+
+ ranked = gutenberg._search_gutenberg_catalog(entries, {"topic": "fiction"})
+ assert [entry.gutenberg_id for entry in ranked] == [45, 79931, 20]
+
+
+def test_standard_ebooks_xhtml_parsers_handle_chapters_parts_and_anthologies():
+ from services import standard_ebooks
+
+ listing_xml = b"""
+
+
+
+
+
+ Dracula
+ Bram Stoker
+
+
+
+
+
+ """
+ cards = standard_ebooks.parse_listing_xhtml(listing_xml)
+ assert len(cards) == 1
+ assert cards[0]["slug"] == "bram-stoker/dracula"
+ assert cards[0]["cover_url"] == "https://standardebooks.org/images/covers/bram-stoker_dracula/abc/cover@2x.jpg"
+
+ detail_xml = b"""
+
+
+
+ Jonathan Harker travels to Transylvania.
+
+ 161,105 words (9 hours 46 minutes) with a reading ease of 77.57 (fairly easy).
+
+
+ """
+ synopsis, genre, minutes = standard_ebooks.parse_book_detail_xhtml(detail_xml, "Dracula")
+ assert "Transylvania" in synopsis
+ assert genre == "Horror"
+ assert minutes > 500
+
+ single_page_xml = b"""
+
+
+
+
+
+ Part I
+
+
+ Left Munich at dusk.1
+ Crossed the Carpathian pass.
+
+
+
+ A Scandal in Bohemia
+ To Sherlock Holmes she is always the woman.
+ I had seen little of Holmes lately.
+
+
+
+
+ """
+ chapters = standard_ebooks.parse_single_page_chapters(single_page_xml, "bram-stoker/dracula")
+ assert len(chapters) == 2
+ assert chapters[0].title == "Part I — I: Harker's Journal"
+ assert chapters[0].content == "Left Munich at dusk.\n\nCrossed the Carpathian pass."
+ assert chapters[1].title == "A Scandal in Bohemia"
+ assert "To Sherlock Holmes she is always the woman." in chapters[1].content
+ assert "I had seen little of Holmes lately." in chapters[1].content
+
+
+def test_standard_ebooks_chapter_parser_falls_back_from_empty_main():
+ from services import standard_ebooks
+
+ xml_doc = b"""
+
+
+
+
+
+ This chapter lives directly under body when the main element is empty.
+
+
+ """
+
+ chapters = standard_ebooks.parse_single_page_chapters(xml_doc, "example/empty-main")
+
+ assert len(chapters) == 1
+ assert chapters[0].title == "Chapter I"
+ assert chapters[0].content == "This chapter lives directly under body when the main element is empty."
+
+
+def test_gutenberg_cleans_marc_title_and_deduplicates_editions():
+ from services import gutenberg
+
+ assert gutenberg._clean_gutenberg_title("Peter Pan : $b [Peter and Wendy]") == "Peter Pan: [Peter and Wendy]"
+
+ entries = [
+ gutenberg.GutenbergCatalogEntry(
+ gutenberg_id=42,
+ title="Dr. Jekyll and Mr. Hyde",
+ authors="Stevenson, Robert Louis",
+ subjects="Fiction; Horror",
+ bookshelves="Gothic Fiction",
+ language="en",
+ ),
+ gutenberg.GutenbergCatalogEntry(
+ gutenberg_id=43,
+ title="Dr. Jekyll and Mr. Hyde : $b Large Print",
+ authors="Stevenson, Robert Louis",
+ subjects="Fiction; Horror",
+ bookshelves="Gothic Fiction",
+ language="en",
+ ),
+ gutenberg.GutenbergCatalogEntry(
+ gutenberg_id=4300,
+ title="Dr. Jekyll and Mr. Hyde",
+ authors="Stevenson, Robert Louis",
+ subjects="Fiction; Horror",
+ bookshelves="",
+ language="en",
+ ),
+ ]
+ ranked = gutenberg._search_gutenberg_catalog(entries, {"topic": "fiction"})
+ assert [entry.gutenberg_id for entry in ranked] == [42, 43]
+
+
+def test_standard_ebooks_cleans_heading_punctuation_and_omits_duplicate_roman():
+ from services import standard_ebooks
+
+ xml_doc = """
+
+
+
+
+ Part I
+
+ I
+ Raskolnikov\u2060 stepped into the summer street.
+
+
+
+ I Harker's Journal.
(Kept in shorthand.)
+ Arrived at Bistritz before nightfall.
+
+
+
+ """.encode("utf-8")
+ chapters = standard_ebooks.parse_single_page_chapters(xml_doc, "fyodor-dostoevsky/crime-and-punishment")
+ assert len(chapters) == 2
+ assert chapters[0].title == "Part I — I"
+ assert chapters[0].content == "Raskolnikov stepped into the summer street."
+ assert chapters[1].title == "I: Harker's Journal: (Kept in shorthand.)"
diff --git a/docs/DATA_SOURCES_AND_API_STRATEGY.md b/docs/DATA_SOURCES_AND_API_STRATEGY.md
index 9e13905..053c9e9 100644
--- a/docs/DATA_SOURCES_AND_API_STRATEGY.md
+++ b/docs/DATA_SOURCES_AND_API_STRATEGY.md
@@ -57,7 +57,8 @@ This architecture mirrors consumer reading platforms like **Medium, Substack, an
```
### Key Characteristics
-1. **Live Public-Domain Catalog:** The app-facing catalog is fetched from Project Gutenberg through Gutendex/RDF metadata. Fable does not bundle or seed placeholder provider stories. Cover URLs come from Gutenberg metadata, and the reader fetches book text only when a user opens a title.
+1. **Live Public-Domain Catalog:** Fable keeps the catalog snapshot, popular-book, and recently added collections distinct. Popular titles use Gutendex's popularity ordering; new additions come from Project Gutenberg's daily RSS feed and are resolved against official RDF metadata, with entries lacking plain text filtered out. The app does not bundle placeholder provider stories. Cover URLs come from provider metadata, and chapter text is fetched when a reader opens a title.
+ - Gutenberg catalog cards use `totalChapters: 0` to mean “not loaded yet.” The reader loads and parses the full text on demand; chapter headings can use numeric, Roman, or spelled-out numbers.
2. **User-Generated Content (UGC):** When a user crafts a story in `WriteView` and taps **Publish**, the app sends an HTTP `POST /api/v1/stories` request. The backend validates and persists the story, making it instantly discoverable for other users.
3. **Data Integrity & Exact Formatting:** Because we define the database schema, all fields (chapter numbers, reading time, excerpt, full body text) match the iOS view models with 100% accuracy.
diff --git a/docs/MULTI_CHAPTER_CHANGES_AND_NEXT_STEPS.md b/docs/MULTI_CHAPTER_CHANGES_AND_NEXT_STEPS.md
new file mode 100644
index 0000000..0dab6e5
--- /dev/null
+++ b/docs/MULTI_CHAPTER_CHANGES_AND_NEXT_STEPS.md
@@ -0,0 +1,65 @@
+# Multi-Chapter Catalog & Cache Remediation — Summary of Changes and Next Steps
+
+**Branch:** `feat/plans-01-04-remediation` (`origin/feat/plans-01-04-remediation`)
+**Remote Repository:** `https://github.com/ur1el0/Fable-IOS.git`
+**Related Plan:** [`docs/plans/07_MULTI_CHAPTER_CATALOG_AND_CACHE_REMEDIATION.md`](./plans/07_MULTI_CHAPTER_CATALOG_AND_CACHE_REMEDIATION.md)
+
+---
+
+## 1. Problem Addressed
+
+1. **Single-chapter Project Gutenberg books:** Default Gutenberg browsing previously surfaced newest-first (`-gutenberg_id`) short stories/pamphlets, Python 3.9 cross-event-loop async primitives could fail on concurrent fetches, and several multi-chapter formatting styles (centered/indented headings, italic spelled-out numerals, `STAVE` headers, nested `PART` + Roman subchapters, and `Contents`-listed unnumbered headings) collapsed into a single `"Chapter I: The Complete Tale"` entry.
+2. **Single-provider bottleneck:** Added **Standard Ebooks** (`https://standardebooks.org`) as a second open-source catalog provider serving structured semantic XHTML chapters.
+3. **Stale client SwiftData cache:** Previously cached single-chapter fallback books and unengaged pulp catalog cards stayed persisted on iOS instead of refreshing cleanly once the backend parsers improved.
+
+---
+
+## 2. Changes Implemented on `feat/plans-01-04-remediation`
+
+| Commit | Conventional Commit Title | Files Changed | Summary |
+|---|---|---|---|
+| `14a7c8c` | `docs(plans): add multi-chapter catalog and cache remediation plan` | `docs/plans/07_MULTI_CHAPTER_CATALOG_AND_CACHE_REMEDIATION.md`, `docs/plans/README.md` | Documented `CACHE-01`, `CACHE-02`, `PG-PARSE-01`, `PG-CAT-01`, and `SE-POLISH-01` root causes and remediation plan. |
+| `f3952ca` | `fix(gutenberg): prioritize classic books, deduplicate editions, and expand chapter parser` | `backend/services/text_parser.py`, `backend/services/gutenberg.py` | Expanded chapter header and `Contents`-guided unnumbered chapter splitting (`GID=42` -> 10 chapters), fixed `PART` TOC leaks and nested Roman subchapters (`GID=24` -> 30 chapters), ranked classics first in `_search_gutenberg_catalog`, cleaned MARC `$b` title artifacts via `_clean_gutenberg_title`, deduplicated editions, and switched module-level locks/semaphores to loop-scoped `_loop_primitive`. |
+| `75f3008` | `feat(standard-ebooks): add open-source XHTML catalog and chapter endpoints` | `backend/services/standard_ebooks.py`, `backend/api/v1/endpoints/standard_ebooks.py`, `backend/api/v1/api.py` | Added Standard Ebooks catalog & semantic XHTML chapter parsing behind `GET /api/v1/public/standard-ebooks` and `GET /api/v1/public/standard-ebooks/chapters`. |
+| `1c3a91b` | `test(providers): cover Gutenberg parser edge cases and Standard Ebooks API` | `backend/test_main.py`, `backend/test_provider_http.py`, `backend/test_provider_services.py` | Added unit and HTTP tests covering Gutenberg parser variants, MARC cleanup, edition deduplication, and Standard Ebooks endpoints/headings. |
+| `3554c8a` | `feat(library): integrate Standard Ebooks and self-heal external chapter caches` | `ProviderCatalogStatus.swift`, `PersistenceService.swift`, `StoryAPIService.swift`, `StoryStore.swift`, `ReaderView.swift` | Integrated Standard Ebooks into iOS catalog/reader loading, added versioned external chapter cache invalidation (`currentExternalChapterParserVersion = 2`), and pruned unengaged stale provider cards while keeping offline fallback and user-engaged books intact. |
+| `5d0952a` | `test(library): cover Standard Ebooks decoding and cache invalidation policies` | `frontend/FableAppTests/StorySummaryDecodingTests.swift`, `frontend/FableAppTests/PlanFeaturesRegressionTests.swift` | Added XCTest coverage for Standard Ebooks DTO decoding, cache invalidation rules, and stale catalog pruning. |
+
+---
+
+## 3. Verification Recorded Before Push
+
+- **Backend unit/integration tests (`cd backend && ../.venv/bin/pytest`):** `124 passed, 6 skipped in 11.17s`
+- **Live local FastAPI smoke checks (`http://127.0.0.1:8001`):**
+ - `/api/v1/health` -> `{"status":"healthy","database":"connected",...}`
+ - `gutenberg?topic=fiction` -> 12 books; `gutenberg/42/chapters` -> 10 chapters; `gutenberg/24/chapters` -> 30 chapters
+ - `standard-ebooks?topic=fiction` -> 12 books; `standard-ebooks/chapters?book_id=fyodor-dostoevsky/crime-and-punishment/constance-garnett` -> 40 chapters
+- **iOS unit tests (`xcodebuild test` on `iPhone 17 Pro` Simulator `299D40A3-700A-47EF-890D-B5624E935D03`):** `Executed 37 tests, with 0 failures` (`** TEST SUCCEEDED **`)
+- **Release config & build validation (`scripts/validate_ios_release_config.sh` + Release Simulator `xcodebuild build`):**
+ - Positive HTTPS URL check (`FABLE_API_BASE_URL=https://api.example.com/api/v1`) passed (`exit 0`).
+ - Negative guard checks (`http://127.0.0.1:8000/api/v1`, `https://127.1/api/v1`, and empty `FABLE_API_BASE_URL`) rejected as required by `.github/workflows/ci.yml`.
+ - Release Simulator build succeeded (`** BUILD SUCCEEDED **`).
+- **Live Simulator launch (`mseuf.edu.ph.FableApp`, PID `30319`):** Confirmed `Live Cloud` connected cleanly to the local backend and rendered Featured `Pride and Prejudice`, `Continue Reading`, and a `STANDARD EBOOKS` card on the Library screen.
+
+---
+
+## 4. What to Do Next (Manual Dashboard Steps)
+
+These remaining actions require GitHub or Render web authentication / owner access (`gh`, `render`, `brew`, and API tokens are not configured in this local environment):
+
+1. **Open the GitHub Pull Request & trigger CI:**
+ - Open `https://github.com/ur1el0/Fable-IOS/pull/new/feat/plans-01-04-remediation` (targeting `main`).
+ - Opening the PR triggers all 4 jobs defined in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml):
+ - `backend-verification` (Python `3.9` and `3.11`)
+ - `postgres-verification` (`postgres:16`)
+ - `docker-build-verification`
+ - `ios-verification` (`iPhone 16` / `iOS 18.5`)
+2. **Merge the PR into `main`:**
+ - Once all CI checks pass cleanly, merge the PR into `main` (per [`AGENTS.md`](../AGENTS.md), do not push directly to `main` bypassing PR CI).
+3. **Resume / Redeploy the Render Backend & Verify Neon DB:**
+ - As checked at handoff time, `https://fable-api.onrender.com/api/v1/health` returns **HTTP `503`** (`Service Suspended` — *"This service has been suspended by its owner."*).
+ - Open the Render Dashboard and resume `fable-api` or re-apply [`render.yaml`](../render.yaml) following [`docs/RENDER_NEON_DEPLOYMENT.md`](./RENDER_NEON_DEPLOYMENT.md) with your Neon pooled `DATABASE_URL` and `FABLE_INGESTION_API_KEY`.
+ - After deployment passes health checks, verify:
+ - `https://.onrender.com/api/v1/health` reports `healthy` and `database: connected`
+ - `https://.onrender.com/api/v1/public/standard-ebooks?topic=fiction` returns non-empty Standard Ebooks titles
+ - Any iOS Release archive uses `FABLE_API_BASE_URL=https://.onrender.com/api/v1`
diff --git a/docs/plans/07_MULTI_CHAPTER_CATALOG_AND_CACHE_REMEDIATION.md b/docs/plans/07_MULTI_CHAPTER_CATALOG_AND_CACHE_REMEDIATION.md
new file mode 100644
index 0000000..e28f68a
--- /dev/null
+++ b/docs/plans/07_MULTI_CHAPTER_CATALOG_AND_CACHE_REMEDIATION.md
@@ -0,0 +1,145 @@
+# Feature Plan 07: Multi-Chapter Catalog, Parser Edge Cases & Client Cache Remediation
+
+**Document Version:** 1.0.0
+**Architectural Scope:** iOS SwiftData Chapter/Catalog Self-Healing, Gutenberg Unnumbered & Multi-Part Parsing, Catalog Deduplication, Standard Ebooks Heading & Timeout Polish
+**Backend Stack:** Python 3.9+ / FastAPI / Pydantic v2 / `xml.etree.ElementTree`
+**Client Stack:** Swift 5.9+ / SwiftUI / SwiftData
+**Related Context:** [`docs/DATA_SOURCES_AND_API_STRATEGY.md`](../DATA_SOURCES_AND_API_STRATEGY.md), [`docs/plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md`](./06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md)
+
+---
+
+## 1. Executive Summary & Problem Context
+
+An initial remediation resolved the primary causes behind every Project Gutenberg book appearing as a single chapter (`"Chapter I: The Complete Tale"`):
+- Replaced newest-first (`-gutenberg_id`) pulp short-story browsing and Python 3.9 cross-event-loop `asyncio.Semaphore` failures in [`backend/services/gutenberg.py`](../../backend/services/gutenberg.py).
+- Expanded [`backend/services/text_parser.py`](../../backend/services/text_parser.py) to match indented/centered headings, italic `_Chapter One_` spelled-out numerals, `STAVE` headers, and two-stage Roman headings without dropping chapters that mention `"Chapter "` inside prose.
+- Added **Standard Ebooks** (`https://standardebooks.org`) as a structured semantic XHTML open-source catalog provider via [`backend/services/standard_ebooks.py`](../../backend/services/standard_ebooks.py), [`backend/api/v1/endpoints/standard_ebooks.py`](../../backend/api/v1/endpoints/standard_ebooks.py), [`StoryAPIService.swift`](../../frontend/FableApp/Features/Library/Services/StoryAPIService.swift), and [`StoryStore.swift`](../../frontend/FableApp/Features/Library/ViewModels/StoryStore.swift).
+
+However, **five concrete issues remain** across the iOS local cache, edge-case Gutenberg formatting, catalog deduplication, and Standard Ebooks formatting polish that still cause stale 1-chapter experiences or rough metadata in the live app. This document specifies the exact root causes and phased fixes to resolve them cleanly.
+
+---
+
+## 2. Issue & Root-Cause Matrix
+
+| ID | Area | Severity | Affected Files & Lines | Finding Summary |
+|---|---|---|---|---|
+| **CACHE-01** | Permanent Stale Single-Chapter SwiftData Cache | **P0 (High)** | `StoryStore.swift` (`L499–511`, `L595–612`, `L910–918`) `PersistenceService.swift` (`L209–211`, `L304–330`) | `StoryStore.fetchChapters(for:)` and `syncWithPersistence()` treat any `StoryEntity.cachedChaptersData` containing readable text as permanently fresh (`hasUsableCachedChapters`). Any external book opened before the parser fix (e.g., `#79934` or `#79925`) remains stuck on its cached 1-chapter `"Chapter I: The Complete Tale"` entry on device indefinitely. |
+| **CACHE-02** | Stale External Pulp Catalog Entries Remaining Pinned in Library | **P1 (High)** | `StoryStore.swift` (`L560–620`, `L815–827`, `L970–1035`) | `staleUnavailableOriginalStoryIDs` only prunes `.fableOriginal` records. Previously persisted external catalog items (`79934`, `79931`, `79930`, `79925`) stay persisted in SwiftData ahead of newly fetched Standard Ebooks and classic Gutenberg titles, and `mergePublicProseBooks` retains stale `max(chapters?.count ?? 0, book.totalChapters)` counts. |
+| **PG-PARSE-01** | Unnumbered Named Chapters & Multi-Part TOCs in Top Gutenberg Books | **P1 (Medium)** | `backend/services/text_parser.py` (`L64–166`) | Live checks of the top 12 Gutenberg `topic=fiction` titles still fail on two patterns: 1. `GID=42` & `GID=43` (*The Strange Case of Dr. Jekyll and Mr. Hyde*) collapse to `1` chapter (~25,684 words) because chapters use unnumbered named headings (`STORY OF THE DOOR`, `SEARCH FOR MR. HYDE`, …) listed under `Contents`. 2. `GID=24` (*O Pioneers!*) outputs `['PART V. Alexandra', 'PART I.', 'PART II.', 'PART III.', 'PART IV.', 'PART V.']` because `'PART V. Alexandra'` leaks from the `Contents` outline (`123w`) and nested Roman chapters (`I..XII`) inside each Part are not split. |
+| **PG-CAT-01** | Duplicate Catalog Editions & Raw MARC `$b` Title Artifacts | **P1 (Medium)** | `backend/services/gutenberg.py` (`L256–295`, `L337`) | Default Gutenberg `topic=fiction` returns both `GID=42` and `GID=43` for *Dr. Jekyll and Mr. Hyde*, and returns raw MARC subfield syntax in `GID=16` (`"Peter Pan : $b [Peter and Wendy]"`). |
+| **SE-POLISH-01** | Standard Ebooks Heading Artifacts & Cold-Start Timeout Margin | **P2 (Low)** | `backend/services/standard_ebooks.py` (`L226–267`, `L269–325`) `StoryAPIService.swift` (`L320–329`) | Standard Ebooks `` concatenation joins punctuation artifacts (e.g. `'I: Jonathan Harker’s Journal.: (Kept in shorthand.)'`), leaves Unicode word-joiners (`\u2060`), and duplicates leading Roman numerals inside nested part prose (e.g. *Crime and Punishment* `Part I — I` body starting with `'I\n\nOn an exceptionally...'`). Cold uncached requests also risk tighter `URLSessionConfiguration` timeout margins if detail fetches stall. |
+
+---
+
+## 3. Target Self-Healing Architecture
+
+```mermaid
+flowchart TD
+ Launch["App Launch / syncWithPersistence()"] --> Hydrate["Hydrate Persisted Stories"]
+ Hydrate --> Refresh["refreshProviderCatalogs() Standard Ebooks + Gutenberg (concurrent)"]
+ Refresh --> Prune["Prune Unengaged Stale Provider Items Keep Bookmarked / Progress > 0 / Annotated"]
+ Prune --> Merge["Merge Live Catalog Books Reset Fallback Chapter Caches When Parser Bumped"]
+
+ OpenReader["User Opens Book -> StoryStore.fetchChapters(for:)"] --> CacheCheck{"Cached Chapters Valid? version == currentParserVersion OR not stale single-chapter fallback"}
+ CacheCheck -- "Valid & Current" --> ReturnCached["Return Local SwiftData Chapters"]
+ CacheCheck -- "Stale / Unverified Fallback" --> NetFetch["Fetch Live Chapters from FastAPI (/public/gutenberg/{id}/chapters or /public/standard-ebooks/chapters)"]
+ NetFetch --> ParsedCheck{"Backend Returns > 1 Chapter or Story Already Checked This Version?"}
+ ParsedCheck --> SaveVersion["Persist Chapters + Mark Parser Version Checked"]
+ SaveVersion --> ReaderUI["Render Full Chapter Table of Contents"]
+```
+
+---
+
+## 4. Phased Remediation Specifications
+
+### Phase 1: iOS Client Cache Self-Healing & Catalog Hygiene (`CACHE-01`, `CACHE-02`)
+
+#### 4.1.1 Introduce Non-Destructive Chapter Parser Versioning (`StoryStore.swift`, `PersistenceService.swift`)
+- **Problem:** Adding a new required field to SwiftData `@Model StoryEntity` without defaults or migration risks unnecessary schema churn; meanwhile `StoryEntity.cachedChaptersData` has no metadata about *which parser version* generated a cached 1-chapter payload.
+- **Fix:**
+ 1. Define a static parser version constant on `StoryStore`:
+ ```swift
+ static let currentExternalChapterParserVersion = 2
+ ```
+ 2. Persist a lightweight `[String: Int]` map (`storyId.uuidString -> verifiedParserVersion`) in `UserDefaults` scoped cleanly via `PersistenceService` (avoiding breaking `StoryEntity` lightweight migration while tracking per-story verification).
+ 3. Add a pure policy helper on `StoryStore` (easily unit-testable in `XCTest`):
+ ```swift
+ static func shouldInvalidateCachedChapters(
+ _ chapters: [Chapter],
+ sourceProvider: SourceProvider,
+ verifiedParserVersion: Int
+ ) -> Bool
+ ```
+ Return `true` when ALL of the following hold:
+ - `sourceProvider == .gutenberg || sourceProvider == .standardEbooks`
+ - `verifiedParserVersion < currentExternalChapterParserVersion`
+ - `chapters.count <= 1` (especially if `chapters.first?.title == "Chapter I: The Complete Tale"` or `chapters.first?.wordCount ?? 0 >= 1_500`), **so multi-chapter cached books stay instant offline while any stale 1-chapter fallback is automatically refreshed once against the fixed backend**.
+ 4. In `StoryStore.fetchChapters(for:)`:
+ - If cached chapters exist and `shouldInvalidateCachedChapters(...) == false`, return immediately.
+ - Otherwise fetch live chapters from `apiService.fetchChapters(...)`; if network fetch succeeds, save the updated chapters, update `stories[idx].chapters` / `totalChapters`, and record `verifiedParserVersion = currentExternalChapterParserVersion`.
+ - If offline / backend unavailable while stale cached chapters exist, fall back cleanly to the cached chapters so offline reading never breaks.
+ 5. Clear `chapters` during `syncWithPersistence()` hydration (`L595–598`) if `shouldInvalidateCachedChapters(...)` is true so opening the reader triggers the live refresh automatically.
+
+#### 4.1.2 Prune Unengaged Stale External Catalog Cards (`StoryStore.swift`)
+- **Problem:** Old Gutenberg items like `79934`–`79917` stored during earlier sessions remain in `SwiftData` and `StoryStore.stories` indefinitely even after the provider stops returning them.
+- **Fix:**
+ 1. Add an engagement check on `Story` / `StoryEntity`: a book is *user-engaged* if `isBookmarked || isCompleted || progressPercent > 0 || lastReadChapterId != nil || hasSavedAnnotations(storyId)` (also `ownerUserId != nil`).
+ 2. Inside `fetchStandardEbooksPublicStories` and `fetchGutenbergPublicStories` **only when `topic != nil && (search ?? "").isEmpty`** (full catalog refresh, *not* targeted search or author search):
+ - Let `liveProviderIDs = Set(fetched.map(\.id))`.
+ - Identify previously cached stories for that same `SourceProvider` that are **not** in `liveProviderIDs` and are **not** user-engaged (`!isUserEngaged(story)`).
+ - Remove them from `stories` and delete them from SwiftData via `PersistenceService.shared.deleteStory(storyId:onlyIfUnannotated: true)`.
+ 3. Preserve user-engaged external books untouched, keeping bookmarks, notes, highlights, and reading progress intact.
+
+---
+
+### Phase 2: Gutenberg Parser Edge Cases & Catalog Hygiene (`PG-PARSE-01`, `PG-CAT-01`)
+
+#### 4.2.1 Support `Contents`-Driven Unnumbered Chapters (`GID=42`, `GID=43`) in `backend/services/text_parser.py`
+- **Problem:** Books like *The Strange Case of Dr. Jekyll and Mr. Hyde* format chapters as unnumbered title lines (`STORY OF THE DOOR`, `SEARCH FOR MR. HYDE`, …, `HENRY JEKYLL’S FULL STATEMENT OF THE CASE`) listed in a `Contents` section.
+- **Fix:**
+ 1. Add Stage 4 fallback inside `extract_chapters_from_text` (executed only when Stages 1–3 produce `< 2` chapters and `len(clean_text.split()) >= 3_000`):
+ - Locate a `Contents` / `CONTENTS` / `Table of Contents` block near the top of `clean_text` (first 20% of document or 12,000 chars).
+ - Extract non-empty candidate lines (`3..60` lines, `3..80` chars each) up to the next large section break, normalizing curly quotes (`’` -> `'`) and collapsing internal whitespace.
+ - Verify those candidate titles sequentially against standalone heading lines (`^\s*{normalized_title}\s*$`) in the body *after* the `Contents` block.
+ - Require at least `3` matched titles covering `>= 60%` of the TOC entries, each followed by `>= 50` prose characters before the next matched title.
+ - Split the body at those verified heading offsets into sequential `Chapter` dicts with title-cased or original titles.
+
+#### 4.2.2 Fix `PART I..V` TOC Leak & Nested Roman Chapter Splitting (`GID=24` *O Pioneers!*)
+- **Problem:** In `GID=24`, `'PART V. Alexandra'` in the `Contents` listing (`Contents\n\n PART I. ...\n ... \n PART V. Alexandra\n\n PART I. The Wild Land\n\nI\n\n...`) matched `PART\s+[IVXLCDM]+` ahead of a blank-line threshold `< 350` words because `I..V` Roman numerals in the TOC weren't counted as TOC lines, and Roman chapters (`I`, `II`, `III`) nested inside each `PART` weren't split.
+- **Fix:**
+ 1. Broaden `_is_toc_listing(body)` to also recognize bare standalone Roman lines (`^[ \t]*[IVXLCDM]{1,6}[ \t]*$` occurring `>= 3` times in `< 450` words) and check whether the preceding block contains `CONTENTS` / `Contents`.
+ 2. When Stage 1 matches top-level `PART` / `BOOK` divisions (`<= 8` sections) whose bodies each contain multiple standalone Roman numeral markers (`\n{2,}[ \t]*[IVXLCDM]{1,7}\.?[ \t]*\n{2,}` with `>= 2` subsections), subdivide each Part into `" — Chapter "` using the existing Stage 3 Roman splitter so books like *O Pioneers!* yield all individual chapters instead of only 5–6 massive Part blobs.
+
+#### 4.2.3 Clean MARC `$b` Title Artifacts & Deduplicate Editions (`backend/services/gutenberg.py`)
+- **Fixes:**
+ 1. Add `_clean_gutenberg_title(raw_title: str) -> str` in `gutenberg.py` (used in `_gutenberg_book_from_rdf`, `_story_from_gutenberg_metadata`, and catalog search normalization) to normalize MARC subfields such as `"Peter Pan : $b [Peter and Wendy]"` → `"Peter Pan: [Peter and Wendy]"` and strip redundant `: $b` / `$b` tokens.
+ 2. Deduplicate matching catalog entries in `_search_gutenberg_catalog` by normalized `(clean_title.casefold(), primary_author.casefold())` (keeping the lowest-ID canonical English edition, e.g., keeping `GID=42` while skipping duplicate `GID=43` unless `search` explicitly targets an ID).
+
+---
+
+### Phase 3: Standard Ebooks Formatting & Reliability Polish (`SE-POLISH-01`)
+
+#### 4.3.1 Clean Chapter Heading Punctuation, `\u2060`, and Nested Roman Headings (`backend/services/standard_ebooks.py`)
+- **Fixes:**
+ 1. In `_clean_heading_text` / `_extract_heading_title`:
+ - Replace Unicode word-joiner `"\u2060"` with `""` and strip trailing punctuation (`.:;`) between title segments before joining (turning `'I: Jonathan Harker’s Journal.: (Kept in shorthand.)'` into `'I: Jonathan Harker’s Journal (Kept in shorthand.)'`).
+ 2. In `_extract_prose_blocks`:
+ - Notice in nested multi-part novels like *Crime and Punishment*, the child chapter's own Roman ``/`` (`"I"`) sits outside `` in an ``/`` or `hgroup` sibling that may still be walked if nested deeper than direct children; skip the exact primary chapter heading element already extracted into `title` so `"Part I — I"` doesn't repeat `"I"` as its first paragraph.
+ 3. Normalize non-breaking spaces `\xa0` and `\u2060` cleanly (`text.replace("\u2060", "")`).
+
+#### 4.3.2 Bound Cold-Start Detail Fetches & Align iOS Timeout Policy
+- **Backend (`backend/services/standard_ebooks.py`):**
+ - Keep detail metadata warm in `_STANDARD_EBOOKS_DETAIL_CACHE` (already 1h TTL) and cap per-detail fetch timeout at `8.0s` so a single slow detail page never stalls all 12 listing cards (`asyncio.Semaphore(6)` gracefully falls back to basic synopsis + `"Classics"` if any detail page times out).
+- **iOS (`frontend/FableApp/Features/Library/Services/StoryAPIService.swift`):**
+ - Verify all public catalog and chapter requests (`fetchPublicCatalogStories`, `fetchChapters`) use `Self.providerRequest(for:)` (which sets `request.timeoutInterval = 20.0`, overriding the default `5.0s` `URLSessionConfiguration` timeout for heavy upstream cold fetches) and add explicit fallback/logging when `fetchStandardEbooksStories` fails.
+
+---
+
+## 5. Verification Plan
+
+| Layer | Verification Action | Expected Result |
+|---|---|---|
+| **Backend Unit Tests (`backend/test_main.py`, `test_provider_services.py`)** | Add tests covering `Contents`-based unnumbered chapters (`Jekyll & Hyde` pattern), nested `PART` + Roman subsections (`O Pioneers!` pattern), MARC `$b` title cleanup & duplicate suppression, and Standard Ebooks clean headings / non-duplicate body headings. | All `pytest` tests pass with zero regressions (`0 failed`). |
+| **Live Upstream Validation (`.venv/bin/python3`)** | Parse live Gutenberg `GID=42` (*Dr. Jekyll*), `GID=24` (*O Pioneers!*), and `GID=16` (*Peter Pan*) + Standard Ebooks *Dracula* & *Crime and Punishment*. | `GID=42` splits into `10` chapters; `GID=24` drops TOC `'PART V. Alexandra'` leak and splits sub-chapters cleanly; catalog shows clean titles without `$b` or duplicates; Standard Ebooks headings have clean punctuation. |
+| **iOS Unit Tests (`xcodebuild test`)** | Add XCTest coverage in `StorySummaryDecodingTests.swift` verifying `StoryStore.shouldInvalidateCachedChapters` refreshes 1-chapter unverified Gutenberg caches, preserves already-verified 1-chapter short stories and multi-chapter caches, and prunes unengaged stale catalog cards while preserving bookmarked/in-progress items. | `FableAppTests` builds and passes (`** TEST SUCCEEDED **`). |
+| **Simulator / Live E2E (`http://127.0.0.1:8001`)** | Launch updated iOS app on booted simulator containing prior single-chapter cache, open Library and Reader on both Gutenberg and Standard Ebooks titles. | Stale pulp cards (`79934`–`79925`) are replaced cleanly by multi-chapter classics; opening any book shows its full Table of Contents (`Chapter 1..N`). |
diff --git a/docs/plans/README.md b/docs/plans/README.md
index 95b96a9..779941e 100644
--- a/docs/plans/README.md
+++ b/docs/plans/README.md
@@ -30,6 +30,7 @@ All plans are formulated under **strict critical system design tenets**:
| **[`04_ORAL_FOLKLORE_AUDIO_SYNTHESIZER.md`](./04_ORAL_FOLKLORE_AUDIO_SYNTHESIZER.md)** | Audio Narration & Accessibility | Native text-to-speech audio reader (`AVSpeechSynthesizer`) | Lock-screen `MPNowPlaying` metadata; sentence-level highlighting synchronization; zero audio clipping |
| **[`05_FASTAPI_CLOUD_SYNC_PIPELINE.md`](./05_FASTAPI_CLOUD_SYNC_PIPELINE.md)** | Distributed Cloud Synchronization | Minimalist FastAPI backend & SQLite cloud sync | Contract-first OpenAPI pipeline; Last-Write-Wins (LWW) conflict resolution; zero enterprise bloat |
| **[`06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md`](./06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md)** | Security & Architecture Hardening | Auth rate-limit hardening, N+1 query elimination, CRUD & account deletion lifecycle, SwiftData resilience | Zero proxy IP collapse; bounded rate-limit tables; App Store 5.1.1(v) compliance; non-fatal SwiftData recovery |
+| **[`07_MULTI_CHAPTER_CATALOG_AND_CACHE_REMEDIATION.md`](./07_MULTI_CHAPTER_CATALOG_AND_CACHE_REMEDIATION.md)** | Multi-Source Catalog & Cache Hygiene | Standard Ebooks XHTML provider, Gutenberg multi-format chapter parsing, MARC cleanup, self-healing SwiftData chapter/catalog cache | Zero stale 1-chapter fallback locks; deduplicated multi-chapter classic browsing; offline fallback preserved |
---
@@ -86,4 +87,5 @@ To ensure manageable, incremental progress aligned with our technical instructor
8. **Phase 8: Enterprise Security, Automated Tests & ADR Baseline** — [COMPLETE] Implemented BCrypt/PBKDF2 auth, token keychain storage, 22-case pytest suite, and formal Architecture Decision Records.
9. **Phase 9: App Health Diagnostics & Media Layout Invariants** — [COMPLETE] Enforced strict `.clipped()` anti-overlap geometry, built `AppHealthTests`, and wired interactive on-device `SystemDiagnosticsSheet`.
10. **Phase 10: Security Vulnerabilities & Architectural Remediation (Plan 06)** — [COMPLETE] Remediated auth rate-limiting gaps, reverse-proxy IP collapse, author/handle impersonation, per-GET SQLite write locks, 1+N story read-count queries, catalog author caching, story CRUD & account deletion lifecycle, and SwiftData launch/shelf resilience.
+11. **Phase 11: Multi-Chapter Catalog, Parser Edge Cases & Client Cache Remediation (Plan 07)** — [COMPLETE] Integrated Standard Ebooks semantic XHTML catalog/reader support, expanded Project Gutenberg chapter splitting (centered headers, spelled-out chapters, staves, `Contents`-driven unnumbered titles, nested `PART` + Roman subchapters), cleaned MARC titles & duplicate editions, and added versioned iOS chapter cache invalidation + unengaged stale card pruning.
diff --git a/frontend/FableApp-Info.plist b/frontend/FableApp-Info.plist
new file mode 100644
index 0000000..f753731
--- /dev/null
+++ b/frontend/FableApp-Info.plist
@@ -0,0 +1,10 @@
+
+
+
+
+ UIBackgroundModes
+
+ audio
+
+
+
diff --git a/frontend/FableApp.xcodeproj/project.pbxproj b/frontend/FableApp.xcodeproj/project.pbxproj
index 5a9c741..47e19ba 100644
--- a/frontend/FableApp.xcodeproj/project.pbxproj
+++ b/frontend/FableApp.xcodeproj/project.pbxproj
@@ -349,6 +349,7 @@
ENABLE_PREVIEWS = YES;
FABLE_API_BASE_URL = "http://127.0.0.1:8001/api/v1";
GENERATE_INFOPLIST_FILE = YES;
+ INFOPLIST_FILE = "FableApp-Info.plist";
INFOPLIST_KEY_FABLE_API_BASE_URL = "$(FABLE_API_BASE_URL)";
INFOPLIST_KEY_NSAppTransportSecurity_NSAllowsArbitraryLoads = NO;
INFOPLIST_KEY_NSAppTransportSecurity_NSAllowsLocalNetworking = YES;
@@ -384,6 +385,7 @@
ENABLE_PREVIEWS = YES;
FABLE_API_BASE_URL = "";
GENERATE_INFOPLIST_FILE = YES;
+ INFOPLIST_FILE = "FableApp-Info.plist";
INFOPLIST_KEY_FABLE_API_BASE_URL = "$(FABLE_API_BASE_URL)";
INFOPLIST_KEY_NSAppTransportSecurity_NSAllowsArbitraryLoads = NO;
INFOPLIST_KEY_NSAppTransportSecurity_NSAllowsLocalNetworking = YES;
diff --git a/frontend/FableApp/Features/Library/Models/ProviderCatalogStatus.swift b/frontend/FableApp/Features/Library/Models/ProviderCatalogStatus.swift
index fdf8697..fbb183d 100644
--- a/frontend/FableApp/Features/Library/Models/ProviderCatalogStatus.swift
+++ b/frontend/FableApp/Features/Library/Models/ProviderCatalogStatus.swift
@@ -2,6 +2,7 @@ import Foundation
enum CatalogProvider: String, CaseIterable, Hashable {
case gutenberg = "Project Gutenberg"
+ case standardEbooks = "Standard Ebooks"
case mangaDex = "MangaDex"
}
diff --git a/frontend/FableApp/Features/Library/Models/Story.swift b/frontend/FableApp/Features/Library/Models/Story.swift
index 5be048e..4d47c9d 100644
--- a/frontend/FableApp/Features/Library/Models/Story.swift
+++ b/frontend/FableApp/Features/Library/Models/Story.swift
@@ -483,7 +483,7 @@ public struct Story: Identifiable, Hashable, Codable {
self.isRecentSubmission = isRecentSubmission
self.isCuratorSpotlight = isCuratorSpotlight
self.badgeText = badgeText
- self.totalChapters = max(1, chapters?.count ?? 1)
+ self.totalChapters = max(0, chapters?.count ?? 0)
self.chapters = chapters
self.contentFormat = contentFormat
self.sourceProvider = sourceProvider
@@ -571,6 +571,7 @@ public struct Annotation: Identifiable, Codable, Equatable, Hashable {
public let storyId: UUID
public var storyTitle: String
public var storyAuthor: String
+ public var chapterNumber: Int?
public let utf16StartOffset: Int
public let utf16EndOffset: Int
public let selectedText: String
@@ -584,6 +585,7 @@ public struct Annotation: Identifiable, Codable, Equatable, Hashable {
storyId: UUID,
storyTitle: String = "",
storyAuthor: String = "",
+ chapterNumber: Int? = nil,
utf16StartOffset: Int,
utf16EndOffset: Int,
selectedText: String,
@@ -596,6 +598,7 @@ public struct Annotation: Identifiable, Codable, Equatable, Hashable {
self.storyId = storyId
self.storyTitle = storyTitle
self.storyAuthor = storyAuthor
+ self.chapterNumber = chapterNumber
self.utf16StartOffset = utf16StartOffset
self.utf16EndOffset = utf16EndOffset
self.selectedText = selectedText
diff --git a/frontend/FableApp/Features/Library/Models/StoryEntity.swift b/frontend/FableApp/Features/Library/Models/StoryEntity.swift
index fe49d60..c761134 100644
--- a/frontend/FableApp/Features/Library/Models/StoryEntity.swift
+++ b/frontend/FableApp/Features/Library/Models/StoryEntity.swift
@@ -93,6 +93,7 @@ public final class StoryEntity {
@Model
public final class AnnotationEntity {
@Attribute(.unique) public var id: UUID
+ public var chapterNumber: Int?
public var utf16StartOffset: Int
public var utf16EndOffset: Int
public var highlightedText: String
@@ -106,6 +107,7 @@ public final class AnnotationEntity {
public init(
id: UUID = UUID(),
+ chapterNumber: Int? = nil,
utf16StartOffset: Int,
utf16EndOffset: Int,
highlightedText: String,
@@ -117,6 +119,7 @@ public final class AnnotationEntity {
story: StoryEntity? = nil
) {
self.id = id
+ self.chapterNumber = chapterNumber
self.utf16StartOffset = utf16StartOffset
self.utf16EndOffset = utf16EndOffset
self.highlightedText = highlightedText
diff --git a/frontend/FableApp/Features/Library/Services/PersistenceService.swift b/frontend/FableApp/Features/Library/Services/PersistenceService.swift
index fbf4dd7..4470807 100644
--- a/frontend/FableApp/Features/Library/Services/PersistenceService.swift
+++ b/frontend/FableApp/Features/Library/Services/PersistenceService.swift
@@ -177,80 +177,129 @@ public final class PersistenceService {
return try? JSONEncoder().encode(chapters)
}
- // Insert or update manuscript
- public func saveStory(_ story: Story) {
+ @discardableResult
+ private func upsertStoryEntity(_ story: Story) throws -> StoryEntity {
let targetId = story.id
var descriptor = FetchDescriptor(
predicate: #Predicate { $0.id == targetId }
)
descriptor.fetchLimit = 1
-
- do {
- let matches = try context.fetch(descriptor)
- if let existing = matches.first {
- existing.title = story.title
- existing.author = story.author
- existing.genreRaw = story.genre.rawValue
- existing.contentFormatRaw = story.contentFormat.rawValue
- existing.sourceProviderRaw = story.sourceProvider.rawValue
- existing.synopsis = story.synopsis
- existing.content = story.content
- existing.readTimeMinutes = story.readTimeMinutes
- existing.readingProgress = Double(story.progressPercent) / 100.0
- existing.currentPage = story.currentPage
- existing.totalPages = story.totalPages
- existing.coverImageName = story.coverImageName
- existing.heroImageName = story.heroImageName
- existing.coverImageUrl = story.coverImageUrl
- if let providerId = story.providerId { existing.providerId = providerId }
- if let ownerUserId = story.ownerUserId { existing.ownerUserId = ownerUserId }
- if let providerDownloadCount = story.providerDownloadCount {
- existing.providerDownloadCount = providerDownloadCount
- }
- if let chapters = story.chapters, !chapters.isEmpty {
- existing.cachedChaptersData = encodedChapters(chapters)
- }
- existing.lastReadChapterId = story.lastReadChapterId
- existing.lastReadChapterNumber = story.lastReadChapterNumber
- existing.isBookmarked = story.isBookmarked
- existing.isCompleted = story.isCompleted
- existing.updatedAtUtc = Date()
- } else {
- let newEntity = StoryEntity(
- id: story.id,
- title: story.title,
- author: story.author,
- genreRaw: story.genre.rawValue,
- contentFormatRaw: story.contentFormat.rawValue,
- sourceProviderRaw: story.sourceProvider.rawValue,
- chapter: "",
- synopsis: story.synopsis,
- content: story.content,
- readTimeMinutes: story.readTimeMinutes,
- readingProgress: Double(story.progressPercent) / 100.0,
- currentPage: story.currentPage,
- totalPages: story.totalPages,
- coverImageName: story.coverImageName,
- heroImageName: story.heroImageName,
- coverImageUrl: story.coverImageUrl,
- providerId: story.providerId,
- ownerUserId: story.ownerUserId,
- providerDownloadCount: story.providerDownloadCount,
- cachedChaptersData: encodedChapters(story.chapters),
- lastReadChapterId: story.lastReadChapterId,
- lastReadChapterNumber: story.lastReadChapterNumber,
- isBookmarked: story.isBookmarked,
- isCompleted: story.isCompleted,
- createdAtUtc: story.createdAtUtc,
- updatedAtUtc: Date()
- )
- context.insert(newEntity)
+
+ let matches = try context.fetch(descriptor)
+ if let existing = matches.first {
+ existing.title = story.title
+ existing.author = story.author
+ existing.genreRaw = story.genre.rawValue
+ existing.contentFormatRaw = story.contentFormat.rawValue
+ existing.sourceProviderRaw = story.sourceProvider.rawValue
+ existing.synopsis = story.synopsis
+ existing.content = story.content
+ existing.readTimeMinutes = story.readTimeMinutes
+ existing.readingProgress = min(1.0, max(0.0, Double(story.progressPercent) / 100.0))
+ existing.currentPage = max(1, story.currentPage)
+ existing.totalPages = max(1, story.totalPages)
+ existing.coverImageName = story.coverImageName
+ existing.heroImageName = story.heroImageName
+ existing.coverImageUrl = story.coverImageUrl
+ if let providerId = story.providerId { existing.providerId = providerId }
+ if let ownerUserId = story.ownerUserId { existing.ownerUserId = ownerUserId }
+ if let providerDownloadCount = story.providerDownloadCount {
+ existing.providerDownloadCount = providerDownloadCount
+ }
+ if let chapters = story.chapters, !chapters.isEmpty {
+ existing.cachedChaptersData = encodedChapters(chapters)
}
+ existing.lastReadChapterId = story.lastReadChapterId
+ existing.lastReadChapterNumber = story.lastReadChapterNumber
+ existing.isBookmarked = story.isBookmarked
+ existing.isCompleted = story.isCompleted
+ existing.updatedAtUtc = Date()
+ return existing
+ }
+
+ let newEntity = StoryEntity(
+ id: story.id,
+ title: story.title,
+ author: story.author,
+ genreRaw: story.genre.rawValue,
+ contentFormatRaw: story.contentFormat.rawValue,
+ sourceProviderRaw: story.sourceProvider.rawValue,
+ chapter: "",
+ synopsis: story.synopsis,
+ content: story.content,
+ readTimeMinutes: story.readTimeMinutes,
+ readingProgress: Double(story.progressPercent) / 100.0,
+ currentPage: story.currentPage,
+ totalPages: story.totalPages,
+ coverImageName: story.coverImageName,
+ heroImageName: story.heroImageName,
+ coverImageUrl: story.coverImageUrl,
+ providerId: story.providerId,
+ ownerUserId: story.ownerUserId,
+ providerDownloadCount: story.providerDownloadCount,
+ cachedChaptersData: encodedChapters(story.chapters),
+ lastReadChapterId: story.lastReadChapterId,
+ lastReadChapterNumber: story.lastReadChapterNumber,
+ isBookmarked: story.isBookmarked,
+ isCompleted: story.isCompleted,
+ createdAtUtc: story.createdAtUtc,
+ updatedAtUtc: Date()
+ )
+ context.insert(newEntity)
+ return newEntity
+ }
+
+ // Insert or update manuscript
+ public func saveStory(_ story: Story) {
+ do {
+ _ = try upsertStoryEntity(story)
try context.save()
} catch {
print("Failed to save story: \(error)")
}
}
+
+ public func fetchStory(id: UUID) -> Story? {
+ var descriptor = FetchDescriptor(
+ predicate: #Predicate { $0.id == id }
+ )
+ descriptor.fetchLimit = 1
+ guard let entity = try? context.fetch(descriptor).first,
+ !Self.legacyDemoStoryIds.contains(entity.id) else {
+ return nil
+ }
+
+ let chapters = cachedChapters(storyId: entity.id)
+ let format = ContentFormat(rawValue: entity.contentFormatRaw ?? "PROSE") ?? .prose
+ let provider = SourceProvider(rawValue: entity.sourceProviderRaw ?? "FABLE_ORIGINAL") ?? .fableOriginal
+ return Story(
+ id: entity.id,
+ title: entity.title,
+ author: entity.author,
+ genre: entity.genreRaw,
+ excerpt: entity.synopsis,
+ paragraphs: entity.content.isEmpty ? [] : [entity.content],
+ coverImageName: entity.coverImageName,
+ heroImageName: entity.heroImageName,
+ coverImageUrl: entity.coverImageUrl,
+ readingTimeMinutes: entity.readTimeMinutes,
+ totalPages: max(1, entity.totalPages),
+ currentPage: max(1, entity.currentPage),
+ progressPercent: Int(entity.readingProgress * 100.0),
+ rating: nil,
+ providerDownloadCount: entity.providerDownloadCount,
+ isRecentSubmission: false,
+ isSaved: entity.isBookmarked,
+ isFinished: entity.isCompleted,
+ contentFormat: format,
+ sourceProvider: provider,
+ providerId: entity.providerId,
+ ownerUserId: entity.ownerUserId,
+ chapters: chapters.isEmpty ? nil : chapters,
+ lastReadChapterId: entity.lastReadChapterId,
+ lastReadChapterNumber: entity.lastReadChapterNumber
+ )
+ }
public func cachedChapters(storyId: UUID) -> [Chapter] {
let descriptor = FetchDescriptor(
@@ -355,7 +404,7 @@ public final class PersistenceService {
}
// Delete story
- public func deleteStory(storyId: UUID) {
+ public func deleteStory(storyId: UUID, onlyIfUnannotated: Bool = false) {
var descriptor = FetchDescriptor(
predicate: #Predicate { $0.id == storyId }
)
@@ -363,6 +412,9 @@ public final class PersistenceService {
do {
if let entity = try context.fetch(descriptor).first {
+ if onlyIfUnannotated && !entity.annotations.isEmpty {
+ return
+ }
context.delete(entity)
try context.save()
}
@@ -372,7 +424,51 @@ public final class PersistenceService {
}
// MARK: - Annotation / Marginalia Methods
-
+
+ private func annotationModel(from entity: AnnotationEntity, storyEntity: StoryEntity) -> Annotation {
+ Annotation(
+ id: entity.id,
+ storyId: storyEntity.id,
+ storyTitle: storyEntity.title,
+ storyAuthor: storyEntity.author,
+ chapterNumber: entity.chapterNumber,
+ utf16StartOffset: entity.utf16StartOffset,
+ utf16EndOffset: entity.utf16EndOffset,
+ selectedText: entity.highlightedText,
+ note: entity.note,
+ color: HighlightColor(rawValue: entity.styleRaw) ?? .terracotta,
+ isPinnedToJournal: entity.isPinnedToJournal,
+ createdAt: entity.createdAtUtc
+ )
+ }
+
+ public func clearCachedChapters(storyId: UUID) {
+ var descriptor = FetchDescriptor(
+ predicate: #Predicate { $0.id == storyId }
+ )
+ descriptor.fetchLimit = 1
+ do {
+ guard let entity = try context.fetch(descriptor).first,
+ entity.cachedChaptersData != nil else { return }
+ entity.cachedChaptersData = nil
+ entity.updatedAtUtc = Date()
+ try context.save()
+ } catch {
+ print("Failed to clear cached story chapters: \(error)")
+ }
+ }
+
+ public func hasAnyAnnotations(for storyId: UUID) -> Bool {
+ var descriptor = FetchDescriptor(
+ predicate: #Predicate { $0.id == storyId }
+ )
+ descriptor.fetchLimit = 1
+ guard let storyEntity = try? context.fetch(descriptor).first else {
+ return false
+ }
+ return !storyEntity.annotations.isEmpty
+ }
+
public func fetchAnnotations(for storyId: UUID, ownerUserId: UUID?) -> [Annotation] {
var descriptor = FetchDescriptor(
predicate: #Predicate { $0.id == storyId }
@@ -383,21 +479,7 @@ public final class PersistenceService {
if let storyEntity = try context.fetch(descriptor).first {
return storyEntity.annotations
.filter { $0.ownerUserId == ownerUserId }
- .map { entity in
- Annotation(
- id: entity.id,
- storyId: storyId,
- storyTitle: storyEntity.title,
- storyAuthor: storyEntity.author,
- utf16StartOffset: entity.utf16StartOffset,
- utf16EndOffset: entity.utf16EndOffset,
- selectedText: entity.highlightedText,
- note: entity.note,
- color: HighlightColor(rawValue: entity.styleRaw) ?? .terracotta,
- isPinnedToJournal: entity.isPinnedToJournal,
- createdAt: entity.createdAtUtc
- )
- }
+ .map { annotationModel(from: $0, storyEntity: storyEntity) }
}
} catch {
print("Failed to fetch annotations: \(error)")
@@ -405,7 +487,7 @@ public final class PersistenceService {
return []
}
- public func saveAnnotation(_ annotation: Annotation, ownerUserId: UUID?) {
+ public func saveAnnotation(_ annotation: Annotation, ownerUserId: UUID?, storyFallback: Story? = nil) {
let storyId = annotation.storyId
var descriptor = FetchDescriptor(
predicate: #Predicate { $0.id == storyId }
@@ -413,10 +495,18 @@ public final class PersistenceService {
descriptor.fetchLimit = 1
do {
- guard let storyEntity = try context.fetch(descriptor).first else { return }
+ let storyEntity: StoryEntity
+ if let fetched = try context.fetch(descriptor).first {
+ storyEntity = fetched
+ } else if let storyFallback {
+ storyEntity = try upsertStoryEntity(storyFallback)
+ } else {
+ return
+ }
if let existing = storyEntity.annotations.first(where: { $0.id == annotation.id }) {
guard existing.ownerUserId == ownerUserId else { return }
+ existing.chapterNumber = annotation.chapterNumber
existing.highlightedText = annotation.selectedText
existing.note = annotation.note
existing.styleRaw = annotation.color.rawValue
@@ -424,6 +514,7 @@ public final class PersistenceService {
} else {
let newEntity = AnnotationEntity(
id: annotation.id,
+ chapterNumber: annotation.chapterNumber,
utf16StartOffset: annotation.utf16StartOffset,
utf16EndOffset: annotation.utf16EndOffset,
highlightedText: annotation.selectedText,
@@ -467,20 +558,9 @@ public final class PersistenceService {
do {
let entities = try context.fetch(descriptor).filter { $0.ownerUserId == ownerUserId }
- return entities.map { entity in
- Annotation(
- id: entity.id,
- storyId: entity.story?.id ?? UUID(),
- storyTitle: entity.story?.title ?? "Fable Manuscript",
- storyAuthor: entity.story?.author ?? "Unknown Author",
- utf16StartOffset: entity.utf16StartOffset,
- utf16EndOffset: entity.utf16EndOffset,
- selectedText: entity.highlightedText,
- note: entity.note,
- color: HighlightColor(rawValue: entity.styleRaw) ?? .terracotta,
- isPinnedToJournal: entity.isPinnedToJournal,
- createdAt: entity.createdAtUtc
- )
+ return entities.compactMap { entity in
+ guard let storyEntity = entity.story else { return nil }
+ return annotationModel(from: entity, storyEntity: storyEntity)
}
} catch {
print("Failed to fetch pinned annotations: \(error)")
diff --git a/frontend/FableApp/Features/Library/Services/StoryAPIService.swift b/frontend/FableApp/Features/Library/Services/StoryAPIService.swift
index 775279d..54b23bd 100644
--- a/frontend/FableApp/Features/Library/Services/StoryAPIService.swift
+++ b/frontend/FableApp/Features/Library/Services/StoryAPIService.swift
@@ -271,7 +271,9 @@ public protocol StoryAPIServiceProtocol: Sendable {
func syncShelf(deviceId: UUID, token: String, items: [ShelfSyncItem]) async throws -> [ShelfSyncItem]
func fetchShelf(deviceId: UUID, token: String) async throws -> [ShelfSyncItem]
func fetchGutenbergStories(topic: String?, search: String?) async throws -> [Story]
+ func fetchGutenbergStories(topic: String?, search: String?, sort: String?) async throws -> [Story]
func fetchGutenbergStory(providerId: String) async throws -> Story
+ func fetchStandardEbooksStories(topic: String?, search: String?) async throws -> [Story]
func fetchMangaStories(search: String?) async throws -> [Story]
func fetchChapters(for storyId: UUID, sourceProvider: String, providerId: String?) async throws -> [Chapter]
func fetchGenres() async throws -> [GenreCategory]
@@ -302,6 +304,14 @@ public extension StoryAPIServiceProtocol {
try await fetchGutenbergStories(topic: topic, search: search)
}
+ func fetchGutenbergStories(topic: String?, search: String?, sort: String?) async throws -> [Story] {
+ try await fetchGutenbergStories(topic: topic, search: search)
+ }
+
+ func fetchStandardEbooksStories(topic: String? = nil, search: String? = nil) async throws -> [Story] {
+ try await fetchStandardEbooksStories(topic: topic, search: search)
+ }
+
func fetchMangaStories(search: String? = nil) async throws -> [Story] {
try await fetchMangaStories(search: search)
}
@@ -467,11 +477,15 @@ public final class StoryAPIService: StoryAPIServiceProtocol {
return result.reconciledItems
}
- public func fetchGutenbergStories(topic: String? = nil, search: String? = nil) async throws -> [Story] {
- var components = URLComponents(url: baseURL.appendingPathComponent("public").appendingPathComponent("gutenberg"), resolvingAgainstBaseURL: true)!
+ private func fetchPublicCatalogStories(endpointComponent: String, topic: String? = nil, search: String? = nil, sort: String? = nil) async throws -> [Story] {
+ var components = URLComponents(
+ url: baseURL.appendingPathComponent("public").appendingPathComponent(endpointComponent),
+ resolvingAgainstBaseURL: true
+ )!
var queryItems: [URLQueryItem] = []
if let topic, topic != "All" { queryItems.append(URLQueryItem(name: "topic", value: topic)) }
if let search, !search.isEmpty { queryItems.append(URLQueryItem(name: "search", value: search)) }
+ if let sort, !sort.isEmpty { queryItems.append(URLQueryItem(name: "sort", value: sort)) }
if !queryItems.isEmpty { components.queryItems = queryItems }
guard let targetURL = components.url else { throw URLError(.badURL) }
@@ -485,6 +499,18 @@ public final class StoryAPIService: StoryAPIServiceProtocol {
return try decoder.decode([Story].self, from: data)
}
+ public func fetchGutenbergStories(topic: String? = nil, search: String? = nil) async throws -> [Story] {
+ try await fetchGutenbergStories(topic: topic, search: search, sort: nil)
+ }
+
+ public func fetchGutenbergStories(topic: String? = nil, search: String? = nil, sort: String?) async throws -> [Story] {
+ try await fetchPublicCatalogStories(endpointComponent: "gutenberg", topic: topic, search: search, sort: sort)
+ }
+
+ public func fetchStandardEbooksStories(topic: String? = nil, search: String? = nil) async throws -> [Story] {
+ try await fetchPublicCatalogStories(endpointComponent: "standard-ebooks", topic: topic, search: search)
+ }
+
public func fetchGutenbergStory(providerId: String) async throws -> Story {
guard let gutenbergId = Int(providerId), gutenbergId > 0 else { throw URLError(.badURL) }
let url = baseURL
@@ -519,6 +545,25 @@ public final class StoryAPIService: StoryAPIServiceProtocol {
return try decoder.decode([Chapter].self, from: data)
} else if sourceProvider == "GUTENBERG" {
throw URLError(.badURL)
+ } else if sourceProvider == "STANDARD_EBOOKS", let providerId, !providerId.isEmpty {
+ var components = URLComponents(
+ url: baseURL
+ .appendingPathComponent("public")
+ .appendingPathComponent("standard-ebooks")
+ .appendingPathComponent("chapters"),
+ resolvingAgainstBaseURL: true
+ )!
+ components.queryItems = [URLQueryItem(name: "book_id", value: providerId)]
+ guard let url = components.url else { throw URLError(.badURL) }
+ let (data, response) = try await session.data(for: Self.providerRequest(for: url))
+ guard let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) else {
+ throw URLError(.badServerResponse)
+ }
+ let decoder = JSONDecoder()
+ decoder.dateDecodingStrategy = .iso8601
+ return try decoder.decode([Chapter].self, from: data)
+ } else if sourceProvider == "STANDARD_EBOOKS" {
+ throw URLError(.badURL)
} else if sourceProvider == "MANGADEX", let providerId, !providerId.isEmpty {
return try await fetchMangaChapters(mangaId: providerId, storyId: storyId)
} else {
diff --git a/frontend/FableApp/Features/Library/ViewModels/StoryStore.swift b/frontend/FableApp/Features/Library/ViewModels/StoryStore.swift
index 2ae7e68..17e15be 100644
--- a/frontend/FableApp/Features/Library/ViewModels/StoryStore.swift
+++ b/frontend/FableApp/Features/Library/ViewModels/StoryStore.swift
@@ -4,6 +4,8 @@ import Combine
@MainActor
public final class StoryStore: ObservableObject {
@Published var stories: [Story] = []
+ @Published var recentGutenbergStories: [Story] = []
+ @Published var popularGutenbergStories: [Story] = []
@Published var selectedCategory: String = "All"
@Published var activeReaderStory: Story?
@Published var isShowingDisplayOptions: Bool = false
@@ -56,10 +58,27 @@ public final class StoryStore: ObservableObject {
@Published private(set) var isRefreshingProviderCatalogs = false
private let apiService: StoryAPIServiceProtocol = StoryAPIService()
+ nonisolated static let currentExternalChapterParserVersion = 2
+ private static let externalChapterParserVersionsDefaultsKey = "fable_external_chapter_parser_versions_v1"
+
private func providerCatalogRefreshKey(_ provider: CatalogProvider) -> String {
"fable_provider_catalog_last_success_\(provider.rawValue)"
}
+ private func verifiedChapterParserVersion(for storyId: UUID) -> Int {
+ let versions = UserDefaults.standard.dictionary(forKey: Self.externalChapterParserVersionsDefaultsKey) as? [String: Int]
+ return versions?[storyId.uuidString] ?? 0
+ }
+
+ private func markChapterParserVersionVerified(
+ for storyId: UUID,
+ version: Int = StoryStore.currentExternalChapterParserVersion
+ ) {
+ var versions = UserDefaults.standard.dictionary(forKey: Self.externalChapterParserVersionsDefaultsKey) as? [String: Int] ?? [:]
+ versions[storyId.uuidString] = version
+ UserDefaults.standard.set(versions, forKey: Self.externalChapterParserVersionsDefaultsKey)
+ }
+
public var persistentDeviceId: UUID {
let ownerKey = AuthManager.shared.currentSession?.id.uuidString ?? "guest"
let key = "fable_device_id_\(ownerKey)"
@@ -456,6 +475,7 @@ public final class StoryStore: ObservableObject {
}
PersistenceService.shared.saveStory(updatedStory)
persistProfileStoriesCache(profileStories, for: session.id)
+ reloadPinnedQuotes()
publishErrorMessage = nil
return updatedStory
} catch let error as APIRequestError {
@@ -478,8 +498,12 @@ public final class StoryStore: ObservableObject {
try await apiService.deleteStory(id: id, token: token)
stories.removeAll { $0.id == id }
profileStories.removeAll { $0.id == id }
+ if activeStoryAnnotations.contains(where: { $0.storyId == id }) {
+ activeStoryAnnotations.removeAll { $0.storyId == id }
+ }
PersistenceService.shared.deleteStory(storyId: id)
persistProfileStoriesCache(profileStories, for: session.id)
+ reloadPinnedQuotes()
publishErrorMessage = nil
return true
} catch let error as APIRequestError {
@@ -491,6 +515,113 @@ public final class StoryStore: ObservableObject {
}
}
+ static func hasUsableCachedChapters(
+ _ chapters: [Chapter]?,
+ format: ContentFormat,
+ allowExternalMangaSource: Bool = false
+ ) -> Bool {
+ guard let chapters, !chapters.isEmpty else { return false }
+ if format == .manga {
+ return chapters.contains {
+ !$0.pageUrls.isEmpty || (allowExternalMangaSource && $0.externalSourceURL != nil)
+ }
+ }
+ return chapters.contains(where: \.hasReadableText)
+ }
+
+ static func shouldInvalidateCachedChapters(
+ _ chapters: [Chapter]?,
+ sourceProvider: SourceProvider,
+ verifiedParserVersion: Int
+ ) -> Bool {
+ guard sourceProvider == .gutenberg || sourceProvider == .standardEbooks else {
+ return false
+ }
+ guard verifiedParserVersion < currentExternalChapterParserVersion else {
+ return false
+ }
+ guard let chapters, !chapters.isEmpty else {
+ return false
+ }
+ guard chapters.count <= 1 else {
+ return false
+ }
+ let firstChapter = chapters.first
+ return firstChapter?.title == "Chapter I: The Complete Tale"
+ || (firstChapter?.wordCount ?? 0) >= 1_500
+ }
+
+ static func staleUnengagedExternalStoryIDs(
+ in stories: [Story],
+ provider: SourceProvider,
+ liveStoryIDs: Set,
+ isAnnotatedProvider: (UUID) -> Bool
+ ) -> Set {
+ guard !liveStoryIDs.isEmpty else { return [] }
+ var staleIDs = Set()
+ for story in stories {
+ guard story.sourceProvider == provider,
+ story.ownerUserId == nil,
+ !liveStoryIDs.contains(story.id),
+ !story.isBookmarked,
+ !story.isCompleted,
+ story.progressPercent == 0,
+ story.lastReadChapterId == nil,
+ !isAnnotatedProvider(story.id) else {
+ continue
+ }
+ staleIDs.insert(story.id)
+ }
+ return staleIDs
+ }
+
+ static func isLocallyReadable(
+ content: String,
+ chapters: [Chapter]?,
+ format: ContentFormat
+ ) -> Bool {
+ if !content.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+ return true
+ }
+ return hasUsableCachedChapters(chapters, format: format)
+ }
+
+ static func shouldHydratePersistedStory(
+ content: String,
+ cachedChapters: [Chapter],
+ format: ContentFormat,
+ isBookmarked: Bool,
+ isCompleted: Bool,
+ readingProgress: Double,
+ lastReadChapterId: String?
+ ) -> Bool {
+ if isLocallyReadable(content: content, chapters: cachedChapters, format: format) {
+ return true
+ }
+ return isBookmarked || isCompleted || readingProgress > 0 || lastReadChapterId != nil
+ }
+
+ static func staleUnavailableOriginalStoryIDs(
+ in stories: [Story],
+ remoteStoryIDs: Set,
+ profileStoryIDs: Set,
+ cachedChaptersProvider: (UUID) -> [Chapter]
+ ) -> Set {
+ let activeIDs = remoteStoryIDs.union(profileStoryIDs)
+ var staleIDs = Set()
+ for story in stories {
+ guard story.sourceProvider == .fableOriginal,
+ !activeIDs.contains(story.id) else {
+ continue
+ }
+ let localChapters = story.chapters ?? cachedChaptersProvider(story.id)
+ if !isLocallyReadable(content: story.content, chapters: localChapters, format: story.contentFormat) {
+ staleIDs.insert(story.id)
+ }
+ }
+ return staleIDs
+ }
+
private func syncWithPersistence() {
// Hydrate and reconcile from SQLite
let persisted = PersistenceService.shared.fetchAllStories()
@@ -527,31 +658,46 @@ public final class StoryStore: ObservableObject {
stories[idx].contentFormat = ContentFormat(rawValue: entity.contentFormatRaw ?? "PROSE") ?? .prose
stories[idx].sourceProvider = SourceProvider(rawValue: entity.sourceProviderRaw ?? "FABLE_ORIGINAL") ?? .fableOriginal
let cachedChapters = PersistenceService.shared.cachedChapters(storyId: entity.id)
- let isUsable: Bool
- if stories[idx].contentFormat == .manga {
- isUsable = cachedChapters.contains { !$0.pageUrls.isEmpty }
- } else {
- isUsable = cachedChapters.contains(where: \.hasReadableText)
+ let verifiedVersion = verifiedChapterParserVersion(for: entity.id)
+ let isStaleChapterCache = Self.shouldInvalidateCachedChapters(
+ cachedChapters,
+ sourceProvider: stories[idx].sourceProvider,
+ verifiedParserVersion: verifiedVersion
+ )
+ if isStaleChapterCache {
+ PersistenceService.shared.clearCachedChapters(storyId: entity.id)
+ stories[idx].chapters = nil
+ } else if Self.hasUsableCachedChapters(cachedChapters, format: stories[idx].contentFormat) {
+ stories[idx].chapters = cachedChapters
}
- if isUsable { stories[idx].chapters = cachedChapters }
stories[idx].lastReadChapterId = entity.lastReadChapterId
stories[idx].lastReadChapterNumber = entity.lastReadChapterNumber
} else {
let initialCached = PersistenceService.shared.cachedChapters(storyId: entity.id)
let format = ContentFormat(rawValue: entity.contentFormatRaw ?? "PROSE") ?? .prose
- let isUsableInitial = format == .manga
- ? initialCached.contains { !$0.pageUrls.isEmpty }
- : initialCached.contains(where: \.hasReadableText)
- if provider != .fableOriginal
- && !isUsableInitial
- && entity.content.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
- && !entity.isBookmarked
- && !entity.isCompleted
- && entity.readingProgress <= 0
- && entity.lastReadChapterId == nil {
+ let verifiedVersion = verifiedChapterParserVersion(for: entity.id)
+ let isStaleInitialCache = Self.shouldInvalidateCachedChapters(
+ initialCached,
+ sourceProvider: provider,
+ verifiedParserVersion: verifiedVersion
+ )
+ if isStaleInitialCache {
+ PersistenceService.shared.clearCachedChapters(storyId: entity.id)
+ }
+ let effectiveCached = isStaleInitialCache ? [] : initialCached
+ let isUsableInitial = Self.hasUsableCachedChapters(effectiveCached, format: format)
+ guard Self.shouldHydratePersistedStory(
+ content: entity.content,
+ cachedChapters: effectiveCached,
+ format: format,
+ isBookmarked: entity.isBookmarked,
+ isCompleted: entity.isCompleted,
+ readingProgress: entity.readingProgress,
+ lastReadChapterId: entity.lastReadChapterId
+ ) else {
continue
}
- let validInitial = isUsableInitial ? initialCached : nil
+ let validInitial = isUsableInitial ? effectiveCached : nil
let userStory = Story(
id: entity.id,
title: entity.title,
@@ -727,7 +873,9 @@ public final class StoryStore: ObservableObject {
stories[index].heroImageName = nil
}
if !remote.author.isEmpty { stories[index].author = remote.author }
- stories[index].totalChapters = remote.totalChapters
+ if remote.totalChapters > 0 {
+ stories[index].totalChapters = max(stories[index].totalChapters, remote.totalChapters)
+ }
stories[index].contentFormat = remote.contentFormat
stories[index].sourceProvider = remote.sourceProvider
if let ownerUserId = remote.ownerUserId { stories[index].ownerUserId = ownerUserId }
@@ -750,6 +898,19 @@ public final class StoryStore: ObservableObject {
}
}
+ let staleOriginalIDs = Self.staleUnavailableOriginalStoryIDs(
+ in: stories,
+ remoteStoryIDs: synchronizedStoryIds,
+ profileStoryIDs: Set(profileStories.map(\.id)),
+ cachedChaptersProvider: { PersistenceService.shared.cachedChapters(storyId: $0) }
+ )
+ if !staleOriginalIDs.isEmpty {
+ stories.removeAll { staleOriginalIDs.contains($0.id) }
+ for staleID in staleOriginalIDs {
+ PersistenceService.shared.deleteStory(storyId: staleID, onlyIfUnannotated: true)
+ }
+ }
+
await refreshProviderCatalogs()
// 2. Fetch live dynamic categories/genres from backend and merge catalog taxonomy
@@ -833,38 +994,52 @@ public final class StoryStore: ObservableObject {
/// Loads authentic chapters on demand for the active reading story
func fetchChapters(for story: Story) async throws -> [Chapter] {
- let isUsable = { (chaps: [Chapter]?) -> Bool in
- guard let chaps, !chaps.isEmpty else { return false }
- if story.contentFormat == .manga {
- return chaps.contains { !$0.pageUrls.isEmpty || $0.externalSourceURL != nil }
- }
- return chaps.contains(where: \.hasReadableText)
- }
+ let verifiedVersion = verifiedChapterParserVersion(for: story.id)
+ var offlineFallbackChapters: [Chapter]? = nil
- if let existing = story.chapters, isUsable(existing) {
- return existing
+ if let existing = story.chapters,
+ Self.hasUsableCachedChapters(existing, format: story.contentFormat, allowExternalMangaSource: true) {
+ if !Self.shouldInvalidateCachedChapters(existing, sourceProvider: story.sourceProvider, verifiedParserVersion: verifiedVersion) {
+ return existing
+ }
+ offlineFallbackChapters = existing
}
let cached = PersistenceService.shared.cachedChapters(storyId: story.id)
- if isUsable(cached) {
- return cached
- }
- let fetched = try await apiService.fetchChapters(
- for: story.id,
- sourceProvider: story.sourceProvider.rawValue,
- providerId: story.providerId
- )
- if let idx = stories.firstIndex(where: { $0.id == story.id }) {
- stories[idx].chapters = fetched
- stories[idx].totalChapters = max(1, fetched.count)
+ if Self.hasUsableCachedChapters(cached, format: story.contentFormat, allowExternalMangaSource: true) {
+ if !Self.shouldInvalidateCachedChapters(cached, sourceProvider: story.sourceProvider, verifiedParserVersion: verifiedVersion) {
+ return cached
+ }
+ if offlineFallbackChapters == nil {
+ offlineFallbackChapters = cached
+ }
}
- if activeReaderStory?.id == story.id {
- activeReaderStory?.chapters = fetched
- activeReaderStory?.totalChapters = max(1, fetched.count)
+ do {
+ let fetched = try await apiService.fetchChapters(
+ for: story.id,
+ sourceProvider: story.sourceProvider.rawValue,
+ providerId: story.providerId
+ )
+ if let idx = stories.firstIndex(where: { $0.id == story.id }) {
+ stories[idx].chapters = fetched
+ stories[idx].totalChapters = max(1, fetched.count)
+ }
+ if activeReaderStory?.id == story.id {
+ activeReaderStory?.chapters = fetched
+ activeReaderStory?.totalChapters = max(1, fetched.count)
+ }
+ let updatedStory = stories.first(where: { $0.id == story.id }) ?? story
+ PersistenceService.shared.saveStory(updatedStory)
+ PersistenceService.shared.saveCachedChapters(fetched, storyId: story.id)
+ if story.sourceProvider == .gutenberg || story.sourceProvider == .standardEbooks {
+ markChapterParserVersionVerified(for: story.id)
+ }
+ return fetched
+ } catch {
+ if let offlineFallbackChapters {
+ return offlineFallbackChapters
+ }
+ throw error
}
- let updatedStory = stories.first(where: { $0.id == story.id }) ?? story
- PersistenceService.shared.saveStory(updatedStory)
- PersistenceService.shared.saveCachedChapters(fetched, storyId: story.id)
- return fetched
}
@@ -886,7 +1061,9 @@ public final class StoryStore: ObservableObject {
PersistenceService.shared.saveStory(cached)
}
}
- await fetchGutenbergPublicStories(topic: nil, search: search)
+ async let seSearch: () = fetchStandardEbooksPublicStories(topic: nil, search: search)
+ async let gutenbergSearch: () = fetchGutenbergPublicStories(topic: nil, search: search)
+ _ = await (seSearch, gutenbergSearch)
if Self.isMangaEnabled {
await fetchMangaPublicStories(search: search)
}
@@ -921,11 +1098,14 @@ public final class StoryStore: ObservableObject {
func fetchAuthorStories(for writer: Writer) async -> [Story] {
if Self.isMangaEnabled {
+ async let seSearch: () = fetchStandardEbooksPublicStories(topic: nil, search: writer.name)
async let gutenbergSearch: () = fetchGutenbergPublicStories(topic: nil, search: writer.name)
async let mangaSearch: () = fetchMangaPublicStories(search: writer.name)
- _ = await (gutenbergSearch, mangaSearch)
+ _ = await (seSearch, gutenbergSearch, mangaSearch)
} else {
- await fetchGutenbergPublicStories(topic: nil, search: writer.name)
+ async let seSearch: () = fetchStandardEbooksPublicStories(topic: nil, search: writer.name)
+ async let gutenbergSearch: () = fetchGutenbergPublicStories(topic: nil, search: writer.name)
+ _ = await (seSearch, gutenbergSearch)
}
if let remoteStories = try? await apiService.fetchStories(genre: nil, search: writer.name) {
@@ -955,48 +1135,120 @@ public final class StoryStore: ObservableObject {
return authorStories.first ?? stories(for: writer).first
}
- func fetchGutenbergPublicStories(topic: String? = nil, search: String? = nil) async {
+ private func mergePublicProseBooks(
+ _ fetched: [Story],
+ provider: CatalogProvider,
+ replaceUnengagedSnapshot: Bool = false
+ ) {
+ recordProviderCatalogResult(provider, succeeded: true)
+ if replaceUnengagedSnapshot && !fetched.isEmpty {
+ let sourceProvider: SourceProvider = provider == .standardEbooks ? .standardEbooks : .gutenberg
+ let staleIDs = Self.staleUnengagedExternalStoryIDs(
+ in: stories,
+ provider: sourceProvider,
+ liveStoryIDs: Set(fetched.map(\.id)),
+ isAnnotatedProvider: { PersistenceService.shared.hasAnyAnnotations(for: $0) }
+ )
+ if !staleIDs.isEmpty {
+ stories.removeAll { staleIDs.contains($0.id) }
+ for staleID in staleIDs {
+ PersistenceService.shared.deleteStory(storyId: staleID, onlyIfUnannotated: true)
+ }
+ }
+ }
+ for book in fetched {
+ if let index = stories.firstIndex(where: { $0.id == book.id }) {
+ stories[index].title = book.title
+ if !book.genre.rawValue.isEmpty {
+ stories[index].genre = book.genre
+ }
+ stories[index].synopsis = book.synopsis
+ if !book.content.isEmpty {
+ stories[index].content = book.content
+ }
+ if book.readTimeMinutes > 0 {
+ stories[index].readTimeMinutes = book.readTimeMinutes
+ }
+ if let chaps = book.chapters, !chaps.isEmpty {
+ stories[index].chapters = chaps
+ PersistenceService.shared.saveCachedChapters(chaps, storyId: book.id)
+ } else if let existingChaps = stories[index].chapters,
+ Self.shouldInvalidateCachedChapters(
+ existingChaps,
+ sourceProvider: book.sourceProvider,
+ verifiedParserVersion: verifiedChapterParserVersion(for: book.id)
+ ) {
+ stories[index].chapters = nil
+ PersistenceService.shared.clearCachedChapters(storyId: book.id)
+ }
+ stories[index].coverImageUrl = validCoverImageURL(book.coverImageUrl)
+ stories[index].contentFormat = book.contentFormat
+ stories[index].sourceProvider = book.sourceProvider
+ stories[index].providerId = book.providerId
+ stories[index].providerDownloadCount = book.providerDownloadCount
+ stories[index].totalChapters = max(
+ max(stories[index].totalChapters, stories[index].chapters?.count ?? 0),
+ book.totalChapters
+ )
+ if book.isRecentSubmission {
+ stories[index].isRecentSubmission = true
+ }
+ if let badge = book.badgeText { stories[index].badgeText = badge }
+ if stories[index].progressPercent == 0,
+ let savedState = loadShelfStateCache()[stories[index].id.uuidString],
+ !savedState.isEmpty {
+ applyShelfState(savedState, to: &stories[index])
+ }
+ PersistenceService.shared.saveStory(stories[index])
+ } else {
+ var liveBook = book
+ liveBook.coverImageUrl = validCoverImageURL(book.coverImageUrl)
+ if let savedState = loadShelfStateCache()[liveBook.id.uuidString] {
+ applyShelfState(savedState, to: &liveBook)
+ }
+ stories.append(liveBook)
+ PersistenceService.shared.saveStory(liveBook)
+ if let chaps = liveBook.chapters, !chaps.isEmpty {
+ PersistenceService.shared.saveCachedChapters(chaps, storyId: liveBook.id)
+ }
+ }
+ }
+ }
+
+ func fetchStandardEbooksPublicStories(topic: String? = nil, search: String? = nil) async {
do {
- let fetched = try await apiService.fetchGutenbergStories(topic: topic, search: search)
- recordProviderCatalogResult(.gutenberg, succeeded: true)
- for book in fetched {
- if let index = stories.firstIndex(where: { $0.id == book.id }) {
- stories[index].synopsis = book.synopsis
- if !book.content.isEmpty {
- stories[index].content = book.content
- }
- if book.readTimeMinutes > 0 {
- stories[index].readTimeMinutes = book.readTimeMinutes
- }
- if let chaps = book.chapters, !chaps.isEmpty {
- stories[index].chapters = chaps
- PersistenceService.shared.saveCachedChapters(chaps, storyId: book.id)
- }
- stories[index].coverImageUrl = validCoverImageURL(book.coverImageUrl)
- stories[index].contentFormat = book.contentFormat
- stories[index].sourceProvider = book.sourceProvider
- stories[index].providerId = book.providerId
- stories[index].providerDownloadCount = book.providerDownloadCount
- stories[index].totalChapters = max(stories[index].chapters?.count ?? 0, book.totalChapters)
- if stories[index].progressPercent == 0,
- let savedState = loadShelfStateCache()[stories[index].id.uuidString],
- !savedState.isEmpty {
- applyShelfState(savedState, to: &stories[index])
+ let fetched = try await apiService.fetchStandardEbooksStories(topic: topic, search: search)
+ let isBrowseSnapshot = topic != nil && (search ?? "").isEmpty
+ mergePublicProseBooks(fetched, provider: .standardEbooks, replaceUnengagedSnapshot: isBrowseSnapshot)
+ } catch {
+ recordProviderCatalogResult(.standardEbooks, succeeded: false)
+ }
+ }
+
+ func fetchGutenbergPublicStories(topic: String? = nil, search: String? = nil, sort: String? = nil) async {
+ do {
+ let fetched = try await apiService.fetchGutenbergStories(topic: topic, search: search, sort: sort)
+ if sort == "recent" {
+ recentGutenbergStories = fetched
+ let recentStoryIDs = Set(fetched.map(\.id))
+ for index in stories.indices where stories[index].sourceProvider == .gutenberg {
+ let isRecent = recentStoryIDs.contains(stories[index].id)
+ guard stories[index].isRecentSubmission != isRecent else { continue }
+ stories[index].isRecentSubmission = isRecent
+ if !isRecent && stories[index].badgeText == "NEW ON GUTENBERG" {
+ stories[index].badgeText = nil
}
PersistenceService.shared.saveStory(stories[index])
- } else {
- var liveBook = book
- liveBook.coverImageUrl = validCoverImageURL(book.coverImageUrl)
- if let savedState = loadShelfStateCache()[liveBook.id.uuidString] {
- applyShelfState(savedState, to: &liveBook)
- }
- stories.append(liveBook)
- PersistenceService.shared.saveStory(liveBook)
- if let chaps = liveBook.chapters, !chaps.isEmpty {
- PersistenceService.shared.saveCachedChapters(chaps, storyId: liveBook.id)
- }
}
+ } else if sort == "popular" {
+ popularGutenbergStories = fetched
}
+ let isBrowseSnapshot = topic != nil && (search ?? "").isEmpty
+ mergePublicProseBooks(
+ fetched,
+ provider: .gutenberg,
+ replaceUnengagedSnapshot: sort == nil && isBrowseSnapshot
+ )
} catch {
recordProviderCatalogResult(.gutenberg, succeeded: false)
}
@@ -1060,7 +1312,10 @@ public final class StoryStore: ObservableObject {
guard !isRefreshingProviderCatalogs else { return }
isRefreshingProviderCatalogs = true
defer { isRefreshingProviderCatalogs = false }
- await fetchGutenbergPublicStories(topic: "fiction", search: nil)
+ async let standardEbooksRefresh: () = fetchStandardEbooksPublicStories(topic: "fiction", search: nil)
+ async let popularGutenbergRefresh: () = fetchGutenbergPublicStories(topic: "fiction", search: nil, sort: "popular")
+ async let recentGutenbergRefresh: () = fetchGutenbergPublicStories(topic: nil, search: nil, sort: "recent")
+ _ = await (standardEbooksRefresh, popularGutenbergRefresh, recentGutenbergRefresh)
if Self.isMangaEnabled {
await fetchMangaPublicStories(search: nil)
}
@@ -1631,6 +1886,7 @@ public final class StoryStore: ObservableObject {
func addAnnotation(
story: Story,
text: String,
+ chapterNumber: Int? = nil,
startOffset: Int,
endOffset: Int,
color: HighlightColor,
@@ -1641,6 +1897,7 @@ public final class StoryStore: ObservableObject {
storyId: story.id,
storyTitle: story.title,
storyAuthor: story.author,
+ chapterNumber: chapterNumber,
utf16StartOffset: startOffset,
utf16EndOffset: endOffset,
selectedText: text,
@@ -1651,11 +1908,34 @@ public final class StoryStore: ObservableObject {
activeStoryAnnotations.append(annotation)
PersistenceService.shared.saveAnnotation(
annotation,
- ownerUserId: AuthManager.shared.currentSession?.id
+ ownerUserId: AuthManager.shared.currentSession?.id,
+ storyFallback: story
)
- if pinToJournal {
- reloadPinnedQuotes()
+ reloadPinnedQuotes()
+ }
+
+ func updateAnnotation(
+ _ annotation: Annotation,
+ story: Story,
+ color: HighlightColor,
+ note: String?,
+ pinToJournal: Bool
+ ) {
+ var updated = annotation
+ updated.color = color
+ updated.note = note
+ updated.isPinnedToJournal = pinToJournal
+ updated.storyTitle = story.title
+ updated.storyAuthor = story.author
+ if let idx = activeStoryAnnotations.firstIndex(where: { $0.id == annotation.id }) {
+ activeStoryAnnotations[idx] = updated
}
+ PersistenceService.shared.saveAnnotation(
+ updated,
+ ownerUserId: AuthManager.shared.currentSession?.id,
+ storyFallback: story
+ )
+ reloadPinnedQuotes()
}
func deleteAnnotation(id: UUID, storyId: UUID) {
diff --git a/frontend/FableApp/Features/Library/Views/AuthorDetailView.swift b/frontend/FableApp/Features/Library/Views/AuthorDetailView.swift
index 504a0b0..ea68fcd 100644
--- a/frontend/FableApp/Features/Library/Views/AuthorDetailView.swift
+++ b/frontend/FableApp/Features/Library/Views/AuthorDetailView.swift
@@ -247,7 +247,9 @@ private struct AuthorStoryRowView: View {
HStack(spacing: 3) {
Image(systemName: "square.stack.fill")
.fableFont(size: 10)
- Text("\(max(1, story.totalChapters)) Chapters")
+ Text(story.totalChapters > 0
+ ? "\(story.totalChapters) \(story.totalChapters == 1 ? "Chapter" : "Chapters")"
+ : "Chapter count loads when opened")
.fableFont(size: 11, weight: .medium)
}
.foregroundColor(FableTheme.textMuted)
diff --git a/frontend/FableApp/Features/Library/Views/LibraryView.swift b/frontend/FableApp/Features/Library/Views/LibraryView.swift
index fc8551b..78647a4 100644
--- a/frontend/FableApp/Features/Library/Views/LibraryView.swift
+++ b/frontend/FableApp/Features/Library/Views/LibraryView.swift
@@ -56,6 +56,20 @@ public struct LibraryView: View {
return validStories.filter { store.storyMatchesCategory($0, category: selectedFilter) }
}
}
+
+ private var visibleRecentGutenbergStories: [Story] {
+ store.recentGutenbergStories.filter { story in
+ !PersistenceService.legacyDemoStoryIds.contains(story.id)
+ && (selectedFilter == "All" || store.storyMatchesCategory(story, category: selectedFilter))
+ }
+ }
+
+ private var visiblePopularGutenbergStories: [Story] {
+ store.popularGutenbergStories.filter { story in
+ !PersistenceService.legacyDemoStoryIds.contains(story.id)
+ && (selectedFilter == "All" || store.storyMatchesCategory(story, category: selectedFilter))
+ }
+ }
public init() {}
@@ -394,11 +408,29 @@ public struct LibraryView: View {
}
.padding(.top, 6)
}
+
+ if !visibleRecentGutenbergStories.isEmpty {
+ providerBookCollection(
+ title: "New on Gutenberg",
+ subtitle: "Recently added public-domain books",
+ badge: "NEW",
+ stories: visibleRecentGutenbergStories
+ )
+ }
+
+ if !visiblePopularGutenbergStories.isEmpty {
+ providerBookCollection(
+ title: "Reader Favorites",
+ subtitle: "Popular books from Project Gutenberg",
+ badge: "POPULAR",
+ stories: visiblePopularGutenbergStories
+ )
+ }
- // Latest Releases Section
+ // Complete library catalog
VStack(alignment: .leading, spacing: 12) {
HStack {
- Text("Latest Releases")
+ Text("Browse Library")
.fableFont(size: 18, weight: .bold, design: .default)
.foregroundColor(FableTheme.textPrimary)
@@ -535,6 +567,75 @@ public struct LibraryView: View {
}
}
+ private func providerBookCollection(
+ title: String,
+ subtitle: String,
+ badge: String,
+ stories: [Story]
+ ) -> some View {
+ VStack(alignment: .leading, spacing: 12) {
+ VStack(alignment: .leading, spacing: 3) {
+ Text(title)
+ .fableFont(size: 18, weight: .bold)
+ .foregroundColor(FableTheme.textPrimary)
+ Text(subtitle)
+ .fableFont(size: 12)
+ .foregroundColor(FableTheme.textMuted)
+ }
+ .padding(.horizontal, 20)
+
+ ScrollView(.horizontal, showsIndicators: false) {
+ HStack(alignment: .top, spacing: 12) {
+ ForEach(stories) { story in
+ Button {
+ selectedStoryToRead = story
+ } label: {
+ VStack(alignment: .leading, spacing: 7) {
+ ZStack(alignment: .topLeading) {
+ FableImageView(
+ name: story.effectiveCoverImage,
+ title: story.title,
+ placeholderIcon: "book.closed"
+ )
+ .frame(width: 132, height: 166)
+ .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
+
+ Text(badge)
+ .fableFont(size: 8, weight: .heavy)
+ .tracking(0.4)
+ .foregroundColor(.white)
+ .padding(.horizontal, 7)
+ .padding(.vertical, 4)
+ .background(FableTheme.brandPrimary)
+ .clipShape(Capsule())
+ .padding(7)
+ }
+
+ Text(story.title)
+ .fableFont(size: 13, weight: .semibold, design: .serif)
+ .foregroundColor(FableTheme.textPrimary)
+ .lineLimit(2)
+ .multilineTextAlignment(.leading)
+ .frame(maxWidth: .infinity, minHeight: 34, alignment: .topLeading)
+
+ Text(story.author)
+ .fableFont(size: 11)
+ .foregroundColor(FableTheme.textMuted)
+ .lineLimit(1)
+ .frame(maxWidth: .infinity, alignment: .leading)
+ }
+ .frame(width: 132, alignment: .leading)
+ .contentShape(Rectangle())
+ }
+ .buttonStyle(.plain)
+ }
+ }
+ .padding(.horizontal, 20)
+ }
+ }
+ .padding(.top, 4)
+ }
+
@ViewBuilder
private func storyBadge(for story: Story) -> some View {
if story.contentFormat == .manga {
diff --git a/frontend/FableApp/Features/Reader/Services/AudioNarratorController.swift b/frontend/FableApp/Features/Reader/Services/AudioNarratorController.swift
index f2a6828..f6806fd 100644
--- a/frontend/FableApp/Features/Reader/Services/AudioNarratorController.swift
+++ b/frontend/FableApp/Features/Reader/Services/AudioNarratorController.swift
@@ -20,12 +20,39 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
private var activeStory: Story?
private var activeChapter: Chapter?
private let voiceStorageKey = "fable_narrator_voice_id"
+ private static var registeredRemoteTargets: [(MPRemoteCommand, Any)] = []
+ public private(set) var isRemoteCommandCenterConfigured: Bool = false
+
+ public static func clampPlaybackRate(_ rate: Float) -> Float {
+ max(0.75, min(1.75, rate))
+ }
+
+ public static func makeNowPlayingInfo(
+ for story: Story,
+ chapter: Chapter? = nil,
+ isPlaying: Bool,
+ playbackRate: Float
+ ) -> [String: Any] {
+ var info = [String: Any]()
+ if let chap = chapter {
+ info[MPMediaItemPropertyTitle] = "\(story.title) • Ch. \(chap.chapterNumber)"
+ info[MPMediaItemPropertyAlbumTitle] = chap.title
+ } else {
+ info[MPMediaItemPropertyTitle] = story.title
+ info[MPMediaItemPropertyAlbumTitle] = story.genre.rawValue
+ }
+ info[MPMediaItemPropertyArtist] = story.author
+ info[MPNowPlayingInfoPropertyPlaybackRate] = isPlaying ? Double(clampPlaybackRate(playbackRate)) : 0.0
+ info[MPNowPlayingInfoPropertyDefaultPlaybackRate] = 1.0
+ return info
+ }
public override init() {
super.init()
synthesizer.delegate = self
self.selectedVoiceIdentifier = UserDefaults.standard.string(forKey: voiceStorageKey)
configureAudioSession()
+ configureRemoteCommandCenter()
}
public var availableVoices: [AVSpeechSynthesisVoice] {
@@ -39,7 +66,7 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
UserDefaults.standard.set(identifier, forKey: voiceStorageKey)
}
- private func configureAudioSession() {
+ public func configureAudioSession() {
do {
let session = AVAudioSession.sharedInstance()
try session.setCategory(.playback, mode: .spokenAudio, options: [.duckOthers])
@@ -48,15 +75,77 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
print("Audio session configuration failed: \(error)")
}
}
+
+ public func configureRemoteCommandCenter() {
+ let center = MPRemoteCommandCenter.shared()
+ for (command, token) in Self.registeredRemoteTargets {
+ command.removeTarget(token)
+ }
+ Self.registeredRemoteTargets.removeAll()
+
+ center.playCommand.isEnabled = true
+ let playTarget = center.playCommand.addTarget { [weak self] _ in
+ Task { @MainActor [weak self] in
+ guard let self else { return }
+ if self.isPaused {
+ self.synthesizer.continueSpeaking()
+ self.isPlaying = true
+ self.isPaused = false
+ self.syncNowPlayingState()
+ } else if !self.isPlaying, let story = self.activeStory {
+ self.speak(story: story, chapter: self.activeChapter)
+ }
+ }
+ return .success
+ }
+
+ center.pauseCommand.isEnabled = true
+ let pauseTarget = center.pauseCommand.addTarget { [weak self] _ in
+ Task { @MainActor [weak self] in
+ guard let self, self.isPlaying else { return }
+ self.synthesizer.pauseSpeaking(at: .immediate)
+ self.isPlaying = false
+ self.isPaused = true
+ self.syncNowPlayingState()
+ }
+ return .success
+ }
+
+ center.togglePlayPauseCommand.isEnabled = true
+ let toggleTarget = center.togglePlayPauseCommand.addTarget { [weak self] _ in
+ Task { @MainActor [weak self] in
+ self?.togglePlayback()
+ }
+ return .success
+ }
+
+ center.stopCommand.isEnabled = true
+ let stopTarget = center.stopCommand.addTarget { [weak self] _ in
+ Task { @MainActor [weak self] in
+ self?.stop()
+ }
+ return .success
+ }
+
+ Self.registeredRemoteTargets = [
+ (center.playCommand, playTarget),
+ (center.pauseCommand, pauseTarget),
+ (center.togglePlayPauseCommand, toggleTarget),
+ (center.stopCommand, stopTarget)
+ ]
+ isRemoteCommandCenterConfigured = true
+ }
public func speak(story: Story, chapter: Chapter? = nil) {
let sameStory = (activeStoryId == story.id)
let sameChapter = (activeChapterNumber == chapter?.chapterNumber)
if sameStory && sameChapter && isPaused {
+ configureAudioSession()
synthesizer.continueSpeaking()
isPlaying = true
isPaused = false
+ syncNowPlayingState()
return
}
@@ -78,6 +167,7 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
utteranceText = story.synopsis
}
+ configureAudioSession()
let utterance = AVSpeechUtterance(string: utteranceText)
if let voiceId = selectedVoiceIdentifier, let voice = AVSpeechSynthesisVoice(identifier: voiceId) {
utterance.voice = voice
@@ -85,7 +175,7 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
utterance.voice = AVSpeechSynthesisVoice(language: Locale.current.identifier)
}
- let clampedMultiplier = max(0.5, min(2.0, playbackRateMultiplier))
+ let clampedMultiplier = Self.clampPlaybackRate(playbackRateMultiplier)
utterance.rate = AVSpeechUtteranceDefaultSpeechRate * clampedMultiplier
utterance.pitchMultiplier = 0.95 // Deep, warm storytelling tone
@@ -109,10 +199,13 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
synthesizer.pauseSpeaking(at: .immediate)
isPlaying = false
isPaused = true
+ syncNowPlayingState()
} else if synthesizer.isPaused {
+ configureAudioSession()
synthesizer.continueSpeaking()
isPlaying = true
isPaused = false
+ syncNowPlayingState()
} else if let story = story ?? activeStory {
speak(story: story, chapter: chapter ?? activeChapter)
}
@@ -128,10 +221,12 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
activeStory = nil
activeChapter = nil
MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+ MPNowPlayingInfoCenter.default().playbackState = .stopped
}
public func setRateMultiplier(_ rate: Float) {
- self.playbackRateMultiplier = max(0.75, min(1.75, rate))
+ self.playbackRateMultiplier = Self.clampPlaybackRate(rate)
+ syncNowPlayingState()
}
// MARK: - AVSpeechSynthesizerDelegate
@@ -156,6 +251,7 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
self.activeStoryId = nil
self.activeChapterNumber = nil
MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+ MPNowPlayingInfoCenter.default().playbackState = .stopped
}
}
@@ -170,19 +266,23 @@ public final class AudioNarratorController: NSObject, ObservableObject, AVSpeech
self.activeStoryId = nil
self.activeChapterNumber = nil
MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+ MPNowPlayingInfoCenter.default().playbackState = .stopped
}
}
-
- private func updateNowPlayingMetadata(story: Story, chapter: Chapter? = nil) {
- var info = [String: Any]()
- if let chap = chapter {
- info[MPMediaItemPropertyTitle] = "\(story.title) • Ch. \(chap.chapterNumber)"
- info[MPMediaItemPropertyAlbumTitle] = chap.title
- } else {
- info[MPMediaItemPropertyTitle] = story.title
- info[MPMediaItemPropertyAlbumTitle] = story.genre.rawValue
+
+ public func updateNowPlayingMetadata(story: Story, chapter: Chapter? = nil) {
+ MPNowPlayingInfoCenter.default().nowPlayingInfo = Self.makeNowPlayingInfo(
+ for: story,
+ chapter: chapter,
+ isPlaying: isPlaying,
+ playbackRate: playbackRateMultiplier
+ )
+ MPNowPlayingInfoCenter.default().playbackState = isPlaying ? .playing : (isPaused ? .paused : .stopped)
+ }
+
+ private func syncNowPlayingState() {
+ if let story = activeStory {
+ updateNowPlayingMetadata(story: story, chapter: activeChapter)
}
- info[MPMediaItemPropertyArtist] = story.author
- MPNowPlayingInfoCenter.default().nowPlayingInfo = info
}
}
diff --git a/frontend/FableApp/Features/Reader/Services/PacingEngine.swift b/frontend/FableApp/Features/Reader/Services/PacingEngine.swift
index 49123ae..2b756ca 100644
--- a/frontend/FableApp/Features/Reader/Services/PacingEngine.swift
+++ b/frontend/FableApp/Features/Reader/Services/PacingEngine.swift
@@ -12,17 +12,16 @@ public final class PacingEngine: ObservableObject {
public init() {}
- public func startSession() {
- lastPageTurnTimestamp = Date()
+ public func startSession(at now: Date = Date()) {
+ lastPageTurnTimestamp = now
}
- public func recordPageTurn(wordsOnPage: Int) {
+ public func recordPageTurn(wordsOnPage: Int, at now: Date = Date()) {
guard let previousTime = lastPageTurnTimestamp else {
- lastPageTurnTimestamp = Date()
+ lastPageTurnTimestamp = now
return
}
- let now = Date()
let elapsedSeconds = now.timeIntervalSince(previousTime)
lastPageTurnTimestamp = now
diff --git a/frontend/FableApp/Features/Reader/Views/ReaderView.swift b/frontend/FableApp/Features/Reader/Views/ReaderView.swift
index 6b52419..caff99c 100644
--- a/frontend/FableApp/Features/Reader/Views/ReaderView.swift
+++ b/frontend/FableApp/Features/Reader/Views/ReaderView.swift
@@ -1,5 +1,74 @@
import SwiftUI
+public enum ReaderPassageMatcher {
+ public static func paragraphs(from text: String) -> [String] {
+ text.replacingOccurrences(of: "\r\n", with: "\n")
+ .components(separatedBy: "\n\n")
+ .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+ .filter { !$0.isEmpty }
+ }
+
+ public static func chapterIndex(for annotation: Annotation, in chapters: [Chapter]) -> Int? {
+ guard !chapters.isEmpty else { return nil }
+ if let chapterNumber = annotation.chapterNumber,
+ let matchedIndex = chapters.firstIndex(where: { $0.chapterNumber == chapterNumber }) {
+ return matchedIndex
+ }
+ let target = annotation.selectedText.trimmingCharacters(in: .whitespacesAndNewlines)
+ guard !target.isEmpty else { return nil }
+ return chapters.firstIndex { chapter in
+ let normalized = chapter.content.replacingOccurrences(of: "\r\n", with: "\n")
+ return normalized.contains(target)
+ }
+ }
+
+ public static func paragraphIndex(for annotation: Annotation, in paragraphs: [String]) -> Int? {
+ guard !paragraphs.isEmpty else { return nil }
+ let target = annotation.selectedText.trimmingCharacters(in: .whitespacesAndNewlines)
+ if !target.isEmpty,
+ let matchedIndex = paragraphs.firstIndex(where: { para in
+ para.contains(target) || target.contains(para)
+ }) {
+ return matchedIndex
+ }
+
+ if annotation.utf16StartOffset >= 0 {
+ var runningOffset = 0
+ for (index, para) in paragraphs.enumerated() {
+ let endOffset = runningOffset + para.utf16.count
+ if annotation.utf16StartOffset <= endOffset {
+ return index
+ }
+ runningOffset = endOffset + 2 // "\n\n" separator
+ }
+ }
+ return nil
+ }
+
+ public static func pageNumber(for annotation: Annotation, in pages: [String]) -> Int? {
+ guard !pages.isEmpty else { return nil }
+ let target = annotation.selectedText.trimmingCharacters(in: .whitespacesAndNewlines)
+ if !target.isEmpty,
+ let matchedIndex = pages.firstIndex(where: { page in
+ page.contains(target) || target.contains(page)
+ }) {
+ return matchedIndex + 1
+ }
+
+ if annotation.utf16StartOffset >= 0 {
+ var runningOffset = 0
+ for (index, page) in pages.enumerated() {
+ let endOffset = runningOffset + page.utf16.count
+ if annotation.utf16StartOffset <= endOffset {
+ return index + 1
+ }
+ runningOffset = endOffset + 2
+ }
+ }
+ return nil
+ }
+}
+
public struct ReaderView: View {
@EnvironmentObject var store: StoryStore
@Environment(\.dismiss) var dismiss
@@ -21,8 +90,12 @@ public struct ReaderView: View {
@State private var isChromeVisible: Bool = true
@State private var isRestoringScrollPosition: Bool = true
@State private var scrollRestoreTrigger: Int = 0
+ @State private var pendingTargetAnnotation: Annotation?
+ @State private var pendingScrollParagraphId: String? = nil
+ @State private var suppressNextPageTurnMetrics: Bool = false
// Marginalia & Highlight Sheet State (Plan 02)
+ @State private var editingAnnotation: Annotation? = nil
@State private var selectedTextToAnnotate: String? = nil
@State private var selectedHighlightColor: HighlightColor = .terracotta
@State private var annotationNote: String = ""
@@ -30,10 +103,11 @@ public struct ReaderView: View {
@State private var isShowingAnnotationSheet: Bool = false
@State private var sessionStartTime: Date = Date()
- public init(story: Story) {
+ public init(story: Story, initialTargetAnnotation: Annotation? = nil) {
self.story = story
_currentPage = State(initialValue: max(1, story.currentPage))
_totalPages = State(initialValue: max(1, story.totalPages))
+ _pendingTargetAnnotation = State(initialValue: initialTargetAnnotation)
}
private var activeChapter: Chapter? {
@@ -48,9 +122,7 @@ public struct ReaderView: View {
}
private var activeParagraphs: [String] {
- activeChapterText.components(separatedBy: "\n\n")
- .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
- .filter { !$0.isEmpty }
+ ReaderPassageMatcher.paragraphs(from: activeChapterText)
}
private var activeChapterTag: String {
@@ -293,11 +365,22 @@ public struct ReaderView: View {
// Content Viewport: Paginated Mode vs Continuous Scroll Mode (Plan 03)
if store.isPaginatedMode {
- GeometryReader { geo in
- ZStack {
- TabView(selection: $currentPage) {
- ForEach(1...max(1, totalPages), id: \.self) { pageNum in
- ScrollView(showsIndicators: false) {
+ ZStack {
+ TabView(selection: $currentPage) {
+ ForEach(1...max(1, totalPages), id: \.self) { pageNum in
+ ScrollView(showsIndicators: false) {
+ ZStack(alignment: .topLeading) {
+ Color.clear
+ .contentShape(Rectangle())
+ .onTapGesture {
+ if store.hapticFeedback {
+ HapticManager.selection()
+ }
+ withAnimation(.easeInOut(duration: 0.2)) {
+ isChromeVisible.toggle()
+ }
+ }
+
VStack(alignment: .leading, spacing: 20) {
HStack {
Text("PAGE \(pageNum) OF \(totalPages)")
@@ -310,63 +393,50 @@ public struct ReaderView: View {
.foregroundColor(store.readerTheme.isDark ? Color.white.opacity(0.75) : FableTheme.textMuted)
}
.padding(.top, 14)
-
+
if pages.indices.contains(pageNum - 1) {
- let pageText = pages[pageNum - 1]
- let pageParas = pageText.components(separatedBy: "\n\n")
- ForEach(pageParas, id: \.self) { para in
+ let pageParas = ReaderPassageMatcher.paragraphs(from: pages[pageNum - 1])
+ ForEach(Array(pageParas.enumerated()), id: \.offset) { _, para in
paragraphView(para)
}
}
-
+
Spacer().frame(height: 120)
}
- .padding(.horizontal, 24)
+ .padding(.horizontal, 32)
}
- .tag(pageNum)
}
+ .tag(pageNum)
}
- .tabViewStyle(.page(indexDisplayMode: .never))
- .onChange(of: currentPage) { oldPage, newPage in
+ }
+ .tabViewStyle(.page(indexDisplayMode: .never))
+ .onChange(of: currentPage) { oldPage, newPage in
+ guard oldPage != newPage else { return }
+ if suppressNextPageTurnMetrics {
+ suppressNextPageTurnMetrics = false
+ } else {
let wordCount = pages.indices.contains(newPage - 1) ? PacingEngine.countWords(in: pages[newPage - 1]) : 180
pacingEngine.recordPageTurn(wordsOnPage: wordCount)
- store.updateProgress(for: story.id, page: newPage, totalPages: totalPages)
}
-
- // Tachiyomi / Kindle 3-Zone Tap Navigation Overlay for Prose Books
- HStack(spacing: 0) {
- // Left 30%: Previous Page / Chapter
- Color.clear
- .contentShape(Rectangle())
- .onTapGesture {
- turnPageBack()
- }
- .frame(width: geo.size.width * 0.30)
-
- // Center 40%: Toggle Immersive Chrome
- Color.clear
- .contentShape(Rectangle())
- .onTapGesture {
- if store.hapticFeedback {
- HapticManager.selection()
- }
- withAnimation(.easeInOut(duration: 0.2)) {
- isChromeVisible.toggle()
- }
- }
- .frame(width: geo.size.width * 0.40)
-
- // Right 30%: Next Page / Chapter
- Color.clear
- .contentShape(Rectangle())
- .onTapGesture {
- turnPageForward()
- }
- .frame(width: geo.size.width * 0.30)
- }
- .frame(maxWidth: .infinity, maxHeight: .infinity)
+ persistCurrentProseProgress()
}
}
+ .overlay(alignment: .leading) {
+ Color.clear
+ .frame(width: 28)
+ .contentShape(Rectangle())
+ .onTapGesture {
+ turnPageBack()
+ }
+ }
+ .overlay(alignment: .trailing) {
+ Color.clear
+ .frame(width: 28)
+ .contentShape(Rectangle())
+ .onTapGesture {
+ turnPageForward()
+ }
+ }
} else {
// Scrollable Editorial Manuscript Body
ScrollViewReader { scrollProxy in
@@ -561,25 +631,37 @@ public struct ReaderView: View {
}
}
.onChange(of: scrollRestoreTrigger) { _, _ in
- let totalParas = activeParagraphs.count
- if currentPage > 1 && totalParas > 1 {
- let targetIdx = min(
- totalParas - 1,
- max(0, Int(((Double(currentPage - 1) / Double(max(1, totalPages))) * Double(totalParas)).rounded()))
- )
+ if let targetParaId = pendingScrollParagraphId {
+ pendingScrollParagraphId = nil
DispatchQueue.main.asyncAfter(deadline: .now() + 0.08) {
withAnimation(.easeInOut(duration: 0.2)) {
- scrollProxy.scrollTo("para-\(targetIdx)", anchor: .top)
+ scrollProxy.scrollTo(targetParaId, anchor: .center)
}
DispatchQueue.main.asyncAfter(deadline: .now() + 0.35) {
isRestoringScrollPosition = false
}
}
} else {
- DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) {
- scrollProxy.scrollTo("para-top", anchor: .top)
- DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
- isRestoringScrollPosition = false
+ let totalParas = activeParagraphs.count
+ if currentPage > 1 && totalParas > 1 {
+ let targetIdx = min(
+ totalParas - 1,
+ max(0, Int(((Double(currentPage - 1) / Double(max(1, totalPages))) * Double(totalParas)).rounded()))
+ )
+ DispatchQueue.main.asyncAfter(deadline: .now() + 0.08) {
+ withAnimation(.easeInOut(duration: 0.2)) {
+ scrollProxy.scrollTo("para-\(targetIdx)", anchor: .top)
+ }
+ DispatchQueue.main.asyncAfter(deadline: .now() + 0.35) {
+ isRestoringScrollPosition = false
+ }
+ }
+ } else {
+ DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) {
+ scrollProxy.scrollTo("para-top", anchor: .top)
+ DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
+ isRestoringScrollPosition = false
+ }
}
}
}
@@ -605,13 +687,11 @@ public struct ReaderView: View {
set: { newVal in
let target = Int(newVal.rounded())
if target != currentPage && target >= 1 && target <= totalPages {
+ suppressNextPageTurnMetrics = true
currentPage = target
if store.hapticFeedback {
HapticManager.selection()
}
- let wordCount = pages.indices.contains(currentPage - 1) ? PacingEngine.countWords(in: pages[currentPage - 1]) : 180
- pacingEngine.recordPageTurn(wordsOnPage: wordCount)
- persistCurrentProseProgress()
}
}
),
@@ -739,16 +819,22 @@ public struct ReaderView: View {
.navigationBarBackButtonHidden(true)
.onAppear {
self.sessionStartTime = Date()
+ pacingEngine.startSession()
let isUsable = story.chapters?.contains(where: \.hasReadableText) ?? false
if let existing = story.chapters, !existing.isEmpty, isUsable {
self.chapters = existing
restoreSavedChapter()
loadCurrentChapterPages(preserveCurrentPage: true)
+ applyPendingAnnotationTargetIfReady()
persistCurrentProseProgress()
triggerScrollRestore()
} else {
restoreSavedChapter()
loadCurrentChapterPages(preserveCurrentPage: true)
+ if story.sourceProvider == .fableOriginal && !activeParagraphs.isEmpty {
+ applyPendingAnnotationTargetIfReady()
+ triggerScrollRestore()
+ }
Task {
await loadChapters()
}
@@ -771,9 +857,11 @@ public struct ReaderView: View {
.onChange(of: store.readerFontSize) { _, _ in
loadCurrentChapterPages(preserveCurrentPage: true)
}
- .sheet(isPresented: $isShowingAnnotationSheet) {
+ .sheet(isPresented: $isShowingAnnotationSheet, onDismiss: {
+ resetAnnotationState()
+ }) {
annotationSheetView
- .presentationDetents([.fraction(0.48), .medium])
+ .presentationDetents([.medium, .large])
.background(Color.white)
}
.sheet(isPresented: $isShowingChapterSheet) {
@@ -784,13 +872,22 @@ public struct ReaderView: View {
isShowingChapterSheet = newValue
}
}
+
+ private func matchingAnnotation(for para: String) -> Annotation? {
+ store.activeStoryAnnotations.first { annot in
+ if let annotChapter = annot.chapterNumber,
+ let currentChapterNum = activeChapter?.chapterNumber,
+ annotChapter != currentChapterNum {
+ return false
+ }
+ return para.contains(annot.selectedText) || annot.selectedText.contains(para)
+ }
+ }
// View helper for rendered manuscript paragraph with marginalia highlighting & oral audio sync
@ViewBuilder
private func paragraphView(_ para: String) -> some View {
- let matchingAnnotation = store.activeStoryAnnotations.first { annot in
- para.contains(annot.selectedText) || annot.selectedText.contains(para)
- }
+ let matchingAnnotation = matchingAnnotation(for: para)
let isSpokenParagraph: Bool = {
guard audioNarrator.isPlaying, audioNarrator.activeStoryId == story.id else { return false }
@@ -829,7 +926,17 @@ public struct ReaderView: View {
.contentShape(Rectangle())
.animation(.easeInOut(duration: 0.25), value: isSpokenParagraph)
.onTapGesture {
+ self.editingAnnotation = matchingAnnotation
self.selectedTextToAnnotate = para
+ if let existing = matchingAnnotation {
+ self.selectedHighlightColor = existing.color
+ self.annotationNote = existing.note ?? ""
+ self.isPinToJournal = existing.isPinnedToJournal
+ } else {
+ self.selectedHighlightColor = .terracotta
+ self.annotationNote = ""
+ self.isPinToJournal = true
+ }
self.isShowingAnnotationSheet = true
}
}
@@ -844,7 +951,7 @@ public struct ReaderView: View {
.padding(.top, 12)
HStack {
- Text("Annotate Passage")
+ Text(editingAnnotation != nil ? "Edit Annotation" : "Annotate Passage")
.fableFont(size: 18, weight: .bold, design: .serif)
.foregroundColor(FableTheme.deepCharcoal)
@@ -942,35 +1049,63 @@ public struct ReaderView: View {
.tint(FableTheme.brandPrimary)
.padding(.horizontal, 20)
- // Save Action Button
- Button(action: {
- if let text = selectedTextToAnnotate {
- let fullText = activeChapterText
- let nsText = fullText as NSString
- let targetRange = nsText.range(of: text)
- let startOffset = targetRange.location != NSNotFound ? targetRange.location : 0
- let endOffset = targetRange.location != NSNotFound ? (targetRange.location + targetRange.length) : text.utf16.count
-
- store.addAnnotation(
- story: story,
- text: text,
- startOffset: startOffset,
- endOffset: endOffset,
- color: selectedHighlightColor,
- note: annotationNote.isEmpty ? nil : annotationNote,
- pinToJournal: isPinToJournal
- )
+ // Save / Update Action Button
+ VStack(spacing: 10) {
+ Button(action: {
+ let cleanNote = annotationNote.trimmingCharacters(in: .whitespacesAndNewlines)
+ let finalNote = cleanNote.isEmpty ? nil : cleanNote
+ if let existing = editingAnnotation {
+ store.updateAnnotation(
+ existing,
+ story: story,
+ color: selectedHighlightColor,
+ note: finalNote,
+ pinToJournal: isPinToJournal
+ )
+ } else if let text = selectedTextToAnnotate {
+ let fullText = activeChapterText
+ let nsText = fullText as NSString
+ let targetRange = nsText.range(of: text)
+ let startOffset = targetRange.location != NSNotFound ? targetRange.location : 0
+ let endOffset = targetRange.location != NSNotFound ? (targetRange.location + targetRange.length) : text.utf16.count
+
+ store.addAnnotation(
+ story: story,
+ text: text,
+ chapterNumber: activeChapter?.chapterNumber,
+ startOffset: startOffset,
+ endOffset: endOffset,
+ color: selectedHighlightColor,
+ note: finalNote,
+ pinToJournal: isPinToJournal
+ )
+ }
+ isShowingAnnotationSheet = false
+ resetAnnotationState()
+ }) {
+ Text(editingAnnotation != nil ? "Update Annotation" : "Save Annotation")
+ .fableFont(size: 15, weight: .semibold)
+ .frame(maxWidth: .infinity)
+ .padding(.vertical, 12)
+ .background(FableTheme.brandPrimary)
+ .foregroundColor(.white)
+ .clipShape(RoundedRectangle(cornerRadius: 12))
+ }
+
+ if let existing = editingAnnotation {
+ Button(role: .destructive) {
+ store.deleteAnnotation(id: existing.id, storyId: story.id)
+ isShowingAnnotationSheet = false
+ resetAnnotationState()
+ } label: {
+ Text("Delete Annotation")
+ .fableFont(size: 14, weight: .semibold)
+ .frame(maxWidth: .infinity)
+ .padding(.vertical, 10)
+ .background(Color.red.opacity(0.08))
+ .clipShape(RoundedRectangle(cornerRadius: 10))
+ }
}
- isShowingAnnotationSheet = false
- resetAnnotationState()
- }) {
- Text("Save Annotation")
- .fableFont(size: 15, weight: .semibold)
- .frame(maxWidth: .infinity)
- .padding(.vertical, 12)
- .background(FableTheme.brandPrimary)
- .foregroundColor(.white)
- .clipShape(RoundedRectangle(cornerRadius: 12))
}
.padding(.horizontal, 20)
.padding(.bottom, 16)
@@ -979,12 +1114,20 @@ public struct ReaderView: View {
// Helper to reset annotation state
private func resetAnnotationState() {
+ editingAnnotation = nil
selectedTextToAnnotate = nil
annotationNote = ""
selectedHighlightColor = .terracotta
isPinToJournal = true
}
+ private func setCurrentPageProgrammatically(_ targetPage: Int) {
+ let clamped = min(max(1, targetPage), max(1, totalPages))
+ guard clamped != currentPage else { return }
+ suppressNextPageTurnMetrics = true
+ currentPage = clamped
+ }
+
private func turnPageBack() {
if store.hapticFeedback {
HapticManager.selection()
@@ -993,9 +1136,6 @@ public struct ReaderView: View {
withAnimation(.easeInOut(duration: 0.2)) {
currentPage -= 1
}
- let wordCount = pages.indices.contains(currentPage - 1) ? PacingEngine.countWords(in: pages[currentPage - 1]) : 180
- pacingEngine.recordPageTurn(wordsOnPage: wordCount)
- persistCurrentProseProgress()
} else if currentChapterIndex > 0 {
if store.hapticFeedback {
HapticManager.notification(type: .success)
@@ -1012,9 +1152,6 @@ public struct ReaderView: View {
withAnimation(.easeInOut(duration: 0.2)) {
currentPage += 1
}
- let wordCount = pages.indices.contains(currentPage - 1) ? PacingEngine.countWords(in: pages[currentPage - 1]) : 180
- pacingEngine.recordPageTurn(wordsOnPage: wordCount)
- persistCurrentProseProgress()
} else if currentChapterIndex < chapters.count - 1 {
if store.hapticFeedback {
HapticManager.notification(type: .success)
@@ -1038,10 +1175,36 @@ public struct ReaderView: View {
restoreSavedChapter()
loadCurrentChapterPages(preserveCurrentPage: true)
}
+ applyPendingAnnotationTargetIfReady()
persistCurrentProseProgress()
triggerScrollRestore()
} catch {
- chapterLoadError = "Couldn't load chapters. Check your connection and try again."
+ if activeParagraphs.isEmpty {
+ chapterLoadError = "Couldn't load chapters. Check your connection and try again."
+ } else {
+ chapterLoadError = nil
+ loadCurrentChapterPages(preserveCurrentPage: true)
+ applyPendingAnnotationTargetIfReady()
+ }
+ }
+ }
+
+ private func applyPendingAnnotationTargetIfReady() {
+ guard let target = pendingTargetAnnotation else { return }
+ if !chapters.isEmpty,
+ let matchedChapterIdx = ReaderPassageMatcher.chapterIndex(for: target, in: chapters),
+ matchedChapterIdx != currentChapterIndex {
+ currentChapterIndex = matchedChapterIdx
+ loadCurrentChapterPages(preserveCurrentPage: false)
+ }
+ if let page = ReaderPassageMatcher.pageNumber(for: target, in: pages) {
+ setCurrentPageProgrammatically(page)
+ }
+ if let paraIdx = ReaderPassageMatcher.paragraphIndex(for: target, in: activeParagraphs) {
+ pendingScrollParagraphId = "para-\(paraIdx)"
+ }
+ if !chapters.isEmpty || !activeParagraphs.isEmpty {
+ pendingTargetAnnotation = nil
}
}
@@ -1051,11 +1214,11 @@ public struct ReaderView: View {
self.pages = chunked
self.totalPages = max(1, chunked.count)
if preserveCurrentPage {
- self.currentPage = min(max(1, self.currentPage), self.totalPages)
+ setCurrentPageProgrammatically(self.currentPage)
} else if startAtLastPage {
- self.currentPage = max(1, chunked.count)
+ setCurrentPageProgrammatically(chunked.count)
} else {
- self.currentPage = 1
+ setCurrentPageProgrammatically(1)
}
store.loadAnnotations(for: story.id)
}
@@ -1071,6 +1234,7 @@ public struct ReaderView: View {
chapterNumber: chapter.chapterNumber
)
loadCurrentChapterPages(startAtLastPage: startAtLastPage)
+ pacingEngine.startSession()
persistCurrentProseProgress()
triggerScrollRestore()
if audioNarrator.isPlaying {
@@ -1170,7 +1334,7 @@ public struct ReaderView: View {
}
.frame(maxWidth: .infinity, alignment: .center)
.padding(.vertical, 36)
- } else if let chapterLoadError {
+ } else if let chapterLoadError, activeParagraphs.isEmpty {
VStack(spacing: 12) {
Text(chapterLoadError)
.fableFont(size: 14, weight: .medium)
diff --git a/frontend/FableApp/Features/Shelf/Views/ShelfView.swift b/frontend/FableApp/Features/Shelf/Views/ShelfView.swift
index 4748be0..35e1da2 100644
--- a/frontend/FableApp/Features/Shelf/Views/ShelfView.swift
+++ b/frontend/FableApp/Features/Shelf/Views/ShelfView.swift
@@ -5,6 +5,7 @@ public struct ShelfView: View {
@State private var selectedTab: String = "Saved"
@State private var selectedStoryToRead: Story?
+ @State private var selectedQuoteTarget: Annotation?
@State private var isShowingSettingsSheet: Bool = false
@State private var isShowingProfileSheet: Bool = false
@@ -242,7 +243,8 @@ public struct ShelfView: View {
TabView {
ForEach(store.pinnedQuotes) { quote in
Button(action: {
- if let matchingStory = store.stories.first(where: { $0.id == quote.storyId }) {
+ if let matchingStory = store.stories.first(where: { $0.id == quote.storyId }) ?? PersistenceService.shared.fetchStory(id: quote.storyId) {
+ selectedQuoteTarget = quote
selectedStoryToRead = matchingStory
}
}) {
@@ -374,6 +376,7 @@ public struct ShelfView: View {
} else {
ForEach(Array(displayedStories.enumerated()), id: \.element.id) { index, story in
Button(action: {
+ selectedQuoteTarget = nil
selectedStoryToRead = story
}) {
HStack(spacing: 14) {
@@ -521,13 +524,15 @@ public struct ShelfView: View {
await store.syncWithCloudBackend()
}
}
- .fullScreenCover(item: $selectedStoryToRead) { story in
+ .fullScreenCover(item: $selectedStoryToRead, onDismiss: {
+ selectedQuoteTarget = nil
+ }) { story in
let currentStory = store.stories.first(where: { $0.id == story.id }) ?? story
if currentStory.contentFormat == .manga || currentStory.sourceProvider == .mangadex {
MangaReaderView(story: currentStory)
.environmentObject(store)
} else {
- ReaderView(story: currentStory)
+ ReaderView(story: currentStory, initialTargetAnnotation: selectedQuoteTarget)
.environmentObject(store)
}
}
diff --git a/frontend/FableAppTests/PlanFeaturesRegressionTests.swift b/frontend/FableAppTests/PlanFeaturesRegressionTests.swift
new file mode 100644
index 0000000..3c4759a
--- /dev/null
+++ b/frontend/FableAppTests/PlanFeaturesRegressionTests.swift
@@ -0,0 +1,408 @@
+import AVFAudio
+import MediaPlayer
+import SwiftData
+import XCTest
+@testable import FableApp
+
+final class PlanFeaturesRegressionTests: XCTestCase {
+ @MainActor
+ func testStoryEntityProgressClampingAndDiskRoundTrip() throws {
+ let tempDir = FileManager.default.temporaryDirectory
+ .appendingPathComponent(UUID().uuidString, isDirectory: true)
+ try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: tempDir) }
+
+ let storeURL = tempDir.appendingPathComponent("plans_01.store")
+ let storyId = UUID()
+ let lowClamp = StoryEntity(
+ id: UUID(),
+ title: "Negative Clamp",
+ author: "Author",
+ genreRaw: "Folklore",
+ synopsis: "Clamp check",
+ content: "Text",
+ readTimeMinutes: 1,
+ readingProgress: -0.5
+ )
+ let highClamp = StoryEntity(
+ id: UUID(),
+ title: "High Clamp",
+ author: "Author",
+ genreRaw: "Folklore",
+ synopsis: "Clamp check",
+ content: "Text",
+ readTimeMinutes: 1,
+ readingProgress: 1.8
+ )
+ XCTAssertEqual(lowClamp.readingProgress, 0.0, accuracy: 0.0001)
+ XCTAssertEqual(highClamp.readingProgress, 1.0, accuracy: 0.0001)
+
+ do {
+ let service = PersistenceService(storeURL: storeURL)
+ let story = Story(
+ id: storyId,
+ title: "The Obsidian Spire",
+ author: "Gothic Author",
+ genre: Genre(rawValue: "Gothic"),
+ synopsis: "Persisted across context reset.",
+ content: "Paragraph one.\n\nParagraph two.",
+ readTimeMinutes: 3
+ )
+ service.saveStory(story)
+ service.updateProgress(storyId: storyId, progressPercent: 180, isCompleted: false, page: 4, totalPages: 4)
+ }
+
+ let reloadedService = PersistenceService(storeURL: storeURL)
+ let reloadedStory = try XCTUnwrap(reloadedService.fetchStory(id: storyId))
+ XCTAssertEqual(reloadedStory.title, "The Obsidian Spire")
+ XCTAssertEqual(reloadedStory.progressPercent, 100)
+ XCTAssertTrue(reloadedStory.isCompleted)
+ XCTAssertEqual(reloadedStory.currentPage, 4)
+ }
+
+ @MainActor
+ func testPersistenceCascadeDeleteRemovesAnnotations() throws {
+ let service = PersistenceService(isStoredInMemoryOnly: true)
+ let ownerId = UUID()
+ let storyId = UUID()
+ let story = Story(
+ id: storyId,
+ title: "Clockwork Tales",
+ author: "Tester",
+ genre: Genre(rawValue: "Mystery"),
+ synopsis: "Cascade test",
+ content: "Opening line.\n\nClosing line.",
+ readTimeMinutes: 2,
+ ownerUserId: ownerId
+ )
+
+ let annot1 = Annotation(
+ storyId: storyId,
+ storyTitle: story.title,
+ storyAuthor: story.author,
+ chapterNumber: 1,
+ utf16StartOffset: 0,
+ utf16EndOffset: 13,
+ selectedText: "Opening line.",
+ note: "First note",
+ color: .terracotta,
+ isPinnedToJournal: true
+ )
+ let annot2 = Annotation(
+ storyId: storyId,
+ storyTitle: story.title,
+ storyAuthor: story.author,
+ chapterNumber: 1,
+ utf16StartOffset: 15,
+ utf16EndOffset: 28,
+ selectedText: "Closing line.",
+ note: nil,
+ color: .sage,
+ isPinnedToJournal: false
+ )
+
+ service.saveAnnotation(annot1, ownerUserId: ownerId, storyFallback: story)
+ service.saveAnnotation(annot2, ownerUserId: ownerId, storyFallback: story)
+ XCTAssertEqual(service.fetchAnnotations(for: storyId, ownerUserId: ownerId).count, 2)
+ XCTAssertEqual(service.fetchAllPinnedAnnotations(ownerUserId: ownerId).count, 1)
+
+ service.deleteStory(storyId: storyId)
+
+ XCTAssertNil(service.fetchStory(id: storyId))
+ XCTAssertTrue(service.fetchAnnotations(for: storyId, ownerUserId: ownerId).isEmpty)
+ XCTAssertTrue(service.fetchAllPinnedAnnotations(ownerUserId: ownerId).isEmpty)
+ let remainingAnnotationRows = try service.context.fetchCount(FetchDescriptor())
+ XCTAssertEqual(remainingAnnotationRows, 0)
+ }
+
+ @MainActor
+ func testSaveAnnotationPersistsFallbackStoryPinUpdatesAndAccountIsolation() {
+ let service = PersistenceService(isStoredInMemoryOnly: true)
+ let userA = UUID()
+ let userB = UUID()
+ let storyId = UUID()
+ let fallbackStory = Story(
+ id: storyId,
+ title: "Explore Story",
+ author: "Classic Author",
+ genre: Genre(rawValue: "Classics"),
+ synopsis: "Not yet saved before reading.",
+ content: "Time is not a stream, but a clockwork wheel.",
+ readTimeMinutes: 4,
+ sourceProvider: .gutenberg,
+ providerId: "999"
+ )
+
+ let annotationId = UUID()
+ let initial = Annotation(
+ id: annotationId,
+ storyId: storyId,
+ storyTitle: fallbackStory.title,
+ storyAuthor: fallbackStory.author,
+ chapterNumber: 2,
+ utf16StartOffset: 0,
+ utf16EndOffset: 44,
+ selectedText: "Time is not a stream, but a clockwork wheel.",
+ note: "Motif",
+ color: .amber,
+ isPinnedToJournal: true
+ )
+
+ service.saveAnnotation(initial, ownerUserId: userA, storyFallback: fallbackStory)
+
+ XCTAssertNotNil(service.fetchStory(id: storyId))
+ let pinnedForA = service.fetchAllPinnedAnnotations(ownerUserId: userA)
+ XCTAssertEqual(pinnedForA.count, 1)
+ XCTAssertEqual(pinnedForA.first?.chapterNumber, 2)
+ XCTAssertTrue(service.fetchAllPinnedAnnotations(ownerUserId: userB).isEmpty)
+
+ var unpinnedUpdate = initial
+ unpinnedUpdate.isPinnedToJournal = false
+ unpinnedUpdate.note = "Updated reflection"
+ unpinnedUpdate.color = .sage
+ service.saveAnnotation(unpinnedUpdate, ownerUserId: userA)
+
+ XCTAssertTrue(service.fetchAllPinnedAnnotations(ownerUserId: userA).isEmpty)
+ let fetchedForA = service.fetchAnnotations(for: storyId, ownerUserId: userA)
+ XCTAssertEqual(fetchedForA.first?.note, "Updated reflection")
+ XCTAssertEqual(fetchedForA.first?.color, .sage)
+
+ service.deleteAnnotation(id: annotationId, ownerUserId: userB)
+ XCTAssertEqual(service.fetchAnnotations(for: storyId, ownerUserId: userA).count, 1)
+
+ service.deleteAnnotation(id: annotationId, ownerUserId: userA)
+ XCTAssertTrue(service.fetchAnnotations(for: storyId, ownerUserId: userA).isEmpty)
+ }
+
+ @MainActor
+ func testReaderPassageMatcherLocatesChapterParagraphAndPageForQuote() {
+ let storyId = UUID()
+ let chapter1 = Chapter(
+ storyId: storyId,
+ chapterNumber: 1,
+ title: "Chapter I",
+ content: "Once upon a midnight dreary.\n\nNothing unusual occurred."
+ )
+ let targetParagraph = "Time is not a stream, but a clockwork wheel."
+ let paddingPara = Array(repeating: "ticking", count: 80).joined(separator: " ")
+ let chapter2Content = [paddingPara, paddingPara, targetParagraph].joined(separator: "\n\n")
+ let chapter2 = Chapter(
+ storyId: storyId,
+ chapterNumber: 2,
+ title: "Chapter II",
+ content: chapter2Content
+ )
+ let chapters = [chapter1, chapter2]
+
+ let quoteWithChapter = Annotation(
+ storyId: storyId,
+ chapterNumber: 2,
+ utf16StartOffset: 0,
+ utf16EndOffset: targetParagraph.utf16.count,
+ selectedText: targetParagraph,
+ isPinnedToJournal: true
+ )
+ let quoteWithoutChapter = Annotation(
+ storyId: storyId,
+ chapterNumber: nil,
+ utf16StartOffset: 0,
+ utf16EndOffset: targetParagraph.utf16.count,
+ selectedText: targetParagraph,
+ isPinnedToJournal: true
+ )
+
+ XCTAssertEqual(ReaderPassageMatcher.chapterIndex(for: quoteWithChapter, in: chapters), 1)
+ XCTAssertEqual(ReaderPassageMatcher.chapterIndex(for: quoteWithoutChapter, in: chapters), 1)
+
+ let ch2Paragraphs = ReaderPassageMatcher.paragraphs(from: chapter2.content)
+ XCTAssertEqual(ReaderPassageMatcher.paragraphIndex(for: quoteWithChapter, in: ch2Paragraphs), 2)
+
+ let pages = PacingEngine.chunkIntoPages(text: chapter2.content, fontSizePercentage: 100.0, baseWordsPerPage: 100)
+ XCTAssertEqual(ReaderPassageMatcher.pageNumber(for: quoteWithChapter, in: pages), pages.count)
+ }
+
+ @MainActor
+ func testPacingEngineRejectsSubThreeSecondPageTurnsCapsIdleTimeAndMonotonicallyEstimatesRemainingMinutes() {
+ let engine = PacingEngine()
+ let t0 = Date(timeIntervalSince1970: 1_000_000)
+ engine.startSession(at: t0)
+
+ // Sub-3s page flip must be discarded
+ engine.recordPageTurn(wordsOnPage: 150, at: t0.addingTimeInterval(2.0))
+ XCTAssertEqual(engine.pacingVelocityWPM, 200.0, accuracy: 0.001)
+
+ // Deliberate turn: 120 words in 30s = 240 WPM -> 0.25*240 + 0.75*200 = 210 WPM
+ engine.recordPageTurn(wordsOnPage: 120, at: t0.addingTimeInterval(32.0))
+ XCTAssertEqual(engine.pacingVelocityWPM, 210.0, accuracy: 0.001)
+
+ // Long idle (> 180s) caps at 180s -> 210 words / 3.0 min = 70 WPM -> 0.25*70 + 0.75*210 = 175 WPM
+ engine.recordPageTurn(wordsOnPage: 210, at: t0.addingTimeInterval(632.0))
+ XCTAssertEqual(engine.pacingVelocityWPM, 175.0, accuracy: 0.001)
+
+ let est1 = engine.estimatedMinutesRemaining(remainingWords: 1200)
+ let est2 = engine.estimatedMinutesRemaining(remainingWords: 600)
+ let est3 = engine.estimatedMinutesRemaining(remainingWords: 100)
+ XCTAssertGreaterThan(est1, est2)
+ XCTAssertGreaterThanOrEqual(est2, est3)
+ XCTAssertEqual(engine.estimatedMinutesRemaining(remainingWords: 0), 1)
+ }
+
+ @MainActor
+ func testAudioNarratorRateClampingBackgroundBundleKeyAndNowPlayingMetadata() throws {
+ let narrator = AudioNarratorController()
+ defer { AudioNarratorController.shared.configureRemoteCommandCenter() }
+
+ XCTAssertEqual(AVAudioSession.sharedInstance().category, .playback)
+ XCTAssertTrue(narrator.isRemoteCommandCenterConfigured)
+
+ let center = MPRemoteCommandCenter.shared()
+ XCTAssertTrue(center.playCommand.isEnabled)
+ XCTAssertTrue(center.pauseCommand.isEnabled)
+ XCTAssertTrue(center.togglePlayPauseCommand.isEnabled)
+ XCTAssertTrue(center.stopCommand.isEnabled)
+
+ let backgroundModes = Bundle.main.object(forInfoDictionaryKey: "UIBackgroundModes") as? [String]
+ XCTAssertEqual(backgroundModes?.contains("audio"), true)
+
+ narrator.setRateMultiplier(0.25)
+ XCTAssertEqual(narrator.playbackRateMultiplier, 0.75, accuracy: 0.001)
+ narrator.setRateMultiplier(3.0)
+ XCTAssertEqual(narrator.playbackRateMultiplier, 1.75, accuracy: 0.001)
+
+ let story = Story(
+ title: "The Clockmaker",
+ author: "Aesop",
+ genre: Genre(rawValue: "Fables"),
+ synopsis: "Tick.",
+ content: "Tick tock.",
+ readTimeMinutes: 1
+ )
+ let chapter = Chapter(storyId: story.id, chapterNumber: 3, title: "Chapter Three", content: "Tick tock.")
+ narrator.updateNowPlayingMetadata(story: story, chapter: chapter)
+
+ let nowPlaying = try XCTUnwrap(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+ XCTAssertEqual(nowPlaying[MPMediaItemPropertyTitle] as? String, "The Clockmaker • Ch. 3")
+ XCTAssertEqual(nowPlaying[MPMediaItemPropertyArtist] as? String, "Aesop")
+ XCTAssertEqual(nowPlaying[MPMediaItemPropertyAlbumTitle] as? String, "Chapter Three")
+
+ narrator.stop()
+ XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+ XCTAssertEqual(MPNowPlayingInfoCenter.default().playbackState, .stopped)
+ }
+
+ @MainActor
+ func testUnreadableCachedStoryHydrationAndStaleCloudPruningHelpers() throws {
+ let tempDir = FileManager.default.temporaryDirectory
+ .appendingPathComponent(UUID().uuidString, isDirectory: true)
+ try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: tempDir) }
+
+ let service = PersistenceService(storeURL: tempDir.appendingPathComponent("stale_cleanup.store"))
+
+ let deadStub = Story(
+ id: UUID(),
+ title: "Stale Server Summary",
+ author: "Unknown",
+ genre: Genre(rawValue: "Folklore"),
+ synopsis: "Summary without content",
+ content: "",
+ readTimeMinutes: 1,
+ sourceProvider: .fableOriginal
+ )
+ let annotatedStub = Story(
+ id: UUID(),
+ title: "Annotated Server Summary",
+ author: "Unknown",
+ genre: Genre(rawValue: "Folklore"),
+ synopsis: "Summary with annotation",
+ content: "",
+ readTimeMinutes: 1,
+ sourceProvider: .fableOriginal
+ )
+ let liveRemoteOriginal = Story(
+ id: UUID(),
+ title: "Active Backend Story",
+ author: "Author",
+ genre: Genre(rawValue: "Classics"),
+ synopsis: "Available remotely",
+ content: "",
+ readTimeMinutes: 3,
+ sourceProvider: .fableOriginal
+ )
+ let localInlineOriginal = Story(
+ id: UUID(),
+ title: "Local Readable Story",
+ author: "Author",
+ genre: Genre(rawValue: "Fiction"),
+ synopsis: "Has inline prose",
+ content: "Readable prose paragraph.",
+ readTimeMinutes: 2,
+ sourceProvider: .fableOriginal
+ )
+ let gutenbergStory = Story(
+ id: UUID(),
+ title: "Alice",
+ author: "Lewis Carroll",
+ genre: Genre(rawValue: "Classics"),
+ synopsis: "Public domain",
+ content: "",
+ readTimeMinutes: 10,
+ sourceProvider: .gutenberg,
+ providerId: "11"
+ )
+
+ XCTAssertFalse(
+ StoryStore.shouldHydratePersistedStory(
+ content: "",
+ cachedChapters: [],
+ format: .prose,
+ isBookmarked: false,
+ isCompleted: false,
+ readingProgress: 0,
+ lastReadChapterId: nil
+ )
+ )
+ XCTAssertTrue(
+ StoryStore.shouldHydratePersistedStory(
+ content: "Readable offline prose",
+ cachedChapters: [],
+ format: .prose,
+ isBookmarked: false,
+ isCompleted: false,
+ readingProgress: 0,
+ lastReadChapterId: nil
+ )
+ )
+
+ let staleIDs = StoryStore.staleUnavailableOriginalStoryIDs(
+ in: [deadStub, annotatedStub, liveRemoteOriginal, localInlineOriginal, gutenbergStory],
+ remoteStoryIDs: [liveRemoteOriginal.id],
+ profileStoryIDs: [],
+ cachedChaptersProvider: { _ in [] }
+ )
+ XCTAssertEqual(staleIDs, [deadStub.id, annotatedStub.id])
+
+ service.saveStory(deadStub)
+ service.saveStory(annotatedStub)
+ service.saveAnnotation(
+ Annotation(
+ storyId: annotatedStub.id,
+ storyTitle: annotatedStub.title,
+ storyAuthor: annotatedStub.author,
+ chapterNumber: 1,
+ utf16StartOffset: 0,
+ utf16EndOffset: 4,
+ selectedText: "Note",
+ isPinnedToJournal: true
+ ),
+ ownerUserId: nil
+ )
+
+ service.deleteStory(storyId: deadStub.id, onlyIfUnannotated: true)
+ service.deleteStory(storyId: annotatedStub.id, onlyIfUnannotated: true)
+
+ XCTAssertNil(service.fetchStory(id: deadStub.id))
+ XCTAssertNotNil(service.fetchStory(id: annotatedStub.id))
+ XCTAssertEqual(service.fetchAllPinnedAnnotations(ownerUserId: nil).count, 1)
+ }
+}
diff --git a/frontend/FableAppTests/StorySummaryDecodingTests.swift b/frontend/FableAppTests/StorySummaryDecodingTests.swift
index 843abf2..08f2f33 100644
--- a/frontend/FableAppTests/StorySummaryDecodingTests.swift
+++ b/frontend/FableAppTests/StorySummaryDecodingTests.swift
@@ -220,4 +220,121 @@ final class StorySummaryDecodingTests: XCTestCase {
)
XCTAssertEqual(CreateStoryRequest.estimatedReadTimeMinutes(for: "word " + String(repeating: "story ", count: 300)), 2)
}
+
+ func testStandardEbooksStoryDecodingAndProviderStatus() throws {
+ let payload = Data(
+ """
+ {
+ "id": "6F090800-8D25-5F7E-9A56-B8D70F678C92",
+ "title": "Dracula",
+ "author": "Bram Stoker",
+ "genre": "Horror",
+ "chapter": "",
+ "synopsis": "Count Dracula travels to England.",
+ "content": "",
+ "readTimeMinutes": 700,
+ "isBookmarked": false,
+ "isCompleted": false,
+ "createdAtUtc": "2026-11-13T00:00:00Z",
+ "updatedAtUtc": "2026-11-13T00:00:00Z",
+ "coverImageUrl": "https://standardebooks.org/images/covers/bram-stoker_dracula/hash/cover@2x.jpg",
+ "totalPages": 0,
+ "currentPage": 1,
+ "progressPercent": 0,
+ "savesCount": "0",
+ "readsCount": "0",
+ "totalChapters": 0,
+ "contentFormat": "PROSE",
+ "sourceProvider": "STANDARD_EBOOKS",
+ "providerId": "bram-stoker/dracula"
+ }
+ """.utf8
+ )
+
+ let decoder = JSONDecoder()
+ decoder.dateDecodingStrategy = .iso8601
+ let story = try decoder.decode(Story.self, from: payload)
+
+ XCTAssertEqual(story.sourceProvider, .standardEbooks)
+ XCTAssertEqual(story.providerId, "bram-stoker/dracula")
+ XCTAssertEqual(story.genre.rawValue, "Horror")
+
+ var status = ProviderCatalogStatus()
+ status.record(.standardEbooks, succeeded: false)
+ XCTAssertTrue(status.warningMessage?.contains("Standard Ebooks") == true)
+ status.record(.standardEbooks, succeeded: true)
+ XCTAssertNil(status.warningMessage)
+ }
+
+ @MainActor
+ func testExternalChapterCacheInvalidationAndStaleCatalogPruningPolicy() {
+ let storyId = UUID()
+ let fallbackChapter = [
+ Chapter(
+ id: UUID(),
+ storyId: storyId,
+ chapterNumber: 1,
+ title: "Chapter I: The Complete Tale",
+ content: "A long novel concatenated into one fallback chapter.",
+ wordCount: 25_000
+ )
+ ]
+
+ XCTAssertTrue(
+ StoryStore.shouldInvalidateCachedChapters(
+ fallbackChapter,
+ sourceProvider: .gutenberg,
+ verifiedParserVersion: 0
+ )
+ )
+ XCTAssertFalse(
+ StoryStore.shouldInvalidateCachedChapters(
+ fallbackChapter,
+ sourceProvider: .gutenberg,
+ verifiedParserVersion: StoryStore.currentExternalChapterParserVersion
+ )
+ )
+ XCTAssertFalse(
+ StoryStore.shouldInvalidateCachedChapters(
+ fallbackChapter,
+ sourceProvider: .fableOriginal,
+ verifiedParserVersion: 0
+ )
+ )
+
+ let multiChapters = [
+ Chapter(id: UUID(), storyId: storyId, chapterNumber: 1, title: "Chapter I", content: "Part one.", wordCount: 500),
+ Chapter(id: UUID(), storyId: storyId, chapterNumber: 2, title: "Chapter II", content: "Part two.", wordCount: 500)
+ ]
+ XCTAssertFalse(
+ StoryStore.shouldInvalidateCachedChapters(
+ multiChapters,
+ sourceProvider: .gutenberg,
+ verifiedParserVersion: 0
+ )
+ )
+
+ let liveId = UUID()
+ let staleUnengagedId = UUID()
+ let staleBookmarkedId = UUID()
+ let staleAnnotatedId = UUID()
+ let seOtherProviderId = UUID()
+
+ let stories = [
+ Story(id: liveId, title: "Live Classic", author: "Lewis Carroll", genre: "Fiction", excerpt: "S", paragraphs: [], coverImageName: "", heroImageName: "", isSaved: false, sourceProvider: .gutenberg, providerId: "11"),
+ Story(id: staleUnengagedId, title: "Old Pulp", author: "Author", genre: "Fiction", excerpt: "S", paragraphs: [], coverImageName: "", heroImageName: "", isSaved: false, sourceProvider: .gutenberg, providerId: "79934"),
+ Story(id: staleBookmarkedId, title: "Saved Old", author: "Author", genre: "Fiction", excerpt: "S", paragraphs: [], coverImageName: "", heroImageName: "", isSaved: true, sourceProvider: .gutenberg, providerId: "79931"),
+ Story(id: staleAnnotatedId, title: "Noted Old", author: "Author", genre: "Fiction", excerpt: "S", paragraphs: [], coverImageName: "", heroImageName: "", isSaved: false, sourceProvider: .gutenberg, providerId: "79930"),
+ Story(id: seOtherProviderId, title: "SE Book", author: "Bram Stoker", genre: "Horror", excerpt: "S", paragraphs: [], coverImageName: "", heroImageName: "", isSaved: false, sourceProvider: .standardEbooks, providerId: "bram-stoker/dracula")
+ ]
+
+ let staleIDs = StoryStore.staleUnengagedExternalStoryIDs(
+ in: stories,
+ provider: .gutenberg,
+ liveStoryIDs: [liveId],
+ isAnnotatedProvider: { $0 == staleAnnotatedId }
+ )
+
+ XCTAssertEqual(staleIDs, [staleUnengagedId])
+ }
}