Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

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.py
index 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.0
updated_at: float = 0.0
@@ -1417,7 +1418,11 @@ async def save_position(material_id: str, payload: PositionPayload) -> PositionI
ReadingPosition(
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.py
index 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 == 200
assert 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 == 400
diff --git a/web/components/reading/EpubDocumentView.tsx b/web/components/reading/EpubDocumentView.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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;
+ }
+});