@khorsheed/dsh-reader 0.2.1 → 0.3.1

package/lib/types/image-fetch.d.ts

@@ -0,0 +1,81 @@
+import type { LookupFunction } from 'node:net';
+/** The outcome of one image fetch: the bytes and their type, or the reason not. */
+export type ImageFetchOutcome = {
+    readonly ok: true;
+    readonly url: string;
+    readonly mime: string;
+    readonly base64: string;
+} | {
+    readonly ok: false;
+    readonly url: string;
+    readonly error: string;
+};
+/** One resolved host address (the `dns.lookup` all-mode shape). */
+export interface ImageResolvedAddress {
+    readonly address: string;
+    readonly family: number;
+}
+/** Injectable resolver seam — the POLICY half's DNS (defaults to the system resolver). */
+export type ImageHostResolver = (hostname: string) => Promise<readonly ImageResolvedAddress[]>;
+/** The transport half's address supply — node's own `lookup` callback contract. */
+export type ImageTransportLookup = LookupFunction;
+/**
+ * The two seams a test injects: `resolve` answers what the POLICY validates
+ * (a public address), `lookup` answers what the CONNECTION dials (the fixture
+ * server's loopback). In production both default to the system resolver and
+ * the lookup is the validated answer set — that identity IS the pin.
+ */
+export interface ImageFetchSeams {
+    readonly resolve?: ImageHostResolver;
+    readonly lookup?: ImageTransportLookup;
+}
+/** Numeric limits, overridable in tests. */
+export interface ImageFetchLimits {
+    readonly maxBytes?: number;
+    readonly timeoutMs?: number;
+    readonly maxRedirects?: number;
+}
+/** An article figure is a few hundred KB; 8 MiB leaves room for print-resolution PNGs. */
+export declare const IMAGE_FETCH_MAX_BYTES: number;
+/** One image fetch never hangs the rescue: the pane's picture stays broken instead. */
+export declare const IMAGE_FETCH_TIMEOUT_MS = 15000;
+/** Redirect hops per image, each re-validated end to end (the classic SSRF hop). */
+export declare const IMAGE_FETCH_MAX_REDIRECTS = 3;
+/**
+ * The byte budget of the in-memory rescue cache (wire size — base64 is what
+ * the map actually holds). A figure-heavy article is a few MB; the budget
+ * covers several of them, and the oldest entry leaves first.
+ */
+export declare const IMAGE_CACHE_BUDGET_BYTES: number;
+/**
+ * The rescue cache: a pane remount (the sidebar unmounts wholesale when
+ * another panel takes over) re-fails every CORP-blocked image, and this map is
+ * what keeps that a memory read instead of a dozen outbound requests. LRU by
+ * insertion refresh, bounded by bytes.
+ */
+export declare class ImageFetchCache {
+    private readonly budgetBytes;
+    private readonly entries;
+    private bytes;
+    constructor(budgetBytes?: number);
+    /** The cached bytes for one URL, refreshing its recency. */
+    get(url: string): {
+        mime: string;
+        base64: string;
+    } | undefined;
+    /** Cache one fetched image, evicting the oldest entries until it fits. */
+    set(url: string, mime: string, base64: string): void;
+}
+/**
+ * Fetch one image, policy-checked end to end.
+ *
+ * Errors are values: the pane's only answer to a failed rescue is leaving the
+ * broken image as it was, so the reason string is for logs, not for display.
+ *
+ * @param rawUrl - the image URL the pane failed on.
+ * @param seams - resolver/lookup overrides (tests only; production pins).
+ * @param limits - byte/timeout/redirect overrides (tests only).
+ * @returns the image bytes base64-encoded with their declared type, or why not.
+ */
+export declare function fetchImageBytes(rawUrl: string, seams?: ImageFetchSeams, limits?: ImageFetchLimits): Promise<ImageFetchOutcome>;
+//# sourceMappingURL=image-fetch.d.ts.map

package/lib/types/image-fetch.js

@@ -0,0 +1,385 @@
+/** An article figure is a few hundred KB; 8 MiB leaves room for print-resolution PNGs. */
+export const IMAGE_FETCH_MAX_BYTES = 8 * 1024 * 1024;
+/** One image fetch never hangs the rescue: the pane's picture stays broken instead. */
+export const IMAGE_FETCH_TIMEOUT_MS = 15_000;
+/** Redirect hops per image, each re-validated end to end (the classic SSRF hop). */
+export const IMAGE_FETCH_MAX_REDIRECTS = 3;
+/** An honest agent line — bot walls are reported, never impersonated around. */
+const IMAGE_FETCH_USER_AGENT = 'dsh-reader image rescue (+https://github.com/Khorsheed/dsh-plugins)';
+/**
+ * The raster/vector types a rescued image may declare. The pane re-points the
+ * failed `<img>` at these bytes, so an SVG rides an image context (which never
+ * scripts); anything else the origin answers — HTML above all — is refused
+ * before the body is read.
+ */
+const IMAGE_MIME = /^image\/(?:png|jpe?g|gif|webp|avif|svg\+xml|bmp|x-icon|vnd\.microsoft\.icon)$/i;
+/**
+ * The byte budget of the in-memory rescue cache (wire size — base64 is what
+ * the map actually holds). A figure-heavy article is a few MB; the budget
+ * covers several of them, and the oldest entry leaves first.
+ */
+export const IMAGE_CACHE_BUDGET_BYTES = 32 * 1024 * 1024;
+/**
+ * The rescue cache: a pane remount (the sidebar unmounts wholesale when
+ * another panel takes over) re-fails every CORP-blocked image, and this map is
+ * what keeps that a memory read instead of a dozen outbound requests. LRU by
+ * insertion refresh, bounded by bytes.
+ */
+export class ImageFetchCache {
+    budgetBytes;
+    entries = new Map();
+    bytes = 0;
+    constructor(budgetBytes = IMAGE_CACHE_BUDGET_BYTES) {
+        this.budgetBytes = budgetBytes;
+    }
+    /** The cached bytes for one URL, refreshing its recency. */
+    get(url) {
+        const hit = this.entries.get(url);
+        if (hit === undefined)
+            return undefined;
+        this.entries.delete(url);
+        this.entries.set(url, hit);
+        return hit;
+    }
+    /** Cache one fetched image, evicting the oldest entries until it fits. */
+    set(url, mime, base64) {
+        if (base64.length > this.budgetBytes)
+            return;
+        const existing = this.entries.get(url);
+        if (existing !== undefined) {
+            this.bytes -= existing.base64.length;
+            this.entries.delete(url);
+        }
+        while (this.bytes + base64.length > this.budgetBytes) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done)
+                break;
+            const dropped = this.entries.get(oldest.value);
+            this.entries.delete(oldest.value);
+            this.bytes -= dropped?.base64.length ?? 0;
+        }
+        this.entries.set(url, { mime, base64 });
+        this.bytes += base64.length;
+    }
+}
+/**
+ * Fetch one image, policy-checked end to end.
+ *
+ * Errors are values: the pane's only answer to a failed rescue is leaving the
+ * broken image as it was, so the reason string is for logs, not for display.
+ *
+ * @param rawUrl - the image URL the pane failed on.
+ * @param seams - resolver/lookup overrides (tests only; production pins).
+ * @param limits - byte/timeout/redirect overrides (tests only).
+ * @returns the image bytes base64-encoded with their declared type, or why not.
+ */
+export async function fetchImageBytes(rawUrl, seams = {}, limits = {}) {
+    const maxBytes = limits.maxBytes ?? IMAGE_FETCH_MAX_BYTES;
+    const timeoutMs = limits.timeoutMs ?? IMAGE_FETCH_TIMEOUT_MS;
+    const maxRedirects = limits.maxRedirects ?? IMAGE_FETCH_MAX_REDIRECTS;
+    let current = rawUrl;
+    for (let hop = 0; hop <= maxRedirects; hop++) {
+        const gate = await checkImageTarget(current, seams.resolve);
+        if (!gate.ok)
+            return { ok: false, url: rawUrl, error: gate.error };
+        const response = await requestOnce(gate.url, gate.addresses, timeoutMs, seams.lookup);
+        if (!response.ok)
+            return { ok: false, url: rawUrl, error: response.error };
+        const { message } = response;
+        const status = message.statusCode ?? 0;
+        if (status >= 300 && status < 400) {
+            message.resume();
+            const location = message.headers['location'];
+            if (typeof location !== 'string' || location.length === 0) {
+                return { ok: false, url: rawUrl, error: `HTTP ${status} without a location` };
+            }
+            try {
+                current = new URL(location, current).toString();
+            }
+            catch {
+                return { ok: false, url: rawUrl, error: `HTTP ${status} to an unparseable location` };
+            }
+            continue;
+        }
+        if (status < 200 || status >= 300) {
+            message.resume();
+            return { ok: false, url: rawUrl, error: `HTTP ${status}` };
+        }
+        const mime = (message.headers['content-type'] ?? '').replace(/;.*$/s, '').trim().toLowerCase();
+        if (!IMAGE_MIME.test(mime)) {
+            message.resume();
+            return { ok: false, url: rawUrl, error: `the response is not an image (content-type "${mime || 'unknown'}")` };
+        }
+        const declared = Number(message.headers['content-length'] ?? Number.NaN);
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            message.resume();
+            return { ok: false, url: rawUrl, error: `the image exceeds the ${Math.floor(maxBytes / 1024 / 1024)} MiB cap` };
+        }
+        const body = await readBody(message, maxBytes);
+        if (!body.ok)
+            return { ok: false, url: rawUrl, error: body.error };
+        return { ok: true, url: rawUrl, mime, base64: body.base64 };
+    }
+    return { ok: false, url: rawUrl, error: `more than ${maxRedirects} redirects` };
+}
+/**
+ * The syntax gate plus the address gate, in the order capture's navigation
+ * policy runs them. The address set travels with the verdict: the transport
+ * dials exactly these, so the hostname is never resolved twice.
+ */
+async function checkImageTarget(raw, resolve) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, error: 'invalid-url' };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return { ok: false, error: `only http(s) images can be rescued, not ${url.protocol}` };
+    }
+    if (url.username !== '' || url.password !== '') {
+        return { ok: false, error: 'URLs with embedded credentials are never fetched' };
+    }
+    const hostname = url.hostname.replace(/\.$/, '');
+    if (hostname === '')
+        return { ok: false, error: 'invalid-url' };
+    if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+        return { ok: false, error: 'localhost is never fetched' };
+    }
+    if (isIpLiteral(hostname)) {
+        const bare = hostname.startsWith('[') ? hostname.slice(1, -1) : hostname;
+        const cls = classifyAddress(bare);
+        if (cls !== 'public')
+            return { ok: false, error: `${bare} is a ${cls} address` };
+        return { ok: true, url, addresses: [{ address: bare, family: bare.includes(':') ? 6 : 4 }] };
+    }
+    const resolver = resolve ?? defaultResolve;
+    let addresses;
+    try {
+        addresses = await resolver(hostname.replace(/^\[(.*)\]$/, '$1'));
+    }
+    catch (error) {
+        return { ok: false, error: `cannot resolve ${hostname}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (addresses.length === 0)
+        return { ok: false, error: `cannot resolve ${hostname}: no addresses` };
+    for (const { address } of addresses) {
+        const cls = classifyAddress(address);
+        if (cls !== 'public')
+            return { ok: false, error: `${hostname} resolves to a ${cls} address` };
+    }
+    return { ok: true, url, addresses };
+}
+/**
+ * Issue one GET against the validated address set.
+ *
+ * The `lookup` handed to the transport answers with the validated addresses
+ * and nothing else — DNS is consulted once, by the gate, and the connection
+ * cannot re-resolve the hostname into a private network (the rebinding window
+ * a plain fetch leaves open). Node still verifies TLS against the HOSTNAME;
+ * the lookup only maps it to an address.
+ */
+function requestOnce(url, addresses, timeoutMs, lookup) {
+    return new Promise((resolvePromise) => {
+        void (async () => {
+            const transport = url.protocol === 'https:'
+                ? await import('node:https')
+                : await import('node:http');
+            const request = transport.request({
+                protocol: url.protocol,
+                // Bracketed IPv6 literals are a URL spelling, not a host option.
+                hostname: url.hostname.replace(/^\[(.*)\]$/, '$1'),
+                port: url.port,
+                path: `${url.pathname}${url.search}`,
+                method: 'GET',
+                headers: {
+                    accept: 'image/avif,image/webp,image/png,image/svg+xml,image/*,*/*;q=0.8',
+                    'accept-encoding': 'identity',
+                    'user-agent': IMAGE_FETCH_USER_AGENT,
+                },
+                lookup: lookup ?? pinnedLookup(addresses),
+            }, (message) => resolvePromise({ ok: true, message }));
+            request.setTimeout(timeoutMs, () => {
+                request.destroy(new Error(`the image fetch timed out after ${timeoutMs} ms`));
+            });
+            request.on('error', (error) => resolvePromise({ ok: false, error: error.message }));
+            request.end();
+        })().catch((error) => resolvePromise({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+    });
+}
+/** The lookup that pins a request to the gate's validated answers. */
+function pinnedLookup(addresses) {
+    return (_hostname, options, callback) => {
+        if (options.all === true) {
+            callback(null, addresses.map(({ address, family }) => ({ address, family })));
+            return;
+        }
+        const first = addresses[0];
+        callback(null, first.address, first.family);
+    };
+}
+/** The body, capped; over the cap is a refusal, not a truncation. */
+function readBody(message, maxBytes) {
+    return new Promise((resolvePromise) => {
+        const chunks = [];
+        let received = 0;
+        message.on('data', (chunk) => {
+            received += chunk.byteLength;
+            if (received > maxBytes) {
+                message.destroy();
+                resolvePromise({ ok: false, error: `the image exceeds the ${Math.floor(maxBytes / 1024 / 1024)} MiB cap` });
+                return;
+            }
+            chunks.push(chunk);
+        });
+        message.on('end', () => resolvePromise({ ok: true, base64: Buffer.concat(chunks).toString('base64') }));
+        message.on('error', (error) => resolvePromise({ ok: false, error: error.message }));
+    });
+}
+/** The system resolver, bound lazily so importing this module never touches `node:dns`. */
+async function defaultResolve(hostname) {
+    const dns = await import('node:dns');
+    return dns.promises.lookup(hostname, { all: true, verbatim: true });
+}
+/** Parse a canonical IPv4 string into its 32-bit value, or undefined. */
+function parseIpv4(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4)
+        return undefined;
+    let value = 0;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return undefined;
+        if (part.length > 1 && part.startsWith('0'))
+            return undefined; // legacy octal-looking octets: fail closed
+        const octet = Number(part);
+        if (octet > 255)
+            return undefined;
+        value = value * 256 + octet;
+    }
+    return value >>> 0;
+}
+/** Expand an IPv6 string into its eight 16-bit groups, or undefined when malformed. */
+function parseIpv6Groups(address) {
+    // Strip a zone id (link-local literals like fe80::1%eth0).
+    const zoneless = address.split('%')[0];
+    if (!/^[0-9a-fA-F:.]+$/.test(zoneless))
+        return undefined;
+    const halves = zoneless.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const parseHalf = (half) => {
+        if (half === '')
+            return [];
+        const groups = [];
+        const parts = half.split(':');
+        for (const [index, part] of parts.entries()) {
+            // An embedded dotted-quad tail (deprecated compatible / mapped forms).
+            if (part.includes('.')) {
+                if (index !== parts.length - 1)
+                    return undefined;
+                const v4 = parseIpv4(part);
+                if (v4 === undefined)
+                    return undefined;
+                groups.push((v4 >>> 16) & 0xffff, v4 & 0xffff);
+                continue;
+            }
+            if (!/^[0-9a-fA-F]{1,4}$/.test(part))
+                return undefined;
+            groups.push(parseInt(part, 16));
+        }
+        return groups;
+    };
+    const head = parseHalf(halves[0]);
+    if (head === undefined)
+        return undefined;
+    if (halves.length === 1)
+        return head.length === 8 ? head : undefined;
+    const tail = parseHalf(halves[1]);
+    if (tail === undefined)
+        return undefined;
+    const missing = 8 - head.length - tail.length;
+    if (missing < 0 || (missing === 0 && halves[1] !== ''))
+        return undefined;
+    return [...head, ...Array(missing).fill(0), ...tail];
+}
+/** The embedded IPv4 value of an IPv4-mapped, NAT64, or 6to4 IPv6 address. */
+function embeddedIpv4(groups) {
+    // ::ffff:a.b.c.d (IPv4-mapped): groups 0-4 zero, group 5 0xffff.
+    if (groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff) {
+        return ((groups[6] << 16) | groups[7]) >>> 0;
+    }
+    // 64:ff9b::/96 (NAT64 well-known prefix): the v4 address is the last 32 bits.
+    if (groups[0] === 0x0064 && groups[1] === 0xff9b && groups.slice(2, 6).every((g) => g === 0)) {
+        return ((groups[6] << 16) | groups[7]) >>> 0;
+    }
+    // 2002::/16 (6to4): the v4 address is groups 1-2.
+    if (groups[0] === 0x2002) {
+        return ((groups[1] << 16) | groups[2]) >>> 0;
+    }
+    return undefined;
+}
+/** Classify a canonical dotted-quad IPv4 value. */
+function classifyIpv4(value) {
+    const a = (value >>> 24) & 0xff;
+    const b = (value >>> 16) & 0xff;
+    if (a === 0)
+        return 'unspecified'; // 0.0.0.0/8 "this host"
+    if (a === 127)
+        return 'loopback';
+    if (a === 10)
+        return 'private';
+    if (a === 172 && b >= 16 && b <= 31)
+        return 'private';
+    if (a === 192 && b === 168)
+        return 'private';
+    if (a === 169 && b === 254)
+        return 'link-local'; // incl. 169.254.169.254 cloud metadata
+    if (a === 100 && b >= 64 && b <= 127)
+        return 'private'; // CGNAT shared space
+    if (a === 192 && b === 0)
+        return 'reserved'; // 192.0.0.0/24 protocol assignments, 192.0.2.0/24 documentation
+    if (a === 198 && (b === 18 || b === 19))
+        return 'reserved'; // benchmarking
+    if (a === 198 && b === 51)
+        return 'reserved'; // documentation
+    if (a === 203 && b === 0)
+        return 'reserved'; // documentation
+    if (a >= 224 && a <= 239)
+        return 'multicast';
+    if (a >= 240)
+        return 'reserved';
+    return 'public';
+}
+/** Classify one resolved address (IPv4 or IPv6, canonical or transition form). */
+function classifyAddress(address) {
+    const v4 = parseIpv4(address);
+    if (v4 !== undefined)
+        return classifyIpv4(v4);
+    const groups = parseIpv6Groups(address);
+    if (groups === undefined)
+        return 'reserved'; // unparseable is never public
+    const embedded = embeddedIpv4(groups);
+    if (embedded !== undefined)
+        return classifyIpv4(embedded);
+    const first = groups[0];
+    if (groups.every((g) => g === 0))
+        return 'unspecified'; // ::
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return 'loopback'; // ::1
+    if ((first & 0xfe00) === 0xfc00)
+        return 'private'; // fc00::/7 unique local
+    if ((first & 0xffc0) === 0xfe80)
+        return 'link-local'; // fe80::/10
+    if ((first & 0xff00) === 0xff00)
+        return 'multicast'; // ff00::/8
+    if (first === 0x2001 && groups[1] === 0x0db8)
+        return 'reserved'; // documentation
+    return 'public';
+}
+/** Whether one hostname string is already an IP literal (bracketed v6 or dotted v4). */
+function isIpLiteral(hostname) {
+    const bare = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+    return parseIpv4(bare) !== undefined || parseIpv6Groups(bare) !== undefined;
+}

package/lib/types/index.d.ts

@@ -13,17 +13,21 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { ReaderService } from './service.ts';
+import { ReaderNotesStore } from './notes.ts';
 export { ReaderService, classifyPayload, normalizeUrl } from './service.ts';
 export { ReaderRemoteService } from './remote.ts';
 export type { ReaderRemoteConfig } from './remote.ts';
 export { MAX_CACHED_BODIES, MAX_TAGS, ReaderStore, ReaderStoreError, boundAnnotations, boundPayloads, emptyStateDoc, normalizeStateDoc, pruneOrphanTags, resolveReaderStateRoot, serializeStateDoc, } from './store.ts';
 export type { ReaderStoreRead } from './store.ts';
+export * from './notes.ts';
 export * from './schedule.ts';
 export * from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** The reader plugin's service core. */
         reader: ReaderService;
+        /** The reader's notes, discussions and article snapshots. */
+        readerNotes: ReaderNotesStore;
     }
 }
 /** Cordis plugin name used by loader diagnostics. */
@@ -32,6 +36,8 @@ export declare const name = "reader";
 export interface ReaderConfig {
     /** Directory holding `state.json`; defaults to `$DSH_HOME/state/dsh-reader`. */
     readonly stateRoot?: string;
+    /** A yt-dlp binary to use instead of the reader's managed copy (video metadata and captions). */
+    readonly ytdlpPath?: string;
 }
 /**
  * Plugin body: provide the service core, then mount the Remote data face.

package/lib/types/index.js

@@ -1,8 +1,10 @@
 import { ReaderService } from "./service.js";
+import { ReaderNotesStore } from "./notes.js";
 import { ReaderRemoteService } from "./remote.js";
 export { ReaderService, classifyPayload, normalizeUrl } from "./service.js";
 export { ReaderRemoteService } from "./remote.js";
 export { MAX_CACHED_BODIES, MAX_TAGS, ReaderStore, ReaderStoreError, boundAnnotations, boundPayloads, emptyStateDoc, normalizeStateDoc, pruneOrphanTags, resolveReaderStateRoot, serializeStateDoc, } from "./store.js";
+export * from "./notes.js";
 export * from "./schedule.js";
 export * from "./types.js";
 /** Cordis plugin name used by loader diagnostics. */
@@ -21,5 +23,6 @@ export const name = 'reader';
 export function apply(ctx, config = {}) {
     const service = new ReaderService(ctx, config);
     ctx.provide('reader', service);
+    ctx.provide('readerNotes', new ReaderNotesStore(config));
     ctx.plugin(ReaderRemoteService, {});
 }

package/lib/types/local-transcribe.d.ts

@@ -0,0 +1,171 @@
+import { type Cue } from './captions.ts';
+import type { ReaderMedia } from './media.ts';
+import type { LocalTranscriptStatus } from './types.ts';
+/** The part of the `transcribe` service the reader calls. */
+export interface TranscribeEngine {
+    modelsFor(request: {
+        language?: 'zh' | 'en' | 'auto';
+        diarize?: false;
+    }): string[];
+    missingBytes(ids: readonly string[]): Promise<number>;
+    run(request: {
+        input: {
+            files: string[];
+        };
+        fromSec?: number;
+        language: 'zh' | 'en' | 'auto';
+        diarize: false;
+        owner: string;
+        label?: string;
+    }, options: {
+        signal?: AbortSignal;
+        onProgress?: (progress: {
+            stage: string;
+            progress: number;
+            ahead?: number;
+        }) => void;
+        onSegments?: (segments: readonly EngineSegment[]) => void;
+    }): Promise<{
+        segments: EngineSegment[];
+        language?: string;
+    }>;
+    /** Who spoke when (an engine older than this has none: transcripts stay one voice). */
+    speakers?(request: {
+        input: {
+            files: string[];
+        };
+        speech?: {
+            start: number;
+            end: number;
+        }[];
+        owner: string;
+        label?: string;
+    }, options: {
+        signal?: AbortSignal;
+        onProgress?: (progress: {
+            stage: string;
+            progress: number;
+            ahead?: number;
+        }) => void;
+    }): Promise<{
+        single: boolean;
+        turns: {
+            cluster: number;
+            start: number;
+            end: number;
+        }[];
+    }>;
+}
+/** A speaker turn as the engine reports it. */
+export interface EngineTurn {
+    readonly cluster: number;
+    readonly start: number;
+    readonly end: number;
+}
+/** One finished stretch as the engine reports it. */
+export interface EngineSegment {
+    readonly start: number;
+    readonly end: number;
+    readonly tokens: readonly {
+        readonly text: string;
+        readonly start: number;
+        readonly end: number;
+    }[];
+}
+/**
+ * Engine stretches as caption-like cues: one per sentence (the engine's
+ * stretches are cut at pauses, not sentence ends), so the transcript merges
+ * into the same paragraphs platform captions do. A sentence that runs on
+ * without a period is closed at a comma or a pause once it is long, or a
+ * single cue would make a minute-and-a-half paragraph (measured 2026-10-20).
+ *
+ * @param segments - the engine's segments, in order.
+ */
+export declare function cuesFromSegments(segments: readonly EngineSegment[], speakers?: readonly (number | undefined)[]): (Cue & {
+    speaker?: number;
+})[];
+/**
+ * Each token's speaker, as an index in order of first appearance (A, B, …):
+ * the turn covering the token's middle, else the nearest one; then runs of a
+ * voice shorter than {@link MIN_TURN_SEC} are folded into the voice before
+ * them — a diarizer's boundary wobble would otherwise split sentences.
+ *
+ * @param segments - the transcript's segments.
+ * @param turns - the engine's turns.
+ */
+export declare function speakerPerToken(segments: readonly EngineSegment[], turns: readonly EngineTurn[]): number[];
+/**
+ * The transcript with its speakers: paragraphs never cross a change of voice,
+ * and each carries `data-spk` (the speaker's index) beside its `data-t`.
+ */
+export declare function renderSpeakerTranscript(segments: readonly EngineSegment[], turns: readonly EngineTurn[]): string;
+/** The marker a locally transcribed paragraph carries (the 来源 line reads it). */
+export declare const LOCAL_MARK = "data-src=\"local\"";
+/** The engine's segments as transcript markup, each paragraph marked local. */
+export declare function renderLocalTranscript(segments: readonly EngineSegment[]): string;
+/**
+ * The language to ask for: always detection (SenseVoice). Measured
+ * 2026-10-20: a platform says nothing reliable about the spoken language — a
+ * Bilibili upload of an English interview came out of the Chinese model as
+ * lower-case English with Chinese punctuation — and on Chinese speech
+ * SenseVoice reads about as well as Paraformer (a 90 s sample: each missed
+ * two or three characters the other got right).
+ */
+export declare function languageFor(_media: ReaderMedia): 'auto';
+/** What the transcriber needs from the reader. */
+export interface LocalTranscriberDeps {
+    /** The engine, probed per start. */
+    readonly engine: () => TranscribeEngine | undefined;
+    /** Where temporary audio goes. */
+    readonly tmpRoot: string;
+    /** Fetch a video's audio track into `dir`. */
+    readonly videoAudio: (url: string, dir: string, options: {
+        signal: AbortSignal;
+        onProgress: (fraction: number) => void;
+    }) => Promise<string>;
+    /** How often a restart checks for the engine before resuming jobs (ms; default 2 s). */
+    readonly resumePollMs?: number;
+    /** Keep the finished transcript as the entry's body (`speakers`: how many voices, once known). */
+    readonly store: (entryId: string, url: string, html: string, language: string | undefined, speakers?: number) => Promise<void>;
+}
+/** The reader's local transcription jobs, by entry. */
+export declare class LocalTranscriber {
+    private readonly deps;
+    private readonly jobs;
+    /** Jobs a previous process left mid-way, waiting for the engine. */
+    private readonly resumable;
+    private resumeTimer;
+    private disposing;
+    constructor(deps: LocalTranscriberDeps);
+    /** An entry's job as the browser sees it. */
+    status(entryId: string): LocalTranscriptStatus;
+    /**
+     * Start (or rejoin) an entry's transcription.
+     *
+     * @param request - the entry, its media, and whether the model download was confirmed.
+     */
+    start(request: {
+        entryId: string;
+        url: string;
+        media: ReaderMedia;
+        title?: string;
+        confirmModels?: boolean;
+    }): Promise<LocalTranscriptStatus>;
+    /**
+     * Leave or stop an entry's job: a queued (or still fetching) job is
+     * withdrawn either way; a running one only with `force`.
+     */
+    cancel(entryId: string, force: boolean): LocalTranscriptStatus;
+    /** Whether the engine is installed right now. */
+    engineAvailable(): boolean;
+    /** Stop everything (plugin disposal) — keeping each job's record, so the next process resumes it. */
+    dispose(): void;
+    /**
+     * Run (or resume) one job: fetch the audio unless the record has it,
+     * transcribe from where the saved segments end, store, then the speakers.
+     *
+     * @param resumeDir - a previous process's directory for this job.
+     */
+    private execute;
+}
+//# sourceMappingURL=local-transcribe.d.ts.map