@khorsheed/dsh-reader 0.2.0

package/lib/types/client/translate.js

@@ -0,0 +1,873 @@
+/**
+ * The target tags to try, in order.
+ *
+ * Chrome's documented list spells Chinese `zh` (Simplified) and `zh-Hant`
+ * (Traditional), and `zh` is what works on the machines this was built on — but
+ * `Translator.create()` has been observed rejecting a pair that
+ * `availability()` had just blessed (`NotSupportedError`, "Unable to create
+ * translator for the given source and target language", macOS builds included).
+ * Trying the next spelling costs one rejected call and turns a dead button into
+ * a working one where a build prefers the other tag.
+ */
+export const TARGET_CANDIDATES = ['zh', 'zh-Hans'];
+/** The unit separator inside a batch. Rare, short, and verified on the way back. */
+export const UNIT_SEPARATOR = '⟦|⟧';
+/** Stop packing a batch once it holds this many characters (or units). */
+const BATCH_MAX_CHARS = 1200;
+const BATCH_MAX_UNITS = 12;
+/** How many remembered sentences the translation memory keeps before evicting. */
+const MEMORY_MAX_ENTRIES = 4000;
+/** `NodeFilter.SHOW_TEXT`, spelled numerically so no global is required. */
+const SHOW_TEXT = 4;
+/** Tokens that end in a period without ending a sentence. */
+const ABBREVIATIONS = new Set([
+    'mr', 'mrs', 'ms', 'dr', 'prof', 'sr', 'jr', 'st', 'vs', 'etc', 'e.g', 'i.e', 'fig', 'no',
+    'inc', 'ltd', 'co', 'corp', 'dept', 'univ', 'approx', 'cf', 'ed', 'eds', 'est', 'vol',
+    'ch', 'sec', 'pp', 'u.s', 'u.k', 'u.n', 'al', 'eq', 'ref',
+]);
+/** Read the page's Translator API, or null when this browser has none. */
+export function detectTranslator(scope = globalThis) {
+    const candidate = scope.Translator;
+    if (candidate === undefined || candidate === null)
+        return null;
+    const api = candidate;
+    if (typeof api.availability !== 'function' || typeof api.create !== 'function')
+        return null;
+    return candidate;
+}
+/** Read the page's Language Detector, or null when this browser has none. */
+export function detectLanguageDetector(scope = globalThis) {
+    const candidate = scope.LanguageDetector;
+    if (candidate === undefined || candidate === null)
+        return null;
+    const api = candidate;
+    if (typeof api.availability !== 'function' || typeof api.create !== 'function')
+        return null;
+    return candidate;
+}
+/**
+ * The body's source language: the browser's detector when it has one, else the
+ * caller's script guess.
+ *
+ * The probe is only worth it because a WRONG source is fatal in a way the
+ * reader cannot see: `create()` rejects for a pair the device does not have, and
+ * the error says "given source and target language" without naming either. The
+ * heuristic that decides this in the pane (`isCjk`) is a script test, not a
+ * language test — it cannot tell German from English.
+ *
+ * @param text - the body's leading text (a sample is enough).
+ * @param fallback - the caller's guess, used when detection is unavailable or unsure.
+ * @returns the BCP-47 tag to ask the translator for.
+ */
+export async function detectSourceLanguage(text, fallback) {
+    const detector = detectLanguageDetector();
+    if (detector === null)
+        return fallback;
+    const sample = text.slice(0, 600).trim();
+    if (sample.length < 20)
+        return fallback;
+    try {
+        const state = await detector.availability();
+        if (state === 'unavailable')
+            return fallback;
+        const session = await detector.create();
+        const results = await session.detect(sample);
+        session.destroy?.();
+        const best = results[0];
+        if (best !== undefined && best.confidence >= 0.5 && typeof best.detectedLanguage === 'string') {
+            return best.detectedLanguage;
+        }
+    }
+    catch {
+        // Degrade to the caller's guess: a failed detection must never block a
+        // translation that would otherwise work.
+    }
+    return fallback;
+}
+/** True when the browser says this pair is not something it can ever build. */
+export function isUnsupported(error) {
+    if (typeof DOMException !== 'undefined' && error instanceof DOMException && error.name === 'NotSupportedError')
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /given source and target|not supported|unsupported language/i.test(message);
+}
+/**
+ * Create a translator, trying every candidate pair in order.
+ *
+ * `availability()` is a hint, not a promise: this browser has been observed
+ * blessing a pair and then rejecting `create()` for it. So the pairs are tried
+ * for real, the failures are collected (the reader gets to see which pair was
+ * asked for), and `unsupported` says whether the browser rejected EVERY attempt
+ * as an unsupported language pair — which is a permanent condition, unlike a
+ * download or a quota failure.
+ *
+ * @param api - the page's Translator API.
+ * @param request - the source candidates, the target candidates, and the monitor.
+ * @returns the first working session, or the collected attempts.
+ */
+export async function createSession(api, request) {
+    const attempts = [];
+    let unsupported = true;
+    let tried = 0;
+    for (const sourceLanguage of request.sources) {
+        for (const targetLanguage of request.targets) {
+            tried += 1;
+            try {
+                const state = await api.availability({ sourceLanguage, targetLanguage });
+                if (state === 'unavailable') {
+                    attempts.push({ sourceLanguage, targetLanguage, reason: 'unavailable' });
+                    continue;
+                }
+            }
+            catch (error) {
+                attempts.push({ sourceLanguage, targetLanguage, reason: error instanceof Error ? error.message : String(error) });
+                unsupported = false;
+                continue;
+            }
+            try {
+                const session = await api.create({ sourceLanguage, targetLanguage, ...(request.monitor === undefined ? {} : { monitor: request.monitor }) });
+                return { ok: true, session, sourceLanguage, targetLanguage };
+            }
+            catch (error) {
+                const reason = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+                if (!isUnsupported(error))
+                    unsupported = false;
+                attempts.push({ sourceLanguage, targetLanguage, reason });
+            }
+        }
+    }
+    return { ok: false, attempts, unsupported: unsupported && tried > 0 };
+}
+/**
+ * Split one run of text into sentence pieces.
+ *
+ * Conservative by construction: a split needs a terminator followed by
+ * whitespace (or the end), a token that is neither a known abbreviation nor a
+ * single initial, and a next character that does not continue a number. When
+ * any rule is unsure it does NOT split — one oversized unit only costs
+ * granularity, while a wrong split hands the model two broken half-sentences.
+ *
+ * @param text - the run's core text (already trimmed at both ends).
+ * @returns the pieces in order; a run with no terminator comes back as one.
+ */
+export function splitSentences(text) {
+    if (text.length === 0)
+        return [];
+    const pieces = [];
+    let start = 0;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (!'.!?。！？…'.includes(ch)) {
+            i += 1;
+            continue;
+        }
+        // A run of terminators ("?!", "…") ends at its last character.
+        let end = i;
+        while (end + 1 < text.length && '.!?。！？…'.includes(text[end + 1]))
+            end += 1;
+        const next = text[end + 1];
+        // Latin terminators need a following break, plus the abbreviation and
+        // decimal checks below. CJK terminators are unambiguous and are written
+        // without a following space, so they stand on their own.
+        if ('.!?…'.includes(ch)) {
+            if (next !== undefined && !/\s/.test(next)) {
+                i = end + 1;
+                continue;
+            }
+            const lastWord = /([A-Za-z][A-Za-z.]*)$/.exec(text.slice(start, end + 1))?.[1] ?? '';
+            const bare = lastWord.replace(/\.$/, '').toLowerCase();
+            if (ABBREVIATIONS.has(bare) || /^[a-z]$/.test(bare)) {
+                i = end + 1;
+                continue;
+            }
+            const after = text.slice(end + 1).trimStart()[0];
+            if (/\d$/.test(text[end]) && after !== undefined && /\d/.test(after)) {
+                i = end + 1;
+                continue;
+            }
+        }
+        // The piece keeps the whitespace that follows the terminator, so joining the
+        // pieces reproduces the run byte for byte.
+        let cut = end + 1;
+        while (cut < text.length && /\s/.test(text[cut]))
+            cut += 1;
+        pieces.push({ text: text.slice(start, cut), core: text.slice(start, end + 1).trim() });
+        start = cut;
+        i = cut;
+    }
+    if (start < text.length) {
+        const tail = text.slice(start);
+        pieces.push({ text: tail, core: tail.trim() });
+    }
+    return pieces.filter(piece => piece.core.length > 0);
+}
+/** The segmentation of each article root, so views can be re-applied cheaply. */
+const BUILT = new WeakMap();
+/** Translation memory: original sentence → translated sentence. */
+const MEMORY = new Map();
+/**
+ * The memory key for one sentence.
+ *
+ * The pair is part of the key: before the host-backed store existed, the page's
+ * memory keyed on the sentence ALONE, so a German title and its English
+ * homograph would have shared one translation. (The hash in the persisted tier
+ * is computed the same way per pair for the same reason.)
+ */
+const memoryKey = (pair, text) => `${pair}\n${text}`;
+/**
+ * The stable key fragment for one sentence (or a whole body).
+ *
+ * FNV-1a over 64 bits: synchronous, which the crypto API is not, and long
+ * enough that the memory's 50k entries never meet a collision (the birthday
+ * bound is ~2^32 entries). The host stores the digest opaquely — only the
+ * browser ever computes it.
+ */
+export function translationHash(text) {
+    let hash = 0xcbf29ce484222325n;
+    for (let index = 0; index < text.length; index += 1) {
+        hash = (hash ^ BigInt(text.charCodeAt(index))) * 0x100000001b3n & 0xffffffffffffffffn;
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+/** Blocks whose text is a code or data payload, never prose. */
+const SKIP_ANCESTORS = 'pre, code, kbd, samp, [data-reader-no-translate]';
+/** Elements that can host prose blocks. */
+const BLOCK_SELECTOR = 'p, li, h1, h2, h3, h4, h5, h6, blockquote, dd, dt, figcaption, td, th';
+/** True when a run carries prose worth translating. */
+function translatable(core) {
+    if (core.length < 2)
+        return false;
+    if (!/[A-Za-z\u00c0-\u024f\u0400-\u04ff]/.test(core))
+        return false;
+    if (/^(https?:\/\/|www\.)\S+$/i.test(core))
+        return false;
+    return true;
+}
+/** The block a text node belongs to, and where its reveal should live. */
+function blockFor(node) {
+    const parent = node.parentElement;
+    if (parent === null)
+        return null;
+    if (parent.closest(SKIP_ANCESTORS) !== null)
+        return null;
+    const found = parent.closest(BLOCK_SELECTOR);
+    if (found !== null) {
+        // A `p` or a heading cannot legally contain a block, so its reveal is a
+        // sibling; everything else (li, blockquote, td…) opens its own container.
+        const tag = found.tagName;
+        return { element: found, placement: tag === 'P' || /^H[1-6]$/.test(tag) ? 'sibling' : 'inside' };
+    }
+    // NO block between this run and the article root. `extract-article` really
+    // does emit a body as bare text (a one-line feed item), and skipping those
+    // runs meant a whole article silently refused to translate. The run's own
+    // parent is the block here, and the reveal follows the run's last sentence.
+    return { element: parent, placement: 'inline' };
+}
+/**
+ * Segment one rendered article into sentence spans.
+ *
+ * Idempotent: a second call for the same element returns the first result, so a
+ * view switch never double-wraps. Mutates the DOM under `root` (each prose text
+ * node is replaced by spans); {@link restoreArticle} undoes it completely.
+ *
+ * @param root - the container holding the normalized article markup.
+ * @param classes - the hashed class names the spans and reveals carry.
+ * @returns the segmentation, or null when there is nothing to translate.
+ */
+export function buildArticle(root, classes) {
+    const existing = BUILT.get(root);
+    if (existing !== undefined)
+        return existing;
+    const walker = root.ownerDocument.createTreeWalker(root, SHOW_TEXT);
+    const nodes = [];
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode())
+        nodes.push(node);
+    const blocks = [];
+    const restores = [];
+    const blockIndex = new Map();
+    for (const node of nodes) {
+        const raw = node.nodeValue ?? '';
+        const lead = /^\s*/.exec(raw)?.[0] ?? '';
+        const tail = /\s*$/.exec(raw)?.[0] ?? '';
+        const core = raw.slice(lead.length, raw.length - tail.length);
+        if (!translatable(core))
+            continue;
+        const host = blockFor(node);
+        if (host === null)
+            continue;
+        const pieces = splitSentences(core);
+        if (pieces.length === 0)
+            continue;
+        const doc = root.ownerDocument;
+        const spans = [];
+        const segments = [];
+        // The original node STAYS in the DOM (holding the leading whitespace) so the
+        // restore path has something to write back to; the spans follow it.
+        node.nodeValue = lead;
+        let anchor = node;
+        for (const piece of pieces) {
+            const span = doc.createElement('span');
+            span.className = classes.unit;
+            span.setAttribute('data-reader-unit', '1');
+            span.textContent = piece.text;
+            anchor.after(span);
+            anchor = span;
+            spans.push(span);
+            const pieceTail = piece.text.slice(piece.core.length);
+            segments.push({
+                span,
+                original: piece.core,
+                lead: segments.length === 0 ? lead : '',
+                tail: pieceTail,
+                gap: segments.length === pieces.length - 1 ? tail : '',
+                translated: null,
+                open: false,
+            });
+        }
+        const tailNode = doc.createTextNode(tail);
+        anchor.after(tailNode);
+        let block = blockIndex.get(host.element);
+        if (block === undefined) {
+            block = { element: host.element, placement: host.placement, segments: [], flat: '', sentences: [], reveal: null };
+            blockIndex.set(host.element, block);
+            blocks.push(block);
+        }
+        block.segments.push(...segments);
+        restores.push({ node, lead, core, tail, tailNode, spans });
+    }
+    if (blocks.length === 0)
+        return null;
+    // Flatten each block's ORIGINAL prose and re-cut it into sentences. Inline
+    // markup (a link inside a sentence) split that sentence into several units;
+    // the reveal must still show the WHOLE sentence, or the original reads as
+    // fragments — the shape the reader reported as "sparse".
+    for (const block of blocks) {
+        let flat = '';
+        for (const segment of block.segments) {
+            flat += segment.lead;
+            flat += segment.original;
+            flat += segment.tail;
+            flat += segment.gap;
+        }
+        const sentences = [];
+        let cursor = 0;
+        for (const piece of splitSentences(flat)) {
+            const end = cursor + piece.text.length;
+            sentences.push({ start: cursor, end });
+            cursor = end;
+        }
+        if (sentences.length === 0)
+            sentences.push({ start: 0, end: flat.length });
+        block.flat = flat;
+        block.sentences = sentences;
+    }
+    const built = { root, blocks, restores, view: 'trans' };
+    BUILT.set(root, built);
+    return built;
+}
+/** Take the segmentation back out, restoring every original text node. */
+export function restoreArticle(root) {
+    const built = BUILT.get(root);
+    if (built === undefined)
+        return;
+    for (const record of built.restores) {
+        for (const span of record.spans)
+            span.remove();
+        record.tailNode.remove();
+        record.node.nodeValue = record.lead + record.core + record.tail;
+    }
+    for (const block of built.blocks)
+        block.reveal?.remove();
+    BUILT.delete(root);
+    root.removeAttribute('data-reader-translated');
+}
+/** The text one segment shows in a view, whitespace included. */
+function segmentText(segment, view) {
+    if (view === 'orig')
+        return segment.original + segment.tail;
+    return (segment.translated ?? segment.original) + segment.tail;
+}
+/** Where one unit starts inside its block's flattened original text. */
+function offsetOf(block, segment) {
+    let offset = 0;
+    for (const candidate of block.segments) {
+        if (candidate === segment)
+            return offset + candidate.lead.length;
+        offset += candidate.lead.length + candidate.original.length + candidate.tail.length + candidate.gap.length;
+    }
+    return offset;
+}
+/** The sentence one unit belongs to. */
+function sentenceIndexOf(block, segment) {
+    const offset = offsetOf(block, segment);
+    const index = block.sentences.findIndex(sentence => offset >= sentence.start && offset < sentence.end);
+    return index === -1 ? 0 : index;
+}
+/** The sentences of a block that a set of units belongs to, in order. */
+function sentencesFor(block, segments) {
+    const indexes = new Set();
+    for (const segment of segments) {
+        const offset = offsetOf(block, segment);
+        let index = block.sentences.findIndex(sentence => offset >= sentence.start && offset < sentence.end);
+        if (index === -1)
+            index = 0;
+        indexes.add(index);
+    }
+    return [...indexes].sort((left, right) => left - right);
+}
+/** Render one block's reveal container for the sentences currently shown. */
+function paintReveal(block, view, classes) {
+    const shown = view === 'both' ? block.sentences.map((_, index) => index) : sentencesFor(block, block.segments.filter(segment => segment.open));
+    if (shown.length === 0 || view === 'orig') {
+        block.reveal?.remove();
+        block.reveal = null;
+        return;
+    }
+    const doc = block.element.ownerDocument;
+    const reveal = block.reveal ?? doc.createElement('div');
+    reveal.className = classes.reveal;
+    reveal.setAttribute('data-reader-reveal', '1');
+    // The spacing depends on WHERE the container sits: a sibling of a paragraph
+    // can be pulled up into that paragraph's bottom margin, while one inside a
+    // list item has nothing to collapse with and would be dragged into the
+    // translation line (reported from the bulleted case).
+    reveal.setAttribute('data-placement', block.placement);
+    reveal.textContent = '';
+    for (const index of shown) {
+        const sentence = block.sentences[index];
+        if (sentence === undefined)
+            continue;
+        const line = doc.createElement('p');
+        line.className = classes.line;
+        line.textContent = block.flat.slice(sentence.start, sentence.end).trim();
+        line.setAttribute('data-reader-sentence', String(index));
+        // The pairing mark: this line is the original of an OPENED translation, so
+        // clicking a sentence lights both sides of the pair up.
+        const opened = block.segments.some(segment => segment.open && sentencesFor(block, [segment]).includes(index));
+        if (opened)
+            line.setAttribute('data-open', '1');
+        reveal.append(line);
+    }
+    if (block.reveal === null) {
+        block.reveal = reveal;
+        if (block.placement === 'sibling')
+            block.element.after(reveal);
+        else if (block.placement === 'inside')
+            block.element.append(reveal);
+        else
+            block.segments[block.segments.length - 1]?.span.after(reveal);
+    }
+}
+/** Paint the spans and the reveals for one view. */
+export function setView(built, view, classes) {
+    built.view = view;
+    const anyTranslated = built.blocks.some(block => block.segments.some(segment => segment.translated !== null));
+    for (const block of built.blocks) {
+        for (const segment of block.segments) {
+            const text = segmentText(segment, view);
+            if (segment.span.textContent !== text)
+                segment.span.textContent = text;
+            if (segment.open)
+                segment.span.setAttribute('data-open', '1');
+            else
+                segment.span.removeAttribute('data-open');
+            // The pair is addressed by SENTENCE, not by unit: a sentence cut into
+            // fragments still has one original line, and hovering any of its
+            // fragments must light that one line.
+            segment.span.setAttribute('data-reader-sentence', String(sentenceIndexOf(block, segment)));
+        }
+        paintReveal(block, view, classes);
+    }
+    // `pending` until the first unit lands: the translated typography (CJK
+    // leading) must not be applied to text that is still English.
+    built.root.setAttribute('data-reader-translated', anyTranslated ? view : 'pending');
+}
+/** The units of one block sentence, in order. */
+function spansOfSentence(block, index) {
+    return block.segments
+        .filter(segment => sentenceIndexOf(block, segment) === index)
+        .map(segment => segment.span);
+}
+/** The reveal line that shows one block sentence, when it is on screen. */
+function lineOfSentence(block, index) {
+    if (block.reveal === null)
+        return null;
+    return block.reveal.querySelector(`[data-reader-sentence="${String(index)}"]`);
+}
+/**
+ * Mark (or clear) the pair under the pointer.
+ *
+ * The page is deliberately CLEAN by default: an expanded original carries no
+ * standing colour or bar, because a reader who explores a few sentences would
+ * otherwise leave the whole article speckled — reported as "the page gets
+ * messy". The pairing shows up on hover instead, from either side: point at a
+ * translated sentence and its original line lights up, point at an original
+ * line and the sentence it belongs to lights up.
+ *
+ * @param built - the live segmentation.
+ * @param target - what the pointer is over (or just left).
+ * @param on - true on hover, false when the pointer leaves.
+ */
+export function setPairHover(built, target, on) {
+    if (!(target instanceof Element))
+        return;
+    const mark = (element) => {
+        if (element === null || element === undefined)
+            return;
+        if (on)
+            element.setAttribute('data-hover', '1');
+        else
+            element.removeAttribute('data-hover');
+    };
+    const unit = target.closest('[data-reader-unit]');
+    if (unit !== null) {
+        for (const block of built.blocks) {
+            const segment = block.segments.find(candidate => candidate.span === unit);
+            if (segment === undefined)
+                continue;
+            const index = sentenceIndexOf(block, segment);
+            for (const span of spansOfSentence(block, index))
+                mark(span);
+            mark(lineOfSentence(block, index));
+            return;
+        }
+        return;
+    }
+    const line = target.closest('[data-reader-sentence]');
+    if (line === null)
+        return;
+    for (const block of built.blocks) {
+        if (block.reveal === null || !block.reveal.contains(line))
+            continue;
+        const index = Number(line.getAttribute('data-reader-sentence'));
+        mark(line);
+        for (const span of spansOfSentence(block, index))
+            mark(span);
+        return;
+    }
+}
+/** The segment a click landed on, if any. */
+export function segmentAt(built, target) {
+    if (!(target instanceof Element))
+        return null;
+    const span = target.closest('[data-reader-unit]');
+    if (span === null)
+        return null;
+    for (const block of built.blocks) {
+        const found = block.segments.find(segment => segment.span === span);
+        if (found !== undefined)
+            return found;
+    }
+    return null;
+}
+/** Flip one sentence's original open / closed (the click gesture). */
+export function toggleSegment(built, segment, classes) {
+    segment.open = !segment.open;
+    if (segment.open)
+        segment.span.setAttribute('data-open', '1');
+    else
+        segment.span.removeAttribute('data-open');
+    for (const block of built.blocks) {
+        if (block.segments.includes(segment)) {
+            paintReveal(block, built.view, classes);
+            return;
+        }
+    }
+}
+/** Remember one translation, evicting oldest-first past the memory's cap. */
+function remember(pair, text, translated) {
+    const key = memoryKey(pair, text);
+    if (text.length === 0 || MEMORY.has(key))
+        return;
+    MEMORY.set(key, translated);
+    if (MEMORY.size > MEMORY_MAX_ENTRIES) {
+        const oldest = MEMORY.keys().next().value;
+        if (oldest !== undefined)
+            MEMORY.delete(oldest);
+    }
+}
+/**
+ * Record a translated unit: in the DOM, and in the translation memory.
+ *
+ * @param pair - the `<src>→<tgt>` label this translation belongs to.
+ */
+export function applyTranslation(built, segment, translated, pair) {
+    segment.translated = translated;
+    if (built.view !== 'orig')
+        segment.span.textContent = translated + segment.tail;
+    remember(pair, segment.original, translated);
+}
+/** A remembered translation for this sentence in this pair, when one exists. */
+export function remembered(pair, text) {
+    return MEMORY.get(memoryKey(pair, text));
+}
+/**
+ * Pour translations the host persisted into the page's memory.
+ *
+ * The pane calls this before a translation run spends the model: every primed
+ * sentence paints from memory instead of a request. Entries already in the page
+ * are left alone (a fresher in-page write wins over the host's copy of it).
+ *
+ * @param pair - the pair label the translations belong to.
+ * @param entries - the sentences and their translations.
+ * @returns how many were new to the page.
+ */
+export function primeMemory(pair, entries) {
+    let primed = 0;
+    for (const { text, translation } of entries) {
+        if (text.length === 0)
+            continue;
+        const key = memoryKey(pair, text);
+        if (MEMORY.has(key))
+            continue;
+        MEMORY.set(key, translation);
+        primed += 1;
+    }
+    while (MEMORY.size > MEMORY_MAX_ENTRIES) {
+        const oldest = MEMORY.keys().next().value;
+        if (oldest === undefined)
+            break;
+        MEMORY.delete(oldest);
+    }
+    return primed;
+}
+/** Drop the translation memory (the specs call this between cases). */
+export function clearMemory() {
+    MEMORY.clear();
+}
+/* ------------------------------------------------------- text (not DOM) units */
+/**
+ * True when a string is already (mostly) the target language, so translating it
+ * would be Chinese-into-Chinese.
+ *
+ * The wall is where this matters: a wall mixes Chinese and English entries, and
+ * one card can even mix them field by field (a Chinese title with an English
+ * summary). The ratio mirrors the pane's own script test, and it is deliberately
+ * the CHEAP synchronous answer — the alternative was a Language Detector round
+ * trip per field for a decision a character count already gets right.
+ *
+ * @param text - the field's text.
+ * @returns true when the field should be left alone.
+ */
+export function isTargetLanguage(text) {
+    const trimmed = text.trim();
+    if (trimmed.length < 2)
+        return true;
+    const cjk = trimmed.match(/[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/g);
+    return (cjk?.length ?? 0) / trimmed.length > 0.2;
+}
+/**
+ * One learned (or recalled) sentence, ready for the host's tiers.
+ *
+ * The hash is over the sentence alone; the pair joins the key on the HOST
+ * (`<src>→<tgt>:<hash>`), which is where the pair-keying invariant lives.
+ *
+ * @param source - the original sentence.
+ * @param target - its translation.
+ */
+function learnOf(source, target) {
+    return { hash: translationHash(source), source, target };
+}
+/**
+ * Translate a list of whole strings — the wall's cards, where a field is the
+ * unit and there is no DOM to segment.
+ *
+ * The batching contract is the article's, unchanged: sentences joined by the
+ * separator, accepted only when the same number of parts comes back, and a
+ * rejected batch re-sent one string at a time so the fallback gives up
+ * granularity rather than correctness. Results land in the same translation
+ * memory the article uses, so a card title translated here is not translated
+ * again when the same entry is opened.
+ *
+ * @param texts - the strings to translate, in order.
+ * @param pair - the `<src>→<tgt>` label these translations belong to.
+ * @param session - a translator for this source language.
+ * @param cancelled - checked between batches.
+ * @param onProgress - called with (done, total) as results land.
+ * @returns the translations, the remembered count and the failures.
+ */
+export async function translateTexts(texts, pair, session, cancelled, onProgress) {
+    const translated = new Map();
+    const unique = [...new Set(texts.filter(text => text.length > 0 && !isTargetLanguage(text)))];
+    const total = unique.length;
+    let done = 0;
+    let rememberedCount = 0;
+    let failed = 0;
+    const learned = [];
+    const recalled = [];
+    const report = () => { onProgress?.(done, total); };
+    const pending = [];
+    for (const text of unique) {
+        const hit = MEMORY.get(memoryKey(pair, text));
+        if (hit !== undefined) {
+            translated.set(text, hit);
+            recalled.push(learnOf(text, hit));
+            done += 1;
+            rememberedCount += 1;
+        }
+        else {
+            pending.push(text);
+        }
+    }
+    report();
+    let batch = [];
+    let chars = 0;
+    const flush = async () => {
+        if (batch.length === 0)
+            return;
+        const current = batch;
+        batch = [];
+        chars = 0;
+        if (cancelled())
+            return;
+        const parts = await translateBatch(current, session);
+        if (parts !== null) {
+            current.forEach((text, index) => {
+                const value = parts[index].trim();
+                translated.set(text, value);
+                remember(pair, text, value);
+                learned.push(learnOf(text, value));
+                done += 1;
+            });
+            report();
+            return;
+        }
+        for (const text of current) {
+            if (cancelled())
+                return;
+            try {
+                const value = (await session.translate(text)).trim();
+                translated.set(text, value);
+                remember(pair, text, value);
+                learned.push(learnOf(text, value));
+                done += 1;
+            }
+            catch {
+                failed += 1;
+            }
+            report();
+        }
+    };
+    for (const text of pending) {
+        if (cancelled())
+            break;
+        if (batch.length > 0 && (chars + text.length > BATCH_MAX_CHARS || batch.length >= BATCH_MAX_UNITS))
+            await flush();
+        if (cancelled())
+            break;
+        batch.push(text);
+        chars += text.length;
+    }
+    await flush();
+    return { translated, remembered: rememberedCount, failed, learned, recalled };
+}
+/**
+ * One batched request, or null when the separator did not survive (the caller
+ * falls back to single requests, which cannot be mis-aligned).
+ */
+async function translateBatch(texts, session) {
+    if (texts.length === 1) {
+        try {
+            return [await session.translate(texts[0])];
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        const parts = (await session.translate(texts.join(UNIT_SEPARATOR))).split(UNIT_SEPARATOR);
+        return parts.length === texts.length ? parts : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every segment of a built article, in reading order. */
+export function segmentsOf(built) {
+    return built.blocks.flatMap(block => block.segments);
+}
+/**
+ * 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 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);
+        if (hit !== undefined) {
+            applyTranslation(built, segment, hit, pair);
+            recalled.push(learnOf(segment.original, hit));
+            done += 1;
+        }
+        else {
+            pending.push(segment);
+        }
+    }
+    report();
+    let batch = [];
+    let chars = 0;
+    const flush = async () => {
+        if (batch.length === 0)
+            return;
+        const current = batch;
+        batch = [];
+        chars = 0;
+        if (cancelled())
+            return;
+        const parts = await translateBatch(current.map(segment => segment.original), session);
+        if (parts !== null) {
+            current.forEach((segment, index) => {
+                const value = parts[index].trim();
+                applyTranslation(built, segment, value, pair);
+                learned.push(learnOf(segment.original, value));
+                done += 1;
+            });
+            report();
+            return;
+        }
+        // The separator did not survive (or the call failed): fall back to one unit
+        // per request, which cannot be mis-aligned.
+        for (const segment of current) {
+            if (cancelled())
+                return;
+            try {
+                const translated = (await session.translate(segment.original)).trim();
+                applyTranslation(built, segment, translated, pair);
+                learned.push(learnOf(segment.original, translated));
+                done += 1;
+            }
+            catch {
+                failed += 1;
+            }
+            report();
+        }
+    };
+    for (const segment of pending) {
+        if (cancelled())
+            break;
+        const size = segment.original.length;
+        if (batch.length > 0 && (chars + size > BATCH_MAX_CHARS || batch.length >= BATCH_MAX_UNITS))
+            await flush();
+        if (cancelled())
+            break;
+        batch.push(segment);
+        chars += size;
+    }
+    await flush();
+    return { done, failed, total, learned, recalled };
+}