@sleetdrop/dsh-plugin-topology 0.4.0 → 0.5.0

package/NEXT-STEPS.md

@@ -17,16 +17,23 @@ unresolved dependencies (red stroke). Color nodes by state instead:
 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.
+Worth noting the boundary: when DSH cannot boot at all, this panel cannot
+render either, so pre-boot diagnosis belongs to a CLI tool. State coloring
+targets the other case — DSH runs, but some plugin misbehaved.
 
 ## 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.
+- Transitively affected plugins ("if I remove X, what breaks?"). Deferred:
+  direct in/out degree already covers the common question, and transitive
+  closure is a query better served by the JSON export than by the picture.
+
+## Done
+
+- **Click a node for details** — shipped in `0.5.0` as a node-anchored popover
+  (state, module source, drawn in/out degree, npm link) with `deg⁺`/`deg⁻`
+  toggles that light one dependency direction at a time. The SVG moved from an
+  `<img>` to inline rendering; highlight classes are applied to the Graphviz DOM
+  and never baked into the exported SVG.

package/README.md

@@ -67,6 +67,26 @@ 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.
 
+### Node inspection
+
+The SVG renders inline, so the graph is interactive without baking anything
+into the export — a downloaded SVG still opens clean in any viewer.
+
+- **Hover** raises a light ring on the node, nothing else.
+- **Click** opens a card anchored to that node (it tracks the node through pan
+  and zoom). The card shows only what needs a running process to know: the
+  fiber `state`, the module `source`, and the drawn in/out degree. The name
+  links to the npm page for everything that does not (version, description,
+  license, repository).
+- **`deg⁺` / `deg⁻`** are pill toggles for the graph-theory out-/in-degree as
+  drawn in the collapsed projection. Tapping one lights exactly that
+  direction's dependency edges and their far ends while the rest fades; tapping
+  it again clears. They are disabled at zero.
+
+Degree counts are read from the rendered SVG rather than the raw snapshot, so a
+merged node reports the edges actually drawn after the projection collapses
+same-named instances.
+
 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.
@@ -79,7 +99,7 @@ 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.7-rc.2`; the `peerDependencies`
+Current release targets DeepSeek Harness `0.2.0-rc.2`; the `peerDependencies`
 pin the client packages and `@deepseek-ai/cordis@^4.0.4` 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
@@ -101,6 +121,7 @@ releases only and skips the fast-moving `alpha` line.
 | `0.3.0` | `0.1.5-rc.1` | Dependency refresh for DSH 0.1.5-rc.1; no code changes required. |
 | `0.3.1` | `0.1.5-rc.3` | Peer refresh to DSH 0.1.5-rc.3 (same 0.1.5 rc line). |
 | `0.4.0` | `0.1.7-rc.2` | TypertCodec API migration (`schema` → `create`); cordis ^4.0.4. |
+| `0.5.0` | `0.2.0-rc.2` | Node detail popover + direction-scoped dependency highlight; panel colors rebound to the real DSH theme tokens (dark theme); peer refresh to DSH 0.2.0-rc.2 (no code changes required). |
 
 ## Known Limitations
 
@@ -121,8 +142,8 @@ pnpm run typecheck  # noEmit check
 ```
 
 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.
+platform-module rows (`react`, `react/jsx-runtime`, and
+`@deepseek-ai/dsh-client-store`), which every supported harness shell serves.
 
 See [NEXT-STEPS.md](NEXT-STEPS.md) for planned renderer improvements.
 
@@ -147,8 +168,8 @@ store avoids the npm cache entirely:
 pnpm publish                    # same prepublishOnly gate, pnpm store
 ```
 
-`files` ships `lib/`, `cordis.patch.yml`, and `overlay.example.yml`; npm adds
-README and LICENSE automatically.
+`files` ships `lib/`, `cordis.patch.yml`, `overlay.example.yml`, and
+`NEXT-STEPS.md`; npm adds README and LICENSE automatically.
 
 ## License
 

package/lib/client/NodeDetailPanel.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+import type { PluginNode, TopologyAnalysis } from '../types.ts';
+import type { PluginTopologyLocaleKey } from './locales.ts';
+/** The currently selected node's detail data, derived from the analysis. */
+export interface NodeDetail {
+    readonly node: PluginNode;
+    readonly dependsOnCount: number;
+    readonly dependedByCount: number;
+    readonly unresolvedCount: number;
+}
+export interface NodeDetailPanelProps {
+    readonly detail: NodeDetail;
+    readonly analysis: TopologyAnalysis;
+    /** Which dependency direction is currently highlighted on the graph, if any. */
+    readonly highlightDirection: 'depends-on' | 'depended-by' | null;
+    readonly onHighlight: (direction: 'depends-on' | 'depended-by' | null) => void;
+    readonly onClose: () => void;
+    readonly t: (key: PluginTopologyLocaleKey) => string;
+}
+/**
+ * Side panel showing runtime-only information about the selected plugin node.
+ * Displays name (linked to npm), state badge, source path, dependency counts
+ * (clickable to highlight edges on the graph), and unresolved dependency count.
+ */
+export declare function NodeDetailPanel({ detail, highlightDirection, onHighlight, onClose, t, }: NodeDetailPanelProps): ReactNode;

package/lib/client/NodeDetailPanel.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { IconCloseOutline16 } from "./icons.js";
+import css from './NodeDetailPanel.module.css';
+/** Build an npm registry URL from a source specifier, or null for local paths. */
+function npmUrl(source) {
+    if (source === undefined)
+        return null;
+    // npm package names: @scope/name or bare-name (no path separators beyond scope)
+    if (source.startsWith('/') || source.startsWith('.') || source.includes(':\\'))
+        return null;
+    return `https://www.npmjs.com/package/${encodeURIComponent(source)}`;
+}
+function stateBadgeClass(state) {
+    if (state === 'ACTIVE')
+        return `${css.stateBadge} ${css.stateActive}`;
+    if (state === 'FAILED')
+        return `${css.stateBadge} ${css.stateFailed}`;
+    return `${css.stateBadge} ${css.stateOther}`;
+}
+/**
+ * Side panel showing runtime-only information about the selected plugin node.
+ * Displays name (linked to npm), state badge, source path, dependency counts
+ * (clickable to highlight edges on the graph), and unresolved dependency count.
+ */
+export function NodeDetailPanel({ detail, highlightDirection, onHighlight, onClose, t, }) {
+    const { node, dependsOnCount, dependedByCount, unresolvedCount } = detail;
+    const url = npmUrl(node.source);
+    const toggleHighlight = (direction) => {
+        onHighlight(highlightDirection === direction ? null : direction);
+    };
+    return (_jsxs("aside", { className: css.panel, "aria-label": t('detailClose'), children: [_jsxs("div", { className: css.header, children: [url !== null ? (_jsx("a", { className: css.nameLink, href: url, target: "_blank", rel: "noopener noreferrer", children: node.label })) : (_jsx("span", { className: css.nameLink, style: { color: 'var(--dsw-text-primary, #0f172a)' }, children: node.label })), _jsx("button", { type: "button", className: css.closeButton, onClick: onClose, "aria-label": t('detailClose'), children: _jsx(IconCloseOutline16, { size: 14 }) })] }), _jsx("span", { className: stateBadgeClass(node.state), children: node.state }), node.source !== undefined && (_jsxs("div", { className: css.row, children: [_jsx("span", { className: css.rowLabel, children: t('detailSource') }), _jsx("span", { className: `${css.rowValue} ${css.sourceValue}`, children: node.source })] })), _jsxs("div", { className: css.row, children: [_jsx("span", { className: css.rowLabel, children: t('detailDependsOn') }), _jsx("button", { type: "button", className: highlightDirection === 'depends-on' ? `${css.countButton} ${css.countButtonActive}` : css.countButton, onClick: () => { toggleHighlight('depends-on'); }, disabled: dependsOnCount === 0, children: dependsOnCount })] }), _jsxs("div", { className: css.row, children: [_jsx("span", { className: css.rowLabel, children: t('detailDependedBy') }), _jsx("button", { type: "button", className: highlightDirection === 'depended-by' ? `${css.countButton} ${css.countButtonActive}` : css.countButton, onClick: () => { toggleHighlight('depended-by'); }, disabled: dependedByCount === 0, children: dependedByCount })] }), unresolvedCount > 0 && (_jsxs("div", { className: css.row, children: [_jsx("span", { className: css.rowLabel, children: t('detailUnresolved') }), _jsx("span", { className: `${css.rowValue} ${css.unresolvedValue}`, children: unresolvedCount })] }))] }));
+}

package/lib/client/NodePopover.d.ts

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+import type { HighlightDirection } from './TopologyGraphView.tsx';
+import type { TopologyAnalysis } from '../types.ts';
+import type { PluginTopologyLocaleKey } from './locales.ts';
+export interface PopoverData {
+    /** Stable element id of the selected node in the SVG. */
+    readonly key: string;
+    /** DOT node id (`p:3` / `m:0`). */
+    readonly nodeId: string;
+    readonly label: string;
+    /** Tap point in graph coordinates; the durable anchor across pan and zoom. */
+    readonly anchorX: number;
+    readonly anchorY: number;
+    /** Viewport-relative x derived from the live transform. */
+    readonly x: number;
+    /** Viewport-relative y derived from the live transform. */
+    readonly y: number;
+    /** Outgoing direct dependencies (deg⁺) as drawn. */
+    readonly outCount: number;
+    /** Incoming direct dependents (deg⁻) as drawn. */
+    readonly inCount: number;
+}
+export interface NodePopoverProps {
+    readonly popover: PopoverData;
+    readonly analysis: TopologyAnalysis;
+    /** Currently highlighted direction, or null when only the node is selected. */
+    readonly direction: HighlightDirection | null;
+    /** Toggle one direction's edge highlight on or off. */
+    readonly onToggleDirection: (direction: HighlightDirection) => void;
+    readonly onClose: () => void;
+    readonly t: (key: PluginTopologyLocaleKey) => string;
+}
+/**
+ * Floating detail card anchored to a clicked graph node. It shows only facts
+ * that need the running process to know (state, load source, drawn in/out
+ * degree) and links the name out to npm for everything else. The deg⁺/deg⁻
+ * pills drive the graph highlight, so the panel itself stays a one-screen read.
+ */
+export declare function NodePopover({ popover, analysis, direction, onToggleDirection, onClose, t, }: NodePopoverProps): ReactNode;

package/lib/client/NodePopover.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { IconCloseOutline16 } from "./icons.js";
+import css from './NodePopover.module.css';
+/** Gap between the anchor and the card's top-left corner, in px. */
+const OFFSET = 8;
+/** Build an npm registry URL from a source specifier, or null for local paths. */
+function npmUrl(source) {
+    if (source === undefined)
+        return null;
+    if (source.startsWith('/') || source.startsWith('.') || source.includes(':\\'))
+        return null;
+    return `https://www.npmjs.com/package/${encodeURIComponent(source)}`;
+}
+function stateBadgeClass(state) {
+    if (state === 'ACTIVE')
+        return `${css.stateBadge} ${css.stateActive}`;
+    if (state === 'FAILED')
+        return `${css.stateBadge} ${css.stateFailed}`;
+    return `${css.stateBadge} ${css.stateOther}`;
+}
+/** The worst lifecycle state in a group, so a broken instance is never hidden. */
+function worstState(states) {
+    if (states.includes('FAILED'))
+        return 'FAILED';
+    if (states.includes('PENDING'))
+        return 'PENDING';
+    return states[0] ?? 'ACTIVE';
+}
+/**
+ * Resolve the runtime facts the panel shows. Single instances map straight to a
+ * snapshot node; merged render nodes (`m:N`, several same-named instances drawn
+ * as one) are recovered from the ordinals in the rendered label.
+ */
+function resolveNode(nodeId, svgLabel, analysis) {
+    const direct = analysis.collapsed.nodes.find(node => node.id === nodeId);
+    if (direct !== undefined) {
+        return {
+            node: direct,
+            unresolved: analysis.graph.unresolved.filter(dep => dep.plugin === nodeId).length,
+        };
+    }
+    const bracket = svgLabel.match(/\[([^\]]*)\]\s*$/);
+    const baseName = svgLabel.replace(/\s*\[[^\]]*\]\s*$/, '').trim();
+    const ordinals = bracket === null
+        ? []
+        : bracket[1].split(',').map(part => part.trim()).filter(part => part !== '' && part !== '…');
+    let members = analysis.collapsed.nodes.filter(node => node.label === baseName);
+    if (ordinals.length > 0) {
+        const wanted = new Set(ordinals.map(ordinal => `p:${ordinal}`));
+        const matched = members.filter(node => wanted.has(node.id));
+        if (matched.length > 0)
+            members = matched;
+    }
+    const source = members.find(member => member.source !== undefined)?.source;
+    const node = {
+        id: nodeId,
+        kind: 'plugin',
+        label: baseName === '' ? svgLabel : baseName,
+        state: worstState(members.map(member => member.state)),
+        parent: null,
+        inject: [],
+        ...(source === undefined ? {} : { source }),
+    };
+    const unresolved = members.reduce((total, member) => total + analysis.graph.unresolved.filter(dep => dep.plugin === member.id).length, 0);
+    return { node, unresolved };
+}
+/**
+ * Floating detail card anchored to a clicked graph node. It shows only facts
+ * that need the running process to know (state, load source, drawn in/out
+ * degree) and links the name out to npm for everything else. The deg⁺/deg⁻
+ * pills drive the graph highlight, so the panel itself stays a one-screen read.
+ */
+export function NodePopover({ popover, analysis, direction, onToggleDirection, onClose, t, }) {
+    const ref = useRef(null);
+    const { node, unresolved } = resolveNode(popover.nodeId, popover.label, analysis);
+    const url = npmUrl(node.source);
+    // Track the anchor on every pan/zoom. The card sits just off the tap point,
+    // clamped inside the viewport so it stays readable and slides along the edge
+    // once its node scrolls out instead of being left behind.
+    useEffect(() => {
+        const el = ref.current;
+        if (el === null)
+            return;
+        const parent = el.parentElement;
+        if (parent === null)
+            return;
+        const bounds = parent.getBoundingClientRect();
+        const own = el.getBoundingClientRect();
+        const maxLeft = Math.max(OFFSET, bounds.width - own.width - OFFSET);
+        const maxTop = Math.max(OFFSET, bounds.height - own.height - OFFSET);
+        el.style.left = `${Math.min(Math.max(OFFSET, popover.x + OFFSET), maxLeft)}px`;
+        el.style.top = `${Math.min(Math.max(OFFSET, popover.y + OFFSET), maxTop)}px`;
+    }, [popover.x, popover.y]);
+    return (_jsxs("div", { ref: ref, className: css.popover, style: { left: popover.x + OFFSET, top: popover.y + OFFSET }, role: "dialog", "aria-label": node.label, children: [_jsxs("div", { className: css.header, children: [url !== null ? (_jsx("a", { className: css.nameLink, href: url, target: "_blank", rel: "noopener noreferrer", children: node.label })) : (_jsx("span", { className: css.namePlain, children: node.label })), _jsx("button", { type: "button", className: css.closeButton, onClick: onClose, "aria-label": t('popoverClose'), children: _jsx(IconCloseOutline16, { size: 12 }) })] }), _jsxs("div", { className: css.metaRow, children: [_jsx("span", { className: stateBadgeClass(node.state), children: node.state }), unresolved > 0 && (_jsxs("span", { className: css.unresolvedBadge, children: [t('popoverUnresolved'), " ", unresolved] }))] }), node.source !== undefined && (_jsxs("div", { className: css.row, children: [_jsx("span", { className: css.rowLabel, children: t('popoverSource') }), _jsx("span", { className: `${css.rowValue} ${css.sourceValue}`, children: node.source })] })), _jsxs("div", { className: css.depPills, children: [_jsxs("button", { type: "button", className: direction === 'out' ? `${css.depPill} ${css.depPillActive}` : css.depPill, "aria-pressed": direction === 'out', "aria-label": t('popoverOutgoing'), title: t('popoverOutgoing'), disabled: popover.outCount === 0, onClick: () => { onToggleDirection('out'); }, children: [_jsx("span", { className: css.degMark, children: "deg\u207A" }), _jsx("span", { className: css.degValue, children: popover.outCount })] }), _jsxs("button", { type: "button", className: direction === 'in' ? `${css.depPill} ${css.depPillActive}` : css.depPill, "aria-pressed": direction === 'in', "aria-label": t('popoverIncoming'), title: t('popoverIncoming'), disabled: popover.inCount === 0, onClick: () => { onToggleDirection('in'); }, children: [_jsx("span", { className: css.degMark, children: "deg\u207B" }), _jsx("span", { className: css.degValue, children: popover.inCount })] })] })] }));
+}

package/lib/client/TopologyGraphView.d.ts

@@ -1,5 +1,35 @@
 import type { ReactNode } from 'react';
 import type { TopologyTransform } from './stores.ts';
+/** Dependency direction highlighted from the selected node. */
+export type HighlightDirection = 'out' | 'in';
+/** A node resolved from the composed SVG DOM. */
+export interface GraphNodeRef {
+    /** Stable element id (`node-p:3` / `iso-node-m:0`), unique across the composed SVG. */
+    readonly key: string;
+    /** DOT node id from the `<title>` text (`p:3` / `m:0`), used to match edge endpoints. */
+    readonly dotId: string;
+    /** Display label (`ApprovalService [60,96]`). */
+    readonly label: string;
+}
+/** Data passed when a graph node is tapped. */
+export interface NodeClickInfo {
+    /** Stable element id, echoed back as the selection key. */
+    readonly key: string;
+    /** DOT node id (`p:3` / `m:0`). */
+    readonly nodeId: string;
+    /** Display label as rendered, including the instance ordinals. */
+    readonly label: string;
+    /**
+     * Tap point in graph coordinates. Anchoring here rather than in viewport px
+     * keeps the popover attached to its node across pan and zoom.
+     */
+    readonly anchorX: number;
+    readonly anchorY: number;
+    /** Outgoing direct dependencies (deg⁺) as drawn in the current projection. */
+    readonly outCount: number;
+    /** Incoming direct dependents (deg⁻) as drawn in the current projection. */
+    readonly inCount: number;
+}
 /** Zoom/pan props plus the localized control labels and the shared transform. */
 export interface TopologyGraphViewProps {
     svg: string;
@@ -16,12 +46,25 @@ export interface TopologyGraphViewProps {
     resetViewLabel: string;
     /** Accessible name for the clickable zoom-level toggle. */
     zoomLevelLabel: string;
+    /** Called when a graph node is tapped; receives id, label, counts, and viewport coords. */
+    onNodeClick?: (info: NodeClickInfo) => void;
+    /** Called when empty space is tapped (to close the popover and drop the highlight). */
+    onEmptyClick?: () => void;
+    /** Element id of the selected node, or null when nothing is selected. */
+    selectedKey?: string | null;
+    /** DOT id of the selected node, used to match edge endpoints. */
+    selectedDotId?: string | null;
+    /** Active dependency direction to highlight; null means selection only. */
+    direction?: HighlightDirection | null;
 }
 /**
- * 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.
+ * Pan/zoom SVG viewer with drill-down interaction. 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.
+ *
+ * Hovering a node raises a ring; tapping it fires onNodeClick with viewport
+ * coordinates and the drawn deg⁺/deg⁻ counts. Tapping empty space fires
+ * onEmptyClick. `direction` lights only the chosen dependency direction.
  */
-export declare function TopologyGraphView({ svg, alt, height, transform, onTransformChange, zoomInLabel, zoomOutLabel, resetViewLabel, zoomLevelLabel, }: TopologyGraphViewProps): ReactNode;
+export declare function TopologyGraphView({ svg, alt, height, transform, onTransformChange, zoomInLabel, zoomOutLabel, resetViewLabel, zoomLevelLabel, onNodeClick, onEmptyClick, selectedKey, selectedDotId, direction, }: TopologyGraphViewProps): ReactNode;