@khorsheed/dsh-reader 0.2.0

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

@@ -0,0 +1,379 @@
+/**
+ * On-device translation for the article body, through the browser's own
+ * Translator API (Chrome 138+ / Edge 148+, desktop only).
+ *
+ * Everything here is the BROWSER half, on purpose. The model runs inside the
+ * user's browser: the article text never reaches the host, is never written to
+ * `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).
+ *
+ * The unit of translation is a SENTENCE inside one text node — never a node,
+ * never a paragraph. Two reasons the granularity matters:
+ *
+ * - The reader wants ONE sentence's original while reading the translation. A
+ *   paragraph-level unit cannot answer that after the fact: the model merges
+ *   and splits sentences, so re-aligning the two sides later is a guess, and a
+ *   wrong guess shows the wrong original. Segmenting first makes the pairing
+ *   true by construction.
+ * - Inline markup survives because we only ever touch text nodes: a link
+ *   inside a sentence stays a link, its href untouched. A sentence that
+ *   CROSSES an inline element becomes two units (the text on each side) — what
+ *   Chrome's own page translation does — and each side still reveals exactly
+ *   its own original.
+ *
+ * Batches go out as one string with a separator between units, and the answer
+ * is only accepted when it comes back with the same number of parts. A mangled
+ * separator costs that batch its granularity — it is re-sent one unit at a
+ * time — never its correctness.
+ *
+ * @module @khorsheed/dsh-reader/client/translate
+ */
+import type { ReaderSentenceLearn } from '../types.ts';
+/** The three views the reader picks between (the globe's menu). */
+export type TranslationView = 'trans' | 'both' | 'orig';
+/** What the browser reports for a language pair. */
+export type TranslationAvailability = 'available' | 'downloadable' | 'downloading' | 'unavailable';
+/**
+ * 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 declare const TARGET_CANDIDATES: readonly string[];
+/** The unit separator inside a batch. Rare, short, and verified on the way back. */
+export declare const UNIT_SEPARATOR = "\u27E6|\u27E7";
+/** The structural slice of the Translator API this module actually uses. */
+export interface TranslatorLike {
+    availability(request: {
+        sourceLanguage: string;
+        targetLanguage: string;
+    }): Promise<string>;
+    create(request: {
+        sourceLanguage: string;
+        targetLanguage: string;
+        monitor?: (monitor: DownloadMonitorLike) => void;
+    }): Promise<TranslatorSessionLike>;
+}
+/** The `monitor` object `create()` hands back; only progress is read. */
+export interface DownloadMonitorLike {
+    addEventListener(type: 'downloadprogress', listener: (event: {
+        loaded: number;
+    }) => void): void;
+}
+/** One created translator. */
+export interface TranslatorSessionLike {
+    readonly inputQuota: number;
+    measureInputUsage(text: string): Promise<number>;
+    translate(text: string): Promise<string>;
+}
+/** Read the page's Translator API, or null when this browser has none. */
+export declare function detectTranslator(scope?: unknown): TranslatorLike | null;
+/** The structural slice of the Language Detector API, when the page has one. */
+export interface LanguageDetectorLike {
+    availability(): Promise<string>;
+    create(options?: {
+        monitor?: (monitor: DownloadMonitorLike) => void;
+    }): Promise<{
+        detect(text: string): Promise<readonly {
+            detectedLanguage: string;
+            confidence: number;
+        }[]>;
+        destroy?(): void;
+    }>;
+}
+/** Read the page's Language Detector, or null when this browser has none. */
+export declare function detectLanguageDetector(scope?: unknown): LanguageDetectorLike | null;
+/**
+ * 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 declare function detectSourceLanguage(text: string, fallback: string): Promise<string>;
+/** One attempted language pair and why it did not produce a translator. */
+export interface SessionAttempt {
+    readonly sourceLanguage: string;
+    readonly targetLanguage: string;
+    readonly reason: string;
+}
+/** The outcome of asking the browser for a translator, across candidate pairs. */
+export type SessionOutcome = {
+    readonly ok: true;
+    readonly session: TranslatorSessionLike;
+    readonly sourceLanguage: string;
+    readonly targetLanguage: string;
+} | {
+    readonly ok: false;
+    readonly attempts: readonly SessionAttempt[];
+    readonly unsupported: boolean;
+};
+/** True when the browser says this pair is not something it can ever build. */
+export declare function isUnsupported(error: unknown): boolean;
+/**
+ * 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 declare function createSession(api: TranslatorLike, request: {
+    readonly sources: readonly string[];
+    readonly targets: readonly string[];
+    readonly monitor?: (monitor: DownloadMonitorLike) => void;
+}): Promise<SessionOutcome>;
+/** One sentence inside a text run, with the whitespace that follows it. */
+export interface SentencePiece {
+    /** The sentence plus its trailing spacing — pieces concatenate back to the run. */
+    readonly text: string;
+    /** The translatable part (`text` without the trailing spacing). */
+    readonly core: string;
+}
+/**
+ * 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 declare function splitSentences(text: string): SentencePiece[];
+/** The class names the article markup is decorated with (hashed by the caller). */
+export interface TranslateClasses {
+    readonly unit: string;
+    readonly reveal: string;
+    readonly line: string;
+}
+/** One translated sentence, as it lives in the article DOM. */
+interface BuiltSegment {
+    readonly span: HTMLElement;
+    /** The source sentence, trimmed: what the reveal shows and what we translate. */
+    readonly original: string;
+    /**
+     * The whitespace that PRECEDED this unit inside its run. It stays in the
+     * original text node (so the DOM is unchanged), but the flattened block text
+     * needs it: without it two runs join as "See thebest-studied domains".
+     */
+    readonly lead: string;
+    /** The whitespace that followed it INSIDE the span (between sentences). */
+    readonly tail: string;
+    /**
+     * The run's own trailing whitespace, which stays in the DOM as a text node
+     * after the last span. It is not part of any span, but the flattened block
+     * text needs it — this is where "See the " + "best-studied domains" keeps its
+     * space.
+     */
+    readonly gap: string;
+    translated: string | null;
+    open: boolean;
+}
+/** Where a block's reveal container belongs. */
+type RevealPlacement = 'sibling' | 'inside' | 'inline';
+/** One block (paragraph, list item, heading…) and the segments inside it. */
+interface BuiltBlock {
+    readonly element: Element;
+    readonly placement: RevealPlacement;
+    readonly segments: BuiltSegment[];
+    /** The block's original prose flattened across its units. */
+    flat: string;
+    /** Sentence ranges inside `flat`, in order — the reveal's real granularity. */
+    sentences: {
+        readonly start: number;
+        readonly end: number;
+    }[];
+    reveal: HTMLElement | null;
+}
+/** What one original text node needs to be put back exactly as it was. */
+interface RestoreRecord {
+    readonly node: Text;
+    readonly lead: string;
+    readonly core: string;
+    readonly tail: string;
+    readonly tailNode: Text;
+    readonly spans: readonly HTMLElement[];
+}
+/** The live segmentation of one rendered article. */
+export interface BuiltArticle {
+    readonly root: Element;
+    readonly blocks: BuiltBlock[];
+    readonly restores: RestoreRecord[];
+    view: TranslationView;
+}
+/**
+ * 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 declare function translationHash(text: string): string;
+/**
+ * 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 declare function buildArticle(root: Element, classes: TranslateClasses): BuiltArticle | null;
+/** Take the segmentation back out, restoring every original text node. */
+export declare function restoreArticle(root: Element): void;
+/** Paint the spans and the reveals for one view. */
+export declare function setView(built: BuiltArticle, view: TranslationView, classes: TranslateClasses): void;
+/**
+ * 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 declare function setPairHover(built: BuiltArticle, target: EventTarget | null, on: boolean): void;
+/** The segment a click landed on, if any. */
+export declare function segmentAt(built: BuiltArticle, target: EventTarget | null): BuiltSegment | null;
+/** Flip one sentence's original open / closed (the click gesture). */
+export declare function toggleSegment(built: BuiltArticle, segment: BuiltSegment, classes: TranslateClasses): void;
+/**
+ * Record a translated unit: in the DOM, and in the translation memory.
+ *
+ * @param pair - the `<src>→<tgt>` label this translation belongs to.
+ */
+export declare function applyTranslation(built: BuiltArticle, segment: BuiltSegment, translated: string, pair: string): void;
+/** A remembered translation for this sentence in this pair, when one exists. */
+export declare function remembered(pair: string, text: string): string | undefined;
+/**
+ * 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 declare function primeMemory(pair: string, entries: readonly {
+    text: string;
+    translation: string;
+}[]): number;
+/** Drop the translation memory (the specs call this between cases). */
+export declare function clearMemory(): void;
+/**
+ * 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 declare function isTargetLanguage(text: string): boolean;
+/** The outcome of translating a list of strings. */
+export interface TextsOutcome {
+    /** Original → translation, for every string that came back. */
+    readonly translated: ReadonlyMap<string, string>;
+    /** How many strings were already remembered (no request needed). */
+    readonly remembered: number;
+    /** How many strings could not be translated at all. */
+    readonly failed: number;
+    /**
+     * What the run newly learned (for the host's persistent tiers), as
+     * `{ hash, source, target }` triples — `hash` is `translationHash(source)`.
+     */
+    readonly learned: readonly ReaderSentenceLearn[];
+    /** What the run was served from memory (whose LRU stamps should move). */
+    readonly recalled: readonly ReaderSentenceLearn[];
+}
+/**
+ * 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 declare function translateTexts(texts: readonly string[], pair: string, session: TranslatorSessionLike, cancelled: () => boolean, onProgress?: (done: number, total: number) => void): Promise<TextsOutcome>;
+/** What the driver needs; everything is injected so the specs can fake it. */
+export interface RunTranslationOptions {
+    readonly built: BuiltArticle;
+    readonly session: TranslatorSessionLike;
+    /** The `<src>→<tgt>` label this run's translations belong to. */
+    readonly pair: string;
+    /** Flipped by the Cancel gesture; checked between batches. */
+    readonly cancelled: () => boolean;
+    readonly onProgress?: (done: number, total: number) => void;
+}
+/** What one run produced, for the host's persistent tiers. */
+export interface RunTranslationResult {
+    readonly done: number;
+    readonly failed: number;
+    readonly total: number;
+    /** Units the model translated this run (new to the memory). */
+    readonly learned: readonly ReaderSentenceLearn[];
+    /** Units the memory served (their LRU stamps should move). */
+    readonly recalled: readonly ReaderSentenceLearn[];
+}
+/** Every segment of a built article, in reading order. */
+export declare function segmentsOf(built: BuiltArticle): BuiltSegment[];
+/**
+ * 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 declare function runTranslation(options: RunTranslationOptions): Promise<RunTranslationResult>;
+export {};
+//# sourceMappingURL=translate.d.ts.map