dsh-plugin-shop 0.6.0-beta.2 → 0.7.0-beta.0

package/README.md

@@ -52,9 +52,9 @@ install them once with `npm install -g @deepseek-ai/dsh pnpm` and verify with
 # holds back very recent releases, so a bare `add dsh-plugin-shop` can hand
 # you an older version for a while. Pin the current release — refresh it
 # with `npm view dsh-plugin-shop version`.
-dsh plugin --profile web add dsh-plugin-shop@0.5.4
+dsh plugin --profile web add dsh-plugin-shop@0.6.0
 # or straight through npx, nothing installed:
-npx -y @deepseek-ai/dsh plugin --profile web add dsh-plugin-shop@0.5.4
+npx -y @deepseek-ai/dsh plugin --profile web add dsh-plugin-shop@0.6.0
 ```
 
 Replace `web` with your profile if you use another one. Then restart `dsh` once — a
@@ -84,7 +84,7 @@ ls -1 "${DSH_HOME:-$HOME/.dsh}/profiles" | grep -v '^node_modules$'
 cooldown, and deterministic installs are the point of the agent path.
 
 ```sh
-dsh plugin --profile <profile> add dsh-plugin-shop@0.5.4
+dsh plugin --profile <profile> add dsh-plugin-shop@0.6.0
 ```
 
 **3. Verify — do not skip this.** A zero exit from step 2 means pnpm resolved the
@@ -138,9 +138,16 @@ Compromising the browser half buys an attacker those nine calls and nothing more
 
 ## ⚙️ Configuration
 
+The shop reads its catalog from whichever source answers first: the npm
+package `dsh-plugin-shop-catalog` (via your configured registry, npmmirror,
+or npmjs) or `https://LivXue.github.io/dsh-plugin-shop/v1/`. All of them
+carry the same bytes; the race exists because the link to one of them can be
+far slower than the link to another. Setting `DSH_SHOP_CATALOG_URL` opts out
+of the race and uses only what you name.
+
 | Variable | Effect |
 |---|---|
-| `DSH_SHOP_CATALOG_URL` | Point the shop at your own catalog mirror instead of the public one |
+| `DSH_SHOP_CATALOG_URL` | Read the catalog only from this base, instead of racing the default sources |
 
 ## 📚 The catalog
 

package/lib/client.js

@@ -4437,7 +4437,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 543,
+						"line": 568,
 						"column": 9
 					}
 				},
@@ -4455,7 +4455,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 723,
+						"line": 748,
 						"column": 9
 					}
 				},
@@ -4483,7 +4483,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 593,
+						"line": 618,
 						"column": 9
 					}
 				},
@@ -4510,7 +4510,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 712,
+						"line": 737,
 						"column": 3
 					}
 				},
@@ -4528,7 +4528,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 873,
+						"line": 898,
 						"column": 9
 					}
 				},
@@ -4555,7 +4555,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 460,
+						"line": 466,
 						"column": 9
 					}
 				},
@@ -4583,7 +4583,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 815,
+						"line": 840,
 						"column": 9
 					}
 				},
@@ -4610,7 +4610,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 933,
+						"line": 958,
 						"column": 9
 					}
 				},
@@ -4628,7 +4628,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					},
 					sourceLocation: {
 						"file": "packages/dsh-plugin-shop/src/host/index.ts",
-						"line": 917,
+						"line": 942,
 						"column": 9
 					}
 				}
@@ -4895,6 +4895,27 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			return `https://www.npmjs.com/package/${name}`;
 		}
 		/**
+		* One entry's install identity — the value the catalog guarantees unique, and
+		* therefore the only safe React key for a shelf card.
+		*
+		* `name` is NOT unique. The catalog's uniqueness invariant is the install
+		* identity (registry `emit.ts` assertCatalogInvariants): `npm:<name>` for an
+		* npm entry, `github:<repo>#<subdir>` for a repo one — so two GitHub
+		* repositories publishing the same `package.json` name are two legitimate
+		* entries under one name, as are two subpackages of one monorepo. The live
+		* catalog holds 151 such names over 243 entries, five of them cookiecutter
+		* templates that all name themselves `{{PKG_NAME}}`.
+		*
+		* Keying the shelf by name handed React duplicate keys, and React could then
+		* no longer match a card to its DOM node: changing the filter left every
+		* duplicate orphaned on the page — hundreds of stale cards from the previous
+		* category, accumulating with each switch until the tab stopped responding.
+		* This mirrors the registry's identity verbatim; the two must not drift.
+		*/
+		function entryKey(entry) {
+			return entry.source === "npm" ? `npm:${entry.name}` : `github:${entry.repo ?? entry.name}#${entry.subdir ?? ""}`;
+		}
+		/**
 		* One entry's star count from the sidecar, or undefined when it has none.
 		*
 		* The sidecar keys a github entry by its repo full name and an npm entry by
@@ -6435,7 +6456,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 							restart,
 							restartSupported,
 							setEnabled
-						}) }, entry.name)), incremental && visibleCount < filtered.length && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", {
+						}) }, entryKey(entry))), incremental && visibleCount < filtered.length && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", {
 							ref: sentinelRef,
 							className: _dsh_plugin_shop_css_e3675a89_default.cardsSentry,
 							"data-shop-sentry": true,

package/lib/index.js

@@ -7,7 +7,9 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync,
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
 import { z } from "zod";
+import { gunzipSync } from "node:zlib";
 import { JSON_SCHEMA, Type, dump, load } from "js-yaml";
 //#region src/own-version.ts
 /** The shop's own published version, read from the package.json that ships
@@ -19,8 +21,332 @@ import { JSON_SCHEMA, Type, dump, load } from "js-yaml";
 function ownVersion() {
 	return JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
 }
+//#endregion
+//#region src/host/origin.ts
+/** The transport seam under `loadCatalog` (design §3).
+*
+* An origin answers a cheap probe, then serves the pointer and the files the
+* pointer names. HTTP and npm are interchangeable behind it, so every line of
+* cache and validation logic in `catalog.ts` stays transport-blind. */
+/** A failure of the link, not of the content: the wire threw, or answered
+* non-2xx. This is the ONLY class `loadCatalog` retries on another origin.
+* A bad schema, a sha mismatch, or a refused url is an interpretation
+* failure and throws — masking a corrupt origin behind a healthy one is
+* exactly the silent-wrongness this project refuses. */
+var TransportError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "TransportError";
+	}
+};
+/** Resolve the pointer's data URL against the catalog base. An absolute URL —
+* any scheme, or a protocol-relative `//host/...` — would hand the pointer a
+* fetch primitive to arbitrary hosts, so it is refused loudly before any
+* fetch (§9.2). The guard is the resolved origin, not the raw string: WHATWG
+* normalization strips leading whitespace and accepts backslash spellings
+* before the string could be inspected, so only comparing the resolved URL's
+* origin to the base's closes every spelling class. */
+function resolveDataUrl(baseUrl, url) {
+	const resolved = new URL(url, baseUrl);
+	if (resolved.origin !== new URL(baseUrl).origin) throw new Error("catalog data url must be relative to the catalog base");
+	return resolved.href;
+}
+/** The transport this project has always used: a static `v1/` tree. */
+function httpOrigin(baseUrl, fetchImpl) {
+	const id = `http:${baseUrl}`;
+	return {
+		id,
+		async probe(signal) {
+			let response;
+			try {
+				response = await fetchImpl(new URL("index.json", baseUrl).href, { signal });
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new TransportError(`catalog pointer fetch failed for ${id}: ${detail}`, { cause: error });
+			}
+			if (!response.ok) throw new TransportError(`catalog pointer returned ${response.status} for ${id}`);
+			const pointerText = await response.text();
+			return {
+				id,
+				pointer: async () => pointerText,
+				file: async (url) => {
+					const resolved = resolveDataUrl(baseUrl, url);
+					let dataResponse;
+					try {
+						dataResponse = await fetchImpl(resolved);
+					} catch (error) {
+						const detail = error instanceof Error ? error.message : String(error);
+						throw new TransportError(`catalog data fetch failed for ${id}: ${detail}`, { cause: error });
+					}
+					if (!dataResponse.ok) throw new TransportError(`catalog data returned ${dataResponse.status} for ${id}`);
+					return dataResponse.text();
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/host/tar.ts
+/** A read-only ustar parser: the npm transport's only way into a tarball.
+*
+* Pure — bytes in, a path-to-bytes map out. It handles exactly what `npm
+* pack` emits and refuses everything else loudly, because the alternative to
+* a small strict reader is a fourth runtime dependency (design §4). */
+/** Bytes up to the first NUL, as ASCII. Tar pads its fixed-width text fields
+* with NULs, so a plain toString would carry them into the path. */
+function cstring(field) {
+	const end = field.indexOf(0);
+	return field.subarray(0, end === -1 ? field.length : end).toString("ascii");
+}
+/** Tar sizes are octal text, NUL- or space-terminated. An unparseable size
+* would desynchronise every subsequent header, so it throws rather than
+* guessing zero. */
+function parseOctal(field) {
+	const text = cstring(field).trim();
+	if (text === "") return 0;
+	const value = Number.parseInt(text, 8);
+	if (!Number.isInteger(value) || value < 0) throw new Error(`tar: unparseable size field ${JSON.stringify(text)}`);
+	return value;
+}
+/** `..` in any position, or a leading `/`, would let an archive write outside
+* the directory it claims. Nothing we publish contains either, so a tarball
+* that does is hostile or corrupt — refuse it rather than filter it. */
+function assertContained(path) {
+	if (path.startsWith("/") || path.split("/").includes("..")) throw new Error(`tar: ${JSON.stringify(path)} escapes the archive root`);
+	return path;
+}
+/**
+* Parse an uncompressed tar archive into path → bytes.
+*
+* Directory entries and every non-regular type (symlinks, pax and GNU
+* extension headers) are skipped: npm packs regular files under `package/`,
+* and a catalog tarball that needs anything else is not one we published.
+*/
+function readTar(buffer) {
+	const files = /* @__PURE__ */ new Map();
+	let offset = 0;
+	while (offset + 512 <= buffer.length) {
+		const header = buffer.subarray(offset, offset + 512);
+		if (header.every((byte) => byte === 0)) break;
+		const name = cstring(header.subarray(0, 100));
+		const prefix = cstring(header.subarray(345, 500));
+		const size = parseOctal(header.subarray(124, 136));
+		const typeflag = String.fromCharCode(header[156] ?? 0);
+		const path = prefix === "" ? name : `${prefix}/${name}`;
+		offset += 512;
+		if (typeflag === "0" || typeflag === "\0") files.set(assertContained(path), buffer.subarray(offset, offset + size));
+		offset += Math.ceil(size / 512) * 512;
+	}
+	return files;
+}
+//#endregion
+//#region src/host/npm-origin.ts
+/** The npm transport (design §2, §3): the catalog as a package.
+*
+* Shell — this and `origin.ts`'s fetch half are the only places the catalog
+* loader touches the network. The payoff is measured, not assumed: the same
+* bytes reach a China-side machine at 12.53 MB/s from npmmirror against
+* 0.03 MB/s from GitHub Pages. */
+/** The abbreviated `latest` manifest. Non-strict: a registry may add keys,
+* and stripping them is what keeps an old host working against a new one. */
+const latestSchema = z.object({
+	version: z.string(),
+	dist: z.object({
+		tarball: z.string(),
+		integrity: z.string()
+	})
+});
+/** Where the published package keeps the catalog tree (design §2). */
+const PACKAGE_ROOT = "package/v1/";
+/** Verify tarball bytes against npm's own Subresource-Integrity string.
+* `dist.integrity` may carry several space-separated digests; npm publishes
+* one, and the first is the one we check. */
+function verifyIntegrity(bytes, integrity, registryUrl) {
+	const first = integrity.trim().split(/\s+/)[0] ?? "";
+	const dash = first.indexOf("-");
+	const algorithm = dash === -1 ? "" : first.slice(0, dash);
+	const expected = dash === -1 ? "" : first.slice(dash + 1);
+	if (algorithm !== "sha512" && algorithm !== "sha256") throw new TransportError(`npm origin ${registryUrl}: unsupported dist.integrity algorithm ${JSON.stringify(algorithm)}`);
+	if (createHash(algorithm).update(bytes).digest("base64") !== expected) throw new Error(`npm origin ${registryUrl}: tarball failed dist.integrity check (${algorithm})`);
+}
+/** Normalise to a trailing slash so relative `URL` resolution against a
+* registry that carries a path — every corporate registry, e.g.
+* `https://artifactory.corp/api/npm/npm-repo` — keeps that path instead of
+* eating its last segment; a host-root registry's trailing slash is already
+* a no-op either way. Exported so `catalog.ts`'s dedupe compares against the
+* same normalised form `npmOrigin` races on. */
+function normalizeRegistryUrl(url) {
+	return url.endsWith("/") ? url : `${url}/`;
+}
+/**
+* An origin that reads the catalog out of `<registryUrl>`'s copy of
+* `<packageName>`.
+*
+* The probe is the abbreviated `latest` manifest — 13.5 KB against the live
+* registry — so the race is decided without downloading anything large. The
+* tarball is fetched lazily on the first `pointer()` or `file()` and kept on
+* the handle, so one origin download serves the whole load.
+*/
+function npmOrigin(rawRegistryUrl, packageName, fetchImpl) {
+	const registryUrl = normalizeRegistryUrl(rawRegistryUrl);
+	const id = `npm:${registryUrl}`;
+	return {
+		id,
+		async probe(signal) {
+			let url;
+			try {
+				url = new URL(`${encodeURIComponent(packageName)}/latest`, registryUrl).href;
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new TransportError(`npm origin ${registryUrl} is not a usable registry url: ${detail}`, { cause: error });
+			}
+			let response;
+			try {
+				response = await fetchImpl(url, { signal });
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new TransportError(`npm origin ${registryUrl} probe failed: ${detail}`, { cause: error });
+			}
+			if (!response.ok) throw new TransportError(`npm origin ${registryUrl} returned ${response.status}`);
+			let manifest;
+			try {
+				manifest = latestSchema.parse(await response.json());
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new TransportError(`npm origin ${registryUrl} returned an unparsable manifest: ${detail}`, { cause: error });
+			}
+			let files = null;
+			const load = async () => {
+				if (files !== null) return files;
+				let tarballUrl;
+				try {
+					tarballUrl = new URL(manifest.dist.tarball);
+				} catch (error) {
+					const detail = error instanceof Error ? error.message : String(error);
+					throw new TransportError(`npm origin ${registryUrl}: dist.tarball is not a valid url: ${detail}`, { cause: error });
+				}
+				if (tarballUrl.origin !== new URL(registryUrl).origin) throw new TransportError(`npm origin ${registryUrl}: dist.tarball host ${tarballUrl.origin} is not the registry's`);
+				let tarballResponse;
+				try {
+					tarballResponse = await fetchImpl(tarballUrl.href);
+				} catch (error) {
+					const detail = error instanceof Error ? error.message : String(error);
+					throw new TransportError(`npm origin ${registryUrl} tarball fetch failed: ${detail}`, { cause: error });
+				}
+				if (!tarballResponse.ok) throw new TransportError(`npm origin ${registryUrl} tarball returned ${tarballResponse.status}`);
+				let bytes;
+				try {
+					bytes = Buffer.from(await tarballResponse.arrayBuffer());
+				} catch (error) {
+					const detail = error instanceof Error ? error.message : String(error);
+					throw new TransportError(`npm origin ${registryUrl} tarball body read failed: ${detail}`, { cause: error });
+				}
+				verifyIntegrity(bytes, manifest.dist.integrity, registryUrl);
+				let parsed;
+				try {
+					parsed = readTar(gunzipSync(bytes));
+				} catch (error) {
+					const detail = error instanceof Error ? error.message : String(error);
+					throw new TransportError(`npm origin ${registryUrl} served an unparsable tarball: ${detail}`, { cause: error });
+				}
+				files = parsed;
+				return files;
+			};
+			const read = async (name) => {
+				const entry = (await load()).get(`${PACKAGE_ROOT}${name}`);
+				if (entry === void 0) throw new TransportError(`npm origin ${registryUrl}: ${name} is not in the catalog package`);
+				return entry.toString("utf8");
+			};
+			return {
+				id,
+				pointer: async () => read("index.json"),
+				file: async (url) => {
+					if (url.includes("/") || url.startsWith(".")) throw new Error(`npm origin ${registryUrl}: ${JSON.stringify(url)} must be a plain file name`);
+					return read(url);
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/host/race.ts
+/**
+* Yield each promise's outcome as it settles, tagged with its argument index.
+*
+* Deliberately NOT an `async function*`. Two properties depend on that:
+*
+* 1. **Handlers attach synchronously, at call time.** An async generator's
+*    body does not run until its first `next()`, so wiring the handlers
+*    inside one would leave a rejection unhandled for as long as the caller
+*    waits before iterating — which crashes the process under Node's default
+*    unhandled-rejection policy.
+* 2. **Order is recorded when each promise settles**, not when a consumer
+*    asks. Re-racing the survivors on every turn tie-breaks on argument
+*    order instead: `Promise.race` over promises that are ALREADY settled
+*    resolves with the first in iteration order, not the first to have
+*    settled — and a consumer doing any work between yields, which is
+*    exactly this module's use case, is what lets two settle inside one turn.
+*/
+function inCompletionOrder(promises) {
+	const settled = [];
+	let wake = null;
+	const record = (outcome) => {
+		settled.push(outcome);
+		const resume = wake;
+		wake = null;
+		resume?.();
+	};
+	for (const [index, promise] of promises.entries()) promise.then((value) => {
+		record({
+			index,
+			value
+		});
+	}, (reason) => {
+		record({
+			index,
+			reason
+		});
+	});
+	return (async function* () {
+		for (let delivered = 0; delivered < promises.length; delivered += 1) {
+			if (settled.length === delivered) await new Promise((resolve) => {
+				wake = resolve;
+			});
+			const outcome = settled[delivered];
+			if (outcome === void 0) throw new Error("inCompletionOrder: woke with nothing settled");
+			yield outcome;
+		}
+	})();
+}
 /** A cached catalog younger than this is served without touching the network. */
 const FRESH_MS = 3e5;
+/** How long a probe may take before the race gives up on that origin. Long
+* enough for a slow but working link, short enough that a black-holed origin
+* does not hold the shelf closed. */
+const PROBE_TIMEOUT_MS = 1e4;
+/** How long the committed origin has to produce its pointer. `httpOrigin`
+* answers instantly — its probe already fetched the bytes — but `npmOrigin`
+* downloads its tarball here, so this is a bulk-transfer budget, not a probe
+* one. Without it a winner that stalls mid-body parks the race forever while
+* healthy origins sit settled and unread, which is the exact failure the race
+* exists to prevent. Generous against every measured npm origin (12.53 MB/s
+* mirror -> 0.12 s for 1.5 MB; npmjs direct 1.99 MB/s -> 0.75 s). */
+const COMMIT_TIMEOUT_MS = 3e4;
+/** Reject with a TransportError if `work` outlives `COMMIT_TIMEOUT_MS`. The
+* underlying fetch is left to finish or fail on its own and its result is
+* discarded: aborting it would need a signal threaded through OriginHandle,
+* and a stalled origin we have already abandoned costs nothing but its own
+* socket. */
+async function withCommitTimeout(work, id) {
+	let timer;
+	try {
+		return await Promise.race([work, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(new TransportError(`${id} did not produce a pointer within ${COMMIT_TIMEOUT_MS} ms`)), COMMIT_TIMEOUT_MS);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
 /** Records when the loader itself wrote the cache; the pointer's `builtAt` is
 * the catalog's build time, not the cache's fetch time. */
 const META_FILE = "index.meta.json";
@@ -122,18 +448,6 @@ const nodeFs$1 = {
 		writeFileSync(path, data);
 	}
 };
-/** Resolve the pointer's data URL against the catalog base. An absolute URL —
-* any scheme, or a protocol-relative `//host/...` — would hand the pointer a
-* fetch primitive to arbitrary hosts, so it is refused loudly before any
-* fetch (§9.2). The guard is the resolved origin, not the raw string: WHATWG
-* normalization strips leading whitespace and accepts backslash spellings
-* before the string could be inspected, so only comparing the resolved URL's
-* origin to the base's closes every spelling class. */
-function resolveDataUrl(baseUrl, url) {
-	const resolved = new URL(url, baseUrl);
-	if (resolved.origin !== new URL(baseUrl).origin) throw new Error("catalog data url must be relative to the catalog base");
-	return resolved.href;
-}
 /** Read and verify a cached/fetched stars sidecar; ANY irregularity degrades
 * to an empty map — stars are advisory (spec §5). */
 function parseStarsText(text) {
@@ -158,7 +472,10 @@ function parseStarsText(text) {
 * included, degrades to no stars (spec §5).
 */
 async function loadCatalog(options) {
-	const { baseUrl, cacheDir, refresh = false, fetchImpl = fetch, now = () => /* @__PURE__ */ new Date(), fsImpl = nodeFs$1 } = options;
+	const { cacheDir, refresh = false, fetchImpl = fetch, now = () => /* @__PURE__ */ new Date(), fsImpl = nodeFs$1 } = options;
+	if (options.baseUrl === void 0 === (options.origins === void 0)) throw new Error("loadCatalog: exactly one of baseUrl or origins is required");
+	const originList = options.origins ?? [httpOrigin(options.baseUrl, fetchImpl)];
+	if (originList.length === 0) throw new Error("loadCatalog: no origins");
 	const indexPath = join(cacheDir, "index.json");
 	const metaPath = join(cacheDir, META_FILE);
 	/** The timestamp freshness is measured from: the sidecar's fetch time when
@@ -211,34 +528,41 @@ async function loadCatalog(options) {
 			};
 		}
 	}
-	let pointerText;
-	try {
-		const response = await fetchImpl(new URL("index.json", baseUrl).href);
-		if (!response.ok) throw new Error(`catalog pointer returned ${response.status}`);
-		pointerText = await response.text();
-	} catch (error) {
+	const cachedOrThrow = (error) => {
 		const cached = readCached();
 		if (cached !== null) return {
 			snapshot: cached,
 			stale: true
 		};
 		throw error;
+	};
+	let handle = null;
+	let pointerText = "";
+	let lastTransportError = new TransportError("no catalog origin was reachable");
+	for await (const settled of inCompletionOrder(originList.map((origin) => origin.probe(AbortSignal.timeout(PROBE_TIMEOUT_MS))))) {
+		if (!("value" in settled)) {
+			if (!(settled.reason instanceof TransportError)) throw settled.reason;
+			lastTransportError = settled.reason;
+			continue;
+		}
+		try {
+			pointerText = await withCommitTimeout(settled.value.pointer(), settled.value.id);
+			handle = settled.value;
+			break;
+		} catch (error) {
+			if (!(error instanceof TransportError)) throw error;
+			lastTransportError = error;
+		}
 	}
+	if (handle === null) return cachedOrThrow(lastTransportError);
 	const pointer = pointerSchema.parse(JSON.parse(pointerText));
 	if (pointer.schemaVersion > 6) throw new Error(`catalog schemaVersion ${pointer.schemaVersion} is newer than this build supports (6)`);
-	const dataUrl = resolveDataUrl(baseUrl, pointer.plugins.url);
 	let dataText;
 	try {
-		const dataResponse = await fetchImpl(dataUrl);
-		if (!dataResponse.ok) throw new Error(`catalog data returned ${dataResponse.status}`);
-		dataText = await dataResponse.text();
+		dataText = await handle.file(pointer.plugins.url);
 	} catch (error) {
-		const cached = readCached();
-		if (cached !== null) return {
-			snapshot: cached,
-			stale: true
-		};
-		throw error;
+		if (!(error instanceof TransportError)) throw error;
+		return cachedOrThrow(error);
 	}
 	const actual = createHash("sha256").update(dataText).digest("hex");
 	if (actual !== pointer.plugins.sha256) throw new Error(`catalog data failed integrity check: expected ${pointer.plugins.sha256}, got ${actual}`);
@@ -247,13 +571,10 @@ async function loadCatalog(options) {
 	validateEntryCoherence(data.plugins);
 	let stars = {};
 	if (pointer.stars !== void 0) try {
-		const starsResponse = await fetchImpl(resolveDataUrl(baseUrl, pointer.stars.url));
-		if (starsResponse.ok) {
-			const starsText = await starsResponse.text();
-			if (createHash("sha256").update(starsText).digest("hex") === pointer.stars.sha256) {
-				stars = parseStarsText(starsText);
-				fsImpl.write(join(cacheDir, basename(pointer.stars.url)), starsText);
-			}
+		const starsText = await handle.file(pointer.stars.url);
+		if (createHash("sha256").update(starsText).digest("hex") === pointer.stars.sha256) {
+			stars = parseStarsText(starsText);
+			fsImpl.write(join(cacheDir, basename(pointer.stars.url)), starsText);
 		}
 	} catch {}
 	const snapshot = {
@@ -271,6 +592,76 @@ async function loadCatalog(options) {
 		stale: false
 	};
 }
+/** The npm package carrying the same `v1/` tree (design §2). */
+const CATALOG_PACKAGE = "dsh-plugin-shop-catalog";
+/** Registries raced by default: the domestic mirror first for legibility —
+* the race, not the order, decides the winner. */
+const DEFAULT_REGISTRIES = ["https://registry.npmmirror.com/", "https://registry.npmjs.org/"];
+/**
+* The origins to race for this installation (design §3).
+*
+* @param catalogUrl - the row's configured base.
+* @param npmRegistry - the user's own registry from `~/.npmrc`, or null.
+*/
+function catalogOrigins(catalogUrl, fetchImpl, npmRegistry) {
+	if (catalogUrl !== "https://LivXue.github.io/dsh-plugin-shop/v1/") return [httpOrigin(catalogUrl, fetchImpl)];
+	const registries = [...DEFAULT_REGISTRIES];
+	const normalizedNpmRegistry = npmRegistry === null ? null : normalizeRegistryUrl(npmRegistry);
+	if (normalizedNpmRegistry !== null && !registries.includes(normalizedNpmRegistry)) registries.unshift(normalizedNpmRegistry);
+	return [...registries.map((registry) => npmOrigin(registry, CATALOG_PACKAGE, fetchImpl)), httpOrigin(catalogUrl, fetchImpl)];
+}
+//#endregion
+//#region src/host/npmrc.ts
+/** The user's configured npm registry, if they have one (design §3).
+*
+* Pure: the caller injects the read. This is a deliberately partial reading
+* of npm's config resolution — only the user-level `registry=` line — and
+* that is safe precisely because the origin list is raced: a registry we
+* guess wrong about loses a 400-byte request and nothing else.
+*
+* That property only holds for a value that is actually a URL, which is why
+* the value is VALIDATED here rather than left to the caller. `npmOrigin`
+* addresses its probe with `new URL(<pkg>/latest, registryUrl)`, which
+* throws a raw `TypeError` — not a `TransportError` — for anything that is
+* not an absolute URL, and `catalog.ts`'s race loop rethrows everything that
+* is not a `TransportError`. An unvalidated `registry=` line would therefore
+* fail the WHOLE load with npmmirror, npmjs and Pages all healthy and no
+* cache fallback: the opposite of the stated property. Not a hypothetical
+* shape either — `registry=${NPM_REGISTRY}/` is npm's own documented config
+* expansion, it works perfectly for npm, and a reader that does not expand
+* it captures the literal. */
+/** The value, if it is an absolute `http:`/`https:` URL; otherwise null.
+*
+* Both halves earn their place. The parse rejects a bare host, a relative
+* path, and an unexpanded `${VAR}`. The scheme check then rejects what
+* `new URL` happily accepts but the raced origins cannot fetch from —
+* `file:` and `ftp:` parse fine and are not registries a `fetch` can read.
+* The raw string is returned rather than the parsed href, so the value the
+* user wrote is what reaches `normalizeRegistryUrl` and the origin id. */
+function asRegistryUrl(value) {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return null;
+	}
+	return parsed.protocol === "http:" || parsed.protocol === "https:" ? value : null;
+}
+/**
+* @param readFile - returns the file's text, or null when it does not exist.
+* @param home - the user's home directory.
+*/
+function npmrcRegistry(readFile, home) {
+	const text = readFile(join(home, ".npmrc"));
+	if (text === null) return null;
+	for (const line of text.split("\n")) {
+		const value = /^\s*registry\s*=\s*(\S+)\s*$/.exec(line)?.[1];
+		if (value === void 0) continue;
+		const url = asRegistryUrl(value);
+		if (url !== null) return url;
+	}
+	return null;
+}
 //#endregion
 //#region src/host/install.ts
 /**
@@ -1334,6 +1725,9 @@ let ShopGateway = (() => {
 		/** The install gate runs against the last loaded snapshot, never a fresh
 		* fetch per request (§7.2: the Host's cached snapshot is the truth). */
 		lastSnapshot = null;
+		/** The origin list built for the last-seen `catalogUrl`, memoised so the
+		* user's npmrc is read at most once per gateway (see `originsFor`). */
+		originCache = null;
 		/** The incompatibility map already computed for `lastSnapshot`, keyed by
 		* that snapshot's own object identity. Design §3 asks for the verdict
 		* once per loaded snapshot, not once per RPC call: `loadCatalog` serves
@@ -1520,6 +1914,25 @@ let ShopGateway = (() => {
 				cacheDir
 			};
 		}
+		/** The origins to race for this row's catalog. Read once per gateway: the
+		* user's npmrc does not change under a running dsh, and re-reading it on
+		* every catalog call would put a filesystem read on the hot path. */
+		originsFor(catalogUrl) {
+			if (this.originCache?.catalogUrl === catalogUrl) return this.originCache.origins;
+			const registry = npmrcRegistry((path) => {
+				try {
+					return readFileSync(path, "utf8");
+				} catch {
+					return null;
+				}
+			}, homedir());
+			const origins = catalogOrigins(catalogUrl, fetch, registry);
+			this.originCache = {
+				catalogUrl,
+				origins
+			};
+			return origins;
+		}
 		/** The explicit restart override. Only the row's `config:` sub-object is
 		* passed to a plugin — a top-level `allowRestart:` beside `name:` would be
 		* silently ignored by the loader (dsh-market README, #227). */
@@ -1531,7 +1944,7 @@ let ShopGateway = (() => {
 		async catalog(args) {
 			const { catalogUrl, cacheDir } = this.rowConfig();
 			const { snapshot, stale } = await (this.options.loadCatalog ?? loadCatalog)({
-				baseUrl: catalogUrl,
+				origins: this.originsFor(catalogUrl),
 				cacheDir,
 				refresh: args?.refresh ?? false
 			});
@@ -1569,7 +1982,7 @@ let ShopGateway = (() => {
 			if (this.lastSnapshot === null) {
 				const { catalogUrl, cacheDir } = this.rowConfig();
 				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					baseUrl: catalogUrl,
+					origins: this.originsFor(catalogUrl),
 					cacheDir
 				});
 				this.lastSnapshot = snapshot;
@@ -1677,7 +2090,7 @@ let ShopGateway = (() => {
 			if (this.lastSnapshot === null) {
 				const { catalogUrl, cacheDir } = this.rowConfig();
 				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					baseUrl: catalogUrl,
+					origins: this.originsFor(catalogUrl),
 					cacheDir
 				});
 				this.lastSnapshot = snapshot;
@@ -1755,7 +2168,7 @@ let ShopGateway = (() => {
 			if (this.lastSnapshot === null) {
 				const { catalogUrl, cacheDir } = this.rowConfig();
 				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
-					baseUrl: catalogUrl,
+					origins: this.originsFor(catalogUrl),
 					cacheDir
 				});
 				this.lastSnapshot = snapshot;

package/lib/typert.host.js

@@ -154,7 +154,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopCatalogResult',
         schema: dsh_plugin_shop_shop_catalog_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":543,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":568,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installed',
@@ -169,7 +169,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop#shop/installed:result',
         schema: dsh_plugin_shop_shop_installed_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":723,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":748,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStart',
@@ -195,7 +195,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopInstallResult',
         schema: dsh_plugin_shop_shop_installStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":593,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":618,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStatus',
@@ -220,7 +220,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopInstallStatusResult',
         schema: dsh_plugin_shop_shop_installStatus_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":712,"column":3},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":737,"column":3},
     },
     {
       id: 'dsh-plugin-shop#shop/restart',
@@ -235,7 +235,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopRestartResult',
         schema: dsh_plugin_shop_shop_restart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":873,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":898,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/setEnabled',
@@ -260,7 +260,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopSetEnabledResult',
         schema: dsh_plugin_shop_shop_setEnabled_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":460,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":466,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/uninstallStart',
@@ -286,7 +286,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopUninstallResult',
         schema: dsh_plugin_shop_shop_uninstallStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":815,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":840,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/updateStart',
@@ -311,7 +311,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopUpdateResult',
         schema: dsh_plugin_shop_shop_updateStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":933,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":958,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/version',
@@ -326,7 +326,7 @@ export const TYPERT = {
         typeSymbol: 'dsh-plugin-shop/types#ShopVersionResult',
         schema: dsh_plugin_shop_shop_version_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":917,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":942,"column":9},
     },
   ],
   model: {

package/lib/typert.remote-client.js

@@ -151,7 +151,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopCatalogResult',
         schema: dsh_plugin_shop_shop_catalog_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":543,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":568,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installed',
@@ -166,7 +166,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop#shop/installed:result',
         schema: dsh_plugin_shop_shop_installed_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":723,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":748,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStart',
@@ -192,7 +192,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopInstallResult',
         schema: dsh_plugin_shop_shop_installStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":593,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":618,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStatus',
@@ -217,7 +217,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopInstallStatusResult',
         schema: dsh_plugin_shop_shop_installStatus_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":712,"column":3},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":737,"column":3},
     },
     {
       id: 'dsh-plugin-shop#shop/restart',
@@ -232,7 +232,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopRestartResult',
         schema: dsh_plugin_shop_shop_restart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":873,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":898,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/setEnabled',
@@ -257,7 +257,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopSetEnabledResult',
         schema: dsh_plugin_shop_shop_setEnabled_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":460,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":466,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/uninstallStart',
@@ -283,7 +283,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopUninstallResult',
         schema: dsh_plugin_shop_shop_uninstallStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":815,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":840,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/updateStart',
@@ -308,7 +308,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopUpdateResult',
         schema: dsh_plugin_shop_shop_updateStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":933,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":958,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/version',
@@ -323,7 +323,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: 'dsh-plugin-shop/types#ShopVersionResult',
         schema: dsh_plugin_shop_shop_version_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":917,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":942,"column":9},
     },
   ],
 }

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

@@ -182,6 +182,25 @@ export declare function hasGithubHome(entry: CatalogEntry): boolean;
  */
 export declare function authorOf(entry: CatalogEntry): string | null;
 export declare function npmPageUrl(entry: CatalogEntry): string | null;
+/**
+ * One entry's install identity — the value the catalog guarantees unique, and
+ * therefore the only safe React key for a shelf card.
+ *
+ * `name` is NOT unique. The catalog's uniqueness invariant is the install
+ * identity (registry `emit.ts` assertCatalogInvariants): `npm:<name>` for an
+ * npm entry, `github:<repo>#<subdir>` for a repo one — so two GitHub
+ * repositories publishing the same `package.json` name are two legitimate
+ * entries under one name, as are two subpackages of one monorepo. The live
+ * catalog holds 151 such names over 243 entries, five of them cookiecutter
+ * templates that all name themselves `{{PKG_NAME}}`.
+ *
+ * Keying the shelf by name handed React duplicate keys, and React could then
+ * no longer match a card to its DOM node: changing the filter left every
+ * duplicate orphaned on the page — hundreds of stale cards from the previous
+ * category, accumulating with each switch until the tab stopped responding.
+ * This mirrors the registry's identity verbatim; the two must not drift.
+ */
+export declare function entryKey(entry: CatalogEntry): string;
 /**
  * One entry's star count from the sidecar, or undefined when it has none.
  *

package/lib/types/host/catalog.d.ts

@@ -1,4 +1,5 @@
 /** Catalog fetch, verification, and disk cache — the Host's only network path. */
+import { type CatalogOrigin } from './origin.ts';
 import type { CatalogEntry, DeniedEntry } from './types.ts';
 /** Highest schemaVersion this build understands; a higher one is refused (§10).
  * 3 adds `source` and repo entries (github install channel); 4 adds `subdir`
@@ -27,7 +28,11 @@ export interface CatalogFs {
     write: (path: string, data: string) => void;
 }
 export interface LoadCatalogOptions {
-    baseUrl: string;
+    /** A single HTTP origin — the explicit-override spelling. Mutually
+     * exclusive with `origins`; exactly one must be given. */
+    baseUrl?: string;
+    /** Origins to race (design §3). */
+    origins?: CatalogOrigin[];
     cacheDir: string;
     refresh?: boolean;
     fetchImpl?: typeof fetch;
@@ -46,3 +51,16 @@ export interface LoadCatalogOptions {
  * included, degrades to no stars (spec §5).
  */
 export declare function loadCatalog(options: LoadCatalogOptions): Promise<CatalogResult>;
+/** The catalog base the shipped `cordis.patch.yml` names. A row carrying
+ * exactly this value expresses no preference, so the loader races its
+ * defaults; anything else is a deliberate override and is used alone. */
+export declare const DEFAULT_CATALOG_URL = "https://LivXue.github.io/dsh-plugin-shop/v1/";
+/** The npm package carrying the same `v1/` tree (design §2). */
+export declare const CATALOG_PACKAGE = "dsh-plugin-shop-catalog";
+/**
+ * The origins to race for this installation (design §3).
+ *
+ * @param catalogUrl - the row's configured base.
+ * @param npmRegistry - the user's own registry from `~/.npmrc`, or null.
+ */
+export declare function catalogOrigins(catalogUrl: string, fetchImpl: typeof fetch, npmRegistry: string | null): CatalogOrigin[];

package/lib/types/host/index.d.ts

@@ -238,6 +238,9 @@ export declare class ShopGateway extends TypertRemoteService {
     /** The install gate runs against the last loaded snapshot, never a fresh
      * fetch per request (§7.2: the Host's cached snapshot is the truth). */
     private lastSnapshot;
+    /** The origin list built for the last-seen `catalogUrl`, memoised so the
+     * user's npmrc is read at most once per gateway (see `originsFor`). */
+    private originCache;
     /** The incompatibility map already computed for `lastSnapshot`, keyed by
      * that snapshot's own object identity. Design §3 asks for the verdict
      * once per loaded snapshot, not once per RPC call: `loadCatalog` serves
@@ -294,6 +297,10 @@ export declare class ShopGateway extends TypertRemoteService {
         enabled: boolean;
     }): Promise<ShopSetEnabledResult>;
     private rowConfig;
+    /** The origins to race for this row's catalog. Read once per gateway: the
+     * user's npmrc does not change under a running dsh, and re-reading it on
+     * every catalog call would put a filesystem read on the hot path. */
+    private originsFor;
     /** The explicit restart override. Only the row's `config:` sub-object is
      * passed to a plugin — a top-level `allowRestart:` beside `name:` would be
      * silently ignored by the loader (dsh-market README, #227). */

package/lib/types/host/npm-origin.d.ts

@@ -0,0 +1,24 @@
+/** The npm transport (design §2, §3): the catalog as a package.
+ *
+ * Shell — this and `origin.ts`'s fetch half are the only places the catalog
+ * loader touches the network. The payoff is measured, not assumed: the same
+ * bytes reach a China-side machine at 12.53 MB/s from npmmirror against
+ * 0.03 MB/s from GitHub Pages. */
+import { type CatalogOrigin } from './origin.ts';
+/** Normalise to a trailing slash so relative `URL` resolution against a
+ * registry that carries a path — every corporate registry, e.g.
+ * `https://artifactory.corp/api/npm/npm-repo` — keeps that path instead of
+ * eating its last segment; a host-root registry's trailing slash is already
+ * a no-op either way. Exported so `catalog.ts`'s dedupe compares against the
+ * same normalised form `npmOrigin` races on. */
+export declare function normalizeRegistryUrl(url: string): string;
+/**
+ * An origin that reads the catalog out of `<registryUrl>`'s copy of
+ * `<packageName>`.
+ *
+ * The probe is the abbreviated `latest` manifest — 13.5 KB against the live
+ * registry — so the race is decided without downloading anything large. The
+ * tarball is fetched lazily on the first `pointer()` or `file()` and kept on
+ * the handle, so one origin download serves the whole load.
+ */
+export declare function npmOrigin(rawRegistryUrl: string, packageName: string, fetchImpl: typeof fetch): CatalogOrigin;

package/lib/types/host/npmrc.d.ts

@@ -0,0 +1,23 @@
+/** The user's configured npm registry, if they have one (design §3).
+ *
+ * Pure: the caller injects the read. This is a deliberately partial reading
+ * of npm's config resolution — only the user-level `registry=` line — and
+ * that is safe precisely because the origin list is raced: a registry we
+ * guess wrong about loses a 400-byte request and nothing else.
+ *
+ * That property only holds for a value that is actually a URL, which is why
+ * the value is VALIDATED here rather than left to the caller. `npmOrigin`
+ * addresses its probe with `new URL(<pkg>/latest, registryUrl)`, which
+ * throws a raw `TypeError` — not a `TransportError` — for anything that is
+ * not an absolute URL, and `catalog.ts`'s race loop rethrows everything that
+ * is not a `TransportError`. An unvalidated `registry=` line would therefore
+ * fail the WHOLE load with npmmirror, npmjs and Pages all healthy and no
+ * cache fallback: the opposite of the stated property. Not a hypothetical
+ * shape either — `registry=${NPM_REGISTRY}/` is npm's own documented config
+ * expansion, it works perfectly for npm, and a reader that does not expand
+ * it captures the literal. */
+/**
+ * @param readFile - returns the file's text, or null when it does not exist.
+ * @param home - the user's home directory.
+ */
+export declare function npmrcRegistry(readFile: (path: string) => string | null, home: string): string | null;

package/lib/types/host/origin.d.ts

@@ -0,0 +1,40 @@
+/** The transport seam under `loadCatalog` (design §3).
+ *
+ * An origin answers a cheap probe, then serves the pointer and the files the
+ * pointer names. HTTP and npm are interchangeable behind it, so every line of
+ * cache and validation logic in `catalog.ts` stays transport-blind. */
+/** A failure of the link, not of the content: the wire threw, or answered
+ * non-2xx. This is the ONLY class `loadCatalog` retries on another origin.
+ * A bad schema, a sha mismatch, or a refused url is an interpretation
+ * failure and throws — masking a corrupt origin behind a healthy one is
+ * exactly the silent-wrongness this project refuses. */
+export declare class TransportError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface OriginHandle {
+    readonly id: string;
+    /** The pointer JSON text. Cheap: the probe has already paid for it. */
+    pointer: () => Promise<string>;
+    /** One file named by the pointer, by the pointer's own raw url string.
+     * Callers pass that string verbatim — never a basename, which would strip
+     * a hostile absolute url into a fetchable relative one. */
+    file: (url: string) => Promise<string>;
+}
+export interface CatalogOrigin {
+    readonly id: string;
+    /** Cheap reachability + identity request. Resolving means this origin can
+     * serve; the expensive work happens on the returned handle. */
+    probe: (signal: AbortSignal) => Promise<OriginHandle>;
+}
+/** Resolve the pointer's data URL against the catalog base. An absolute URL —
+ * any scheme, or a protocol-relative `//host/...` — would hand the pointer a
+ * fetch primitive to arbitrary hosts, so it is refused loudly before any
+ * fetch (§9.2). The guard is the resolved origin, not the raw string: WHATWG
+ * normalization strips leading whitespace and accepts backslash spellings
+ * before the string could be inspected, so only comparing the resolved URL's
+ * origin to the base's closes every spelling class. */
+export declare function resolveDataUrl(baseUrl: string, url: string): string;
+/** The transport this project has always used: a static `v1/` tree. */
+export declare function httpOrigin(baseUrl: string, fetchImpl: typeof fetch): CatalogOrigin;

package/lib/types/host/race.d.ts

@@ -0,0 +1,41 @@
+/** Settle a set of promises in the order they finish (design §3).
+ *
+ * Pure and timer-free. `Promise.any` would give only the first success and
+ * discard the rest; the origin race needs the losers too, in order, so a
+ * probe that "won" but then fails to produce a pointer can fall through to
+ * the next-finishing probe instead of failing the whole load — this is how
+ * an npm origin's bulk tarball download, which happens inside `pointer()`,
+ * gets a fall-through on failure.
+ *
+ * That is deliberately narrower than "any bulk fetch falls through to
+ * another origin." This module only ever wraps `probe()` promises; once
+ * `catalog.ts` has committed to a handle and calls `file()` for the data
+ * file, that call happens outside this generator entirely, and a
+ * TransportError there falls back to the disk cache instead (see
+ * `catalog.ts`'s `cachedOrThrow`), never back into a race. Do not "fix"
+ * that path to match this comment — the split is intentional. */
+export type Settled<T> = {
+    index: number;
+    value: T;
+} | {
+    index: number;
+    reason: unknown;
+};
+/**
+ * Yield each promise's outcome as it settles, tagged with its argument index.
+ *
+ * Deliberately NOT an `async function*`. Two properties depend on that:
+ *
+ * 1. **Handlers attach synchronously, at call time.** An async generator's
+ *    body does not run until its first `next()`, so wiring the handlers
+ *    inside one would leave a rejection unhandled for as long as the caller
+ *    waits before iterating — which crashes the process under Node's default
+ *    unhandled-rejection policy.
+ * 2. **Order is recorded when each promise settles**, not when a consumer
+ *    asks. Re-racing the survivors on every turn tie-breaks on argument
+ *    order instead: `Promise.race` over promises that are ALREADY settled
+ *    resolves with the first in iteration order, not the first to have
+ *    settled — and a consumer doing any work between yields, which is
+ *    exactly this module's use case, is what lets two settle inside one turn.
+ */
+export declare function inCompletionOrder<T>(promises: readonly Promise<T>[]): AsyncGenerator<Settled<T>>;

package/lib/types/host/tar.d.ts

@@ -0,0 +1,13 @@
+/** A read-only ustar parser: the npm transport's only way into a tarball.
+ *
+ * Pure — bytes in, a path-to-bytes map out. It handles exactly what `npm
+ * pack` emits and refuses everything else loudly, because the alternative to
+ * a small strict reader is a fourth runtime dependency (design §4). */
+/**
+ * Parse an uncompressed tar archive into path → bytes.
+ *
+ * Directory entries and every non-regular type (symlinks, pax and GNU
+ * extension headers) are skipped: npm packs regular files under `package/`,
+ * and a catalog tarball that needs anything else is not one we published.
+ */
+export declare function readTar(buffer: Buffer): Map<string, Buffer>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-shop",
-  "version": "0.6.0-beta.2",
+  "version": "0.7.0-beta.0",
   "description": "The DeepSeek Harness plugin shop: browse, install, enable, and update dsh plugins from a git-auditable catalog.",
   "repository": {
     "type": "git",