@sleetdrop/dsh-plugin-topology 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sleetdrop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NEXT-STEPS.md

@@ -0,0 +1,32 @@
+# Next steps
+
+Planned directions for the plugin topology renderer. None of these are
+committed API; they are design notes for future releases.
+
+## Node coloring by fiber state
+
+The snapshot already captures every fiber's lifecycle state (`ACTIVE`,
+`FAILED`, `PENDING`, `DISPOSED`, …), but the SVG currently colors only
+unresolved dependencies (red stroke). Color nodes by state instead:
+
+- `FAILED` — red fill
+- `DISPOSED` — gray, dashed border
+- `PENDING` — light fill
+- merged nodes take the "worst" state of their instances
+
+This surfaces the most common diagnostic question — "which plugins did not
+load successfully" — at a glance.
+
+## Click a node for details
+
+The snapshot captures each plugin's `inject` (service names) and `source`
+(module specifier), but the UI never shows them. Clicking a node could open a
+small popover with state, injected services, module path, and degree
+centrality. Requires switching the SVG from an `<img>` to inline rendering
+with pointer hit-testing — a medium-sized change.
+
+## Deferred ideas
+
+- Show an instance count (`timer ×3`) instead of the ordinal list. Deferred:
+  the ordinal list doubles as a startup-order hint, and adding the count
+  crowds the label.

package/README.md

@@ -0,0 +1,120 @@
+# @sleetdrop/dsh-plugin-topology
+
+Plugin dependency graph inspector for DeepSeek Harness. It snapshots the live
+Cordis plugin fiber tree into a plugin/service bipartite graph, derives
+graph-theory metrics, and renders it as JSON, Graphviz DOT, or SVG.
+
+One installable bundle ships three surfaces:
+
+- **host service** (`@sleetdrop/dsh-plugin-topology`): a `TypertRemoteService`
+  exposing `analyze()` and `render()` over the gateway.
+- **host tool** (`@sleetdrop/dsh-plugin-topology/tool`): the model-facing
+  `graph.render` tool, registering on `ctx.tools`.
+- **browser surface** (`dsh.client`): a global panel reachable from the sidebar
+  footer that renders the graph, metrics, legend, unresolved-dependency log, and
+  pan/zoom + format downloads.
+
+## Install
+
+```sh
+# From the npm registry (prebuilt lib/, no build permission needed):
+dsh plugin --profile <name> add @sleetdrop/dsh-plugin-topology
+
+# From a local checkout:
+git clone https://github.com/sleetdrop/dsh-plugin-topology.git
+cd dsh-plugin-topology && pnpm install && pnpm build
+dsh plugin --profile <name> add ./dsh-plugin-topology
+```
+
+The bundle patch mounts the host service row and the `graph.render` tool row.
+The tool row can live in the profile patch instead — a deployment that prefers
+per-session placement may remove it from `cordis.patch.yml` and add it to its
+agent preset.
+
+## Model Experience
+
+The `graph.render` tool serializes the running instance's plugin dependency
+graph as one document:
+
+- `json` — a NetworkX-compatible node-link graph whose nodes carry graph-theory
+  metrics (in/out degree, degree/betweenness/eigenvector centrality, page-rank)
+  and whose `graph` object carries global metrics (density, strongly connected
+  components, `isDag`, diameter).
+- `dot` — Graphviz source for layout via any Graphviz tool.
+- `svg` — a Graphviz-rendered SVG, with isolated plugins composed beside the
+  main graph.
+
+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.
+
+## Browser panel
+
+The trigger sits in `sidebar.footer.action` (a root-scope list slot, above
+Settings), visible with or without a selected session — the topology is
+runtime-global and needs no session context. The panel opens maximized by
+default (the Graphviz canvas needs the space); the header button restores a
+centered window. Same-named plugin instances merge into one node; each node's
+label carries the instance creation ordinals in brackets (`timer [1,9,23]`),
+assigned at startup and meaningful only within that run.
+
+The client injects `remote` (the gateway ClientRemote service) and self-mounts
+its own `pluginTopology` Remote contribution, so it does not require editing
+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.
+
+## Known Limitations
+
+- A future Cordis that reshapes the internal registry/reflect surfaces breaks
+  `snapshot()`; it does not degrade silently.
+- The browser panel requires a web profile (the `--patch` overlay covers only
+  the node half).
+- Same-named instances merge in the display graph; per-instance identity stays
+  available in the JSON export and the complete downloadable DOT.
+
+## Development
+
+```sh
+pnpm install
+pnpm run build      # tsc (node half) + tsdown (client bundle)
+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.
+
+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:
+
+```sh
+npm login                       # once, with the sleetdrop account
+npm publish                     # builds, tests, and publishes the tarball
+```
+
+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:
+
+```sh
+pnpm publish                    # same prepublishOnly gate, pnpm store
+```
+
+`files` ships `lib/`, `cordis.patch.yml`, and `overlay.example.yml`; npm adds
+README and LICENSE automatically.
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# The plugin-topology bundle patch. Applied when a profile lists this bundle.
+# The plugin-topology host service is the package default export; the graph.render
+# tool is the ./tool subpath default export; the browser surface is the dsh.client
+# row the bundle declares (see package.json dsh.client).
+
+- insert:
+    - id: plugin-topology
+      name: '@sleetdrop/dsh-plugin-topology'
+
+- insert:
+    - id: tool-plugin-topology
+      name: '@sleetdrop/dsh-plugin-topology/tool'
+      # Model-visible tools in the harness mount through the per-session agent
+      # preset; a bundle may place the tool here so a profile that adds this
+      # bundle exposes the tool in its own preset. Users who prefer the
+      # per-session placement can remove this row and add it to their agent
+      # preset instead.

package/lib/client/TopologyGraphView.d.ts

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+import type { TopologyTransform } from './stores.ts';
+/** Zoom/pan props plus the localized control labels and the shared transform. */
+export interface TopologyGraphViewProps {
+    svg: string;
+    alt: string;
+    /** Viewport height as a CSS length (`100%` inside the view body). */
+    height: string;
+    /** Remembered transform; null until the first fit lands. */
+    transform: TopologyTransform | null;
+    /** Persist the latest transform (panel reopen survival). */
+    onTransformChange: (transform: TopologyTransform) => void;
+    zoomInLabel: string;
+    zoomOutLabel: string;
+    /** Reset-to-initial-view control (returns to the centered fit transform). */
+    resetViewLabel: string;
+    /** Accessible name for the clickable zoom-level toggle. */
+    zoomLevelLabel: string;
+}
+/**
+ * Pan/zoom SVG viewer: fit-and-center on load, wheel zooms toward the cursor,
+ * drag pans, double-click zooms toward the cursor, and a compact floating pill
+ * (fit / zoom-out / zoom-level / zoom-in) collapses to just the fit control at
+ * rest. The transform is written back to the parent store on every change so it
+ * survives panel close/reopen.
+ */
+export declare function TopologyGraphView({ svg, alt, height, transform, onTransformChange, zoomInLabel, zoomOutLabel, resetViewLabel, zoomLevelLabel, }: TopologyGraphViewProps): ReactNode;

package/lib/client/TopologyGraphView.js

@@ -0,0 +1,246 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { IconFullscreenOutline16, IconMinusOutline16, IconPlusOutline16 } from "./icons.js";
+import css from './TopologyGraphView.module.css';
+const MIN_K = 0.05;
+/** A fit never shrinks below this scale, so the default and reset land at actual size. */
+const MIN_FIT_K = 1.0;
+const MAX_K = 64;
+const ZOOM_FACTOR = 1.25;
+/** Arrow-key pan step in screen px. */
+const PAN_STEP = 40;
+function clampK(k) {
+    return Math.min(MAX_K, Math.max(MIN_K, k));
+}
+/** Format the current scale as a map-like zoom level (e.g. "2.5×"). */
+function formatZoom(k) {
+    return `${Math.round(k * 10) / 10}×`;
+}
+/** Fit the natural-size image inside the container and center it, but never below `MIN_FIT_K`. */
+function fitView(containerWidth, containerHeight, naturalWidth, naturalHeight) {
+    const k = Math.max(MIN_FIT_K, Math.min(containerWidth / naturalWidth, containerHeight / naturalHeight));
+    return {
+        k,
+        x: (containerWidth - naturalWidth * k) / 2,
+        y: (containerHeight - naturalHeight * k) / 2,
+    };
+}
+/**
+ * Pan/zoom SVG viewer: fit-and-center on load, wheel zooms toward the cursor,
+ * drag pans, double-click zooms toward the cursor, and a compact floating pill
+ * (fit / zoom-out / zoom-level / zoom-in) collapses to just the fit control at
+ * rest. The transform is written back to the parent store on every change so it
+ * survives panel close/reopen.
+ */
+export function TopologyGraphView({ svg, alt, height, transform, onTransformChange, zoomInLabel, zoomOutLabel, resetViewLabel, zoomLevelLabel, }) {
+    const containerRef = useRef(null);
+    const naturalRef = useRef(null);
+    const dragRef = useRef(null);
+    const [view, setView] = useState(() => transform ?? { x: 0, y: 0, k: 1 });
+    const [fitted, setFitted] = useState(transform !== null);
+    const [containerSize, setContainerSize] = useState(null);
+    const [atFit, setAtFit] = useState(false);
+    const [panelHovered, setPanelHovered] = useState(false);
+    const [viewportHovered, setViewportHovered] = useState(false);
+    const commit = useCallback((next) => {
+        setView(next);
+        onTransformChange(next);
+    }, [onTransformChange]);
+    const fit = useCallback(() => {
+        const container = containerRef.current;
+        const natural = naturalRef.current;
+        if (container === null || natural === null)
+            return;
+        const rect = container.getBoundingClientRect();
+        commit(fitView(rect.width, rect.height, natural.width, natural.height));
+        setAtFit(true);
+    }, [commit]);
+    const zoomAtCenter = useCallback((factor) => {
+        const element = containerRef.current;
+        if (element === null)
+            return;
+        const rect = element.getBoundingClientRect();
+        const cx = rect.width / 2;
+        const cy = rect.height / 2;
+        setView((current) => {
+            const k = clampK(current.k * factor);
+            const ratio = k / current.k;
+            const next = { k, x: cx - ratio * (cx - current.x), y: cy - ratio * (cy - current.y) };
+            onTransformChange(next);
+            return next;
+        });
+        setAtFit(false);
+    }, [onTransformChange]);
+    const zoomAround = useCallback((px, py, factor) => {
+        setView((current) => {
+            const k = clampK(current.k * factor);
+            const ratio = k / current.k;
+            const next = { k, x: px - ratio * (px - current.x), y: py - ratio * (py - current.y) };
+            onTransformChange(next);
+            return next;
+        });
+        setAtFit(false);
+    }, [onTransformChange]);
+    const panBy = useCallback((dx, dy) => {
+        setView((current) => {
+            const next = { ...current, x: current.x + dx, y: current.y + dy };
+            onTransformChange(next);
+            return next;
+        });
+        setAtFit(false);
+    }, [onTransformChange]);
+    const onLoad = (event) => {
+        const img = event.currentTarget;
+        naturalRef.current = { width: img.naturalWidth, height: img.naturalHeight };
+        if (transform === null)
+            fit();
+        setFitted(true);
+    };
+    // Track the container size so the zoom-level "actual size" (100%) stays centered.
+    // ResizeObserver is unavailable in jsdom; the initial size already comes from
+    // getBoundingClientRect, so the center just won't react to resizes there.
+    useEffect(() => {
+        const element = containerRef.current;
+        if (element === null)
+            return;
+        const update = () => {
+            const rect = element.getBoundingClientRect();
+            setContainerSize({ width: rect.width, height: rect.height });
+        };
+        update();
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(update);
+        observer.observe(element);
+        return () => { observer.disconnect(); };
+    }, []);
+    // A non-passive wheel listener (React's synthetic onWheel is passive, so it cannot preventDefault).
+    useEffect(() => {
+        const element = containerRef.current;
+        if (element === null)
+            return;
+        const onWheel = (event) => {
+            event.preventDefault();
+            const rect = element.getBoundingClientRect();
+            const px = event.clientX - rect.left;
+            const py = event.clientY - rect.top;
+            setView((current) => {
+                const factor = event.deltaY < 0 ? ZOOM_FACTOR : 1 / ZOOM_FACTOR;
+                const k = clampK(current.k * factor);
+                const ratio = k / current.k;
+                const next = { k, x: px - ratio * (px - current.x), y: py - ratio * (py - current.y) };
+                onTransformChange(next);
+                return next;
+            });
+            setAtFit(false);
+        };
+        element.addEventListener('wheel', onWheel, { passive: false });
+        return () => { element.removeEventListener('wheel', onWheel); };
+    }, [onTransformChange]);
+    // Keyboard shortcuts while the pointer is over the canvas: +/− zoom, 0/F reset-to-fit,
+    // arrow keys pan. Ignored while a text field has focus.
+    useEffect(() => {
+        if (!viewportHovered)
+            return;
+        const onKey = (event) => {
+            const target = document.activeElement;
+            if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement
+                || (target instanceof HTMLElement && target.isContentEditable))
+                return;
+            switch (event.key) {
+                case '+':
+                case '=':
+                    zoomAtCenter(ZOOM_FACTOR);
+                    event.preventDefault();
+                    break;
+                case '-':
+                case '_':
+                    zoomAtCenter(1 / ZOOM_FACTOR);
+                    event.preventDefault();
+                    break;
+                case '0':
+                case 'f':
+                case 'F':
+                    fit();
+                    event.preventDefault();
+                    break;
+                case 'ArrowLeft':
+                    panBy(-PAN_STEP, 0);
+                    event.preventDefault();
+                    break;
+                case 'ArrowRight':
+                    panBy(PAN_STEP, 0);
+                    event.preventDefault();
+                    break;
+                case 'ArrowUp':
+                    panBy(0, -PAN_STEP);
+                    event.preventDefault();
+                    break;
+                case 'ArrowDown':
+                    panBy(0, PAN_STEP);
+                    event.preventDefault();
+                    break;
+            }
+        };
+        window.addEventListener('keydown', onKey);
+        return () => { window.removeEventListener('keydown', onKey); };
+    }, [viewportHovered, zoomAtCenter, fit, panBy]);
+    const onPointerDown = (event) => {
+        dragRef.current = {
+            pointerId: event.pointerId,
+            startX: event.clientX,
+            startY: event.clientY,
+            baseX: view.x,
+            baseY: view.y,
+        };
+        event.currentTarget.setPointerCapture(event.pointerId);
+    };
+    const onPointerMove = (event) => {
+        const drag = dragRef.current;
+        if (drag === null || drag.pointerId !== event.pointerId)
+            return;
+        commit({
+            ...view,
+            x: drag.baseX + (event.clientX - drag.startX),
+            y: drag.baseY + (event.clientY - drag.startY),
+        });
+        setAtFit(false);
+    };
+    const onPointerEnd = (event) => {
+        if (dragRef.current?.pointerId === event.pointerId)
+            dragRef.current = null;
+    };
+    const onDoubleClick = (event) => {
+        const element = containerRef.current;
+        if (element === null)
+            return;
+        const rect = element.getBoundingClientRect();
+        const px = event.clientX - rect.left;
+        const py = event.clientY - rect.top;
+        zoomAround(px, py, event.shiftKey ? 1 / ZOOM_FACTOR : ZOOM_FACTOR);
+    };
+    // Clicking the zoom level toggles between the reset-to-fit transform and 100% (k = 1).
+    const onZoomLevelClick = () => {
+        if (atFit) {
+            const size = containerSize;
+            const natural = naturalRef.current;
+            const width = size?.width ?? 0;
+            const height = size?.height ?? 0;
+            commit({
+                k: 1,
+                x: (width - (natural?.width ?? 0)) / 2,
+                y: (height - (natural?.height ?? 0)) / 2,
+            });
+            setAtFit(false);
+        }
+        else {
+            fit();
+        }
+    };
+    const collapsed = atFit && !panelHovered;
+    const src = `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
+    return (_jsxs("div", { className: css.graphBox, style: { height }, children: [_jsx("div", { ref: containerRef, className: css.graphViewport, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: onPointerEnd, onPointerCancel: onPointerEnd, onDoubleClick: onDoubleClick, onPointerEnter: () => { setViewportHovered(true); }, onPointerLeave: () => { setViewportHovered(false); }, children: _jsx("img", { className: css.graphImg, src: src, alt: alt, draggable: false, onLoad: onLoad, style: {
+                        opacity: fitted ? 1 : 0,
+                        transform: `translate(${view.x}px, ${view.y}px) scale(${view.k})`,
+                    } }) }), _jsxs("div", { className: collapsed ? `${css.zoomControls} ${css.collapsed}` : css.zoomControls, onPointerEnter: () => { setPanelHovered(true); }, onPointerLeave: () => { setPanelHovered(false); }, children: [_jsx("button", { type: "button", className: `${css.iconButton} ${css.fitButton}`, onClick: fit, "aria-label": resetViewLabel, title: resetViewLabel, children: _jsx(IconFullscreenOutline16, {}) }), _jsx("button", { type: "button", className: `${css.iconButton} ${css.zoomButton}`, onClick: () => { zoomAtCenter(1 / ZOOM_FACTOR); }, "aria-label": zoomOutLabel, title: zoomOutLabel, children: _jsx(IconMinusOutline16, {}) }), _jsx("button", { type: "button", className: css.zoomLevel, onClick: onZoomLevelClick, "aria-label": zoomLevelLabel, title: zoomLevelLabel, children: formatZoom(view.k) }), _jsx("button", { type: "button", className: `${css.iconButton} ${css.zoomButton}`, onClick: () => { zoomAtCenter(ZOOM_FACTOR); }, "aria-label": zoomInLabel, title: zoomInLabel, children: _jsx(IconPlusOutline16, {}) })] })] }));
+}

package/lib/client/TopologyView.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+import type { Rankdir, RenderFormat, TopologyAnalysis } from '../types.ts';
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PluginTopologyLocaleKey } from './locales.ts';
+import { type TopologyTransform } from './stores.ts';
+/** Registration-side injected callbacks used by the view. */
+export interface TopologyViewInjected {
+    /** Read the current Host plugin topology analysis for the metrics. */
+    analyze: () => Promise<TopologyAnalysis>;
+    /** Serialize the current topology in one format along the given layout direction. */
+    render: (format: RenderFormat, rankdir: Rankdir) => Promise<string>;
+}
+/** Viewer state selector: the remembered transform (null until the first fit). */
+export type ViewerStateSelector = SnapshotSelectorHook<{
+    transform: TopologyTransform | null;
+}>;
+/** Full component props: the store seat, the injected callbacks, and the locale `t`. */
+export type TopologyViewProps = {
+    useStore: ViewerStateSelector;
+    actions: {
+        setTransform: (transform: TopologyTransform | null) => void;
+    };
+    t: (key: PluginTopologyLocaleKey) => string;
+} & TopologyViewInjected;
+/** The plugin dependency graph view, rendered inside the global footer-action panel. */
+export declare function TopologyView({ useStore, actions, analyze, render, t }: TopologyViewProps): ReactNode;

package/lib/client/TopologyView.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { IconChevronDownOutline14, IconDownloadOutline16, OutlineButton } from "./icons.js";
+import { TopologyGraphView } from "./TopologyGraphView.js";
+import { createTopologyViewStore } from "./stores.js";
+import css from './TopologyView.module.css';
+const DOWNLOAD_FORMATS = [
+    { format: 'svg', labelKey: 'downloadSvg' },
+    { format: 'dot', labelKey: 'downloadDot' },
+    { format: 'json', labelKey: 'downloadJson' },
+];
+/**
+ * The health-oriented metrics: scale, the broken-dependency signal, and the
+ * three coupling/depth/fragmentation facts. Cycle invariants (isDag, SCC) and
+ * descriptive counts (average path, source/sink) are omitted — the former is
+ * constant on an inject/provide graph, the latter carry no health signal.
+ */
+function metricRows(analysis, t) {
+    const m = analysis.graphMetrics;
+    const unresolved = analysis.graph.unresolved.length;
+    return [
+        { label: t('metricPlugins'), value: String(m.nodeCount) },
+        { label: t('metricDependencies'), value: String(m.edgeCount) },
+        { label: t('metricUnresolved'), value: String(unresolved), warning: unresolved > 0, expandable: unresolved > 0 },
+        { label: t('metricDensity'), value: m.density.toFixed(3) },
+        { label: t('metricWeakComponents'), value: String(m.weaklyConnectedComponents) },
+        { label: t('metricDiameter'), value: String(m.diameter) },
+    ];
+}
+/** Trigger a browser download of the rendered document. */
+async function download(format, rankdir, render) {
+    const content = await render(format, rankdir);
+    const mime = format === 'json' ? 'application/json' : format === 'dot' ? 'text/vnd.graphviz' : 'image/svg+xml';
+    const blob = new Blob([content], { type: mime });
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = `plugin-topology.${format}`;
+    document.body.append(anchor);
+    anchor.click();
+    anchor.remove();
+    URL.revokeObjectURL(url);
+}
+/** Group unresolved dependencies per plugin, so one row carries every missing service. */
+function unresolvedRows(analysis) {
+    const labels = new Map(analysis.graph.nodes
+        .filter(node => node.kind === 'plugin')
+        .map(node => [node.id, node.label]));
+    const groups = new Map();
+    for (const dep of analysis.graph.unresolved) {
+        let group = groups.get(dep.plugin);
+        if (group === undefined) {
+            const name = labels.get(dep.plugin) ?? dep.plugin;
+            group = { id: dep.plugin, plugin: `${name} [${dep.plugin.replace(/^p:/, '')}]`, state: dep.state, reasons: [] };
+            groups.set(dep.plugin, group);
+        }
+        group.reasons.push(dep.service);
+    }
+    return [...groups.values()].map(group => ({
+        key: group.id,
+        plugin: group.plugin,
+        state: group.state,
+        reasons: group.reasons,
+    }));
+}
+/** The plugin dependency graph view, rendered inside the global footer-action panel. */
+export function TopologyView({ useStore, actions, analyze, render, t }) {
+    const [request, setRequest] = useState(0);
+    const [state, setState] = useState({ status: 'loading' });
+    const [unresolvedOpen, setUnresolvedOpen] = useState(false);
+    const [rankdir, setRankdir] = useState('LR');
+    const transform = useStore(store => store.transform);
+    useEffect(() => {
+        let current = true;
+        void Promise.all([analyze(), render('svg', rankdir)]).then(([analysis, svg]) => { if (current)
+            setState({ status: 'ready', analysis, svg }); }, (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error('[plugin-topology] load failed:', error);
+            if (current)
+                setState({ status: 'error', message });
+        });
+        return () => { current = false; };
+    }, [request, rankdir, analyze, render]);
+    const retry = () => {
+        setState({ status: 'loading' });
+        setRequest(value => value + 1);
+    };
+    const onTransformChange = (next) => { actions.setTransform(next); };
+    const onRankdirChange = (next) => {
+        if (next === rankdir)
+            return;
+        actions.setTransform(null);
+        setRankdir(next);
+    };
+    return (_jsxs("div", { className: css.root, "data-plugin-topology-view": "", children: [state.status === 'loading' ? _jsx("p", { className: css.status, children: t('loading') }) : null, state.status === 'error' ? (_jsxs("div", { className: css.failure, children: [_jsx("p", { className: css.status, role: "alert", children: t('error') }), _jsx("pre", { className: css.errorDetail, children: state.message }), _jsx(OutlineButton, { onClick: retry, children: t('retry') })] })) : null, state.status === 'ready' ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: css.toolbar, children: [_jsx("div", { className: css.summaryGroup, children: _jsx("div", { className: css.metricStrip, children: metricRows(state.analysis, t).map(row => (_jsxs("span", { className: row.warning === true ? `${css.stat} ${css.statAlert}` : css.stat, children: [_jsx("span", { className: css.statLabel, children: row.label }), row.expandable === true ? (_jsxs("button", { type: "button", className: css.statToggle, "aria-expanded": unresolvedOpen, onClick: () => { setUnresolvedOpen(value => !value); }, children: [_jsx("span", { className: css.statValue, children: row.value }), _jsx(IconChevronDownOutline14, { className: unresolvedOpen ? `${css.statChevron} ${css.statChevronOpen}` : css.statChevron })] })) : (_jsx("span", { className: css.statValue, children: row.value }))] }, row.label))) }) }), _jsxs("div", { className: css.actions, children: [_jsxs("div", { className: css.rankdirGroup, role: "group", "aria-label": t('rankdirToggle'), children: [_jsx("button", { type: "button", className: css.rankdirOption, "aria-pressed": rankdir === 'TB', onClick: () => { onRankdirChange('TB'); }, children: "TD" }), _jsx("button", { type: "button", className: css.rankdirOption, "aria-pressed": rankdir === 'LR', onClick: () => { onRankdirChange('LR'); }, children: "LR" })] }), DOWNLOAD_FORMATS.map(({ format, labelKey }) => (_jsx(OutlineButton, { icon: _jsx(IconDownloadOutline16, { size: 14 }), onClick: () => { void download(format, rankdir, render); }, children: t(labelKey) }, format)))] })] }), unresolvedOpen ? (_jsx("div", { className: css.unresolvedPanel, children: _jsx("div", { className: css.unresolvedScroll, children: _jsxs("table", { className: css.unresolvedTable, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", className: css.unresolvedColPlugin, children: t('unresolvedPlugin') }), _jsx("th", { scope: "col", className: css.unresolvedColState, children: t('unresolvedState') }), _jsx("th", { scope: "col", children: t('unresolvedService') })] }) }), _jsx("tbody", { children: unresolvedRows(state.analysis).map(row => (_jsxs("tr", { children: [_jsx("td", { className: css.unresolvedPlugin, children: row.plugin }), _jsx("td", { className: css.unresolvedState, children: row.state }), _jsx("td", { className: css.unresolvedService, children: row.reasons.join(' · ') })] }, row.key))) })] }) }) })) : null, _jsxs("div", { className: css.legend, role: "note", "aria-label": t('legendLabel'), children: [_jsxs("span", { className: css.legendItem, children: [_jsx("span", { className: `${css.legendSwatch} ${css.legendIsolatedBox}`, "aria-hidden": true }), t('legendIsolated')] }), _jsxs("span", { className: css.legendItem, children: [_jsx("span", { className: `${css.legendSwatch} ${css.legendUnresolvedBox}`, "aria-hidden": true }), t('legendUnresolved')] }), _jsxs("span", { className: css.legendItem, children: [_jsx("code", { className: css.legendIdSample, children: "[42]" }), t('legendId')] })] }), _jsx("div", { className: css.body, children: _jsx(TopologyGraphView, { svg: state.svg, alt: t('title'), height: "100%", transform: transform, onTransformChange: onTransformChange, zoomInLabel: t('zoomIn'), zoomOutLabel: t('zoomOut'), resetViewLabel: t('resetView'), zoomLevelLabel: t('zoomLevel') }) })] })) : null] }));
+}

package/lib/client/icons.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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
+ * SVG in the `currentColor` convention.
+ * @module @sleetdrop/dsh-plugin-topology/client/icons
+ */
+import type { ReactNode } from 'react';
+export interface IconProps {
+    readonly size?: number;
+    readonly className?: string;
+}
+/** Stroke-free minus glyph, matching the plus geometry. */
+export declare function IconMinusOutline16({ size, className }: IconProps): ReactNode;
+/** Stroke-free plus glyph. */
+export declare function IconPlusOutline16({ size, className }: IconProps): ReactNode;
+/** Close cross glyph. */
+export declare function IconCloseOutline16({ size, className }: IconProps): ReactNode;
+/** Down chevron for expandable stats. */
+export declare function IconChevronDownOutline14({ size, className }: IconProps): ReactNode;
+/** Download arrow glyph. */
+export declare function IconDownloadOutline16({ size, className }: IconProps): ReactNode;
+/** Fullscreen / fit glyph. */
+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). */
+export declare function OutlineButton({ children, onClick, title, icon, }: {
+    children: ReactNode;
+    onClick: () => void;
+    title?: string;
+    icon?: ReactNode;
+}): ReactNode;