@sleetdrop/dsh-plugin-topology 0.1.0

package/lib/client/icons.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Stroke-free minus glyph, matching the plus geometry. */
+export function IconMinusOutline16({ size = 16, className }) {
+    return (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: _jsx("path", { d: "M1.5 7.34961H14.5V8.65039H1.5Z", fill: "currentColor" }) }));
+}
+/** Stroke-free plus glyph. */
+export function IconPlusOutline16({ size = 16, className }) {
+    return (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: _jsx("path", { d: "M8.64453 1.5V7.34961H14.5V8.65039H8.64453V14.5H7.34473V8.65039H1.5V7.34961H7.34473V1.5H8.64453Z", fill: "currentColor" }) }));
+}
+/** Close cross glyph. */
+export function IconCloseOutline16({ size = 16, className }) {
+    return (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: _jsx("path", { d: "M8 6.93934L14.4697 0.46967L15.5303 1.53033L9.06066 8L15.5303 14.4697L14.4697 15.5303L8 9.06066L1.53033 15.5303L0.46967 14.4697L6.93934 8L0.46967 1.53033L1.53033 0.46967L8 6.93934Z", fill: "currentColor" }) }));
+}
+/** Down chevron for expandable stats. */
+export function IconChevronDownOutline14({ size = 14, className }) {
+    return (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 14 14", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: _jsx("path", { d: "M11.8486 5.5L11.4238 5.92383L8.69727 8.65137C8.44157 8.90706 8.21562 9.13382 8.01172 9.29785C7.79912 9.46883 7.55595 9.61756 7.25 9.66602C7.08435 9.69222 6.91565 9.69222 6.75 9.66602C6.44405 9.61756 6.20088 9.46883 5.98828 9.29785C5.78438 9.13382 5.55843 8.90706 5.30273 8.65137L2.57617 5.92383L2.15137 5.5L3 4.65137L3.42383 5.07617L6.15137 7.80273C6.42595 8.07732 6.59876 8.24849 6.74023 8.3623C6.87291 8.46904 6.92272 8.47813 6.9375 8.48047C6.97895 8.48703 7.02105 8.48703 7.0625 8.48047C7.07728 8.47813 7.12709 8.46904 7.25977 8.3623C7.40124 8.24849 7.57405 8.07732 7.84863 7.80273L10.5762 5.07617L11 4.65137L11.8486 5.5Z", fill: "currentColor" }) }));
+}
+/** Download arrow glyph. */
+export function IconDownloadOutline16({ 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("path", { d: "M7.29414 1.5H8.70586V9.88477L12.1963 6.39429L13.1963 7.39429L8 12.5906L2.80371 7.39429L3.80371 6.39429L7.29414 9.88477V1.5Z", fill: "currentColor" }), _jsx("path", { d: "M1.5 13.5V14.8H14.5V13.5H1.5Z", fill: "currentColor" })] }));
+}
+/** Fullscreen / fit glyph. */
+export function IconFullscreenOutline16({ 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("path", { d: "M1.5 1.5H6.5V2.8H2.8V6.5H1.5V1.5Z", fill: "currentColor" }), _jsx("path", { d: "M14.5 1.5H9.5V2.8H13.2V6.5H14.5V1.5Z", fill: "currentColor" }), _jsx("path", { d: "M1.5 14.5V9.5H2.8V13.2H6.5V14.5H1.5Z", fill: "currentColor" }), _jsx("path", { d: "M13.2 9.5H14.5V14.5H9.5V13.2H13.2V9.5Z", fill: "currentColor" })] }));
+}
+/** Plugin-mark glyph for the footer trigger. */
+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). */
+export function OutlineButton({ children, onClick, title, icon, }) {
+    const handle = (event) => {
+        event.preventDefault();
+        onClick();
+    };
+    return (_jsxs("button", { type: "button", className: "pluginTopologyButton", onClick: handle, title: title, children: [icon, _jsx("span", { children: children })] }));
+}

package/lib/client/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Browser half: a global plugin-topology panel reachable from the sidebar
+ * footer. A `sidebar.footer.action` occupant renders a trigger button and a
+ * 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.
+ * @module @sleetdrop/dsh-plugin-topology/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type PluginTopologyLocaleKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Plugin dependency graph view copy. */
+        'pluginTopology': PluginTopologyLocaleKey;
+    }
+}
+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 declare const inject: string[];
+/** Contribute the global topology panel trigger + panel to the sidebar footer. */
+export declare function apply(ctx: ClientContext): void;

package/lib/client/index.js

@@ -0,0 +1,76 @@
+/**
+ * Browser half: a global plugin-topology panel reachable from the sidebar
+ * footer. A `sidebar.footer.action` occupant renders a trigger button and a
+ * 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.
+ * @module @sleetdrop/dsh-plugin-topology/client
+ */
+// The generated Host Remote-descriptor contribution for this package.
+import topologyRemote from "./remote-client.js";
+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 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');
+    // 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) => {
+        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');
+        if (namespace === undefined) {
+            throw new Error('pluginTopology remote namespace is not mounted yet — reopen the panel');
+        }
+        return namespace;
+    };
+    ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register({
+        name: 'sidebar.footer.action',
+        id: 'plugin-topology',
+        order: 100,
+        locale: NS,
+        label: () => t('title'),
+        store: viewerStore,
+        inject: () => ({
+            analyze: async () => {
+                const result = await namespaceOf().analyze();
+                if (!result.ok) {
+                    throw new Error(`pluginTopology.analyze failed: ${result.error.code}: ${result.error.message}`);
+                }
+                return result.value;
+            },
+            render: async (format, rankdir) => {
+                const result = await namespaceOf().render(format, rankdir);
+                if (!result.ok) {
+                    throw new Error(`pluginTopology.render failed: ${result.error.code}: ${result.error.message}`);
+                }
+                return result.value;
+            },
+        }),
+    }, TopologyPanel));
+}

package/lib/client/locales.d.ts

@@ -0,0 +1,4 @@
+export declare const NS = "pluginTopology";
+export type PluginTopologyLocaleKey = 'title' | 'loading' | 'error' | 'retry' | 'zoomIn' | 'zoomOut' | 'resetView' | 'zoomLevel' | 'downloadSvg' | 'downloadDot' | 'downloadJson' | 'metricPlugins' | 'metricDependencies' | 'metricUnresolved' | 'metricDensity' | 'metricWeakComponents' | 'metricDiameter' | 'rankdirToggle' | 'unresolvedPlugin' | 'unresolvedService' | 'unresolvedState' | 'legendLabel' | 'legendUnresolved' | 'legendIsolated' | 'legendId';
+export declare const en: Record<PluginTopologyLocaleKey, string>;
+export declare const zh: Record<PluginTopologyLocaleKey, string>;

package/lib/client/locales.js

@@ -0,0 +1,55 @@
+export const NS = 'pluginTopology';
+export const en = {
+    title: 'Plugin topology',
+    loading: 'Loading…',
+    error: 'Failed to load the plugin topology',
+    retry: 'Retry',
+    zoomIn: 'Zoom in',
+    zoomOut: 'Zoom out',
+    resetView: 'Reset view',
+    zoomLevel: 'Zoom level',
+    downloadSvg: 'SVG',
+    downloadDot: 'DOT',
+    downloadJson: 'JSON',
+    metricPlugins: 'Plugins',
+    metricDependencies: 'Dependencies',
+    metricUnresolved: 'Unresolved dependencies',
+    metricDensity: 'Coupling density',
+    metricWeakComponents: 'Disconnected parts',
+    metricDiameter: 'Deepest dependency chain',
+    rankdirToggle: 'Layout direction',
+    unresolvedPlugin: 'Plugin',
+    unresolvedService: 'Missing service',
+    unresolvedState: 'State',
+    legendLabel: 'Legend',
+    legendUnresolved: 'Unresolved dependency',
+    legendIsolated: 'Isolated plugin',
+    legendId: 'Instance creation ordinal within this run',
+};
+export const zh = {
+    title: '插件拓扑',
+    loading: '加载中…',
+    error: '加载插件拓扑失败',
+    retry: '重试',
+    zoomIn: '放大',
+    zoomOut: '缩小',
+    resetView: '复位视图',
+    zoomLevel: '缩放比例',
+    downloadSvg: 'SVG',
+    downloadDot: 'DOT',
+    downloadJson: 'JSON',
+    metricPlugins: '插件数',
+    metricDependencies: '依赖数',
+    metricUnresolved: '未解析依赖',
+    metricDensity: '耦合密度',
+    metricWeakComponents: '不相连的部分',
+    metricDiameter: '最深依赖链',
+    rankdirToggle: '布局方向',
+    unresolvedPlugin: '插件',
+    unresolvedService: '缺失服务',
+    unresolvedState: '状态',
+    legendLabel: '图例',
+    legendUnresolved: '存在未解析依赖',
+    legendIsolated: '孤立插件（无依赖边）',
+    legendId: '本次运行内的创建序号',
+};

package/lib/client/panel.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import { type TopologyViewInjected, type ViewerStateSelector } from './TopologyView.tsx';
+import type { PluginTopologyLocaleKey } from './locales.ts';
+/** Props assembled by the slot renderer: store seat, injected face, and locale t. */
+export type TopologyPanelProps = {
+    /** Wide/rail layout flag supplied by the sidebar footer-action slot. */
+    wide?: boolean;
+    useStore: ViewerStateSelector;
+    actions: {
+        setTransform: (transform: {
+            x: number;
+            y: number;
+            k: number;
+        } | null) => void;
+    };
+    t: (key: PluginTopologyLocaleKey) => string;
+} & TopologyViewInjected;
+/** The plugin-topology panel content wrapper and its footer trigger. */
+export declare function TopologyPanel({ wide, useStore, actions, analyze, render, t, }: TopologyPanelProps): ReactNode;

package/lib/client/panel.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { IconCloseOutline16, IconFullscreenOutline16, IconPluginOutline16 } from "./icons.js";
+import { TopologyView } from "./TopologyView.js";
+import css from './panel.module.css';
+/** The plugin-topology panel content wrapper and its footer trigger. */
+export function TopologyPanel({ wide, useStore, actions, analyze, render, t, }) {
+    const rootRef = useRef(null);
+    const [open, setOpen] = useState(false);
+    // Open maximized by default: the Graphviz canvas needs the space.
+    const [maximized, setMaximized] = useState(true);
+    // Close on outside pointer; mounted only while open, so the listener
+    // lifetime is the panel's.
+    useEffect(() => {
+        if (!open)
+            return;
+        const onDown = (event) => {
+            const root = rootRef.current;
+            if (root === null)
+                return;
+            const panel = root.querySelector('[data-plugin-topology-panel]');
+            if (event.target instanceof Node && panel !== null && !panel.contains(event.target)) {
+                setOpen(false);
+            }
+        };
+        document.addEventListener('pointerdown', onDown);
+        return () => { document.removeEventListener('pointerdown', onDown); };
+    }, [open]);
+    // Escape closes the panel.
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKey = (event) => {
+            if (event.key === 'Escape')
+                setOpen(false);
+        };
+        window.addEventListener('keydown', onKey);
+        return () => { window.removeEventListener('keydown', onKey); };
+    }, [open]);
+    return (_jsxs("div", { ref: rootRef, className: css.layer, children: [_jsxs("button", { type: "button", className: css.trigger, "aria-haspopup": "dialog", "aria-expanded": open, onClick: () => { setOpen(value => !value); }, children: [_jsx(IconPluginOutline16, { size: wide === true ? 16 : 18 }), wide === true && _jsx("span", { className: css.triggerLabel, children: t('title') })] }), open && (_jsxs("section", { className: maximized ? `${css.panel} ${css.maximized}` : css.panel, "data-plugin-topology-panel": "", role: "dialog", "aria-modal": "true", "aria-label": t('title'), children: [_jsxs("header", { className: css.header, children: [_jsx("span", { className: css.title, children: t('title') }), _jsxs("div", { className: css.headerActions, children: [_jsx("button", { type: "button", className: css.close, "aria-label": t('resetView'), title: t('resetView'), onClick: () => { setMaximized(value => !value); }, children: _jsx(IconFullscreenOutline16, { size: 14 }) }), _jsx("button", { type: "button", className: css.close, "aria-label": t('title'), onClick: () => { setOpen(false); }, children: _jsx(IconCloseOutline16, { size: 14 }) })] })] }), _jsx("div", { className: css.body, children: _jsx(TopologyView, { useStore: useStore, actions: actions, analyze: analyze, render: render, t: t }) })] }))] }));
+}

package/lib/client/remote-client.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Host Remote-descriptor contribution consumed by the unary gateway client.
+ *
+ * This mirrors the artifact the `@deepseek-ai/dsh-typert-generator` would emit
+ * from the Host FaceModel. It is checked in verbatim rather than regenerated at
+ * build time so the standalone repo builds without the generator's workspace
+ * scan; when the generator is wired, replace this module with its output.
+ * @module @sleetdrop/dsh-plugin-topology/client/remote-client
+ */
+import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+export declare const TYPERT_REMOTE: TypertRemoteContribution;
+export default TYPERT_REMOTE;

package/lib/client/remote-client.js

@@ -0,0 +1,148 @@
+/**
+ * Host Remote-descriptor contribution consumed by the unary gateway client.
+ *
+ * This mirrors the artifact the `@deepseek-ai/dsh-typert-generator` would emit
+ * from the Host FaceModel. It is checked in verbatim rather than regenerated at
+ * build time so the standalone repo builds without the generator's workspace
+ * scan; when the generator is wired, replace this module with its output.
+ * @module @sleetdrop/dsh-plugin-topology/client/remote-client
+ */
+import { z } from 'zod';
+const analyze_result$schema = z.object({
+    'graph': z.object({
+        'kind': z.literal('bipartite').readonly(),
+        'generatedAt': z.string().readonly(),
+        'nodes': z.array(z.union([
+            z.object({
+                'id': z.string().readonly(),
+                'kind': z.literal('plugin').readonly(),
+                'label': z.string().readonly(),
+                'state': z.union([
+                    z.literal('PENDING'), z.literal('LOADING'), z.literal('ACTIVE'),
+                    z.literal('FAILED'), z.literal('DISPOSED'), z.literal('UNLOADING'),
+                ]).readonly(),
+                'parent': z.union([z.literal(null), z.string()]).readonly(),
+                'inject': z.array(z.string()).readonly(),
+                'source': z.string().readonly().optional(),
+            }),
+            z.object({
+                'id': z.string().readonly(),
+                'kind': z.literal('service').readonly(),
+                'label': z.string().readonly(),
+                'scope': z.string().readonly(),
+            }),
+        ])).readonly(),
+        'edges': z.array(z.object({
+            'source': z.string().readonly(),
+            'target': z.string().readonly(),
+            'kind': z.union([z.literal('provides'), z.literal('injects')]).readonly(),
+            'service': z.string().readonly(),
+        })).readonly(),
+        'unresolved': z.array(z.object({
+            'plugin': z.string().readonly(),
+            'service': z.string().readonly(),
+            'state': z.union([
+                z.literal('PENDING'), z.literal('LOADING'), z.literal('ACTIVE'),
+                z.literal('FAILED'), z.literal('DISPOSED'), z.literal('UNLOADING'),
+            ]).readonly(),
+        })).readonly(),
+    }).readonly(),
+    'collapsed': z.object({
+        'kind': z.literal('collapsed').readonly(),
+        'generatedAt': z.string().readonly(),
+        'nodes': z.array(z.object({
+            'id': z.string().readonly(),
+            'kind': z.literal('plugin').readonly(),
+            'label': z.string().readonly(),
+            'state': z.union([
+                z.literal('PENDING'), z.literal('LOADING'), z.literal('ACTIVE'),
+                z.literal('FAILED'), z.literal('DISPOSED'), z.literal('UNLOADING'),
+            ]).readonly(),
+            'parent': z.union([z.literal(null), z.string()]).readonly(),
+            'inject': z.array(z.string()).readonly(),
+            'source': z.string().readonly().optional(),
+        })).readonly(),
+        'edges': z.array(z.object({
+            'source': z.string().readonly(),
+            'target': z.string().readonly(),
+            'service': z.string().readonly(),
+        })).readonly(),
+    }).readonly(),
+    'nodeMetrics': z.record(z.string(), z.object({
+        'inDegree': z.number().readonly(),
+        'outDegree': z.number().readonly(),
+        'degreeCentrality': z.number().readonly(),
+        'betweennessCentrality': z.number().readonly(),
+        'eigenvectorCentrality': z.number().readonly(),
+        'pagerank': z.number().readonly(),
+    })).readonly(),
+    'graphMetrics': z.object({
+        'nodeCount': z.number().readonly(),
+        'edgeCount': z.number().readonly(),
+        'density': z.number().readonly(),
+        'stronglyConnectedComponents': z.number().readonly(),
+        'largestSccSize': z.number().readonly(),
+        'isDag': z.boolean().readonly(),
+        'weaklyConnectedComponents': z.number().readonly(),
+        'diameter': z.number().readonly(),
+        'averagePathLength': z.number().readonly(),
+        'sourceCount': z.number().readonly(),
+        'sinkCount': z.number().readonly(),
+    }).readonly(),
+});
+const render_parameter_0$schema = z.union([z.literal('json'), z.literal('dot'), z.literal('svg')]);
+const render_parameter_1$schema = z.union([z.literal('TB'), z.literal('LR')]);
+const render_result$schema = z.string();
+export const TYPERT_REMOTE = {
+    package: '@sleetdrop/dsh-plugin-topology',
+    descriptors: [
+        {
+            id: '@sleetdrop/dsh-plugin-topology#pluginTopology/analyze',
+            service: 'pluginTopology',
+            namespace: 'pluginTopology',
+            method: 'analyze',
+            invocation: { kind: 'direct' },
+            parameters: [],
+            result: {
+                mode: 'strict',
+                typeSymbol: '@sleetdrop/dsh-plugin-topology/types#TopologyAnalysis',
+                schema: analyze_result$schema,
+            },
+        },
+        {
+            id: '@sleetdrop/dsh-plugin-topology#pluginTopology/render',
+            service: 'pluginTopology',
+            namespace: 'pluginTopology',
+            method: 'render',
+            invocation: { kind: 'direct' },
+            parameters: [
+                {
+                    name: 'format',
+                    wire: 'format',
+                    source: 'json',
+                    codec: {
+                        mode: 'strict',
+                        typeSymbol: '@sleetdrop/dsh-plugin-topology/types#RenderFormat',
+                        schema: render_parameter_0$schema,
+                    },
+                },
+                {
+                    name: 'rankdir',
+                    wire: 'rankdir',
+                    source: 'json',
+                    codec: {
+                        mode: 'strict',
+                        typeSymbol: '@sleetdrop/dsh-plugin-topology/types#Rankdir',
+                        schema: render_parameter_1$schema,
+                    },
+                },
+            ],
+            result: {
+                mode: 'strict',
+                typeSymbol: '@sleetdrop/dsh-plugin-topology#pluginTopology/render:result',
+                schema: render_result$schema,
+            },
+        },
+    ],
+};
+export default TYPERT_REMOTE;

package/lib/client/stores.d.ts

@@ -0,0 +1,25 @@
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+/** The pan/zoom transform of the graph viewport. */
+export interface TopologyTransform {
+    /** Horizontal translate in px. */
+    x: number;
+    /** Vertical translate in px. */
+    y: number;
+    /** Scale factor (1 = fit-to-viewport). */
+    k: number;
+}
+/** Viewer state: the remembered transform, or null until the first fit lands. */
+type ViewerState = {
+    transform: TopologyTransform | null;
+};
+type ViewerActions = {
+    setTransform: (draft: ViewerState, transform: TopologyTransform | null) => void;
+};
+/**
+ * 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 {};

package/lib/client/stores.js

@@ -0,0 +1,15 @@
+import { defineStore } from '@deepseek-ai/dsh-client-runtime/client';
+/**
+ * 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 function createTopologyViewStore() {
+    return defineStore({
+        init: () => ({ transform: null }),
+        actions: {
+            setTransform: (d, transform) => { d.transform = transform; },
+        },
+    });
+}

package/lib/client/useDismissOnOutsidePointer.d.ts

@@ -0,0 +1,9 @@
+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.
+ * @param ref - root element the interaction belongs to.
+ * @param open - whether the popover is currently open.
+ * @param setOpen - close state setter.
+ */
+export declare function useDismissOnOutsidePointer(ref: RefObject<HTMLElement | null>, open: boolean, setOpen: (open: boolean) => void): void;

package/lib/client/useDismissOnOutsidePointer.js

@@ -0,0 +1,23 @@
+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.
+ * @param ref - root element the interaction belongs to.
+ * @param open - whether the popover is currently open.
+ * @param setOpen - close state setter.
+ */
+export function useDismissOnOutsidePointer(ref, open, setOpen) {
+    useEffect(() => {
+        if (!open)
+            return;
+        const onDown = (event) => {
+            const root = ref.current;
+            if (root === null)
+                return;
+            if (event.target instanceof Node && !root.contains(event.target))
+                setOpen(false);
+        };
+        document.addEventListener('pointerdown', onDown);
+        return () => { document.removeEventListener('pointerdown', onDown); };
+    }, [ref, open, setOpen]);
+}