dsh-plugin-shop 0.9.0 → 0.10.0-beta.0

package/lib/typert.host.js

@@ -55,6 +55,7 @@ const dsh_plugin_shop_shop_catalog_result$schema = z.object({
   'installSize': z.union([z.undefined(), z.number()]).optional(),
   'archived': z.union([z.undefined(), z.literal(false), z.literal(true)]).optional(),
   'forked': z.union([z.undefined(), z.literal(false), z.literal(true)]).optional(),
+  'icon': z.union([z.undefined(), z.string()]).optional(),
 })),
   'denied': z.array(z.object({
   'name': z.string(),
@@ -63,6 +64,7 @@ const dsh_plugin_shop_shop_catalog_result$schema = z.object({
 })),
   'notAShop': z.union([z.undefined(), z.array(z.string())]).optional(),
   'stars': z.record(z.string(), z.number()),
+  'icons': z.record(z.string(), z.string()),
   'incompatible': z.record(z.string(), z.array(z.string())),
   'incompatibleHarness': z.record(z.string(), z.object({
   'dsh': z.union([z.undefined(), z.object({
@@ -202,7 +204,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_catalog_result$schema,
         create: () => dsh_plugin_shop_shop_catalog_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1314,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1317,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installed',
@@ -218,7 +220,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_installed_result$schema,
         create: () => dsh_plugin_shop_shop_installed_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1821,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1825,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installedSpecs',
@@ -234,7 +236,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_installedSpecs_result$schema,
         create: () => dsh_plugin_shop_shop_installedSpecs_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1812,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1816,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStart',
@@ -262,7 +264,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_installStart_result$schema,
         create: () => dsh_plugin_shop_shop_installStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1440,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1444,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStatus',
@@ -289,7 +291,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_installStatus_result$schema,
         create: () => dsh_plugin_shop_shop_installStatus_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1788,"column":3},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1792,"column":3},
     },
     {
       id: 'dsh-plugin-shop#shop/restart',
@@ -305,7 +307,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_restart_result$schema,
         create: () => dsh_plugin_shop_shop_restart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2072,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2076,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/setEnabled',
@@ -332,7 +334,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_setEnabled_result$schema,
         create: () => dsh_plugin_shop_shop_setEnabled_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":966,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":969,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/uninstallStart',
@@ -360,7 +362,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_uninstallStart_result$schema,
         create: () => dsh_plugin_shop_shop_uninstallStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1966,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1970,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/updateStart',
@@ -387,7 +389,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_updateStart_result$schema,
         create: () => dsh_plugin_shop_shop_updateStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2179,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2183,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/version',
@@ -403,7 +405,7 @@ export const TYPERT = {
         schema: dsh_plugin_shop_shop_version_result$schema,
         create: () => dsh_plugin_shop_shop_version_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2136,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2140,"column":9},
     },
   ],
   model: {
@@ -500,7 +502,7 @@ export const TYPERT = {
           },
           {
             "name": "CatalogEntry",
-            "declaration": "export interface CatalogEntry {\n    name: string;\n    version: string;\n    integrity: string | null;\n    publishedAt: string | null;\n    repository: string | null;\n    license: string | null;\n    tier: 'verified' | 'verified-stale' | 'community';\n    metadata: 'declared' | 'derived';\n    review?: { reviewedVersion?: string; reviewedCommit?: string; reviewedSha256?: string; repo?: string; reviewer: string; reviewCommit: string; notes: string; };\n    catalog?: CatalogSection;\n    source: 'npm' | 'github';\n    publisher?: string;\n    repo?: string;\n    subdir?: string;\n    tarball?: { url: string; sha256: string; };\n    added?: string;\n    peers?: string[];\n    compatibility?: { dsh?: string; profiles?: string[]; };\n    dshPeers?: Record<string, string>;\n    manifestVersion?: string;\n    unpackedSize?: number;\n    installSize?: number;\n    archived?: boolean;\n    forked?: boolean;\n}"
+            "declaration": "export interface CatalogEntry {\n    name: string;\n    version: string;\n    integrity: string | null;\n    publishedAt: string | null;\n    repository: string | null;\n    license: string | null;\n    tier: 'verified' | 'verified-stale' | 'community';\n    metadata: 'declared' | 'derived';\n    review?: { reviewedVersion?: string; reviewedCommit?: string; reviewedSha256?: string; repo?: string; reviewer: string; reviewCommit: string; notes: string; };\n    catalog?: CatalogSection;\n    source: 'npm' | 'github';\n    publisher?: string;\n    repo?: string;\n    subdir?: string;\n    tarball?: { url: string; sha256: string; };\n    added?: string;\n    peers?: string[];\n    compatibility?: { dsh?: string; profiles?: string[]; };\n    dshPeers?: Record<string, string>;\n    manifestVersion?: string;\n    unpackedSize?: number;\n    installSize?: number;\n    archived?: boolean;\n    forked?: boolean;\n    icon?: string;\n}"
           },
           {
             "name": "CatalogSection",
@@ -552,7 +554,7 @@ export const TYPERT = {
           },
           {
             "name": "ShopCatalogResult",
-            "declaration": "export interface ShopCatalogResult {\n    schemaVersion: number;\n    builtAt: string;\n    stale: boolean;\n    plugins: CatalogEntry[];\n    denied: DeniedEntry[];\n    notAShop?: string[];\n    stars: Record<string, number>;\n    incompatible: Record<string, string[]>;\n    incompatibleHarness: Record<string, HarnessVerdict>;\n}"
+            "declaration": "export interface ShopCatalogResult {\n    schemaVersion: number;\n    builtAt: string;\n    stale: boolean;\n    plugins: CatalogEntry[];\n    denied: DeniedEntry[];\n    notAShop?: string[];\n    stars: Record<string, number>;\n    icons: Record<string, string>;\n    incompatible: Record<string, string[]>;\n    incompatibleHarness: Record<string, HarnessVerdict>;\n}"
           },
           {
             "name": "ShopInstalledEntry",

package/lib/typert.remote-client.js

@@ -55,6 +55,7 @@ const dsh_plugin_shop_shop_catalog_result$schema = z.object({
   'installSize': z.union([z.undefined(), z.number()]).optional(),
   'archived': z.union([z.undefined(), z.literal(false), z.literal(true)]).optional(),
   'forked': z.union([z.undefined(), z.literal(false), z.literal(true)]).optional(),
+  'icon': z.union([z.undefined(), z.string()]).optional(),
 })),
   'denied': z.array(z.object({
   'name': z.string(),
@@ -63,6 +64,7 @@ const dsh_plugin_shop_shop_catalog_result$schema = z.object({
 })),
   'notAShop': z.union([z.undefined(), z.array(z.string())]).optional(),
   'stars': z.record(z.string(), z.number()),
+  'icons': z.record(z.string(), z.string()),
   'incompatible': z.record(z.string(), z.array(z.string())),
   'incompatibleHarness': z.record(z.string(), z.object({
   'dsh': z.union([z.undefined(), z.object({
@@ -199,7 +201,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_catalog_result$schema,
         create: () => dsh_plugin_shop_shop_catalog_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1314,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1317,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installed',
@@ -215,7 +217,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_installed_result$schema,
         create: () => dsh_plugin_shop_shop_installed_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1821,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1825,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installedSpecs',
@@ -231,7 +233,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_installedSpecs_result$schema,
         create: () => dsh_plugin_shop_shop_installedSpecs_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1812,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1816,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStart',
@@ -259,7 +261,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_installStart_result$schema,
         create: () => dsh_plugin_shop_shop_installStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1440,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1444,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/installStatus',
@@ -286,7 +288,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_installStatus_result$schema,
         create: () => dsh_plugin_shop_shop_installStatus_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1788,"column":3},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1792,"column":3},
     },
     {
       id: 'dsh-plugin-shop#shop/restart',
@@ -302,7 +304,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_restart_result$schema,
         create: () => dsh_plugin_shop_shop_restart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2072,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2076,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/setEnabled',
@@ -329,7 +331,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_setEnabled_result$schema,
         create: () => dsh_plugin_shop_shop_setEnabled_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":966,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":969,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/uninstallStart',
@@ -357,7 +359,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_uninstallStart_result$schema,
         create: () => dsh_plugin_shop_shop_uninstallStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1966,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":1970,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/updateStart',
@@ -384,7 +386,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_updateStart_result$schema,
         create: () => dsh_plugin_shop_shop_updateStart_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2179,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2183,"column":9},
     },
     {
       id: 'dsh-plugin-shop#shop/version',
@@ -400,7 +402,7 @@ export const TYPERT_REMOTE = {
         schema: dsh_plugin_shop_shop_version_result$schema,
         create: () => dsh_plugin_shop_shop_version_result$schema,
       },
-      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2136,"column":9},
+      sourceLocation: {"file":"packages/dsh-plugin-shop/src/host/index.ts","line":2140,"column":9},
     },
   ],
 }

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

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+/** The artwork an entry without a usable icon draws: dsh's own default,
+ * `PluginArtworkDefault` from `dsh-client-ui-primitives` (MIT, DeepSeek — see
+ * the dsh repository's LICENSE). Copied rather than imported because
+ * 0.1.5-rc.3 exports nothing this build could borrow at run time.
+ *
+ * A constant data URL drawn through an `<img>`, not inline markup: the SVG
+ * carries a gradient addressed by id, so thousands of inline copies would each
+ * need one, while an image document is its own namespace and needs none
+ * (design 2026-10-23-shop-plugin-icons §8.1). The id inside this string is
+ * fixed for the same reason.
+ */
+export declare const DEFAULT_ICON_DATA_URL = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzYiIGhlaWdodD0iMzYiIHZpZXdCb3g9IjAgMCAzNiAzNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMjQuNjI5NCA4LjYzNjk2QzI2LjI4NjIgOC42MzcwNSAyNy42Mjk0IDkuOTgwMTYgMjcuNjI5NCAxMS42MzdWMTIuNzgyNUMyNy42MjkyIDE0LjQzOTEgMjYuMjg2MSAxNS43ODI0IDI0LjYyOTQgMTUuNzgyNUgyMy40ODM5QzIyLjY1MTkgMTUuNzgyNSAyMS41NDU0IDE2LjM0NTkgMjEuNTQ1NCAxNy4xNzc4VjE4LjE1NzNDMjEuNTQ1NCAxOC43NzU3IDIyLjIxNiAxOS4xOTY2IDIyLjgzNDUgMTkuMTk2NUgyNC42Mjk0QzI2LjI4NjEgMTkuMTk2NSAyNy42MjkyIDIwLjUzOTggMjcuNjI5NCAyMi4xOTY1VjIzLjk5MjRDMjcuNjI5MiAyNS42NDkxIDI2LjI4NjEgMjYuOTkyNCAyNC42Mjk0IDI2Ljk5MjRIMjIuODM0NUMyMS4xNzc4IDI2Ljk5MjQgMTkuODM0NyAyNS42NDkgMTkuODM0NSAyMy45OTI0VjIyLjE5NjVDMTkuODM0NSAyMS43MTQ4IDE5LjQ5NTcgMjEuMjMyNyAxOS4wMTQgMjEuMjMyN0gxNi40NzkyQzE1Ljc5NzUgMjEuMjMyNyAxNS4zMzc0IDIyLjAwNjEgMTUuMzM3NCAyMi42ODc3VjIzLjgzMzNDMTUuMzM3MyAyNS40OSAxMy45OTQyIDI2LjgzMzMgMTIuMzM3NCAyNi44MzMzSDExLjE5MTlDOS41MzUwOSAyNi44MzMzIDguMTkxOTggMjUuNDkgOC4xOTE4OSAyMy44MzMzVjIyLjY4NzdDOC4xOTE4OSAyMS4wMzA5IDkuNTM1MDQgMTkuNjg3NyAxMS4xOTE5IDE5LjY4NzdIMTIuMzM3NEMxMy4xOTY0IDE5LjY4NzcgMTQuMzk5OSAxOS4wOTU5IDE0LjM5OTkgMTguMjM2OVYxNi4wMTg1QzE0LjM5OTkgMTQuOTUxOCAxNS4yNjQ2IDE0LjA4NzIgMTYuMzMxMiAxNC4wODcySDE5LjQzNUMyMC4wNTk2IDE0LjA4NzIgMjAuNDg0IDEzLjQwNzEgMjAuNDgzOSAxMi43ODI1VjExLjYzN0MyMC40ODM5IDkuOTgwMTEgMjEuODI3IDguNjM2OTYgMjMuNDgzOSA4LjYzNjk2SDI0LjYyOTRaTTEzLjQxMTYgMTEuMjQ2OEMxMy40MTE2IDEyLjY4ODIgMTIuMjQzMSAxMy44NTY3IDEwLjgwMTggMTMuODU2N0M5LjM2MDM3IDEzLjg1NjcgOC4xOTE4OSAxMi42ODgyIDguMTkxODkgMTEuMjQ2OEM4LjE5MTg5IDkuODA1NDQgOS4zNjAzNyA4LjYzNjk2IDEwLjgwMTggOC42MzY5NkMxMi4yNDMxIDguNjM2OTYgMTMuNDExNiA5LjgwNTQ0IDEzLjQxMTYgMTEuMjQ2OFoiIGZpbGw9InVybCgjYSkiLz48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImEiIHgxPSIxNS4xNDgxIiB5MT0iOS45NDE4OCIgeDI9IjE1LjE0ODEiIHkyPSIxMy42Mzc1IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHN0b3Agc3RvcC1jb2xvcj0iIzU0RUNFNyIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzY1OEVGRiIvPjwvbGluZWFyR3JhZGllbnQ+PC9kZWZzPjwvc3ZnPg==";
+/** One entry's icon: a 32px tile holding a 24px image (design §8.3).
+ *
+ * An author's icon reaches the DOM only here, as this `<img>`'s `src` — a
+ * `data:` URL built from bytes the catalog carried. Never `innerHTML`, never
+ * an inline `<svg>`: an image document runs no script and loads nothing
+ * external, and that is the whole defence for an SVG (§8.5).
+ *
+ * `onError` swaps a source that will not decode for the default, as dsh's own
+ * `PackageArtwork` does. The failed source, not a boolean, is remembered, so a
+ * later entry reusing this component instance still tries its own icon.
+ */
+export declare function EntryIcon({ icon }: {
+    icon: string | undefined;
+}): ReactNode;

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

@@ -478,6 +478,14 @@ export declare function entryKey(entry: CatalogEntry): string;
  * shelf that hides the plugin.
  */
 export declare function listedOnShelf(entry: CatalogEntry, cleared: ReadonlySet<string>): boolean;
+/**
+ * An entry's icon as the catalog's data URL, or undefined to draw the default:
+ * it declares none, the catalog predates the icons file, or the sidecar
+ * degraded and the map does not carry its sha256. The map is keyed by 64-hex
+ * sha256, so no name from the catalog is ever used as a lookup here (design
+ * 2026-10-23-shop-plugin-icons §7).
+ */
+export declare function iconOf(entry: CatalogEntry | undefined, icons: Readonly<Record<string, string>>): string | undefined;
 /**
  * One entry's star count from the sidecar, or undefined when it has none.
  *

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

@@ -28,6 +28,11 @@ export interface CatalogSnapshot {
     /** GitHub star counts by package name; {} when the pointer names no
      * sidecar or the sidecar could not be fetched/verified (spec §5). */
     stars: Record<string, number>;
+    /** sha256 → data URL for the catalogue's icons; {} when the pointer names no
+     * sidecar, or it could not be fetched, verified or parsed (design
+     * 2026-10-23-shop-plugin-icons §7). Optional like `notAShop`: `loadCatalog`
+     * always sets it, and a snapshot assembled by hand need not carry it. */
+    icons?: Record<string, string>;
 }
 export interface CatalogResult {
     snapshot: CatalogSnapshot;

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

@@ -308,6 +308,9 @@ export interface ShopCatalogResult {
     /** GitHub star counts by package name; {} when the pointer names no sidecar
      * or the sidecar could not be fetched/verified (§5). */
     stars: Record<string, number>;
+    /** sha256 → data URL for the catalogue's icons; {} when the pointer names
+     * none or it could not be read (design 2026-10-23-shop-plugin-icons §7). */
+    icons: Record<string, string>;
     /** Install identity (`npm:<name>` / `github:<repo>#<subdir>`) → the declared
      * peers node resolution cannot find from the profile. This is the HOST half
      * of the verdict only: a module the browser's module table serves — a

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

@@ -132,6 +132,13 @@ export interface CatalogEntry {
      * nothing reads it here yet — it is telemetry the catalog publishes, not a
      * gate, a badge, or an install decision. */
     forked?: boolean;
+    /** The sha256 that keys this entry's icon in the catalog's icons sidecar
+     * (registry `Entry.icon`; design 2026-10-23-shop-plugin-icons §6.1). Present
+     * exactly when the build published an icon for the entry. The bytes are not
+     * on the entry but in the sidecar, which holds each distinct icon once, so
+     * this is only the key. Additive and optional, so it rides every
+     * schemaVersion. */
+    icon?: string;
 }
 export interface DeniedEntry {
     name: string;

package/lib/types/shared/npm-name.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The npm package-name grammar a catalogue row's `name` must satisfy.
+ *
+ * ONE definition, read in three places: the Host's entry schema
+ * (`host/catalog.ts`), the registry's gate (`registry/scripts/src/gate.ts`)
+ * and `emit`'s last-line invariant. The dependency can only point this way —
+ * the package's tsconfig pins `rootDir: "src"`, so the registry reaches in
+ * and nothing here can reach out (the same reason `shop-like.ts` lives here).
+ *
+ * Why it is narrower than npm's own rule: `validate-npm-package-name` accepts
+ * a scope beginning with `_` or `.` — `@_iluxury/dsh-routerai-price-watcher`
+ * is valid for a NEW publication — while this grammar requires the scope's
+ * first character to be a letter or digit. That was a deliberate argv-safety
+ * choice when the rule lived only in the client: the name becomes half of an
+ * install spec, and everything this excludes is shell punctuation. It stopped
+ * being merely a client rule the moment a catalogue shipped, because the
+ * clients parse the WHOLE data file as one zod object: a single name outside
+ * this grammar costs every listing, not one. On 2026-10-30
+ * `@_iluxury/dsh-routerai-price-watcher` did exactly that — valid on npm, no
+ * gate rule to catch it, and every 0.8.0+ shop answered 「暂时无法读取目录」
+ * for a 21,493-row catalogue. The gate now admits only what this parses.
+ *
+ * The narrow side is therefore the WIRE CONTRACT, frozen by the installed
+ * base: widening it in a client release also widens the gate, because this is
+ * one constant, and the catalogue would then carry names every older client
+ * still refuses. Do not widen it without a way to know which client versions
+ * are installed; npm's per-version download counts cannot answer that (the
+ * measurement is in `emit.ts`'s `peers` comment).
+ *
+ * @module shared/npm-name
+ */
+/**
+ * An optional `@scope/`, then a name starting with a letter or digit and
+ * continuing in lowercase letters, digits, `.`, `_` or `-`. No uppercase, no
+ * leading dot or underscore on either segment, and no shell punctuation.
+ */
+export declare const CATALOG_NPM_NAME: RegExp;
+/**
+ * Whether a catalogue row can carry `name`.
+ * @param name - the npm package name, taken from the published packument.
+ */
+export declare function isCatalogNpmName(name: string): boolean;

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

@@ -6,8 +6,13 @@
 /**
  * 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.
+ * Directory entries and the type flags that carry no file are skipped: npm
+ * packs regular files under `package/`, and a catalog tarball that needs
+ * anything else is not one we published. A pax (`x`) or GNU (`L`) header is not
+ * a file either, but it NAMES the next one: a path too long or too wide for a
+ * ustar header arrives this way, and skipping the header without reading it
+ * left its file under a truncated name, reported missing from an archive that
+ * ships it ({@link pathFromPax}).
+ * Each path is spelled by its bytes, one character each ({@link cstring}).
  */
 export declare function readTar(buffer: Buffer): Map<string, Buffer>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-shop",
-  "version": "0.9.0",
-  "description": "The DeepSeek Harness plugin shop: browse, install, enable, and update dsh plugins from a git-auditable catalog.",
+  "version": "0.10.0-beta.0",
+  "description": "Browse, install, enable, and update plugins for DeepSeek Harness.",
   "icon": "./assets/icon.png",
   "keywords": [
     "dsh-plugin",