@khorsheed/dsh-reader 0.2.0

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

@@ -0,0 +1,254 @@
+/**
+ * Compile-time contract between the reader's browser half and its host half.
+ *
+ * Nothing here executes: this module holds the shapes only, so a change in the
+ * Remote surface or in the injected business face breaks compilation at the
+ * components that consume them instead of at runtime.
+ *
+ * @module @khorsheed/dsh-reader/client/contract
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { GlobalStandardProps, InjectFace, PropsLocale, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ReaderAddFailure, ReaderAddOutcome, ReaderAddRefusal, ReaderAnnotationOutcome, ReaderBackfillCandidate, ReaderEntryBodyView, ReaderEntryFetchState, ReaderBody, ReaderCapabilities, ReaderEntryTranslationView, ReaderMutationOutcome, ReaderRefreshResult, ReaderRecentEntry, ReaderSentenceLearn, ReaderSourceSummary, ReaderStorageStats, ReaderTag } from '../types.ts';
+import type { createReaderStore } from './store.ts';
+export type { RemoteResult };
+/** The result of extracting one article, as the detail view consumes it. */
+export interface ReaderArticle {
+    /** Whitelisted body markup, ready to render. */
+    readonly html: string;
+    /** True when the body is known to be incomplete (size cap or partial parse). */
+    readonly truncated: boolean;
+    /** Set when nothing usable could be extracted. */
+    readonly error?: string;
+}
+/**
+ * The capture package's Remote face (the ingest proposal's M1), mirrored
+ * structurally — never imported. Absent namespaces probe as undefined.
+ */
+export interface ReaderCaptureRemote {
+    /** Render a URL in the managed browser and hand back the serialized page. */
+    render: (request: {
+        url: string;
+        timeoutMs?: number;
+    }) => Promise<RemoteResult<{
+        html: string;
+        finalUrl?: string;
+        title?: string;
+        truncated?: boolean;
+    }>>;
+}
+/**
+ * What the pane's own extraction read from the article, beyond the stored body:
+ * the article's own title and a short excerpt. A saved link's card upgrades
+ * from the URL-derived label to these; a feed entry's title is already the
+ * publisher's and is never overridden.
+ */
+export interface ReaderExtractedMeta {
+    readonly title?: string;
+    readonly excerpt?: string;
+}
+/**
+ * The business face every reader surface receives from its registration.
+ *
+ * The wire verbs come straight off the Remote; the last four are local
+ * gestures the pane cannot perform itself (they need the session scope, the
+ * clipboard, or the browser), so `client/index.ts` injects them.
+ */
+export interface ReaderPaneInjected {
+    /** Round-trip the capability handshake. */
+    capabilities: () => Promise<RemoteResult<ReaderCapabilities>>;
+    /** The configured sources, newest first. */
+    listSources: () => Promise<RemoteResult<{
+        sources: ReaderSourceSummary[];
+    }>>;
+    /** Add a feed or a pasted article; the host decides which by content. */
+    addSource: (url: string) => Promise<RemoteResult<ReaderAddOutcome | ReaderAddRefusal | ReaderAddFailure>>;
+    /** Change a source's label/enabled flag, or the global refresh time. */
+    updateSource: (request: {
+        id: string;
+        enabled?: boolean;
+        label?: string;
+        url?: string;
+        timeOfDay?: string;
+    }) => Promise<RemoteResult<ReaderMutationOutcome>>;
+    /** Drop a source. Its entries' translation maps go with it (the caller passes the ids it parsed). */
+    removeSource: (id: string, entryIds?: readonly string[]) => Promise<RemoteResult<ReaderMutationOutcome>>;
+    /** Fetch the named sources, or every enabled one. */
+    refresh: (ids?: string[]) => Promise<RemoteResult<{
+        results: ReaderRefreshResult[];
+    }>>;
+    /** Raw payloads, for this process to parse (the host never parses). */
+    getBodies: (ids: string[]) => Promise<RemoteResult<{
+        bodies: ReaderBody[];
+    }>>;
+    /** Offer a ref block to the side-chat service when one is composed. */
+    quoteToSideChat: (request: {
+        contextKey: string;
+        label: string;
+        text: string;
+    }) => Promise<RemoteResult<'ok' | 'unavailable'>>;
+    /** What the plugin holds per entry: a body, a stored payload, or a failure. */
+    entryFetchStates: (entryIds: readonly string[]) => Promise<RemoteResult<{
+        states: Record<string, ReaderEntryFetchState>;
+    }>>;
+    /** Cache body markup this process holds (the sweep's extractions, or a feed's own full text on open). */
+    storeEntryBody: (request: {
+        entryId: string;
+        url: string;
+        html: string;
+        truncated?: boolean;
+        scriptFigures?: number;
+        /** This body came from the capture rendered fetch; 「重新抓取」 re-renders rather than plain-fetches it. */
+        rendered?: boolean;
+        /** `translationHash(html)` — the entry's translation map dies with a body it no longer matches. */
+        bodyHash?: string;
+        /** The article's own title, as extracted — a saved link's card upgrade. */
+        title?: string;
+        /** A short excerpt (the first substantial paragraph), with the title. */
+        excerpt?: string;
+    }) => Promise<RemoteResult<ReaderEntryBodyView>>;
+    /** A payload the host stored, so this process can extract it (late or never). */
+    getRawBody: (entryId: string) => Promise<RemoteResult<{
+        entryId: string;
+        raw?: string;
+        url?: string;
+        truncated?: boolean;
+        error?: string;
+    }>>;
+    /**
+     * The entries whose full text still has to be filled in (the automatic
+     * backfill's work list; the host owns the policy, this process owns the DOM).
+     */
+    listBackfillCandidates: (entries: readonly {
+        entryId: string;
+        url: string;
+        label: string;
+        hasBody: boolean;
+    }[]) => Promise<RemoteResult<{
+        candidates: ReaderBackfillCandidate[];
+    }>>;
+    /**
+     * What the host has for one entry: a fresh cached body, else the feed's own
+     * payload, else nothing (plus why a previous fetch failed).
+     */
+    getEntryBody: (request: {
+        entryId: string;
+        url: string;
+        feedHtml?: string;
+    }) => Promise<RemoteResult<ReaderEntryBodyView>>;
+    /**
+     * Fetch one entry's article, extract it in THIS process (the host has no
+     * parser) and cache what came out. One call from the view's perspective; the
+     * extracted title/excerpt ride along for the card upgrade.
+     */
+    fetchEntryBody: (entryId: string, url: string) => Promise<ReaderEntryBodyView & ReaderExtractedMeta>;
+    /** The tags on one entry. */
+    entryTags: (entryId: string) => Promise<RemoteResult<{
+        tags: ReaderTag[];
+    }>>;
+    /** The tag vocabulary, with per-tag usage counts. */
+    listTags: () => Promise<RemoteResult<{
+        tags: ReaderTag[];
+        counts: Record<string, number>;
+    }>>;
+    /** Create a tag, or return the existing one whose name matches. */
+    createTag: (name: string) => Promise<RemoteResult<ReaderTag | ReaderAnnotationOutcome>>;
+    /** Add or remove one tag on one entry. */
+    tagEntry: (entryId: string, tagId: string, on: boolean) => Promise<RemoteResult<ReaderAnnotationOutcome>>;
+    /** Rename a tag. */
+    renameTag: (id: string, name: string) => Promise<RemoteResult<ReaderAnnotationOutcome>>;
+    /** Delete a tag everywhere. */
+    deleteTag: (id: string) => Promise<RemoteResult<ReaderAnnotationOutcome>>;
+    /** Drop tags nothing references any more. */
+    pruneTags: () => Promise<RemoteResult<{
+        removed: number;
+    }>>;
+    /** Record that the reader opened one entry (the 「最近阅读」 page's write half). */
+    recordRead: (request: {
+        entryId: string;
+        sourceId: string;
+        title: string;
+        url?: string;
+    }) => Promise<RemoteResult<{
+        entries: number;
+    }>>;
+    /** The entries the reader opened, newest first. */
+    listRecent: () => Promise<RemoteResult<{
+        entries: ReaderRecentEntry[];
+    }>>;
+    /** Forget every recent entry. */
+    clearRecent: () => Promise<RemoteResult<{
+        removed: number;
+    }>>;
+    /** Read / set the article cache policy (and the translation budget). */
+    getCachePolicy: () => Promise<RemoteResult<{
+        ttlHours: number;
+        maxEntries: number;
+        translationBudgetChars: number;
+    }>>;
+    setCachePolicy: (ttlHours: number, maxEntries?: number, translationBudgetChars?: number) => Promise<RemoteResult<ReaderAnnotationOutcome>>;
+    /** One entry's exact-fit translation record, when the host holds a usable one. */
+    getEntryTranslation: (entryId: string) => Promise<RemoteResult<{
+        translation?: ReaderEntryTranslationView;
+    }>>;
+    /** Translations for exactly the asked sentence hashes of one pair (never the table). */
+    getSentenceTranslations: (request: {
+        pair: string;
+        hashes: readonly string[];
+    }) => Promise<RemoteResult<{
+        translations: Record<string, string>;
+    }>>;
+    /**
+     * Persist what one translation run learned (and refresh what it reused), in
+     * one batch — the caller batches by run, so this is never a per-sentence call.
+     */
+    rememberSentences: (request: {
+        pair: string;
+        entries: readonly ReaderSentenceLearn[];
+        recalled?: readonly ReaderSentenceLearn[];
+        entryId?: string;
+        bodyHash?: string;
+    }) => Promise<RemoteResult<{
+        stored: number;
+    }>>;
+    /** Per-tier cache usage, aggregated on the host (the manage page's readout). */
+    getStorageStats: () => Promise<RemoteResult<ReaderStorageStats>>;
+    /** Forget every translation: the global memory and every entry map. */
+    clearTranslations: () => Promise<RemoteResult<{
+        clearedEntries: number;
+        clearedMemory: boolean;
+    }>>;
+    /** Read the current conversation draft (the merge `setDraft` needs). */
+    readDraft: () => string;
+    /** Replace the conversation draft with `merged`; a no-op without a session surface. */
+    setDraft: (merged: string) => void;
+    /** Copy text to the clipboard; resolves false when the API is unavailable. */
+    copyText: (text: string) => Promise<boolean>;
+    /** Open a URL in the user's browser; false when the platform refuses. */
+    openExternal: (url: string) => boolean;
+    /**
+     * Whether the host's in-app Sidebar Browser is mounted (probed live: the tab
+     * kind `browser` exists on host 0.1.6-alpha.2+). When it is, fetches that
+     * need a real browser — a page that draws its figures with scripts, a bot
+     * wall — get an in-app way out instead of only an external link.
+     */
+    browserTabAvailable: () => boolean;
+    /**
+     * Open a URL in the in-app Sidebar Browser; false when the seam is absent or
+     * refuses, so the caller falls back to {@link ReaderPaneInjected.openExternal}.
+     */
+    openBrowserTab: (url: string) => boolean;
+    /**
+     * The capture package's Remote, when one is mounted — the 「渲染抓取」 slot
+     * renders only while this answers. M0 ships no capture package (it is the
+     * ingest proposal's M1), so the probe is the whole point today: probed live,
+     * never cached, never thrown.
+     */
+    captureRemote: () => ReaderCaptureRemote | undefined;
+}
+/** Full props of the reader pane: the seat's session + store + locale + face. */
+export type ReaderPaneProps = {
+    sessionId: SessionId;
+} & GlobalStandardProps & PropsStore<ReturnType<typeof createReaderStore>> & InjectFace<ReaderPaneInjected> & PropsLocale<'reader'>;
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/client/contract.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,27 @@
+/**
+ * Stage one of the reader's right-Sidebar registration: the tab type, the body
+ * of which is registered in `client/index.ts`.
+ *
+ * The kind is MINTED (`reader`) rather than taken over: this is a page type of
+ * its own, not a superset of an official one, so it claims no address and ships
+ * no `patterns` / `canOpen`. It joins the guide page as its own card, which is
+ * how a reader finds it before pinning the tab.
+ *
+ * @module @khorsheed/dsh-reader/client/definition
+ */
+import type { SidebarRightTabDefinition } from '@deepseek-ai/dsh-client-ui-sidebar-right/client';
+import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client';
+/** The tab kind: minted, since no official kind means "reader". */
+export declare const READER_KIND = "reader";
+/** This implementation's identity, and the key its body registers under. */
+export declare const READER_TAB_ID = "@khorsheed/dsh-reader";
+/**
+ * The reader type's registry definition. No `priority` (the default
+ * `extension` band is right for a type from outside the product) and no
+ * `patterns`/`canOpen` (a page type recognises no address).
+ *
+ * @param t - the reader namespace's translator.
+ * @returns the definition to register.
+ */
+export declare function readerDefinition(t: TranslateNS<'reader'>): SidebarRightTabDefinition;
+//# sourceMappingURL=definition.d.ts.map

package/lib/types/client/definition.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { IconGlobeOutlineMedium } from "./icons.js";
+/** The tab kind: minted, since no official kind means "reader". */
+export const READER_KIND = 'reader';
+/** This implementation's identity, and the key its body registers under. */
+export const READER_TAB_ID = '@khorsheed/dsh-reader';
+/** The type's glyph on the guide card. */
+function ReaderGlyph({ size, className }) {
+    return _jsx(IconGlobeOutlineMedium, { size: size, className: className });
+}
+/**
+ * The reader type's registry definition. No `priority` (the default
+ * `extension` band is right for a type from outside the product) and no
+ * `patterns`/`canOpen` (a page type recognises no address).
+ *
+ * @param t - the reader namespace's translator.
+ * @returns the definition to register.
+ */
+export function readerDefinition(t) {
+    return {
+        id: READER_TAB_ID,
+        kind: READER_KIND,
+        title: () => t('tab.label'),
+        guide: [{
+                id: READER_KIND,
+                order: 60,
+                title: () => t('tab.label'),
+                description: () => t('guide.description'),
+                icon: ReaderGlyph,
+            }],
+    };
+}

package/lib/types/client/extract-article.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Article extraction and rich-text normalization for the browser half.
+ *
+ * Two exports, one for each shape of input the reader handles:
+ *
+ * - {@link extractArticle} takes a fetched HTML page and finds its body. The
+ *   honest problem here is that which block is "the article" is a heuristic:
+ *   this module scores candidate blocks the way readability implementations do
+ *   (paragraph mass, minus link mass, with wrapper blocks demoted) and adds the
+ *   one signal that a single-language scorer gets wrong — Chinese paragraphs
+ *   are short by nature, so a length threshold tuned for English rejects them
+ *   and the scorer falls back to the whole page container (measured: 473 <p>
+ *   and 56 images instead of the article).
+ * - {@link normalizeRichText} takes markup that is ALREADY known to be a body
+ *   (a feed's `content:encoded`, or the block extraction selected) and puts it
+ *   through a tag whitelist, so the renderer never sees third-party scripts,
+ *   styles, forms or event handlers.
+ *
+ * Everything runs in the browser because the host runtime has no DOM parser at
+ * all; nothing here touches the network.
+ *
+ * @module @khorsheed/dsh-reader/client/extract-article
+ */
+/** Result of extracting one article page. */
+export type ExtractArticleResult = {
+    readonly ok: true;
+    readonly html: string;
+    readonly textLength: number;
+    /**
+     * The article's own title, when one is recoverable: the body's first
+     * heading, else the document's `<title>`. A saved link's card upgrades from
+     * the URL-derived label to this — the wall is where "which paper was this"
+     * gets answered.
+     */
+    readonly title?: string;
+    /**
+     * A short plain-text excerpt (the first substantial paragraph, truncated at
+     * the card's measure), captured with the title.
+     */
+    readonly excerpt?: string;
+    /**
+     * How many figures had to be dropped because the page DRAWS them.
+     *
+     * Measured on the acceptance instance's transformer-circuits.pub paper:
+     * `<figure data-fignum="2">` contains an empty `<div class='intro-structural'>`
+     * and a caption, and the illustration is rendered by the page's own scripts.
+     * A fetch runs no scripts, so what arrives is a caption describing a picture
+     * that is not there. Dropping the empty figure and saying so beats leaving a
+     * bare caption the reader will read as "the plugin lost my image".
+     */
+    readonly scriptFigures?: number;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Extract the article body from a fetched page.
+ *
+ * @param pageHtml - the raw HTML the host fetched.
+ * @param baseUrl - the page URL, used to absolutize relative links and images.
+ * @returns the normalized body HTML, or the reason nothing usable was found.
+ */
+export declare function extractArticle(pageHtml: string, baseUrl: string): ExtractArticleResult;
+/**
+ * Put trusted-shape markup through the whitelist.
+ *
+ * Feed bodies take this path: a feed's `content:encoded` is markup from the
+ * same publisher as the page, so it earns the same whitelist rather than the
+ * extraction heuristic.
+ *
+ * @param html - markup from a feed or from extraction.
+ * @param baseUrl - base for relative URLs (feed bodies usually use absolute ones).
+ * @returns whitelisted HTML, or an empty string when nothing survives.
+ */
+export declare function normalizeRichText(html: string, baseUrl?: string): string;
+/**
+ * The payload size that separates a real inlined figure from a 1px tracking
+ * placeholder. A transparent-gif placeholder is ~70 characters of base64; the
+ * smallest real chart is thousands — the threshold sits far from both, so no
+ * borderline page ever decides anything. (transformer-circuits.pub inlines its
+ * real figures as multi-hundred-KB data URIs; the old all-data:-is-placeholder
+ * rule deleted them.)
+ */
+export declare const DATA_IMAGE_MIN_PAYLOAD = 512;
+/**
+ * A `data:` URI worth keeping as an image, or `undefined` (which reads as
+ * ABSENT — the caller falls through to the lazy-loading attributes).
+ *
+ * The gate is MIME plus payload size; base64 payloads are whitespace-stripped
+ * because pages line-wrap them (a raw newline inside an emitted attribute is
+ * legal HTML, but the stripped form is what browsers parse either way).
+ */
+export declare function substantiveDataImage(value: string): string | undefined;
+/**
+ * Turn an inline-only rendering of a node into plain text-safe markup. Feed
+ * summaries use this shape when the caller wants emphasis but no blocks.
+ *
+ * @param html - markup.
+ * @returns normalized inline markup.
+ */
+export declare function normalizeInline(html: string): string;
+//# sourceMappingURL=extract-article.d.ts.map