@dimina-kit/devtools 0.4.0-dev.20260618090552 → 0.4.0-dev.20260624084417

package/dist/main/services/views/devtools-tabs.js

@@ -35,9 +35,12 @@
  */
 /**
  * Canonical DevTools panel view ids kept in the DEFAULT tab bar (stable front-end
- * ids, unchanged for many Chromium releases): `elements`, `console`, `network`.
+ * ids, unchanged for many Chromium releases): `elements`, `console`, `network`,
+ * `sources`. Sources stays so a source-link click that isn't routed to Monaco
+ * (build/runtime chunks, framework frames) still has a panel to reveal in instead
+ * of silently no-op'ing.
  */
-export const DEVTOOLS_KEPT_VIEW_IDS = ['elements', 'console', 'network'];
+export const DEVTOOLS_KEPT_VIEW_IDS = ['elements', 'console', 'network', 'sources'];
 /**
  * Build the `executeJavaScript` source injected into the DevTools front-end
  * WebContents. The kept ids + display names are carried as JSON data literals
@@ -48,13 +51,19 @@ export function buildCustomizeTabsScript(keptIds = DEVTOOLS_KEPT_VIEW_IDS) {
     // fallback path); the DevTools UI may be EN or ZH, so include both.
     const NAME_MAP = {
         elements: ['Elements', '元素'], console: ['Console', '控制台'], network: ['Network', '网络'],
+        sources: ['Sources', '来源', '源代码'],
     };
     const keepNames = keptIds.flatMap((id) => NAME_MAP[id] ?? [id]);
     const keepIdsJson = JSON.stringify(JSON.stringify([...keptIds]));
     const keepNamesJson = JSON.stringify(JSON.stringify(keepNames));
+    const srcNamesJson = JSON.stringify(JSON.stringify(NAME_MAP.sources));
+    const netNamesJson = JSON.stringify(JSON.stringify(NAME_MAP.network));
     return `(function(){try{
     var KEEPID = new Set(JSON.parse(${keepIdsJson}));
     var KEEPNAME = new Set(JSON.parse(${keepNamesJson}));
+    var SRCNAME = new Set(JSON.parse(${srcNamesJson}));
+    var NETNAME = new Set(JSON.parse(${netNamesJson}));
+    var WANT_SOURCES_LAST = KEEPID.has('sources');
     // (1) Locale infobar — official host-preference suppression (NOT localStorage).
     try { var IFH=globalThis.InspectorFrontendHost; if(IFH&&typeof IFH.setPreference==='function'){ IFH.setPreference('disable-locale-info-bar','true'); } }catch(_){}
     function deepCollect(sel,cap){ var out=[],seen=0,stack=[document]; while(stack.length&&seen<(cap||40000)){ var root=stack.pop(); try{var m=root.querySelectorAll?root.querySelectorAll(sel):[];for(var i=0;i<m.length;i++)out.push(m[i]);}catch(_){} try{var all=root.querySelectorAll?root.querySelectorAll('*'):[];for(var j=0;j<all.length;j++){seen++;if(all[j].shadowRoot)stack.push(all[j].shadowRoot);}}catch(_){} } return out; }
@@ -82,9 +91,18 @@ export function buildCustomizeTabsScript(keptIds = DEVTOOLS_KEPT_VIEW_IDS) {
           handled=true;
         }catch(_){} }
         // fallback: registrations not enumerable -> at least clear the bar by id
-        if(!handled){ var FALL=['timeline','resources','heap-profiler','sources','security','lighthouse','chrome-recorder','coverage','linear-memory-inspector','sensors','rendering','animations','autofill-view','medias','issues-pane']; for(var fr=0;fr<FALL.length;fr++){ try{ if(!KEEPID.has(FALL[fr])) maybeRemove(FALL[fr]); }catch(_){} } }
+        if(!handled){ var FALL=['timeline','resources','heap-profiler','security','lighthouse','chrome-recorder','coverage','linear-memory-inspector','sensors','rendering','animations','autofill-view','medias','issues-pane']; for(var fr=0;fr<FALL.length;fr++){ try{ if(!KEEPID.has(FALL[fr])) maybeRemove(FALL[fr]); }catch(_){} } }
       } else { domFallback(); }
     })();
+    // Keep Sources LAST in the bar (after Network). Default DevTools order puts
+    // Sources between Console and Network; nudge it to just after Network. Runs in
+    // BOTH paths (registry removal leaves the kept tabs in default order). Self-
+    // stable: once Sources follows Network the condition no longer holds.
+    if(WANT_SOURCES_LAST){ var ro=0,rt=setInterval(function(){ ro++; try{
+      var tabs=deepCollect('[role="tab"]'),src=null,net=null;
+      for(var i=0;i<tabs.length;i++){ var n=txt(tabs[i]); if(SRCNAME.has(n))src=tabs[i]; else if(NETNAME.has(n))net=tabs[i]; }
+      if(src&&net&&src.parentElement&&src.parentElement===net.parentElement&&(src.compareDocumentPosition(net)&Node.DOCUMENT_POSITION_FOLLOWING)){ net.parentElement.insertBefore(src,net.nextSibling); }
+    }catch(_){} if(ro>120)clearInterval(rt); },60); }
     // DOM fallback: only if the ESM module couldn't be resolved at all.
     function domFallback(){ var cachedBar=null;
       function findBar(){ if(cachedBar&&cachedBar.isConnected)return cachedBar; cachedBar=null; var tabs=deepCollect('[role="tab"]'); var a=null; for(var i=0;i<tabs.length;i++){if(KEEPNAME.has(txt(tabs[i]))){a=tabs[i];break;}} if(!a)return null; var p=a.parentElement; while(p){try{if(p.querySelectorAll('[role="tab"]').length>1){cachedBar=p;return p;}}catch(_){} p=p.parentElement;} cachedBar=a.parentElement; return cachedBar; }

package/dist/main/services/views/host-toolbar-session-runtime.d.ts

@@ -2,15 +2,15 @@
  * Ref-counted registration of the host-toolbar framework runtime on
  * `session.defaultSession`.
  *
- * The toolbar's height advertiser no longer rides the toolbar WCV's
- * `webPreferences.preload` (a host's `setPreloadPath` used to replace it and
- * the strip height collapsed to 0). Instead the runtime bundle
+ * The toolbar's height advertiser does not ride the toolbar WCV's
+ * `webPreferences.preload`: a host's `setPreloadPath` would replace it and the
+ * strip height would collapse to 0. Instead the runtime bundle
  * (`hostToolbarRuntimePreloadPath`) is registered once per process as a
  * session frame preload; its own guard (`--dimina-host-toolbar` marker +
  * `isMainFrame`) keeps it a zero-footprint no-op in every other defaultSession
  * renderer.
  *
- * Ref-counting (codex condition 3): multiple ViewManagers can coexist in one
+ * Ref-counting: multiple ViewManagers can coexist in one
  * process and share the ONE defaultSession. Each manager acquires at most one
  * reference (on first toolbar need) and releases it in `disposeAll`. Only the
  * first acquire registers; only the last release unregisters (with the id

package/dist/main/services/views/host-toolbar-session-runtime.js

@@ -2,15 +2,15 @@
  * Ref-counted registration of the host-toolbar framework runtime on
  * `session.defaultSession`.
  *
- * The toolbar's height advertiser no longer rides the toolbar WCV's
- * `webPreferences.preload` (a host's `setPreloadPath` used to replace it and
- * the strip height collapsed to 0). Instead the runtime bundle
+ * The toolbar's height advertiser does not ride the toolbar WCV's
+ * `webPreferences.preload`: a host's `setPreloadPath` would replace it and the
+ * strip height would collapse to 0. Instead the runtime bundle
  * (`hostToolbarRuntimePreloadPath`) is registered once per process as a
  * session frame preload; its own guard (`--dimina-host-toolbar` marker +
  * `isMainFrame`) keeps it a zero-footprint no-op in every other defaultSession
  * renderer.
  *
- * Ref-counting (codex condition 3): multiple ViewManagers can coexist in one
+ * Ref-counting: multiple ViewManagers can coexist in one
  * process and share the ONE defaultSession. Each manager acquires at most one
  * reference (on first toolbar need) and releases it in `disposeAll`. Only the
  * first acquire registers; only the last release unregisters (with the id

package/dist/main/services/views/view-manager.d.ts

@@ -1,5 +1,6 @@
 import type { WebContents } from 'electron';
 import type { NativeDeviceInfo } from '../../../shared/ipc-channels.js';
+import { type OpenInEditorRequest } from '../../../shared/open-in-editor.js';
 import { type WorkbenchContext } from '../workbench-context.js';
 import { type HostToolbarMessageSubscription } from './host-toolbar-port-channel.js';
 /**
@@ -17,6 +18,8 @@ export interface ViewManagerContext {
      * `createWorkbenchContext` always supplies it.
      */
     connections: WorkbenchContext['connections'];
+    /** Active project root used to validate/open console source locations. */
+    workspace?: WorkbenchContext['workspace'];
     /**
      * Absolute path to the simulator preload bundle. Only consumed by the
      * native-host simulator WebContentsView (`attachNativeSimulator`); the
@@ -82,7 +85,7 @@ export interface ViewManager {
      * `simWidth` rides the wire for schema compatibility but is unused: all
      * geometry is anchor-published.
      */
-    attachNativeSimulator(simulatorUrl: string, simWidth: number): void;
+    attachNativeSimulator(simulatorUrl: string, simWidth: number): Promise<void>;
     /**
      * Destroy and null out the simulator view (e.g. on simulator detach).
      * Also destroys the cached settings view and hides the popover —
@@ -106,6 +109,8 @@ export interface ViewManager {
     getSimulatorWebContentsId(): number | null;
     /** Return the live webContents of the currently attached simulator, or null. */
     getSimulatorWebContents(): WebContents | null;
+    /** Return the active project path bound to the current native simulator. */
+    getSimulatorProjectPath(): string | null;
     /** Return the settings overlay's WebContents (for renderer-notifier). */
     getSettingsWebContents(): WebContents | null;
     /** Return the webContents ID of the settings overlay if alive, else null. */
@@ -277,6 +282,17 @@ export interface HostToolbarControl {
      */
     setHeightMode(mode: HostToolbarHeightMode): void;
 }
+export interface ProjectEditorTarget {
+    path: string;
+    line?: number;
+    column?: number;
+}
+/**
+ * Resolve a DevTools source request against the service-host URL that created
+ * the inspected app. Its pkgRoot is authoritative; the workspace is only a
+ * stale-session consistency guard.
+ */
+export declare function resolveProjectEditorTarget(serviceHostUrl: string, activeProjectRoot: string | undefined, req: OpenInEditorRequest, isFile?: (absolutePath: string) => boolean): ProjectEditorTarget | null;
 /**
  * Build a ViewManager bound to the given context. The returned object is the
  * only component allowed to instantiate or add/remove overlay WebContentsViews.

package/dist/main/services/views/view-manager.js

@@ -1,10 +1,11 @@
 import { ipcMain, nativeTheme, shell, WebContentsView, webContents } from 'electron';
+import fs from 'node:fs';
 import path from 'path';
 import { cjsSiblingPreloadPath, mainPreloadPath } from '../../utils/paths.js';
 import { simDeskBg } from '../../utils/theme.js';
 import { applyNavigationHardening, handleWindowOpenExternal, } from '../../windows/navigation-hardening.js';
 import { SimulatorCustomApiBridgeChannel } from '../../../shared/ipc-channels.js';
-import { OPEN_IN_EDITOR_SCHEME, decodeOpenInEditorUrl, resourceUrlToProjectRelativePath, } from '../../../shared/open-in-editor.js';
+import { buildDevtoolsProjectSourceLinksScript, decodeOpenInEditorUrl, projectSourceContextFromServiceHostUrl, resourceUrlToProjectRelativePath, } from '../../../shared/open-in-editor.js';
 import { createSafeAreaController } from '../safe-area/index.js';
 import { buildCustomizeTabsScript } from './devtools-tabs.js';
 import { installElementsForward } from '../elements-forward/index.js';
@@ -16,6 +17,35 @@ import { acquireHostToolbarSessionRuntime, releaseHostToolbarSessionRuntime, } f
 import { createHostToolbarPortChannel, } from './host-toolbar-port-channel.js';
 import { parseRoute } from '../../../shared/simulator-route.js';
 import { HEADER_H, HOST_TOOLBAR_RUNTIME_MARKER } from '../../../shared/constants.js';
+/**
+ * Resolve a DevTools source request against the service-host URL that created
+ * the inspected app. Its pkgRoot is authoritative; the workspace is only a
+ * stale-session consistency guard.
+ */
+export function resolveProjectEditorTarget(serviceHostUrl, activeProjectRoot, req, isFile = (absolutePath) => fs.statSync(absolutePath).isFile()) {
+    const sourceContext = projectSourceContextFromServiceHostUrl(serviceHostUrl, activeProjectRoot);
+    if (!sourceContext)
+        return null;
+    const rel = resourceUrlToProjectRelativePath(req.url, sourceContext);
+    if (!rel)
+        return null;
+    const absolute = path.resolve(sourceContext.projectRoot, ...rel.split('/'));
+    const fromRoot = path.relative(path.resolve(sourceContext.projectRoot), absolute);
+    if (!fromRoot || fromRoot.startsWith('..') || path.isAbsolute(fromRoot))
+        return null;
+    try {
+        if (!isFile(absolute))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return {
+        path: rel,
+        line: typeof req.line === 'number' ? req.line + 1 : undefined,
+        column: typeof req.column === 'number' ? req.column + 1 : undefined,
+    };
+}
 /**
  * Build a ViewManager bound to the given context. The returned object is the
  * only component allowed to instantiate or add/remove overlay WebContentsViews.
@@ -37,6 +67,8 @@ export function createViewManager(ctx) {
     // while `simulatorView` above hosts its DevTools in the right panel region.
     let nativeSimulatorView = null;
     let nativeSimulatorViewAdded = false;
+    let nativeSimulatorProjectPath = null;
+    let settleNativeSimulatorReady = null;
     // Model A: the renderer's measured inner-screen rect is the SOLE authority for
     // the native simulator WCV bounds (see docs/simulator-render-architecture.md).
     // Cache the last rect so a report that lands before attachNativeSimulator (the
@@ -429,43 +461,18 @@ export function createViewManager(ctx) {
     // `devtools-open-url` on the inspected (service-host) wc, which we decode,
     // map to a project-relative path, and broadcast to the renderer's Monaco.
     const openInEditorWiredWcIds = new Set();
-    function injectOpenResourceHandler(devtoolsWc) {
-        // `setOpenResourceHandler` is the official Chromium DevTools hook IDEs use
-        // to route source-link clicks to an external editor. We poll for the host
-        // (it appears once the front-end finishes bootstrapping, like `UI` above)
-        // and register a handler that re-emits an encoded sentinel via
-        // `openInNewTab` → Electron `devtools-open-url`. Best-effort: wrapped in
-        // try/catch and a bounded poll so a missing API never throws.
-        const scheme = JSON.stringify(OPEN_IN_EDITOR_SCHEME);
-        devtoolsWc.executeJavaScript(`
-      (function() {
-        try {
-          let tries = 0
-          const timer = setInterval(() => {
-            tries++
-            try {
-              const Host = globalThis.Host
-              const host = Host && Host.InspectorFrontendHost
-              if (host && typeof host.setOpenResourceHandler === 'function'
-                       && typeof host.openInNewTab === 'function') {
-                host.setOpenResourceHandler((url, lineNumber, columnNumber) => {
-                  try {
-                    const p = new URLSearchParams()
-                    p.set('u', String(url))
-                    if (typeof lineNumber === 'number') p.set('l', String(lineNumber))
-                    if (typeof columnNumber === 'number') p.set('c', String(columnNumber))
-                    host.openInNewTab(${scheme} + ':?' + p.toString())
-                  } catch (_) {}
-                })
-                clearInterval(timer)
-                return
-              }
-            } catch (_) {}
-            if (tries > 80) clearInterval(timer)
-          }, 50)
-        } catch (_) {}
-      })()
-    `).catch(() => { });
+    function injectOpenResourceHandler(serviceWc, devtoolsWc) {
+        // Inject the front-end glue that routes a project source-link click to our
+        // Monaco editor instead of the DevTools Sources panel: a capture-phase click
+        // interceptor re-emits an encoded sentinel via
+        // `InspectorFrontendHost.openInNewTab` → Electron `devtools-open-url`. (The
+        // legacy `setOpenResourceHandler` hook this used to rely on is gone in
+        // current Chromium, so the script keeps it only as a fallback.) Best-effort:
+        // the script is fully try/catch-wrapped so a missing API never throws.
+        const sourceContext = projectSourceContextFromServiceHostUrl(serviceWc.getURL(), ctx.workspace?.getProjectPath?.());
+        if (!sourceContext)
+            return;
+        devtoolsWc.executeJavaScript(buildDevtoolsProjectSourceLinksScript(sourceContext)).catch(() => { });
     }
     // ── DevTools tab customization: keep only Elements/Console/Network ──────────
     // Inject into the same DevTools front-end host wc that the console/network
@@ -502,10 +509,10 @@ export function createViewManager(ctx) {
         // wc is recreated per simulatorView, so a fresh host needs the handler set.
         if (!devtoolsWc.isDestroyed()) {
             if (devtoolsWc.isLoading()) {
-                devtoolsWc.once('dom-ready', () => injectOpenResourceHandler(devtoolsWc));
+                devtoolsWc.once('dom-ready', () => injectOpenResourceHandler(serviceWc, devtoolsWc));
             }
             else {
-                injectOpenResourceHandler(devtoolsWc);
+                injectOpenResourceHandler(serviceWc, devtoolsWc);
             }
         }
         // Attach the `devtools-open-url` decoder to the inspected service wc once
@@ -518,13 +525,10 @@ export function createViewManager(ctx) {
             const req = decodeOpenInEditorUrl(url);
             if (!req)
                 return; // not our sentinel — leave it to Electron's default path
-            const rel = resourceUrlToProjectRelativePath(req.url);
-            if (!rel)
+            const target = resolveProjectEditorTarget(serviceWc.getURL(), ctx.workspace?.getProjectPath?.(), req);
+            if (!target)
                 return;
-            // DevTools reports 0-based line/column; Monaco is 1-based.
-            const line = typeof req.line === 'number' ? req.line + 1 : undefined;
-            const column = typeof req.column === 'number' ? req.column + 1 : undefined;
-            ctx.notify.editorOpenFile({ path: rel, line, column });
+            ctx.notify.editorOpenFile(target);
         };
         serviceWc.on('devtools-open-url', onOpenUrl);
         // Consolidate teardown onto the connection layer (foundation.md §4 / P2),
@@ -793,8 +797,12 @@ export function createViewManager(ctx) {
     function attachNativeSimulator(simulatorUrl, _simWidth) {
         if (!ctx.preloadPath) {
             console.error('[workbench] attachNativeSimulator — preloadPath unset; cannot mount native simulator');
-            return;
+            return Promise.resolve();
         }
+        // Unblock a superseded IPC invocation. Its renderer effect cleanup marks
+        // that generation cancelled, so this cannot schedule a stale capture.
+        settleNativeSimulatorReady?.();
+        settleNativeSimulatorReady = null;
         // Tear down any previous native simulator view (relaunch / re-open).
         if (nativeSimulatorView) {
             detachNativeCustomApiBridge();
@@ -813,6 +821,10 @@ export function createViewManager(ctx) {
             catch { /* ignore */ }
             nativeSimulatorView = null;
         }
+        nativeSimulatorProjectPath = null;
+        const ready = new Promise((resolve) => {
+            settleNativeSimulatorReady = resolve;
+        });
         // Derive THIS project's session partition from the simulator URL's appId so
         // its cookies/localStorage/cache are isolated from every other project (P0
         // debt). Same project → same partition (storage survives a relaunch);
@@ -840,6 +852,7 @@ export function createViewManager(ctx) {
             },
         });
         nativeSimulatorView = view;
+        nativeSimulatorProjectPath = ctx.workspace?.getProjectPath() || null;
         // Paint the WCV surface the themed desk color (simDeskBg(): dark #121212 /
         // light #e8e8e8) so a height-resize that grows the region never flashes a
         // mismatched strip before DeviceShell's desk repaints — the WCV, the desk,
@@ -929,6 +942,15 @@ export function createViewManager(ctx) {
                     e.preventDefault();
                 }
             });
+            // The outer DeviceShell loading is insufficient: slow projects attach a
+            // render guest later. Resolve the renderer's attach IPC only after that
+            // first mini-app page has completed its own document load.
+            guestWc.once('did-finish-load', () => {
+                if (nativeSimulatorView !== view || simWc.isDestroyed())
+                    return;
+                settleNativeSimulatorReady?.();
+                settleNativeSimulatorReady = null;
+            });
             // A render-host guest only attaches after a spawn, so the service window
             // exists by now — (re)point the right-panel DevTools at it. Belt-and-braces
             // with the `onRenderEvent` path in case its emit lost the attach race.
@@ -984,8 +1006,11 @@ export function createViewManager(ctx) {
         // (The UI/view layer's Elements equivalent is the native WXML panel +
         // render-guest highlight chain, which targets the active render guest.)
         attachNativeSimulatorDevtoolsHost();
+        return ready;
     }
     function detachSimulator() {
+        settleNativeSimulatorReady?.();
+        settleNativeSimulatorReady = null;
         stopFollowingNativeServiceHost();
         detachNativeCustomApiBridge();
         // Stop Elements forwarding (detaches only the debugger sessions IT attached;
@@ -1029,6 +1054,7 @@ export function createViewManager(ctx) {
         simulatorView = null;
         simulatorViewAdded = false;
         simulatorWebContentsId = null;
+        nativeSimulatorProjectPath = null;
         // Drop the renderer-published rect so a stale "hidden" override doesn't
         // suppress the next view before its renderer republishes.
         simulatorBoundsOverride = null;
@@ -1239,6 +1265,7 @@ export function createViewManager(ctx) {
             const wc = webContents.fromId(simulatorWebContentsId);
             return wc && !wc.isDestroyed() ? wc : null;
         },
+        getSimulatorProjectPath: () => nativeSimulatorProjectPath,
         getSettingsWebContents: () => {
             if (!settingsView)
                 return null;

package/dist/main/services/workspace/workspace-service.js

@@ -215,11 +215,22 @@ export function createWorkspaceService(ctx) {
         getLastClosedProjectPath: () => lastClosedProjectPath,
         hasActiveSession: () => currentSession !== null,
         async captureThumbnail(projectPath) {
+            if (!currentSession || projectPath !== currentProjectPath)
+                return null;
             const wc = ctx.views.getSimulatorWebContents();
             if (!wc)
                 return null;
+            if (ctx.views.getSimulatorProjectPath() !== projectPath)
+                return null;
+            const session = currentSession;
             try {
                 const image = await wc.capturePage();
+                if (currentSession !== session
+                    || currentProjectPath !== projectPath
+                    || ctx.views.getSimulatorWebContents() !== wc
+                    || ctx.views.getSimulatorProjectPath() !== projectPath) {
+                    return null;
+                }
                 const dataUrl = `data:image/png;base64,${image.toPNG().toString('base64')}`;
                 if (provider.saveThumbnail) {
                     await provider.saveThumbnail(projectPath, dataUrl);

package/dist/main/windows/service-host-window/create.d.ts

@@ -14,6 +14,7 @@ export interface ServiceHostWindowOptions {
     appId: string;
     pagePath: string;
     pkgRoot: string;
+    root?: string;
     resourceBaseUrl: string;
     hostEnvSnapshot?: Record<string, unknown>;
 }

package/dist/main/windows/service-host-window/create.js

@@ -52,6 +52,7 @@ export function buildServiceHostSpawnUrl(opts) {
     url.searchParams.set('appId', opts.appId);
     url.searchParams.set('pagePath', opts.pagePath);
     url.searchParams.set('pkgRoot', opts.pkgRoot);
+    url.searchParams.set('root', opts.root || 'main');
     url.searchParams.set('resourceBaseUrl', opts.resourceBaseUrl);
     if (opts.hostEnvSnapshot) {
         // Encode the resolved host-env so preload can hydrate

package/dist/preload/instrumentation/wxml-extract.js

@@ -4,16 +4,24 @@ const INTERNAL_CLASSES = new Set([
     '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;
-    if (!parent)
-        return null;
-    const parentType = parent.type;
+    const parentType = parent?.type;
     const components = parentType?.components;
     if (components) {
         for (const [regName, comp] of Object.entries(components)) {
             if (comp === instance.type)
-                return regName.startsWith('dd-') ? regName.slice(3) : regName;
+                return normalizeRegisteredName(regName);
         }
     }
     const appComponents = instance.appContext?.components;
@@ -21,7 +29,7 @@ function resolveTemplateNameFromParent(instance) {
         return null;
     for (const [regName, comp] of Object.entries(appComponents)) {
         if (comp === instance.type)
-            return regName.startsWith('dd-') ? regName.slice(3) : regName;
+            return normalizeRegisteredName(regName);
     }
     return null;
 }
@@ -53,6 +61,29 @@ function resolvePagePath(instance) {
         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)
@@ -63,12 +94,22 @@ function resolveTagName(instance) {
     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) {
-        if (type.__scopeId && type.components)
-            return 'page';
+        // 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';
@@ -132,6 +173,11 @@ function getElementSid(instance) {
 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;

package/dist/preload/runtime/host-toolbar-port.d.ts

@@ -19,7 +19,7 @@
  * envelope stays the single waist (same posture as the main side's
  * host-toolbar-port-channel.ts).
  *
- * Ordering reality this module absorbs (spike .repro/wave3-spike):
+ * Ordering reality this module absorbs:
  *  - The page script runs BEFORE the handshake can complete (the port is
  *    posted on did-finish-load). Page `send()`s issued before the port
  *    arrives go into a PENDING QUEUE and flush in order on handshake —

package/dist/preload/runtime/host-toolbar-port.js

@@ -19,7 +19,7 @@
  * envelope stays the single waist (same posture as the main side's
  * host-toolbar-port-channel.ts).
  *
- * Ordering reality this module absorbs (spike .repro/wave3-spike):
+ * Ordering reality this module absorbs:
  *  - The page script runs BEFORE the handshake can complete (the port is
  *    posted on did-finish-load). Page `send()`s issued before the port
  *    arrives go into a PENDING QUEUE and flush in order on handshake —

package/dist/preload/runtime/host-toolbar-runtime.d.ts

@@ -10,15 +10,16 @@
  *  - the toolbar WCV's creation injects `HOST_TOOLBAR_RUNTIME_MARKER` into its
  *    process argv via `webPreferences.additionalArguments`;
  *  - the marker is PROCESS-level (subframes of the toolbar window carry it
- *    too — spike .repro/wave3-spike/RESULTS.md item 3), so the guard needs
- *    BOTH wings: `isMainFrame` AND `argv.includes(marker)`;
+ *    too), so the guard needs BOTH wings: `isMainFrame` AND
+ *    `argv.includes(marker)`;
  *  - a renderer that fails the guard returns immediately with ZERO footprint
- *    (no advertiser, no listeners, no globals — spike item 4).
+ *    (no advertiser, no listeners, no globals).
  *
- * Why session-resident at all: the advertiser used to ride the toolbar WCV's
- * `webPreferences.preload`, so a host calling `setPreloadPath(<its own
- * preload>)` REPLACED it and the strip height collapsed to 0. With the runtime
- * on the session layer, the host preload and the framework runtime coexist.
+ * Why session-resident at all: riding the toolbar WCV's
+ * `webPreferences.preload` lets a host calling `setPreloadPath(<its own
+ * preload>)` REPLACE the advertiser, collapsing the strip height to 0. With the
+ * runtime on the session layer, the host preload and the framework runtime
+ * coexist.
  */
 /**
  * Pure guard predicate: should the toolbar runtime activate in a renderer with

package/dist/preload/runtime/host-toolbar-runtime.js

@@ -10,15 +10,16 @@
  *  - the toolbar WCV's creation injects `HOST_TOOLBAR_RUNTIME_MARKER` into its
  *    process argv via `webPreferences.additionalArguments`;
  *  - the marker is PROCESS-level (subframes of the toolbar window carry it
- *    too — spike .repro/wave3-spike/RESULTS.md item 3), so the guard needs
- *    BOTH wings: `isMainFrame` AND `argv.includes(marker)`;
+ *    too), so the guard needs BOTH wings: `isMainFrame` AND
+ *    `argv.includes(marker)`;
  *  - a renderer that fails the guard returns immediately with ZERO footprint
- *    (no advertiser, no listeners, no globals — spike item 4).
+ *    (no advertiser, no listeners, no globals).
  *
- * Why session-resident at all: the advertiser used to ride the toolbar WCV's
- * `webPreferences.preload`, so a host calling `setPreloadPath(<its own
- * preload>)` REPLACED it and the strip height collapsed to 0. With the runtime
- * on the session layer, the host preload and the framework runtime coexist.
+ * Why session-resident at all: riding the toolbar WCV's
+ * `webPreferences.preload` lets a host calling `setPreloadPath(<its own
+ * preload>)` REPLACE the advertiser, collapsing the strip height to 0. With the
+ * runtime on the session layer, the host preload and the framework runtime
+ * coexist.
  */
 import { HOST_TOOLBAR_RUNTIME_MARKER } from '../../shared/constants.js';
 import { installHostToolbarAdvertiserWhenReady } from './host-toolbar-advertiser.js';