@khorsheed/dsh-reader 0.2.0

package/lib/types/client/selectors.js

@@ -0,0 +1,413 @@
+import { kindQuery, READER_SOURCE_KINDS } from "../types.js";
+/** How many entries the pane will show before it stops rendering cards. */
+export const LIST_RENDER_LIMIT = 300;
+/** Every parsed entry, flattened in source order. */
+export function flattenEntries(parsed) {
+    const out = [];
+    for (const source of Object.values(parsed))
+        out.push(...source.entries);
+    return out;
+}
+/**
+ * What the plugin holds for one entry, as every surface reads it.
+ *
+ * The host's annotation is the only authority (a cached body, an in-flight or
+ * stored-raw fetch, a classified failure with its reason); the pane mirrors it
+ * per entry, and this is the ONE read path into that mirror — including the
+ * default, so no surface spells "no record" as anything other than `none`.
+ *
+ * @param states - the pane's mirror of the host's fetch states.
+ * @param entryId - the entry being shown.
+ * @returns the entry's fetch state.
+ */
+export function fetchStateOf(states, entryId) {
+    return states[entryId] ?? { state: 'none' };
+}
+/**
+ * Apply the filter, the query and the sort.
+ *
+ * @param entries - the parsed entries.
+ * @param sources - presentation metadata per source id.
+ * @param options - the current filter/query/sort plus the session's read cursor.
+ * @returns the rows to render, newest-first unless the sort says otherwise.
+ */
+export function selectRows(entries, sources, options) {
+    const query = options.query.trim().toLowerCase();
+    const rows = [];
+    for (const entry of entries) {
+        const source = sources.get(entry.sourceId);
+        if (source === undefined)
+            continue;
+        if (options.unreadOnly && options.read[entry.id] === true)
+            continue;
+        if (options.filter === 'today' && !isToday(entry.publishedAt, options.now))
+            continue;
+        if (query.length > 0 && !matches(entry, source, query, options.tags ?? {}))
+            continue;
+        rows.push({
+            entry,
+            sourceId: source.id,
+            sourceLabel: source.label,
+            sourceTile: source.tile,
+            sourceHue: source.hue,
+            sourceAddedAt: source.addedAt,
+            sourceKind: source.kind,
+            unread: options.read[entry.id] !== true,
+        });
+    }
+    sortRows(rows, options.sort);
+    // Relevance before the chosen order, but only for a TEXT search: a phrase
+    // that appears in a title is what the reader meant, and leaving a title match
+    // buried under newer summary matches is how a search "returns the wrong
+    // things first". `#sourceId` / `@tagId` selectors are not ranked — every row
+    // matches them the same way. Array#sort is stable, so the chosen order is
+    // what the rows inside one tier keep.
+    if (query.length > 0 && !query.startsWith('#') && !query.startsWith('@')) {
+        rows.sort((a, b) => relevance(a.entry.title, query) - relevance(b.entry.title, query));
+    }
+    return rows.slice(0, LIST_RENDER_LIMIT);
+}
+/**
+ * The row for one entry, when its source is still known.
+ *
+ * `selectRows` builds rows for the LIST; the detail view needs the same row for
+ * one entry it was told to reopen (a restored reading position), and rebuilding
+ * the row by hand there would be a second, drifting copy of this mapping.
+ *
+ * @param entry - the entry to present.
+ * @param sources - presentation metadata per source id.
+ * @param read - the session's read cursor.
+ * @returns the row, or `undefined` when the entry's source is gone.
+ */
+export function rowFor(entry, sources, read) {
+    const source = sources.get(entry.sourceId);
+    if (source === undefined)
+        return undefined;
+    return {
+        entry,
+        sourceId: source.id,
+        sourceLabel: source.label,
+        sourceTile: source.tile,
+        sourceHue: source.hue,
+        sourceAddedAt: source.addedAt,
+        sourceKind: source.kind,
+        unread: read[entry.id] !== true,
+    };
+}
+/**
+ * Whether an entry belongs in the "today" view.
+ *
+ * An entry with NO usable date is kept, not dropped. The default filter is
+ * `today`, and a saved article link carries no `publishedAt` at all — dropping
+ * undated entries would make the primary add-a-link flow produce a link the
+ * reader can never see. A date the reader cannot compare is likewise not
+ * evidence that the entry is old.
+ *
+ * @param iso - the feed-declared timestamp, when there is one.
+ * @param now - the reference day.
+ * @returns true when the entry is on that day, or carries no comparable date.
+ */
+export function isToday(iso, now) {
+    if (iso === undefined)
+        return true;
+    const parsed = new Date(iso);
+    if (Number.isNaN(parsed.getTime()))
+        return true;
+    return parsed.getFullYear() === now.getFullYear()
+        && parsed.getMonth() === now.getMonth()
+        && parsed.getDate() === now.getDate();
+}
+/**
+ * The query that selects exactly one source's entries.
+ *
+ * The search box and the source strip are the same mechanism — one local
+ * predicate (D14) — so a source filter is a query the reader can also see and
+ * edit. The two-character prefix keeps it out of the way of real search terms:
+ * no title search will accidentally match it, and the id is stable across
+ * renames.
+ *
+ * @param sourceId - the source to select.
+ * @returns the query string.
+ */
+export function sourceQuery(sourceId) {
+    return `#${sourceId}`;
+}
+/**
+ * The query that selects everything carrying one tag.
+ *
+ * @param tagId - the tag to select.
+ * @returns the query string.
+ */
+export function tagQuery(tagId) {
+    return `@${tagId}`;
+}
+/**
+ * How directly a title answers a text query: 0 exact, 1 contains, 2 elsewhere.
+ *
+ * @param title - the entry title.
+ * @param query - the lower-cased query.
+ * @returns the tier, lowest first.
+ */
+function relevance(title, query) {
+    const lower = title.toLowerCase();
+    if (lower === query)
+        return 0;
+    return lower.includes(query) ? 1 : 2;
+}
+/** Whether an entry matches the query, across the fields a reader searches by. */
+function matches(entry, source, query, tags) {
+    if (query.startsWith('#')) {
+        const selector = query.slice(1);
+        // A kind selector first: source ids are always `<kind>-<hash>`, so
+        // `#link` can never be one, and the two vocabularies stay disjoint.
+        const kind = READER_SOURCE_KINDS.find(candidate => kindQuery(candidate) === query);
+        if (kind !== undefined)
+            return source.kind === kind;
+        return selector === entry.sourceId;
+    }
+    if (query.startsWith('@'))
+        return (tags[entry.id] ?? []).includes(query.slice(1));
+    const haystack = [
+        entry.title,
+        entry.summary ?? '',
+        entry.author ?? '',
+        source.label,
+        ...(entry.tags ?? []),
+    ].join(' ').toLowerCase();
+    return haystack.includes(query);
+}
+/**
+ * When a row belongs on a time-ordered wall.
+ *
+ * An entry's own date wins; a saved link has none at all, so it falls back to
+ * when the SOURCE was added. An entry with neither (a hand-made link entry
+ * from a source whose document predates `addedAt`) sorts as `0`, i.e. last,
+ * which is the old behaviour and still deterministic.
+ *
+ * @param row - the row to date.
+ * @returns milliseconds, or `0` when the row carries no comparable date.
+ */
+function timeOf(row) {
+    const iso = row.entry.publishedAt ?? row.sourceAddedAt;
+    const parsed = iso === undefined ? Number.NaN : new Date(iso).getTime();
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/** Sort in place: newest first, oldest first, or grouped by source. */
+function sortRows(rows, sort) {
+    if (sort === 'newest') {
+        rows.sort((a, b) => timeOf(b) - timeOf(a));
+        return;
+    }
+    if (sort === 'oldest') {
+        rows.sort((a, b) => timeOf(a) - timeOf(b));
+        return;
+    }
+    // Grouped: source name first, then newest inside each group. The comparison
+    // is total (ties broken by the stable entry id) so repeated renders of the
+    // same data never reshuffle.
+    rows.sort((a, b) => {
+        if (a.sourceLabel !== b.sourceLabel)
+            return a.sourceLabel < b.sourceLabel ? -1 : 1;
+        const delta = timeOf(b) - timeOf(a);
+        if (delta !== 0)
+            return delta;
+        return a.entry.id < b.entry.id ? -1 : a.entry.id > b.entry.id ? 1 : 0;
+    });
+}
+/** How many of these rows are still unread. */
+export function countUnread(rows) {
+    return rows.reduce((count, row) => count + (row.unread ? 1 : 0), 0);
+}
+/* -------------------------------------------------------------- wall dedupe */
+/**
+ * Wall dedupe: aggregated feeds republish the same article, and the wall
+ * should show it once (measured on the reader's own wall: "An Alien Mind"
+ * under both an aggregator and the source blog).
+ *
+ * Grouping is deliberately NEVER fuzzy — a miss costs one duplicate card, a
+ * false positive costs an article. Three tiers, strongest first; a match on
+ * ANY tier groups (they compose transitively — an id-match and a link-match
+ * bridge two groups into one):
+ *
+ * 1. **Same entry id** — the strongest signal there is: `stableEntryId` shares
+ *    one id across copies BY DESIGN (a shared guid buys shared fetch/read/
+ *    translation state), so a guid collision is the publisher saying "same
+ *    item", and it folds even when the copies' links differ.
+ * 2. **Normalized link** (any entry that has one): scheme, `www.` and
+ *    trailing slashes stripped, tracking parameters (`utm_*`, `fbclid`,
+ *    `gclid`, `ref`, `spm`, …) removed, the rest of the query sorted.
+ * 3. **Folded title + same published day**: case, accents and punctuation
+ *    folded; BOTH entries must carry a comparable date, so undated saved links
+ *    never title-group.
+ */
+/** Query keys that never change which article a link names. */
+const TRACKING_PARAMS = new Set([
+    'fbclid', 'gclid', 'spm', 'ref', 'ref_src', 'source', 'mc_cid', 'mc_eid', 'igshid',
+]);
+/** The dedupe key for an entry's link, or `undefined` when it has none worth one. */
+function linkKey(link) {
+    if (link === undefined)
+        return undefined;
+    try {
+        const url = new URL(link.trim());
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return undefined;
+        const host = url.hostname.toLowerCase().replace(/^www\./, '');
+        const path = url.pathname.replace(/\/+$/, '');
+        const params = [...url.searchParams.entries()]
+            .filter(([key]) => !/^utm_/i.test(key) && !TRACKING_PARAMS.has(key.toLowerCase()))
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        const query = params.map(([key, value]) => `${key}=${value}`).join('&');
+        return `${host}${path}${query === '' ? '' : `?${query}`}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The dedupe key for an entry's title + day, or `undefined` when either is missing. */
+function titleDayKey(entry) {
+    const title = entry.title
+        .normalize('NFKD')
+        .replace(/\p{M}/gu, '')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+    // A handful of characters is a topic, not a title: folding "Go 语言" onto
+    // itself across two feeds is a false positive, not a duplicate.
+    if (title.length < 6)
+        return undefined;
+    const parsed = entry.publishedAt === undefined ? Number.NaN : new Date(entry.publishedAt).getTime();
+    if (Number.isNaN(parsed))
+        return undefined;
+    return `${title}|${entry.publishedAt.slice(0, 10)}`;
+}
+/** Every tier key an entry qualifies for (the id tier always applies). */
+function dedupeKeysOf(entry) {
+    const keys = [`i:${entry.id}`];
+    const link = linkKey(entry.link);
+    if (link !== undefined)
+        keys.push(`l:${link}`);
+    const title = titleDayKey(entry);
+    if (title !== undefined)
+        keys.push(`t:${title}`);
+    return keys;
+}
+/**
+ * Fold duplicate rows into their survivors.
+ *
+ * Survivor choice, in order: a member whose body the host already holds
+ * (a `ready` fetch state — the fetched copy opens instantly) beats a NEWER
+ * member, and a tie keeps the input order. Same-id copies share the id-keyed
+ * fetch-state record, so between them the choice is always the input order —
+ * they share every annotation anyway. The survivor sits at its own position in
+ * the row order. Read state merges across the group: the card reads as read
+ * when ANY copy was read (free via the shared id for same-id copies). Hidden
+ * rows are reported, never deleted — the card badges them.
+ *
+ * All bookkeeping is POSITIONAL (row indexes), never id-keyed for the fold
+ * itself: two copies of one article can share ONE entry id by design, and
+ * id-keyed folding keeps both — the survivor's id is the hidden copy's id.
+ * Only the badge lookup (`dupesBy`) is id-keyed, which is safe: the surviving
+ * card is the only rendered row carrying that id.
+ *
+ * @param rows - the wall's rows (selectRows' output: filtered and sorted).
+ * @param fetchStates - the pane's fetch-state mirror, for the ready signal.
+ * @returns the rows to render, and where the hidden ones went.
+ */
+export function dedupeRows(rows, fetchStates = {}) {
+    // Multi-tier grouping with bridging: a row joins the group any of its tier
+    // keys names, and a row whose keys name two groups merges them (A≡B by id
+    // and B≡C by link fold all three).
+    const keyToGroup = new Map();
+    const groupRows = [];
+    const groupKeys = [];
+    rows.forEach((row, index) => {
+        const keys = dedupeKeysOf(row.entry);
+        const hits = [...new Set(keys.map(key => keyToGroup.get(key)).filter((group) => group !== undefined))];
+        if (hits.length === 0) {
+            const created = groupRows.length;
+            groupRows.push([index]);
+            groupKeys.push([...keys]);
+            for (const key of keys)
+                keyToGroup.set(key, created);
+            return;
+        }
+        const target = hits[0];
+        groupRows[target].push(index);
+        groupKeys[target].push(...keys);
+        for (const key of keys)
+            keyToGroup.set(key, target);
+        for (const absorbed of hits.slice(1)) {
+            groupRows[target].push(...groupRows[absorbed]);
+            for (const key of groupKeys[absorbed])
+                keyToGroup.set(key, target);
+            groupRows[absorbed] = [];
+            groupKeys[absorbed] = [];
+        }
+    });
+    /** The survivor of one group, by row index: a cached body first, then newest, then input order. */
+    const survivorIndexOf = (members) => {
+        let best = members[0];
+        for (const index of members.slice(1)) {
+            const member = rows[index];
+            const bestRow = rows[best];
+            const ready = fetchStates[member.entry.id]?.state === 'ready';
+            const bestReady = fetchStates[bestRow.entry.id]?.state === 'ready';
+            if (ready !== bestReady) {
+                if (ready)
+                    best = index;
+                continue;
+            }
+            if (timeOf(member) > timeOf(bestRow))
+                best = index;
+        }
+        return best;
+    };
+    const dupesBy = new Map();
+    const folded = new Set(); // row indexes hidden behind their survivor
+    let hiddenCount = 0;
+    for (const members of groupRows) {
+        if (members.length <= 1)
+            continue;
+        const survivor = survivorIndexOf(members);
+        dupesBy.set(rows[survivor].entry.id, members.filter(index => index !== survivor).map(index => rows[index]));
+        for (const index of members) {
+            if (index === survivor)
+                continue;
+            folded.add(index);
+            hiddenCount += 1;
+        }
+    }
+    const out = rows
+        .filter((_, index) => !folded.has(index))
+        .map(row => {
+        const hidden = dupesBy.get(row.entry.id);
+        if (hidden === undefined)
+            return row;
+        // Read state merges across the group: one read copy reads the card.
+        const mergedUnread = ![row, ...hidden].some(member => !member.unread);
+        return mergedUnread === row.unread ? row : { ...row, unread: mergedUnread };
+    });
+    return { rows: out, dupesBy, hiddenCount };
+}
+/** A short, stable, source-derived monogram tile (design decision D11). */
+export function tileForSource(label) {
+    const first = label.trim().slice(0, 1);
+    return first.length > 0 ? first.toUpperCase() : '·';
+}
+/** A stable hue derived from the source label, so a source keeps its colour. */
+export function hueForSource(label) {
+    const palette = [
+        'rgb(41,41,41)',
+        'rgb(84,85,87)',
+        'rgb(65,118,230)',
+        'rgb(217,119,87)',
+        'rgb(47,158,68)',
+        'rgb(151,157,166)',
+    ];
+    let hash = 0;
+    for (let index = 0; index < label.length; index++) {
+        hash = (hash * 31 + label.charCodeAt(index)) >>> 0;
+    }
+    return palette[hash % palette.length];
+}

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

@@ -0,0 +1,171 @@
+/**
+ * Where the reader was, kept for as long as the page is.
+ *
+ * The host unmounts the whole right sidebar when another main panel takes over
+ * (`RightbarRoot` renders only while `activePanelId === null`), and the pane's
+ * store is created per mount — so returning from the side chat used to lose the
+ * open article, the reading position, the wall's narrowing and the fact that a
+ * translation was on. This module is the fix: one snapshot in module memory.
+ *
+ * ONE bucket for the whole page, not one per dsh session. The pane is mounted
+ * per session, so keying this by `sessionId` meant "open the reader in another
+ * conversation" started from scratch — the same wall, the same article, the
+ * same translation, all to be set up again. The reader is one person reading one
+ * wall; the session id stays what it is genuinely for (the conversation draft,
+ * the side-chat context key), and nothing else here is session-bound.
+ *
+ * The PLACE is persisted, the CONTENT is not. `sessionStorage` carries the four
+ * fields that say where the reader was (the open entry, the view, the article
+ * anchors, the wall's offset), because "where I was reading" is not third-party
+ * content and the reader's report was exactly that a reload — or anything else
+ * that restarts the page — lost it. What stays out of every storage is the
+ * translated text and the translator sessions: those are a third party's words,
+ * and this package's rule is that they never leave the page. So after a reload
+ * the article and the position come back, and the globe does not (there is no
+ * session to restore it with, and rebuilding one needs a gesture).
+ *
+ * Everything else — the wall's narrowing, the read cursor, the wall's own
+ * translation switch and its card texts — is memory only: it is about this
+ * visit. Host state (cached bodies, sources, the 「最近阅读」 list) is read from
+ * the host, as always.
+ *
+ * @module @khorsheed/dsh-reader/client/session
+ */
+import type { ReaderFilter, ReaderSort, ReaderView } from './store.ts';
+import type { TranslationView, TranslatorSessionLike } from './translate.ts';
+/** One session's worth of "where the reader was". */
+export interface ReaderSessionSnapshot {
+    readonly view: ReaderView;
+    readonly openEntryId: string | null;
+    readonly openSourceId: string | null;
+    readonly filter: ReaderFilter;
+    readonly query: string;
+    readonly sort: ReaderSort;
+    readonly unreadOnly: boolean;
+    /** Whether the wall folds republished duplicates (default ON). */
+    readonly hideDupes: boolean;
+    readonly read: Record<string, true>;
+    /** Which surface was translated on the wall, and how it was shown. */
+    readonly wallOn: boolean;
+    readonly wallBoth: boolean;
+    /** Card translations already produced (small: title and summary per entry). */
+    readonly cardTranslations: Record<string, {
+        title?: string;
+        summary?: string;
+    }>;
+    /**
+     * Where the reader was inside each entry.
+     *
+     * An ANCHOR, not a pixel offset: the body's height is not final when it first
+     * renders (an article's images carry no dimensions, so they grow the document
+     * as they load), and a remembered pixel position then points at different
+     * content — which is how a reader ends up back at the top of a paper.
+     */
+    readonly scroll: Record<string, ReaderReadingAnchor>;
+    /** Where the WALL itself was scrolled to, in pixels. */
+    readonly wallScroll?: number;
+    /** The translation view a reader chose per entry (its presence means "globe was on"). */
+    readonly translationView: Record<string, TranslationView>;
+    /** The source language that view was built for, so the cached session is findable. */
+    readonly translationSource: Record<string, string>;
+}
+/**
+ * Where the reader was inside one entry.
+ *
+ * `block` + `offset` name a place in the DOCUMENT (the Nth top-level block, and
+ * how far into it the viewport top sat), so it survives everything above it
+ * changing height. `top` is the same place as a pixel offset: the fast path when
+ * the layout is already settled, and the only thing left when the body is not
+ * the one the anchor was taken from.
+ *
+ * `text` is the same place once more, as a CHARACTER offset into the block's
+ * text. A pixel offset into a block is only valid for the layout it was
+ * measured in: the translated view sets different words (Chinese runs shorter
+ * than English), so the same paragraph is a different height and `offset`
+ * points at the wrong sentence. `text` restores exactly (a Range rect) when the
+ * block still holds the same text, and as the same FRACTION of the text when it
+ * does not. `textLength` is how the restore tells those two apart. Both are
+ * optional: anchors written before them restore via the pixel offset, as
+ * before.
+ */
+export interface ReaderReadingAnchor {
+    readonly block: number;
+    readonly offset: number;
+    readonly top: number;
+    readonly text?: number;
+    readonly textLength?: number;
+}
+type Patch = Partial<ReaderSessionSnapshot>;
+/**
+ * What the page remembers, or `{}` when it remembers nothing yet.
+ *
+ * The persisted place sits UNDER the in-memory snapshot: within one page the
+ * memory is the truth (it has fields the place does not), and after a restart
+ * the place is all there is.
+ *
+ * @returns the snapshot (a copy of the recorded fields).
+ */
+export declare function readSession(): Patch;
+/**
+ * Record what changed.
+ *
+ * A field set to `undefined` is dropped rather than stored: "no record" and
+ * "recorded as nothing" would otherwise be two spellings of the same state.
+ *
+ * @param patch - the fields to replace.
+ */
+export declare function patchSession(patch: Patch): void;
+/** Drop the snapshot, here and in storage (the specs call this between cases). */
+export declare function forgetSession(): void;
+/**
+ * Remember where the reader was inside one entry.
+ *
+ * @param entryId - the entry whose body was on screen.
+ * @param anchor - the place in the document the viewport top sat at.
+ */
+export declare function rememberReadingPosition(entryId: string, anchor: ReaderReadingAnchor): void;
+/**
+ * Remember where the reader had scrolled the wall itself.
+ *
+ * The wall is the other long scroller in this pane, and losing its place is the
+ * same complaint as losing the place inside an article.
+ *
+ * @param top - the wall scroller's offset in pixels.
+ */
+export declare function rememberWallScroll(top: number): void;
+/**
+ * Remember that one entry is showing a translation, and in which view.
+ *
+ * @param entryId - the entry that was translated.
+ * @param view - the view that was on screen, or `'orig'` to forget it.
+ * @param source - the source language the translator was built for.
+ */
+export declare function rememberTranslation(entryId: string, view: TranslationView, source: string): void;
+/**
+ * Forget one entry's translation record (a re-fetch replaced its body).
+ *
+ * @param entryId - the entry whose body changed.
+ */
+export declare function forgetTranslation(entryId: string): void;
+/** The cache key for one language pair. */
+export declare function translationKey(sources: readonly string[], targets: readonly string[]): string;
+/**
+ * A built session for this pair, when one exists in this page.
+ *
+ * @param sources - source language candidates, in priority order.
+ * @param targets - target language candidates, in priority order.
+ * @returns the session, or `undefined`.
+ */
+export declare function cachedTranslator(sources: readonly string[], targets: readonly string[]): TranslatorSessionLike | undefined;
+/**
+ * Remember a session this page built.
+ *
+ * @param sources - source language candidates, in priority order.
+ * @param targets - target language candidates, in priority order.
+ * @param session - the built session.
+ */
+export declare function rememberTranslator(sources: readonly string[], targets: readonly string[], session: TranslatorSessionLike): void;
+/** Drop the translator sessions (the specs call this between cases). */
+export declare function forgetTranslators(): void;
+export {};
+//# sourceMappingURL=session.d.ts.map