@sleetdrop/dsh-plugin-topology 0.1.0 → 0.3.0

package/README.md

@@ -47,6 +47,16 @@ graph as one document:
 For `dot` or `svg`, write the returned content to a file with the write tool to
 produce a shareable artifact. Use `json` to inspect or analyze the assembly.
 
+## Screenshots
+
+The panel opens maximized by default and renders the live plugin/service
+topology as a zoomable Graphviz graph, with metrics, a color legend, and an
+unresolved-dependency table. The same panel is localized through the harness
+locale dictionaries:
+
+- [Chinese (zh_CN)](docs/screenshots/panel-zh_CN.png)
+- [English (en_US)](docs/screenshots/panel-en_US.png)
+
 ## Browser panel
 
 The trigger sits in `sidebar.footer.action` (a root-scope list slot, above
@@ -63,11 +73,32 @@ the host assembly's contribution list.
 
 ## Compatibility
 
-Targets DeepSeek Harness `0.1.1-rc.2`; the `peerDependencies` pin the client
-packages and `@deepseek-ai/cordis@^4.0.1` the snapshot reads through. The
-service reads Cordis internals (`root.registry`, `root.reflect.store`, fiber
-fields) that are not part of the stable public API — verify the installed
-harness satisfies the peer ranges before enabling the tool or panel.
+The plugin uses its **own independent semantic version** — it does not mirror
+the DeepSeek Harness version. New plugin features and bugfixes bump the plugin
+version on their own schedule, independent of which DSH release it targets.
+The table below maps each plugin version to the DSH release it was validated
+against, so pick the plugin version whose target DSH matches your harness.
+
+Current release targets DeepSeek Harness `0.1.5-rc.1`; the `peerDependencies`
+pin the client packages and `@deepseek-ai/cordis@^4.0.2` the snapshot reads
+through. The 0.1.2 rc line removed the old `dsh-client-runtime` browser runtime:
+the client now runs on the Cordis `Context` augmented by the shell baseline
+renderer (`dsh-client-ui-renderer` → `ctx.slots`), `dsh-client-store`
+(`defineStore`), `dsh-client-locale` (`ctx.locale`), and `dsh-api-remotes`
+(`ctx.remote`). The service reads Cordis internals (`root.registry`,
+`root.reflect.store`, fiber fields) that are not part of the stable public API
+— verify the installed harness satisfies the peer ranges before enabling the
+tool or panel.
+
+DSH itself has no beta channel — it publishes `alpha` then `rc` (its `latest`
+dist-tag is stale, follow its `next`). This plugin adapts to stable DSH `rc`
+releases only and skips the fast-moving `alpha` line.
+
+| Plugin version (Git + npm) | Targets DSH harness | Notes |
+| --- | --- | --- |
+| `0.1.0` | `0.1.1-rc.2` | Old `dsh-client-runtime` browser model (frozen). |
+| `0.2.0` | `0.1.2-rc.1` | Cordis-Context browser model; client-runtime removed. |
+| `0.3.0` | `0.1.5-rc.1` | Dependency refresh for DSH 0.1.5-rc.1; no code changes required. |
 
 ## Known Limitations
 
@@ -87,23 +118,25 @@ pnpm test           # node:test over compiled specs
 pnpm run typecheck  # noEmit check
 ```
 
-The `dsh.client` browser bundle inlines everything except `react` and
-`@deepseek-ai/dsh-client-runtime`, the two rows every harness shell serves.
+The `dsh.client` browser bundle inlines everything except the shell's frozen
+platform-module rows (`react`, `@deepseek-ai/cordis`, `dsh-client-store`, and
+`dsh-client-ui-slots`), which every 0.1.2-rc.1 harness shell serves.
 
 See [NEXT-STEPS.md](NEXT-STEPS.md) for planned renderer improvements.
 
 ## Publishing
 
-`prepublishOnly` runs the build and tests. `publishConfig` pins `access:
-public` and the `registry.npmjs.org` target (machine-local pnpm may default to
-a read-only mirror), so:
+The full end-to-end release checklist (version bump → build/test → commit/tag →
+headless + browser smoke → publish) is in [`docs/RELEASING.md`](docs/RELEASING.md).
+The final publish requires an interactive OTP, so it is run by hand:
 
 ```sh
-npm login                       # once, with the sleetdrop account
-npm publish                     # builds, tests, and publishes the tarball
+pnpm publish --access public   # prompts for your OTP
 ```
 
-If `npm publish` fails with an `EPERM` from the npm cache
+`prepublishOnly` runs the build and tests. `publishConfig` pins `access:
+public` and the `registry.npmjs.org` target (machine-local pnpm may default to
+a read-only mirror). If `npm publish` fails with an `EPERM` from the npm cache
 (`root-owned files`), either fix the cache once
 (`sudo chown -R $(id -u):$(id -g) ~/.npm`) or publish through pnpm, whose
 store avoids the npm cache entirely:

package/lib/client/icons.d.ts

@@ -1,8 +1,8 @@
 /**
  * Local icon set for the topology viewer.
  *
- * The 0.1.1-rc.2 harness has no shared `dsh-client-ui-primitives` package, so
- * the plugin carries its own icons and controls. Each glyph is a self-contained
+ * The plugin carries its own icons and controls rather than depending on the
+ * shell's `dsh-client-ui-primitives` glyph set. Each glyph is a self-contained
  * SVG in the `currentColor` convention.
  * @module @sleetdrop/dsh-plugin-topology/client/icons
  */
@@ -25,7 +25,7 @@ export declare function IconDownloadOutline16({ size, className }: IconProps): R
 export declare function IconFullscreenOutline16({ size, className }: IconProps): ReactNode;
 /** Plugin-mark glyph for the footer trigger. */
 export declare function IconPluginOutline16({ size, className }: IconProps): ReactNode;
-/** Minimal outline button (the rc.2 harness ships no shared Button). */
+/** Minimal outline button (the plugin keeps its own control set). */
 export declare function OutlineButton({ children, onClick, title, icon, }: {
     children: ReactNode;
     onClick: () => void;

package/lib/client/icons.js

@@ -27,7 +27,7 @@ export function IconFullscreenOutline16({ size = 16, className }) {
 export function IconPluginOutline16({ size = 16, className }) {
     return (_jsxs("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: [_jsx("circle", { cx: "8", cy: "8", r: "6.5", stroke: "currentColor", strokeWidth: "1.3" }), _jsx("circle", { cx: "5.6", cy: "5.6", r: "1.1", fill: "currentColor" }), _jsx("circle", { cx: "10.4", cy: "5.6", r: "1.1", fill: "currentColor" }), _jsx("circle", { cx: "8", cy: "9.4", r: "1.1", fill: "currentColor" }), _jsx("path", { d: "M5.6 5.6L8 9.4M10.4 5.6L8 9.4", stroke: "currentColor", strokeWidth: "1.1" })] }));
 }
-/** Minimal outline button (the rc.2 harness ships no shared Button). */
+/** Minimal outline button (the plugin keeps its own control set). */
 export function OutlineButton({ children, onClick, title, icon, }) {
     const handle = (event) => {
         event.preventDefault();

package/lib/client/index.d.ts

@@ -4,14 +4,15 @@
  * fixed, centered panel that shows the live Host plugin dependency graph
  * (metrics, legend, unresolved-dependency log, zoom/pan and format downloads).
  *
- * The Host service is consumed through the generated `remote` namespace, whose
- * contribution this plugin mounts itself (`ctx.remote.$mount`). The mounted
- * namespace service is read through `ctx.get('remote.pluginTopology')` — the
- * Cordis no-inject read — because declaring it in `inject` would deadlock:
- * the service does not exist until this plugin's own apply mounts it.
+ * The Host service is consumed through the generated `remote` namespace. This
+ * package self-mounts its `pluginTopology` Remote contribution on `ctx.remote`
+ * (`$mount`), so it does not require a hand-edited host assembly contribution
+ * list. The namespace is read lazily inside the panel callbacks through the
+ * `ctx.get('remote.pluginTopology')` no-inject read — those closures run only
+ * after the user opens the panel, long after the mount settles.
  * @module @sleetdrop/dsh-plugin-topology/client
  */
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import type { Context } from '@deepseek-ai/cordis';
 import { type PluginTopologyLocaleKey } from './locales.ts';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
@@ -22,8 +23,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 export type { TopologyViewInjected, TopologyViewProps } from './TopologyView.tsx';
 export type { PluginTopologyLocaleKey } from './locales.ts';
 export { TopologyPanel, type TopologyPanelProps } from './panel.tsx';
-/** Services required by the panel. The topology namespace is self-mounted and
- * read through ctx.get — see the module doc for the deadlock rationale. */
+export { createTopologyViewStore, type ViewerHandle } from './stores.ts';
+/** Required services: the slot registry, the locale runtime, and the Remote gateway. */
 export declare const inject: string[];
 /** Contribute the global topology panel trigger + panel to the sidebar footer. */
-export declare function apply(ctx: ClientContext): void;
+export declare function apply(ctx: Context): void;

package/lib/client/index.js

@@ -4,11 +4,12 @@
  * fixed, centered panel that shows the live Host plugin dependency graph
  * (metrics, legend, unresolved-dependency log, zoom/pan and format downloads).
  *
- * The Host service is consumed through the generated `remote` namespace, whose
- * contribution this plugin mounts itself (`ctx.remote.$mount`). The mounted
- * namespace service is read through `ctx.get('remote.pluginTopology')` — the
- * Cordis no-inject read — because declaring it in `inject` would deadlock:
- * the service does not exist until this plugin's own apply mounts it.
+ * The Host service is consumed through the generated `remote` namespace. This
+ * package self-mounts its `pluginTopology` Remote contribution on `ctx.remote`
+ * (`$mount`), so it does not require a hand-edited host assembly contribution
+ * list. The namespace is read lazily inside the panel callbacks through the
+ * `ctx.get('remote.pluginTopology')` no-inject read — those closures run only
+ * after the user opens the panel, long after the mount settles.
  * @module @sleetdrop/dsh-plugin-topology/client
  */
 // The generated Host Remote-descriptor contribution for this package.
@@ -17,32 +18,32 @@ import { createTopologyViewStore } from "./stores.js";
 import { TopologyPanel } from "./panel.js";
 import { en, NS, zh } from "./locales.js";
 export { TopologyPanel } from "./panel.js";
-/** Services required by the panel. The topology namespace is self-mounted and
- * read through ctx.get — see the module doc for the deadlock rationale. */
+export { createTopologyViewStore } from "./stores.js";
+/** Required services: the slot registry, the locale runtime, and the Remote gateway. */
 export const inject = ['slots', 'locale', 'remote'];
 /** Contribute the global topology panel trigger + panel to the sidebar footer. */
 export function apply(ctx) {
-    // rc.2 locale API: per-locale registration (the typed dicts form needs a
-    // LocaleNamespaceMap merge this package deliberately avoids).
-    ctx.effect(() => {
-        const unregisterEn = ctx.locale.register(NS, 'en', en);
-        const unregisterZh = ctx.locale.register(NS, 'zh', zh);
-        return () => {
-            unregisterEn();
-            unregisterZh();
-        };
-    }, 'ui-plugin-topology: dictionaries');
+    // rc.1 locale API: register the dictionary map object keyed by built-in
+    // locale id (the typed dicts form needs a LocaleNamespaceMap merge — the
+    // declare module above provides the `pluginTopology` namespace).
+    ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'ui-plugin-topology: dictionaries');
     // Mount the package's own Remote contribution so `remote.pluginTopology`
-    // becomes a live namespace service. The mounted service is read via
-    // ctx.get (no-inject) inside the panel callbacks, which run only after the
-    // user opens the panel — long after this mount has settled.
-    ctx.effect(() => ctx.remote.$mount(topologyRemote).then(dispose => dispose, (error) => {
+    // becomes a live namespace service. The namespace is read via the
+    // `ctx.get('remote.pluginTopology')` no-inject read inside the panel
+    // callbacks, which run only after the user opens the panel — long after this
+    // mount has settled.
+    ctx.effect(() => ctx.remote.$mount(topologyRemote).then((dispose) => dispose, (error) => {
         console.error('[plugin-topology] remote contribution mount failed:', error);
         return () => { };
     }), 'ui-plugin-topology: mount remote contribution');
-    const t = ctx.locale.bind(NS);
     const viewerStore = createTopologyViewStore();
     const namespaceOf = () => {
+        // No-inject read: the `remote.pluginTopology` namespace service is mounted
+        // by this plugin's own `$mount` above, so it cannot appear in `inject`
+        // (injecting a self-mounted dynamic service would deadlock — the service
+        // does not exist until this plugin's apply mounts it). `ctx.get` reads the
+        // store without the inject requirement; it resolves only once the mount's
+        // namespace fiber is ACTIVE, which the panel callbacks guarantee.
         const namespace = ctx.get('remote.pluginTopology');
         if (namespace === undefined) {
             throw new Error('pluginTopology remote namespace is not mounted yet — reopen the panel');
@@ -54,7 +55,10 @@ export function apply(ctx) {
         id: 'plugin-topology',
         order: 100,
         locale: NS,
-        label: () => t('title'),
+        // Store seat persisted across panel remounts (the transform is written
+        // here so it survives closing/reopening the global panel). Declaring it
+        // makes the occupant receive `useStore` + bound `actions` props, and the
+        // `inject` factory below receives the same baked actions as its arg.
         store: viewerStore,
         inject: () => ({
             analyze: async () => {

package/lib/client/stores.d.ts

@@ -1,4 +1,4 @@
-import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-store';
 /** The pan/zoom transform of the graph viewport. */
 export interface TopologyTransform {
     /** Horizontal translate in px. */
@@ -9,17 +9,18 @@ export interface TopologyTransform {
     k: number;
 }
 /** Viewer state: the remembered transform, or null until the first fit lands. */
-type ViewerState = {
+export type ViewerState = {
     transform: TopologyTransform | null;
 };
-type ViewerActions = {
+export type ViewerActions = {
     setTransform: (draft: ViewerState, transform: TopologyTransform | null) => void;
 };
+/** The engine-backed viewer handle (spec + actions in one). */
+export type ViewerHandle = EngineStoreHandle<ViewerState, ViewerActions>;
 /**
  * Create the shared root-scope viewer handle. The transform is written here so
  * it survives the panel's unmount/remount when the user closes and reopens the
  * global panel.
  * @returns the store handle (spec + type + identity + factory in one).
  */
-export declare function createTopologyViewStore(): EngineStoreHandle<ViewerState, ViewerActions>;
-export {};
+export declare function createTopologyViewStore(): ViewerHandle;

package/lib/client/stores.js

@@ -1,4 +1,4 @@
-import { defineStore } from '@deepseek-ai/dsh-client-runtime/client';
+import { defineStore } from '@deepseek-ai/dsh-client-store';
 /**
  * Create the shared root-scope viewer handle. The transform is written here so
  * it survives the panel's unmount/remount when the user closes and reopens the

package/lib/client/useDismissOnOutsidePointer.d.ts

@@ -1,7 +1,7 @@
 import type { RefObject } from 'react';
 /**
  * Close a popover when the pointer presses outside its root element.
- * Local implementation: the 0.1.1-rc.2 harness ships no shared dismiss hook.
+ * Local implementation: the plugin keeps its own dismiss hook.
  * @param ref - root element the interaction belongs to.
  * @param open - whether the popover is currently open.
  * @param setOpen - close state setter.

package/lib/client/useDismissOnOutsidePointer.js

@@ -1,7 +1,7 @@
 import { useEffect } from 'react';
 /**
  * Close a popover when the pointer presses outside its root element.
- * Local implementation: the 0.1.1-rc.2 harness ships no shared dismiss hook.
+ * Local implementation: the plugin keeps its own dismiss hook.
  * @param ref - root element the interaction belongs to.
  * @param open - whether the popover is currently open.
  * @param setOpen - close state setter.

package/lib/client.js

@@ -23,8 +23,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-let __deepseek_ai_dsh_client_runtime_client = require("@deepseek-ai/dsh-client-runtime/client");
-__deepseek_ai_dsh_client_runtime_client = __toESM(__deepseek_ai_dsh_client_runtime_client);
+let __deepseek_ai_dsh_client_store = require("@deepseek-ai/dsh-client-store");
+__deepseek_ai_dsh_client_store = __toESM(__deepseek_ai_dsh_client_store);
 let react = require("react");
 react = __toESM(react);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -4450,7 +4450,7 @@ var remote_client_default = TYPERT_REMOTE;
 * @returns the store handle (spec + type + identity + factory in one).
 */
 function createTopologyViewStore() {
-	return (0, __deepseek_ai_dsh_client_runtime_client.defineStore)({
+	return (0, __deepseek_ai_dsh_client_store.defineStore)({
 		init: () => ({ transform: null }),
 		actions: { setTransform: (d, transform$1) => {
 			d.transform = transform$1;
@@ -4610,7 +4610,7 @@ function IconPluginOutline16({ size = 16, className }) {
 		]
 	});
 }
-/** Minimal outline button (the rc.2 harness ships no shared Button). */
+/** Minimal outline button (the plugin keeps its own control set). */
 function OutlineButton({ children, onClick, title, icon }) {
 	const handle = (event) => {
 		event.preventDefault();
@@ -5508,8 +5508,7 @@ const zh = {
 
 //#endregion
 //#region src/client/index.ts
-/** Services required by the panel. The topology namespace is self-mounted and
-* read through ctx.get — see the module doc for the deadlock rationale. */
+/** Required services: the slot registry, the locale runtime, and the Remote gateway. */
 const inject = [
 	"slots",
 	"locale",
@@ -5517,19 +5516,14 @@ const inject = [
 ];
 /** Contribute the global topology panel trigger + panel to the sidebar footer. */
 function apply(ctx) {
-	ctx.effect(() => {
-		const unregisterEn = ctx.locale.register(NS, "en", en);
-		const unregisterZh = ctx.locale.register(NS, "zh", zh);
-		return () => {
-			unregisterEn();
-			unregisterZh();
-		};
-	}, "ui-plugin-topology: dictionaries");
+	ctx.effect(() => ctx.locale.register(NS, {
+		en,
+		zh
+	}), "ui-plugin-topology: dictionaries");
 	ctx.effect(() => ctx.remote.$mount(remote_client_default).then((dispose) => dispose, (error) => {
 		console.error("[plugin-topology] remote contribution mount failed:", error);
 		return () => {};
 	}), "ui-plugin-topology: mount remote contribution");
-	const t = ctx.locale.bind(NS);
 	const viewerStore = createTopologyViewStore();
 	const namespaceOf = () => {
 		const namespace = ctx.get("remote.pluginTopology");
@@ -5541,7 +5535,6 @@ function apply(ctx) {
 		id: "plugin-topology",
 		order: 100,
 		locale: NS,
-		label: () => t("title"),
 		store: viewerStore,
 		inject: () => ({
 			analyze: async () => {
@@ -5561,6 +5554,7 @@ function apply(ctx) {
 //#endregion
 exports.TopologyPanel = TopologyPanel;
 exports.apply = apply;
+exports.createTopologyViewStore = createTopologyViewStore;
 exports.inject = inject;
 return module.exports; } });
 //# sourceMappingURL=client.js.map