@khorsheed/dsh-reader 0.2.1 → 0.3.1

package/lib/types/client/useNotes.js

@@ -0,0 +1,423 @@
+/**
+ * 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 { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { translationHash } from "./translate.js";
+import { mergedDraft } from "./quote.js";
+import { discussionCardText, lastCanvas, noteCardText, rememberCanvas, sourceOf, } from "./canvas-sync.js";
+import { blockElements, captureSelection, formatNotesDraft, NOTE_FLASH_HIGHLIGHT, NOTE_HIGHLIGHT, noteRanges, paintHighlight, paragraphsOf, registerNoteTarget, } from "./notes.js";
+/** How long a jumped-to excerpt stays lit. */
+const FLASH_MS = 1400;
+/** How long the "select a passage first" hint stays up. */
+const HINT_MS = 2600;
+/**
+ * How often the notes face re-reads the host while it shows: the model writes
+ * conclusions from the conversation, and they should appear without a reload
+ * (the canvas board's 4-second precedent).
+ */
+const NOTES_POLL_MS = 5000;
+/** How long the 「已同步」 line stays. */
+const SYNC_DONE_MS = 5000;
+/** True when two sets hold the same ids. */
+function sameSet(left, right) {
+    if (left.size !== right.size)
+        return false;
+    for (const id of left)
+        if (!right.has(id))
+            return false;
+    return true;
+}
+/**
+ * The notes of the open article, and every gesture on them.
+ *
+ * @param input - what the pane already holds.
+ */
+export function useNotes(input) {
+    const { props, entry, sourceLabel, articleHtml, articleRef, builtRef, detailRef, paintKey, translateView, speakerLabel } = input;
+    const { t, sessionId } = props;
+    const entryId = entry?.id;
+    const [tab, setTab] = useState('article');
+    const [notes, setNotes] = useState(undefined);
+    const [missing, setMissing] = useState(new Set());
+    const [sheet, setSheet] = useState(null);
+    const [saving, setSaving] = useState(false);
+    const [failed, setFailed] = useState(false);
+    const [hint, setHint] = useState(false);
+    const snapshotted = useRef(new Set());
+    const articleScroll = useRef(0);
+    const sessions = props.useSessions(state => state.byId);
+    const identity = useMemo(() => entry === undefined ? undefined : {
+        entryId: entry.id,
+        title: entry.title,
+        ...(entry.link === undefined ? {} : { url: entry.link }),
+        ...(sourceLabel === '' ? {} : { source: sourceLabel }),
+    }, [entry, sourceLabel]);
+    const reload = useCallback(async (id) => {
+        const loaded = await props.entryNotes(id);
+        if (loaded.ok)
+            setNotes(loaded.value.entry);
+    }, [props]);
+    // A different article: back to its text, and its own notes.
+    useEffect(() => {
+        setTab('article');
+        setSheet(null);
+        setNotes(undefined);
+        setMissing(new Set());
+        if (entryId !== undefined)
+            void reload(entryId);
+    }, [entryId, reload]);
+    // Hand the host the article's ORIGINAL text, once per body: the model reads
+    // it from there (the host never parses an article itself).
+    useEffect(() => {
+        if (identity === undefined || articleHtml === null || articleHtml.length === 0)
+            return;
+        const paragraphs = paragraphsOf(articleHtml, speakerLabel);
+        const key = `${identity.entryId}\n${translationHash(paragraphs.join('\n'))}`;
+        if (snapshotted.current.has(key))
+            return;
+        snapshotted.current.add(key);
+        if (paragraphs.length === 0)
+            return;
+        void props.snapshotEntry({ ...identity, paragraphs });
+    }, [identity, articleHtml, props, speakerLabel]);
+    // Paint the excerpts on whatever text is on screen now. Recomputed after
+    // every rebuild: a translation replaces the text nodes a range points into.
+    useEffect(() => {
+        const article = articleRef.current;
+        if (article === null || tab !== 'article') {
+            paintHighlight(NOTE_HIGHLIGHT, []);
+            return;
+        }
+        const found = noteRanges(article, builtRef.current, notes?.notes ?? []);
+        paintHighlight(NOTE_HIGHLIGHT, [...found.values()].flat());
+        const lost = new Set([...found].filter(([, ranges]) => ranges.length === 0).map(([id]) => id));
+        setMissing(current => sameSet(current, lost) ? current : lost);
+    }, [notes, articleHtml, paintKey, translateView, tab, articleRef, builtRef]);
+    // While the notes face shows, follow what the conversation writes into it.
+    useEffect(() => {
+        if (tab !== 'notes' || entryId === undefined)
+            return;
+        void reload(entryId);
+        const timer = setInterval(() => {
+            if (document.visibilityState === 'visible')
+                void reload(entryId);
+        }, NOTES_POLL_MS);
+        return () => { clearInterval(timer); };
+    }, [tab, entryId, reload]);
+    // Nothing stays painted once the pane is gone.
+    useEffect(() => () => {
+        paintHighlight(NOTE_HIGHLIGHT, []);
+        paintHighlight(NOTE_FLASH_HIGHLIGHT, []);
+    }, []);
+    const startNote = useCallback(() => {
+        const article = articleRef.current;
+        const selection = article === null ? null : captureSelection(article, builtRef.current);
+        if (selection === null) {
+            setHint(true);
+            setTimeout(() => { setHint(false); }, HINT_MS);
+            return;
+        }
+        setFailed(false);
+        setSheet(selection);
+    }, [articleRef, builtRef]);
+    // The quote menu's「记笔记」finds this pane through the target registry.
+    useEffect(() => registerNoteTarget({
+        owns: node => articleRef.current?.contains(node) === true,
+        start: startNote,
+    }), [articleRef, startNote]);
+    const saveNote = useCallback((comment) => {
+        if (identity === undefined || sheet === null)
+            return;
+        setSaving(true);
+        void props.addNote({
+            ...identity,
+            block: sheet.block,
+            ...(sheet.start === undefined ? {} : { start: sheet.start }),
+            quote: sheet.quote,
+            ...(sheet.translated === undefined ? {} : { translated: sheet.translated }),
+            ...(sheet.time === undefined ? {} : { time: sheet.time }),
+            ...(comment.trim() === '' ? {} : { comment }),
+        }).then(async (result) => {
+            setSaving(false);
+            if (!result.ok || typeof result.value === 'string') {
+                setFailed(true);
+                return;
+            }
+            setSheet(null);
+            window.getSelection()?.removeAllRanges();
+            await reload(identity.entryId);
+        });
+    }, [identity, sheet, props, reload]);
+    const switchTab = useCallback((next) => {
+        const scroller = detailRef.current;
+        if (next === 'notes' && scroller !== null)
+            articleScroll.current = scroller.scrollTop;
+        setTab(next);
+        if (next === 'article') {
+            requestAnimationFrame(() => {
+                if (detailRef.current !== null)
+                    detailRef.current.scrollTop = articleScroll.current;
+            });
+        }
+    }, [detailRef]);
+    const jump = useCallback((note) => {
+        setTab('article');
+        // Two frames: one for the article face to come back, one for its layout.
+        requestAnimationFrame(() => requestAnimationFrame(() => {
+            const article = articleRef.current;
+            if (article === null)
+                return;
+            const ranges = noteRanges(article, builtRef.current, [note]).get(note.id) ?? [];
+            const first = ranges[0];
+            if (first === undefined)
+                return;
+            const target = first.startContainer instanceof Element ? first.startContainer : first.startContainer.parentElement;
+            target?.scrollIntoView({ block: 'center' });
+            paintHighlight(NOTE_FLASH_HIGHLIGHT, ranges);
+            setTimeout(() => { paintHighlight(NOTE_FLASH_HIGHLIGHT, []); }, FLASH_MS);
+        }));
+    }, [articleRef, builtRef]);
+    const edit = useCallback(async (note, comment) => {
+        if (entryId === undefined)
+            return false;
+        const result = await props.updateNote({ entryId, noteId: note.id, comment });
+        if (!result.ok || result.value !== 'ok')
+            return false;
+        await reload(entryId);
+        return true;
+    }, [entryId, props, reload]);
+    const remove = useCallback((note) => {
+        if (entryId === undefined)
+            return;
+        void props.deleteNote({ entryId, noteId: note.id }).then(() => reload(entryId));
+    }, [entryId, props, reload]);
+    /** The conversation this pane belongs to, remembered on the article. */
+    const remember = useCallback(() => {
+        if (identity === undefined)
+            return;
+        const sessionTitle = sessions[sessionId]?.displayTitle;
+        void props.recordDiscussion({
+            ...identity,
+            sessionId: String(sessionId),
+            ...(sessionTitle === undefined ? {} : { sessionTitle }),
+        }).then(() => reload(identity.entryId));
+    }, [identity, sessions, sessionId, props, reload]);
+    const discuss = useCallback((noteIds) => {
+        if (identity === undefined || notes === undefined)
+            return;
+        const chosen = noteIds.length === 0 ? notes.notes : notes.notes.filter(note => noteIds.includes(note.id));
+        if (chosen.length === 0)
+            return;
+        const block = formatNotesDraft({
+            entryId: identity.entryId,
+            title: identity.title,
+            source: identity.source ?? '',
+            ...(identity.url === undefined ? {} : { link: identity.url }),
+        }, chosen, {
+            heading: count => t('notes.draftHeading', { count }),
+            comment: t('notes.draftComment'),
+            hint: id => t('notes.draftHint', { id }),
+        });
+        props.setDraft(mergedDraft(props.readDraft(), block));
+        remember();
+    }, [identity, notes, props, t, remember]);
+    const addReply = useCallback(async (note, text) => {
+        if (entryId === undefined)
+            return false;
+        const result = await props.addReply({ entryId, noteId: note.id, text });
+        if (!result.ok || result.value !== 'ok')
+            return false;
+        await reload(entryId);
+        return true;
+    }, [entryId, props, reload]);
+    const editReply = useCallback(async (note, index, text) => {
+        if (entryId === undefined)
+            return false;
+        const result = await props.editReply({ entryId, noteId: note.id, index, text });
+        if (!result.ok || result.value !== 'ok')
+            return false;
+        await reload(entryId);
+        return true;
+    }, [entryId, props, reload]);
+    const deleteDiscussion = useCallback((discussion) => {
+        if (entryId === undefined)
+            return;
+        void props.deleteDiscussion({ entryId, discussionId: discussion.id }).then(() => reload(entryId));
+    }, [entryId, props, reload]);
+    const jumpPara = useCallback((para) => {
+        setTab('article');
+        requestAnimationFrame(() => requestAnimationFrame(() => {
+            const article = articleRef.current;
+            const block = article === null ? undefined : blockElements(article)[para - 1];
+            if (block === undefined)
+                return;
+            block.scrollIntoView({ block: 'center' });
+            const range = block.ownerDocument.createRange();
+            range.selectNodeContents(block);
+            paintHighlight(NOTE_FLASH_HIGHLIGHT, [range]);
+            setTimeout(() => { paintHighlight(NOTE_FLASH_HIGHLIGHT, []); }, FLASH_MS);
+        }));
+    }, [articleRef]);
+    /* ------------------------------------------------------- 同步到画布 */
+    const [syncTarget, setSyncTarget] = useState(null);
+    const [canvases, setCanvases] = useState(null);
+    const [pick, setPick] = useState(null);
+    const [withReplies, setWithReplies] = useState(true);
+    const [kinds, setKinds] = useState(null);
+    const [kind, setKind] = useState(null);
+    const [syncBusy, setSyncBusy] = useState(false);
+    const [syncError, setSyncError] = useState(null);
+    const [syncDone, setSyncDone] = useState(null);
+    const inbox = props.canvasInbox();
+    const openSync = useCallback((target) => {
+        const current = props.canvasInbox();
+        if (current === undefined)
+            return;
+        setSyncTarget(target);
+        setCanvases(null);
+        setKinds(null);
+        setKind(null);
+        setSyncError(null);
+        void current.listCanvases().then(list => {
+            setCanvases(list);
+            const remembered = lastCanvas();
+            const showing = current.current();
+            const preferred = [remembered, showing].find(id => id !== null && list.some(item => item.id === id));
+            setPick(preferred ?? list[0]?.id ?? null);
+        }, () => { setCanvases([]); });
+    }, [props]);
+    const runSync = useCallback(() => {
+        const current = props.canvasInbox();
+        if (current === undefined || syncTarget === null || pick === null || identity === undefined || notes === undefined)
+            return;
+        const canvas = canvases?.find(item => item.id === pick);
+        const words = {
+            conclusion: t('notes.syncConclusion'),
+            original: t('notes.syncOriginal'),
+            kindCheck: t('notes.kindCheck'),
+            kindDiscussion: t('notes.kindDiscussion'),
+        };
+        const article = { title: identity.title, ...(identity.url === undefined ? {} : { url: identity.url }) };
+        const items = syncTarget.kind === 'notes'
+            ? notes.notes.filter(note => syncTarget.ids.includes(note.id))
+                .map(note => ({ text: noteCardText(note, article, words, withReplies), mark: { noteId: note.id } }))
+            : (notes.discussions ?? []).filter(item => item.id === syncTarget.id)
+                .map(item => ({ text: discussionCardText(item, article, words), mark: { discussionId: item.id } }));
+        setSyncBusy(true);
+        setSyncError(null);
+        void (async () => {
+            let landed;
+            for (const item of items) {
+                const outcome = await current.addCard(String(sessionId), {
+                    canvasId: pick,
+                    text: item.text,
+                    ...(kind === null ? {} : { kind }),
+                    source: sourceOf(article),
+                });
+                if (!outcome.ok) {
+                    if (outcome.error === 'needs-kind' && 'kinds' in outcome) {
+                        setKinds(outcome.kinds);
+                        setKind(outcome.kinds[0]?.id ?? null);
+                    }
+                    else {
+                        setSyncError(outcome.error);
+                    }
+                    setSyncBusy(false);
+                    await reload(identity.entryId);
+                    return;
+                }
+                landed = { cardId: outcome.cardId };
+                await props.markSynced({ entryId: identity.entryId, ...item.mark, canvasId: pick, cardId: outcome.cardId, canvasTitle: canvas?.title ?? pick });
+            }
+            rememberCanvas(pick);
+            setSyncBusy(false);
+            setSyncTarget(null);
+            await reload(identity.entryId);
+            if (landed !== undefined) {
+                setSyncDone({ canvasId: pick, cardId: landed.cardId, title: canvas?.title ?? pick });
+                setTimeout(() => { setSyncDone(null); }, SYNC_DONE_MS);
+            }
+        })();
+    }, [props, syncTarget, pick, identity, notes, canvases, t, withReplies, kind, sessionId, reload]);
+    const sync = {
+        available: inbox !== undefined,
+        target: syncTarget,
+        canvases,
+        pick,
+        last: lastCanvas(),
+        withReplies,
+        kinds,
+        kind,
+        busy: syncBusy,
+        error: syncError,
+        done: syncDone,
+        open: openSync,
+        setPick: id => { setPick(id); setKinds(null); setKind(null); },
+        setWithReplies,
+        setKind,
+        run: runSync,
+        cancel: () => { setSyncTarget(null); },
+        openDone: () => { if (syncDone !== null)
+            props.canvasInbox()?.openCard(syncDone.canvasId, syncDone.cardId); },
+    };
+    // 「让Agent考考我」: the request (with the round's contract, so it works even
+    // where the skill is not loaded) goes into the draft; the reader sends it.
+    const check = useCallback(() => {
+        if (identity === undefined)
+            return;
+        const count = notes?.notes.length ?? 0;
+        const request = [
+            t('notes.checkDraft', { title: identity.title, id: identity.entryId }),
+            ...(count > 0 ? [t('notes.checkDraftNotes', { count })] : []),
+        ].join('\n');
+        props.setDraft(mergedDraft(props.readDraft(), request));
+        remember();
+    }, [identity, notes, t, props, remember]);
+    // 让Agent润色译文: the request into the draft, like 考考我 (the reader adds a wish and sends it).
+    const polish = useCallback((total, from) => {
+        if (identity === undefined)
+            return;
+        const request = from === undefined
+            ? t('polish.draft', { title: identity.title, id: identity.entryId, count: total })
+            : t('polish.continueDraft', { title: identity.title, id: identity.entryId, count: total, from });
+        props.setDraft(mergedDraft(props.readDraft(), request));
+        remember();
+    }, [identity, t, props, remember]);
+    return {
+        polish,
+        sync,
+        addReply,
+        editReply,
+        deleteDiscussion,
+        jumpPara,
+        check,
+        tab,
+        setTab: switchTab,
+        entry: notes,
+        count: notes?.notes.length ?? 0,
+        missing,
+        sheet,
+        saving,
+        failed,
+        hint,
+        startNote,
+        saveNote,
+        cancelSheet: () => { setSheet(null); },
+        jump,
+        edit,
+        remove,
+        discuss,
+        canOpenSession: props.canOpenSession(),
+        openSession: id => { props.openSession(id); },
+        sessionTitle: id => sessions[id]?.displayTitle,
+    };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * The 润色 layer in the detail view: the agent's paragraph translations
+ * (written back through `reader_translate`) shown in place of the browser's
+ * machine translation.
+ *
+ * Each polished block gets, once: its own content wrapped in
+ * `span[data-reader-orig-run]` (whatever the machine translation does inside
+ * it), the 润色 text in `div[data-reader-polish]` with a 「✦ 润色」 tag, and
+ * the original text in `div[data-reader-polish-orig]` — the article's
+ * `data-polish-view` then decides which of them show:
+ * - `trans`: the 润色 alone; `both`: the 润色 over the original;
+ * - `orig` / none: the block as it was.
+ * Without a machine translation running the 润色 shows side by side (both);
+ * with one, the globe's view applies. 「看机翻」 hides the layer for this
+ * visit only (not remembered — the 润色 is the default, 2026-10-20).
+ *
+ * @module @khorsheed/dsh-reader/client/usePolish
+ */
+import { type MutableRefObject } from 'react';
+import type { ReaderPolishView } from '../types.ts';
+import type { ReaderPaneProps } from './contract.ts';
+export interface UsePolishInput {
+    readonly entryId: string | undefined;
+    readonly articleHtml: string | null;
+    readonly articleRef: MutableRefObject<HTMLDivElement | null>;
+    /** The globe's state: the view applies only while a machine translation runs. */
+    readonly translating: boolean;
+    readonly translateView: 'trans' | 'both' | 'orig';
+    readonly remote: Pick<ReaderPaneProps, 'polish' | 'setPolishOff'>;
+    readonly tagLabel: string;
+    /** The tag's tooltip: clicking it puts this paragraph back to the machine translation. */
+    readonly tagTitle: string;
+}
+export interface PolishFace {
+    readonly view: ReaderPolishView | undefined;
+    /** Polishing has stopped short (no write for a while): offer to continue. */
+    readonly stalled: boolean;
+    /** The layer is hidden for this visit (「看机翻」). */
+    readonly hidden: boolean;
+    readonly setHidden: (hidden: boolean) => void;
+    /** The reader sent the request: watch for the first batch. */
+    readonly requested: () => void;
+    /** A request went into the draft and nothing has come back yet. */
+    readonly awaiting: boolean;
+}
+export declare function usePolish(input: UsePolishInput): PolishFace;
+//# sourceMappingURL=usePolish.d.ts.map

package/lib/types/client/usePolish.js

@@ -0,0 +1,162 @@
+/**
+ * The 润色 layer in the detail view: the agent's paragraph translations
+ * (written back through `reader_translate`) shown in place of the browser's
+ * machine translation.
+ *
+ * Each polished block gets, once: its own content wrapped in
+ * `span[data-reader-orig-run]` (whatever the machine translation does inside
+ * it), the 润色 text in `div[data-reader-polish]` with a 「✦ 润色」 tag, and
+ * the original text in `div[data-reader-polish-orig]` — the article's
+ * `data-polish-view` then decides which of them show:
+ * - `trans`: the 润色 alone; `both`: the 润色 over the original;
+ * - `orig` / none: the block as it was.
+ * Without a machine translation running the 润色 shows side by side (both);
+ * with one, the globe's view applies. 「看机翻」 hides the layer for this
+ * visit only (not remembered — the 润色 is the default, 2026-10-20).
+ *
+ * @module @khorsheed/dsh-reader/client/usePolish
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { blockElements } from "./notes.js";
+/** How often an article being polished is re-read (ms). */
+const POLL_MS = 5000;
+/** After the reader sends the request, poll this long for the first batch (ms). */
+const AWAIT_FIRST_MS = 20 * 60_000;
+/** A layer untouched this long, and not complete, has stalled (ms). */
+const STALLED_MS = 3 * 60_000;
+/** Decorations that are not the paragraph's own content. */
+const DECORATION = '[data-reader-ts],[data-reader-spk],[data-reader-polish],[data-reader-polish-orig],[data-reader-orig-run]';
+/** The original text of each top-level block of an article body. */
+function originals(html) {
+    const doc = new DOMParser().parseFromString(`<div>${html}</div>`, 'text/html');
+    const root = doc.body.firstElementChild;
+    return root === null ? [] : [...root.children].map(child => (child.textContent ?? '').replace(/\s+/g, ' ').trim());
+}
+export function usePolish(input) {
+    const { entryId, articleHtml, articleRef, translating, translateView, remote, tagLabel, tagTitle } = input;
+    const [viewOf, setViewOf] = useState(undefined);
+    const view = viewOf !== undefined && viewOf.entryId === entryId ? viewOf.view : undefined;
+    const [hiddenFor, setHiddenFor] = useState(null);
+    const hidden = hiddenFor !== null && hiddenFor === entryId;
+    const [awaitingSince, setAwaitingSince] = useState(null);
+    const remoteRef = useRef(remote);
+    remoteRef.current = remote;
+    const read = useCallback((id) => {
+        void remoteRef.current.polish({ entryId: id }).then(answer => {
+            if (answer.ok)
+                setViewOf({ entryId: id, view: answer.value ?? undefined });
+        });
+    }, []);
+    useEffect(() => {
+        setAwaitingSince(null);
+        if (entryId !== undefined && articleHtml !== null && articleHtml !== '')
+            read(entryId);
+    }, [entryId, articleHtml, read]);
+    // Poll while the agent is (or may soon be) writing.
+    const now = Date.now();
+    const fresh = view !== undefined && !view.complete && now - Date.parse(view.updatedAt) < STALLED_MS;
+    const awaiting = awaitingSince !== null && now - awaitingSince < AWAIT_FIRST_MS && (view === undefined || !view.complete);
+    useEffect(() => {
+        if (entryId === undefined || (!fresh && !awaiting))
+            return undefined;
+        const timer = setInterval(() => { read(entryId); }, POLL_MS);
+        return () => { clearInterval(timer); };
+    }, [entryId, fresh, awaiting, read]);
+    const sources = useMemo(() => (articleHtml === null ? [] : originals(articleHtml)), [articleHtml]);
+    // Decorate polished blocks; undecorate ones that are no longer.
+    useEffect(() => {
+        const article = articleRef.current;
+        if (article === null)
+            return;
+        const blocks = blockElements(article);
+        const off = new Set(view?.off ?? []);
+        blocks.forEach((block, index) => {
+            const text = view?.paragraphs[String(index + 1)];
+            const polishedHere = text !== undefined && !off.has(index + 1);
+            let polish = block.querySelector(':scope > [data-reader-polish]');
+            if (!polishedHere) {
+                if (polish !== null) {
+                    block.querySelector(':scope > [data-reader-polish-orig]')?.remove();
+                    polish.remove();
+                    block.removeAttribute('data-polished');
+                }
+                return;
+            }
+            const doc = block.ownerDocument;
+            // The block's own content, wrapped once so CSS can hide it.
+            if (block.querySelector(':scope > [data-reader-orig-run]') === null) {
+                const run = doc.createElement('span');
+                run.setAttribute('data-reader-orig-run', '1');
+                for (const node of [...block.childNodes]) {
+                    if (node instanceof Element && node.matches(DECORATION))
+                        continue;
+                    run.append(node);
+                }
+                block.append(run);
+            }
+            if (polish === null) {
+                polish = doc.createElement('div');
+                polish.setAttribute('data-reader-polish', '1');
+                polish.setAttribute('data-reader-no-translate', '1');
+                const orig = doc.createElement('div');
+                orig.setAttribute('data-reader-polish-orig', '1');
+                orig.setAttribute('data-reader-no-translate', '1');
+                block.append(polish, orig);
+            }
+            const body = text.replace(/^\[\d+(?::\d+){1,2}\]\s*/, '');
+            if (polish.getAttribute('data-text') !== body) {
+                polish.setAttribute('data-text', body);
+                polish.textContent = body;
+                const tag = doc.createElement('button');
+                tag.type = 'button';
+                tag.setAttribute('data-reader-polish-tag', String(index + 1));
+                tag.setAttribute('data-label', tagLabel);
+                tag.title = tagTitle;
+                polish.append(tag);
+            }
+            const orig = block.querySelector(':scope > [data-reader-polish-orig]');
+            if (orig !== null)
+                orig.textContent = (sources[index] ?? '').replace(/^\d+:\d+(?::\d+)?\s*/, '');
+            block.setAttribute('data-polished', '1');
+        });
+    }, [view, articleHtml, articleRef, sources, tagLabel, tagTitle]);
+    // Which layer the article shows.
+    useEffect(() => {
+        const article = articleRef.current;
+        if (article === null)
+            return;
+        const mode = view === undefined || hidden ? null : translating ? translateView : 'both';
+        if (mode === null || mode === 'orig')
+            article.removeAttribute('data-polish-view');
+        else
+            article.setAttribute('data-polish-view', mode);
+    }, [view, hidden, translating, translateView, articleRef, articleHtml]);
+    // The 「✦ 润色」 tag: this paragraph back to the machine translation.
+    useEffect(() => {
+        const article = articleRef.current;
+        if (article === null || entryId === undefined)
+            return undefined;
+        const onClick = (event) => {
+            const tag = event.target?.closest?.('[data-reader-polish-tag]');
+            if (tag === null || tag === undefined)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            const paragraph = Number(tag.getAttribute('data-reader-polish-tag'));
+            void remoteRef.current.setPolishOff({ entryId, paragraph, off: true }).then(answer => {
+                if (answer.ok)
+                    setViewOf({ entryId, view: answer.value ?? undefined });
+            });
+        };
+        article.addEventListener('click', onClick, true);
+        return () => { article.removeEventListener('click', onClick, true); };
+    }, [entryId, articleRef]);
+    return {
+        view,
+        stalled: view !== undefined && !view.complete && !fresh,
+        hidden,
+        setHidden: (value) => { setHiddenFor(value && entryId !== undefined ? entryId : null); },
+        requested: () => { setAwaitingSince(Date.now()); },
+        awaiting: awaiting && view === undefined,
+    };
+}