@khorsheed/dsh-reader 0.2.1 → 0.3.1

package/lib/types/service.d.ts

@@ -35,7 +35,9 @@
  * @module @khorsheed/dsh-reader/service
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { type ReaderAddFailure, type ReaderAddOutcome, type ReaderAddRefusal, type ReaderAnnotationOutcome, type ReaderBackfillCandidate, type ReaderEntryBodyView, type ReaderBody, type ReaderCapabilities, type ReaderMutationOutcome, type ReaderEntryFetchState, type ReaderEntryTranslationView, type ReaderPreviewFailure, type ReaderPreviewFailureCode, type ReaderRecentEntry, type ReaderRefreshResult, type ReaderSentenceLearn, type ReaderSourceSummary, type ReaderStorageStats, type ReaderTag } from './types.ts';
+import { type ReaderAddFailure, type ReaderAddOutcome, type ReaderAddRefusal, type ReaderAnnotationOutcome, type ReaderBackfillCandidate, type ReaderEntryBodyView, type ReaderBody, type ReaderCapabilities, type ReaderMutationOutcome, type ReaderEntryFetchState, type ReaderEntryTranslationView, type ReaderPreviewFailure, type ReaderPreviewFailureCode, type ReaderImageResult, type ReaderRecentEntry, type ReaderRefreshResult, type ReaderSentenceLearn, type ReaderSourceSummary, type ReaderStorageStats, type ReaderTag, type MediaCardStates } from './types.ts';
+import { LocalTranscriber } from './local-transcribe.ts';
+import { ReaderMediaHost } from './media-host.ts';
 /**
  * How many entries one automatic backfill run may fetch.
  *
@@ -46,6 +48,15 @@ import { type ReaderAddFailure, type ReaderAddOutcome, type ReaderAddRefusal, ty
 export declare const BACKFILL_MAX_PER_RUN = 8;
 /** How long a FAILED fetch is left alone before it may be retried (6 hours). */
 export declare const BACKFILL_RETRY_MS: number;
+/**
+ * How many sources one refresh fetches at once.
+ *
+ * A strictly sequential loop made one dead source (a full 30 s timeout) stall
+ * every source behind it — the "refresh takes minutes" half of the slow-load
+ * report. Three at a time is the politeness ceiling this package applies to
+ * other people's servers everywhere (the backfill runs at two).
+ */
+export declare const REFRESH_CONCURRENCY = 3;
 /**
  * Thrown when the FETCH itself failed — a refused connection, a timeout, a
  * response over the seam's byte cap. Carries the seam's own message: the
@@ -73,17 +84,24 @@ export declare function classifyPayload(raw: string): 'feed' | 'page';
 /** The reader service. */
 export declare class ReaderService {
     private readonly store;
+    /** Video and audio entries: synthetic pages, channel feeds, transcripts. */
+    readonly media: ReaderMediaHost;
+    /** Local transcription of entries without captions (the optional `transcribe` engine). */
+    readonly local: LocalTranscriber;
     private readonly ctx;
     private timer;
     private disposed;
     /** The document of record when no filesystem is mounted. */
     private memoryDoc;
+    /** Rescued images, by URL — a pane remount re-fails every blocked image, and this is what keeps that a memory read. */
+    private readonly imageCache;
     /**
      * @param ctx - owning context.
      * @param config - optional state-root override.
      */
     constructor(ctx: Context, config?: {
         stateRoot?: string;
+        ytdlpPath?: string;
     });
     /** Capabilities the browser may rely on. */
     capabilities(): Promise<ReaderCapabilities>;
@@ -230,6 +248,33 @@ export declare class ReaderService {
         truncated?: boolean;
         error?: string;
     }>;
+    /**
+     * One image the browser could not load cross-origin, fetched host-side.
+     *
+     * The pane calls this only for an `<img>` that already FAILED: the page's
+     * bytes arrived fine (a direct fetch gets a 200) but the origin answers them
+     * with `Cross-Origin-Resource-Policy: same-origin`, so the browser withholds
+     * them from this page no matter what the tag asks — measured on claude.dev's
+     * `/media/*` figures (2026-09-29), which broke with the alt text showing.
+     * CORP is an embedder-side check, so a host-process fetch is the way through.
+     *
+     * This deliberately does NOT ride `ctx.web.fetch`: the seam's decoded body is
+     * a closed html|text union and its provider refuses binary content types
+     * outright. The image fetch re-implements the seam's hardening at image
+     * scope instead (public-address validation with the connection pinned to the
+     * validated answers, a byte cap, a timeout, per-hop re-validation, and an
+     * image/* content-type gate) — see `image-fetch.ts`.
+     *
+     * Rescued bytes are kept in an in-memory LRU under a byte budget: the
+     * sidebar unmounts wholesale when another panel takes over, and a remount
+     * re-fails every blocked image before this cache can answer it.
+     *
+     * @param request - the image URL the pane failed on.
+     * @returns the bytes and their declared type, or why there are none.
+     */
+    fetchImage(request: {
+        url: string;
+    }): Promise<ReaderImageResult>;
     /**
      * Which entries have a body, a stored raw payload, or a recorded failure.
      *
@@ -294,6 +339,8 @@ export declare class ReaderService {
         title?: string;
         /** A short excerpt (abstract / first paragraph), with the title. */
         excerpt?: string;
+        /** Keep regardless of the cache TTL (a transcript costs a yt-dlp run, not a page fetch). */
+        keep?: boolean;
     }): Promise<ReaderEntryBodyView>;
     /**
      * Which entries still need their full text, and which may be retried.
@@ -562,6 +609,58 @@ export declare class ReaderService {
      * @returns the final URL and its decoded payload.
      */
     private fetchFollowing;
+    /**
+     * Fetch a source's payload, media-aware (media-host.ts).
+     *
+     * A YouTube channel is fetched as YouTube's own channel feed; a Xiaoyuzhou
+     * podcast page as the RSS document it is turned into; a single video or
+     * Xiaoyuzhou episode as a synthetic page carrying its media description.
+     * Everything else is the ordinary {@link fetchFollowing}.
+     *
+     * @param url - the source URL.
+     */
+    private fetchSource;
+    /**
+     * A video entry's transcript: the stored one, else the platform captions
+     * fetched now and kept (no TTL — it costs a yt-dlp run). A video known to
+     * have no captions answers so without running yt-dlp again.
+     *
+     * @param request - the entry and its video page URL.
+     * @returns the transcript markup, `none`, or why it failed.
+     */
+    mediaTranscript(request: {
+        entryId: string;
+        url: string;
+    }): Promise<{
+        entryId: string;
+        html?: string;
+        captions: 'platform' | 'none' | 'failed';
+        language?: string;
+        error?: string;
+    }>;
+    /** The reader's names for an entry's speakers, by index. */
+    speakerNames(request: {
+        entryId: string;
+    }): Record<string, string>;
+    /**
+     * Name one speaker of an entry's transcript (an empty name restores the default).
+     *
+     * @param request - the entry, the speaker's index, the name.
+     */
+    nameSpeaker(request: {
+        entryId: string;
+        speaker: number;
+        name: string;
+    }): Record<string, string>;
+    /**
+     * The wall's media cards: a live local job first, else what the captions
+     * record says (platform captions, a stored local transcript, none).
+     *
+     * @param request - the card ids on screen.
+     */
+    mediaStates(request: {
+        entryIds: readonly string[];
+    }): MediaCardStates;
     /** Arm (or re-arm) the daily refresh timer against the current document. */
     private armSchedule;
 }