@khorsheed/dsh-reader 0.2.0 → 0.3.0

package/lib/types/image-fetch.js

@@ -0,0 +1,385 @@
+/** An article figure is a few hundred KB; 8 MiB leaves room for print-resolution PNGs. */
+export const IMAGE_FETCH_MAX_BYTES = 8 * 1024 * 1024;
+/** One image fetch never hangs the rescue: the pane's picture stays broken instead. */
+export const IMAGE_FETCH_TIMEOUT_MS = 15_000;
+/** Redirect hops per image, each re-validated end to end (the classic SSRF hop). */
+export const IMAGE_FETCH_MAX_REDIRECTS = 3;
+/** An honest agent line — bot walls are reported, never impersonated around. */
+const IMAGE_FETCH_USER_AGENT = 'dsh-reader image rescue (+https://github.com/Khorsheed/dsh-plugins)';
+/**
+ * The raster/vector types a rescued image may declare. The pane re-points the
+ * failed `<img>` at these bytes, so an SVG rides an image context (which never
+ * scripts); anything else the origin answers — HTML above all — is refused
+ * before the body is read.
+ */
+const IMAGE_MIME = /^image\/(?:png|jpe?g|gif|webp|avif|svg\+xml|bmp|x-icon|vnd\.microsoft\.icon)$/i;
+/**
+ * The byte budget of the in-memory rescue cache (wire size — base64 is what
+ * the map actually holds). A figure-heavy article is a few MB; the budget
+ * covers several of them, and the oldest entry leaves first.
+ */
+export const IMAGE_CACHE_BUDGET_BYTES = 32 * 1024 * 1024;
+/**
+ * The rescue cache: a pane remount (the sidebar unmounts wholesale when
+ * another panel takes over) re-fails every CORP-blocked image, and this map is
+ * what keeps that a memory read instead of a dozen outbound requests. LRU by
+ * insertion refresh, bounded by bytes.
+ */
+export class ImageFetchCache {
+    budgetBytes;
+    entries = new Map();
+    bytes = 0;
+    constructor(budgetBytes = IMAGE_CACHE_BUDGET_BYTES) {
+        this.budgetBytes = budgetBytes;
+    }
+    /** The cached bytes for one URL, refreshing its recency. */
+    get(url) {
+        const hit = this.entries.get(url);
+        if (hit === undefined)
+            return undefined;
+        this.entries.delete(url);
+        this.entries.set(url, hit);
+        return hit;
+    }
+    /** Cache one fetched image, evicting the oldest entries until it fits. */
+    set(url, mime, base64) {
+        if (base64.length > this.budgetBytes)
+            return;
+        const existing = this.entries.get(url);
+        if (existing !== undefined) {
+            this.bytes -= existing.base64.length;
+            this.entries.delete(url);
+        }
+        while (this.bytes + base64.length > this.budgetBytes) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done)
+                break;
+            const dropped = this.entries.get(oldest.value);
+            this.entries.delete(oldest.value);
+            this.bytes -= dropped?.base64.length ?? 0;
+        }
+        this.entries.set(url, { mime, base64 });
+        this.bytes += base64.length;
+    }
+}
+/**
+ * Fetch one image, policy-checked end to end.
+ *
+ * Errors are values: the pane's only answer to a failed rescue is leaving the
+ * broken image as it was, so the reason string is for logs, not for display.
+ *
+ * @param rawUrl - the image URL the pane failed on.
+ * @param seams - resolver/lookup overrides (tests only; production pins).
+ * @param limits - byte/timeout/redirect overrides (tests only).
+ * @returns the image bytes base64-encoded with their declared type, or why not.
+ */
+export async function fetchImageBytes(rawUrl, seams = {}, limits = {}) {
+    const maxBytes = limits.maxBytes ?? IMAGE_FETCH_MAX_BYTES;
+    const timeoutMs = limits.timeoutMs ?? IMAGE_FETCH_TIMEOUT_MS;
+    const maxRedirects = limits.maxRedirects ?? IMAGE_FETCH_MAX_REDIRECTS;
+    let current = rawUrl;
+    for (let hop = 0; hop <= maxRedirects; hop++) {
+        const gate = await checkImageTarget(current, seams.resolve);
+        if (!gate.ok)
+            return { ok: false, url: rawUrl, error: gate.error };
+        const response = await requestOnce(gate.url, gate.addresses, timeoutMs, seams.lookup);
+        if (!response.ok)
+            return { ok: false, url: rawUrl, error: response.error };
+        const { message } = response;
+        const status = message.statusCode ?? 0;
+        if (status >= 300 && status < 400) {
+            message.resume();
+            const location = message.headers['location'];
+            if (typeof location !== 'string' || location.length === 0) {
+                return { ok: false, url: rawUrl, error: `HTTP ${status} without a location` };
+            }
+            try {
+                current = new URL(location, current).toString();
+            }
+            catch {
+                return { ok: false, url: rawUrl, error: `HTTP ${status} to an unparseable location` };
+            }
+            continue;
+        }
+        if (status < 200 || status >= 300) {
+            message.resume();
+            return { ok: false, url: rawUrl, error: `HTTP ${status}` };
+        }
+        const mime = (message.headers['content-type'] ?? '').replace(/;.*$/s, '').trim().toLowerCase();
+        if (!IMAGE_MIME.test(mime)) {
+            message.resume();
+            return { ok: false, url: rawUrl, error: `the response is not an image (content-type "${mime || 'unknown'}")` };
+        }
+        const declared = Number(message.headers['content-length'] ?? Number.NaN);
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            message.resume();
+            return { ok: false, url: rawUrl, error: `the image exceeds the ${Math.floor(maxBytes / 1024 / 1024)} MiB cap` };
+        }
+        const body = await readBody(message, maxBytes);
+        if (!body.ok)
+            return { ok: false, url: rawUrl, error: body.error };
+        return { ok: true, url: rawUrl, mime, base64: body.base64 };
+    }
+    return { ok: false, url: rawUrl, error: `more than ${maxRedirects} redirects` };
+}
+/**
+ * The syntax gate plus the address gate, in the order capture's navigation
+ * policy runs them. The address set travels with the verdict: the transport
+ * dials exactly these, so the hostname is never resolved twice.
+ */
+async function checkImageTarget(raw, resolve) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, error: 'invalid-url' };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return { ok: false, error: `only http(s) images can be rescued, not ${url.protocol}` };
+    }
+    if (url.username !== '' || url.password !== '') {
+        return { ok: false, error: 'URLs with embedded credentials are never fetched' };
+    }
+    const hostname = url.hostname.replace(/\.$/, '');
+    if (hostname === '')
+        return { ok: false, error: 'invalid-url' };
+    if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+        return { ok: false, error: 'localhost is never fetched' };
+    }
+    if (isIpLiteral(hostname)) {
+        const bare = hostname.startsWith('[') ? hostname.slice(1, -1) : hostname;
+        const cls = classifyAddress(bare);
+        if (cls !== 'public')
+            return { ok: false, error: `${bare} is a ${cls} address` };
+        return { ok: true, url, addresses: [{ address: bare, family: bare.includes(':') ? 6 : 4 }] };
+    }
+    const resolver = resolve ?? defaultResolve;
+    let addresses;
+    try {
+        addresses = await resolver(hostname.replace(/^\[(.*)\]$/, '$1'));
+    }
+    catch (error) {
+        return { ok: false, error: `cannot resolve ${hostname}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (addresses.length === 0)
+        return { ok: false, error: `cannot resolve ${hostname}: no addresses` };
+    for (const { address } of addresses) {
+        const cls = classifyAddress(address);
+        if (cls !== 'public')
+            return { ok: false, error: `${hostname} resolves to a ${cls} address` };
+    }
+    return { ok: true, url, addresses };
+}
+/**
+ * Issue one GET against the validated address set.
+ *
+ * The `lookup` handed to the transport answers with the validated addresses
+ * and nothing else — DNS is consulted once, by the gate, and the connection
+ * cannot re-resolve the hostname into a private network (the rebinding window
+ * a plain fetch leaves open). Node still verifies TLS against the HOSTNAME;
+ * the lookup only maps it to an address.
+ */
+function requestOnce(url, addresses, timeoutMs, lookup) {
+    return new Promise((resolvePromise) => {
+        void (async () => {
+            const transport = url.protocol === 'https:'
+                ? await import('node:https')
+                : await import('node:http');
+            const request = transport.request({
+                protocol: url.protocol,
+                // Bracketed IPv6 literals are a URL spelling, not a host option.
+                hostname: url.hostname.replace(/^\[(.*)\]$/, '$1'),
+                port: url.port,
+                path: `${url.pathname}${url.search}`,
+                method: 'GET',
+                headers: {
+                    accept: 'image/avif,image/webp,image/png,image/svg+xml,image/*,*/*;q=0.8',
+                    'accept-encoding': 'identity',
+                    'user-agent': IMAGE_FETCH_USER_AGENT,
+                },
+                lookup: lookup ?? pinnedLookup(addresses),
+            }, (message) => resolvePromise({ ok: true, message }));
+            request.setTimeout(timeoutMs, () => {
+                request.destroy(new Error(`the image fetch timed out after ${timeoutMs} ms`));
+            });
+            request.on('error', (error) => resolvePromise({ ok: false, error: error.message }));
+            request.end();
+        })().catch((error) => resolvePromise({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+    });
+}
+/** The lookup that pins a request to the gate's validated answers. */
+function pinnedLookup(addresses) {
+    return (_hostname, options, callback) => {
+        if (options.all === true) {
+            callback(null, addresses.map(({ address, family }) => ({ address, family })));
+            return;
+        }
+        const first = addresses[0];
+        callback(null, first.address, first.family);
+    };
+}
+/** The body, capped; over the cap is a refusal, not a truncation. */
+function readBody(message, maxBytes) {
+    return new Promise((resolvePromise) => {
+        const chunks = [];
+        let received = 0;
+        message.on('data', (chunk) => {
+            received += chunk.byteLength;
+            if (received > maxBytes) {
+                message.destroy();
+                resolvePromise({ ok: false, error: `the image exceeds the ${Math.floor(maxBytes / 1024 / 1024)} MiB cap` });
+                return;
+            }
+            chunks.push(chunk);
+        });
+        message.on('end', () => resolvePromise({ ok: true, base64: Buffer.concat(chunks).toString('base64') }));
+        message.on('error', (error) => resolvePromise({ ok: false, error: error.message }));
+    });
+}
+/** The system resolver, bound lazily so importing this module never touches `node:dns`. */
+async function defaultResolve(hostname) {
+    const dns = await import('node:dns');
+    return dns.promises.lookup(hostname, { all: true, verbatim: true });
+}
+/** Parse a canonical IPv4 string into its 32-bit value, or undefined. */
+function parseIpv4(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4)
+        return undefined;
+    let value = 0;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return undefined;
+        if (part.length > 1 && part.startsWith('0'))
+            return undefined; // legacy octal-looking octets: fail closed
+        const octet = Number(part);
+        if (octet > 255)
+            return undefined;
+        value = value * 256 + octet;
+    }
+    return value >>> 0;
+}
+/** Expand an IPv6 string into its eight 16-bit groups, or undefined when malformed. */
+function parseIpv6Groups(address) {
+    // Strip a zone id (link-local literals like fe80::1%eth0).
+    const zoneless = address.split('%')[0];
+    if (!/^[0-9a-fA-F:.]+$/.test(zoneless))
+        return undefined;
+    const halves = zoneless.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const parseHalf = (half) => {
+        if (half === '')
+            return [];
+        const groups = [];
+        const parts = half.split(':');
+        for (const [index, part] of parts.entries()) {
+            // An embedded dotted-quad tail (deprecated compatible / mapped forms).
+            if (part.includes('.')) {
+                if (index !== parts.length - 1)
+                    return undefined;
+                const v4 = parseIpv4(part);
+                if (v4 === undefined)
+                    return undefined;
+                groups.push((v4 >>> 16) & 0xffff, v4 & 0xffff);
+                continue;
+            }
+            if (!/^[0-9a-fA-F]{1,4}$/.test(part))
+                return undefined;
+            groups.push(parseInt(part, 16));
+        }
+        return groups;
+    };
+    const head = parseHalf(halves[0]);
+    if (head === undefined)
+        return undefined;
+    if (halves.length === 1)
+        return head.length === 8 ? head : undefined;
+    const tail = parseHalf(halves[1]);
+    if (tail === undefined)
+        return undefined;
+    const missing = 8 - head.length - tail.length;
+    if (missing < 0 || (missing === 0 && halves[1] !== ''))
+        return undefined;
+    return [...head, ...Array(missing).fill(0), ...tail];
+}
+/** The embedded IPv4 value of an IPv4-mapped, NAT64, or 6to4 IPv6 address. */
+function embeddedIpv4(groups) {
+    // ::ffff:a.b.c.d (IPv4-mapped): groups 0-4 zero, group 5 0xffff.
+    if (groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff) {
+        return ((groups[6] << 16) | groups[7]) >>> 0;
+    }
+    // 64:ff9b::/96 (NAT64 well-known prefix): the v4 address is the last 32 bits.
+    if (groups[0] === 0x0064 && groups[1] === 0xff9b && groups.slice(2, 6).every((g) => g === 0)) {
+        return ((groups[6] << 16) | groups[7]) >>> 0;
+    }
+    // 2002::/16 (6to4): the v4 address is groups 1-2.
+    if (groups[0] === 0x2002) {
+        return ((groups[1] << 16) | groups[2]) >>> 0;
+    }
+    return undefined;
+}
+/** Classify a canonical dotted-quad IPv4 value. */
+function classifyIpv4(value) {
+    const a = (value >>> 24) & 0xff;
+    const b = (value >>> 16) & 0xff;
+    if (a === 0)
+        return 'unspecified'; // 0.0.0.0/8 "this host"
+    if (a === 127)
+        return 'loopback';
+    if (a === 10)
+        return 'private';
+    if (a === 172 && b >= 16 && b <= 31)
+        return 'private';
+    if (a === 192 && b === 168)
+        return 'private';
+    if (a === 169 && b === 254)
+        return 'link-local'; // incl. 169.254.169.254 cloud metadata
+    if (a === 100 && b >= 64 && b <= 127)
+        return 'private'; // CGNAT shared space
+    if (a === 192 && b === 0)
+        return 'reserved'; // 192.0.0.0/24 protocol assignments, 192.0.2.0/24 documentation
+    if (a === 198 && (b === 18 || b === 19))
+        return 'reserved'; // benchmarking
+    if (a === 198 && b === 51)
+        return 'reserved'; // documentation
+    if (a === 203 && b === 0)
+        return 'reserved'; // documentation
+    if (a >= 224 && a <= 239)
+        return 'multicast';
+    if (a >= 240)
+        return 'reserved';
+    return 'public';
+}
+/** Classify one resolved address (IPv4 or IPv6, canonical or transition form). */
+function classifyAddress(address) {
+    const v4 = parseIpv4(address);
+    if (v4 !== undefined)
+        return classifyIpv4(v4);
+    const groups = parseIpv6Groups(address);
+    if (groups === undefined)
+        return 'reserved'; // unparseable is never public
+    const embedded = embeddedIpv4(groups);
+    if (embedded !== undefined)
+        return classifyIpv4(embedded);
+    const first = groups[0];
+    if (groups.every((g) => g === 0))
+        return 'unspecified'; // ::
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return 'loopback'; // ::1
+    if ((first & 0xfe00) === 0xfc00)
+        return 'private'; // fc00::/7 unique local
+    if ((first & 0xffc0) === 0xfe80)
+        return 'link-local'; // fe80::/10
+    if ((first & 0xff00) === 0xff00)
+        return 'multicast'; // ff00::/8
+    if (first === 0x2001 && groups[1] === 0x0db8)
+        return 'reserved'; // documentation
+    return 'public';
+}
+/** Whether one hostname string is already an IP literal (bracketed v6 or dotted v4). */
+function isIpLiteral(hostname) {
+    const bare = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+    return parseIpv4(bare) !== undefined || parseIpv6Groups(bare) !== undefined;
+}

package/lib/types/remote.d.ts

@@ -11,7 +11,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import type { ReaderAddFailure, ReaderAddOutcome, ReaderAddRefusal, ReaderAnnotationOutcome, ReaderBackfillCandidate, ReaderEntryBodyView, ReaderEntryFetchState, ReaderBody, ReaderCapabilities, ReaderEntryTranslationView, ReaderMutationOutcome, ReaderRecentEntry, ReaderRefreshResult, ReaderSentenceLearn, ReaderSourceSummary, ReaderStorageStats, ReaderTag } from './types.ts';
+import type { ReaderAddFailure, ReaderAddOutcome, ReaderAddRefusal, ReaderAnnotationOutcome, ReaderBackfillCandidate, ReaderEntryBodyView, ReaderImageResult, ReaderEntryFetchState, ReaderBody, ReaderCapabilities, ReaderEntryTranslationView, ReaderMutationOutcome, ReaderRecentEntry, ReaderRefreshResult, ReaderSentenceLearn, ReaderSourceSummary, ReaderStorageStats, ReaderTag } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         readerRemote: ReaderRemoteService;
@@ -80,6 +80,14 @@ export declare class ReaderRemoteService extends TypertRemoteService<ReaderRemot
         truncated?: boolean;
         error?: string;
     }>;
+    /**
+     * Fetch one image the browser could not load cross-origin (CORP /
+     * hotlink-protected), so the pane can re-point the failed `<img>` at the
+     * bytes. Called per failed image, never for a healthy one.
+     */
+    fetchImage(request: {
+        url: string;
+    }): Promise<ReaderImageResult>;
     /** Cache the markup the browser extracted for one entry. */
     storeEntryBody(request: {
         entryId: string;

package/lib/types/remote.js

@@ -46,6 +46,7 @@ let ReaderRemoteService = (() => {
     let _getBodies_decorators;
     let _getEntryBody_decorators;
     let _fetchEntryBody_decorators;
+    let _fetchImage_decorators;
     let _storeEntryBody_decorators;
     let _entryFetchStates_decorators;
     let _getRawBody_decorators;
@@ -80,6 +81,7 @@ let ReaderRemoteService = (() => {
             _getBodies_decorators = [Remote('getBodies')];
             _getEntryBody_decorators = [Remote('getEntryBody')];
             _fetchEntryBody_decorators = [Remote('fetchEntryBody')];
+            _fetchImage_decorators = [Remote('fetchImage')];
             _storeEntryBody_decorators = [Remote('storeEntryBody')];
             _entryFetchStates_decorators = [Remote('entryFetchStates')];
             _getRawBody_decorators = [Remote('getRawBody')];
@@ -111,6 +113,7 @@ let ReaderRemoteService = (() => {
             __esDecorate(this, null, _getBodies_decorators, { kind: "method", name: "getBodies", static: false, private: false, access: { has: obj => "getBodies" in obj, get: obj => obj.getBodies }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getEntryBody_decorators, { kind: "method", name: "getEntryBody", static: false, private: false, access: { has: obj => "getEntryBody" in obj, get: obj => obj.getEntryBody }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _fetchEntryBody_decorators, { kind: "method", name: "fetchEntryBody", static: false, private: false, access: { has: obj => "fetchEntryBody" in obj, get: obj => obj.fetchEntryBody }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _fetchImage_decorators, { kind: "method", name: "fetchImage", static: false, private: false, access: { has: obj => "fetchImage" in obj, get: obj => obj.fetchImage }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _storeEntryBody_decorators, { kind: "method", name: "storeEntryBody", static: false, private: false, access: { has: obj => "storeEntryBody" in obj, get: obj => obj.storeEntryBody }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _entryFetchStates_decorators, { kind: "method", name: "entryFetchStates", static: false, private: false, access: { has: obj => "entryFetchStates" in obj, get: obj => obj.entryFetchStates }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getRawBody_decorators, { kind: "method", name: "getRawBody", static: false, private: false, access: { has: obj => "getRawBody" in obj, get: obj => obj.getRawBody }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -181,6 +184,14 @@ let ReaderRemoteService = (() => {
         fetchEntryBody(request) {
             return this.core.fetchEntryBody(request);
         }
+        /**
+         * Fetch one image the browser could not load cross-origin (CORP /
+         * hotlink-protected), so the pane can re-point the failed `<img>` at the
+         * bytes. Called per failed image, never for a healthy one.
+         */
+        fetchImage(request) {
+            return this.core.fetchImage(request);
+        }
         /** Cache the markup the browser extracted for one entry. */
         storeEntryBody(request) {
             return this.core.storeEntryBody(request);

package/lib/types/service.d.ts

@@ -35,7 +35,7 @@
  * @module @khorsheed/dsh-reader/service
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { type ReaderAddFailure, type ReaderAddOutcome, type ReaderAddRefusal, type ReaderAnnotationOutcome, type ReaderBackfillCandidate, type ReaderEntryBodyView, type ReaderBody, type ReaderCapabilities, type ReaderMutationOutcome, type ReaderEntryFetchState, type ReaderEntryTranslationView, type ReaderPreviewFailure, type ReaderPreviewFailureCode, type ReaderRecentEntry, type ReaderRefreshResult, type ReaderSentenceLearn, type ReaderSourceSummary, type ReaderStorageStats, type ReaderTag } from './types.ts';
+import { type ReaderAddFailure, type ReaderAddOutcome, type ReaderAddRefusal, type ReaderAnnotationOutcome, type ReaderBackfillCandidate, type ReaderEntryBodyView, type ReaderBody, type ReaderCapabilities, type ReaderMutationOutcome, type ReaderEntryFetchState, type ReaderEntryTranslationView, type ReaderPreviewFailure, type ReaderPreviewFailureCode, type ReaderImageResult, type ReaderRecentEntry, type ReaderRefreshResult, type ReaderSentenceLearn, type ReaderSourceSummary, type ReaderStorageStats, type ReaderTag } from './types.ts';
 /**
  * How many entries one automatic backfill run may fetch.
  *
@@ -78,6 +78,8 @@ export declare class ReaderService {
     private disposed;
     /** The document of record when no filesystem is mounted. */
     private memoryDoc;
+    /** Rescued images, by URL — a pane remount re-fails every blocked image, and this is what keeps that a memory read. */
+    private readonly imageCache;
     /**
      * @param ctx - owning context.
      * @param config - optional state-root override.
@@ -230,6 +232,33 @@ export declare class ReaderService {
         truncated?: boolean;
         error?: string;
     }>;
+    /**
+     * One image the browser could not load cross-origin, fetched host-side.
+     *
+     * The pane calls this only for an `<img>` that already FAILED: the page's
+     * bytes arrived fine (a direct fetch gets a 200) but the origin answers them
+     * with `Cross-Origin-Resource-Policy: same-origin`, so the browser withholds
+     * them from this page no matter what the tag asks — measured on claude.dev's
+     * `/media/*` figures (2026-09-29), which broke with the alt text showing.
+     * CORP is an embedder-side check, so a host-process fetch is the way through.
+     *
+     * This deliberately does NOT ride `ctx.web.fetch`: the seam's decoded body is
+     * a closed html|text union and its provider refuses binary content types
+     * outright. The image fetch re-implements the seam's hardening at image
+     * scope instead (public-address validation with the connection pinned to the
+     * validated answers, a byte cap, a timeout, per-hop re-validation, and an
+     * image/* content-type gate) — see `image-fetch.ts`.
+     *
+     * Rescued bytes are kept in an in-memory LRU under a byte budget: the
+     * sidebar unmounts wholesale when another panel takes over, and a remount
+     * re-fails every blocked image before this cache can answer it.
+     *
+     * @param request - the image URL the pane failed on.
+     * @returns the bytes and their declared type, or why there are none.
+     */
+    fetchImage(request: {
+        url: string;
+    }): Promise<ReaderImageResult>;
     /**
      * Which entries have a body, a stored raw payload, or a recorded failure.
      *

package/lib/types/service.js

@@ -2,6 +2,7 @@ import { MAX_RECENT_ENTRIES, ReaderStore, ReaderStoreError, boundTranslations, e
 import { defaultSourceLabel, errorMessage, isRetryablePreviewFailure, linkEntryId, DEFAULT_CACHE_POLICY, DEFAULT_TRANSLATION_BUDGET_CHARS, INLINE_BODY_MAX_CHARS, TRANSLATION_STORAGE_VERSION, } from "./types.js";
 import { delayUntilNext, isCatchUpDue } from "./schedule.js";
 import { arxivHtmlUrl } from "./arxiv.js";
+import { fetchImageBytes, ImageFetchCache } from "./image-fetch.js";
 import { resolveLink } from "./link-resolvers.js";
 /**
  * How many entries one automatic backfill run may fetch.
@@ -81,6 +82,8 @@ export class ReaderService {
     disposed = false;
     /** The document of record when no filesystem is mounted. */
     memoryDoc;
+    /** Rescued images, by URL — a pane remount re-fails every blocked image, and this is what keeps that a memory read. */
+    imageCache = new ImageFetchCache();
     /**
      * @param ctx - owning context.
      * @param config - optional state-root override.
@@ -549,6 +552,43 @@ export class ReaderService {
             return { entryId: request.entryId, error: failure.message };
         }
     }
+    /**
+     * One image the browser could not load cross-origin, fetched host-side.
+     *
+     * The pane calls this only for an `<img>` that already FAILED: the page's
+     * bytes arrived fine (a direct fetch gets a 200) but the origin answers them
+     * with `Cross-Origin-Resource-Policy: same-origin`, so the browser withholds
+     * them from this page no matter what the tag asks — measured on claude.dev's
+     * `/media/*` figures (2026-09-29), which broke with the alt text showing.
+     * CORP is an embedder-side check, so a host-process fetch is the way through.
+     *
+     * This deliberately does NOT ride `ctx.web.fetch`: the seam's decoded body is
+     * a closed html|text union and its provider refuses binary content types
+     * outright. The image fetch re-implements the seam's hardening at image
+     * scope instead (public-address validation with the connection pinned to the
+     * validated answers, a byte cap, a timeout, per-hop re-validation, and an
+     * image/* content-type gate) — see `image-fetch.ts`.
+     *
+     * Rescued bytes are kept in an in-memory LRU under a byte budget: the
+     * sidebar unmounts wholesale when another panel takes over, and a remount
+     * re-fails every blocked image before this cache can answer it.
+     *
+     * @param request - the image URL the pane failed on.
+     * @returns the bytes and their declared type, or why there are none.
+     */
+    async fetchImage(request) {
+        const url = normalizeUrl(request.url);
+        if (url === undefined)
+            return { url: request.url, error: 'invalid-url' };
+        const cached = this.imageCache.get(url);
+        if (cached !== undefined)
+            return { url, mime: cached.mime, base64: cached.base64 };
+        const fetched = await fetchImageBytes(url);
+        if (!fetched.ok)
+            return { url, error: fetched.error };
+        this.imageCache.set(url, fetched.mime, fetched.base64);
+        return { url, mime: fetched.mime, base64: fetched.base64 };
+    }
     /**
      * Which entries have a body, a stored raw payload, or a recorded failure.
      *

package/lib/types/types.d.ts

@@ -707,4 +707,23 @@ export interface ReaderEntryBodyView {
     /** Why a fetch could not produce a body, when one was attempted. */
     readonly error?: string;
 }
+/**
+ * One image the pane could not load cross-origin, fetched host-side.
+ *
+ * The browser-side block is CORP/hotlink protection: the origin answers the
+ * bytes (a direct fetch gets a 200) but withholds them from a cross-origin
+ * page. The rescue hands the bytes over the wire base64-encoded — the pane
+ * re-points the failed `<img>` at a `data:` URI built from them. A failed
+ * rescue carries `error` instead; the pane leaves the broken image alone.
+ */
+export interface ReaderImageResult {
+    /** The URL the pane asked about (echoed, so a late answer can be matched). */
+    readonly url: string;
+    /** The image's declared content type, when the fetch produced bytes. */
+    readonly mime?: string;
+    /** The image bytes, base64-encoded, when the fetch produced them. */
+    readonly base64?: string;
+    /** Why the rescue failed, when it did. */
+    readonly error?: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.3.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -41,7 +41,8 @@
     "lib/typert.remote-client.d.ts",
     "lib/typert.remote-client.js",
     "cordis.patch.yml",
-    "locale/*.json"
+    "locale/*.json",
+    "CHANGELOG.md"
   ],
   "license": "MIT",
   "dependencies": {
@@ -49,15 +50,15 @@
   },
   "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",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-session": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.1.7-rc.1 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6 || ^0.2.0-rc.1",
     "react": "^18.2.0"
   },
   "peerDependenciesMeta": {