@khorsheed/dsh-reader 0.2.0

package/lib/types/types.js

@@ -0,0 +1,182 @@
+/**
+ * Shared vocabulary of `@khorsheed/dsh-reader`: the persisted state document,
+ * the Remote wire payloads, and the pure helpers both faces share.
+ *
+ * Two responsibilities are deliberately split across the process boundary:
+ *
+ * - the HOST half owns the network (the sanctioned `ctx.web` fetch seam) and
+ *   the disk (one version-guarded JSON document over `ctx.fs`). It stores the
+ *   LAST RAW PAYLOAD per source — feed XML or article HTML — plus fetch
+ *   metadata, and never parses either.
+ * - the BROWSER half owns parsing. The host runtime has no XML/DOM parser at
+ *   all (Node's `globalThis.DOMParser` is absent), so the single parser lives
+ *   in the browser where `DOMParser` is native, and its output never needs to
+ *   be persisted: entries and extracted article bodies are session state.
+ *
+ * @module @khorsheed/dsh-reader/types
+ */
+/**
+ * Whether an automatic retry is worth the request.
+ *
+ * Only a transport failure is: a bot wall, a login wall, a PDF and a 404 all
+ * answer the same way forever, so retrying them on a timer would be a crawler
+ * with a grudge rather than a reader. The manual refresh stays available.
+ *
+ * @param code - the recorded failure.
+ * @returns true when the entry may be retried automatically.
+ */
+export function isRetryablePreviewFailure(code) {
+    return code === 'unreachable';
+}
+/** The default cache policy: a day, and a few hundred articles. */
+export const DEFAULT_CACHE_POLICY = { ttlHours: 24, maxEntries: 500 };
+/* ---------------------------------------------------- translation memory */
+/**
+ * The schema version of the persisted translation tiers (the global sentence
+ * memory's table, and each entry's segment map). A browser Translator model
+ * upgrade quietly changes what the same sentence translates to, and a
+ * segmentation change here changes what a "sentence" is — bumping this turns
+ * every old record into a MISS. Records are evicted LAZILY (the next write or
+ * budget pass drops them), never wiped eagerly.
+ */
+export const TRANSLATION_STORAGE_VERSION = 1;
+/**
+ * The default total budget for both translation tiers, in characters — 64 MB
+ * worth of text. Counted in characters, like every other budget in this
+ * document (a CJK sentence costs more bytes than that reads; the approximation
+ * is the store's existing convention).
+ */
+export const DEFAULT_TRANSLATION_BUDGET_CHARS = 64 * 1024 * 1024;
+/** How many sentences the global memory keeps before its own LRU end is evicted. */
+export const MAX_TRANSLATION_MEMORY_ENTRIES = 50_000;
+/* ------------------------------------------------------------------ helpers */
+/** Default state root segment under `$DSH_HOME/state`. */
+export const STATE_ROOT_SEGMENT = 'dsh-reader';
+/** Default daily refresh time. */
+export const DEFAULT_REFRESH_TIME = '10:00';
+/**
+ * Per-source raw-payload budget in characters.
+ *
+ * Sized to the HOST's egress cap rather than below it: a deployment can raise
+ * `web-fetch-http`'s `maxBodyChars` (the acceptance instance runs it at
+ * 2,000,000), and a per-source budget smaller than what the seam is willing to
+ * deliver would silently re-truncate every large feed here — the reader would
+ * pay for the fetch and still get half a document, with the note blaming the
+ * fetch. The fetch cap is the outer bound; this one must not be the inner one.
+ */
+export const MAX_BODY_CHARS_PER_SOURCE = 2 * 1024 * 1024;
+/** Total raw-payload budget in characters across all sources (newest kept). */
+export const MAX_TOTAL_BODY_CHARS = 12 * 1024 * 1024;
+/**
+ * How large an extracted body may be before it lives in its own file.
+ *
+ * `state.json` is read and rewritten as a whole on every mutation, so a research
+ * paper whose figures are inlined as base64 (transformer-circuits.pub's emotions
+ * paper is a 41.8 MB HTML document and extracts to tens of megabytes) would make
+ * every reader operation pay a multi-megabyte JSON round trip. Above this
+ * threshold the body is written to one file under `bodies/` and the document
+ * keeps only its metadata — so the cache policy (`ttlHours`, `maxEntries`) still
+ * governs it exactly like an inline body, and eviction deletes the file.
+ */
+export const INLINE_BODY_MAX_CHARS = 256 * 1024;
+/**
+ * Build a display label for a source from its URL: the registrable-ish host
+ * plus the last meaningful path segment, which is what distinguishes several
+ * feeds from one publisher.
+ *
+ * @param url - the source URL (any string; a malformed one degrades to its own head).
+ * @returns a short human label.
+ */
+export function defaultSourceLabel(url) {
+    try {
+        const parsed = new URL(url);
+        const host = parsed.hostname.replace(/^www\./, '');
+        const segments = parsed.pathname.split('/').filter(segment => segment.length > 0);
+        const last = segments.at(-1) ?? '';
+        // Drop a bare feed file name that repeats the host ("example.com/feed.xml"
+        // reads better as "example.com/feed"); keep the host alone when nothing
+        // useful is left.
+        const tail = last.replace(/\.(xml|rss|atom|json)$/i, '');
+        return tail.length > 0 ? `${host}/${tail}` : host;
+    }
+    catch {
+        return url.slice(0, 60);
+    }
+}
+/**
+ * Build a stable entry id. Feeds are inconsistent about identifiers, so the
+ * order is: explicit guid/id, then the entry link, then a hash over title and
+ * link together (a feed with neither must still deduplicate across refreshes).
+ *
+ * @param entry - the identifying fields an entry may carry.
+ * @returns an id stable across refreshes of the same feed content.
+ */
+export function stableEntryId(entry) {
+    const explicit = entry.guid?.trim();
+    if (explicit !== undefined && explicit.length > 0)
+        return `g:${explicit}`;
+    const link = entry.link?.trim();
+    if (link !== undefined && link.length > 0)
+        return `l:${link}`;
+    return `h:${hash32(`${entry.title}\u0000${entry.link ?? ''}`).toString(36)}`;
+}
+/**
+ * The entry id a saved link's single entry carries.
+ *
+ * A `link` source is exactly one entry, so the host must be able to name that
+ * entry when it records a per-entry annotation (the fetch failure the detail
+ * view reads). Both halves use this one function: a magic string duplicated
+ * across the process boundary is a bug waiting for a rename.
+ *
+ * @param sourceId - the link source's id.
+ * @returns the entry id the browser will build for it.
+ */
+export function linkEntryId(sourceId) {
+    return `link:${sourceId}`;
+}
+/**
+ * The query that selects every entry of one source KIND.
+ *
+ * The same local-predicate mechanism as a source or tag filter, so a kind
+ * narrowing is visible in the search box and can be cleared there. The prefix
+ * cannot collide with a real source id: ids are always `<kind>-<hash>`.
+ *
+ * @param kind - the source kind to select.
+ * @returns the query string.
+ */
+export function kindQuery(kind) {
+    return `#${kind}`;
+}
+/** The source kinds a kind query can name, for the predicate that reads one. */
+export const READER_SOURCE_KINDS = ['rss', 'link'];
+/**
+ * Shorten a summary for a card, collapsing whitespace so multi-line feed
+ * descriptions do not blow up the layout.
+ *
+ * @param text - the raw summary or content text.
+ * @param maxLength - the maximum returned length, ellipsis included.
+ * @returns the collapsed, shortened text, or `undefined` when there is none.
+ */
+export function summarize(text, maxLength = 280) {
+    if (text === undefined)
+        return undefined;
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    if (collapsed.length === 0)
+        return undefined;
+    if (collapsed.length <= maxLength)
+        return collapsed;
+    return `${collapsed.slice(0, maxLength - 1)}…`;
+}
+/** Coerce an unknown thrown value into a message string. */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** 32-bit FNV-1a hash, used only to build stable ids (never for security). */
+function hash32(input) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index++) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Reader",
+    "description": "Read RSS feeds and saved article links on a card wall."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "灵感空间",
+    "description": "订阅 RSS 源、保存文章链接，在灵感墙上阅读正文。"
+  }
+}

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@khorsheed/dsh-reader",
+  "description": "Link reader tab: RSS/Atom subscriptions plus pasted article links, a card feed with a readable detail view, host-side fetch and daily refresh over a Typert Remote data face",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "lib/typert.host.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.remote-client.d.ts",
+    "lib/typert.remote-client.js",
+    "cordis.patch.yml",
+    "locale/*.json"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-api-remotes": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-primitives": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-sidebar-right": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-invariants": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "reader",
+    "rss",
+    "atom",
+    "feed",
+    "readability",
+    "sidebar"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ],
+      "platform": "web"
+    },
+    "compat": {
+      "minHost": "0.1.5-rc.1",
+      "notes": "A page-type right-Sidebar tab (minted kind `reader`) over a Typert Remote data face. Fetching runs on the HOST through the sanctioned `ctx.web` seam; state is written with plain `node:fs` (atomic temp+rename) under `$DSH_HOME/state/dsh-reader`, NOT through `ctx.fs` — that service is the session-fenced sandboxed filesystem, so a workspace-write session refuses a write to the state root (observed on the acceptance instance). Every optional capability is probed at apply time and degrades (no `web` → domain refusals; no `sideChat` → the side-chat gesture hides; no `quote` → selection quoting is unavailable while the entry-level quote button still works). KNOWN LIMIT: the host fetch seam caps a decoded body at 100,000 chars and truncates silently, so articles larger than that cannot be extracted — the detail view falls back to a 「受限篇幅，内容未完整呈现」 notice with a 「阅读原文」 button (measured: Anthropic research pages, theverge.com, newyorker.com). On-device translation (0.2.0) runs the page's own Translator API (Chrome 138+/Edge 148+, desktop): the model never leaves the device and no model quota is spent, while the derived sentence pairs persist on the host (a global memory file plus per-entry segment maps under the state root, one shared budget, no TTL) so a reload re-paints instead of re-translating. Where that API is absent or the pair is unavailable, the globe is simply not rendered — the pane keeps working exactly as before. Source bodies that are already Chinese are not offered translation at all. On host 0.1.6-alpha.2+ the spots that want a real browser (the script-figure notice, a bot-wall card's action) open the in-app Sidebar Browser tab, probed through the `browser` tab kind; on older hosts they are the ordinary external link. Pages that inline real figures as base64 data URIs are now kept whole (substantive payloads over a 512-char threshold; 1px placeholders still yield to lazy-loading attributes), so a figure-heavy paper on a cap-raised deployment becomes a multi-MB cached body by design — bodies are bounded by entry count + TTL, not by a char budget.",
+      "verifiedHost": "0.1.5-rc.1"
+    },
+    "references": [
+      "@khorsheed/dsh-quote",
+      "@khorsheed/dsh-sidechat"
+    ]
+  }
+}