@dimina-kit/devtools 0.4.0-dev.20260616102751 → 0.4.0-dev.20260624040247

package/dist/main/services/service-console/console-api.js

@@ -0,0 +1,103 @@
+/**
+ * Pure helpers for the native-host service-console forwarder.
+ *
+ * The service-host's console is captured via CDP `Runtime.consoleAPICalled`,
+ * which preserves native source attribution. A `console.*` monkeypatch in
+ * `service-host/preload.cjs` would add a stack frame, so Chrome DevTools (attached
+ * natively to the service host) would attribute EVERY service-layer log to the
+ * wrapper line instead of the developer's source.
+ *
+ * These functions turn the CDP event shape into the `GuestConsoleEntry` shape
+ * the existing console fan-out (automation `App.logAdded`) expects, WITHOUT any
+ * electron / IO dependency so they are unit-testable in isolation. The async
+ * deep-fetch (`Runtime.callFunctionOn`) for object args lives in `index.ts`.
+ */
+/**
+ * sourceURL stamped on the render→service `[视图]` re-injection script
+ * (`console-forward.buildForwardScript`). The CDP capture skips any
+ * `consoleAPICalled` whose top frame carries this URL so a forwarded render line
+ * is not re-captured and re-broadcast as a service entry (duplicate / loop).
+ */
+export const RENDER_FORWARD_SOURCE_URL = 'dimina://render-console-forward';
+const KNOWN_LEVELS = new Set(['log', 'warn', 'error', 'info', 'debug']);
+/**
+ * CDP `consoleAPICalled.type` → our console level. CDP emits `'warning'` where
+ * we use `'warn'`; every other known level passes through; anything else (e.g.
+ * `'dir'`, `'table'`, `'trace'`, `undefined`) maps to `'log'`.
+ */
+export function mapConsoleApiType(type) {
+    if (type === 'warning')
+        return 'warn';
+    if (type && KNOWN_LEVELS.has(type))
+        return type;
+    return 'log';
+}
+const BIGINT_LITERAL = /^-?\d+n$/;
+/**
+ * A single RemoteObject → a JSON-serializable value WITHOUT a CDP round-trip
+ * (shallow). Objects that need their full contents are flagged by
+ * {@link needsDeepFetch} and deep-serialized by the caller; this is the
+ * inline/best-effort fallback.
+ */
+export function remoteObjectToValue(ro) {
+    if (!ro)
+        return ro;
+    // 1. An inlined value (CDP includes `value` for JSON-serializable primitives
+    //    and small arrays). Use `in` so falsy values (0, '', false) and an
+    //    explicit `null` are honoured rather than falling through.
+    if ('value' in ro)
+        return ro.value;
+    // 2. Specials that can't ride in `value`.
+    if (typeof ro.unserializableValue === 'string') {
+        const u = ro.unserializableValue;
+        if (u === 'Infinity')
+            return Infinity;
+        if (u === '-Infinity')
+            return -Infinity;
+        if (u === 'NaN')
+            return NaN;
+        if (u === '-0')
+            return -0;
+        if (BIGINT_LITERAL.test(u))
+            return u;
+        return u;
+    }
+    // 3. Fall back by type.
+    switch (ro.type) {
+        case 'undefined':
+            return undefined;
+        case 'function':
+            return ro.description ?? '[Function]';
+        case 'symbol':
+            return ro.description ?? '[Symbol]';
+        case 'object':
+            if (ro.subtype === 'null')
+                return null;
+            return ro.description ?? '[Object]';
+        default:
+            return ro.description ?? '[Unknown]';
+    }
+}
+/**
+ * Whether this RemoteObject must be deep-fetched via `Runtime.callFunctionOn`
+ * (returnByValue) to be fully serialized — i.e. a real object/array referenced
+ * by `objectId` with no inline `value`. Functions, primitives, `null`, and
+ * already-inlined values do not.
+ */
+export function needsDeepFetch(ro) {
+    if (!ro)
+        return false;
+    if ('value' in ro)
+        return false;
+    return ro.type === 'object' && ro.subtype !== 'null' && typeof ro.objectId === 'string';
+}
+/**
+ * True when a `consoleAPICalled` event is the render→service `[视图]`
+ * re-injection (its top call frame URL === the sentinel) and must NOT be
+ * re-forwarded — the original render entry already reached every consumer.
+ */
+export function isRenderForwardEvent(params, sentinelUrl) {
+    const top = params?.stackTrace?.callFrames?.[0]?.url;
+    return typeof top === 'string' && top === sentinelUrl;
+}
+//# sourceMappingURL=console-api.js.map

package/dist/main/services/service-console/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Native-host SERVICE-layer console capture via CDP.
+ *
+ * The embedded Chrome DevTools front-end is attached natively to the service
+ * host, so the service layer's `console.*` already displays there with correct
+ * source attribution + sourcemaps — UNLESS something rewrites `console.*`. The
+ * old `service-host/preload.cjs` monkeypatch did exactly that (wrapping each
+ * level to also post the entry to main), which made DevTools attribute every
+ * service log to the wrapper line (`preload.cjs:237`) instead of the developer's
+ * source. That monkeypatch is removed; this service replaces its ONE remaining
+ * job — feeding service-layer entries to the console fan-out (automation
+ * `App.logAdded`) — by capturing `Runtime.consoleAPICalled` over an in-process
+ * CDP session instead. Capturing at the CDP layer adds no stack frame, so native
+ * attribution in the DevTools console is preserved (verified: an in-process
+ * `debugger.attach('1.3')` coexists with the custom-host DevTools front-end on
+ * the same wc — Electron multi-client CDP).
+ *
+ * Lifecycle: installed when the right-panel DevTools is pointed at a service host
+ * wc (`view-manager.pointNativeDevtoolsAtServiceWc`) and stopped when that source
+ * is closed / swapped (pre-warm pool recycles the service window). `stop()` is
+ * idempotent.
+ */
+import type { WebContents } from 'electron';
+import type { ConnectionRegistry } from '@dimina-kit/electron-deck/main';
+import type { GuestConsoleEntry } from '../console-forward/index.js';
+export interface ServiceConsoleForwardDeps {
+    /** The service host wc whose `console.*` we capture (top-level BrowserWindow wc). */
+    serviceWc: WebContents;
+    /** Sink for each captured service entry (wired to `consoleForwarder.emit`). */
+    emit: (entry: GuestConsoleEntry) => void;
+    /** Connection registry — binds teardown to the service wc's destroy ('closed'). */
+    connections?: ConnectionRegistry;
+}
+export interface ServiceConsoleForwardHandle {
+    /** Detach the CDP session (if we attached it) and stop capturing. Idempotent. */
+    stop(): void;
+}
+/**
+ * Attach an in-process CDP session to `serviceWc`, enable Runtime, and forward
+ * every `Runtime.consoleAPICalled` to `emit` as a `source:'service'` entry —
+ * EXCEPT the render→service `[视图]` re-injection (skipped via sentinel so it is
+ * not double-broadcast). Object args are deep-serialized via
+ * `Runtime.callFunctionOn` on our OWN session (the objectId can't be released by
+ * the front-end), falling back to the shallow inline value on failure.
+ */
+export declare function installServiceConsoleForward(deps: ServiceConsoleForwardDeps): ServiceConsoleForwardHandle;
+//# sourceMappingURL=index.d.ts.map

package/dist/main/services/service-console/index.js

@@ -0,0 +1,139 @@
+import { RENDER_FORWARD_SOURCE_URL, mapConsoleApiType, needsDeepFetch, remoteObjectToValue, isRenderForwardEvent, } from './console-api.js';
+/**
+ * Attach an in-process CDP session to `serviceWc`, enable Runtime, and forward
+ * every `Runtime.consoleAPICalled` to `emit` as a `source:'service'` entry —
+ * EXCEPT the render→service `[视图]` re-injection (skipped via sentinel so it is
+ * not double-broadcast). Object args are deep-serialized via
+ * `Runtime.callFunctionOn` on our OWN session (the objectId can't be released by
+ * the front-end), falling back to the shallow inline value on failure.
+ */
+export function installServiceConsoleForward(deps) {
+    const { serviceWc, emit, connections } = deps;
+    let disposed = false;
+    // Did WE attach the session (vs. it already being attached by someone else)?
+    // Only detach what we own.
+    let selfAttached = false;
+    // Process events in arrival order even though arg resolution is async, so the
+    // forwarded sequence matches the order the developer logged.
+    let tail = Promise.resolve();
+    let closedSub;
+    function usableDebugger() {
+        try {
+            if (serviceWc.isDestroyed())
+                return false;
+            if (serviceWc.debugger.isAttached())
+                return true;
+        }
+        catch {
+            return false;
+        }
+        try {
+            serviceWc.debugger.attach('1.3');
+            selfAttached = true;
+            return true;
+        }
+        catch {
+            // Race: someone attached between the check and here → still usable.
+            try {
+                return serviceWc.debugger.isAttached();
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    /** Deep-serialize one arg; best-effort, never throws. */
+    async function resolveArg(ro) {
+        if (!needsDeepFetch(ro))
+            return remoteObjectToValue(ro);
+        try {
+            const res = (await serviceWc.debugger.sendCommand('Runtime.callFunctionOn', {
+                objectId: ro.objectId,
+                functionDeclaration: 'function () { return this }',
+                returnByValue: true,
+            }));
+            if (res && res.result && 'value' in res.result)
+                return res.result.value;
+        }
+        catch {
+            // Object released / host navigating — fall back to the shallow value.
+        }
+        return remoteObjectToValue(ro);
+    }
+    async function handleConsoleApi(params) {
+        if (disposed)
+            return;
+        // Skip the render→service `[视图]` re-injection — the original render entry
+        // already reached every consumer; re-forwarding would duplicate it.
+        if (isRenderForwardEvent(params, RENDER_FORWARD_SOURCE_URL))
+            return;
+        const level = mapConsoleApiType(params.type);
+        const rawArgs = Array.isArray(params.args) ? params.args : [];
+        let args;
+        try {
+            args = await Promise.all(rawArgs.map((a) => resolveArg(a)));
+        }
+        catch {
+            args = rawArgs.map((a) => remoteObjectToValue(a));
+        }
+        if (disposed)
+            return;
+        emit({ source: 'service', level, args, ts: Date.now() });
+    }
+    const onMessage = (_event, method, params) => {
+        if (disposed)
+            return;
+        if (method !== 'Runtime.consoleAPICalled')
+            return;
+        const p = params;
+        tail = tail.then(() => handleConsoleApi(p)).catch(() => { });
+    };
+    function stop() {
+        if (disposed)
+            return;
+        disposed = true;
+        try {
+            closedSub?.dispose();
+        }
+        catch { /* gone */ }
+        try {
+            serviceWc.debugger.removeListener('message', onMessage);
+        }
+        catch { /* gone */ }
+        if (selfAttached) {
+            try {
+                if (!serviceWc.isDestroyed() && serviceWc.debugger.isAttached())
+                    serviceWc.debugger.detach();
+            }
+            catch { /* already detached / destroyed */ }
+            selfAttached = false;
+        }
+    }
+    if (!usableDebugger()) {
+        disposed = true;
+        return { stop() { } };
+    }
+    try {
+        serviceWc.debugger.on('message', onMessage);
+    }
+    catch {
+        stop();
+        return { stop() { } };
+    }
+    // Enable Runtime so consoleAPICalled flows. Best-effort — a mid-destroy host
+    // rejects, in which case there's simply nothing to capture.
+    serviceWc.debugger.sendCommand('Runtime.enable').catch(() => { });
+    // Bind teardown to the service wc's real destroy. The service window is
+    // pool-recycled, but 'closed' fires only on hard destroy — the right lifetime
+    // for a session we attached to THIS wc. `on('closed')` returns a handle whose
+    // dispose() removes the listener WITHOUT firing it.
+    try {
+        if (connections)
+            closedSub = connections.acquire(serviceWc).on('closed', stop);
+        else
+            serviceWc.once('destroyed', stop);
+    }
+    catch { /* fake/minimal wc in tests */ }
+    return { stop };
+}
+//# sourceMappingURL=index.js.map

package/dist/main/services/service-host-pool/pool.d.ts

@@ -7,9 +7,8 @@ import { BrowserWindow } from 'electron';
  * (release / releaseDestroyed), opt-in behind `DIMINA_PREWARM_POOL_SIZE`
  * (default OFF). Only the SERVICE-HOST window is pooled; the simulator content
  * WebContentsView (`view-manager.attachNativeSimulator`) is created fresh per
- * attach. (The historical `<webview>`-tag default arch was never poolable —
- * Electron can't reparent a pre-warmed WebContents into a `<webview>`; doc §5
- * Phase 4 — and that route has since been deleted outright.)
+ * attach. (A `<webview>`-tag arch is not poolable — Electron can't reparent a
+ * pre-warmed WebContents into a `<webview>`.)
  *
  * Lifecycle of a pool entry:
  *   warming   — BrowserWindow constructed, page loading

package/dist/main/services/simulator-storage/index.d.ts

@@ -2,11 +2,9 @@
  * SimulatorStorageWatcher
  *
  * Attaches the Chrome DevTools Protocol debugger to the simulator <webview>
- * and forwards `DOMStorage.*` events to the renderer host. Replaces the
- * preload-side localStorage.setItem hook that used to push storage changes
- * via SimulatorChannel.Storage / StorageAll.
+ * and forwards `DOMStorage.*` events to the renderer host.
  *
- * Trade-offs vs the preload approach:
+ * Trade-offs vs a preload-side localStorage.setItem hook:
  *   + Uses standard browser protocol; no preload injection
  *   + Captures every change including ones bypassing wx (api-compat fallback,
  *     direct localStorage.setItem from devtools, etc.)

package/dist/main/services/simulator-storage/index.js

@@ -2,11 +2,9 @@
  * SimulatorStorageWatcher
  *
  * Attaches the Chrome DevTools Protocol debugger to the simulator <webview>
- * and forwards `DOMStorage.*` events to the renderer host. Replaces the
- * preload-side localStorage.setItem hook that used to push storage changes
- * via SimulatorChannel.Storage / StorageAll.
+ * and forwards `DOMStorage.*` events to the renderer host.
  *
- * Trade-offs vs the preload approach:
+ * Trade-offs vs a preload-side localStorage.setItem hook:
  *   + Uses standard browser protocol; no preload injection
  *   + Captures every change including ones bypassing wx (api-compat fallback,
  *     direct localStorage.setItem from devtools, etc.)

package/dist/main/services/simulator-temp-files/index.js

@@ -155,8 +155,8 @@ export function setupSimulatorTempFiles(simSession) {
     installOnSession(simSession);
     // Apply to every per-project miniapp partition session (current + future).
     const unregisterConfigurator = registerMiniappSessionConfigurator((sess) => installOnSession(sess));
-    // Phase 1 (P1-7): renderer FSM → main fs operations bridge. The same
-    // simulator-only sender policy applies — registry instance is shared.
+    // Renderer FSM → main fs operations bridge. The same simulator-only sender
+    // policy applies — registry instance is shared.
     registry.handle('simulator:fs:read', (_event, payload) => handleFsRead(payload));
     registry.handle('simulator:fs:write', (_event, payload) => handleFsWrite(payload));
     registry.handle('simulator:fs:stat', (_event, payload) => handleFsStat(payload));

package/dist/main/services/update/update-manager.d.ts

@@ -26,7 +26,7 @@ export declare class UpdateManager {
     private downloadedPath;
     /**
      * Whether this instance has already emitted `Available` once. The periodic
-     * check fires forever (interval default 1h), and downstream UI (qdmp shell
+     * check fires forever (interval default 1h), and downstream UI (a downstream host shell
      * renders a native toast / Notification) is not idempotent — every event
      * stacks. We dedupe at the source: at most one Available per instance
      * lifetime, regardless of how the upstream `info.version` shifts. The user

package/dist/main/services/update/update-manager.js

@@ -9,7 +9,7 @@ export class UpdateManager {
     downloadedPath = null;
     /**
      * Whether this instance has already emitted `Available` once. The periodic
-     * check fires forever (interval default 1h), and downstream UI (qdmp shell
+     * check fires forever (interval default 1h), and downstream UI (a downstream host shell
      * renders a native toast / Notification) is not idempotent — every event
      * stacks. We dedupe at the source: at most one Available per instance
      * lifetime, regardless of how the upstream `info.version` shifts. The user

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
@@ -34,6 +37,13 @@ export interface ViewManagerContext {
      * console line is the fallback). Optional so partial test contexts compile.
      */
     networkForward?: WorkbenchContext['networkForward'];
+    /**
+     * Always-on console fan-out (set by `installBridgeRouter`). The service-console
+     * capture feeds service-layer `consoleAPICalled` entries here so they reach
+     * automation; mirrors how render entries arrive via the bridge. Optional so
+     * partial test contexts compile.
+     */
+    consoleForwarder?: WorkbenchContext['consoleForwarder'];
     /**
      * Per-context registry of host-registered simulator custom APIs. The
      * native-host simulator is a top-level WebContentsView with no embedder
@@ -75,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 —
@@ -99,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. */
@@ -270,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.