@dimina-kit/inspect 0.3.0 → 0.4.0-dev.20260716163758

package/src/use-active-bridge-id.test.tsx

@@ -0,0 +1,202 @@
+/**
+ * Unit tests for `useActiveBridgeId`.
+ *
+ * Validates the synchronous-derivation contract:
+ * - `activeBridgeId` must be correct on the **same render** as `bridges`
+ *   changes — no useEffect lag allowed.
+ * - Tracks the last newly-added bridge id automatically.
+ * - Manual selection via `setActiveBridge` is respected across rerenders
+ *   (while no new bridge id appears).
+ * - A newly-added bridge always overrides a prior manual selection.
+ * - If the selected bridge id is removed, falls back to the last bridge.
+ * - Calling `setActiveBridge` with an id not in `bridges` is ignored.
+ */
+import { describe, it, expect } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+
+import { useActiveBridgeId } from './use-active-bridge-id.js'
+
+const A = { id: 'A', pagePath: '/a' }
+const B = { id: 'B', pagePath: '/b' }
+const C = { id: 'C', pagePath: '/c' }
+
+describe('useActiveBridgeId — synchronous derivation contract', () => {
+  // Step 1: initial empty bridges → activeBridgeId is null
+  it('step 1: returns null when bridges is empty', () => {
+    const { result } = renderHook(() => useActiveBridgeId([]))
+    // Must be correct synchronously — no await / flush needed
+    expect(result.current.activeBridgeId).toBeNull()
+  })
+
+  // Step 2: first bridge appears → activeBridgeId follows immediately
+  it('step 2: tracks the only bridge synchronously on rerender', () => {
+    const { result, rerender } = renderHook(
+      ({ bridges }) => useActiveBridgeId(bridges),
+      { initialProps: { bridges: [] as typeof A[] } },
+    )
+    expect(result.current.activeBridgeId).toBeNull()
+
+    rerender({ bridges: [A] })
+    // Synchronous check — if the impl uses useEffect, this will still be null → red
+    expect(result.current.activeBridgeId).toBe('A')
+  })
+
+  // Step 3: new bridge B is appended → activeBridgeId follows the newest (last) id
+  it('step 3: follows the newest bridge when a new id is added', () => {
+    const { result, rerender } = renderHook(
+      ({ bridges }) => useActiveBridgeId(bridges),
+      { initialProps: { bridges: [] as Array<{ id: string; pagePath: string | null }> } },
+    )
+
+    rerender({ bridges: [A] })
+    expect(result.current.activeBridgeId).toBe('A')
+
+    rerender({ bridges: [A, B] })
+    // B is new — must be selected synchronously
+    expect(result.current.activeBridgeId).toBe('B')
+  })
+
+  // Step 4 + 5: manual setActiveBridge is respected and persists across rerenders
+  // without new bridge ids
+  it('step 4+5: setActiveBridge selects a valid id and persists across rerenders with no new bridges', () => {
+    const { result, rerender } = renderHook(
+      ({ bridges }) => useActiveBridgeId(bridges),
+      { initialProps: { bridges: [A, B] } },
+    )
+    // After initial render with [A, B], B is last → selected
+    expect(result.current.activeBridgeId).toBe('B')
+
+    // Step 4: manual select A
+    act(() => {
+      result.current.setActiveBridge('A')
+    })
+    expect(result.current.activeBridgeId).toBe('A')
+
+    // Step 5: rerender with the same ids — no new bridge → manual selection persists
+    rerender({ bridges: [A, B] })
+    expect(result.current.activeBridgeId).toBe('A')
+  })
+
+  // Step 6: selected bridge is removed → falls back to last bridge
+  it('step 6: falls back to last bridge when the selected bridge is removed', () => {
+    const { result, rerender } = renderHook(
+      ({ bridges }) => useActiveBridgeId(bridges),
+      { initialProps: { bridges: [A, B] } },
+    )
+
+    // Manually select A
+    act(() => {
+      result.current.setActiveBridge('A')
+    })
+    expect(result.current.activeBridgeId).toBe('A')
+
+    // Remove A — only B remains
+    rerender({ bridges: [B] })
+    expect(result.current.activeBridgeId).toBe('B')
+  })
+
+  // Step 7: new bridge C appears even when A was manually selected → C takes over
+  it('step 7: new bridge overrides prior manual selection synchronously', () => {
+    const { result, rerender } = renderHook(
+      ({ bridges }) => useActiveBridgeId(bridges),
+      { initialProps: { bridges: [A, B] } },
+    )
+
+    // Manual select A
+    act(() => {
+      result.current.setActiveBridge('A')
+    })
+    expect(result.current.activeBridgeId).toBe('A')
+
+    // C is a newly-added bridge id → must override manual selection
+    rerender({ bridges: [A, B, C] })
+    // Synchronous check — C must be selected in this render, not a future one
+    expect(result.current.activeBridgeId).toBe('C')
+  })
+
+  // Extra: setActiveBridge with unknown id is silently ignored
+  it('ignores setActiveBridge calls with an id not present in bridges', () => {
+    const { result } = renderHook(() => useActiveBridgeId([A, B]))
+    // Default: B (last)
+    expect(result.current.activeBridgeId).toBe('B')
+
+    act(() => {
+      result.current.setActiveBridge('DOES_NOT_EXIST')
+    })
+    // Still B — invalid id was ignored
+    expect(result.current.activeBridgeId).toBe('B')
+  })
+})
+
+describe('useActiveBridgeId — follows the simulator active page', () => {
+  // Auto-follow targets the page on screen, NOT just the last-inited bridge.
+  it('selects the bridge matching activePagePath instead of the last bridge', () => {
+    // B is last, but the active page is A → A wins.
+    const { result } = renderHook(() => useActiveBridgeId([A, B], '/a'))
+    expect(result.current.activeBridgeId).toBe('A')
+  })
+
+  // Switching a tabBar tab re-inits no bridge; only activePagePath changes.
+  it('re-follows when activePagePath changes with the same bridge set', () => {
+    const { result, rerender } = renderHook(
+      ({ active }) => useActiveBridgeId([A, B, C], active),
+      { initialProps: { active: '/a' } },
+    )
+    expect(result.current.activeBridgeId).toBe('A')
+
+    rerender({ active: '/c' })
+    expect(result.current.activeBridgeId).toBe('C')
+  })
+
+  // A tab switch overrides a stale manual pick — the panel returns to the page
+  // the user is now looking at.
+  it('drops a manual pick when the active page changes', () => {
+    const { result, rerender } = renderHook(
+      ({ active }) => useActiveBridgeId([A, B, C], active),
+      { initialProps: { active: '/a' } },
+    )
+    act(() => {
+      result.current.setActiveBridge('B')
+    })
+    expect(result.current.activeBridgeId).toBe('B')
+
+    // User switches the simulator to page C → follow C, not the pinned B.
+    rerender({ active: '/c' })
+    expect(result.current.activeBridgeId).toBe('C')
+  })
+
+  // While the active page is unchanged, a manual pick is still respected.
+  it('keeps a manual pick while activePagePath is unchanged', () => {
+    const { result, rerender } = renderHook(
+      ({ active }) => useActiveBridgeId([A, B, C], active),
+      { initialProps: { active: '/a' } },
+    )
+    act(() => {
+      result.current.setActiveBridge('B')
+    })
+    expect(result.current.activeBridgeId).toBe('B')
+
+    rerender({ active: '/a' })
+    expect(result.current.activeBridgeId).toBe('B')
+  })
+
+  // pagePath comparison tolerates a leading slash on either side.
+  it('matches activePagePath regardless of a leading slash', () => {
+    const bareA = { id: 'A', pagePath: 'pages/a/a' }
+    const bareB = { id: 'B', pagePath: 'pages/b/b' }
+    const { result } = renderHook(() => useActiveBridgeId([bareA, bareB], '/pages/a/a'))
+    expect(result.current.activeBridgeId).toBe('A')
+  })
+
+  // No active page / no matching bridge → keep the legacy newest-bridge default.
+  it('falls back to the last bridge when the active page is empty or unmatched', () => {
+    const { result, rerender } = renderHook(
+      ({ active }) => useActiveBridgeId([A, B], active),
+      { initialProps: { active: '' } },
+    )
+    expect(result.current.activeBridgeId).toBe('B')
+
+    rerender({ active: '/zzz' })
+    expect(result.current.activeBridgeId).toBe('B')
+  })
+})

package/src/use-active-bridge-id.ts

@@ -0,0 +1,71 @@
+import { useState } from 'react'
+
+function normalizePagePath(p: string | null | undefined): string {
+  return (p ?? '').replace(/^\/+/, '')
+}
+
+/**
+ * Derive which AppData page tab is active, synchronously.
+ *
+ * `activeBridgeId` is a pure derivation of (current bridges, the simulator's
+ * active page, manual pick), computed during render — so it is never stale for
+ * a frame the way a useEffect-derived value would be. Auto-follow tracks the
+ * page the user is actually looking at: when `activePagePath` matches a
+ * bridge's pagePath the panel snaps to it, so switching tabBar tabs (which
+ * re-inits no bridge) still moves the panel. A brand-new bridge id appearing or
+ * the active page changing both drop a prior manual pick back to auto-follow.
+ */
+export function useActiveBridgeId(
+  bridges: ReadonlyArray<{ id: string; pagePath: string | null }>,
+  activePagePath = '',
+): { activeBridgeId: string | null; setActiveBridge: (id: string) => void } {
+  const ids = bridges.map((b) => b.id)
+  // NUL separator: ids are runtime-generated and never contain it, so two
+  // distinct id lists can never collide on the same key.
+  const idsKey = ids.join('\x00')
+
+  // The user's manual tab pick; null means "auto-follow the active page".
+  const [selectedBridgeId, setSelectedBridgeId] = useState<string | null>(null)
+  // The id list from the previous render — lets us spot a freshly-inited page.
+  const [prevIdsKey, setPrevIdsKey] = useState('')
+  // The active page from the previous render — lets us spot a tab switch.
+  const [prevActivePath, setPrevActivePath] = useState(activePagePath)
+
+  if (idsKey !== prevIdsKey) {
+    // The bridge set changed. If a never-before-seen id appeared, a new page
+    // inited → drop back to auto-follow. Adjusting state during render is the
+    // React-sanctioned alternative to an effect: React re-renders synchronously
+    // before the commit, so `activeBridgeId` below is correct this frame.
+    const prevIds = prevIdsKey ? prevIdsKey.split('\x00') : []
+    if (ids.some((id) => !prevIds.includes(id))) {
+      setSelectedBridgeId(null)
+    }
+    setPrevIdsKey(idsKey)
+  }
+
+  if (activePagePath !== prevActivePath) {
+    // The simulator navigated to a different active page (e.g. a tabBar switch).
+    // Drop the manual pick so the panel re-follows the page on screen — without
+    // this, switching tabs leaves the panel stuck on whichever page inited last.
+    setSelectedBridgeId(null)
+    setPrevActivePath(activePagePath)
+  }
+
+  // Auto-follow target: the bridge whose pagePath matches the active page.
+  const activeFollowId = activePagePath
+    ? bridges.find((b) => normalizePagePath(b.pagePath) === normalizePagePath(activePagePath))?.id ?? null
+    : null
+
+  const activeBridgeId
+    = selectedBridgeId && ids.includes(selectedBridgeId)
+      ? selectedBridgeId
+      // Prefer the active page; fall back to the newest bridge when the active
+      // page is unknown or has no matching bridge yet.
+      : (activeFollowId ?? ids.at(-1) ?? null)
+
+  const setActiveBridge = (id: string): void => {
+    if (ids.includes(id)) setSelectedBridgeId(id)
+  }
+
+  return { activeBridgeId, setActiveBridge }
+}

package/src/wxml-extract.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { resolveTagName } from './wxml-extract.js'
+import type { ComponentInstance } from './wxml-extract.js'
+
+function instance(type: Record<string, unknown>, extra: Record<string, unknown> = {}): ComponentInstance {
+  return { type, ...extra } as ComponentInstance
+}
+
+describe('resolveTagName: authoritative Vue name = source path', () => {
+  it('surfaces a custom component whose name is its full module path', () => {
+    // The render runtime sets `name: componentPath` on every usingComponents
+    // entry, so the panel tags the node with its source path (WeChat parity).
+    expect(resolveTagName(instance({ name: '/components/ubt/index' }))).toBe('components/ubt/index')
+  })
+
+  it('surfaces a page whose name is its module path', () => {
+    expect(resolveTagName(instance({ name: 'pages/tab/home/index' }))).toBe('pages/tab/home/index')
+  })
+
+  it('strips the leading slash so tags never start with `/`', () => {
+    expect(resolveTagName(instance({ name: '/pages/index/index' }))).toBe('pages/index/index')
+  })
+
+  it('accepts the path off `__name` when `name` is absent', () => {
+    expect(resolveTagName(instance({ __name: '/node-modules/pickpic/thumbnail/image' })))
+      .toBe('node-modules/pickpic/thumbnail/image')
+  })
+
+  it('resolves from `type.name` alone, without any provides chain', () => {
+    // Robustness over the legacy provide/inject reconstruction, which needed a
+    // live parent provides chain; the per-type name carries the path directly.
+    expect(resolveTagName(instance({ name: '/components/card/card' }, { parent: undefined, provides: undefined })))
+      .toBe('components/card/card')
+  })
+})
+
+describe('resolveTagName: non-path names keep the legacy fallback behavior', () => {
+  it('kebab-cases a built-in PascalCase name (no slash → not a source path)', () => {
+    expect(resolveTagName(instance({ name: 'ScrollView' }))).toBe('scroll-view')
+  })
+
+  it('does NOT mislabel a nameless `__scopeId` wrapper as a second page', () => {
+    // A Taro template wrapper (`taro_tmpl`/`tmpl_0_3`) carries `__scopeId` but no
+    // path-name and is not a page; it must fall back to `template`, never `page`.
+    const wrapper = instance(
+      { __scopeId: 'data-v-abc' },
+      { parent: { type: { components: {} } }, appContext: { components: {} } },
+    )
+    expect(resolveTagName(wrapper)).not.toBe('page')
+    expect(resolveTagName(wrapper)).toBe('template')
+  })
+
+  it('no longer reconstructs a path from the provides chain (heuristic removed)', () => {
+    // Identity now comes solely from the authoritative `name`. An instance that
+    // only carries the legacy signals (proxy.__page__ + provides.path, no
+    // path-like name) is NOT upgraded to its path — it falls back like any
+    // nameless __scopeId wrapper. Real pages/components always carry `name`.
+    const legacy = instance(
+      { __scopeId: 'data-v-x' },
+      {
+        proxy: { __page__: true },
+        provides: { path: '/pages/legacy/legacy' },
+        parent: { type: { components: {} } },
+        appContext: { components: {} },
+      },
+    )
+    expect(resolveTagName(legacy)).not.toBe('pages/legacy/legacy')
+    expect(resolveTagName(legacy)).toBe('template')
+  })
+})

package/src/wxml-extract.ts

@@ -55,71 +55,25 @@ 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 {
+export 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
+  // Authoritative source-path identity: the render runtime sets each compiled
+  // page/custom-component's Vue `name` to its miniprogram module path. A name
+  // containing `/` IS that source path — trust it directly (WeChat parity).
+  // It is per-type (not inherited via provides), so a descendant never leaks its
+  // ancestor's path, and it needs no live provide/inject chain to reconstruct.
+  const nameId = (type.name || type.__name) as string | undefined
+  if (nameId && nameId.includes('/')) {
+    return nameId.startsWith('/') ? nameId.slice(1) : nameId
+  }
   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
+    // A nameless component carrying a `__scopeId` is a framework template
+    // wrapper (e.g. a Taro `taro_tmpl`/`tmpl_0_3`) — pages and custom components
+    // carry a path `name` and are resolved above. Recover the registered tag and
+    // fall back to `template`; never default to `page` here, which would
     // mislabel every such wrapper as a second page root.
     if (type.__scopeId) return resolveTemplateNameFromParent(instance) || 'template'
     return 'unknown'
@@ -190,12 +144,35 @@ function getElementSid(instance: ComponentInstance): string | undefined {
   return registerSyntheticSid(el)
 }
 
+/**
+ * The absolute component path a `dd-wrapper` carries in its `name` prop/attr, or
+ * null. dimina wraps EVERY custom-component template root in
+ * `<dd-wrapper name="/components/foo/foo">`; the path always starts with `/`,
+ * which a user-authored `name` attr essentially never does.
+ */
+function wrapperPathName(instance: ComponentInstance): string | null {
+  for (const raw of [instance.props, instance.attrs]) {
+    const n = (raw as Record<string, unknown> | undefined)?.name
+    if (typeof n === 'string' && n.startsWith('/')) return n
+  }
+  return null
+}
+
 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
+  // dimina wraps every custom-component template root in a
+  // `<dd-wrapper name="/path">`. Under the name-path model the ENCLOSING
+  // component instance already carries that same source path as its own node
+  // (its Vue `name` IS the path), so surfacing the wrapper too would emit a
+  // SECOND identical path node — the doubled `<components/foo/foo>` layer. The
+  // wrapper is redundant scaffolding: pass its children through. Gated on a
+  // path-shaped `name` so a user-authored `<wrapper name="x">` is never
+  // swallowed (dimina paths always start with `/`).
+  if (tagName === 'wrapper' && wrapperPathName(instance)) return true
   if (tagName === 'template') {
     const props = instance.props as Record<string, unknown> | undefined
     const is = props?.is as string | undefined
@@ -296,45 +273,6 @@ function extractChildrenFromVNode(vnode: Record<string, unknown> | null | undefi
   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`，对齐微信开发者工具：组件本身
@@ -362,5 +300,5 @@ export function walkInstance(instance: ComponentInstance, depth: number): WxmlNo
   const node: WxmlNode = { tagName, attrs: extractProps(instance), children }
   const sid = getElementSid(instance)
   if (sid) node.sid = sid
-  return wrapInShadowRoot(unwrapCustomComponent(node))
+  return wrapInShadowRoot(node)
 }