@khorsheed/dsh-reader 0.3.0 → 0.3.1

package/lib/types/client/session.js

@@ -100,9 +100,21 @@ export function patchSession(patch) {
     PAGE = next;
     updatePlace(patch);
 }
+let WALL;
+/** What makes a source's parsed entries stale: its fetch, its body, its kind. */
+export function sourceStamp(source) {
+    return [source.kind, source.url, source.fetchedAt ?? '', source.hasBody, source.status ?? '', source.truncated === true, source.failure?.code ?? ''].join('|');
+}
+export function readWallCache() {
+    return WALL;
+}
+export function writeWallCache(cache) {
+    WALL = cache;
+}
 /** Drop the snapshot, here and in storage (the specs call this between cases). */
 export function forgetSession() {
     PAGE = {};
+    WALL = undefined;
     // Back to "not read yet", not to "nothing": the next read must consult storage
     // again (clearing it first, so what it finds is the truth).
     PLACE = null;

package/lib/types/client/store.js

@@ -13,6 +13,7 @@
  * @module @khorsheed/dsh-reader/client/store
  */
 import { defineStore } from '@deepseek-ai/dsh-client-store';
+import { repairStoredBody } from "./extract-article.js";
 const INITIAL = {
     sources: [],
     parsed: {},
@@ -169,7 +170,9 @@ export function createReaderStore() {
                 d.read = { ...d.read, [entryId]: true };
             },
             setArticle: (d, html, truncated, error) => {
-                d.articleHtml = html;
+                // Every body reaches the screen through here, so a cached one written
+                // by an older extractor is brought up to the current SVG rules once.
+                d.articleHtml = repairStoredBody(html);
                 d.articleTruncated = truncated;
                 d.articleError = error;
             },

package/lib/types/client/translate.d.ts

@@ -7,7 +7,10 @@
  * `state.json`, and costs no tokens. That is also why this module has no
  * Remote verb and no host counterpart — its only dependency is a global the
  * page may or may not have, and {@link detectTranslator} is the whole
- * degradation story (no API → no button, not a broken one).
+ * degradation story (no API → no button, not a broken one). The one exception
+ * is a translation some OTHER browser already made: the host stores those, and
+ * a page without the API may still show them ({@link applyRemembered}) — it
+ * can view a stored translation, never make a new one.
  *
  * The unit of translation is a SENTENCE inside one text node — never a node,
  * never a paragraph. Two reasons the granularity matters:
@@ -364,6 +367,28 @@ export interface RunTranslationResult {
 }
 /** Every segment of a built article, in reading order. */
 export declare function segmentsOf(built: BuiltArticle): BuiltSegment[];
+/** What the memory alone could paint onto a built article. */
+export interface RememberedResult {
+    readonly done: number;
+    readonly total: number;
+    /** Units the memory served (their LRU stamps should move). */
+    readonly recalled: readonly ReaderSentenceLearn[];
+    /** Units the memory did not know, in reading order. */
+    readonly pending: readonly BuiltSegment[];
+}
+/**
+ * Paint every segment the page's memory already knows, and nothing else.
+ *
+ * This is the first step of every run, and the WHOLE of one on a browser with
+ * no Translator API: there the host's stored translations (warmed into the
+ * memory first) are the only source, and a sentence they do not cover simply
+ * stays in its original.
+ *
+ * @param built - the segmented article.
+ * @param pair - the `<src>→<tgt>` label the memory is read under.
+ * @returns how many units were painted, out of how many, and the rest.
+ */
+export declare function applyRemembered(built: BuiltArticle, pair: string): RememberedResult;
 /**
  * Translate every segment of a built article, best effort.
  *

package/lib/types/client/translate.js

@@ -788,24 +788,21 @@ export function segmentsOf(built) {
     return built.blocks.flatMap(block => block.segments);
 }
 /**
- * Translate every segment of a built article, best effort.
+ * Paint every segment the page's memory already knows, and nothing else.
  *
- * Remembered units paint immediately; the rest go out in batches of whole
- * sentences. A batch whose separator comes back altered is re-sent one unit at
- * a time — the fallback gives up granularity for that batch, never correctness.
+ * This is the first step of every run, and the WHOLE of one on a browser with
+ * no Translator API: there the host's stored translations (warmed into the
+ * memory first) are the only source, and a sentence they do not cover simply
+ * stays in its original.
  *
- * @param options - the built article, a created session, and the cancel flag.
- * @returns how many units were translated, how many failed, and the total.
+ * @param built - the segmented article.
+ * @param pair - the `<src>→<tgt>` label the memory is read under.
+ * @returns how many units were painted, out of how many, and the rest.
  */
-export async function runTranslation(options) {
-    const { built, session, pair, cancelled, onProgress } = options;
+export function applyRemembered(built, pair) {
     const segments = segmentsOf(built);
-    const total = segments.length;
     let done = 0;
-    let failed = 0;
-    const learned = [];
     const recalled = [];
-    const report = () => { onProgress?.(done, total); };
     const pending = [];
     for (const segment of segments) {
         const hit = remembered(pair, segment.original);
@@ -818,6 +815,26 @@ export async function runTranslation(options) {
             pending.push(segment);
         }
     }
+    return { done, total: segments.length, recalled, pending };
+}
+/**
+ * Translate every segment of a built article, best effort.
+ *
+ * Remembered units paint immediately; the rest go out in batches of whole
+ * sentences. A batch whose separator comes back altered is re-sent one unit at
+ * a time — the fallback gives up granularity for that batch, never correctness.
+ *
+ * @param options - the built article, a created session, and the cancel flag.
+ * @returns how many units were translated, how many failed, and the total.
+ */
+export async function runTranslation(options) {
+    const { built, session, pair, cancelled, onProgress } = options;
+    const memory = applyRemembered(built, pair);
+    const { total, recalled, pending } = memory;
+    let done = memory.done;
+    let failed = 0;
+    const learned = [];
+    const report = () => { onProgress?.(done, total); };
     report();
     let batch = [];
     let chars = 0;

package/lib/types/client/useLocalTranscript.d.ts

@@ -0,0 +1,43 @@
+import type { LocalTranscriptStatus, ReaderMedia } from '../types.ts';
+import type { ReaderPaneProps } from './contract.ts';
+/** What the hook reads. */
+export interface UseLocalTranscriptInput {
+    readonly entry: {
+        readonly id: string;
+        readonly link?: string;
+        readonly title: string;
+        readonly media?: ReaderMedia;
+    } | undefined;
+    /** True once the pane knows the entry has no captions and no stored transcript. */
+    readonly wanted: boolean;
+    /** The 字幕 switch is off: no transcription. */
+    readonly hidden: boolean;
+    /**
+     * A stored local transcript is on screen: the host may still be working on
+     * it (the speakers pass runs on after the transcript is stored), so the
+     * pane asks once and follows it.
+     */
+    readonly rejoin?: boolean;
+    readonly remote: Pick<ReaderPaneProps, 'startLocalTranscript' | 'localTranscript' | 'cancelLocalTranscript'>;
+    /** The transcript so far (`partial`) or in full. */
+    readonly onHtml: (entryId: string, html: string, partial: boolean) => void;
+}
+/** What the pane renders. */
+export interface LocalTranscriptFace {
+    readonly status: LocalTranscriptStatus | undefined;
+    /** Seconds left, once the rate is measurable. */
+    readonly etaSeconds: number | undefined;
+    /** Confirm the first model download and start. */
+    readonly confirm: () => void;
+    /** Start again after a failure or a stop. */
+    readonly retry: () => void;
+    /** Stop the running job (取消, or the 字幕 switch). */
+    readonly stop: () => void;
+}
+/**
+ * The open entry's local transcription.
+ *
+ * @param input - the entry and what the pane knows.
+ */
+export declare function useLocalTranscript(input: UseLocalTranscriptInput): LocalTranscriptFace;
+//# sourceMappingURL=useLocalTranscript.d.ts.map

package/lib/types/client/useLocalTranscript.js

@@ -0,0 +1,129 @@
+/**
+ * Local transcription of the open video / audio entry when it has no captions
+ * (2026-10-20 decision: automatic on opening the detail, never on refresh).
+ *
+ * The host runs the job (`startLocalTranscript`); this hook starts it once per
+ * entry, polls its status while it runs — the stretches transcribed so far
+ * replace the body as they arrive, so they can be read and noted at once —
+ * and hands the finished transcript over. Leaving the entry withdraws a job
+ * that is still queued (a running one finishes and is stored); the 字幕 switch
+ * and 取消 stop it outright. The first use asks once to download the speech
+ * models.
+ *
+ * @module @khorsheed/dsh-reader/client/useLocalTranscript
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+/** How often a running job is polled (ms). */
+const POLL_MS = 1500;
+/** States in which the job is alive on the host. */
+const ACTIVE = new Set(['fetching', 'queued', 'transcribing', 'speakers']);
+/**
+ * The open entry's local transcription.
+ *
+ * @param input - the entry and what the pane knows.
+ */
+export function useLocalTranscript(input) {
+    const { entry, wanted, hidden, rejoin, remote, onHtml } = input;
+    const [statusOf, setStatusOf] = useState(undefined);
+    const status = statusOf !== undefined && statusOf.entryId === entry?.id ? statusOf : undefined;
+    const started = useRef(null);
+    const lastHtml = useRef(undefined);
+    const rate = useRef(undefined);
+    const [eta, setEta] = useState(undefined);
+    const remoteRef = useRef(remote);
+    remoteRef.current = remote;
+    const onHtmlRef = useRef(onHtml);
+    onHtmlRef.current = onHtml;
+    const accept = useCallback((next) => {
+        setStatusOf(next);
+        if (next.html !== undefined && next.html !== lastHtml.current) {
+            lastHtml.current = next.html;
+            onHtmlRef.current(next.entryId, next.html, next.state !== 'done');
+        }
+        if (next.state === 'transcribing' && next.progress !== undefined) {
+            const now = Date.now();
+            if (rate.current === undefined)
+                rate.current = { at: now, progress: next.progress };
+            else {
+                const done = next.progress - rate.current.progress;
+                setEta(done > 0.02 ? ((now - rate.current.at) / 1000) * ((1 - next.progress) / done) : undefined);
+            }
+        }
+    }, []);
+    const begin = useCallback(async (confirmModels) => {
+        if (entry?.link === undefined || entry.media === undefined)
+            return;
+        started.current = entry.id;
+        lastHtml.current = undefined;
+        rate.current = undefined;
+        setEta(undefined);
+        const answer = await remoteRef.current.startLocalTranscript({
+            entryId: entry.id, url: entry.link, media: entry.media, title: entry.title, ...(confirmModels ? { confirmModels: true } : {}),
+        });
+        if (answer.ok)
+            accept(answer.value);
+        else
+            setStatusOf({ entryId: entry.id, state: 'failed', error: answer.error.message });
+    }, [entry, accept]);
+    // Start once per entry, when the pane says there is nothing else to read.
+    useEffect(() => {
+        if (entry === undefined || !wanted || hidden || started.current === entry.id)
+            return;
+        void begin(false);
+    }, [entry, wanted, hidden, begin]);
+    // Reopened onto a stored local transcript: join the host's job if it is still running.
+    const rejoined = useRef(null);
+    useEffect(() => {
+        if (entry === undefined || rejoin !== true || rejoined.current === entry.id)
+            return;
+        rejoined.current = entry.id;
+        const id = entry.id;
+        void remoteRef.current.localTranscript({ entryId: id }).then(answer => {
+            if (!answer.ok || !ACTIVE.has(answer.value.state))
+                return;
+            started.current = id;
+            lastHtml.current = answer.value.html;
+            setStatusOf(answer.value);
+        });
+    }, [entry, rejoin]);
+    // Poll while the host works.
+    const active = status !== undefined && ACTIVE.has(status.state);
+    useEffect(() => {
+        if (!active || entry === undefined)
+            return undefined;
+        const id = entry.id;
+        const timer = setInterval(() => {
+            void remoteRef.current.localTranscript({ entryId: id }).then(answer => { if (answer.ok)
+                accept(answer.value); });
+        }, POLL_MS);
+        return () => { clearInterval(timer); };
+    }, [active, entry, accept]);
+    // Leaving the entry withdraws a queued job (a running one finishes on the host).
+    useEffect(() => {
+        const id = entry?.id;
+        return () => {
+            if (id !== undefined && started.current === id) {
+                started.current = null;
+                void remoteRef.current.cancelLocalTranscript({ entryId: id, force: false });
+            }
+        };
+    }, [entry?.id]);
+    const stop = useCallback(() => {
+        if (entry === undefined)
+            return;
+        void remoteRef.current.cancelLocalTranscript({ entryId: entry.id, force: true });
+        setStatusOf({ entryId: entry.id, state: 'idle' });
+    }, [entry]);
+    // The 字幕 switch turned off mid-job stops it.
+    useEffect(() => {
+        if (hidden && active)
+            stop();
+    }, [hidden, active, stop]);
+    return {
+        status,
+        etaSeconds: active ? eta : undefined,
+        confirm: () => { void begin(true); },
+        retry: () => { void begin(false); },
+        stop,
+    };
+}

package/lib/types/client/useMedia.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The detail view's media half, as one hook: the transcript's state, the
+ * 「字幕」 switch, the remembered position, the current paragraph and
+ * following it, seeking from a paragraph's time, and the player's size (full,
+ * or the mini bar while the reader is down in the transcript).
+ *
+ * Following: the playing paragraph scrolls into view until the reader
+ * scrolls by hand; then it stops — no timer pulls the page back — and
+ * 「回到正在播放」 resumes it (2026-10-20).
+ *
+ * The transcript is the article body (`<p data-t>` blocks, captions.ts). This
+ * hook only decorates it — a time chip per paragraph, drawn from a
+ * `data-label` through CSS so a selection never picks the time up — and marks
+ * the current paragraph with `data-now`. It never rewrites text nodes, which
+ * belong to `translate.ts`.
+ *
+ * @module @khorsheed/dsh-reader/client/useMedia
+ */
+import { type MutableRefObject } from 'react';
+import type { ReaderMedia } from '../media.ts';
+import type { MediaPlayerHandle } from './MediaPlayer.tsx';
+/** Where a media entry's transcript stands. */
+export type TranscriptState = 'loading' | 'ready' | 'none' | 'failed';
+/** The start time a block carries (`data-t`), when it is a transcript paragraph. */
+export declare function blockTime(element: Element | undefined): number | undefined;
+/** What the hook reads from the pane. */
+export interface UseMediaInput {
+    readonly entryId: string | undefined;
+    readonly media: ReaderMedia | undefined;
+    readonly articleHtml: string | null;
+    readonly articleRef: MutableRefObject<HTMLDivElement | null>;
+    readonly detailRef: MutableRefObject<HTMLDivElement | null>;
+    /** A time chip's tooltip, from its clock label. */
+    readonly chipTitle: (clock: string) => string;
+    /** A speaker's display name, for paragraphs that carry `data-spk`. */
+    readonly speakerLabel: (speaker: number) => string;
+}
+/** What the pane renders from. */
+export interface MediaFace {
+    readonly media: ReaderMedia | undefined;
+    readonly transcript: TranscriptState | undefined;
+    /** Record an entry's transcript state (keyed by entry: an answer for another entry never shows). */
+    readonly setTranscript: (entryId: string, state: TranscriptState) => void;
+    readonly hidden: boolean;
+    readonly setHidden: (hidden: boolean) => void;
+    readonly startAt: number;
+    readonly playerRef: MutableRefObject<MediaPlayerHandle | null>;
+    readonly onTime: (seconds: number) => void;
+    /** Following stopped by a hand scroll, with a playing paragraph to go back to. */
+    readonly followPaused: boolean;
+    /** Scroll back to the playing paragraph and follow again. */
+    readonly resumeFollow: () => void;
+    /** The video as the mini bar. */
+    readonly mini: boolean;
+    readonly setMini: (mini: boolean) => void;
+    /** The one-time 「点时间可以跳转」 hint is still owed. */
+    readonly hintOwed: boolean;
+    readonly dismissHint: () => void;
+    /** Jump the player to a moment. */
+    readonly seek: (seconds: number) => void;
+}
+/**
+ * The open entry's media state.
+ *
+ * @param input - what the pane already holds.
+ */
+export declare function useMedia(input: UseMediaInput): MediaFace;
+//# sourceMappingURL=useMedia.d.ts.map