DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(reading): track EPUB text progress within chapters (#1673)
Bingxi Zhao (Frank)8ccca47bacfc
diff --git a/deeptutor/api/routers/reading.py b/deeptutor/api/routers/reading.pyindex d90df1436..2adb1e904 100644--- a/deeptutor/api/routers/reading.py+++ b/deeptutor/api/routers/reading.py@@ -321,10 +321,11 @@ class AnnotationInfo(BaseModel):class PositionPayload(BaseModel):locator: int = Field(ge=1)source_anchor: str = Field(default="", max_length=4096)- percentage: float = Field(default=0.0, ge=0.0, le=1.0)+ percentage: float | None = Field(default=None, ge=0.0, le=1.0)class PositionInfo(PositionPayload):+ percentage: float = 0.0updated_at: float = 0.0@@ -1417,7 +1418,11 @@ async def save_position(material_id: str, payload: PositionPayload) -> PositionIReadingPosition(locator=payload.locator,source_anchor=payload.source_anchor,- percentage=payload.percentage,+ percentage=(+ payload.percentage+ if payload.percentage is not None+ else store.position(material_id).percentage+ ),),)try:diff --git a/tests/reading/test_router.py b/tests/reading/test_router.pyindex 7f36e8baa..7e8966602 100644--- a/tests/reading/test_router.py+++ b/tests/reading/test_router.py@@ -362,6 +362,12 @@ def test_epub_contract_exposes_source_refs_original_and_position(client: TestCli)assert saved.status_code == 200assert client.get(base).json()["source_anchor"] == "epubcfi(/6/2)"+ # EPUB can save its CFI while text locations are still being generated.+ # Missing progress must preserve the last known value, not fabricate 0%.+ resumed = client.put(base, json={"locator": 1, "source_anchor": "epubcfi(/6/4)"})+ assert resumed.status_code == 200+ assert resumed.json()["percentage"] == 0.4+ assert resumed.json()["source_anchor"] == "epubcfi(/6/4)"assert client.put(base, json={"locator": 2, "percentage": 0}).status_code == 400diff --git a/web/components/reading/EpubDocumentView.tsx b/web/components/reading/EpubDocumentView.tsxindex e0f348b78..d933e75d4 100644--- a/web/components/reading/EpubDocumentView.tsx+++ b/web/components/reading/EpubDocumentView.tsx@@ -32,6 +32,7 @@ import { ReaderDisplayControls } from "./ReaderDisplayControls";type EpubLocation = {start?: { cfi?: string; href?: string; percentage?: number };+ atEnd?: boolean;};type EpubContents = {@@ -86,7 +87,10 @@ type EpubBook = {package?: { metadata?: { direction?: string } };load: (path: string) => Promise<unknown>;spine: { get: (target: string | number) => EpubSection | undefined };- locations?: { percentageFromCfi?: (cfi: string) => number };+ locations?: {+ percentageFromCfi?: (cfi: string) => number | null;+ generate?: (characters: number) => Promise<unknown>;+ };renderTo: (element: Element,options: Record<string, unknown>,@@ -148,6 +152,7 @@ export interface EpubDocumentViewProps {onSelection: (payload: SelectionPayload | null) => void;onAnnotationClick?: (annotation: AnnotationItem) => void;onVisibleLocatorChange?: (locator: number) => void;+ onProgressChange?: (percentage: number | null) => void;onHeadingsChange?: (headings: ReaderHeading[]) => void;headingJump?: {id: string;@@ -169,6 +174,7 @@ export function EpubDocumentView({onSelection,onAnnotationClick,onVisibleLocatorChange,+ onProgressChange,onHeadingsChange,headingJump,onError,@@ -183,6 +189,7 @@ export function EpubDocumentView({const refsRef = useRef(unitRefs);const annotationClickRef = useRef(onAnnotationClick);const visibleChangeRef = useRef(onVisibleLocatorChange);+ const progressChangeRef = useRef(onProgressChange);const headingsChangeRef = useRef(onHeadingsChange);const headingsByLocatorRef = useRef<Map<number, ReaderHeading[]>>(new Map());const errorRef = useRef(onError);@@ -243,6 +250,10 @@ export function EpubDocumentView({useEffect(() => {annotationClickRef.current = onAnnotationClick;}, [onAnnotationClick]);+ useEffect(() => {+ progressChangeRef.current = onProgressChange;+ }, [onProgressChange]);+useEffect(() => {visibleChangeRef.current = onVisibleLocatorChange;}, [onVisibleLocatorChange]);@@ -272,21 +283,18 @@ export function EpubDocumentView({let book: EpubBook | null = null;const onRelocated = (raw: unknown) => {+ if (cancelled) return;const location = raw as EpubLocation;const href = location.start?.href ?? "";const nextLocator = locatorForEpubHref(href, refsRef.current) || 1;const cfi = location.start?.cfi ?? "";- const percentage = Math.min(- 1,- Math.max(- 0,- Number(- location.start?.percentage ??- book?.locations?.percentageFromCfi?.(cfi) ??- (unitCount > 1 ? (nextLocator - 1) / (unitCount - 1) : 0),- ),- ),- );+ const observed = location.atEnd ? 1+ : book?.locations?.percentageFromCfi?.(cfi) ?? location.start?.percentage;+ const percentage = typeof observed === "number" && Number.isFinite(observed)+ ? Math.min(1, Math.max(0, observed)) : null;+ // A spine entry is a chapter, not a fraction of the whole text (#1673).+ // Until CFI locations are ready, publish uncertainty instead of 100%.+ progressChangeRef.current?.(percentage);locatorRef.current = nextLocator;visibleChangeRef.current?.(nextLocator);headingsChangeRef.current?.(@@ -297,7 +305,7 @@ export function EpubDocumentView({void saveReadingPosition(materialId, {locator: nextLocator,source_anchor: cfi,- percentage,+ ...(percentage === null ? {} : { percentage }),}).catch(() => {// Reading must continue when a background progress write fails.});@@ -455,7 +463,15 @@ export function EpubDocumentView({refsRef.current[0]?.source_href,);}- if (!cancelled) setLoading(false);+ if (cancelled) return;+ setLoading(false);+ void book.locations?.generate?.(1600).then(() => {+ if (cancelled || !rendition) return;+ const location = rendition.currentLocation();+ if (location) onRelocated(location);+ }).catch(() => {+ // CFI navigation still works when progress cannot be calculated.+ });} catch (error) {if (cancelled) return;const message =diff --git a/web/components/reading/ReaderPane.tsx b/web/components/reading/ReaderPane.tsxindex 71bed03e6..c57110751 100644--- a/web/components/reading/ReaderPane.tsx+++ b/web/components/reading/ReaderPane.tsx@@ -233,6 +233,12 @@ export function ReaderPane({const [autoJump, setAutoJump] = useState(true);const [exporting, setExporting] = useState(false);const [currentLocator, setCurrentLocator] = useState(1);+ const [epubPosition, setEpubPosition] = useState<{+ materialId: string; percentage: number | null;+ } | null>(null);+ const handleEpubProgress = useCallback((percentage: number | null) => {+ if (material) setEpubPosition({ materialId: material.material_id, percentage });+ }, [material]);const nonceRef = useRef(0);const headingLocatorRef = useRef(1);const jumpMaterialIdRef = useRef<string | null>(null);@@ -876,13 +882,9 @@ export function ReaderPane({const currentUnitTitle = isEpub? material?.unit_refs.find((row) => row.locator === currentLocator)?.title: undefined;- const epubProgress = material- ? Math.round(- material.unit_count > 1- ? ((currentLocator - 1) / (material.unit_count - 1)) * 100- : 100,- )- : 0;+ const epubProgress = epubPosition?.materialId === material?.material_id+ && epubPosition?.percentage != null+ ? Math.round(epubPosition.percentage * 100) : null;const bookmarkedHere = bookmarks.some((row) => row.locator === currentLocator,);@@ -1002,9 +1004,7 @@ export function ReaderPane({<span className="max-w-[180px] truncate">{currentUnitTitle || material.title}</span>- <span>- {` · ${Math.min(100, Math.max(0, epubProgress))}%`}- </span>+ {epubProgress !== null && <span>{` · ${epubProgress}%`}</span>}</>) : (t("{{unit}} {{n}} / {{total}}", {@@ -1202,6 +1202,7 @@ export function ReaderPane({setActiveAnnotationId(annotation.annotation_id)}onVisibleLocatorChange={handleVisibleLocator}+ onProgressChange={handleEpubProgress}onHeadingsChange={onHeadingsChange}headingJump={headingJump}onError={setError}diff --git a/web/lib/reading-api.ts b/web/lib/reading-api.tsindex 17fffcf13..b49e9ea68 100644--- a/web/lib/reading-api.ts+++ b/web/lib/reading-api.ts@@ -519,7 +519,7 @@ export async function getReadingPosition(export async function saveReadingPosition(materialId: string,- position: Pick<ReadingPosition, "locator" | "source_anchor" | "percentage">,+ position: Pick<ReadingPosition, "locator" | "source_anchor"> & Partial<Pick<ReadingPosition, "percentage">>,): Promise<ReadingPosition> {return parseReadingPosition(await unwrap(diff --git a/web/tests/epub-display-preferences.spec.tsx b/web/tests/epub-display-preferences.spec.tsxindex d109e9151..19b847ce7 100644--- a/web/tests/epub-display-preferences.spec.tsx+++ b/web/tests/epub-display-preferences.spec.tsx@@ -27,6 +27,10 @@ const fixture = vi.hoisted(() => {};return {rendition,+ locations: {+ generate: vi.fn(async () => []),+ percentageFromCfi: vi.fn((): number | null => null),+ },renderTo: vi.fn(() => rendition),apiFetch: vi.fn(async () => ({ok: true,@@ -41,6 +45,7 @@ vi.mock("epubjs", () => ({ready: Promise.resolve(),renderTo: fixture.renderTo,spine: { get: () => ({ href: "one.xhtml" }) },+ locations: fixture.locations,destroy: vi.fn(),}),}));@@ -58,6 +63,7 @@ let publisherParagraph: HTMLParagraphElement | null = null;let themeStyle: HTMLStyleElement | null = null;beforeEach(() => {+ fixture.locations.percentageFromCfi.mockReturnValue(null);fixture.rendition.currentLocation.mockReturnValue({start: { cfi: "epubcfi(/6/2)" },});@@ -232,3 +238,23 @@ it("drops a previous book's pending CFI before the next book relayout", async ()),).toHaveLength(oldCfiDisplays);});++it("reports CFI progress inside the final chapter, including one-chapter books (#1673)", async () => {+ const progress = vi.fn();+ const visible = vi.fn();+ render(<EpubDocumentView materialId="book" unitCount={1}+ unitRefs={[{ locator: 1, source_href: "one.xhtml", title: "Only chapter" }]}+ annotations={[]} jump={null} onSelection={() => undefined}+ onProgressChange={progress} onVisibleLocatorChange={visible} />);+ await waitFor(() => expect(fixture.locations.generate).toHaveBeenCalledWith(1600));+ const relocated = fixture.rendition.on.mock.calls.find(([event]) => event === "relocated")?.[1] as unknown as (location: unknown) => void;+ fixture.locations.percentageFromCfi.mockReturnValue(0.32);+ relocated({ start: { href: "one.xhtml", cfi: "epubcfi(/6/2)", percentage: 0.32 }, atEnd: false });+ expect(visible).toHaveBeenLastCalledWith(1);+ expect(progress).toHaveBeenLastCalledWith(0.32);+ fixture.locations.percentageFromCfi.mockReturnValue(null);+ relocated({ start: { href: "one.xhtml", cfi: "epubcfi(/6/2)" } });+ expect(progress).toHaveBeenLastCalledWith(null);+ relocated({ start: { href: "one.xhtml", cfi: "epubcfi(/6/2)" }, atEnd: true });+ expect(progress).toHaveBeenLastCalledWith(1);+});diff --git a/web/tests/reading-toolbar-selection.spec.tsx b/web/tests/reading-toolbar-selection.spec.tsxindex 4db82f7e5..2357b6a97 100644--- a/web/tests/reading-toolbar-selection.spec.tsx+++ b/web/tests/reading-toolbar-selection.spec.tsx@@ -46,6 +46,8 @@ const api = vi.hoisted(() => ({/** The document view is stubbed down to "report this selection upward". */const view = vi.hoisted(() => ({select: null as null | ((payload: unknown) => void),+ locate: null as null | ((locator: number) => void),+ progress: null as null | ((percentage: number | null) => void),}));vi.mock("@/lib/reading-api", async (importOriginal) => ({@@ -75,7 +77,14 @@ vi.mock("@/lib/auth", () => ({}));vi.mock("@/components/reading/EpubDocumentView", () => ({- EpubDocumentView: () => null,+ EpubDocumentView: ({ onVisibleLocatorChange, onProgressChange }: {+ onVisibleLocatorChange: (locator: number) => void;+ onProgressChange: (percentage: number | null) => void;+ }) => {+ view.locate = onVisibleLocatorChange;+ view.progress = onProgressChange;+ return <div data-testid="epub" />;+ },}));vi.mock("@/components/reading/TextUnitView", () => ({@@ -96,6 +105,7 @@ const material = {render_mode: "raw",has_raw_view: true,unit_count: 10,+ unit_refs: [{ locator: 1, title: "Opening" }, { locator: 2, title: "Final chapter" }],};vi.mock("@/context/ReadingContext", () => ({@@ -269,3 +279,24 @@ describe("reading toolbar with a live selection", () => {).not.toBeInTheDocument();});});++it("shows real EPUB progress inside the final chapter rather than declaring completion (#1673)", async () => {+ material.render_mode = "epub";+ material.unit_count = 2;+ try {+ render(<ReaderPane onClose={() => undefined} />);+ await waitFor(() => expect(view.locate).not.toBeNull());+ act(() => view.locate?.(2));+ expect(screen.getByText("Final chapter")).toBeVisible();+ expect(screen.queryByText("· 100%")).not.toBeInTheDocument();+ act(() => view.progress?.(0.62));+ expect(screen.getByText("· 62%")).toBeVisible();+ act(() => view.progress?.(0.73));+ expect(screen.getByText("· 73%")).toBeVisible();+ act(() => view.progress?.(1));+ expect(screen.getByText("· 100%")).toBeVisible();+ } finally {+ material.render_mode = "raw";+ material.unit_count = 10;+ }+});