@dimina-kit/inspect 0.3.0-dev.20260711141929

package/src/storage-reducer.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import { applyStorageEvent } from './storage-reducer.js'
+import type { StorageEvent, StorageItem } from './storage-types.js'
+
+describe('applyStorageEvent: added', () => {
+  it('appends a new key to the end of the list', () => {
+    const items: StorageItem[] = [{ key: 'a', value: '1' }]
+    const result = applyStorageEvent(items, { type: 'added', key: 'b', newValue: '2' })
+    expect(result).toEqual([{ key: 'a', value: '1' }, { key: 'b', value: '2' }])
+  })
+
+  it('replaces the value of an existing key in place instead of duplicating it', () => {
+    const items: StorageItem[] = [{ key: 'a', value: '1' }, { key: 'b', value: '2' }]
+    const result = applyStorageEvent(items, { type: 'added', key: 'a', newValue: '99' })
+    expect(result).toEqual([{ key: 'a', value: '99' }, { key: 'b', value: '2' }])
+  })
+})
+
+describe('applyStorageEvent: updated', () => {
+  it('replaces the value of an existing key', () => {
+    const items: StorageItem[] = [{ key: 'a', value: '1' }]
+    const result = applyStorageEvent(items, { type: 'updated', key: 'a', oldValue: '1', newValue: '2' })
+    expect(result).toEqual([{ key: 'a', value: '2' }])
+  })
+
+  it('appends the key when an updated event arrives before its added event', () => {
+    const items: StorageItem[] = []
+    const result = applyStorageEvent(items, { type: 'updated', key: 'a', oldValue: '', newValue: '2' })
+    expect(result).toEqual([{ key: 'a', value: '2' }])
+  })
+})
+
+describe('applyStorageEvent: removed', () => {
+  it('drops the matching key', () => {
+    const items: StorageItem[] = [{ key: 'a', value: '1' }, { key: 'b', value: '2' }]
+    const result = applyStorageEvent(items, { type: 'removed', key: 'a' })
+    expect(result).toEqual([{ key: 'b', value: '2' }])
+  })
+
+  it('returns the list unchanged in length when the key is absent', () => {
+    const items: StorageItem[] = [{ key: 'a', value: '1' }]
+    const result = applyStorageEvent(items, { type: 'removed', key: 'missing' })
+    expect(result).toEqual(items)
+    expect(result).toHaveLength(1)
+  })
+})
+
+describe('applyStorageEvent: cleared', () => {
+  it('returns an empty list regardless of prior contents', () => {
+    const items: StorageItem[] = [{ key: 'a', value: '1' }, { key: 'b', value: '2' }]
+    const result = applyStorageEvent(items, { type: 'cleared' })
+    expect(result).toEqual([])
+  })
+})
+
+describe('applyStorageEvent: purity', () => {
+  it('never mutates the input array, for any event type', () => {
+    const items: readonly StorageItem[] = Object.freeze([
+      Object.freeze({ key: 'a', value: '1' }),
+      Object.freeze({ key: 'b', value: '2' }),
+    ])
+    const events: StorageEvent[] = [
+      { type: 'added', key: 'a', newValue: 'x' },
+      { type: 'added', key: 'c', newValue: 'x' },
+      { type: 'updated', key: 'a', oldValue: '1', newValue: 'x' },
+      { type: 'removed', key: 'a' },
+      { type: 'cleared' },
+    ]
+    for (const evt of events) {
+      expect(() => applyStorageEvent(items, evt)).not.toThrow()
+    }
+    expect(items).toEqual([{ key: 'a', value: '1' }, { key: 'b', value: '2' }])
+  })
+
+  it('returns a new array reference distinct from the input', () => {
+    const items: StorageItem[] = [{ key: 'a', value: '1' }]
+    const result = applyStorageEvent(items, { type: 'added', key: 'b', newValue: '2' })
+    expect(result).not.toBe(items)
+  })
+})

package/src/storage-reducer.ts

@@ -0,0 +1,26 @@
+import type { StorageEvent, StorageItem } from './storage-types.js'
+
+/**
+ * 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: readonly StorageItem[], evt: StorageEvent): StorageItem[] {
+  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/src/storage-source.ts

@@ -0,0 +1,28 @@
+// The host-transport contract behind the Storage panel: the panel's data
+// wiring (seed, live event reduction, visibility gating, write forwarding)
+// is written ONCE against this interface (see ConnectedStoragePanel); each
+// host only implements how the operations travel — Electron IPC channels, a
+// same-origin localStorage + `storage` events, or anything else.
+import type { StorageEvent, StorageItem, StorageWriteResult } from './storage-types.js'
+
+export interface StoragePanelSource {
+  /** Fetch the current item snapshot (seed on panel activation). */
+  getSnapshot(): Promise<StorageItem[]>
+  /** Live mutation pushes; returns an unsubscribe function. */
+  subscribe(onEvent: (evt: StorageEvent) => void): () => void
+  /** Visibility gate: hosts whose change feed costs something (listeners,
+   * polling) only keep it armed while some panel is visible. */
+  setActive(on: boolean): void
+  /** Write one entry. `key` carries the full `${appId}_` prefix. */
+  setItem(key: string, value: string): Promise<StorageWriteResult>
+  /** Remove one entry by full key. */
+  removeItem(key: string): Promise<StorageWriteResult>
+  /** Clear the active appId's entries only. */
+  clear(): Promise<StorageWriteResult>
+  /** Origin-wide wipe across every appId. Optional: hosts whose storage
+   * partition is shared with non-mini-program data must not provide it, and
+   * the panel then hides the「清空所有」action entirely. */
+  clearAll?(): Promise<StorageWriteResult>
+  /** The active appId namespace prefix (`${appId}_`), '' while unresolved. */
+  getPrefix(): Promise<string>
+}

package/src/storage-types.ts

@@ -0,0 +1,26 @@
+// 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.
+
+/** One storage entry. `key` carries the full `${appId}_` namespace prefix;
+ * values are the raw localStorage strings (objects are JSON-stringified by
+ * the runtime before they land here). */
+export interface StorageItem {
+  key: string
+  value: string
+}
+
+/** An incremental storage mutation pushed by a host's change feed (CDP
+ * DOMStorage events, `storage` DOM events, or synthesized after the host's
+ * own writes). Keys carry the full prefix, same as StorageItem. */
+export type StorageEvent =
+  | { type: 'added', key: string, newValue: string }
+  | { type: 'updated', key: string, oldValue: string, newValue: string }
+  | { type: 'removed', key: string }
+  | { type: 'cleared' }
+
+/** Result of a panel-initiated write. Failures carry a user-displayable
+ * message; the panel surfaces it inline instead of throwing. */
+export type StorageWriteResult =
+  | { ok: true }
+  | { ok: false, error: string }

package/src/types.ts

@@ -0,0 +1,35 @@
+// 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 interface WxmlNode {
+  tagName: string
+  attrs: Record<string, string>
+  children: WxmlNode[]
+  text?: string
+  sid?: string
+}
+
+/** Measurement of one element (by sid): bounding rect + the computed-style
+ * subset the panel footer displays. Producing it must not mutate the page —
+ * any visual highlight is the host's concern. */
+export interface ElementInspection {
+  sid: string
+  rect: {
+    x: number
+    y: number
+    width: number
+    height: number
+  }
+  style: {
+    display: string
+    position: string
+    boxSizing: string
+    margin: string
+    padding: string
+    color: string
+    backgroundColor: string
+    fontSize: string
+  }
+}

package/src/use-source-wiring.ts

@@ -0,0 +1,69 @@
+// 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'
+
+interface ConnectedSource {
+  setActive(on: boolean): void
+}
+
+export function useSourceWiring<S extends ConnectedSource>(options: {
+  source: S
+  /** Data availability gate: while false, zero source calls are made. */
+  enabled: boolean
+  /** Panel visibility (the host's tab-active state). */
+  active: boolean
+  /** Open the live push subscription; returns the unsubscriber. */
+  subscribe: (source: S) => () => void
+  /** Fetch + apply one snapshot. `isDisposed()` turns true once this seed's
+   * cleanup ran (unmount or a newer seed) — a resolution arriving after that
+   * must be dropped by the handler. */
+  seed: (source: S, isDisposed: () => boolean) => void
+}): void {
+  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: S | null, on: boolean }>({ 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/src/wxml-extract.ts

@@ -0,0 +1,366 @@
+import { registerSyntheticSid } from './sid-registry.js'
+import type { WxmlNode } from './types.js'
+
+export interface ComponentInstance extends Record<string, unknown> {
+  type?: Record<string, unknown>
+  props?: Record<string, unknown>
+  attrs?: Record<string, unknown>
+  parent?: Record<string, unknown>
+  appContext?: Record<string, unknown>
+  subTree?: Record<string, unknown>
+}
+
+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: string): string {
+  const base = regName.startsWith('dd-') ? regName.slice(3) : regName
+  return base.startsWith('tpl-') ? base.slice(4) : base
+}
+
+function resolveTemplateNameFromParent(instance: ComponentInstance): string | null {
+  const parent = instance.parent as Record<string, unknown> | undefined
+  const parentType = parent?.type as Record<string, unknown> | undefined
+  const components = parentType?.components as Record<string, unknown> | undefined
+  if (components) {
+    for (const [regName, comp] of Object.entries(components)) {
+      if (comp === instance.type) return normalizeRegisteredName(regName)
+    }
+  }
+  const appComponents = instance.appContext?.components as Record<string, unknown> | undefined
+  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: string): string {
+  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: ComponentInstance): string | null {
+  // dimina runtime 在 dd-page 的 setup 里 `instance.proxy.__page__ = true` 并
+  // `provide('path', path)`。两个标记同时具备才视为页面层级，避免 dd-page
+  // 的子节点继承 provides.path 后被误判（Vue 用 Object.create 链式 provides）。
+  const proxy = (instance as Record<string, unknown>).proxy as
+    | Record<string, unknown>
+    | undefined
+  if (proxy?.__page__ !== true) return null
+  const provides = (instance as Record<string, unknown>).provides as
+    | Record<string, unknown>
+    | undefined
+  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: ComponentInstance): string | null {
+  const provides = (instance as Record<string, unknown>).provides as Record<string, unknown> | undefined
+  const path = provides?.path
+  if (typeof path !== 'string' || !path) return null
+  const parent = instance.parent as Record<string, unknown> | undefined
+  const parentProvides = parent?.provides as Record<string, unknown> | undefined
+  if (path === parentProvides?.path) return null
+  return path.startsWith('/') ? path.slice(1) : path
+}
+
+function resolveTagName(instance: ComponentInstance): string {
+  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) as string | undefined
+  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: string, value: unknown): boolean {
+  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: string): string {
+  return value.split(/\s+/).filter((c) => !c.startsWith('dd-')).join(' ')
+}
+
+function stringifyPropValue(value: unknown): string {
+  return typeof value === 'object' ? JSON.stringify(value) : String(value)
+}
+
+function assignProp(out: Record<string, string>, key: string, value: unknown): void {
+  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: ComponentInstance): Record<string, string> {
+  const out: Record<string, string> = {}
+  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: Record<string, unknown>): boolean {
+  const props = vnode.props as Record<string, unknown> | null
+  if (!props) return false
+  const cls = String(props.class || '')
+  return cls.split(/\s+/).some((c) => INTERNAL_CLASSES.has(c))
+}
+
+function getElementSid(instance: ComponentInstance): string | undefined {
+  const subTree = instance.subTree as Record<string, unknown> | undefined
+  const el = subTree?.el as HTMLElement | undefined
+  if (!el?.getAttribute) return undefined
+  const sid = el.getAttribute('data-sid')
+  if (sid) return sid
+  return registerSyntheticSid(el)
+}
+
+function isTransparentComponent(instance: ComponentInstance, tagName: string): boolean {
+  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 as Record<string, unknown> | undefined
+    const is = props?.is as string | undefined
+    if (is && FRAMEWORK_TEMPLATE_RE.test(is)) return true
+    if (!is) {
+      const type = instance.type as Record<string, unknown> | undefined
+      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: Record<string, unknown>): boolean {
+  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: string): WxmlNode {
+  return { tagName: '#text', attrs: {}, children: [], text }
+}
+
+/** A component vnode's children come from walking its mounted instance, not `vnode.children`. */
+function childrenFromComponentVNode(component: ComponentInstance, depth: number): WxmlNode[] {
+  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: Record<string, unknown>, depth: number): WxmlNode[] {
+  const activeBranch = suspense.activeBranch as Record<string, unknown> | null
+  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: Record<string, unknown>): WxmlNode[] | null {
+  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: string): WxmlNode[] {
+  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: Record<string, unknown>, depth: number): WxmlNode[] {
+  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: unknown, depth: number): WxmlNode[] {
+  if (!child) return []
+  if (typeof child === 'string') return textChildEntry(child)
+  if (typeof child !== 'object') return []
+  const c = child as Record<string, unknown>
+  if (c.component) return childrenFromComponentVNode(c.component as ComponentInstance, 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: Record<string, unknown> | null | undefined, depth: number): WxmlNode[] {
+  if (!vnode || depth > 50) return []
+  if (isCommentVNode(vnode)) return []
+  if (vnode.component) return childrenFromComponentVNode(vnode.component as ComponentInstance, depth)
+  if (vnode.suspense) return childrenFromSuspenseVNode(vnode.suspense as Record<string, unknown>, depth)
+  const directText = directTextChild(vnode)
+  if (directText) return directText
+  const kids = vnode.children
+  if (!Array.isArray(kids)) return []
+  const result: WxmlNode[] = []
+  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: WxmlNode): WxmlNode {
+  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: Record<string, string> = {}
+  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: WxmlNode): WxmlNode {
+  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: ComponentInstance, depth: number): WxmlNode | WxmlNode[] | null {
+  if (depth > 50) return null
+  const tagName = resolveTagName(instance)
+  const children = extractChildrenFromVNode(instance.subTree as Record<string, unknown>, depth)
+  if (isTransparentComponent(instance, tagName)) return children.length > 0 ? children : null
+  const node: WxmlNode = { tagName, attrs: extractProps(instance), children }
+  const sid = getElementSid(instance)
+  if (sid) node.sid = sid
+  return wrapInShadowRoot(unwrapCustomComponent(node))
+}