cyreader 0.1.0

package/bundle/server/dist/library-static.js

@@ -0,0 +1,75 @@
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { serveStatic } from '@hono/node-server/serve-static';
+const CACHE_CONTROL = 'public, max-age=86400';
+let libraryDirectories = [];
+function buildEtag(stats) {
+    return `"${stats.size}-${Math.trunc(stats.mtimeMs)}"`;
+}
+function resolveStaticFilePath(requestPath, directoryId, root) {
+    let filename;
+    try {
+        filename = decodeURI(requestPath);
+        if (/(?:^|[/\\])\.{1,2}(?:$|[/\\])|[/\\]{2,}/.test(filename)) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    const relativePath = filename.replace(new RegExp(`^/static/${directoryId}`), '');
+    if (!relativePath) {
+        return null;
+    }
+    const filePath = path.join(root, relativePath);
+    let stats;
+    try {
+        stats = statSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    if (!stats.isFile()) {
+        return null;
+    }
+    return filePath;
+}
+function applyCacheHeaders(c, filePath) {
+    const stats = statSync(filePath);
+    c.header('Cache-Control', CACHE_CONTROL);
+    c.header('ETag', buildEtag(stats));
+    c.header('Last-Modified', stats.mtime.toUTCString());
+    if (path.extname(filePath).toLowerCase() === '.txt') {
+        c.header('Content-Type', 'text/plain; charset=utf-8');
+    }
+}
+export function refreshLibraryStaticRoutes(config) {
+    libraryDirectories = [...config.comicDirectories, ...config.novelDirectories];
+}
+export function mountLibraryStaticRoutes(app, config) {
+    refreshLibraryStaticRoutes(config);
+    app.use('/static/:directoryId/*', async (c, next) => {
+        const directoryId = c.req.param('directoryId');
+        const entry = libraryDirectories.find((directory) => directory.id === directoryId);
+        if (!entry) {
+            return c.notFound();
+        }
+        const filePath = resolveStaticFilePath(c.req.path, directoryId, entry.path);
+        if (!filePath) {
+            return next();
+        }
+        const stats = statSync(filePath);
+        const etag = buildEtag(stats);
+        const ifNoneMatch = c.req.header('If-None-Match');
+        if (ifNoneMatch === etag) {
+            applyCacheHeaders(c, filePath);
+            return c.body(null, 304);
+        }
+        applyCacheHeaders(c, filePath);
+        const handler = serveStatic({
+            root: entry.path,
+            rewriteRequestPath: (requestPath) => requestPath.replace(new RegExp(`^/static/${directoryId}`), ''),
+        });
+        return handler(c, next);
+    });
+}

package/bundle/server/dist/library-static.test.js

@@ -0,0 +1,81 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { Hono } from 'hono';
+import { mountLibraryStaticRoutes, refreshLibraryStaticRoutes } from './library-static.js';
+describe('library static routes', () => {
+    let tempDir;
+    let comicRoot;
+    let novelRoot;
+    let mangaDir;
+    let app;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(path.join(tmpdir(), 'cyreader-library-static-'));
+        comicRoot = path.join(tempDir, 'comics');
+        novelRoot = path.join(tempDir, 'novels');
+        mangaDir = path.join(comicRoot, 'manga');
+        await mkdir(mangaDir, { recursive: true });
+        await mkdir(novelRoot, { recursive: true });
+        await writeFile(path.join(mangaDir, '1.jpg'), 'page-one');
+        await writeFile(path.join(mangaDir, '2.jpg'), 'page-two');
+        await writeFile(path.join(novelRoot, 'book.txt'), 'chapter one\n\nchapter two');
+        app = new Hono();
+        mountLibraryStaticRoutes(app, {
+            novelDirectories: [{ id: 'novel-root', path: novelRoot }],
+            comicDirectories: [{ id: 'comic-root', path: comicRoot }],
+            gbkNovelHandling: 'ignore',
+        });
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('serves comic page via /static/{directoryId}/{title}/{filename}', async () => {
+        const res = await app.request('/static/comic-root/manga/1.jpg');
+        expect(res.status).toBe(200);
+        expect(await res.text()).toBe('page-one');
+        expect(res.headers.get('cache-control')).toBe('public, max-age=86400');
+        expect(res.headers.get('etag')).toMatch(/^"\d+-\d+"$/u);
+        expect(res.headers.get('last-modified')).toBeTruthy();
+    });
+    it('serves novel txt via /static/{directoryId}/{filename}', async () => {
+        const res = await app.request('/static/novel-root/book.txt');
+        expect(res.status).toBe(200);
+        expect(await res.text()).toBe('chapter one\n\nchapter two');
+        expect(res.headers.get('content-type')).toBe('text/plain; charset=utf-8');
+        expect(res.headers.get('cache-control')).toBe('public, max-age=86400');
+        expect(res.headers.get('etag')).toMatch(/^"\d+-\d+"$/u);
+    });
+    it('returns 304 when If-None-Match matches ETag', async () => {
+        const first = await app.request('/static/comic-root/manga/1.jpg');
+        const etag = first.headers.get('etag');
+        expect(etag).toBeTruthy();
+        const second = await app.request('/static/comic-root/manga/1.jpg', {
+            headers: { 'If-None-Match': etag },
+        });
+        expect(second.status).toBe(304);
+        expect(second.headers.get('cache-control')).toBe('public, max-age=86400');
+        expect(second.headers.get('etag')).toBe(etag);
+        expect(await second.text()).toBe('');
+    });
+    it('returns 404 for unknown static path', async () => {
+        const res = await app.request('/static/comic-root/manga/missing.jpg');
+        expect(res.status).toBe(404);
+    });
+    it('refreshes static routes after config change', async () => {
+        const newRoot = path.join(tempDir, 'comics-new');
+        const newMangaDir = path.join(newRoot, 'series');
+        await mkdir(newMangaDir, { recursive: true });
+        await writeFile(path.join(newMangaDir, 'cover.png'), 'new-cover');
+        refreshLibraryStaticRoutes({
+            novelDirectories: [{ id: 'novel-root', path: novelRoot }],
+            comicDirectories: [{ id: 'new-root', path: newRoot }],
+            gbkNovelHandling: 'ignore',
+        });
+        const oldRes = await app.request('/static/comic-root/manga/1.jpg');
+        expect(oldRes.status).toBe(404);
+        const newRes = await app.request('/static/new-root/series/cover.png');
+        expect(newRes.status).toBe(200);
+        expect(await newRes.text()).toBe('new-cover');
+    });
+});

package/bundle/server/dist/listen-config.js

@@ -0,0 +1,23 @@
+export const DEFAULT_PORT = 4613;
+export function getListenPort() {
+    const raw = process.env.CYREADER_PORT;
+    if (raw === undefined || raw === '') {
+        return DEFAULT_PORT;
+    }
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid CYREADER_PORT: ${raw}`);
+    }
+    return port;
+}
+export function getListenHostname() {
+    const hostname = process.env.CYREADER_HOST;
+    if (hostname === undefined || hostname === '') {
+        return undefined;
+    }
+    return hostname;
+}
+export function formatListenUrl(port, hostname) {
+    const host = hostname ?? 'localhost';
+    return `http://${host}:${port}`;
+}

package/bundle/server/dist/listen-config.test.js

@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { DEFAULT_PORT, formatListenUrl, getListenHostname, getListenPort, } from './listen-config.js';
+describe('listen config', () => {
+    let previousPort;
+    let previousHost;
+    beforeEach(() => {
+        previousPort = process.env.CYREADER_PORT;
+        previousHost = process.env.CYREADER_HOST;
+    });
+    afterEach(() => {
+        if (previousPort === undefined) {
+            delete process.env.CYREADER_PORT;
+        }
+        else {
+            process.env.CYREADER_PORT = previousPort;
+        }
+        if (previousHost === undefined) {
+            delete process.env.CYREADER_HOST;
+        }
+        else {
+            process.env.CYREADER_HOST = previousHost;
+        }
+    });
+    it('uses the default port when CYREADER_PORT is unset', () => {
+        delete process.env.CYREADER_PORT;
+        expect(getListenPort()).toBe(DEFAULT_PORT);
+    });
+    it('reads CYREADER_PORT from the environment', () => {
+        process.env.CYREADER_PORT = '8080';
+        expect(getListenPort()).toBe(8080);
+    });
+    it('rejects invalid CYREADER_PORT values', () => {
+        process.env.CYREADER_PORT = '0';
+        expect(() => getListenPort()).toThrow(/Invalid CYREADER_PORT/);
+    });
+    it('returns undefined hostname when CYREADER_HOST is unset', () => {
+        delete process.env.CYREADER_HOST;
+        expect(getListenHostname()).toBeUndefined();
+    });
+    it('reads CYREADER_HOST from the environment', () => {
+        process.env.CYREADER_HOST = '0.0.0.0';
+        expect(getListenHostname()).toBe('0.0.0.0');
+    });
+    it('formats the listen URL with localhost when hostname is unset', () => {
+        expect(formatListenUrl(4613)).toBe('http://localhost:4613');
+    });
+    it('formats the listen URL with the configured hostname', () => {
+        expect(formatListenUrl(8080, '0.0.0.0')).toBe('http://0.0.0.0:8080');
+    });
+});

package/bundle/server/dist/reading/progress/merge.js

@@ -0,0 +1,32 @@
+function novelProgress(entry) {
+    return entry?.type === 'novel' ? entry : null;
+}
+function comicProgress(entry) {
+    return entry?.type === 'comic' ? entry : null;
+}
+export function attachProgressToListItem(item, progressMap) {
+    const entry = progressMap[item.id] ?? null;
+    if (item.type === 'novel') {
+        return {
+            ...item,
+            progress: novelProgress(entry),
+        };
+    }
+    return {
+        ...item,
+        progress: comicProgress(entry),
+    };
+}
+export function attachProgressToDetail(detail, progressMap) {
+    const entry = progressMap[detail.id] ?? null;
+    if (detail.type === 'novel') {
+        return {
+            ...detail,
+            progress: novelProgress(entry),
+        };
+    }
+    return {
+        ...detail,
+        progress: comicProgress(entry),
+    };
+}

package/bundle/server/dist/reading/progress/schema.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+const comicProgressSchema = z.object({
+    type: z.literal('comic'),
+    pageIndex: z.number().int().min(0),
+    updatedAt: z.string().datetime(),
+    completedAt: z.string().datetime().nullable().optional(),
+});
+const novelProgressSchema = z.object({
+    type: z.literal('novel'),
+    paragraphIndex: z.number().int().min(0),
+    updatedAt: z.string().datetime(),
+    anchor: z.string().optional(),
+    layout: z
+        .object({
+        paragraphCount: z.number().int().min(0),
+        charCount: z.number().int().min(0),
+    })
+        .optional(),
+    completedAt: z.string().datetime().nullable().optional(),
+});
+export const progressEntrySchema = z.discriminatedUnion('type', [
+    comicProgressSchema,
+    novelProgressSchema,
+]);
+const progressStoreSchema = z.object({
+    items: z.record(z.string(), progressEntrySchema),
+});
+export const comicProgressInputSchema = z.object({
+    type: z.literal('comic'),
+    pageIndex: z.number().int().min(0),
+    completedAt: z.string().datetime().nullable().optional(),
+});
+export const novelProgressInputSchema = z.object({
+    type: z.literal('novel'),
+    paragraphIndex: z.number().int().min(0),
+    anchor: z.string().optional(),
+    layout: z
+        .object({
+        paragraphCount: z.number().int().min(0),
+        charCount: z.number().int().min(0),
+    })
+        .optional(),
+    completedAt: z.string().datetime().nullable().optional(),
+});
+export const progressInputSchema = z.discriminatedUnion('type', [
+    comicProgressInputSchema,
+    novelProgressInputSchema,
+]);
+export function createEmptyProgressStore() {
+    return { items: {} };
+}
+export function parseProgressStore(data) {
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return createEmptyProgressStore();
+    }
+    const record = data;
+    const rawItems = record.items;
+    if (rawItems === undefined) {
+        return createEmptyProgressStore();
+    }
+    const parsed = progressStoreSchema.safeParse({ items: rawItems });
+    if (!parsed.success) {
+        return createEmptyProgressStore();
+    }
+    return parsed.data;
+}

package/bundle/server/dist/reading/progress/schema.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { parseProgressStore, progressInputSchema } from './schema.js';
+describe('progress schema', () => {
+    it('parses comic and novel entries', () => {
+        const store = parseProgressStore({
+            items: {
+                comic1: {
+                    type: 'comic',
+                    pageIndex: 2,
+                    updatedAt: '2026-01-01T00:00:00.000Z',
+                },
+                novel1: {
+                    type: 'novel',
+                    paragraphIndex: 10,
+                    updatedAt: '2026-01-01T00:00:00.000Z',
+                    anchor: 'chapter',
+                    layout: { paragraphCount: 100, charCount: 5000 },
+                },
+            },
+        });
+        expect(store.items.comic1?.type).toBe('comic');
+        expect(store.items.novel1?.type === 'novel' ? store.items.novel1.paragraphIndex : null).toBe(10);
+    });
+    it('treats missing items as an empty store', () => {
+        expect(parseProgressStore({})).toEqual({ items: {} });
+        expect(parseProgressStore(null)).toEqual({ items: {} });
+    });
+    it('validates progress input', () => {
+        expect(progressInputSchema.safeParse({
+            type: 'comic',
+            pageIndex: 0,
+            completedAt: null,
+        }).success).toBe(true);
+        expect(progressInputSchema.safeParse({
+            type: 'novel',
+            paragraphIndex: 3,
+        }).success).toBe(true);
+    });
+});

package/bundle/server/dist/reading/progress/service.js

@@ -0,0 +1,81 @@
+import { NotFoundError } from '../../library/errors.js';
+import { ensureProgressStore, readProgressStoreFromDisk, writeProgressStore } from './storage.js';
+export class ProgressService {
+    libraryService;
+    constructor(libraryService) {
+        this.libraryService = libraryService;
+    }
+    static async create(libraryService) {
+        await ensureProgressStore();
+        return new ProgressService(libraryService);
+    }
+    async getProgressMap() {
+        const store = await this.pruneStaleEntries();
+        return store.items;
+    }
+    getProgressFromMap(progressMap, itemId) {
+        return progressMap[itemId] ?? null;
+    }
+    async getProgress(itemId) {
+        const progressMap = await this.getProgressMap();
+        return this.getProgressFromMap(progressMap, itemId);
+    }
+    async saveProgress(itemId, input) {
+        const listItem = this.libraryService.getListItem(itemId);
+        if (!listItem) {
+            throw new NotFoundError('Item not found');
+        }
+        if (listItem.type !== input.type) {
+            throw new TypeError('Progress type does not match library item type');
+        }
+        const entry = this.buildEntry(itemId, input);
+        const store = await readProgressStoreFromDisk();
+        store.items[itemId] = entry;
+        await writeProgressStore(store);
+        return entry;
+    }
+    async pruneStaleEntries() {
+        const store = await readProgressStoreFromDisk();
+        const keptItems = {};
+        let hasStale = false;
+        for (const [itemId, entry] of Object.entries(store.items)) {
+            const listItem = this.libraryService.getListItem(itemId);
+            if (!listItem || listItem.type !== entry.type) {
+                hasStale = true;
+                continue;
+            }
+            keptItems[itemId] = entry;
+        }
+        if (hasStale) {
+            await writeProgressStore({ items: keptItems });
+            return { items: keptItems };
+        }
+        return store;
+    }
+    buildEntry(itemId, input) {
+        const updatedAt = new Date().toISOString();
+        if (input.type === 'comic') {
+            const detail = this.libraryService.getItemDetail(itemId);
+            if (detail.type !== 'comic') {
+                throw new TypeError('Progress type does not match library item type');
+            }
+            const pageCount = detail.pages.length;
+            const pageIndex = pageCount === 0 ? 0 : Math.min(input.pageIndex, pageCount - 1);
+            return {
+                type: 'comic',
+                pageIndex,
+                updatedAt,
+                ...(input.completedAt !== undefined ? { completedAt: input.completedAt } : {}),
+            };
+        }
+        const paragraphIndex = Math.max(0, input.paragraphIndex);
+        return {
+            type: 'novel',
+            paragraphIndex,
+            updatedAt,
+            ...(input.anchor !== undefined ? { anchor: input.anchor } : {}),
+            ...(input.layout !== undefined ? { layout: input.layout } : {}),
+            ...(input.completedAt !== undefined ? { completedAt: input.completedAt } : {}),
+        };
+    }
+}

package/bundle/server/dist/reading/progress/service.test.js

@@ -0,0 +1,104 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { NotFoundError } from '../../library/errors.js';
+import { LibraryService } from '../../library/service.js';
+import { ProgressService } from './service.js';
+import { readProgressStoreFromDisk } from './storage.js';
+describe('ProgressService', () => {
+    let tempDir;
+    let previousConfigDir;
+    let novelRoot;
+    let comicRoot;
+    let mangaDir;
+    let libraryService;
+    let progressService;
+    let novelId;
+    let comicId;
+    beforeEach(async () => {
+        previousConfigDir = process.env.CYREADER_CONFIG_DIR;
+        tempDir = await mkdtemp(path.join(tmpdir(), 'cyreader-progress-service-'));
+        process.env.CYREADER_CONFIG_DIR = tempDir;
+        novelRoot = path.join(tempDir, 'novels');
+        comicRoot = path.join(tempDir, 'comics');
+        mangaDir = path.join(comicRoot, 'manga');
+        await mkdir(novelRoot);
+        await mkdir(mangaDir, { recursive: true });
+        await writeFile(path.join(novelRoot, 'book.txt'), 'line one\n\nline two');
+        await writeFile(path.join(mangaDir, '1.jpg'), '');
+        await writeFile(path.join(mangaDir, '2.jpg'), '');
+        await writeFile(path.join(mangaDir, '3.jpg'), '');
+        libraryService = new LibraryService(() => ({
+            novelDirectories: [{ id: 'novel-root', path: novelRoot }],
+            comicDirectories: [{ id: 'comic-root', path: comicRoot }],
+            gbkNovelHandling: 'ignore',
+        }));
+        await libraryService.scan();
+        progressService = await ProgressService.create(libraryService);
+        const items = libraryService.getState().items;
+        novelId = items.find((item) => item.type === 'novel').id;
+        comicId = items.find((item) => item.type === 'comic').id;
+    });
+    afterEach(async () => {
+        if (previousConfigDir === undefined) {
+            delete process.env.CYREADER_CONFIG_DIR;
+        }
+        else {
+            process.env.CYREADER_CONFIG_DIR = previousConfigDir;
+        }
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('saves and reads comic progress with clamped page index', async () => {
+        const entry = await progressService.saveProgress(comicId, {
+            type: 'comic',
+            pageIndex: 99,
+        });
+        expect(entry).toEqual({
+            type: 'comic',
+            pageIndex: 2,
+            updatedAt: expect.any(String),
+        });
+        const map = await progressService.getProgressMap();
+        const comicProgress = map[comicId];
+        expect(comicProgress?.type).toBe('comic');
+        if (comicProgress?.type === 'comic') {
+            expect(comicProgress.pageIndex).toBe(2);
+        }
+    });
+    it('saves novel progress', async () => {
+        const entry = await progressService.saveProgress(novelId, {
+            type: 'novel',
+            paragraphIndex: 4,
+            anchor: 'line one',
+            layout: { paragraphCount: 2, charCount: 20 },
+        });
+        expect(entry.type).toBe('novel');
+        if (entry.type === 'novel') {
+            expect(entry.paragraphIndex).toBe(4);
+            expect(entry.anchor).toBe('line one');
+        }
+    });
+    it('throws for unknown item', async () => {
+        await expect(progressService.saveProgress('missing', { type: 'novel', paragraphIndex: 0 })).rejects.toBeInstanceOf(NotFoundError);
+    });
+    it('throws when progress type mismatches item type', async () => {
+        await expect(progressService.saveProgress(novelId, { type: 'comic', pageIndex: 0 })).rejects.toBeInstanceOf(TypeError);
+    });
+    it('prunes stale progress entries', async () => {
+        await progressService.saveProgress(novelId, { type: 'novel', paragraphIndex: 1 });
+        const store = await readProgressStoreFromDisk();
+        store.items.stale = {
+            type: 'novel',
+            paragraphIndex: 0,
+            updatedAt: new Date().toISOString(),
+        };
+        await import('./storage.js').then(({ writeProgressStore }) => writeProgressStore(store));
+        const map = await progressService.getProgressMap();
+        expect(map.stale).toBeUndefined();
+        const novelProgress = map[novelId];
+        if (novelProgress?.type === 'novel') {
+            expect(novelProgress.paragraphIndex).toBe(1);
+        }
+    });
+});

package/bundle/server/dist/reading/progress/storage.js

@@ -0,0 +1,44 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { getConfigDir, getProgressFilePath } from '../../config/paths.js';
+import { createEmptyProgressStore, parseProgressStore } from './schema.js';
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function writeProgressStore(store) {
+    const configDir = getConfigDir();
+    const progressFile = getProgressFilePath();
+    const normalized = parseProgressStore(store);
+    await mkdir(configDir, { recursive: true });
+    await writeFile(progressFile, `${JSON.stringify(normalized, null, 2)}\n`, 'utf-8');
+}
+export async function readProgressStoreFromDisk() {
+    const progressFile = getProgressFilePath();
+    const content = await readFile(progressFile, 'utf-8');
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse progress file: ${progressFile}`, { cause: error });
+    }
+    return parseProgressStore(data);
+}
+export async function ensureProgressStore() {
+    const configDir = getConfigDir();
+    const progressFile = getProgressFilePath();
+    await mkdir(configDir, { recursive: true });
+    if (!(await fileExists(progressFile))) {
+        const empty = createEmptyProgressStore();
+        await writeProgressStore(empty);
+        return empty;
+    }
+    const store = await readProgressStoreFromDisk();
+    await writeProgressStore(store);
+    return store;
+}

package/bundle/server/dist/reading/recent/schema.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const MAX_RECENT = 7;
+const recentEntrySchema = z.object({
+    itemId: z.string().min(1),
+    type: z.enum(['novel', 'comic']),
+    openedAt: z.string().datetime(),
+});
+const recentStoreSchema = z.object({
+    recent: z.array(recentEntrySchema),
+});
+export function createEmptyRecentStore() {
+    return { recent: [] };
+}
+export function parseRecentStore(data) {
+    return recentStoreSchema.parse(data);
+}

package/bundle/server/dist/reading/recent/service.js

@@ -0,0 +1,54 @@
+import { NotFoundError } from '../../library/errors.js';
+import { MAX_RECENT } from './schema.js';
+import { ensureRecentStore, readRecentStoreFromDisk, writeRecentStore } from './storage.js';
+export class RecentService {
+    libraryService;
+    constructor(libraryService) {
+        this.libraryService = libraryService;
+    }
+    static async create(libraryService) {
+        await ensureRecentStore();
+        return new RecentService(libraryService);
+    }
+    async recordOpen(itemId) {
+        const listItem = this.libraryService.getListItem(itemId);
+        if (!listItem) {
+            throw new NotFoundError('Item not found');
+        }
+        const store = await readRecentStoreFromDisk();
+        const filtered = store.recent.filter((entry) => entry.itemId !== itemId);
+        const updated = {
+            recent: [
+                {
+                    itemId,
+                    type: listItem.type,
+                    openedAt: new Date().toISOString(),
+                },
+                ...filtered,
+            ].slice(0, MAX_RECENT),
+        };
+        await writeRecentStore(updated);
+    }
+    async getRecentItems(progressMap = {}) {
+        const store = await readRecentStoreFromDisk();
+        const items = [];
+        const keptEntries = [];
+        let hasStale = false;
+        for (const entry of store.recent) {
+            const listItem = this.libraryService.getListItem(entry.itemId, progressMap);
+            if (!listItem) {
+                hasStale = true;
+                continue;
+            }
+            keptEntries.push(entry);
+            items.push({
+                ...listItem,
+                openedAt: entry.openedAt,
+            });
+        }
+        if (hasStale) {
+            await writeRecentStore({ recent: keptEntries });
+        }
+        return items;
+    }
+}