@khorsheed/dsh-reader 0.2.0

package/README.en.md

@@ -0,0 +1,90 @@
+# @khorsheed/dsh-reader
+
+The **inspiration space**: one **page-type tab** in the right sidebar that gathers RSS/Atom subscriptions and pasted article links onto a single wall. Clicking a card reads the body inside dsh (selectable, so it can be quoted); when the host's fetch cap truncated the body, the page says so in one line and offers a button to the original.
+
+> The package name, tab kind and Remote namespace stay `reader` — they are stable identifiers (renaming them would change a deployed loader row and the on-disk state root). "Inspiration" is the name the reader SEES.
+
+Fetching happens on the **host half** through the sanctioned `ctx.web` egress seam; the browser half only parses and renders. The subscription list and the most recent raw payloads are persisted to `$DSH_HOME/state/dsh-reader/state.json` with atomic `node:fs` writes — **not** through `ctx.fs`, which is the policy-fenced sandboxed filesystem (see Compatibility) — and a daily refresh is armed by a plugin-owned `setTimeout`, since no host scheduler service exists to ride.
+
+## The three surfaces
+
+| Surface | Contents |
+| --- | --- |
+| The wall | **Content first**: the entry cards own the first screen. **The search field owns its own full-width row**, and the filter, sort and wall-translation controls moved up into the pane's header (with refresh, settings and add) — a field wedged between three buttons is a field the reader cannot see what they typed in on a narrow sidebar; every popover hangs under **the button that opened it** and cannot cover the other one. The filter is a **two-page popover** narrowing the wall four ways — read state (unread), by source, by KIND (a feed or a saved link) and by tag: the root page holds the two read-state rows (unread, and **Hide duplicates**), a by-source drill row that carries the **current value** (so no narrowing is ever hidden) and the three kind rows. **Dedupe is on by default**: an article republished by several feeds folds into one card (three grouping tiers, any hit folds: same entry id — a shared guid shares fetch/read/translation state by design; normalized link — scheme/www/utm-style tracking parameters stripped; folded title plus the same published day; never fuzzy), the surviving card carries a 「N 个重复来源」 badge (hover names the other sources), reading any copy reads the group, the footer notes how many folded, and the backfill never spends a fetch on a hidden copy, and drilling in opens the source page, which owns the panel's height, its own scroll and — past six sources — its own search box, so **however many subscriptions accumulate, the panel's first page stays a fixed handful of rows**. It is the same local predicate as the search box (D14), so filtering costs no round trip, and its value is visible in the search box (`#sourceId` / `#rss` / `#link` / `@tagId`), which is also how it is cleared — and **a field with text in it grows an × at its right edge**, one click away from clearing both the typed term and the filter value. A **text** search is ranked by relevance — exact title, then title contains, then the other fields, with the chosen sort deciding inside each tier (`#sourceId` / `@tagId` selectors are not ranked) — and the footer says how many entries matched (`N matching “X”`), so a narrowed wall can never be mistaken for the whole wall. **The wall translates too**: the globe at the right of the toolbar (its own switch, separate from the detail view's, sharing one translation memory). It decides **per FIELD**: a Chinese title or summary is left exactly as it is, a mixed card has only its English half translated, and Chinese is never translated into Chinese. Only cards that have **entered the viewport** are queued (IntersectionObserver feeds a queue, six cards per pass, grouped by detected language, through the article's own sentinel-batch contract), so scrolling back costs nothing and opening an entry does not re-translate its title. Two views: translation only (**hovering the translated TEXT** swaps just that FIELD back to its original — the title for the title, the summary for the summary; the card's blank space, tile and chevron change nothing) and side by side (each field's original stays under its translation and keeps that FIELD's own typography — a title's original is title-sized, told apart by ink and weight rather than shrunk to caption size). **The text boxes are fixed** — title and summary each reserve two clamped lines — so swapping languages on hover cannot resize a card or shift the grid; only the side-by-side view makes the grid taller, and that is a mode the reader picks. Entry cards are **cards** — a fill, a hairline border, a 12px radius — where hover only lifts the tone (never the geometry) and a keyboard focus draws a ring; unread entries ink their title and keep the **dot** (7px) on the tile's corner — session-only, never persisted — while read entries stay put and go quieter; the feed's own category and the reader's own tag share one pill metric (the reader's tag is outlined, and the row wraps), and tagging opens from the card's `+` into a panel where you tick the vocabulary or **type a name and press Enter to create it** (the native `datalist` is gone, replaced by stylable rows). **Tags are deletable from the filter popover's `By tag` section** (a quiet × at the end of each row removes it from the vocabulary and from every entry, and clears the narrowing when it was the active one) — a vocabulary you can only add to is a one-way door. A freshness line sits at the bottom — "Refreshed 3 h ago · daily 10:00" — so a reader can tell whether the snapshot is worth re-fetching |
+| Detail | Where a card leads. The body renders as DOM text — **that is exactly what makes passage quoting work**, and why this surface never hosts an iframe. The body has **no reading measure**: it fills the width the sidebar is given, and paragraphs and lists share one right edge. Toolbar: back, **translate (globe + view menu)**, copy link, open the original in the browser, and — for a single saved link — **a delete button** (a feed entry gets none: the next refresh would bring it back, and a delete that undoes itself is a lie); the **tag row under the title also carries 「重新抓取」** (the same host action as the card's pill, and asking for a fresh copy drops that entry's translation record — the body is about to be a different DOM). Below the body, the other entries "also from this source". **A figure the page draws with its own scripts cannot be fetched**: such a `<figure>` carries nothing but an empty div and a caption in the served HTML (measured: 84 of them on the transformer-circuits.pub paper), and a fetch runs no scripts — so **the caption stays in the body** (it is text the page published, and it says what the picture shows) while one line above the body says 「这一页有 N 张插图由页面自己的脚本绘制，抓取时拿不到画面（图注保留在正文里）」 with the original-page link (opened in the in-app Sidebar Browser when the host has one; and when a future capture package is mounted, a 「渲染抓取」 action appears here — unprobed, it does not render). **And a capture-rendered page keeps its figures**: script-drawn figures arrive as inline SVG with inlined styles and survive through a safe subset (shapes/text/defs/gradients/clips/symbol reuse; `script`/`foreignObject`/SMIL/events/external references never do, and `url(` may only point at a same-document fragment) — instead of leaving only a caption. **Composite figures keep their structure too**: a capture-rendered composite (a diagram plus property cards built from styled boxes) keeps its div/span containers inside the figure with an allowlisted style set (layout/paint properties; `position:fixed`, over-bound `z-index`, external `url()`s and script tricks all stripped), and every unwrapped block container leaves a word boundary — sibling texts can never concatenate. **A picture whose URL IS in the static markup is recovered, though**: lazy-loading sites keep the real URL in a `data-src`-style attribute, a `srcset`, a `<picture>`'s `<source>`, or the `<noscript>` no-JS fallback (the `src` holds a 1px placeholder), and the extractor resolves the candidates in that order, taking the largest srcset one; **the converse shape is kept too — pages that inline their real figures as base64 data URIs (transformer-circuits.pub style)**: placeholder and picture are split by payload size (a 512-char threshold; a 1px gif is ~70, a real chart runs to the thousands), the small one still counts as absent and yields to the lazy attributes, the large one is kept as-is; every emitted `<img>` carries `referrerpolicy="no-referrer"`, because anti-hotlink CDNs answer 403 otherwise. **Formulas render as native MathML**: an arXiv HTML paper's `<math alttext="…">` passes through a safe presentation subset (`annotation-xml` and any script never do — the former is an HTML-injection vector), and display math scrolls sideways instead of breaking the layout. **LaTeXML's vector figures are kept too**: arXiv HTML embeds them as `<object type="image/svg+xml" data="…">`, which the normalizer rewrites as an `<img>` carrying the original width/height; a non-image object (a PDF, a movie) is still dropped whole|
+| Translation (on-device) | The toolbar's **globe** is a switch: lit means this body is showing a translation. Its caret holds three views — **translation only** (the default; a one-time line above the body teaches "click any sentence to see its original, click again to hide it"), **side by side** (every paragraph carries its original underneath, foldable per paragraph), and **original only**. The unit is a SENTENCE: clicking one sentence reveals that ONE sentence's original under its paragraph (hairline plus a highlight), and several can be open at once; when the sentence contains an inline link and was cut into several text runs, the reveal still shows the COMPLETE sentence rather than the fragments, the original line itself is NOT a control (it is text meant to be selected for quoting — clicking it does nothing, and a click that ends a selection is ignored, so quoting never folds the sentence away). The English original is set at BODY size (13.5px, the secondary ink, 1.62 leading, 3px between lines) and is spaced by WHERE its container sits: beside a paragraph it hugs that paragraph (4px above, 14px before the next block), while inside a list item, quote or table cell it sits 5px under the translation instead of being pulled up into it by a negative margin. An EXPANDED sentence keeps one quiet marker — a hairline underline, with no standing fill or bar (that is the "this sentence is bound to the line below" cue). The pairing highlight itself is HOVER-ONLY: pointing at a Chinese sentence lights that sentence (including the fragments a link split it into) together with its one original line, and pointing at the original line does the reverse. Nothing carries a standing colour or bar by default — the earlier always-on marks turned a skimmed article into confetti. All of it runs **in the browser** (the `Translator` API in Chrome 138+ / Edge 148+, desktop): the model never leaves the device and spends no tokens, but **the derived sentence pairs do persist** (below), while the globe record and translator sessions never do. Without that API, with an unavailable pair, or on a body that is already Chinese, the globe is **not rendered at all**. **The translations persist in two tiers** (under `$DSH_HOME/state/dsh-reader`, the same directory, sensitivity class and uninstall story as the cached originals): a global **sentence memory** (`<src>→<tgt>:<sentenceHash>` → source + translation, 50k entries) and a **per-entry segment map** (hash → translation, keyed to the body's hash, so a minor refetch still reuses every unchanged sentence). One shared budget — 64 MB by default, tunable through the same cache-policy verb as the body retention — evicts least-recently-used across both tiers, with **no TTL** (a translation costs a gesture plus per-sentence model work to rebuild, so it must not expire by the clock). The net effect: after a reload the globe still waits for its gesture, and after it the whole article re-paints from disk with the model untouched; both tiers carry a schema version that reads as a miss and evicts lazily, so a browser-model upgrade never passes old translations off as the new model's |
+| Add (dialog) | The header's plus, the empty-state card and the dashed card at the end of the wall all open the same **dialog** (the members tab's invite-dialog idiom: transparent overlay plus centered card, Esc and overlay-click close), because adding is a momentary act and the wall should not be replaced by it. **What comes back decides how it is stored** (D15): a feed becomes a subscription, a web page is saved as a single item. **An arXiv abs/pdf link is upgraded to the paper's official HTML version** (`arxiv.org/html/<id>` — LaTeXML-built semantic markup: real tables, real formulas); when the HTML version does not exist (404) the pasted address falls back to the ordinary path. **A DOI link is resolved to its arXiv version first** (Crossref for the title and authors → an arXiv title search → a two-factor gate of title similarity plus author family-name overlap; no match means the ordinary path, never a guess), and a landed card marks the DOI it came from; **an OpenReview link is saved link-only without a fetch** (measured unreadable server-side: the API sits behind a Cloudflare challenge, the forum is a JS SPA), with the reason and the suggestion on the card (paste the arXiv version if one exists). **A URL that cannot be read is still saved**: the verdict changed from "succeeded / failed" to "saved, plus whether it can be previewed", the reason is classified (bot wall / login wall / not a web page / cross-site hop / unreachable / HTTP error) and the card is marked 「仅链接」 — dropping the URL the reader pasted is worse than a card that can only be opened in a browser. **A saved link’s card upgrades to the article’s own title once the body parses** (the body’s first h1, else the document title, plus the first substantial paragraph as the excerpt) and keeps it in the host annotation — the card still reads that memory after the body’s budget eviction, so a wall of papers is scannable without opening each one |
+| Subscriptions (page) | The header's settings button opens the **subscription page**: one **compressed settings row** at the top (daily refresh time and article retention side by side, their long explanations moved into hover titles), a **storage row** (the article cache's readout — "N cached · size", the translation cache's readout — "M maps + S sentences · size" — the **translation budget** input in MB, committed on blur/Enter, and a two-step **clear translation cache** button; the readouts are aggregated on the host, the tables never cross the wire) plus two labelled **chip groups** — `By type` (all / feeds / saved links, each with its count) and `Sort` (added / name / last fetch, added-time descending by default) — then one row per source where **both the name and the feed address are editable in place** (a changed address is a different document, so it refetches on save; clearing the name falls back to the feed's own title), plus its kind, item count, last fetch, failure reason (classified, not the seam's raw sentence), per-source refresh, pause/resume, remove, and the **daily refresh time setting**. Those questions are about SOURCES rather than about content, so they do not live on the wall |
+| Recently read (page) | The header's **clock** opens the **recently read page**: the entries you opened, **newest first** (title, source, "how long ago"), where clicking one **reads it again**; a bin in the page bar **clears the whole list**. It records "what was I just reading", so it is **persisted** (`state.json`'s `recent`, **at most 100 rows**; reopening an entry moves it back to the top instead of duplicating it) and survives a reload and a restart — unlike the pane's own memory (the open article, the reading position, the translation), which is shared **across dsh sessions but not across a reload** (it is per page — see above); `recent` is deployment-level and outlives a restart. **A row stores only the entry id, source id, title, URL and time** — never the body — so the page can still reopen an entry that has **rolled out of its feed's window** (as long as the source is still there). An entry whose source was deleted is still listed but cannot be opened, and says so |
+
+**The 「抓取」 pill on every card**: **grey = not fetched (click to fetch) / blue = fetching, or fetched and waiting to be extracted / green = the full text is cached (open it and read) / red = failed**. The failed state **acts per cause**: clicking the red pill opens a small popover — the reason, plus the action that cause answers (a transport failure gets 「重新抓取」; a bot wall, a login wall, a non-web file and a known-unreadable page get **open in a real browser** — the in-app Sidebar Browser when the host has one, else the external browser; an HTTP error, an empty page and a cross-site hop are final, so the popover holds the reason and no action) — while the card itself stays one line tall and never breaks the grid. Once you press it you can **leave the page immediately** — switch panels, close the tab, even reload: the fetch runs on the HOST, the raw page is written to `bodies/` first, and the next time the inspiration space opens, the browser half extracts it and caches the body. So you can queue what you plan to read from the wall instead of waiting in the detail view. **Opening an entry whose body is still missing fetches it automatically** — the same action the pill performs; **an entry that has already been fetched is not fetched again** (the text on screen IS the cached body, and re-fetching it would only replace the DOM — taking the reader's translation with it). **An entry whose feed publishes full text is kept on its first open** — the feed's own text becomes the cached body (no request at all; the text is already on screen), the pill turns green on the same gesture, and the body survives the entry rolling out of the feed's window. To ask for a fresh copy, use **「重新抓取」 in the detail view's tag row** (the same host path; it also drops that entry's translation record — see below).
+
+**Leave and come back — and carry on in another conversation**: when another main panel takes over, the host **unmounts** the whole right sidebar (`RightbarRoot` renders only while no other panel is active — it is not hidden), and this pane's store is created per mount. Hopping to the side chat and back used to lose the open article, the reading position, the wall's search/sort/filter and **the translation the reader had already paid for**. No flash of the wall while that happens: the pane knows from its first frame which entry it should be showing, and shows the detail surface with a loading line instead. All of that is now remembered by the **whole page** and restored: **across dsh sessions** — opening the reader in another conversation finds the same article, the same reading position, the same narrowing and the same translation — including **the wall's own translation switch and the card texts it already produced** (the pane is mounted per session; this memory is per page) — and the same-session round trip through the side chat works as it did. The article is reopened (its body answered from the host's cache, so no request), the reading position returns (both scrollers — the wall and the article — and the article's place is remembered by CONTENT, "the Nth block, this far into it, at **this character of its text**", not as a pixel count, because an article's own images carry no dimensions and grow the document as they load; a body replaced or re-fetched under the reader puts them back again, **and an original↔translation switch — which rewrites every block's height — re-anchors to the same sentence through the character offset**) the wall's narrowing stands, and **the translation turns the globe back on by itself whenever this page already built a translator session** (`Translator.create()` needs user activation, so only a session that already exists can restore — with none, nothing is automatic, the record stays, and the next click on the globe still costs nothing). **A translation follows its body**: when the body is replaced under the reader (a re-fetch landing, an expired cache re-read, the element rebuilt), the translation is re-applied to the NEW body as long as this entry's globe is on — from the page's sentence memory, so usually without a request. **The PLACE survives a reload**: the open entry, the article anchors and the wall's offset are written to `sessionStorage`, so a page that restarts still finds the reader where they were. **The globe record and the translator sessions are never written anywhere**, so the globe comes back off after a reload (there is no session to restore it with, and building one needs a gesture) — but **the translated sentence pairs are persisted**, so one click re-paints the whole article from the host's two tiers without a single model request. Closing the tab clears the sessionStorage part (`sessionStorage` is per tab); the translations on the host age out under the budget, or go with the directory on uninstall.
+
+**Click semantics (settled as option B)**: a card click opens the detail view. Most reading happens in dsh; when the body is too long or the reader wants the original, the detail view's own button goes to the browser. The trailing chevron is a cue that the card leads somewhere, not a control.
+
+## Quoting
+
+The body is an app-level selection, so `@khorsheed/dsh-quote`'s overlay menu **already covers it** — this package builds no selection menu of its own. The detail view also carries:
+
+- **Quote**: the selection (the whole entry when there is none) plus a source label, merged into the current conversation draft through the official input machine (the live draft is read and merged, never overwritten, never sent);
+- **Sent to side chat**: shown only when the composition really has a `sideChat` service (the capability handshake decides), hidden otherwise.
+
+`reader` ships its own thin typert Remote (namespace `reader`) with the verbs `capabilities` / `listSources` / `addSource` / `updateSource` / `removeSource` / `refresh` / `getBodies` / `quoteToSideChat`. The host half **never parses** a feed — parsing lives in the browser half, and `getBodies` only hands the raw payload across.
+
+## Install
+
+```sh
+dsh plugin --profile web add @khorsheed/dsh-reader
+# uninstall:
+dsh plugin --profile web remove @khorsheed/dsh-reader
+```
+
+Restart the host afterwards. Exactly one directory is written: `$DSH_HOME/state/dsh-reader/` — `state.json` (the subscription list, the latest payloads, the reader's own tags and the 「最近阅读」 records) and `bodies/` (one file per body over 256 KiB; the global translation memory is its `translation-memory.json`, and a large per-entry segment map gets its own file). Uninstalling leaves the directory behind — delete the whole `dsh-reader/` for a clean removal.
+
+## Compatibility
+
+- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): ✅ complete — the `sidebar.right.pane.tab` seat, the `ctx.web.fetch` egress seam, version-guarded `ctx.fs` writes; no `pluginInventory` needed (this package does no preset self-hide).
+- Source line (deepseek-harness master): ✅ (verifiedHost: 0.1.5-rc.1)
+- **Why state does not go through `ctx.fs`**: `ctx.fs` is this repo's **sandboxed** filesystem — every mutation is fenced by the FILE POLICY OF THE CALLING SESSION, so a workspace-write session is refused a write under `$DSH_HOME/state` (`FS_SANDBOX_DENIED`, observed on the acceptance instance). The fence is right and stays; the mistake was aiming a session-scoped capability at deployment-owned state. This package therefore writes with `node:fs` (atomic temp-file plus rename), the way this repo's other host-state packages do (`packages/lab/src/state.ts`), and degrades to memory-only when the root is unwritable.
+- **Sources are named by the feed's own title**: the host half cannot parse a feed (it has no XML parser), so a new source starts with a URL-derived label — the `raw.githubusercontent.com/...` you see in the strip. Once the browser half has parsed `<channel><title>`, that real title replaces the display label, so cards read "Anthropic Research"; it falls back to the URL when parsing fails. The `{count} d ago` placeholder the list showed for an errored source was the other face of the same class of bug (an uninterpolated parameter) and is fixed.
+- **Translation uses the browser's own on-device model, not the host's**: `self.Translator` (Chrome 138+ / Edge 148+, desktop only) translates inside the page's own process, so **the model never leaves the device, spends no tokens and needs no network** (the first use downloads a small language pack per pair, and `Translator.create()` requires user activation — the click on the globe is exactly that). **The derived sentence pairs are written to the host side** (the global sentence memory and the per-entry maps under `$DSH_HOME/state/dsh-reader`, a shared 64 MB budget, LRU, no TTL; derived content of pages the reader read, the same sensitivity class as the cached originals beside them — the privacy invariant was always about the network, not the disk). The price is availability: Safari, Firefox and mobile have no such API, and the plugin then hides the globe while everything else keeps working. That trade is deliberate: sending one 50,000-character article through a host LLM costs tens of thousands of tokens, tens of seconds, and a second copy of the article to the model provider, while on-device translation is free, seconds and stays on the machine (its quality is page-translation-grade NMT, not LLM-grade).
+- **The translation unit is a sentence — not a paragraph, not a text node**: sentences are cut BEFORE the request, so the pairing is true by construction rather than guessed afterwards — a paragraph-level translation comes back as one block, the model merges and splits sentences, and re-aligning the two sides afterwards can show the wrong original. Batches separate sentences with a sentinel and, when the returned part count does not match, that batch is re-sent one unit per request: **granularity is what the fallback gives up, never correctness**. A sentence that crosses an inline element (a link inside it) becomes two units and the link itself is never touched; nothing inside `<pre>`/`<code>` is translated.
+- **A translator that cannot be built is reported, never faked**: `Translator.availability()` is a HINT, not a promise — on Chrome a pair has been observed answering "available" and then rejecting `create()` with `NotSupportedError` ("Unable to create translator for the given source and target language"; Chromium has the same failure recorded for macOS builds). So the plugin (1) asks the browser's `LanguageDetector` for the source language first — a wrong source is one way a pair cannot be built, and that error names NEITHER language; (2) actually tries the target in both accepted spellings, `zh` then `zh-Hans`; and (3) when every attempt is rejected as unsupported, HIDES the globe and says which pairs it tried while pointing at `chrome://on-device-internals` ("Broker State"). Non-permanent failures (download, quota) keep the globe so the reader can retry, and report the attempted pairs plus the reason.
+- **Restoring the body is byte-exact**: translation only rewrites text nodes (the originals stay in memory), so "original only" and cancel put back exactly the HTML the host sent. That is also why a translation cannot lose links, images or tables — they are never touched.
+- **Some sites refuse automatic fetches, and the button says so honestly**: measured, `openai.com` answers **403 to every non-browser request** (with a proxy, without one, and with a browser User-Agent — it returns a bot-challenge page). That is not an extraction failure and no retry fixes it, so for a 401/403 the detail view says "this publisher refuses automatic fetches" instead of "could not extract". **The status code is not the only signal**: an `openreview.net` PDF link was measured answering `302 → /challenge?redirect=…` and then a **200** challenge page — trusting the status code stores that page as the article, which is exactly how "I added it and there is no content" happened. So the decision is a combination: whether the final URL moved, whether the visible text is too short to be a page, and the words a bot or login page leaves behind; any hit means the payload is NOT stored as a body and the link is saved as 「仅链接」. Newsletter platforms and paywalls behave the same way. It is also why browser-rendered fetching is out of scope here: that needs the browser pane, which is still `planned`.
+- **Some feeds publish full text for some posts and only a summary for others**: measured on the OpenAI alignment feed, whose 27 entries run from **155 characters** (a one-line summary) to **62,044** (full text). Nothing is truncated; that is how it is published. **A summary is no longer mistaken for the article**: the feed's `<description>` used to be promoted into `contentHtml`, so the entry looked complete — the backfill skipped it, opening it fetched nothing, and the detail view rendered those 167 characters as the whole paper. Such entries are now flagged `summaryOnly`: opening one fetches the real article on the spot (the detail view says 「这条订阅源只发布了摘要 —— 全文在原文页面上」 while it does, with the original-page link, and the line disappears when the text arrives) and the automatic backfill counts them as text it still owes. **That fetch now happens only while the entry has no cached body**: `summaryOnly` is a property of the FEED entry and is true forever, so this used to re-fetch an already-fetched article on EVERY open — replacing its DOM, and its translation, with the same bytes. The fetch is now gated on the text on screen being the feed's own (`fromFeed`).
+- **The host hands over at most 100,000 characters per payload, so an oversized feed can only be read in part**: this is the egress seam's default (`web-fetch-http`'s `maxBodyChars`), NOT this package's body budget (256 KB per source, 2 MiB total). The acceptance instance's feed is 646,905 characters; the host supplies the first 100,000, so only the two entries falling inside that prefix are readable. The plugin **cannot** work around it: `ctx.web.fetch` accepts `{ url }` only — no Range, no custom headers, no pagination — and vendoring `fetch` to bypass it would bypass the host's egress policy, which is not an option. Reading such a feed whole needs **no host code change**: the official patch overlay adds config to that row (`--patch <file>`, or the machine-level `$DSH_HOME/cordis.patch.yml` which applies to every profile):
+
+```yaml
+- id: web-fetch-http
+  config:
+    maxBodyChars: 2000000   # default 100000
+```
+
+Verified with `dsh --profile web --patch <file> --dump-config` (the composed tree carries the value), and then applied on the acceptance instance: the same feed went from "100,000 characters, truncated, 2 entries" to "**646,905 characters, untruncated, 21 complete entries**". **Raised again on 2026-09-19**: research articles are large in their own right — the transformer-circuits.pub emotions paper is a **41.8 MB** HTML document (60 of its figures are inline base64), and the seam's BYTE cap (`maxResponseBytes`) defaults to 5 MB, so the whole fetch fails (`response exceeds the maximum of 5000000 bytes`) with `maxBodyChars` waiting behind it. The acceptance instance's deployment config now raises **both** to 64 MB and the fetch **timeout from its 30 s default to 180 s** (that page takes 19.5 s on a direct connection, so a busy machine used to fail it with `web fetch timed out`; same patch row, `$DSH_HOME/profiles/web/cordis.patch.yml`). The price is machine-wide: peak memory and transfer per fetch go up with it. Note that this package's OWN per-source budget must not sit below the host's cap, or storing the payload re-cuts it — it is 2 MiB per source, 12 MiB total. The boundary that remains is ownership — a plugin patch mounts its OWN row only (the repo forbids one package mounting or editing another's row), so this override is a **deployment configuration** decision, and it raises the cap for **every web fetch on the machine**.
+- **Full text is filled in automatically — there is no button to press**: after each load the host reports which entries still lack text (at most 8 per run; a failed entry is left alone for 6 hours), and the browser half fetches + extracts them into a 24-hour cache (configurable on the subscription page), **two requests at a time**. An entry being filled keeps showing the feed's own text, the footer reports "Filling in 3/8…", and a completed card carries a "Full text" badge (meaning: the card still shows the feed's own summary, and the full text is cached — open it to read). **Do not want to wait for the slice? Open that entry**: if no body is held locally, opening it fetches once right there and says 「正在抓取正文…」 instead of waiting for the backfill's turn.
+  - Why not fetch them all at once: that would crawl every article of every subscription. This takes a slice per refresh and moves forward.
+  - **What arrives is what is shown**: a publisher refusing us (401/403), an unreachable host, and an unreadable page are three different sentences, and the body area always shows the feed's own content plus "read the original" — never a blank page.
+- **A feed the host truncates is salvaged, not discarded**: the egress seam caps a payload by CHARACTER COUNT, and a cap that lands inside a tag makes the whole document malformed — which used to mean **no entries at all**. The parser now keeps every complete `<item>`/`<entry>` (re-wrapping each fragment with the document root's namespace declarations, without which a fragment carrying `content:encoded` is itself malformed), repairs the cut-off block best-effort and flags it **partial** so its arrived text still renders, and the wall shows an "incomplete" line with the original-page link. The shape is pinned by a committed fixture (`tests/fixtures/feed-truncated.xml`).
+  Measured: the acceptance instance's 646 KB feed (of which the host hands over 100,000 characters) now yields **2 cards** — one complete 42 KB body and one partial — where before this fix it yielded **0**.
+- **The default filter is "all", not "today"**: a feed's newest entry is often not from today (the acceptance instance's feed was 8 days old), and a default `today` filter made a freshly subscribed wall look empty — which reads as "the subscribe did not work". There is **no today filter at all** now: the four ways to narrow the wall (unread / by source / by kind / by tag) live in the filter popover, and the button's own pressed state plus the `#sourceId` / `#rss` / `#link` / `@tagId` query it writes into the search box keep "what is hidden" visible.
+- **A body over 256 KiB is stored as its own file**: `state.json` keeps only its metadata (file name and character count) and the markup itself lives in `$DSH_HOME/state/dsh-reader/bodies/<hash>.html`. The article-retention setting (12/24/168 hours or forever) governs both kinds identically, and eviction deletes the file with the metadata. The reason is that `state.json` is read and rewritten as a whole: a paper whose figures are inlined as base64 extracts to tens of megabytes, and inlining those would make every reader operation pay a multi-megabyte round trip.
+- **A repeated title at the top of the body is dropped**: the detail view already renders the entry title, and the article's own HTML often carries it again (measured: TWO `<h1>`s, preceded by the site name and a logo link). Extraction removes top-level headings that repeat the document title, plus the leading masthead and blank lines, so the body starts at real content ("Authors").
+- **The body has no reading measure**: paragraphs and lists fill the width the sidebar is given — no `max-width` (the earlier paragraph-only cap left a ragged band of empty space on the right that read as a broken layout). Want a shorter line? Narrow the sidebar.
+- **The host fetch cap is a known limit**: `ctx.web.fetch` truncates a decoded body at 100,000 characters and does so **silently**. Articles past that cannot be fully extracted (measured: an Anthropic research page ~266k, theverge.com ~899k, newyorker.com ~1.97M characters); a summary page's title, author and description still arrive. The detail view therefore shows 「受限篇幅，内容未完整呈现」 with a 「阅读原文」 button. RSS feeds are mostly safe (measured: HN 11KB, BBC 25KB, 阮一峰 69KB, Simon Willison 83KB — 83KB already sits against the cap).
+- **Degrade matrix**: no `fs` → state is memory-only and lost on restart (the handshake reports `hasFs: false` rather than pretending persistence exists); no `web` → a pasted link is still saved, marked 「仅链接 (unreachable)」 with 「阅读原文」, and no exception is thrown and no URL is lost; no `sideChat` → the side-chat action is hidden; no `quote` → the selection overlay is simply absent, while the entry-level Quote button keeps working. A host below 0.1.6-alpha.2 (no `browser` right-Sidebar tab kind) → the spots that want a real browser (the script-figure notice, the bot-wall card action) offer the ordinary external link instead, without an error.
+- **A cross-origin redirect is followed only when it can be reconstructed**: the host seam refuses one (`WEB_REDIRECT_BLOCKED`) and reports the target **origin only — never the path**. So this service re-enters the seam only for a same-HOST scheme/port change (`http://host/feed` → `https://host/feed`, path and query preserved) and otherwise reports that the address moves to another site instead of following it — fetching the bare origin would return a different page and file it under the reader's URL. The earlier text here claimed "up to 3 hops"; that follow path was dead code, because it looked for the text `WEB_REDIRECT_BLOCKED` in an error MESSAGE that never contains it (the host puts it in `error.code`), so every cross-origin redirect surfaced as the seam's raw sentence. It now reads the code, with a regression test.
+- **Refusals become 「仅链接」 cards**: a fetched page with almost no readable text (under 200 visible characters after script/style are stripped) that also carries bot-wall or login-wall markers is never stored as an article — **a challenge page never becomes a card's body** — and `application/pdf` and friends are refused outright by the egress seam (`WEB_UNSUPPORTED_CONTENT_TYPE`: only html/text/json/xml). Those cards stay on the wall, take tags, copy their link and can be deleted; opening one shows the reason and 「阅读原文」.
+- **A permanent refusal is not retried automatically**: bot walls, login walls, PDFs, HTTP errors and empty pages are recorded as non-retryable (`isRetryablePreviewFailure` lets only `unreachable` through), so the automatic backfill stops knocking; the subscription page's per-source Refresh still retries by hand and clears the record on success. That is what keeps the plugin from tapping a site that will always say no every six hours.
+- **No conditional requests**: the host seam exposes no custom-request-header entry point, so there is no ETag/If-None-Match and every refresh is a full fetch.
+- **Nothing behind a login wall**: there is no credential-injection surface.
+
+## Known Limitations
+
+- **Subscribe, do not crawl**: adding a subscription fetches the feed itself and never pre-fetches every entry's body (that would blow up storage and amount to running a crawler). Opening one entry pays for one fetch.
+- **A PDF (or any non-web file) has no body**: the egress seam accepts only `text/html`, `text/*`, `application/json` and `application/xml`, so `application/pdf` is refused before extraction even starts — and extraction is DOM-based, which a PDF does not have. Such a link is a 「仅链接」 card plus 「阅读原文」; this plugin is not a PDF reader.
+- **A cross-site hop is not followed**: the seam reports the target origin only, so the path cannot be reconstructed. Shorteners and institutional proxies are therefore reported as "this address moves to another site" rather than guessed at.
+- **Read state and bodies are not persisted**: they are session state. Persisting a per-entry read cursor would need a second, write-heavy document, and "what is new since I last looked" is the whole value of this plugin.
+- **XML parsing lives in the browser**: the host has no XML/DOM parser (`globalThis.DOMParser === false`), so feed parsing has to happen client-side.
+- **No browser-pane dependency**: `proposals/active/2026-09-13-browser-pane.md` is still `planned`, and canvas CDP frames cannot host selection quoting.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record: the git blob hash of each side as of the
+# last confirmed-consistent state. Both languages carry equal authority; after
+# editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/dsh-reader/README.en.md
+packages/dsh-reader/README.en.md: eb4fd3ca3636e3329283829f1734f6708699aa78
+packages/dsh-reader/README.md: 212a805160058c7cfbdccded74890ca3543f0f0b

package/README.md

@@ -0,0 +1,90 @@
+# @khorsheed/dsh-reader
+
+**灵感空间**：右侧栏一个**页面型 tab**，把 RSS/Atom 订阅和随手粘贴的文章链接收在同一面「灵感墙」上。点卡片在 dsh 里直接读正文（可划选引用），正文受宿主抓取上限截断时明说「内容未完整呈现」并给一个去原文的按钮。
+
+> 包名、tab kind、Remote namespace 都还是 `reader` —— 它们是稳定标识（改了等于改部署的 loader 行和落盘目录），「灵感空间」是**用户看到的名字**。
+
+抓取在**宿主半**完成（走 `ctx.web` 这条官方出网缝），浏览器半只做解析和渲染；订阅清单与最近一次抓回的原始 payload 落在 `$DSH_HOME/state/dsh-reader/state.json`（用 `node:fs` 原子写，**不走 `ctx.fs`** —— 那是按会话策略上锁的沙箱文件系统，见下方 Compatibility），每日按点自动刷新（插件自带 `setTimeout`，不是宿主服务）。
+
+## 三个面
+
+| 面 | 内容 |
+| --- | --- |
+| 灵感墙 | **内容优先**：第一屏就是条目卡片流。**搜索框独占一行、铺满整行宽度**，筛选 / 排序 / 整墙翻译三个控件都移到**表头那一行**（和刷新、设置、加号在一起）——搜索框夹在三个按钮之间时，窄侧栏里连自己打了什么都看不全；每个弹层仍然挂在**打开它的那个按钮**下面，不会盖住另一个按钮。**文字搜索按相关性排**：标题完全命中 → 标题包含 → 其它字段命中，同一档里才用你选的排序（`#源id` / `@标签id` 这类选择器不参与排序），所以「搜一个标题却先出来别的」不再发生；搜索生效时底部还会写明**匹配了多少条**（`匹配「X」N 条`），列表有没有被筛过一眼可见。筛选是一个**两级弹层**，按「阅读状态」（未读）、「按来源」、「**按类型**」（订阅源 / 保存的链接）、「按标签」四种方式收窄墙：根页是阅读状态两行（只看未读、**隐藏重复**）、`按来源` 钻取行（那一行带着**当前值**，所以不存在「被藏起来的状态」）和类型三行。**隐藏重复默认开**：同一篇文章被多个源转载时折成一张卡（三层归并，任一命中即同组：同条目 id——共享 guid 按设计共享抓取/已读/译文；链接归一化——剥协议/www/utm 类追踪参数；折叠标题 + 同一发布日；绝不模糊匹配），幸存卡带「N 个重复来源」徽章（悬停列出其它来源），读过一个副本整组即已读，底部注明隐藏了几条，自动补抓也不为被隐藏的副本花请求，点进去是来源页——独占弹层高度、自己滚动、来源超过 6 个时出现自己的搜索框；**所以订阅再多，弹层第一页也恒定是几行**。筛选用的是和搜索同一套本地谓词（D14），所以不花请求，值就写在搜索框里（`#源id` / `#rss` / `#link` / `@标签id`）、看得见也能清掉——**搜索框里有内容时框内右侧出现一个 ×**，点它一次清空（筛选值和手输的关键词一起清）。**墙上也能整墙翻译**：工具条最右的地球（和详情页那个各自独立，共享同一份翻译记忆）。开启后**逐字段判语言**——中文标题/摘要原样保留、混合卡片只翻英文那一半，绝不中译中；只翻**进入过视口**的卡片（IntersectionObserver 喂队列、每批 6 张、按语言分组、沿用正文那套哨兵批量+校验+逐条兜底），滚回去不重复请求，进详情也不再翻一次标题。下拉两档：只看译文（**鼠标悬停在被翻译的文字上**时只把**那个字段**换回原文——标题换标题、摘要换摘要，卡片空白处/瓷贴/箭头一律不动，便于核对又不神经质）/ 双语对照（每个字段的原文常驻在译文下方，且**沿用该字段自身的排版**——标题原文就是标题字号与行高，靠墨色和字重与译文区分，不缩成小注）。**卡片文字盒是固定的**：标题与摘要各按两行预留高度并双向 clamp，所以译文/原文互换（hover 或对照）都不会改变卡片高度、网格不跳动；只有「双语对照」是显式切换、会让网格整体变高一次。条目卡片是**有底、有描边、12px 圆角的卡**：悬停只提亮不位移，键盘聚焦有环；未读条目标题上墨、瓷砖角上一个**圆点**（7px，会话级、不落盘），已读条目留在原位、只是安静一档；feed 自己的分类与读者自建标签共用同一套药丸尺寸（自建标签带描边、可折行），打标签按卡片上的「＋」打开面板——里面勾选已存在的标签，或**输入名字回车新建**（原生 datalist 已换成可样式化的行）；**标签在筛选弹层的「按标签」区可以删除**（每行右侧一个安静的 ×，删掉即从词表和所有条目上移除，正在用它筛选时收窄也一并清掉）。**保存的链接如果读不到正文，卡片上有一个「仅链接」小徽章**（虚线、安静），悬停与详情会说明原因（见下方「只能存链接的链接」）。**链接卡片的标题在正文解析出来后升级成文章自己的**（正文第一个 h1，否则文档标题；另带第一段实质文字当摘要），随正文写进宿主标注——正文被预算淘汰后卡片仍读这份记忆，一墙论文不用一篇篇点开。没有 `publishedAt` 的保存链接按**它的源加入时间**参与时间排序，所以刚加的那条在最上面，不会沉底。底部一行**新鲜度**：「刷出于 3 小时前 · 每日 10:00」，让你决定要不要按刷新 |
+| 详情 | 点卡片进来。正文以 DOM 文本渲染——**这正是划选引用能工作的原因**，也是这个面不放 iframe 的原因。正文**没有阅读量度**：侧栏给多宽就铺多宽，段落和列表共用同一条右缘。工具条：返回、**翻译（地球 + 视图下拉）**、复制链接、在浏览器打开原文，**单条保存的链接另有一个删除按钮**（订阅源的条目没有：下次刷新它还会回来，给「删除」是假承诺）；标题下的**标签行里还有「重新抓取」**（和卡片药丸同一个宿主动作，用它换一份新副本时会清掉这篇的译文记录——正文要换成新的 DOM）。正文下面列"同一来源"的其他条目。**页面用脚本画的插图抓不到**：这类 `<figure>` 在服务器 HTML 里只有一个空 div 和一句图注（实测 transformer-circuits.pub 这篇有 84 张），抓取不执行脚本，所以**图注保留在正文里**（它是页面发布的文字，写明了画的是什么），正文上方另给一行「这一页有 N 张插图由页面自己的脚本绘制，抓取时拿不到画面（图注保留在正文里）—— 阅读原文」（宿主有 Sidebar Browser 时这个出口开在应用内；未来 capture 包在场时这里还会出现「渲染抓取」——探测不到就不渲染）。**capture 渲染回来的图能进正文**：页面脚本绘制的图以「内联 SVG + 内联样式」到达，归一化按安全子集保留（形状/文字/defs/渐变/裁剪/symbol 复用；`script`/`foreignObject`/SMIL/事件/外部引用永不放行，`url(` 只许本文档片段）——而不是只剩图注。**组合图的结构同样保**：capture 渲染的组合图（图 + 样式盒搭的属性卡）在 figure 里保留 div/span 容器与白名单样式（布局/绘制属性；`position:fixed`、`z-index` 超限、外部 `url()`、脚本把戏全剥），而且任何被解包的块级容器都留下词边界——相邻文字绝不粘连。**但静态标记里就有 URL 的图会回收**：懒加载站点把真 URL 放在 `data-src` 等属性、`srcset`、`<picture>` 的 `<source>` 或 `<noscript>` 的 no-JS 兜底里（`src` 里只是 1px 占位图），抽取按这个顺序解析候选、取 srcset 里最大的一张；**反过来，把真图直接内联成 base64 data URI 的页面（transformer-circuits 一类）也保**——占位图与真图按载荷大小分道（阈值 512 字符，1px gif 约 70、真图表数千起），小的照旧当占位、穿透到懒加载属性，大的原样保留；正文输出的每个 `<img>` 都带 `referrerpolicy="no-referrer"`（防盗链的 CDN 否则直接 403）。**LaTeXML 的矢量图也保**：arxiv HTML 把图嵌成 `<object type="image/svg+xml" data="…">`，归一化把它改写成带原始宽高的 `<img>`；非图片的 object（PDF、视频）照旧整棵丢弃。**公式是原生渲染的 MathML**：arxiv HTML 版的 `<math alttext="…">` 按安全子集放行（`annotation-xml` 与任何脚本永不放行——前者是 HTML 注射通道），块级公式横向滚动而不是顶破排版 |
+| 翻译（浏览器本地） | 工具条上的**地球**是开关：点亮 = 正文显示译文。它右边的下拉三档：**只看译文**（默认，正文上方一条一次性提示说明「点任意一句可看原文，再点收起」）、**双语对照**（每段下方常驻原文小字，可整段折起）、**只看原文**。翻译单元是**句子**：点一句只展开那**一句**的原文（段落下、左侧细线 + 高亮），再点收起，可同时展开多句；**即使这句话中间夹着链接、被切成几段文本，展开的仍是完整的那一句**（不会显示成碎片），**原文那一行不是控件**（它是给选中引用用的文本，点它不收起；点句子才收起，而且**正在选区里的点击会被忽略**，所以拖选原文或译文都不会把展开的原文收掉）。英文原文按**正文级**排版（13.5px、secondary 墨色、行距 1.62、行间 3px）；它**按容器位置分别排边距**（段落旁：贴住所属段落，上 4px / 下 14px；列表项、引用、表格单元格里则在译文下方 5px，**不会被负边距拽上去贴住译文**），**已展开的那一句保留一条很细的下划线**（只有下划线，没有常驻底色/竖条——那是「这句绑定了下面那行原文」的安静标记）；配对高亮**只在 hover 时**出现：鼠标移到某句中文上，这一句（含被链接切开的各段）和它对应那一行原文一起高亮；移到原文行上同理反向。**默认不画任何底色或竖条** —— 试过的常驻标记会把整篇点成花的。**全程在浏览器里跑**（Chrome 138+/Edge 148+ 桌面版的 `Translator` API），模型不出设备、不花 token；**译文的句子对会落盘**（见下），地球开关与翻译会话不落——没有这个 API、语言对不可用、或正文本来就是中文时，地球**不出现**。**译文两层落盘**（`$DSH_HOME/state/dsh-reader`，与缓存正文同一目录、同一敏感级、同一个卸载故事）：全局**句子记忆**（按 `<源>→<目标>:<句子哈希>` 存原文+译文，5 万句上限）+ **按条目的段落映射**（哈希→译文，键在正文哈希上，正文小幅重抓后逐句复用仍在）；合计预算默认 64 MB（订阅管理页的缓存策略同一个动词可调），按「最近使用」跨两层淘汰，**没有 TTL**（重建一份译文要一次手势加逐句模型，不该按小时过期）。效果是：刷新后地球照样等那一下手势，手势之后整篇从磁盘重绘、模型不沾；句子在两份 schema 版本失配时读作 miss、惰性淘汰（浏览器模型升级后不会把旧译文当成新模型的产出） |
+| 新增（弹窗） | 表头加号、空态卡片、墙上尾部虚线卡片三处都能打开同一个**弹窗**（成员 tab 的邀请弹窗同款做法：透明遮罩 + 居中卡片，Esc / 点遮罩关闭），因为「新增」是个瞬时动作，墙没必要被它替换掉。粘进去的地址**存成什么由抓回来的内容决定**（D15）：是 feed 就建订阅，是网页就只存这一篇。**arxiv 的 abs/pdf 链接自动升级到官方 HTML 版**（`arxiv.org/html/<id>`，LaTeXML 生成的语义标记：真表格、真公式），HTML 版不存在（404）时回退到粘进来的地址照常走。**DOI 链接先解析成 arXiv 版再落地**（Crossref 取标题与作者 → arXiv 标题搜索 → 标题相似度 + 作者姓重合的双因子闸；配不上就回普通路径，绝不猜），命中时卡片标注来源 DOI；**OpenReview 链接不抓、直接存仅链接**（实测服务器端读不到：API 在 Cloudflare 挑战后、论坛是 JS SPA），原因和建议写在卡片上（有 arxiv 版就粘 arxiv 链接）。**抓不到也一定存下来**：判定从「成功 / 失败」改成「已保存 + 能不能预览」，原因分档写在弹窗里（反爬 / 需要登录 / 不是网页 / 跨站跳转 / 连不上 / HTTP 错误），对应的卡片标成「仅链接」——把读者粘的 URL 丢掉，比留一张只能打开原文的卡更坏 |
+| 订阅管理（页面） | 表头齿轮进入**订阅管理页**：顶部是一行**压缩设置**（每日刷新时间 + 正文保留并排，长说明收进悬停提示）与一行**存储区**（原文缓存读数「N 篇 · 体量」、译文缓存读数「M 篇映射 + S 句 · 体量」、**译文预算**输入（MB，blur/回车提交）、两步的**清空译文缓存**——读数是宿主聚合的，表本身不过线）与两排带小标题的**筛选片**（`按类型`：全部 / 订阅源 / 保存的链接，各带条数；`排序`：按添加时间 / 按名称 / 按抓取时间，默认添加时间倒序），下面每个源一行，**名称与订阅地址都可以就地编辑**（改地址 = 换一份文档，保存后立刻重抓，名称留空则回退成 feed 自己的标题）、类型、条目数、上次抓取时间、失败原因（按分类说人话，不是宿主缝原话）、单独刷新、暂停/恢复、删除，以及**每日刷新时间的配置**。这些问题是关于「源」而不是关于「内容」的，所以它们不在墙上 |
+| 最近阅读（页面） | 表头**时钟**进入**最近阅读页**：**按打开时间倒序**列出读过的条目（标题 + 来源 + 「多久以前」），点一条**接着读**；右上角一个垃圾桶**清空这份列表**。它记的是「我刚才在读什么」，所以**落盘**（`state.json` 的 `recent`，**最多 100 条**，重开同一条只会把它挪到最上面，不会重复），刷新/重启都还在——这与面板内那份记忆（打开的文章、阅读位置、译文）是两件事：那份**跨 dsh 会话共享、但不跨刷新**（按页面共享，见上），`recent` 则是部署级、重启也在。**一条记录只存条目 id、来源 id、标题、URL、时间**，不存正文；因此即使那条已经**滚出 feed 的窗口**（源还在），这一页依然能把它打开。源被删掉的条目仍然列出，但不可点，并说明只能去原文地址开 |
+
+**卡片上的「抓取」**：每张卡在标签行里有一个状态药丸——**灰＝还没抓（点一下就开始）/ 蓝＝抓取中或已抓待解析 / 绿＝已有全文（点开秒读）/ 红＝失败**。失败态**按原因给动作**：点红色药丸开一个浮层（原因 + 该原因对应的动作——连不上（网络类）给「重新抓取」；反爬 / 登录墙 / 不是网页 / 服务器端读不到给**在真浏览器里打开**（宿主有 Sidebar Browser 就开在应用内，否则外部浏览器）；HTTP 错误 / 空页 / 跨站跳转是终局，只有原因、没有动作），卡片本身保持一行高，不把墙撑破。点「抓取」之后**可以立刻离开这个页面**（切到别的面板、关掉标签、刷新都行）：抓取跑在**宿主**上，原始网页先落到 `bodies/`，下次打开灵感空间时由浏览器半抽出正文再缓存。所以你能先在墙上把想看的几篇点掉，再慢慢读，不必在详情页等。**进入详情时如果这篇还没抓，仍然会自动抓一次**（和点卡片上的「抓取」是同一个动作）；**已经抓过的就不再重抓**——屏上那份就是缓存里的正文，重抓只会白白把 DOM 换掉、连读者已经翻好的译文一起冲走。**feed 自己发布全文的条目，第一次打开就把这份全文存成正文**（零请求——文字已经在屏上了），药丸在同一次手势里转绿，条目滚出 feed 窗口后正文还在。想换一份新副本，用**详情页标签行里的「重新抓取」**（同一条宿主路径，并清掉这篇的译文记录，见下）。
+
+**离开再回来、换个会话接着读**：宿主在另一个主面板接管时会**卸载整个右侧栏**（`RightbarRoot` 只在没有活动主面板时渲染，不是藏起来），而这个面板的 store 每次挂载新建——所以「切到侧边对话再切回来」以前会把打开的正文、阅读位置、墙上的搜索/排序/筛选，以及**已经翻好的译文**全部丢掉。现在这些由**整个页面**记住并恢复：**跨 dsh 会话**——在另一个对话里打开灵感空间，仍然是同一篇文章、同一个阅读位置、同样的收窄和同样的译文——包括**墙上整墙翻译的开关与它翻好的卡片**（面板按会话挂载，这份记忆按页面共享）；**同一会话内**从侧边对话回来也一样。恢复时那篇文章被重新打开（正文由宿主缓存作答，不花请求），阅读位置回到原处（**墙和正文各自的位置都算**；正文里的位置按**内容**记——「第几个块、块内多少像素、**块内第几个字符**」而不是一个像素数——因为文章自带的图片没有尺寸、会边加载边把文档撑高；正文被替换或重抓落地后会重新落回原处，**原文↔译文切换改写块的高度时，也会按字符偏移重新落回同一句**），**译文在本页已经建过翻译会话时自动重新点亮地球**（`Translator.create()` 需要用户手势，所以只有本页已有的会话才可能自动恢复；没有会话就不自动恢复，但记录还在，点一下地球依旧零成本）。**译文跟着正文走**：正文在读者脚下被替换（重抓落地、缓存过期后重取、元素被重建）时，只要这一条的地球是亮的，译文会自动重新贴回新正文（靠页面内的句子记忆，通常不花请求）。**刷新（或页面重新初始化）之后，位置还在**：「读到哪」这份**位置**（打开的条目、正文里的锚点、墙的偏移）写进 `sessionStorage`，所以页面重启后文章和阅读位置都会回来；**地球记录与翻译会话不落盘**（没有可用于恢复的会话，而新建一个需要用户手势），刷新后地球是灭的——但**译文的句子对落盘了**：点一下地球，整篇从宿主的两层存储重绘，模型一个请求都不发。**关掉标签页即清空**（`sessionStorage` 的作用域就是这一个标签页；宿主目录里的译文随预算淘汰，或随卸载整个目录一起删）。
+
+**点击语义（定案方案 B）**：点卡片 = 进详情页。大多数阅读在 dsh 里完成；正文太长或想直接看原文时，详情页自己的按钮会跳浏览器。卡片尾部的箭头是"这里能进"的提示，不是控件。
+
+## 引用
+
+正文是应用级选区，所以 `@khorsheed/dsh-quote` 的浮层菜单**本来就覆盖它**——本插件不自己造选区菜单。详情页底部另有：
+
+- **引用**：选区（没选区就是整条）+ 来源标签，经官方输入机合成进当前会话草稿（读现有草稿合并，绝不覆盖、绝不发送）；
+- **引用到侧边对话**：只有组合里真有 `sideChat` 服务时才显示（能力握手说了算），否则这一项隐藏。
+
+`reader` 自带一个薄 typert Remote（namespace `reader`），verb：`capabilities` / `listSources` / `addSource` / `updateSource` / `removeSource` / `refresh` / `getBodies` / `quoteToSideChat`。宿主半**不解析** feed——解析在浏览器半，`getBodies` 只把原始 payload 交过去。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @khorsheed/dsh-reader
+# 卸载：
+dsh plugin --profile web remove @khorsheed/dsh-reader
+```
+
+装完重启宿主。落盘只有一处目录：`$DSH_HOME/state/dsh-reader/`——`state.json`（订阅清单 + 最近 payload + 读者自己的标签与「最近阅读」记录）与 `bodies/`（超过 256 KiB 的正文各占一个文件；全局翻译记忆是其中的 `translation-memory.json`，超过阈值的条目译文映射也各占一个文件）。卸载后这个目录会留下——想彻底清干净就删掉整个 `dsh-reader/`。
+
+## Compatibility
+
+- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：✅ 完整——`sidebar.right.pane.tab` 座位、`ctx.web.fetch` 出网缝、`ctx.fs` 版本守卫写、`pluginInventory` 都不需要（本插件不做 preset 自隐）。
+- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.5-rc.1）
+- **状态为什么不用 `ctx.fs`**：`ctx.fs` 是本仓库的**沙箱**文件系统，每一次写都由**调用会话**的文件策略把关；workspace-write 会话写 `$DSH_HOME/state` 会被拒（`FS_SANDBOX_DENIED`，验收实例上真实发生过）。这道栅栏本身是对的、要留着；错的是把「属于部署」的状态交给一个「属于会话」的能力。所以本包按仓库里其它宿主态包的写法（`packages/lab/src/state.ts`）用 `node:fs` 原子写（临时文件 + rename），目录不可写时降级为仅内存。
+- **来源名用 feed 自己声明的标题**：宿主半不解析 feed（它没有 XML 解析器），所以新建时只能给一个从 URL 推出来的名字（就是你看到的那串 `raw.githubusercontent.com/...`）。浏览器半解析出 `<channel><title>` 后会用真实标题替换显示名，所以卡片上会出现「Anthropic Research」这样的名字，失败时回退成 URL。列表里报错时显示「{count} 天前」这种占位符也是同一类问题的另一面（参数没被插值），已修。
+- **翻译用的是浏览器自己的端上模型，不是宿主的模型**：`self.Translator`（Chrome 138+/Edge 148+，仅桌面版）在本机进程内翻译，所以**模型不出设备、不花任何 token、不联网**（首次按语言对下一次小语言包，`Translator.create()` 需要用户手势——点地球那一下正好是）。**译文的派生句子对会写到宿主侧**（`$DSH_HOME/state/dsh-reader` 下的全局句子记忆 + 按条目映射，默认 64 MB 预算按最近使用淘汰，无 TTL；敏感级与旁边缓存的正文相同，隐私论据从来是关于网络而不是磁盘）。代价是**只在 Chrome/Edge 桌面存在**：Safari、Firefox、移动端没有这个 API，插件就把地球藏起来，其余功能不受影响。这是刻意的选择：一篇 5 万字符的长文如果走宿主 LLM，是几万 token + 十几秒 + 把文章再发给模型服务一次；端上翻译是零成本、秒级、不出设备（质量是网页翻译级的 NMT，不是 LLM 级）。
+- **翻译单元是句子，不是段落，也不是文本节点**：先按句切好再发出去，配对是**构造出来的真**，不是事后猜的——段落级翻译拿回来是一整段，模型会合句拆句，再对齐就可能给你看错原文。批量发送时句子之间插哨兵，返回的段数对不上就把那一批退回「一句一请求」，**代价是粒度，永远不是正确性**。跨行内元素的句子（例如句中有链接）会变成两个单元，链接本身不动；`<pre>`/`<code>` 里的内容从不翻译。
+- **翻译器建不起来时不会假装**：`Translator.availability()` 只是**提示**，不是承诺 —— Chrome 上确实出现过「availability 说能用、`create()` 却抛 `NotSupportedError`（"Unable to create translator for the given source and target language"）」的情况（macOS 构建有同类记录）。所以插件会：① 源语言先问浏览器的 `LanguageDetector`（猜错源语言正会让某些语言对建不起来，而那条报错**不说是哪个语言对**）；② 目标语言按 `zh` → `zh-Hans` 两种写法依次真建一次；③ 全都以 `NotSupportedError` 拒绝时，**地球自行消失**并明说「这个浏览器无法翻译 en → zh / en → zh-Hans」，同时指向 `chrome://on-device-internals` 的 Broker State 自查；网络/配额这类**非永久**失败则保留地球以便重试，并报出尝试过的语言对与原因（浏览器原文里两个语言都不出现）。
+- **正文还原是逐字节的**：翻译只改文本节点（原文在内存里留着），「只看原文」和取消都能把正文还原成宿主发来的那份 HTML 原样。这也是为什么译文不会丢掉链接、图片、表格——它们根本没被碰过。
+- **有些站点拒绝自动抓取，界面会诚实地告诉你**：实测 `openai.com` 对**任何非浏览器请求都返回 403**（带代理、不带代理、换浏览器 UA 都一样，返回的是一个反机器人挑战页）。这不是抽取失败，也不是能靠重试解决的问题，所以详情页对 401/403 显示「这个站点拒绝自动抓取（原文地址对人以外的请求返回验证页）」而不是「无法提取正文」。**状态码不是唯一线索**：实测 `openreview.net` 的 PDF 链接是 `302 → /challenge?redirect=…` 然后 **200** 的挑战页——只看状态码会把挑战页当成文章存下来（这正是「加进去了但点开没内容」的根因）。所以判定是组合的：最终 URL 与请求 URL 是否变了、可见文本是否少到不像一页、以及反爬/登录页的痕迹词；命中任一条就不再存正文，改存「仅链接」。同类站点（newsletter 平台、付费墙）会有同样表现。这也是为什么浏览器渲染抓取不在本插件范围内：那条路需要 browser-pane，而它目前仍是 planned。
+- **有的 feed 只对部分文章给全文，其余只给摘要**：实测 OpenAI alignment feed 的 27 条正文从 **155 字符**（一句摘要）到 **62,044 字符**（全文）不等——这不是截断，是发布方就这么发的。**摘要不再被当成全文**：以前 feed 的 `<description>` 会被塞进 `contentHtml`，于是条目看起来「已经有正文」——自动补齐跳过它、点开也不再抓，详情页就把那 167 字的摘要当成整篇文章显示。现在解析器给这种条目打上 `summaryOnly`，**打开时照样就地抓一次真文章**（抓取期间正文上方写明「这条订阅源只发布了摘要 —— 全文在原文页面上」，抓到之后这句自动消失），自动补齐也把它列进待补清单。**重抓只在这篇还没有缓存正文时发生**：`summaryOnly` 是 feed 条目的属性、一旦为真就永远为真，所以以前这里会让已经抓过的文章**每次打开都重抓一次**（用同一份正文把 DOM 换掉，译文也就跟着没了）；现在只有屏上那段文字是 feed 自己给的（`fromFeed`）才触发抓取。
+- **宿主一次只交接 100,000 字符，所以超大 feed 只能读到一部分**：这是宿主出网缝的默认上限（`web-fetch-http` 的 `maxBodyChars`），**不是插件的正文预算**（插件自己的预算是单源 256 KB / 总量 2 MiB）。你那条 feed 有 646,905 字符，宿主只给前 100,000，所以 21 条里只有落在前面那部分的两条能读到。插件**无法**绕过它：`ctx.web.fetch` 只接受 `{ url }`，没有 Range、没有自定义请求头、没有分页，插件也不会为了绕过它去 vendor `fetch`（那等于绕开宿主的出网策略）。要让 646 KB 的 feed 完整可读，**不需要改宿主代码**：用官方的 patch 叠加层给那一行加 config 即可（`--patch <file>` 或机器级的 `$DSH_HOME/cordis.patch.yml`，后者对所有 profile 生效）：
+
+```yaml
+- id: web-fetch-http
+  config:
+    maxBodyChars: 2000000   # 默认 100000
+```
+
+已用 `dsh --profile web --patch <file> --dump-config` 实测确认合成结果里带着这个值；3080 上已按此加上覆盖并实测：同一条 feed 由「100,000 字符 / 截断 / 2 条」变成「**646,905 字符 / 未截断 / 21 条完整**」。**2026-09-19 又抬了一档**：研究类文章本身就很大——实测 `transformer-circuits.pub` 的 emotions 那篇 HTML 有 **41.8 MB**（60 张插图是内联 base64），而宿主缝的**字节上限** `maxResponseBytes` 默认只有 5 MB，整次抓取会直接失败（`response exceeds the maximum of 5000000 bytes`），`maxBodyChars` 也挡在前面。现在 3080 的部署配置把**两个上限一起抬到 64 MB**，并把**抓取超时从默认 30 秒抬到 180 秒**（同一篇实测直连 19.5 秒，机器一忙以前就会以 `web fetch timed out` 失败；见 `$DSH_HOME/profiles/web/cordis.patch.yml`）。代价是**全机**每次抓取的峰值内存与传输量都随之上升。注意**插件自己的单源预算必须 ≥ 宿主上限**，否则落盘时会再切一刀——本包的预算是 2 MiB/源、12 MiB/总量（见 `MAX_BODY_CHARS_PER_SOURCE`）。注意边界：插件的 patch 只能挂**自己那一行**（仓库禁止插件去挂/改别人的行），所以这条覆盖属于**部署配置**，由部署方决定；而且它抬高的是**全机所有网页抓取**的上限。
+- **全文是自动补齐的，不需要你点**：每次加载后，宿主给出"还缺全文"的条目清单（一次最多 8 条，失败的条目 6 小时内不再重试），浏览器半条一条抓取+抽取并写入缓存（24 小时，管理页可改），**同时最多 2 个请求**。补齐中的条目仍在墙上显示 feed 自己给的内容，底部一行进度「正在补齐全文 3/8…」；抓到的卡片标一个「已抓全文」（徽章的含义是：卡片上仍是 feed 自己的摘要，全文已经缓存好了，点开就能读）。**不确定要不要等？直接点开那一条**：打开时若本地还没有正文，它会就地抓一次并显示「正在抓取正文…」，不必等补齐轮到它。
+  - 为什么不是"全部一次抓完"：那等于把每个订阅源的所有文章都爬一遍。这里是**每次刷新补一片**，滚动前进。
+  - **抓不到就展示已有的**：站点拒绝（401/403）、连不上、抽取失败，三种情况分开说明，正文位置永远显示 feed 自己发布的内容 + 「阅读原文」，绝不空白。
+- **被宿主截断的 feed 会抢救，而不是整份丢掉**：宿主缝按字符数截断，截在标签中间会让整份 XML 不合法——而"整份不合法"曾经等于**一条都没有**。现在解析器会：完整闭合的 `<item>`/`<entry>` 全部保留（用文档根上的命名空间声明重新包装，否则带 `content:encoded` 前缀的片段自己也是坏 XML）；被截断的那条尽最大努力修复并标成**部分**，正文照常显示已经拿到的部分；墙上给一行「未完整」说明 + 阅读原文。配一个提交在仓库里的 fixture（`tests/fixtures/feed-truncated.xml`）锁住这个形状。
+  实测：验收实例那条 646 KB 的 feed（宿主只给 100,000 字符）现在能出 **2 张卡**——一张完整的 42 KB 正文，一张部分正文——而在这次修复前是 **0 张**。
+- **默认过滤是「全部」而不是「今日」**：RSS 源的最新条目经常不是今天的（验收实例那条 feed 最新一篇是 8 天前），默认「今日」会让刚订阅完的墙看起来像空的 —— 也就是「订阅成功了但什么都没有」。现在**没有「今日」这个过滤**：收窄墙的四种方式（未读 / 按来源 / 按类型 / 按标签）都在筛选弹层里，按钮自己的按下态、以及它写进搜索框的 `#源id` / `#rss` / `#link` / `@标签id`，让「被隐藏了什么」始终看得见。
+- **正文超过 256 KiB 会存成单独文件**：`state.json` 只留元数据（文件名 + 字符数），正文本体落在 `$DSH_HOME/state/dsh-reader/bodies/<hash>.html`。【正文保留】设置的 12/24/168 小时 / 永久对**两种正文一视同仁**，淘汰（超出「保留条数」上限或 TTL 到期后重抓）时会连文件一起删掉。这样做是因为 `state.json` 是一份整体读写的 JSON：一篇插图内联成 base64 的论文抽出来几十 MB，直接塞进去会让之后每一次读者操作都付出几 MB 的往返。
+- **正文顶部的重复标题会被去掉**：详情页已经渲染了条目标题，而文章自己的 HTML 里常常再来一两遍（实测那篇有**两个** `<h1>`，前面还跟着站名和 logo 链接）。抽取时会去掉与文档标题重复的一二级标题、开头的站头chaff 与空行，正文从「Authors」这类真实内容开始。
+- **正文没有阅读量度**：段落和列表都铺满侧栏给的宽度，没有 `max-width`（早先只给段落限宽，右侧留出一条参差的空白带，看起来像布局坏了）。想要更短的行，把侧栏收窄即可。
+- **宿主抓取上限是已知限制**：`ctx.web.fetch` 把解码后的正文截到 100,000 字符且**静默截断**。超限的文章抽不全（实测：Anthropic 研究页 ~266k、theverge.com ~899k、newyorker.com ~1.97M 字符）；摘要页里的文章标题、作者、摘要仍然在。详情页会因此显示「受限篇幅，内容未完整呈现」+「阅读原文」。RSS 源基本安全（实测：HN 11KB、BBC 25KB、阮一峰 69KB、Simon Willison 83KB——83KB 已经贴着上限）。
+- **降级矩阵**：无 `fs` → 状态只在内存里、重启即丢（握手会 `hasFs: false`，不假装有持久化）；无 `web` → 新增的链接照样存下来并标成「仅链接（连不上）」+「阅读原文」，不抛异常、更不丢 URL；无 `sideChat` → 侧边对话那一项隐藏；无 `quote` → 选区浮层缺席，但条目级「引用」按钮照常工作。宿主低于 0.1.6-alpha.2（没有 `browser` 这个右栏 tab 类型）→ 需要真浏览器的地方（脚本插图提示、反爬卡片的动作）给的是普通外部链接，不报错。
+- **跨源重定向只跟随能还原的那一跳**：宿主缝会拒跨源跳转（`WEB_REDIRECT_BLOCKED`），而且**只报目标 origin、不报路径**。所以插件只在**同一个主机换 scheme/端口**时重新进缝（`http://host/feed` → `https://host/feed`，路径与查询原样保留）；**换了主机就如实说「这个地址会跳到另一个站点」，不再跟过去**——跟着 origin 根路径抓回来的是另一个页面，然后还会被当成读者粘的那个地址存下来。这条以前写的是「最多跟 3 跳」，但那段判定读的是错误**消息文本**里根本没有的 `WEB_REDIRECT_BLOCKED`（宿主把它放在 `error.code` 上），所以跟随从来没生效过、每次都是把宿主缝的原话甩给用户；现在按 `code` 判定，并补了回归测试。
+- **站点拒绝 / 登录墙 / PDF 都只会变成「仅链接」**：抓回来的页面如果**几乎没有可读文本**（`< 200` 字符可见文本，去掉 script/style 后计）并且带着反爬或登录页的痕迹，就不当作文章存下来——**挑战页本身绝不落成卡片正文**。`application/pdf` 之类更是宿主的出网缝直接拒绝的类型（`WEB_UNSUPPORTED_CONTENT_TYPE`，只认 html/text/json/xml）。这些卡片照常出现在墙上、能打标签、能复制链接、能删除，点开只有原因 + 「阅读原文」。
+- **不可重试的原因不会被自动重试**：反爬、登录墙、PDF、HTTP 错误、空页面都记录成不可重试（`isRetryablePreviewFailure` 只放行 `unreachable`），自动补齐不会再敲它们；订阅管理页那一行的「刷新」仍可手动重试，成功后清掉记录。这样插件不会对一个永远拒绝它的站点每 6 小时敲一次。
+- **不做条件请求**：宿主缝没有自定义请求头入口，所以没有 ETag/If-None-Match，每次刷新都是完整抓取。
+- **订阅登录墙后面的内容：不做**。没有凭证注入面。
+
+## Known Limitations
+
+- **只订阅、不抓文**：新增订阅时只抓 feed 本身，不会为每条目预抓正文（存储会爆，而且那是在当爬虫）。想看某条正文时点开它，付一次抓取。
+- **PDF 与其它非网页文件没有正文**：宿主的出网缝只认 `text/html`、`text/*`、`application/json`、`application/xml`，`application/pdf` 会被直接拒绝；而正文提取本来就是 DOM 的，PDF 没有 DOM。所以 PDF 链接只能存成「仅链接」的卡片 + 「阅读原文」，插件不是 PDF 阅读器。
+- **跨站跳转不跟随**：宿主缝只报目标 origin，路径无法还原，所以换了主机的跳转（短链、ezproxy 之类的代理）一律如实报「跳到另一个站点」，不会跟过去猜。
+- **未读与正文不落盘**：会话级状态。持久化逐条已读游标需要第二份写密集文档，而"自上次看过以来有什么新的"本身就是这个插件的价值所在。
+- **XML 解析在浏览器**：宿主侧没有 XML/DOM 解析器（`globalThis.DOMParser === false`），所以 feed 解析必然在客户端。
+- **不依赖 browser-pane**：`proposals/active/2026-09-13-browser-pane.md` 还是 planned，而且 canvas 的 CDP 帧里承载不了划选引用。

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# dsh-reader bundle patch: inserts the plugin row into the composing profile,
+# so `dsh plugin --profile <name> add @khorsheed/dsh-reader` reconciles it into
+# the bundles layer. The row is a bare mount — the host half provides the
+# `reader` service core and mounts its thin Remote face; the browser half is
+# discovered through the package.json `dsh.client` block.
+#
+# NOTE: a composition must mount this row id exactly once. Official images
+# mount no reader row, so plugin-adding this package is the install path there;
+# a composition that already mounts the id by other means must NOT also add it
+# — a duplicate loader entry id fails boot.
+- insert:
+    - id: reader
+      name: "@khorsheed/dsh-reader"