@khorsheed/dsh-reader 0.2.0

package/lib/types/arxiv.d.ts

@@ -0,0 +1,47 @@
+/**
+ * arXiv link recognition, and the upgrade to the official HTML version.
+ *
+ * Many papers carry a LaTeXML-built HTML rendering next to the abstract and the
+ * PDF (`arxiv.org/html/<id>`): real tables, semantic sections and MathML
+ * formulas, where the PDF is a byte stream and the abstract page is a summary.
+ * A pasted `/abs` or `/pdf` link therefore upgrades to the HTML version BEFORE
+ * the first fetch — the reader who pasted the paper meant the paper.
+ *
+ * Pure and network-free, so both the add flow and the link resolvers build on
+ * it; the fetch policy (try the HTML version, fall back on 404) lives in the
+ * service.
+ *
+ * @module @khorsheed/dsh-reader/arxiv
+ */
+/** One parsed arXiv article link. */
+export interface ArxivLink {
+    /** Which of the paper's three faces the link points at. */
+    readonly kind: 'abs' | 'pdf' | 'html';
+    /** The paper id as the link carries it, version suffix (`v2`) included. */
+    readonly id: string;
+}
+/** Whether a bare string is a syntactically valid arXiv id (the resolvers validate API answers with it). */
+export declare function isArxivId(value: string): boolean;
+/**
+ * Parse an arxiv.org link to one paper.
+ *
+ * Only the three single-paper paths count: `/abs`, `/pdf`, `/html`. Listing,
+ * search and author pages name no paper, so they read as ordinary links.
+ *
+ * @param url - the URL as pasted (already normalized by the caller).
+ * @returns the parsed link, or `undefined`.
+ */
+export declare function arxivLink(url: string): ArxivLink | undefined;
+/**
+ * The official HTML version of an `/abs` or `/pdf` link.
+ *
+ * `undefined` when the link IS already the HTML page (no rewrite, so the add
+ * flow can never loop) or is not an arXiv paper link at all. The HTML version
+ * is not guaranteed to exist — old papers lack it — so the caller must treat
+ * a 404 as "no upgrade", not as a failure of the link.
+ *
+ * @param url - the pasted arXiv URL.
+ * @returns the HTML version's URL, or `undefined`.
+ */
+export declare function arxivHtmlUrl(url: string): string | undefined;
+//# sourceMappingURL=arxiv.d.ts.map

package/lib/types/arxiv.js

@@ -0,0 +1,76 @@
+/**
+ * arXiv link recognition, and the upgrade to the official HTML version.
+ *
+ * Many papers carry a LaTeXML-built HTML rendering next to the abstract and the
+ * PDF (`arxiv.org/html/<id>`): real tables, semantic sections and MathML
+ * formulas, where the PDF is a byte stream and the abstract page is a summary.
+ * A pasted `/abs` or `/pdf` link therefore upgrades to the HTML version BEFORE
+ * the first fetch — the reader who pasted the paper meant the paper.
+ *
+ * Pure and network-free, so both the add flow and the link resolvers build on
+ * it; the fetch policy (try the HTML version, fall back on 404) lives in the
+ * service.
+ *
+ * @module @khorsheed/dsh-reader/arxiv
+ */
+/**
+ * The id shapes arXiv assigns: new-style `YYMM.NNNNN(vN)` (month-keyed, four or
+ * five sequence digits — six from 2027 on), or the archived subject-class form
+ * `hep-th/9901001(vN)` / `math.GT/0309136(vN)`.
+ */
+const ARXIV_ID = /^(?:\d{4}\.\d{4,6}|[a-z-]+(?:\.[A-Z]{2})?\/\d{7})(?:v\d+)?$/;
+/** Whether a bare string is a syntactically valid arXiv id (the resolvers validate API answers with it). */
+export function isArxivId(value) {
+    return ARXIV_ID.test(value);
+}
+/**
+ * Parse an arxiv.org link to one paper.
+ *
+ * Only the three single-paper paths count: `/abs`, `/pdf`, `/html`. Listing,
+ * search and author pages name no paper, so they read as ordinary links.
+ *
+ * @param url - the URL as pasted (already normalized by the caller).
+ * @returns the parsed link, or `undefined`.
+ */
+export function arxivLink(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (host !== 'arxiv.org' && host !== 'www.arxiv.org')
+        return undefined;
+    // The id itself may carry one slash (the old `archive/YYMMNNN` form), so the
+    // capture runs to the query/fragment and the id pattern below is the judge.
+    const match = /^\/(abs|pdf|html)\/([^?#]+)/.exec(parsed.pathname);
+    const kind = match?.[1];
+    let id = match?.[2];
+    if (kind === undefined || id === undefined)
+        return undefined;
+    // A pdf link may spell the id with its file suffix: `/pdf/1706.03762v7.pdf`.
+    if (kind === 'pdf' && /\.pdf$/i.test(id))
+        id = id.slice(0, -4);
+    if (!ARXIV_ID.test(id))
+        return undefined;
+    return { kind, id };
+}
+/**
+ * The official HTML version of an `/abs` or `/pdf` link.
+ *
+ * `undefined` when the link IS already the HTML page (no rewrite, so the add
+ * flow can never loop) or is not an arXiv paper link at all. The HTML version
+ * is not guaranteed to exist — old papers lack it — so the caller must treat
+ * a 404 as "no upgrade", not as a failure of the link.
+ *
+ * @param url - the pasted arXiv URL.
+ * @returns the HTML version's URL, or `undefined`.
+ */
+export function arxivHtmlUrl(url) {
+    const link = arxivLink(url);
+    if (link === undefined || link.kind === 'html')
+        return undefined;
+    return `https://arxiv.org/html/${link.id}`;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * The inspiration space: the right-Sidebar tab body.
+ *
+ * It is the only React surface this package ships, and it owns the whole
+ * interaction the design settled on:
+ *
+ * - **the wall** — one card per entry, with a search box, an all/today filter,
+ *   an unread-only toggle and a sort menu. All four are local predicates over
+ *   entries this process parsed (design decision D14), so none of them costs a
+ *   round trip.
+ * - **the detail view** — clicking a card opens it. This is the whole point:
+ *   the body renders as DOM text, which is what makes passage quoting work
+ *   (the QUOTE plugin's own selection menu sees it), and it is why the pane
+ *   never hosts a sandboxed iframe.
+ * - **the add dialog** — an overlay in the members-tab idiom, because adding is
+ *   a momentary act and the wall should stay where it was behind it. The host
+ *   decides whether a pasted URL is a feed or an article from what comes back
+ *   (D15); this surface reports the verdict, plus the fetch seam's own words
+ *   when the fetch failed.
+ * - **the subscription page** — every source with its schedule, its pause
+ *   switch and its last-fetch status. It exists because "why am I not seeing
+ *   anything" and "stop refreshing this one" are questions about SOURCES, and
+ *   neither belongs on the wall.
+ *
+ * The browser has no XML parser on the host side to lean on, so the pane parses
+ * payloads itself through `parse-rss` / `extract-article`.
+ *
+ * @module @khorsheed/dsh-reader/client/ReaderPane
+ */
+import { type ReactNode } from 'react';
+import type { ReaderPaneProps } from './contract.ts';
+import { type ReaderReadingAnchor } from './session.ts';
+/**
+ * One top-level block, measured.
+ *
+ * `textLength` is captured in the same pass so the scroll handler can record a
+ * TEXT offset without touching the DOM; `element` is what lets a restore
+ * resolve that offset to an exact pixel spot (a Range rect) later.
+ */
+export interface ArticleBlockMetrics {
+    readonly top: number;
+    readonly height: number;
+    /** How long the block's text was at measure time. */
+    readonly textLength: number;
+    /** The block itself, for the text-offset resolution. */
+    readonly element: HTMLElement;
+}
+/**
+ * How far into the anchor block the viewport top sat, in the CURRENT layout.
+ *
+ * A pixel offset into a block is only valid for the layout it was measured in,
+ * and the translated view IS a different layout: the same paragraph sets
+ * different words at a different height, so the recorded `offset` points at the
+ * wrong sentence — the drift the reader reported. The recorded TEXT offset is
+ * the fix: when the block still holds the same text it resolves to an exact
+ * pixel spot (a Range rect over the text node that holds that character); when
+ * the words changed, the same FRACTION of the text is the honest place. An
+ * anchor written before the text offset existed falls back to the pixel offset,
+ * unchanged.
+ *
+ * Exported for the specs; the pane itself reaches it through
+ * `applyReadingPosition`.
+ *
+ * @param block - the anchor block's CURRENT metrics.
+ * @param anchor - the recorded place.
+ * @returns pixels into the block.
+ */
+export declare function offsetInBlock(block: ArticleBlockMetrics, anchor: ReaderReadingAnchor): number;
+/** The reader tab body. */
+export declare function ReaderPane(props: ReaderPaneProps): ReactNode;
+//# sourceMappingURL=ReaderPane.d.ts.map