@dimina-kit/inspect 0.3.0-dev.20260711141929

package/src/inspector.test.ts

@@ -0,0 +1,282 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { SYNTHETIC_SID_PREFIX } from './sid-registry.js'
+import { createWxmlInspector, type WxmlInspector } from './inspector.js'
+import type { WxmlNode } from './types.js'
+
+/** Minimal fake Vue instance leaf: a mounted element with no children of its own. */
+function makeLeafInstance(tagName: string, props: Record<string, unknown>, el: HTMLElement) {
+  return { type: { __tagName: tagName }, props, subTree: { el, children: [] } }
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+describe('createWxmlInspector', () => {
+  let inspector: WxmlInspector
+
+  beforeEach(() => {
+    inspector = createWxmlInspector({ document })
+  })
+
+  afterEach(() => {
+    inspector.dispose()
+    delete (document.body as unknown as Record<string, unknown>).__vue_app__
+    document.body.innerHTML = ''
+  })
+
+  describe('getWxml', () => {
+    it('returns null when body has no mounted Vue app', () => {
+      expect(inspector.getWxml()).toBeNull()
+    })
+
+    it('walks _instance into a WxmlNode tree with synthetic sids on nodes and their children', () => {
+      // Mounted-DOM fixture: the sid registry deliberately refuses to resolve
+      // disconnected elements, and a walked Vue subtree is always mounted.
+      const rootEl = document.createElement('div')
+      const childEl = document.createElement('span')
+      rootEl.appendChild(childEl)
+      document.body.appendChild(rootEl)
+      const child = makeLeafInstance('text', {}, childEl)
+      const root = {
+        type: { __tagName: 'view' },
+        props: { class: 'user-cls' },
+        subTree: { el: rootEl, children: [{ component: child }] },
+      }
+      ;(document.body as unknown as Record<string, unknown>).__vue_app__ = { _instance: root }
+
+      const tree = inspector.getWxml()
+
+      expect(tree?.tagName).toBe('view')
+      expect(tree?.attrs).toEqual({ class: 'user-cls' })
+      expect(tree?.sid).toMatch(new RegExp(`^${SYNTHETIC_SID_PREFIX}`))
+      expect(tree?.children).toHaveLength(1)
+      expect(tree?.children[0]).toMatchObject({ tagName: 'text', attrs: {}, children: [] })
+      expect(tree?.children[0]?.sid).toMatch(new RegExp(`^${SYNTHETIC_SID_PREFIX}`))
+      // The minted sids must round-trip back to the exact elements they came from.
+      expect(inspector.elementFor(tree!.sid!)).toBe(rootEl)
+      expect(inspector.elementFor(tree!.children[0]!.sid!)).toBe(childEl)
+    })
+
+    it('uses an element pre-existing data-sid attribute instead of minting a synthetic one', () => {
+      const el = document.createElement('div')
+      el.setAttribute('data-sid', 'real-sid-7')
+      const root = makeLeafInstance('view', {}, el)
+      ;(document.body as unknown as Record<string, unknown>).__vue_app__ = { _instance: root }
+
+      expect(inspector.getWxml()?.sid).toBe('real-sid-7')
+    })
+
+    it('falls back to _container._vnode.component when _instance is absent', () => {
+      const el = document.createElement('div')
+      const inst = makeLeafInstance('view', {}, el)
+      ;(document.body as unknown as Record<string, unknown>).__vue_app__ = {
+        _container: { _vnode: { component: inst } },
+      }
+
+      expect(inspector.getWxml()?.tagName).toBe('view')
+    })
+
+    it('wraps a multi-root walk result in a synthetic #fragment node', () => {
+      const elA = document.createElement('div')
+      const elB = document.createElement('div')
+      const childA = makeLeafInstance('view', {}, elA)
+      const childB = makeLeafInstance('text', {}, elB)
+      // A nameless top-level instance (no `type`) is transparent, so walking it
+      // surfaces its two component children as separate roots.
+      const root = { subTree: { children: [{ component: childA }, { component: childB }] } }
+      ;(document.body as unknown as Record<string, unknown>).__vue_app__ = { _instance: root }
+
+      const tree = inspector.getWxml()
+
+      expect(tree?.tagName).toBe('#fragment')
+      expect(tree?.children).toHaveLength(2)
+      expect(tree?.children.map((c: WxmlNode) => c.tagName)).toEqual(['view', 'text'])
+    })
+
+    it('returns null when the walked tree has no content', () => {
+      const root = { subTree: { children: [] } }
+      ;(document.body as unknown as Record<string, unknown>).__vue_app__ = { _instance: root }
+
+      expect(inspector.getWxml()).toBeNull()
+    })
+
+    it('defaults to globalThis.document when no document option is given', () => {
+      const defaultInspector = createWxmlInspector()
+      expect(() => defaultInspector.getWxml()).not.toThrow()
+      defaultInspector.dispose()
+    })
+  })
+
+  describe('highlightElement', () => {
+    it('measures rect and the requested style subset without mutating the element', () => {
+      const el = document.createElement('div')
+      el.setAttribute('data-sid', 'measured-1')
+      el.style.display = 'flex'
+      el.style.position = 'absolute'
+      el.style.boxSizing = 'border-box'
+      el.style.margin = '4px'
+      el.style.padding = '2px'
+      el.style.color = 'rgb(255, 0, 0)'
+      el.style.backgroundColor = 'rgb(0, 0, 255)'
+      el.style.fontSize = '16px'
+      document.body.appendChild(el)
+
+      const fakeRect = { x: 10, y: 20, width: 100, height: 50, top: 20, left: 10, right: 110, bottom: 70, toJSON() {} }
+      el.getBoundingClientRect = vi.fn(() => fakeRect as unknown as DOMRect)
+
+      const beforeHtml = document.body.innerHTML
+
+      const inspection = inspector.highlightElement('measured-1')
+
+      expect(inspection?.sid).toBe('measured-1')
+      expect(inspection?.rect).toEqual({ x: 10, y: 20, width: 100, height: 50 })
+      expect(inspection?.style).toEqual({
+        display: 'flex',
+        position: 'absolute',
+        boxSizing: 'border-box',
+        margin: '4px',
+        padding: '2px',
+        color: 'rgb(255, 0, 0)',
+        backgroundColor: 'rgb(0, 0, 255)',
+        fontSize: '16px',
+      })
+      // A measurement must be read-only: no attribute/overlay side effects.
+      expect(document.body.innerHTML).toBe(beforeHtml)
+      expect(document.body.children).toHaveLength(1)
+    })
+
+    it('returns null for an sid with no matching element', () => {
+      expect(inspector.highlightElement('does-not-exist')).toBeNull()
+    })
+  })
+
+  describe('elementFor', () => {
+    it('resolves a data-sid attribute to its live element', () => {
+      const el = document.createElement('div')
+      el.setAttribute('data-sid', 'find-me')
+      document.body.appendChild(el)
+
+      expect(inspector.elementFor('find-me')).toBe(el)
+    })
+
+    it('returns null for an sid with no registered or matching element', () => {
+      expect(inspector.elementFor('nope')).toBeNull()
+    })
+  })
+
+  describe('setObserving', () => {
+    it('merges a burst of DOM mutations into a single debounced callback', async () => {
+      const container = document.createElement('div')
+      document.body.appendChild(container)
+      const onMutated = vi.fn()
+      const observing = createWxmlInspector({ document, onMutated, debounceMs: 20 })
+
+      observing.setObserving(true)
+      container.setAttribute('data-x', '1')
+      container.setAttribute('data-x', '2')
+      container.appendChild(document.createElement('span'))
+
+      await wait(80)
+
+      expect(onMutated).toHaveBeenCalledTimes(1)
+      observing.dispose()
+    })
+
+    it('does not call back before observing has been turned on', async () => {
+      const container = document.createElement('div')
+      document.body.appendChild(container)
+      const onMutated = vi.fn()
+      const observing = createWxmlInspector({ document, onMutated, debounceMs: 20 })
+
+      container.setAttribute('data-x', '1')
+      await wait(80)
+
+      expect(onMutated).not.toHaveBeenCalled()
+      observing.dispose()
+    })
+
+    it('stops delivering callbacks once observing is turned off', async () => {
+      const container = document.createElement('div')
+      document.body.appendChild(container)
+      const onMutated = vi.fn()
+      const observing = createWxmlInspector({ document, onMutated, debounceMs: 20 })
+
+      observing.setObserving(true)
+      observing.setObserving(false)
+      container.setAttribute('data-x', '1')
+      await wait(80)
+
+      expect(onMutated).not.toHaveBeenCalled()
+      observing.dispose()
+    })
+
+    it('cancels a debounced callback already pending when observing turns off before it fires', async () => {
+      const container = document.createElement('div')
+      document.body.appendChild(container)
+      const onMutated = vi.fn()
+      const observing = createWxmlInspector({ document, onMutated, debounceMs: 30 })
+
+      observing.setObserving(true)
+      container.setAttribute('data-x', '1')
+      await wait(5) // mutation observed and debounce timer armed, well short of debounceMs
+      observing.setObserving(false)
+      await wait(80)
+
+      expect(onMutated).not.toHaveBeenCalled()
+      observing.dispose()
+    })
+
+    it('does not double the callback when turned on twice in a row', async () => {
+      const container = document.createElement('div')
+      document.body.appendChild(container)
+      const onMutated = vi.fn()
+      const observing = createWxmlInspector({ document, onMutated, debounceMs: 20 })
+
+      observing.setObserving(true)
+      observing.setObserving(true)
+      container.setAttribute('data-x', '1')
+      await wait(80)
+
+      expect(onMutated).toHaveBeenCalledTimes(1)
+      observing.dispose()
+    })
+
+    it('resumes observing after being turned off and back on', async () => {
+      const container = document.createElement('div')
+      document.body.appendChild(container)
+      const onMutated = vi.fn()
+      const observing = createWxmlInspector({ document, onMutated, debounceMs: 20 })
+
+      observing.setObserving(true)
+      observing.setObserving(false)
+      observing.setObserving(true)
+      container.setAttribute('data-x', '1')
+      await wait(80)
+
+      expect(onMutated).toHaveBeenCalledTimes(1)
+      observing.dispose()
+    })
+  })
+
+  describe('dispose', () => {
+    it('produces no further callbacks after dispose, even for mutations already pending', async () => {
+      const container = document.createElement('div')
+      document.body.appendChild(container)
+      const onMutated = vi.fn()
+      const observing = createWxmlInspector({ document, onMutated, debounceMs: 20 })
+
+      observing.setObserving(true)
+      container.setAttribute('data-x', '1')
+      observing.dispose()
+      await wait(80)
+
+      expect(onMutated).not.toHaveBeenCalled()
+    })
+
+    it('is safe to call before observing was ever turned on', () => {
+      const observing = createWxmlInspector({ document })
+      expect(() => observing.dispose()).not.toThrow()
+    })
+  })
+})

package/src/inspector.ts

@@ -0,0 +1,144 @@
+// 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, type ComponentInstance } from './wxml-extract.js'
+import type { ElementInspection, WxmlNode } from './types.js'
+
+export interface WxmlInspectorOptions {
+  /** Document hosting the mounted Vue app. Defaults to `globalThis.document`. */
+  document?: Document
+  /** Called (debounced) on every DOM change while observing is on. */
+  onMutated?: () => void
+  /** Debounce window for mutation bursts. Defaults to 200ms. */
+  debounceMs?: number
+}
+
+export interface WxmlInspector {
+  /** Walk `document.body.__vue_app__` into a WxmlNode tree. Multiple roots are
+   * wrapped in a synthetic `#fragment`; no app / empty tree → null. */
+  getWxml(): WxmlNode | null
+  /** Measure the element with `sid`: bounding rect + the computed-style subset
+   * the panel footer shows. Read-only — drawing a highlight is the host's job. */
+  highlightElement(sid: string): ElementInspection | null
+  /** Resolve the sid to its live DOM element (synthetic registry or data-sid). */
+  elementFor(sid: string): HTMLElement | null
+  /** Start/stop watching the page DOM. Idempotent in both directions; turning
+   * off cancels a pending debounced callback. */
+  setObserving(on: boolean): void
+  /** Stop observing; the instance produces no further callbacks. */
+  dispose(): void
+}
+
+/** Coalesce a burst of setData-driven mutations into one notify per frame-ish. */
+const DEFAULT_DEBOUNCE_MS = 200
+
+export function createWxmlInspector(options: WxmlInspectorOptions = {}): WxmlInspector {
+  const doc = options.document ?? globalThis.document
+  const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS
+  const onMutated = options.onMutated
+
+  const getVueApp = (): ComponentInstance | null => {
+    try {
+      const body = doc?.body as unknown as Record<string, unknown> | null
+      const app = body?.__vue_app__ as Record<string, unknown> | undefined
+      if (!app) return null
+      if (app._instance) return app._instance as ComponentInstance
+      const container = app._container as Record<string, unknown> | undefined
+      const vnode = container?._vnode as Record<string, unknown> | undefined
+      return (vnode?.component as ComponentInstance | null) ?? null
+    } catch {
+      return null
+    }
+  }
+
+  const getWxml = (): WxmlNode | null => {
+    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: string): HTMLElement | null => {
+    if (!sid) return null
+    return findElementBySid(doc, sid)
+  }
+
+  const highlightElement = (sid: string): ElementInspection | null => {
+    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: MutationObserver | null = null
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+  const notifyMutated = (): void => {
+    debounceTimer = null
+    onMutated?.()
+  }
+
+  const setObserving = (on: boolean): void => {
+    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 = (): void => {
+        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/src/panel-source.ts

@@ -0,0 +1,20 @@
+// The host-transport contract behind the WXML panel: the panel's data wiring
+// (seed, live push, visibility gating, element inspection) is written ONCE
+// against this interface (see ConnectedWxmlPanel); each host only implements
+// how the five operations travel — Electron IPC channels, iframe postMessage,
+// or anything else.
+import type { ElementInspection, WxmlNode } from './types.js'
+
+export interface WxmlPanelSource {
+  /** Fetch the current tree snapshot (seed / manual refresh). */
+  getSnapshot(): Promise<WxmlNode | null>
+  /** Live tree pushes; returns an unsubscribe function. */
+  subscribe(onTree: (tree: WxmlNode | null) => void): () => void
+  /** Visibility gate: the producer only observes the page DOM (and pays the
+   * Vue-tree walk) while some panel is visible. */
+  setActive(on: boolean): void
+  /** Measure the element with `sid`; the producer draws its own highlight. */
+  inspect(sid: string): Promise<ElementInspection | null>
+  /** Drop the current measurement highlight. */
+  clearInspection(): void | Promise<void>
+}