@khorsheed/dsh-reader 0.3.0 → 0.3.1

package/lib/types/polish.d.ts

@@ -0,0 +1,41 @@
+import type { ReaderPolishView } from './types.ts';
+/**
+ * What a layer belongs to: the paragraphs' text without their time and
+ * speaker prefixes, hashed.
+ */
+export declare function sourceKey(paragraphs: readonly string[]): string;
+/**
+ * Parse the model's write-back: lines `¶12：译文…` (a line without a ¶
+ * continues the paragraph before it).
+ *
+ * @param text - what the model sent.
+ */
+export declare function parsePolish(text: string): Map<number, string>;
+/** The per-article 润色 layers. */
+export declare class ReaderPolishStore {
+    private readonly dir;
+    private readonly memory;
+    constructor(stateRoot: string);
+    private fileOf;
+    private load;
+    private save;
+    /**
+     * An article's layer, when it belongs to the text now captured.
+     *
+     * @param entryId - the article.
+     * @param key - the current text's {@link sourceKey}.
+     */
+    view(entryId: string, key: string | undefined): ReaderPolishView | undefined;
+    /**
+     * Merge the model's translations into the layer (a different text starts a
+     * fresh one).
+     *
+     * @returns the layer after the write.
+     */
+    write(entryId: string, key: string, total: number, updates: ReadonlyMap<number, string>): ReaderPolishView;
+    /** Turn one paragraph back to (or away from) the machine translation. */
+    setOff(entryId: string, key: string | undefined, paragraph: number, off: boolean): ReaderPolishView | undefined;
+    /** Forget an article's layer. */
+    drop(entryId: string): void;
+}
+//# sourceMappingURL=polish.d.ts.map

package/lib/types/polish.js

@@ -0,0 +1,136 @@
+/**
+ * The 润色 layer: an agent's paragraph-by-paragraph translation of an
+ * article, written back through `reader_translate` and shown in place of the
+ * browser's sentence-by-sentence machine translation.
+ *
+ * Keyed to the article's text as the model read it (the snapshot): a
+ * re-transcription changes the text and so drops the layer; renaming a
+ * speaker only changes the "[mm:ss] 名字：" prefixes and keeps it.
+ *
+ * One JSON file per article under `<state>/polish/`, memory-only when the
+ * state root cannot be written.
+ *
+ * @module @khorsheed/dsh-reader/polish
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The time / speaker prefix of a transcript paragraph in the snapshot. */
+const PREFIX = /^\[\d+(?::\d+){1,2}\]\s*(?:[^：\n]{1,40}：)?/;
+/**
+ * What a layer belongs to: the paragraphs' text without their time and
+ * speaker prefixes, hashed.
+ */
+export function sourceKey(paragraphs) {
+    const hash = createHash('sha1');
+    hash.update(String(paragraphs.length));
+    for (const paragraph of paragraphs)
+        hash.update(`\n${paragraph.replace(PREFIX, '')}`);
+    return hash.digest('hex').slice(0, 24);
+}
+/**
+ * Parse the model's write-back: lines `¶12：译文…` (a line without a ¶
+ * continues the paragraph before it).
+ *
+ * @param text - what the model sent.
+ */
+export function parsePolish(text) {
+    const out = new Map();
+    let current;
+    for (const line of text.split(/\r?\n/)) {
+        const head = /^\s*¶\s*(\d+)\s*[：:]\s*(.*)$/.exec(line);
+        if (head !== null) {
+            current = Number(head[1]);
+            out.set(current, head[2].trim());
+        }
+        else if (current !== undefined && line.trim() !== '') {
+            out.set(current, `${out.get(current) ?? ''}${line.trim()}`);
+        }
+    }
+    for (const [key, value] of out)
+        if (value === '')
+            out.delete(key);
+    return out;
+}
+/** The per-article 润色 layers. */
+export class ReaderPolishStore {
+    dir;
+    memory = new Map();
+    constructor(stateRoot) {
+        this.dir = join(stateRoot, 'polish');
+    }
+    fileOf(entryId) {
+        return join(this.dir, `${createHash('sha1').update(entryId).digest('hex').slice(0, 32)}.json`);
+    }
+    load(entryId) {
+        const cached = this.memory.get(entryId);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const parsed = JSON.parse(readFileSync(this.fileOf(entryId), 'utf8'));
+            if (parsed.entryId !== entryId)
+                return undefined;
+            this.memory.set(entryId, parsed);
+            return parsed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    save(file) {
+        this.memory.set(file.entryId, file);
+        try {
+            mkdirSync(this.dir, { recursive: true });
+            const target = this.fileOf(file.entryId);
+            writeFileSync(`${target}.tmp`, JSON.stringify(file));
+            renameSync(`${target}.tmp`, target);
+        }
+        catch {
+            // Memory-only: the layer lasts this process.
+        }
+    }
+    /**
+     * An article's layer, when it belongs to the text now captured.
+     *
+     * @param entryId - the article.
+     * @param key - the current text's {@link sourceKey}.
+     */
+    view(entryId, key) {
+        const file = this.load(entryId);
+        if (file === undefined || key === undefined || file.sourceKey !== key)
+            return undefined;
+        const done = Object.keys(file.paragraphs).length;
+        return { total: file.total, done, paragraphs: { ...file.paragraphs }, off: [...file.off], updatedAt: file.updatedAt, complete: done >= file.total };
+    }
+    /**
+     * Merge the model's translations into the layer (a different text starts a
+     * fresh one).
+     *
+     * @returns the layer after the write.
+     */
+    write(entryId, key, total, updates) {
+        const before = this.load(entryId);
+        const fresh = before === undefined || before.sourceKey !== key;
+        const paragraphs = fresh ? {} : { ...before.paragraphs };
+        for (const [index, value] of updates)
+            if (index >= 1 && index <= total)
+                paragraphs[String(index)] = value;
+        const file = { entryId, sourceKey: key, total, paragraphs, off: fresh ? [] : before.off, updatedAt: new Date().toISOString() };
+        this.save(file);
+        return this.view(entryId, key);
+    }
+    /** Turn one paragraph back to (or away from) the machine translation. */
+    setOff(entryId, key, paragraph, off) {
+        const file = this.load(entryId);
+        if (file === undefined || key === undefined || file.sourceKey !== key)
+            return undefined;
+        const rest = file.off.filter(item => item !== paragraph);
+        this.save({ ...file, off: off ? [...rest, paragraph] : rest });
+        return this.view(entryId, key);
+    }
+    /** Forget an article's layer. */
+    drop(entryId) {
+        this.memory.delete(entryId);
+        rmSync(this.fileOf(entryId), { force: true });
+    }
+}

package/lib/types/remote.d.ts

@@ -11,6 +11,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { LocalTranscriptStatus, MediaCardStates, ReaderEntryIdentity, ReaderPolishView, ReaderEntryNotes, ReaderMedia, ReaderNote, ReaderNoteInput, ReaderNoteOutcome } from './types.ts';
 import type { ReaderAddFailure, ReaderAddOutcome, ReaderAddRefusal, ReaderAnnotationOutcome, ReaderBackfillCandidate, ReaderEntryBodyView, ReaderImageResult, ReaderEntryFetchState, ReaderBody, ReaderCapabilities, ReaderEntryTranslationView, ReaderMutationOutcome, ReaderRecentEntry, ReaderRefreshResult, ReaderSentenceLearn, ReaderSourceSummary, ReaderStorageStats, ReaderTag } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -26,6 +27,8 @@ export declare class ReaderRemoteService extends TypertRemoteService<ReaderRemot
     constructor(ctx: Context, _config?: ReaderRemoteConfig);
     /** The service core this face delegates to. */
     private get core();
+    /** The notes store this face delegates to. */
+    private get notes();
     /** Capability handshake: what the browser may rely on in this composition. */
     capabilities(): Promise<ReaderCapabilities>;
     /** The configured sources, without payloads. */
@@ -227,6 +230,121 @@ export declare class ReaderRemoteService extends TypertRemoteService<ReaderRemot
         label: string;
         text: string;
     }): Promise<'ok' | 'unavailable'>;
+    /** One article's notes and the conversations that discussed it. */
+    entryNotes(request: {
+        entryId: string;
+    }): Promise<{
+        entry?: ReaderEntryNotes;
+    }>;
+    /** How many notes each article carries. */
+    noteCounts(): Promise<{
+        counts: Record<string, number>;
+    }>;
+    /** Keep one excerpt (and its comment). */
+    addNote(request: ReaderNoteInput): Promise<ReaderNote | 'empty' | 'full'>;
+    /** Change or clear one note's comment. */
+    updateNote(request: {
+        entryId: string;
+        noteId: string;
+        comment: string;
+    }): Promise<ReaderNoteOutcome>;
+    /** Delete one note. */
+    deleteNote(request: {
+        entryId: string;
+        noteId: string;
+    }): Promise<ReaderNoteOutcome>;
+    /** Remember that a conversation discussed this article. */
+    recordDiscussion(request: ReaderEntryIdentity & {
+        sessionId: string;
+        sessionTitle?: string;
+    }): Promise<'ok' | 'empty'>;
+    /** Add the reader's own line under a note. */
+    addReply(request: {
+        entryId: string;
+        noteId: string;
+        text: string;
+    }): Promise<ReaderNoteOutcome>;
+    /** Rewrite (or, with empty text, remove) one line under a note. */
+    editReply(request: {
+        entryId: string;
+        noteId: string;
+        index: number;
+        text: string;
+    }): Promise<ReaderNoteOutcome>;
+    /** Remember that a note or a discussion note became a canvas card. */
+    markSynced(request: {
+        entryId: string;
+        noteId?: string;
+        discussionId?: string;
+        canvasId: string;
+        cardId: string;
+        canvasTitle: string;
+    }): Promise<ReaderNoteOutcome>;
+    /** Delete one discussion note. */
+    deleteDiscussion(request: {
+        entryId: string;
+        discussionId: string;
+    }): Promise<ReaderNoteOutcome>;
+    /** A video entry's transcript from its platform captions (stored; `none` when it has none). */
+    mediaTranscript(request: {
+        entryId: string;
+        url: string;
+    }): Promise<{
+        entryId: string;
+        html?: string;
+        captions: 'platform' | 'none' | 'failed';
+        language?: string;
+        error?: string;
+    }>;
+    /**
+     * Start (or rejoin) local transcription of an entry without captions.
+     * Answers `unavailable` without the transcription plugin and `needs-models`
+     * until the first model download is confirmed.
+     */
+    startLocalTranscript(request: {
+        entryId: string;
+        url: string;
+        media: ReaderMedia;
+        title?: string;
+        confirmModels?: boolean;
+    }): Promise<LocalTranscriptStatus>;
+    /** Where an entry's local transcription stands, with the transcript so far. */
+    localTranscript(request: {
+        entryId: string;
+    }): Promise<LocalTranscriptStatus>;
+    /** The reader's names for a transcript's speakers, by index. */
+    speakerNames(request: {
+        entryId: string;
+    }): Promise<Record<string, string>>;
+    /** Name one speaker of a transcript (empty: back to 说话人 A…); answers all the names. */
+    nameSpeaker(request: {
+        entryId: string;
+        speaker: number;
+        name: string;
+    }): Promise<Record<string, string>>;
+    /** The wall's video / audio cards: what each one's transcript is (captions, local, transcribing…). */
+    mediaStates(request: {
+        entryIds: string[];
+    }): Promise<MediaCardStates>;
+    /** Leave (withdraws a queued job) or, with `force`, stop an entry's local transcription. */
+    cancelLocalTranscript(request: {
+        entryId: string;
+        force: boolean;
+    }): Promise<LocalTranscriptStatus>;
+    /** The article's 润色 layer (the agent's translation), when there is one for its current text. */
+    polish(request: {
+        entryId: string;
+    }): Promise<ReaderPolishView | null>;
+    /** Show one paragraph's machine translation instead of the 润色 (or back). */
+    setPolishOff(request: {
+        entryId: string;
+        paragraph: number;
+        off: boolean;
+    }): Promise<ReaderPolishView | null>;
+    /** Hand the host the article's original text, block by block, for the model to read. */
+    snapshotEntry(request: ReaderEntryIdentity & {
+        paragraphs: string[];
+    }): Promise<'ok' | 'empty'>;
 }
 export default ReaderRemoteService;
 //# sourceMappingURL=remote.d.ts.map

package/lib/types/remote.js

@@ -69,6 +69,26 @@ let ReaderRemoteService = (() => {
     let _listRecent_decorators;
     let _clearRecent_decorators;
     let _quoteToSideChat_decorators;
+    let _entryNotes_decorators;
+    let _noteCounts_decorators;
+    let _addNote_decorators;
+    let _updateNote_decorators;
+    let _deleteNote_decorators;
+    let _recordDiscussion_decorators;
+    let _addReply_decorators;
+    let _editReply_decorators;
+    let _markSynced_decorators;
+    let _deleteDiscussion_decorators;
+    let _mediaTranscript_decorators;
+    let _startLocalTranscript_decorators;
+    let _localTranscript_decorators;
+    let _speakerNames_decorators;
+    let _nameSpeaker_decorators;
+    let _mediaStates_decorators;
+    let _cancelLocalTranscript_decorators;
+    let _polish_decorators;
+    let _setPolishOff_decorators;
+    let _snapshotEntry_decorators;
     return class ReaderRemoteService extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -104,6 +124,26 @@ let ReaderRemoteService = (() => {
             _listRecent_decorators = [Remote('listRecent')];
             _clearRecent_decorators = [Remote('clearRecent')];
             _quoteToSideChat_decorators = [Remote('quoteToSideChat')];
+            _entryNotes_decorators = [Remote('entryNotes')];
+            _noteCounts_decorators = [Remote('noteCounts')];
+            _addNote_decorators = [Remote('addNote')];
+            _updateNote_decorators = [Remote('updateNote')];
+            _deleteNote_decorators = [Remote('deleteNote')];
+            _recordDiscussion_decorators = [Remote('recordDiscussion')];
+            _addReply_decorators = [Remote('addReply')];
+            _editReply_decorators = [Remote('editReply')];
+            _markSynced_decorators = [Remote('markSynced')];
+            _deleteDiscussion_decorators = [Remote('deleteDiscussion')];
+            _mediaTranscript_decorators = [Remote('mediaTranscript')];
+            _startLocalTranscript_decorators = [Remote('startLocalTranscript')];
+            _localTranscript_decorators = [Remote('localTranscript')];
+            _speakerNames_decorators = [Remote('speakerNames')];
+            _nameSpeaker_decorators = [Remote('nameSpeaker')];
+            _mediaStates_decorators = [Remote('mediaStates')];
+            _cancelLocalTranscript_decorators = [Remote('cancelLocalTranscript')];
+            _polish_decorators = [Remote('polish')];
+            _setPolishOff_decorators = [Remote('setPolishOff')];
+            _snapshotEntry_decorators = [Remote('snapshotEntry')];
             __esDecorate(this, null, _capabilities_decorators, { kind: "method", name: "capabilities", static: false, private: false, access: { has: obj => "capabilities" in obj, get: obj => obj.capabilities }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _listSources_decorators, { kind: "method", name: "listSources", static: false, private: false, access: { has: obj => "listSources" in obj, get: obj => obj.listSources }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _addSource_decorators, { kind: "method", name: "addSource", static: false, private: false, access: { has: obj => "addSource" in obj, get: obj => obj.addSource }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -136,9 +176,29 @@ let ReaderRemoteService = (() => {
             __esDecorate(this, null, _listRecent_decorators, { kind: "method", name: "listRecent", static: false, private: false, access: { has: obj => "listRecent" in obj, get: obj => obj.listRecent }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _clearRecent_decorators, { kind: "method", name: "clearRecent", static: false, private: false, access: { has: obj => "clearRecent" in obj, get: obj => obj.clearRecent }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _quoteToSideChat_decorators, { kind: "method", name: "quoteToSideChat", static: false, private: false, access: { has: obj => "quoteToSideChat" in obj, get: obj => obj.quoteToSideChat }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _entryNotes_decorators, { kind: "method", name: "entryNotes", static: false, private: false, access: { has: obj => "entryNotes" in obj, get: obj => obj.entryNotes }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _noteCounts_decorators, { kind: "method", name: "noteCounts", static: false, private: false, access: { has: obj => "noteCounts" in obj, get: obj => obj.noteCounts }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _addNote_decorators, { kind: "method", name: "addNote", static: false, private: false, access: { has: obj => "addNote" in obj, get: obj => obj.addNote }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _updateNote_decorators, { kind: "method", name: "updateNote", static: false, private: false, access: { has: obj => "updateNote" in obj, get: obj => obj.updateNote }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteNote_decorators, { kind: "method", name: "deleteNote", static: false, private: false, access: { has: obj => "deleteNote" in obj, get: obj => obj.deleteNote }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _recordDiscussion_decorators, { kind: "method", name: "recordDiscussion", static: false, private: false, access: { has: obj => "recordDiscussion" in obj, get: obj => obj.recordDiscussion }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _addReply_decorators, { kind: "method", name: "addReply", static: false, private: false, access: { has: obj => "addReply" in obj, get: obj => obj.addReply }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _editReply_decorators, { kind: "method", name: "editReply", static: false, private: false, access: { has: obj => "editReply" in obj, get: obj => obj.editReply }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _markSynced_decorators, { kind: "method", name: "markSynced", static: false, private: false, access: { has: obj => "markSynced" in obj, get: obj => obj.markSynced }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteDiscussion_decorators, { kind: "method", name: "deleteDiscussion", static: false, private: false, access: { has: obj => "deleteDiscussion" in obj, get: obj => obj.deleteDiscussion }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mediaTranscript_decorators, { kind: "method", name: "mediaTranscript", static: false, private: false, access: { has: obj => "mediaTranscript" in obj, get: obj => obj.mediaTranscript }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _startLocalTranscript_decorators, { kind: "method", name: "startLocalTranscript", static: false, private: false, access: { has: obj => "startLocalTranscript" in obj, get: obj => obj.startLocalTranscript }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _localTranscript_decorators, { kind: "method", name: "localTranscript", static: false, private: false, access: { has: obj => "localTranscript" in obj, get: obj => obj.localTranscript }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _speakerNames_decorators, { kind: "method", name: "speakerNames", static: false, private: false, access: { has: obj => "speakerNames" in obj, get: obj => obj.speakerNames }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _nameSpeaker_decorators, { kind: "method", name: "nameSpeaker", static: false, private: false, access: { has: obj => "nameSpeaker" in obj, get: obj => obj.nameSpeaker }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mediaStates_decorators, { kind: "method", name: "mediaStates", static: false, private: false, access: { has: obj => "mediaStates" in obj, get: obj => obj.mediaStates }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _cancelLocalTranscript_decorators, { kind: "method", name: "cancelLocalTranscript", static: false, private: false, access: { has: obj => "cancelLocalTranscript" in obj, get: obj => obj.cancelLocalTranscript }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _polish_decorators, { kind: "method", name: "polish", static: false, private: false, access: { has: obj => "polish" in obj, get: obj => obj.polish }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setPolishOff_decorators, { kind: "method", name: "setPolishOff", static: false, private: false, access: { has: obj => "setPolishOff" in obj, get: obj => obj.setPolishOff }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _snapshotEntry_decorators, { kind: "method", name: "snapshotEntry", static: false, private: false, access: { has: obj => "snapshotEntry" in obj, get: obj => obj.snapshotEntry }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        static inject = ['reader'];
+        static inject = ['reader', 'readerNotes'];
         constructor(ctx, _config = {}) {
             super(ctx, 'readerRemote', { namespace: 'reader' });
             __runInitializers(this, _instanceExtraInitializers);
@@ -147,6 +207,10 @@ let ReaderRemoteService = (() => {
         get core() {
             return this.ctx.reader;
         }
+        /** The notes store this face delegates to. */
+        get notes() {
+            return this.ctx.readerNotes;
+        }
         /** Capability handshake: what the browser may rely on in this composition. */
         capabilities() {
             return this.core.capabilities();
@@ -280,6 +344,92 @@ let ReaderRemoteService = (() => {
         quoteToSideChat(request) {
             return this.core.quoteToSideChat(request);
         }
+        /* ------------------------------------------------------------------ notes */
+        /** One article's notes and the conversations that discussed it. */
+        async entryNotes(request) {
+            const entry = this.notes.entry(request.entryId);
+            return entry === undefined ? {} : { entry };
+        }
+        /** How many notes each article carries. */
+        async noteCounts() {
+            return { counts: this.notes.counts() };
+        }
+        /** Keep one excerpt (and its comment). */
+        addNote(request) {
+            return this.notes.addNote(request);
+        }
+        /** Change or clear one note's comment. */
+        updateNote(request) {
+            return this.notes.updateNote(request);
+        }
+        /** Delete one note. */
+        deleteNote(request) {
+            return this.notes.deleteNote(request);
+        }
+        /** Remember that a conversation discussed this article. */
+        recordDiscussion(request) {
+            return this.notes.recordSession(request);
+        }
+        /** Add the reader's own line under a note. */
+        addReply(request) {
+            return this.notes.addReply({ ...request, by: 'user' });
+        }
+        /** Rewrite (or, with empty text, remove) one line under a note. */
+        editReply(request) {
+            return this.notes.editReply(request);
+        }
+        /** Remember that a note or a discussion note became a canvas card. */
+        markSynced(request) {
+            return this.notes.markSynced(request);
+        }
+        /** Delete one discussion note. */
+        deleteDiscussion(request) {
+            return this.notes.deleteDiscussion(request);
+        }
+        /** A video entry's transcript from its platform captions (stored; `none` when it has none). */
+        mediaTranscript(request) {
+            return this.core.mediaTranscript(request);
+        }
+        /**
+         * Start (or rejoin) local transcription of an entry without captions.
+         * Answers `unavailable` without the transcription plugin and `needs-models`
+         * until the first model download is confirmed.
+         */
+        startLocalTranscript(request) {
+            return this.core.local.start(request);
+        }
+        /** Where an entry's local transcription stands, with the transcript so far. */
+        localTranscript(request) {
+            return Promise.resolve(this.core.local.status(request.entryId));
+        }
+        /** The reader's names for a transcript's speakers, by index. */
+        speakerNames(request) {
+            return Promise.resolve(this.core.speakerNames(request));
+        }
+        /** Name one speaker of a transcript (empty: back to 说话人 A…); answers all the names. */
+        nameSpeaker(request) {
+            return Promise.resolve(this.core.nameSpeaker(request));
+        }
+        /** The wall's video / audio cards: what each one's transcript is (captions, local, transcribing…). */
+        mediaStates(request) {
+            return Promise.resolve(this.core.mediaStates(request));
+        }
+        /** Leave (withdraws a queued job) or, with `force`, stop an entry's local transcription. */
+        cancelLocalTranscript(request) {
+            return Promise.resolve(this.core.local.cancel(request.entryId, request.force));
+        }
+        /** The article's 润色 layer (the agent's translation), when there is one for its current text. */
+        polish(request) {
+            return Promise.resolve(this.notes.polishView(request.entryId) ?? null);
+        }
+        /** Show one paragraph's machine translation instead of the 润色 (or back). */
+        setPolishOff(request) {
+            return Promise.resolve(this.notes.setPolishOff(request.entryId, request.paragraph, request.off) ?? null);
+        }
+        /** Hand the host the article's original text, block by block, for the model to read. */
+        snapshotEntry(request) {
+            return this.notes.snapshot(request);
+        }
     };
 })();
 export { ReaderRemoteService };

package/lib/types/service.d.ts

@@ -35,7 +35,9 @@
  * @module @khorsheed/dsh-reader/service
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { type ReaderAddFailure, type ReaderAddOutcome, type ReaderAddRefusal, type ReaderAnnotationOutcome, type ReaderBackfillCandidate, type ReaderEntryBodyView, type ReaderBody, type ReaderCapabilities, type ReaderMutationOutcome, type ReaderEntryFetchState, type ReaderEntryTranslationView, type ReaderPreviewFailure, type ReaderPreviewFailureCode, type ReaderImageResult, type ReaderRecentEntry, type ReaderRefreshResult, type ReaderSentenceLearn, type ReaderSourceSummary, type ReaderStorageStats, type ReaderTag } from './types.ts';
+import { type ReaderAddFailure, type ReaderAddOutcome, type ReaderAddRefusal, type ReaderAnnotationOutcome, type ReaderBackfillCandidate, type ReaderEntryBodyView, type ReaderBody, type ReaderCapabilities, type ReaderMutationOutcome, type ReaderEntryFetchState, type ReaderEntryTranslationView, type ReaderPreviewFailure, type ReaderPreviewFailureCode, type ReaderImageResult, type ReaderRecentEntry, type ReaderRefreshResult, type ReaderSentenceLearn, type ReaderSourceSummary, type ReaderStorageStats, type ReaderTag, type MediaCardStates } from './types.ts';
+import { LocalTranscriber } from './local-transcribe.ts';
+import { ReaderMediaHost } from './media-host.ts';
 /**
  * How many entries one automatic backfill run may fetch.
  *
@@ -46,6 +48,15 @@ import { type ReaderAddFailure, type ReaderAddOutcome, type ReaderAddRefusal, ty
 export declare const BACKFILL_MAX_PER_RUN = 8;
 /** How long a FAILED fetch is left alone before it may be retried (6 hours). */
 export declare const BACKFILL_RETRY_MS: number;
+/**
+ * How many sources one refresh fetches at once.
+ *
+ * A strictly sequential loop made one dead source (a full 30 s timeout) stall
+ * every source behind it — the "refresh takes minutes" half of the slow-load
+ * report. Three at a time is the politeness ceiling this package applies to
+ * other people's servers everywhere (the backfill runs at two).
+ */
+export declare const REFRESH_CONCURRENCY = 3;
 /**
  * Thrown when the FETCH itself failed — a refused connection, a timeout, a
  * response over the seam's byte cap. Carries the seam's own message: the
@@ -73,6 +84,10 @@ export declare function classifyPayload(raw: string): 'feed' | 'page';
 /** The reader service. */
 export declare class ReaderService {
     private readonly store;
+    /** Video and audio entries: synthetic pages, channel feeds, transcripts. */
+    readonly media: ReaderMediaHost;
+    /** Local transcription of entries without captions (the optional `transcribe` engine). */
+    readonly local: LocalTranscriber;
     private readonly ctx;
     private timer;
     private disposed;
@@ -86,6 +101,7 @@ export declare class ReaderService {
      */
     constructor(ctx: Context, config?: {
         stateRoot?: string;
+        ytdlpPath?: string;
     });
     /** Capabilities the browser may rely on. */
     capabilities(): Promise<ReaderCapabilities>;
@@ -323,6 +339,8 @@ export declare class ReaderService {
         title?: string;
         /** A short excerpt (abstract / first paragraph), with the title. */
         excerpt?: string;
+        /** Keep regardless of the cache TTL (a transcript costs a yt-dlp run, not a page fetch). */
+        keep?: boolean;
     }): Promise<ReaderEntryBodyView>;
     /**
      * Which entries still need their full text, and which may be retried.
@@ -591,6 +609,58 @@ export declare class ReaderService {
      * @returns the final URL and its decoded payload.
      */
     private fetchFollowing;
+    /**
+     * Fetch a source's payload, media-aware (media-host.ts).
+     *
+     * A YouTube channel is fetched as YouTube's own channel feed; a Xiaoyuzhou
+     * podcast page as the RSS document it is turned into; a single video or
+     * Xiaoyuzhou episode as a synthetic page carrying its media description.
+     * Everything else is the ordinary {@link fetchFollowing}.
+     *
+     * @param url - the source URL.
+     */
+    private fetchSource;
+    /**
+     * A video entry's transcript: the stored one, else the platform captions
+     * fetched now and kept (no TTL — it costs a yt-dlp run). A video known to
+     * have no captions answers so without running yt-dlp again.
+     *
+     * @param request - the entry and its video page URL.
+     * @returns the transcript markup, `none`, or why it failed.
+     */
+    mediaTranscript(request: {
+        entryId: string;
+        url: string;
+    }): Promise<{
+        entryId: string;
+        html?: string;
+        captions: 'platform' | 'none' | 'failed';
+        language?: string;
+        error?: string;
+    }>;
+    /** The reader's names for an entry's speakers, by index. */
+    speakerNames(request: {
+        entryId: string;
+    }): Record<string, string>;
+    /**
+     * Name one speaker of an entry's transcript (an empty name restores the default).
+     *
+     * @param request - the entry, the speaker's index, the name.
+     */
+    nameSpeaker(request: {
+        entryId: string;
+        speaker: number;
+        name: string;
+    }): Record<string, string>;
+    /**
+     * The wall's media cards: a live local job first, else what the captions
+     * record says (platform captions, a stored local transcript, none).
+     *
+     * @param request - the card ids on screen.
+     */
+    mediaStates(request: {
+        entryIds: readonly string[];
+    }): MediaCardStates;
     /** Arm (or re-arm) the daily refresh timer against the current document. */
     private armSchedule;
 }