@khorsheed/dsh-reader 0.3.0 → 0.3.2

package/lib/types/client/useMedia.js

@@ -0,0 +1,299 @@
+/**
+ * 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 { useCallback, useEffect, useRef, useState } from 'react';
+import { formatClock } from "../captions.js";
+import { blockElements } from "./notes.js";
+/** Scrolled this far into the transcript, a video shrinks to the mini bar (px)… */
+const MINI_AFTER_PX = 160;
+/** …and back near the top it opens again. */
+const FULL_BEFORE_PX = 24;
+/** Positions kept per entry, at most. */
+const MAX_POSITIONS = 200;
+const POSITIONS_KEY = 'dsh-reader.mediaPositions';
+const HIDDEN_KEY = 'dsh-reader.captionsHidden';
+const HINT_KEY = 'dsh-reader.timeHintSeen';
+/** A small per-browser record (a convenience: an empty store is a fine answer). */
+function readRecord(key) {
+    try {
+        return JSON.parse(globalThis.localStorage?.getItem(key) ?? '{}');
+    }
+    catch {
+        return {};
+    }
+}
+function writeRecord(key, value) {
+    try {
+        globalThis.localStorage?.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // Private window / blocked storage: the position simply is not remembered.
+    }
+}
+/** The start time a block carries (`data-t`), when it is a transcript paragraph. */
+export function blockTime(element) {
+    const value = element?.getAttribute('data-t');
+    if (value === null || value === undefined)
+        return undefined;
+    const seconds = Number(value);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}
+/**
+ * The open entry's media state.
+ *
+ * @param input - what the pane already holds.
+ */
+export function useMedia(input) {
+    const { entryId, media, articleHtml, articleRef, detailRef, chipTitle, speakerLabel } = input;
+    const [transcriptOf, setTranscriptOf] = useState(undefined);
+    const transcript = transcriptOf !== undefined && transcriptOf.entryId === entryId ? transcriptOf.state : undefined;
+    const setTranscript = useCallback((id, state) => { setTranscriptOf({ entryId: id, state }); }, []);
+    const [hiddenIds, setHiddenIds] = useState(() => readRecord(HIDDEN_KEY));
+    const [followPaused, setFollowPaused] = useState(false);
+    const [mini, setMiniState] = useState(false);
+    const [hintOwed, setHintOwed] = useState(() => {
+        try {
+            return globalThis.localStorage?.getItem(HINT_KEY) !== '1';
+        }
+        catch {
+            return false;
+        }
+    });
+    const playerRef = useRef(null);
+    const nowRef = useRef(null);
+    const paused = useRef(false);
+    /** A mini bar the reader asked for stays until they open it again. */
+    const pinnedMini = useRef(false);
+    const ownScroll = useRef(false);
+    /** When the playback time last moved (a paused video has nothing to follow). */
+    const advancedAt = useRef(0);
+    const lastSeconds = useRef(undefined);
+    const lastSaved = useRef(0);
+    const startAt = entryId === undefined ? 0 : readRecord(POSITIONS_KEY)[entryId] ?? 0;
+    const hidden = entryId !== undefined && hiddenIds[entryId] === true;
+    // A different entry: no paragraph is playing yet, the player opens full.
+    useEffect(() => {
+        nowRef.current = null;
+        paused.current = false;
+        pinnedMini.current = false;
+        setFollowPaused(false);
+        setMiniState(false);
+    }, [entryId]);
+    const setMini = useCallback((value) => {
+        pinnedMini.current = value;
+        setMiniState(value);
+    }, []);
+    const dismissHint = useCallback(() => {
+        setHintOwed(false);
+        try {
+            globalThis.localStorage?.setItem(HINT_KEY, '1');
+        }
+        catch {
+            // The hint shows again next time; harmless.
+        }
+    }, []);
+    const setHidden = useCallback((value) => {
+        if (entryId === undefined)
+            return;
+        setHiddenIds(current => {
+            const next = { ...current };
+            if (value)
+                next[entryId] = true;
+            else
+                delete next[entryId];
+            writeRecord(HIDDEN_KEY, next);
+            return next;
+        });
+    }, [entryId]);
+    // Decorate the transcript's paragraphs with their time chip.
+    useEffect(() => {
+        const article = articleRef.current;
+        if (article === null || media === undefined)
+            return;
+        for (const block of blockElements(article)) {
+            const seconds = blockTime(block);
+            if (seconds === undefined || block.querySelector(':scope > [data-reader-ts]') !== null)
+                continue;
+            const chip = article.ownerDocument.createElement('button');
+            chip.type = 'button';
+            chip.setAttribute('data-reader-ts', String(seconds));
+            chip.setAttribute('data-label', formatClock(seconds));
+            chip.setAttribute('data-reader-no-translate', '1');
+            chip.setAttribute('aria-label', chipTitle(formatClock(seconds)));
+            chip.title = chipTitle(formatClock(seconds));
+            block.prepend(chip);
+        }
+    }, [articleHtml, media, articleRef, chipTitle]);
+    // Who speaks: a name at the start of the paragraph where the voice changes
+    // (a transcript's habit — not repeated on every paragraph), drawn from CSS
+    // content like the time, so selections and translation never take it; kept
+    // current as the reader renames a speaker.
+    useEffect(() => {
+        const article = articleRef.current;
+        if (article === null || media === undefined)
+            return;
+        let previous = null;
+        for (const block of blockElements(article)) {
+            const spk = block.getAttribute('data-spk');
+            if (spk === null)
+                continue;
+            const changes = spk !== previous;
+            previous = spk;
+            let label = block.querySelector(':scope > [data-reader-spk]');
+            if (!changes) {
+                label?.remove();
+                continue;
+            }
+            if (label === null) {
+                label = article.ownerDocument.createElement('span');
+                label.setAttribute('data-reader-spk', spk);
+                label.setAttribute('data-reader-no-translate', '1');
+                const chip = block.querySelector(':scope > [data-reader-ts]');
+                if (chip !== null)
+                    chip.after(label);
+                else
+                    block.prepend(label);
+            }
+            label.setAttribute('data-label', speakerLabel(Number(spk)));
+        }
+    }, [articleHtml, media, articleRef, speakerLabel]);
+    const seek = useCallback((seconds) => {
+        paused.current = false;
+        setFollowPaused(false);
+        playerRef.current?.seek(seconds);
+    }, []);
+    // A chip click seeks (capture phase: it must not reach the translation click).
+    useEffect(() => {
+        const article = articleRef.current;
+        if (article === null || media === undefined)
+            return;
+        const onClick = (event) => {
+            const chip = event.target?.closest?.('[data-reader-ts]');
+            if (chip === null || chip === undefined)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            seek(Number(chip.getAttribute('data-reader-ts')));
+        };
+        article.addEventListener('click', onClick, true);
+        return () => { article.removeEventListener('click', onClick, true); };
+    }, [articleHtml, media, articleRef, seek]);
+    // A hand scroll stops following (our own scroll does not), and the scroll
+    // depth sizes a video: down in the transcript it is the mini bar.
+    useEffect(() => {
+        const scroller = detailRef.current;
+        if (scroller === null || media === undefined)
+            return;
+        const onScroll = () => {
+            if (media.kind === 'video' && !pinnedMini.current) {
+                if (scroller.scrollTop > MINI_AFTER_PX)
+                    setMiniState(true);
+                else if (scroller.scrollTop < FULL_BEFORE_PX)
+                    setMiniState(false);
+            }
+        };
+        // Only the reader's own gestures stop following — a layout change (the
+        // player shrinking) scrolls too, and must not count.
+        const onHand = () => {
+            if (ownScroll.current || paused.current || nowRef.current === null)
+                return;
+            if (Date.now() - advancedAt.current > 3000)
+                return;
+            paused.current = true;
+            setFollowPaused(true);
+        };
+        const onKey = (event) => {
+            if (['ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End', ' '].includes(event.key))
+                onHand();
+        };
+        scroller.addEventListener('scroll', onScroll, { passive: true });
+        scroller.addEventListener('wheel', onHand, { passive: true });
+        scroller.addEventListener('touchmove', onHand, { passive: true });
+        scroller.addEventListener('keydown', onKey);
+        return () => {
+            scroller.removeEventListener('scroll', onScroll);
+            scroller.removeEventListener('wheel', onHand);
+            scroller.removeEventListener('touchmove', onHand);
+            scroller.removeEventListener('keydown', onKey);
+        };
+    }, [media, detailRef, entryId]);
+    const onTime = useCallback((seconds) => {
+        if (entryId === undefined)
+            return;
+        if (lastSeconds.current !== undefined && Math.abs(seconds - lastSeconds.current) > 0.05)
+            advancedAt.current = Date.now();
+        lastSeconds.current = seconds;
+        // The position, every few seconds of play (not on every tick).
+        if (Math.abs(seconds - lastSaved.current) >= 5) {
+            lastSaved.current = seconds;
+            const positions = readRecord(POSITIONS_KEY);
+            delete positions[entryId];
+            const next = { [entryId]: Math.floor(seconds), ...positions };
+            writeRecord(POSITIONS_KEY, Object.fromEntries(Object.entries(next).slice(0, MAX_POSITIONS)));
+        }
+        const article = articleRef.current;
+        if (article === null)
+            return;
+        let current;
+        for (const block of blockElements(article)) {
+            const t = blockTime(block);
+            if (t === undefined)
+                continue;
+            if (t > seconds + 0.25)
+                break;
+            current = block;
+        }
+        if (current === undefined || current === nowRef.current)
+            return;
+        nowRef.current?.removeAttribute('data-now');
+        current.setAttribute('data-now', '1');
+        nowRef.current = current;
+        if (!paused.current) {
+            ownScroll.current = true;
+            current.scrollIntoView({ block: 'center', behavior: 'smooth' });
+            setTimeout(() => { ownScroll.current = false; }, 1200);
+        }
+    }, [entryId, articleRef]);
+    const resumeFollow = useCallback(() => {
+        paused.current = false;
+        setFollowPaused(false);
+        const current = nowRef.current;
+        if (current === null)
+            return;
+        ownScroll.current = true;
+        current.scrollIntoView({ block: 'center', behavior: 'smooth' });
+        setTimeout(() => { ownScroll.current = false; }, 1200);
+    }, []);
+    return {
+        media,
+        transcript,
+        setTranscript,
+        hidden,
+        setHidden,
+        startAt,
+        playerRef,
+        onTime,
+        followPaused,
+        resumeFollow,
+        mini,
+        setMini,
+        hintOwed,
+        dismissHint,
+        seek,
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { MediaCardStates } from '../types.ts';
+import type { ReaderPaneProps } from './contract.ts';
+/**
+ * @param entryIds - the media cards on the wall.
+ * @param active - whether the wall is on screen.
+ * @param remote - the Remote verb.
+ */
+export declare function useMediaStates(entryIds: readonly string[], active: boolean, remote: Pick<ReaderPaneProps, 'mediaStates'>): MediaCardStates | undefined;
+//# sourceMappingURL=useMediaStates.d.ts.map

package/lib/types/client/useMediaStates.js

@@ -0,0 +1,43 @@
+/**
+ * The wall's video / audio cards: what each one's transcript is (platform
+ * captions, a local transcript, transcribing, none), read from the host for
+ * the media cards on screen and re-read every few seconds while any of them
+ * is transcribing — the card's pill is how a reader sees a job they left run.
+ *
+ * @module @khorsheed/dsh-reader/client/useMediaStates
+ */
+import { useEffect, useRef, useState } from 'react';
+/** How often a wall with a transcribing card re-reads (ms). */
+const POLL_MS = 3000;
+const LIVE = new Set(['fetching', 'queued', 'transcribing']);
+/**
+ * @param entryIds - the media cards on the wall.
+ * @param active - whether the wall is on screen.
+ * @param remote - the Remote verb.
+ */
+export function useMediaStates(entryIds, active, remote) {
+    const [states, setStates] = useState(undefined);
+    const remoteRef = useRef(remote);
+    remoteRef.current = remote;
+    const key = entryIds.join(',');
+    const live = states !== undefined && Object.values(states.states).some(status => LIVE.has(status.state));
+    useEffect(() => {
+        if (!active || key === '')
+            return undefined;
+        let cancelled = false;
+        const read = () => {
+            void remoteRef.current.mediaStates({ entryIds: key.split(',') }).then(answer => {
+                if (!cancelled && answer.ok)
+                    setStates(answer.value);
+            });
+        };
+        read();
+        const timer = live ? setInterval(read, POLL_MS) : undefined;
+        return () => {
+            cancelled = true;
+            if (timer !== undefined)
+                clearInterval(timer);
+        };
+    }, [key, active, live]);
+    return states;
+}

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

@@ -0,0 +1,110 @@
+/**
+ * The detail view's notes, as one hook: loading an article's notes, handing
+ * the host its text, painting the highlights, the note sheet, and the
+ * gestures on notes.
+ *
+ * Kept out of `ReaderPane.tsx` on purpose: the pane already owns the reading
+ * position, the translation and the fetch lifecycle, and the notes only READ
+ * those (the article element, the segmentation, the view) — they never drive
+ * them.
+ *
+ * @module @khorsheed/dsh-reader/client/useNotes
+ */
+import { type MutableRefObject } from 'react';
+import type { ReaderDiscussion, ReaderEntryNotes, ReaderNote } from '../notes-types.ts';
+import type { ReaderPaneProps } from './contract.ts';
+import type { ReaderEntry } from './parse-rss.ts';
+import type { BuiltArticle, TranslationView } from './translate.ts';
+import { type SyncCanvas, type SyncKind } from './canvas-sync.ts';
+import { type NoteSelection } from './notes.ts';
+/** Which face of the detail view is showing. */
+export type DetailTab = 'article' | 'notes';
+/** What is being synced to a canvas: some notes, or one discussion note. */
+export type SyncTarget = {
+    readonly kind: 'notes';
+    readonly ids: readonly string[];
+} | {
+    readonly kind: 'discussion';
+    readonly id: string;
+};
+/** The 「同步到画布」 sheet's state and gestures. */
+export interface SyncFace {
+    /** Whether the canvas inbox is there at all (the gesture hides without it). */
+    readonly available: boolean;
+    readonly target: SyncTarget | null;
+    /** The canvases to pick from; null while loading. */
+    readonly canvases: readonly SyncCanvas[] | null;
+    readonly pick: string | null;
+    readonly last: string | null;
+    readonly withReplies: boolean;
+    /** Set when the picked canvas retired 灵感: the categories it takes. */
+    readonly kinds: readonly SyncKind[] | null;
+    readonly kind: string | null;
+    readonly busy: boolean;
+    readonly error: string | null;
+    /** The last sync's landing place, shown for a moment with an 打开. */
+    readonly done: {
+        readonly canvasId: string;
+        readonly cardId: string;
+        readonly title: string;
+    } | null;
+    readonly open: (target: SyncTarget) => void;
+    readonly setPick: (canvasId: string) => void;
+    readonly setWithReplies: (on: boolean) => void;
+    readonly setKind: (kind: string) => void;
+    readonly run: () => void;
+    readonly cancel: () => void;
+    readonly openDone: () => void;
+}
+/** What the hook reads from the pane. */
+export interface UseNotesInput {
+    readonly props: ReaderPaneProps;
+    readonly entry: ReaderEntry | undefined;
+    readonly sourceLabel: string;
+    readonly articleHtml: string | null;
+    readonly articleRef: MutableRefObject<HTMLDivElement | null>;
+    readonly builtRef: MutableRefObject<BuiltArticle | null>;
+    readonly detailRef: MutableRefObject<HTMLDivElement | null>;
+    /** Anything whose change means the article's text nodes changed under us. */
+    readonly paintKey: unknown;
+    readonly translateView: TranslationView;
+    /** A transcript speaker's display name (with the names that make it, so a rename re-snapshots). */
+    readonly speakerLabel?: (speaker: number) => string;
+}
+/** What the pane renders from. */
+export interface NotesFace {
+    readonly tab: DetailTab;
+    readonly setTab: (tab: DetailTab) => void;
+    readonly entry: ReaderEntryNotes | undefined;
+    readonly count: number;
+    readonly missing: ReadonlySet<string>;
+    readonly sheet: NoteSelection | null;
+    readonly saving: boolean;
+    readonly failed: boolean;
+    readonly hint: boolean;
+    readonly startNote: () => void;
+    readonly saveNote: (comment: string) => void;
+    readonly cancelSheet: () => void;
+    readonly jump: (note: ReaderNote) => void;
+    readonly edit: (note: ReaderNote, comment: string) => Promise<boolean>;
+    readonly remove: (note: ReaderNote) => void;
+    readonly discuss: (noteIds: readonly string[]) => void;
+    readonly canOpenSession: boolean;
+    readonly openSession: (sessionId: string) => void;
+    readonly sessionTitle: (sessionId: string) => string | undefined;
+    readonly addReply: (note: ReaderNote, text: string) => Promise<boolean>;
+    readonly editReply: (note: ReaderNote, index: number, text: string) => Promise<boolean>;
+    readonly deleteDiscussion: (discussion: ReaderDiscussion) => void;
+    readonly jumpPara: (para: number) => void;
+    readonly check: () => void;
+    /** Put a 润色 (re-translate) request into the draft: the whole article, or continuing at ¶`from`. */
+    readonly polish: (total: number, from?: number) => void;
+    readonly sync: SyncFace;
+}
+/**
+ * The notes of the open article, and every gesture on them.
+ *
+ * @param input - what the pane already holds.
+ */
+export declare function useNotes(input: UseNotesInput): NotesFace;
+//# sourceMappingURL=useNotes.d.ts.map