@dimina-kit/inspect 0.3.0-dev.20260711141929

package/dist/use-source-wiring.js

@@ -0,0 +1,52 @@
+// The source-lifecycle wiring every connected panel shares, written once:
+// subscription + feed-gate lifecycle per (source, enabled), visibility
+// forwarding, and the (enabled && active) rising-edge seed (including a
+// source swap while on) with late-resolution dropping. Panel-specific parts —
+// what a push event does to state and how a snapshot lands — come in as the
+// `subscribe`/`seed` handlers, read through a ref so effects depend only on
+// (source, enabled, active) and inline handler lambdas never re-fire them.
+import { useEffect, useRef } from 'react';
+export function useSourceWiring(options) {
+    const { source, enabled, active } = options;
+    // Declared before every consuming effect so it runs first on each commit
+    // and the handlers are always current when an effect fires.
+    const handlers = useRef({ subscribe: options.subscribe, seed: options.seed });
+    useEffect(() => {
+        handlers.current = { subscribe: options.subscribe, seed: options.seed };
+    });
+    // Subscription + feed-gate lifecycle, per (source, enabled). Cleanup disarms
+    // the producer's feed so an unmounted/disabled panel costs nothing; a source
+    // swap tears the old transport down first.
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const unsubscribe = handlers.current.subscribe(source);
+        return () => {
+            unsubscribe();
+            source.setActive(false);
+        };
+    }, [source, enabled]);
+    // Forward the visibility gate on every change while enabled.
+    useEffect(() => {
+        if (!enabled)
+            return;
+        source.setActive(active);
+    }, [source, enabled, active]);
+    // Seed on the (enabled && active) rising edge — including a source swap
+    // while on. A kept-alive tab that turns active again re-fetches, so it never
+    // shows data from before its invisible stretch.
+    const prevSeed = useRef({ source: null, on: false });
+    useEffect(() => {
+        const on = enabled && active;
+        const prev = prevSeed.current;
+        const rising = on && (!prev.on || prev.source !== source);
+        prevSeed.current = { source, on };
+        if (!rising)
+            return undefined;
+        let disposed = false;
+        handlers.current.seed(source, () => disposed);
+        return () => {
+            disposed = true;
+        };
+    }, [source, enabled, active]);
+}

package/dist/wxml-extract.js

@@ -0,0 +1,381 @@
+import { registerSyntheticSid } from './sid-registry.js';
+const INTERNAL_CLASSES = new Set([
+    'dd-swiper-wrapper', 'dd-swiper-slides', 'dd-swiper-slide-frame', 'dd-swiper-dots',
+    'dd-picker-overlay', 'dd-picker-container', 'dd-picker-header', 'dd-picker-body',
+]);
+const FRAMEWORK_TEMPLATE_RE = /^(taro_tmpl|tmpl_\d+)/;
+/**
+ * Strip the `dd-` registration prefix and the `tpl-` prefix dimina adds to
+ * compiled template components (`app.component('dd-tpl-taro_tmpl', …)`), so a
+ * framework template wrapper normalizes to its bare name (`taro_tmpl`,
+ * `tmpl_0_3`) and `FRAMEWORK_TEMPLATE_RE` recognizes it.
+ */
+function normalizeRegisteredName(regName) {
+    const base = regName.startsWith('dd-') ? regName.slice(3) : regName;
+    return base.startsWith('tpl-') ? base.slice(4) : base;
+}
+function resolveTemplateNameFromParent(instance) {
+    const parent = instance.parent;
+    const parentType = parent?.type;
+    const components = parentType?.components;
+    if (components) {
+        for (const [regName, comp] of Object.entries(components)) {
+            if (comp === instance.type)
+                return normalizeRegisteredName(regName);
+        }
+    }
+    const appComponents = instance.appContext?.components;
+    if (!appComponents)
+        return null;
+    for (const [regName, comp] of Object.entries(appComponents)) {
+        if (comp === instance.type)
+            return normalizeRegisteredName(regName);
+    }
+    return null;
+}
+/**
+ * Convert a PascalCase / camelCase identifier to kebab-case. Matches the
+ * upstream `camelCaseToUnderscore` (dimina/fe/packages/common) so a name
+ * already normalized by `withInstall` round-trips identically.
+ * `View` -> `view`, `ScrollView` -> `scroll-view`, `CoverImage` -> `cover-image`.
+ */
+function pascalToKebab(name) {
+    return name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+/**
+ * Read the page's source path off Vue's provide/inject. dimina runtime.js 在
+ * dd-page 的 setup() 里调用 `provide('path', path)`，Vue 把它存到
+ * `instance.provides`。我们利用这个把页面节点的 tagName 从硬编码 `page`
+ * 升级为页面全路径（如 `pages/index/index`），对齐微信开发者工具。
+ */
+function resolvePagePath(instance) {
+    // dimina runtime 在 dd-page 的 setup 里 `instance.proxy.__page__ = true` 并
+    // `provide('path', path)`。两个标记同时具备才视为页面层级，避免 dd-page
+    // 的子节点继承 provides.path 后被误判（Vue 用 Object.create 链式 provides）。
+    const proxy = instance.proxy;
+    if (proxy?.__page__ !== true)
+        return null;
+    const provides = instance.provides;
+    const path = provides?.path;
+    if (typeof path !== 'string' || !path)
+        return null;
+    return path.startsWith('/') ? path.slice(1) : path;
+}
+/**
+ * A NATIVE dimina custom component (a `usingComponents` entry) calls
+ * `provide('path', componentPath)` in its setup (render runtime), so its
+ * provided `path` DIFFERS from its parent's. A plain descendant inherits the
+ * same provides object (identical `path`) and is not a boundary; a Taro template
+ * wrapper (`dd-tpl-*`) never provides, so it never differs either. Comparing
+ * against the parent's provided path therefore isolates exactly the native
+ * component roots — matching WeChat, which shows each custom component as a node
+ * tagged with its full registered path (with a synthetic `#shadow-root` added by
+ * `wrapInShadowRoot` since the path contains `/`). Pages are handled earlier via
+ * their authoritative `__page__` marker, so this only fires for components.
+ */
+function resolveComponentPath(instance) {
+    const provides = instance.provides;
+    const path = provides?.path;
+    if (typeof path !== 'string' || !path)
+        return null;
+    const parent = instance.parent;
+    const parentProvides = parent?.provides;
+    if (path === parentProvides?.path)
+        return null;
+    return path.startsWith('/') ? path.slice(1) : path;
+}
+function resolveTagName(instance) {
+    const type = instance.type;
+    if (!type)
+        return 'unknown';
+    // 页面层级优先：dd-page 没有 __tagName/__name，且 home 页等无 usingComponents
+    // 的页面 type.components 为 undefined，会落到 resolveTemplateNameFromParent
+    // 回到 'page'。在那之前直接用 provide('path') 的路径升级 tag 名。
+    const pagePath = resolvePagePath(instance);
+    if (pagePath)
+        return pagePath;
+    // Native custom-component boundary → tag with its full registered path (WeChat
+    // parity). Must precede the __tagName/__name/dd- shortening below, which would
+    // otherwise collapse `dd-foo` to the bare `foo` and lose the path.
+    const componentPath = resolveComponentPath(instance);
+    if (componentPath)
+        return componentPath;
+    if (typeof type.__tagName === 'string')
+        return type.__tagName;
+    const name = (type.__name || type.name);
+    if (!name) {
+        // A nameless component carrying a `__scopeId` is a compiled page, custom
+        // component, or framework template wrapper. The page is already resolved
+        // above via its authoritative `__page__` marker, so by here it is NOT a
+        // page — recover the registered tag (e.g. a Taro `taro_tmpl`/`tmpl_0_3`
+        // wrapper) and fall back to `template`. Defaulting to `page` here would
+        // mislabel every such wrapper as a second page root.
+        if (type.__scopeId)
+            return resolveTemplateNameFromParent(instance) || 'template';
+        return 'unknown';
+    }
+    if (name === 'dd-page')
+        return 'page';
+    if (name.startsWith('dd-'))
+        return name.slice(3);
+    // Reverse-map Dimina component names back to their miniprogram tag names.
+    // The installer (`withInstall`) sets `__tagName = camelCaseToUnderscore(__name)`,
+    // but in dev builds, custom registrations, or when the installer hasn't run,
+    // we may only see the raw `__name`/`name` (e.g. `View`, `ScrollView`, `DdButton`).
+    // Without this fallback the WXML panel would surface the upstream Vue name
+    // verbatim, defeating the panel's purpose of showing source-level tags.
+    if (name.startsWith('Dd') && name.length > 2)
+        return pascalToKebab(name.slice(2));
+    if (/^[A-Z]/.test(name))
+        return pascalToKebab(name);
+    return name;
+}
+/** Props/attrs entries that never surface in the WXML panel (internal Vue plumbing, falsy booleans). */
+function isSkippedProp(key, value) {
+    if (typeof value === 'function' || value === undefined)
+        return true;
+    if (key === 'data' || key.startsWith('__'))
+        return true;
+    return typeof value === 'boolean' && !value;
+}
+/** Drop the `dd-` internal-marker classes so the panel shows only user-authored classes. */
+function cleanClassAttr(value) {
+    return value.split(/\s+/).filter((c) => !c.startsWith('dd-')).join(' ');
+}
+function stringifyPropValue(value) {
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+function assignProp(out, key, value) {
+    if (isSkippedProp(key, value))
+        return;
+    if (key === 'class' && typeof value === 'string') {
+        const cleaned = cleanClassAttr(value);
+        if (cleaned)
+            out[key] = cleaned;
+        return;
+    }
+    out[key] = stringifyPropValue(value);
+}
+function extractProps(instance) {
+    const out = {};
+    for (const raw of [instance.props, instance.attrs]) {
+        if (!raw)
+            continue;
+        for (const [k, v] of Object.entries(raw)) {
+            assignProp(out, k, v);
+        }
+    }
+    return out;
+}
+function isInternalElement(vnode) {
+    const props = vnode.props;
+    if (!props)
+        return false;
+    const cls = String(props.class || '');
+    return cls.split(/\s+/).some((c) => INTERNAL_CLASSES.has(c));
+}
+function getElementSid(instance) {
+    const subTree = instance.subTree;
+    const el = subTree?.el;
+    if (!el?.getAttribute)
+        return undefined;
+    const sid = el.getAttribute('data-sid');
+    if (sid)
+        return sid;
+    return registerSyntheticSid(el);
+}
+function isTransparentComponent(instance, tagName) {
+    if (tagName === 'unknown')
+        return true;
+    // A framework template wrapper (Taro `taro_tmpl` / `tmpl_0_3`, whether named
+    // via `props.is` or recovered from its registration) is compiler scaffolding,
+    // not user content — pass its children straight through.
+    if (FRAMEWORK_TEMPLATE_RE.test(tagName))
+        return true;
+    if (tagName === 'template') {
+        const props = instance.props;
+        const is = props?.is;
+        if (is && FRAMEWORK_TEMPLATE_RE.test(is))
+            return true;
+        if (!is) {
+            const type = instance.type;
+            if (type?.__scopeId && !type.components)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 检测 Vue 的 Comment vnode（`v-if`/`v-else`/`v-for` 占位锚点）。
+ * Vue 在条件不成立时会留下 `<!-- v-if -->` 这样的注释 vnode 用作 DOM 锚点。
+ * 这些 vnode 不是用户内容，必须从 wxml 树里剔除。
+ *
+ * - dev build：type 是 `Symbol('Comment')`，description = 'Comment' 或 'v-cmt'
+ * - prod build：description 可能丢失，但 children 一般是 'v-if'/'v-else' 等 marker
+ */
+function isCommentVNode(vnode) {
+    const type = vnode.type;
+    if (typeof type !== 'symbol')
+        return false;
+    const desc = type.description;
+    if (desc === 'Comment' || desc === 'v-cmt')
+        return true;
+    const children = typeof vnode.children === 'string' ? vnode.children : '';
+    return /^v-(if|else|else-if|for)$/.test(children);
+}
+function textNode(text) {
+    return { tagName: '#text', attrs: {}, children: [], text };
+}
+/** A component vnode's children come from walking its mounted instance, not `vnode.children`. */
+function childrenFromComponentVNode(component, depth) {
+    const result = walkInstance(component, depth + 1);
+    if (!result)
+        return [];
+    return Array.isArray(result) ? result : [result];
+}
+/** A `<Suspense>` vnode's visible content is whichever branch is currently active. */
+function childrenFromSuspenseVNode(suspense, depth) {
+    const activeBranch = suspense.activeBranch;
+    return activeBranch ? extractChildrenFromVNode(activeBranch, depth + 1) : [];
+}
+/**
+ * A vnode whose OWN `children` is a plain string only counts as a text node when
+ * its `type` is a symbol/string (a real element or fragment) — a component vnode
+ * with string `children` is slot content, not text, and is handled elsewhere.
+ * Returns null when this vnode is not (top-level) text, so the caller falls
+ * through to the array-children path.
+ */
+function directTextChild(vnode) {
+    if (typeof vnode.children !== 'string' || !vnode.children.trim())
+        return null;
+    const vnodeType = vnode.type;
+    if (typeof vnodeType !== 'symbol' && typeof vnodeType !== 'string')
+        return null;
+    return [textNode(vnode.children.trim())];
+}
+function textChildEntry(child) {
+    const trimmed = child.trim();
+    return trimmed ? [textNode(trimmed)] : [];
+}
+/** A DOM-typed child (`type` is its tag name string): text leaf, internal wrapper, or a normal subtree. */
+function domTypedChildEntries(c, depth) {
+    if (isInternalElement(c))
+        return extractChildrenFromVNode(c, depth + 1);
+    if (typeof c.children === 'string' && c.children.trim())
+        return [textNode(c.children.trim())];
+    return extractChildrenFromVNode(c, depth + 1);
+}
+/** One entry from a vnode's `children` array, normalized to zero or more WXML nodes. */
+function extractChildEntry(child, depth) {
+    if (!child)
+        return [];
+    if (typeof child === 'string')
+        return textChildEntry(child);
+    if (typeof child !== 'object')
+        return [];
+    const c = child;
+    if (c.component)
+        return childrenFromComponentVNode(c.component, depth);
+    if (typeof c.type === 'symbol')
+        return extractChildrenFromVNode(c, depth + 1);
+    if (typeof c.type === 'string')
+        return domTypedChildEntries(c, depth);
+    return extractChildrenFromVNode(c, depth + 1);
+}
+function extractChildrenFromVNode(vnode, depth) {
+    if (!vnode || depth > 50)
+        return [];
+    if (isCommentVNode(vnode))
+        return [];
+    if (vnode.component)
+        return childrenFromComponentVNode(vnode.component, depth);
+    if (vnode.suspense)
+        return childrenFromSuspenseVNode(vnode.suspense, depth);
+    const directText = directTextChild(vnode);
+    if (directText)
+        return directText;
+    const kids = vnode.children;
+    if (!Array.isArray(kids))
+        return [];
+    const result = [];
+    for (const child of kids) {
+        result.push(...extractChildEntry(child, depth));
+    }
+    return result;
+}
+/**
+ * Reverse-map Dimina's `<wrapper name="/components/foo/foo">` (used to host
+ * every user-defined component) back to the source-level tag the user wrote
+ * in WXML (e.g. `<foo>`).
+ *
+ * The wrapper carries the registered component path in its `name` Vue prop.
+ * By convention (also followed by miniprogram tooling), the registered key is
+ * the last path segment, optionally stripping a trailing `/index`. We can't
+ * see the page's `usingComponents` map from inside the Vue instance, so this
+ * convention-based recovery is best-effort: if the user picked a different
+ * registration key than the directory name (e.g. `usingComponents:
+ * { myCounter: '/components/counter/counter' }`), the panel will show
+ * `counter`, not `myCounter`.
+ *
+ * The path heuristic also resolves a name-collision risk: a user-written
+ * `<counter name="x">` would land in the same `attrs.name` slot as the
+ * wrapper-internal path. We only unwrap when the value looks like an absolute
+ * component path (leading `/`), which dimina always emits but a user would
+ * almost never type as a literal attr.
+ */
+function unwrapCustomComponent(node) {
+    if (node.tagName !== 'wrapper')
+        return node;
+    const path = node.attrs?.name;
+    if (typeof path !== 'string' || !path.startsWith('/'))
+        return node;
+    // 去掉前导 `/` 后保留原路径形式（保留所有斜杠，不做 kebab/dash 转换）。
+    // 仅当路径以 `/index` 结尾且剥离后仍至少剩一段时才剥（`/index` 单独存在则
+    // 退回 wrapper，避免出现空 tagName）。
+    const stripped = path.replace(/^\//, '');
+    const withoutIndex = stripped.endsWith('/index') ? stripped.slice(0, -'/index'.length) : stripped;
+    const recovered = withoutIndex || stripped;
+    if (!recovered || recovered === 'index')
+        return node;
+    const nextAttrs = {};
+    for (const [k, v] of Object.entries(node.attrs)) {
+        if (k === 'name')
+            continue;
+        nextAttrs[k] = v;
+    }
+    return { ...node, tagName: recovered, attrs: nextAttrs };
+}
+/**
+ * 把"用户授权"层级（页面 / 自定义组件，tagName 以路径形式呈现，含 `/`）
+ * 的 children 包一层合成 `#shadow-root`，对齐微信开发者工具：组件本身
+ * 与内部实现之间用 shadow-root 边界视觉分隔。
+ *
+ * 内置组件（view/text/button 等）和合成节点（#text/#fragment）tagName 都
+ * 不含 `/`，自然不会被包裹。children 为空也不插入（避免空壳）。重复调用
+ * 是幂等的：若 children[0] 已经是 #shadow-root 就跳过。
+ */
+function wrapInShadowRoot(node) {
+    if (!node.tagName.includes('/'))
+        return node;
+    if (node.children.length === 0)
+        return node;
+    if (node.children[0]?.tagName === '#shadow-root')
+        return node;
+    return {
+        ...node,
+        children: [{ tagName: '#shadow-root', attrs: {}, children: node.children }],
+    };
+}
+export function walkInstance(instance, depth) {
+    if (depth > 50)
+        return null;
+    const tagName = resolveTagName(instance);
+    const children = extractChildrenFromVNode(instance.subTree, depth);
+    if (isTransparentComponent(instance, tagName))
+        return children.length > 0 ? children : null;
+    const node = { tagName, attrs: extractProps(instance), children };
+    const sid = getElementSid(instance);
+    if (sid)
+        node.sid = sid;
+    return wrapInShadowRoot(unwrapCustomComponent(node));
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@dimina-kit/inspect",
+  "version": "0.3.0-dev.20260711141929",
+  "description": "Host-agnostic WXML tree extraction and inspection for dimina render layers: Vue runtime walk, stable-id registry, mutation-observing inspector, and a React tree panel.",
+  "keywords": [
+    "dimina",
+    "wxml",
+    "devtools",
+    "inspector"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "EchoTechFE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EchoTechFE/dimina-kit.git",
+    "directory": "packages/inspect"
+  },
+  "bugs": {
+    "url": "https://github.com/EchoTechFE/dimina-kit/issues"
+  },
+  "homepage": "https://github.com/EchoTechFE/dimina-kit/tree/main/packages/inspect#readme",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./panel": {
+      "types": "./src/panel.tsx",
+      "default": "./dist/panel.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@testing-library/react": "^16.3.2",
+    "react-dom": "^18.3.1",
+    "@vitest/coverage-v8": "^4.1.4",
+    "eslint": "^10.2.1",
+    "jsdom": "^29.0.2",
+    "react": "^18.3.1",
+    "typescript": "5.9.2",
+    "vitest": "^4.1.4",
+    "@dimina-kit/eslint-config": "0.1.0",
+    "@dimina-kit/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run --reporter=default --reporter=json --outputFile.json=test-report.json --coverage.enabled --coverage.reporter=json-summary --coverage.reportsDirectory=coverage",
+    "test:dev": "vitest"
+  }
+}