@dimina-kit/inspect 0.3.0-dev.20260711141929

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EchoTechFE and dimina-kit contributors
+
+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/README.md

@@ -0,0 +1,56 @@
+# @dimina-kit/inspect
+
+Host-agnostic runtime inspection for dimina mini-programs: WXML tree
+extraction and Storage inspection. One package owns the protocol types, the
+pure logic (Vue-runtime walk, stable-id registry, mutation-observing
+inspector, storage-event reduction), the React panels, and the panels' data
+wiring — so the Electron devtools and any downstream host (browser workbench,
+preview iframe) share a single implementation and stay wire-compatible.
+
+## Entry points
+
+- `@dimina-kit/inspect` — core, zero runtime dependencies:
+  - `WxmlNode` / `ElementInspection` — the wire-format types. Hosts transport
+    them over IPC, `postMessage` or anything else.
+  - `walkInstance(instance, depth)` — walks a mounted dimina render-layer Vue
+    instance (`document.body.__vue_app__`) into a `WxmlNode` tree.
+  - `registerSyntheticSid` / `findElementBySid` — stable element ids without
+    writing `data-*` attributes into the page.
+  - `createWxmlInspector(options)` — bundles the above into the surface a
+    host injects into the render document: `getWxml()`,
+    `highlightElement(sid)` (measure-only), `elementFor(sid)`,
+    `setObserving(on)` (debounced `onMutated` callback while a panel is
+    visible), `dispose()`.
+  - `StorageItem` / `StorageEvent` / `StorageWriteResult` — the Storage
+    wire-format types, plus `applyStorageEvent(items, evt)`, the pure
+    reducer that folds a change feed into an item list.
+- `@dimina-kit/inspect/panel` — the React layer (React ≥ 18 peer):
+  - `WxmlPanel` / `StoragePanel` — the pure views (props in, no data wiring).
+  - `ConnectedWxmlPanel` / `ConnectedStoragePanel` — the panels' data wiring,
+    written once against their source contracts: seed on the
+    (enabled && active) rising edge, live updates via the push subscription,
+    visibility gating, hover inspection (WXML) / write forwarding (Storage).
+    Hosts render them with their source implementation and never duplicate
+    the wiring.
+  - Styling uses Tailwind utility classes over CSS variables
+    (`--color-code-blue`, `--color-surface-2`, …); the consuming app provides
+    the Tailwind theme mapping and variable values, and must include this
+    package's sources in its Tailwind content scan.
+- `WxmlPanelSource` (main entry, type-only) — the five-operation transport
+  contract behind the WXML panel: `getSnapshot` / `subscribe` / `setActive` /
+  `inspect` / `clearInspection`. Each host implements only how these travel
+  (Electron IPC channels, preview-iframe postMessage, …).
+- `StoragePanelSource` (main entry, type-only) — the Storage counterpart:
+  `getSnapshot` / `subscribe` / `setActive` / `setItem` / `removeItem` /
+  `clear` / `clearAll?` / `getPrefix`. `clearAll` is optional — hosts whose
+  storage partition is shared with non-mini-program data must omit it, and
+  the panel then hides the origin-wide wipe entirely.
+
+## Contract notes
+
+- Every inspector method is read-only on the page. Visual highlighting is the
+  host's job (CDP overlay, DOM overlay, …).
+- `setObserving(true)` is only meant to be on while a WXML panel is visible —
+  the tree walk is not free, so hosts gate it on panel visibility.
+- After a render-document reload the injected realm (and its sid registry) is
+  gone: the host must re-inject and re-push a full snapshot.

package/dist/connected-panel.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The WXML panel's data wiring, written once against WxmlPanelSource: seed on
+// the (enabled && active) rising edge, stay live through the push
+// subscription, forward the visibility gate, and route hover inspection.
+// Hosts render this with their transport implementation (Electron IPC,
+// preview-iframe postMessage, …) and the pure WxmlPanel view underneath never
+// needs host-specific code.
+import { useState } from 'react';
+import { WxmlPanel } from './panel-view.js';
+import { useSourceWiring } from './use-source-wiring.js';
+export function ConnectedWxmlPanel({ source, active = true, enabled = true, isRuntimeRunning = true, }) {
+    const [tree, setTree] = useState(null);
+    useSourceWiring({
+        source,
+        enabled,
+        active,
+        subscribe: s => s.subscribe(setTree),
+        seed: (s, isDisposed) => {
+            void s.getSnapshot().then((next) => {
+                if (!isDisposed())
+                    setTree(next);
+            });
+        },
+    });
+    return (_jsx(WxmlPanel, { tree: tree, onInspectElement: sid => source.inspect(sid), onClearInspection: async () => {
+            await source.clearInspection();
+        }, isRuntimeRunning: isRuntimeRunning }));
+}

package/dist/connected-storage-panel.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The Storage panel's data wiring, written once against StoragePanelSource:
+// seed on the (enabled && active) rising edge, stay live by reducing the
+// push subscription's StorageEvents into the item list, forward the
+// visibility gate, and route the panel's writes. Hosts render this with
+// their transport implementation (Electron IPC, same-origin localStorage +
+// `storage` events, …) and the pure StoragePanel view underneath never
+// needs host-specific code.
+import { useState } from 'react';
+import { StoragePanel } from './storage-panel-view.js';
+import { applyStorageEvent } from './storage-reducer.js';
+import { useSourceWiring } from './use-source-wiring.js';
+export function ConnectedStoragePanel({ source, active = true, enabled = true, isRuntimeRunning = true, }) {
+    const [items, setItems] = useState([]);
+    useSourceWiring({
+        source,
+        enabled,
+        active,
+        subscribe: s => s.subscribe((evt) => {
+            setItems(prev => applyStorageEvent(prev, evt));
+        }),
+        seed: (s, isDisposed) => {
+            void s.getSnapshot().then((next) => {
+                if (!isDisposed())
+                    setItems(next);
+            });
+        },
+    });
+    // clearAll is re-bound per source: passing it through only when the source
+    // has the capability is what makes the view hide the origin-wide wipe.
+    const clearAll = source.clearAll?.bind(source);
+    return (_jsx(StoragePanel, { items: items, onSet: (key, value) => source.setItem(key, value), onRemove: key => source.removeItem(key), onClear: () => source.clear(), onClearAll: clearAll, getPrefix: () => source.getPrefix(), isRuntimeRunning: isRuntimeRunning }));
+}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { SYNTHETIC_SID_PREFIX, registerSyntheticSid, findElementBySid, } from './sid-registry.js';
+export { walkInstance } from './wxml-extract.js';
+export { createWxmlInspector, } from './inspector.js';
+export { applyStorageEvent } from './storage-reducer.js';

package/dist/inspector.js

@@ -0,0 +1,122 @@
+// Host-agnostic WXML inspector over a render-layer document. It owns the
+// three read paths every host needs — Vue-tree walk (getWxml), sid → element
+// resolution (elementFor), element measurement (highlightElement) — plus the
+// visibility-gated DOM observer that debounces a setData burst into a single
+// onMutated callback. Hosts wire the callback to their own transport
+// (Electron bridge message, iframe postMessage, …) and draw any visual
+// highlight themselves: every method here is strictly read-only on the page.
+import { findElementBySid } from './sid-registry.js';
+import { walkInstance } from './wxml-extract.js';
+/** Coalesce a burst of setData-driven mutations into one notify per frame-ish. */
+const DEFAULT_DEBOUNCE_MS = 200;
+export function createWxmlInspector(options = {}) {
+    const doc = options.document ?? globalThis.document;
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const onMutated = options.onMutated;
+    const getVueApp = () => {
+        try {
+            const body = doc?.body;
+            const app = body?.__vue_app__;
+            if (!app)
+                return null;
+            if (app._instance)
+                return app._instance;
+            const container = app._container;
+            const vnode = container?._vnode;
+            return vnode?.component ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const getWxml = () => {
+        const instance = getVueApp();
+        if (!instance)
+            return null;
+        const tree = walkInstance(instance, 0);
+        if (!tree)
+            return null;
+        return Array.isArray(tree)
+            ? { tagName: '#fragment', attrs: {}, children: tree }
+            : tree;
+    };
+    const elementFor = (sid) => {
+        if (!sid)
+            return null;
+        return findElementBySid(doc, sid);
+    };
+    const highlightElement = (sid) => {
+        const el = elementFor(sid);
+        if (!el)
+            return null;
+        const rect = el.getBoundingClientRect();
+        const style = el.ownerDocument.defaultView?.getComputedStyle(el);
+        if (!style)
+            return null;
+        return {
+            sid,
+            rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            style: {
+                display: style.display,
+                position: style.position,
+                boxSizing: style.boxSizing,
+                margin: style.margin,
+                padding: style.padding,
+                color: style.color,
+                backgroundColor: style.backgroundColor,
+                fontSize: style.fontSize,
+            },
+        };
+    };
+    // getWxml/highlightElement are read-only, so the observer never re-triggers
+    // itself. Debounced so a setData burst coalesces into a single callback.
+    let observer = null;
+    let debounceTimer = null;
+    const notifyMutated = () => {
+        debounceTimer = null;
+        onMutated?.();
+    };
+    const setObserving = (on) => {
+        if (on) {
+            if (observer)
+                return;
+            observer = new MutationObserver(() => {
+                if (debounceTimer !== null)
+                    clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(notifyMutated, debounceMs);
+            });
+            // The host may enable observing before the page DOM is up. Observing a
+            // null body throws, so defer to DOMContentLoaded when needed — but bail
+            // if observing was turned off again before the body arrived.
+            const begin = () => {
+                if (!observer || !doc.body)
+                    return;
+                observer.observe(doc.body, {
+                    childList: true,
+                    subtree: true,
+                    attributes: true,
+                    characterData: true,
+                });
+            };
+            if (doc.body)
+                begin();
+            else
+                doc.addEventListener('DOMContentLoaded', begin, { once: true });
+        }
+        else {
+            if (debounceTimer !== null) {
+                clearTimeout(debounceTimer);
+                debounceTimer = null;
+            }
+            observer?.disconnect();
+            observer = null;
+        }
+    };
+    return {
+        getWxml,
+        highlightElement,
+        elementFor,
+        setObserving,
+        dispose: () => setObserving(false),
+    };
+}

package/dist/panel-source.js

@@ -0,0 +1 @@
+export {};

package/dist/panel-view.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * 默认是否展开：对齐微信开发者工具的 wxml 面板。
+ * - `#shadow-root` 永远默认展开（组件边界标记，展开后才能看到内部结构）
+ * - 路径式 tag（含 `/`）= 页面或自定义组件，默认展开（让用户一眼看清组件层级）
+ * - 普通 DOM 节点（view/text 等）默认折叠，需要用户手动点开
+ */
+function isDefaultExpanded(node) {
+    if (node.tagName === '#shadow-root')
+        return true;
+    if (node.tagName.includes('/'))
+        return true;
+    return false;
+}
+/** Renders a `[key, value]` attr list as `{' '}key="value"` pairs. */
+function AttrList({ entries }) {
+    return (_jsx(_Fragment, { children: entries.map(([k, v]) => (_jsxs("span", { children: [' ', _jsx("span", { className: "text-code-blue", children: k }), _jsx("span", { className: "text-text-dim", children: "=" }), _jsxs("span", { className: "text-code-orange", children: ["\"", v, "\""] })] }, k))) }));
+}
+// Text node — render as plain text.
+function WxmlTextNode({ node, depth }) {
+    return (_jsxs("div", { className: "py-px leading-[18px] hover:bg-surface-2", style: { paddingLeft: depth * 16 }, children: [_jsx("span", { className: "w-3 inline-block" }), _jsx("span", { className: "text-text", children: node.text })] }));
+}
+// Fragment — transparent root wrapper; render children directly without extra depth/tag.
+function WxmlFragmentNode({ node, depth, inspectedSid, onInspect }) {
+    return (_jsx(_Fragment, { children: (node.children ?? []).map((child, i) => (_jsx(WxmlTreeNode, { node: child, depth: depth, inspectedSid: inspectedSid, onInspect: onInspect }, i))) }));
+}
+// Shadow root — synthetic boundary for custom component internals.
+// Clickable to collapse like WeChat DevTools; default expanded; no closing tag.
+function WxmlShadowRootNode({ node, depth, inspectedSid, onInspect }) {
+    const [expanded, setExpanded] = useState(() => isDefaultExpanded(node));
+    const indent = depth * 16;
+    const hasShadowChildren = (node.children ?? []).length > 0;
+    return (_jsxs("div", { children: [_jsxs("div", { className: "py-px leading-[18px] hover:bg-surface-2 cursor-pointer", style: { paddingLeft: indent }, onClick: () => hasShadowChildren && setExpanded(!expanded), children: [_jsx("span", { className: "text-text-dim w-3 shrink-0 inline-block text-center select-none", children: hasShadowChildren ? (expanded ? '▾' : '▸') : ' ' }), _jsx("span", { className: "text-text-dim italic", children: "#shadow-root" })] }), expanded && node.children.map((child, i) => (_jsx(WxmlTreeNode, { node: child, depth: depth + 1, inspectedSid: inspectedSid, onInspect: onInspect }, i)))] }));
+}
+// Single text child — render inline: <tag>text</tag>
+function WxmlInlineTextRow({ node, indent, attrEntries, isInspected, onMouseEnter, inlineText, }) {
+    const rowClassName = `py-px leading-[18px] hover:bg-surface-2${isInspected ? ' bg-surface-2' : ''}`;
+    return (_jsxs("div", { className: rowClassName, style: { paddingLeft: indent }, onMouseEnter: onMouseEnter, "data-wxml-sid": node.sid, children: [_jsx("span", { className: "w-3 inline-block" }), _jsxs("span", { className: "text-code-keyword", children: ['<', node.tagName] }), _jsx(AttrList, { entries: attrEntries }), _jsx("span", { className: "text-code-keyword", children: '>' }), _jsx("span", { className: "text-text", children: inlineText }), _jsxs("span", { className: "text-code-keyword", children: ['</', node.tagName, '>'] })] }));
+}
+// Full open/close-tag row, with children rendered underneath when expanded.
+function WxmlBlockRow({ node, depth, indent, attrEntries, hasChildren, expanded, isInspected, inspectedSid, onInspect, onToggle, onMouseEnter, }) {
+    return (_jsxs("div", { children: [_jsxs("div", { className: `flex items-start hover:bg-surface-2 py-px leading-[18px]${hasChildren ? ' cursor-pointer' : ''}${isInspected ? ' bg-surface-2' : ''}`, style: { paddingLeft: indent }, onMouseEnter: onMouseEnter, onClick: () => {
+                    if (hasChildren)
+                        onToggle();
+                }, "data-wxml-sid": node.sid, children: [_jsx("span", { className: "text-text-dim w-3 shrink-0 text-center select-none", children: hasChildren ? (expanded ? '▾' : '▸') : ' ' }), _jsxs("span", { children: [_jsxs("span", { className: "text-code-keyword", children: ['<', node.tagName] }), _jsx(AttrList, { entries: attrEntries }), _jsx("span", { className: "text-code-keyword", children: hasChildren ? '>' : ' />' })] })] }), expanded && hasChildren && (_jsxs(_Fragment, { children: [node.children.map((child, i) => (_jsx(WxmlTreeNode, { node: child, depth: depth + 1, inspectedSid: inspectedSid, onInspect: onInspect }, i))), _jsxs("div", { style: { paddingLeft: indent }, className: "py-px leading-[18px]", children: [_jsx("span", { className: "w-3 inline-block" }), _jsxs("span", { className: "text-code-keyword", children: ['</', node.tagName, '>'] })] })] }))] }));
+}
+// Ordinary element node — decides between the inline-text and block layouts.
+function WxmlElementNode({ node, depth, inspectedSid, onInspect }) {
+    const [expanded, setExpanded] = useState(() => isDefaultExpanded(node));
+    const indent = depth * 16;
+    const isInspected = Boolean(node.sid && node.sid === inspectedSid);
+    const hasChildren = (node.children ?? []).length > 0;
+    const attrEntries = Object.entries(node.attrs);
+    const inspect = () => {
+        if (node.sid)
+            onInspect?.(node);
+    };
+    // Single text child — render inline: <tag>text</tag>
+    const inlineText = hasChildren && node.children.length === 1 && node.children[0].tagName === '#text'
+        ? node.children[0].text
+        : null;
+    if (inlineText) {
+        return (_jsx(WxmlInlineTextRow, { node: node, indent: indent, attrEntries: attrEntries, isInspected: isInspected, onMouseEnter: inspect, inlineText: inlineText }));
+    }
+    return (_jsx(WxmlBlockRow, { node: node, depth: depth, indent: indent, attrEntries: attrEntries, hasChildren: hasChildren, expanded: expanded, isInspected: isInspected, inspectedSid: inspectedSid, onInspect: onInspect, onToggle: () => setExpanded(!expanded), onMouseEnter: inspect }));
+}
+function WxmlTreeNode({ node, depth, inspectedSid, onInspect }) {
+    if (node.tagName === '#text')
+        return _jsx(WxmlTextNode, { node: node, depth: depth });
+    if (node.tagName === '#fragment') {
+        return _jsx(WxmlFragmentNode, { node: node, depth: depth, inspectedSid: inspectedSid, onInspect: onInspect });
+    }
+    if (node.tagName === '#shadow-root') {
+        return _jsx(WxmlShadowRootNode, { node: node, depth: depth, inspectedSid: inspectedSid, onInspect: onInspect });
+    }
+    return _jsx(WxmlElementNode, { node: node, depth: depth, inspectedSid: inspectedSid, onInspect: onInspect });
+}
+function InspectionFooter({ inspection }) {
+    if (!inspection)
+        return null;
+    const { rect, style } = inspection;
+    const styleParts = [
+        style.display,
+        style.position !== 'static' ? style.position : null,
+        style.boxSizing,
+    ].filter(Boolean);
+    return (_jsxs("div", { className: "border-t border-border-subtle bg-bg-panel px-2.5 py-1.5 font-mono text-[11px] text-text-dim shrink-0", children: [_jsx("span", { className: "text-text", children: "box" }), ' ', Math.round(rect.width), " x ", Math.round(rect.height), ' @ ', Math.round(rect.x), ", ", Math.round(rect.y), _jsx("span", { className: "mx-2 text-border-subtle", children: "|" }), styleParts.join(' / '), _jsx("span", { className: "mx-2 text-border-subtle", children: "|" }), "font ", style.fontSize] }));
+}
+export function WxmlPanel({ tree, onInspectElement, onClearInspection, isRuntimeRunning = true, }) {
+    const [inspection, setInspection] = useState(null);
+    // 序号 + rAF 用于解决 hover 触发的两个独立问题：
+    // - reqSeqRef：防止 await 完成顺序与 hover 顺序不一致导致 footer 抖动；
+    //   每次发起请求自增，写入前比对，落后的响应直接丢弃。
+    // - rafRef：把 hover 触发的 IPC 合并到下一帧，连续扫过列表只会留最后一帧。
+    const reqSeqRef = useRef(0);
+    const rafRef = useRef(null);
+    useEffect(() => () => {
+        if (rafRef.current !== null)
+            cancelAnimationFrame(rafRef.current);
+    }, []);
+    const inspectNode = useCallback((node) => {
+        if (!node.sid || !onInspectElement)
+            return;
+        const sid = node.sid;
+        if (rafRef.current !== null)
+            cancelAnimationFrame(rafRef.current);
+        rafRef.current = requestAnimationFrame(() => {
+            rafRef.current = null;
+            const seq = ++reqSeqRef.current;
+            onInspectElement(sid).then((next) => {
+                if (seq !== reqSeqRef.current)
+                    return;
+                setInspection(next);
+            }).catch(() => {
+                if (seq !== reqSeqRef.current)
+                    return;
+                setInspection(null);
+            });
+        });
+    }, [onInspectElement]);
+    const clearInspection = useCallback(() => {
+        if (rafRef.current !== null) {
+            cancelAnimationFrame(rafRef.current);
+            rafRef.current = null;
+        }
+        // 让所有 in-flight 响应被序号校验丢弃，避免它们在 clear 之后又把 inspection 写回来。
+        reqSeqRef.current++;
+        setInspection(null);
+        void onClearInspection?.();
+    }, [onClearInspection]);
+    if (!tree) {
+        return (_jsx("div", { className: "flex flex-col flex-1 overflow-hidden", "data-testid": "wxml-panel", children: _jsx("div", { className: "text-[12px] text-text-dim text-center px-4 py-6", children: isRuntimeRunning ? '等待小程序加载...' : '小程序未运行' }) }));
+    }
+    return (_jsxs("div", { className: "flex flex-col flex-1 overflow-hidden", onMouseLeave: clearInspection, "data-testid": "wxml-panel", children: [_jsx("div", { className: "flex-1 overflow-y-auto p-2 font-mono text-[12px]", children: _jsx(WxmlTreeNode, { node: tree, depth: 0, inspectedSid: inspection?.sid ?? null, onInspect: inspectNode }) }), _jsx(InspectionFooter, { inspection: inspection })] }));
+}

package/dist/panel.js

@@ -0,0 +1,7 @@
+// Public React entry (`@dimina-kit/inspect/panel`): the pure views plus the
+// source-connected containers. Split into files so a pure view stays
+// importable without its data-wiring layer.
+export { WxmlPanel } from './panel-view.js';
+export { ConnectedWxmlPanel } from './connected-panel.js';
+export { StoragePanel } from './storage-panel-view.js';
+export { ConnectedStoragePanel } from './connected-storage-panel.js';

package/dist/sid-registry.js

@@ -0,0 +1,45 @@
+// Stable-id registry for WXML nodes, shared by every extractor that walks a
+// render-layer document (host iframe extractors, injected guest inspectors,
+// browser preview bridges). It is dependency-free so injected bundles stay
+// small and don't drag in host-specific machinery.
+// 合成 sid 注册表：用 WeakMap 把元素 ↔ sid 双向绑定，避免在源 DOM 上写
+// `data-*` 属性（提取本应只读，且属性形式会污染用户的快照/选择器）。
+// elBySyntheticSid 为反向查找用 WeakRef，元素被 GC 后下次 lookup 自动清理。
+export const SYNTHETIC_SID_PREFIX = 'devtools-';
+const syntheticSidByEl = new WeakMap();
+const elBySyntheticSid = new Map();
+let nextSyntheticSid = 1;
+export function registerSyntheticSid(el) {
+    const existing = syntheticSidByEl.get(el);
+    if (existing)
+        return existing;
+    const synthetic = `${SYNTHETIC_SID_PREFIX}${nextSyntheticSid++}`;
+    syntheticSidByEl.set(el, synthetic);
+    elBySyntheticSid.set(synthetic, new WeakRef(el));
+    return synthetic;
+}
+export function findElementBySid(doc, sid) {
+    if (sid.startsWith(SYNTHETIC_SID_PREFIX)) {
+        const ref = elBySyntheticSid.get(sid);
+        if (!ref)
+            return null;
+        const el = ref.deref();
+        if (!el || !el.isConnected) {
+            elBySyntheticSid.delete(sid);
+            return null;
+        }
+        if (el.ownerDocument !== doc)
+            return null;
+        return el;
+    }
+    return doc.querySelector(`[data-sid="${escapeForAttrSelector(sid)}"]`);
+}
+// `CSS.escape` only exists in real browser realms (jsdom has no `window.CSS`).
+// Inside a double-quoted attribute selector, escaping backslashes and quotes
+// is sufficient, so fall back to that when the host lacks the API.
+function escapeForAttrSelector(value) {
+    const impl = globalThis.CSS?.escape;
+    if (impl)
+        return impl(value);
+    return value.replace(/[\\"]/g, '\\$&');
+}

package/dist/storage-panel-view.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The pure Storage table view: items in, write callbacks out. No data
+// wiring lives here (seed/subscribe/visibility belong to
+// ConnectedStoragePanel); no host UI kit either — the couple of buttons are
+// plain elements styled with the same Tailwind utility tokens as the rest of
+// the panel, so any host that maps the CSS variables gets the native look.
+import { useEffect, useState } from 'react';
+const BUTTON_CLASS = 'inline-flex items-center justify-center gap-1.5 font-medium transition-colors '
+    + 'focus:outline-none disabled:opacity-35 disabled:cursor-not-allowed whitespace-nowrap shrink-0 '
+    + 'border border-border text-text-muted hover:text-text rounded h-5 px-2 text-[11px]';
+export function StoragePanel({ items, onSet, onRemove, onClear, onClearAll, getPrefix, isRuntimeRunning = true, }) {
+    const [editing, setEditing] = useState(null);
+    const [error, setError] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const [prefix, setPrefix] = useState('');
+    const [addKey, setAddKey] = useState('');
+    const [addValue, setAddValue] = useState('');
+    useEffect(() => {
+        let cancelled = false;
+        let timer;
+        // The panel can mount before the host has resolved the active appId, so
+        // `getPrefix()` initially returns '' and the key un-prefixing below would
+        // never engage. The prefix is empty only transiently during session
+        // warmup, so poll until it resolves non-empty (then stop). Once set it is
+        // stable for the session's lifetime.
+        const load = () => {
+            void getPrefix().then((p) => {
+                if (cancelled)
+                    return;
+                if (p) {
+                    setPrefix(p);
+                    return;
+                }
+                timer = setTimeout(load, 300);
+            });
+        };
+        load();
+        return () => { cancelled = true; if (timer)
+            clearTimeout(timer); };
+    }, [getPrefix]);
+    async function withBusy(op) {
+        setBusy(true);
+        setError(null);
+        try {
+            const r = await op();
+            if (!r.ok) {
+                setError(r.error);
+                return null;
+            }
+            return r;
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    function startEdit(item) {
+        setEditing({ key: item.key, draft: item.value });
+    }
+    async function commitEdit() {
+        if (!editing)
+            return;
+        const { key, draft } = editing;
+        setEditing(null);
+        await withBusy(() => onSet(key, draft));
+    }
+    async function handleRemove(key) {
+        await withBusy(() => onRemove(key));
+    }
+    async function handleClear() {
+        if (items.length === 0)
+            return;
+        await withBusy(() => onClear());
+    }
+    async function handleClearAll() {
+        if (!onClearAll)
+            return;
+        // Origin-wide wipe affects every appId's keys in the shared storage
+        // partition. Use `window.confirm` so the user has to opt in explicitly.
+        if (typeof window !== 'undefined' && !window.confirm('清空所有 appId 的 Storage 数据？该操作不可撤销。'))
+            return;
+        await withBusy(() => onClearAll());
+    }
+    async function handleAdd() {
+        const trimmedKey = addKey.trim();
+        if (!trimmedKey) {
+            setError('key 不能为空');
+            return;
+        }
+        const fullKey = prefix + trimmedKey;
+        const r = await withBusy(() => onSet(fullKey, addValue));
+        if (r) {
+            setAddKey('');
+            setAddValue('');
+        }
+    }
+    return (_jsxs("div", { className: "flex flex-col overflow-hidden flex-1", "data-testid": "storage-panel", children: [_jsxs("div", { className: "flex items-center gap-1.5 px-2.5 py-1.5 border-b border-border-subtle shrink-0 bg-bg-panel", children: [_jsx("button", { type: "button", onClick: () => void handleClear(), disabled: busy || items.length === 0, className: `${BUTTON_CLASS} hover:border-status-error hover:text-status-error`, title: "\u4EC5\u6E05\u7A7A\u5F53\u524D appId \u7684 Storage", children: "\u6E05\u7A7A" }), onClearAll && (_jsx("button", { type: "button", onClick: () => void handleClearAll(), disabled: busy, className: `${BUTTON_CLASS} hover:border-status-error hover:text-status-error`, title: "\u6E05\u7A7A\u6240\u6709 appId \u7684 Storage", children: "\u6E05\u7A7A\u6240\u6709" })), error && (_jsx("span", { className: "ml-2 text-[11px] text-status-error truncate", title: error, children: error }))] }), _jsx("div", { className: "flex-1 overflow-y-auto", children: _jsxs("table", { className: "w-full border-collapse text-[12px]", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { className: "text-left text-code-label font-normal px-2.5 py-1 border-b border-border-subtle text-[11px] sticky top-0 bg-bg-panel z-10 w-px pr-5", children: "Key" }), _jsx("th", { className: "text-left text-code-label font-normal px-2.5 py-1 border-b border-border-subtle text-[11px] sticky top-0 bg-bg-panel z-10", children: "Value" }), _jsx("th", { className: "w-px sticky top-0 bg-bg-panel z-10 border-b border-border-subtle" })] }) }), _jsx("tbody", { children: items.length === 0
+                                ? (_jsx("tr", { children: _jsx("td", { colSpan: 3, className: "text-[12px] text-text-dim text-center px-4 py-6", children: isRuntimeRunning ? '暂无 Storage 数据' : '小程序未运行' }) }))
+                                : items.map((item) => {
+                                    const isEditing = editing?.key === item.key;
+                                    // Display keys without the active appId namespace prefix
+                                    // (`${appId}_`), the way Chrome's Local Storage panel shows
+                                    // clean keys. The full key (used for every read/write below)
+                                    // stays in the `title` for discoverability.
+                                    const displayKey = prefix && item.key.startsWith(prefix)
+                                        ? item.key.slice(prefix.length)
+                                        : item.key;
+                                    return (_jsxs("tr", { className: "hover:[&>td]:bg-surface", children: [_jsx("td", { className: "px-2.5 py-0.5 border-b border-border-subtle w-px pr-5 align-top", children: _jsx("div", { className: "font-mono text-code-blue max-w-[240px] truncate", title: item.key, children: displayKey }) }), _jsx("td", { className: "px-2.5 py-0.5 border-b border-border-subtle font-mono text-code-orange break-all align-top cursor-text", onClick: () => { if (!isEditing)
+                                                    startEdit(item); }, children: isEditing
+                                                    ? (_jsx("input", { autoFocus: true, type: "text", value: editing.draft, onChange: e => setEditing({ key: item.key, draft: e.target.value }), onBlur: () => void commitEdit(), onKeyDown: (e) => {
+                                                            if (e.key === 'Enter') {
+                                                                e.preventDefault();
+                                                                void commitEdit();
+                                                            }
+                                                            else if (e.key === 'Escape') {
+                                                                e.preventDefault();
+                                                                setEditing(null);
+                                                            }
+                                                        }, className: "w-full bg-transparent outline-none border border-accent/60 rounded px-1 py-0 font-mono text-code-orange" }))
+                                                    : item.value }), _jsx("td", { className: "px-1 py-0.5 border-b border-border-subtle align-top", children: _jsx("button", { type: "button", onClick: () => void handleRemove(item.key), disabled: busy, title: "\u5220\u9664", className: "text-text-dim hover:text-status-error px-1 leading-none", children: "\u00D7" }) })] }, item.key));
+                                }) })] }) }), _jsxs("div", { className: "flex items-center gap-1.5 px-2.5 py-1.5 border-t border-border-subtle shrink-0 bg-bg-panel", children: [_jsx("input", { type: "text", placeholder: "key", value: addKey, onChange: e => setAddKey(e.target.value), onKeyDown: (e) => { if (e.key === 'Enter') {
+                            e.preventDefault();
+                            void handleAdd();
+                        } }, className: "w-32 bg-transparent border border-border-subtle rounded px-1.5 py-0.5 text-[12px] font-mono outline-none focus:border-accent" }), _jsx("input", { type: "text", placeholder: "value", value: addValue, onChange: e => setAddValue(e.target.value), onKeyDown: (e) => { if (e.key === 'Enter') {
+                            e.preventDefault();
+                            void handleAdd();
+                        } }, className: "flex-1 bg-transparent border border-border-subtle rounded px-1.5 py-0.5 text-[12px] font-mono outline-none focus:border-accent" }), _jsx("button", { type: "button", onClick: () => void handleAdd(), disabled: busy || !addKey.trim(), className: `${BUTTON_CLASS} hover:border-accent hover:text-accent`, children: "+ \u65B0\u589E" })] })] }));
+}

package/dist/storage-reducer.js

@@ -0,0 +1,25 @@
+/**
+ * Applies one incremental StorageEvent to an item list, pure-function style
+ * (the input array is never mutated; a new array is always returned).
+ * `added` and `updated` are both tolerant upserts — host change feeds can
+ * deliver them out of order (an `updated` may arrive before its `added`, or
+ * an `added` may repeat for an existing key), and the reducer must converge
+ * on the same list either way instead of duplicating keys or dropping data.
+ */
+export function applyStorageEvent(items, evt) {
+    switch (evt.type) {
+        case 'added':
+        case 'updated': {
+            const idx = items.findIndex(it => it.key === evt.key);
+            if (idx < 0)
+                return [...items, { key: evt.key, value: evt.newValue }];
+            const next = [...items];
+            next[idx] = { key: evt.key, value: evt.newValue };
+            return next;
+        }
+        case 'removed':
+            return items.filter(it => it.key !== evt.key);
+        case 'cleared':
+            return [];
+    }
+}

package/dist/storage-source.js

@@ -0,0 +1 @@
+export {};

package/dist/storage-types.js

@@ -0,0 +1,4 @@
+// Wire-format types for mini-program Storage inspection. Hosts transport
+// them over IPC, postMessage, or read them straight off a shared
+// localStorage — the shapes are the contract, not the transport.
+export {};

package/dist/types.js

@@ -0,0 +1,5 @@
+// Wire-format types shared by every host that extracts or displays a WXML
+// tree (Electron devtools, browser workbench panels, downstream hosts). They
+// are the protocol layer: hosts may transport them over IPC, postMessage or
+// any other channel, but the shapes themselves stay host-agnostic.
+export {};