@dimina-kit/devtools 0.3.2-dev.20260525152421 → 0.3.2-dev.20260610082053

package/dist/main/services/notifications/renderer-notifier.d.ts

@@ -1,5 +1,6 @@
 import type { BrowserWindow, WebContents, WebContentsView } from 'electron';
 import type { CompileConfig } from '../../../shared/types.js';
+import { type EditorOpenFilePayload } from '../../../shared/ipc-channels.js';
 import type { WorkbenchSettings } from '../settings/index.js';
 import type { ProjectSettings } from '../projects/project-repository.js';
 /**
@@ -54,6 +55,16 @@ export interface RendererNotifier {
     popoverRelaunch(config: CompileConfig): void;
     /** Tell the main renderer the toolbar actions list has changed. */
     toolbarActionsChanged(): void;
+    /**
+     * Push the reserved host-toolbar height to the main renderer so its toolbar
+     * placeholder div resizes (closes the host-toolbar dynamic-height loop).
+     */
+    hostToolbarHeightChanged(height: number): void;
+    /**
+     * Ask the main renderer's Monaco editor to open a project file at a position.
+     * Drives the "click a console file link → open in editor" pipeline.
+     */
+    editorOpenFile(payload: EditorOpenFilePayload): void;
     /** Initialise the currently shown compile popover overlay. */
     popoverInit(popoverView: WebContentsView, payload: unknown): void;
     /** Initialise the currently shown settings overlay (no-op if hidden). */

package/dist/main/services/notifications/renderer-notifier.js

@@ -1,4 +1,4 @@
-import { ProjectChannel, WindowChannel, SettingsChannel, PopoverChannel, ToolbarChannel, WorkbenchSettingsChannel, } from '../../../shared/ipc-channels.js';
+import { ProjectChannel, WindowChannel, SettingsChannel, PopoverChannel, ToolbarChannel, WorkbenchSettingsChannel, EditorChannel, ViewChannel, } from '../../../shared/ipc-channels.js';
 /** Safely resolve a WebContents, skipping destroyed / missing targets. */
 function liveWebContents(wc) {
     if (!wc)
@@ -42,6 +42,12 @@ export function createRendererNotifier(ctx) {
         toolbarActionsChanged() {
             sendToMain(ToolbarChannel.ActionsChanged);
         },
+        hostToolbarHeightChanged(height) {
+            sendToMain(ViewChannel.HostToolbarHeightChanged, height);
+        },
+        editorOpenFile(payload) {
+            sendToMain(EditorChannel.OpenFile, payload);
+        },
         popoverInit(popoverView, payload) {
             const wc = liveWebContents(popoverView.webContents);
             if (!wc)

package/dist/main/services/render-inspect/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * RenderInspector — native-host element/WXML access into a render-host
+ * <webview> guest.
+ *
+ * Injects the bundled `render-inspect` IIFE (dist/render-host/render-inspect.js,
+ * exposing `window.__diminaRenderInspect`) into the guest's MAIN world via
+ * `executeJavaScript`, then drives it to read the WXML tree and
+ * highlight/unhighlight elements by sid. Injection is idempotent per
+ * WebContents id (the guest IIFE also self-guards); the injected-set entry is
+ * cleared when the wc is destroyed so a recycled id re-injects.
+ *
+ * The page's Vue tree + geometry live in the guest main world, and
+ * executeJavaScript (no worldId) runs there too — so the inspector, the DOM it
+ * reads, and the sid registry all share one realm. See render-inspect.ts.
+ */
+import type { WebContents } from 'electron';
+import type { ConnectionRegistry } from '@dimina-kit/electron-deck/main';
+import type { ElementInspection } from '../../../shared/ipc-channels.js';
+import type { WxmlNode } from '../../../preload/shared/sid-registry.js';
+export interface RenderInspector {
+    /** Inject (once per wc) the inspector IIFE, then read the WXML tree. */
+    getWxml(wc: WebContents): Promise<WxmlNode | null>;
+    /** Inject (once per wc), then highlight the element with `sid`. */
+    highlight(wc: WebContents, sid: string): Promise<ElementInspection | null>;
+    /** Clear any highlight overlay in the guest. */
+    unhighlight(wc: WebContents): Promise<void>;
+}
+export interface RenderInspectorOptions {
+    /** Override the injected IIFE source (default: read the built bundle). Test seam. */
+    loadSource?: () => string;
+    /**
+     * Connection registry (foundation.md §4 / P2). When provided, the per-wc
+     * `injected` bookkeeping is torn down via the wc's connection (deterministic
+     * with the rest of that webContents's resources) instead of a bespoke
+     * `once('destroyed')`. Optional so focused unit tests can omit it (they fall
+     * back to the direct `once('destroyed')`).
+     */
+    connections?: ConnectionRegistry;
+}
+export declare function createRenderInspector(options?: RenderInspectorOptions): RenderInspector;
+//# sourceMappingURL=index.d.ts.map

package/dist/main/services/render-inspect/index.js

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { devtoolsPackageRoot } from '../../utils/paths.js';
+const DEFAULT_SOURCE_PATH = 'dist/render-host/render-inspect.js';
+export function createRenderInspector(options = {}) {
+    const loadSource = options.loadSource ??
+        (() => readFileSync(path.join(devtoolsPackageRoot, DEFAULT_SOURCE_PATH), 'utf8'));
+    let cachedSource = null;
+    const injected = new Set();
+    function source() {
+        if (cachedSource === null)
+            cachedSource = loadSource();
+        return cachedSource;
+    }
+    /** Inject the IIFE once per live wc. Returns false if the guest is unusable. */
+    async function ensureInjected(wc) {
+        if (wc.isDestroyed())
+            return false;
+        if (injected.has(wc.id))
+            return true;
+        let src;
+        try {
+            src = source();
+        }
+        catch (e) {
+            console.warn('[render-inspect] failed to load inspector source:', e.message);
+            return false;
+        }
+        try {
+            await wc.executeJavaScript(src);
+        }
+        catch (e) {
+            console.warn('[render-inspect] inject failed:', e.message);
+            return false;
+        }
+        injected.add(wc.id);
+        // Consolidate the per-wc bookkeeping teardown onto the connection layer
+        // (foundation.md §4 / P2) when a registry is available; fall back to the
+        // bespoke `once('destroyed')` only when omitted (focused unit tests).
+        if (options.connections) {
+            options.connections.acquire(wc).own(() => injected.delete(wc.id));
+        }
+        else {
+            wc.once('destroyed', () => injected.delete(wc.id));
+        }
+        return true;
+    }
+    async function getWxml(wc) {
+        if (wc.isDestroyed())
+            return null;
+        if (!(await ensureInjected(wc)))
+            return null;
+        try {
+            const result = await wc.executeJavaScript('window.__diminaRenderInspect ? window.__diminaRenderInspect.getWxml() : null');
+            return result ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function highlight(wc, sid) {
+        if (wc.isDestroyed())
+            return null;
+        if (!(await ensureInjected(wc)))
+            return null;
+        try {
+            const result = await wc.executeJavaScript(`window.__diminaRenderInspect ? window.__diminaRenderInspect.highlightElement(${JSON.stringify(sid)}) : null`);
+            return result ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function unhighlight(wc) {
+        if (wc.isDestroyed())
+            return;
+        if (!(await ensureInjected(wc)))
+            return;
+        try {
+            await wc.executeJavaScript('window.__diminaRenderInspect && window.__diminaRenderInspect.unhighlightElement && window.__diminaRenderInspect.unhighlightElement()');
+        }
+        catch {
+            // best-effort
+        }
+    }
+    return { getWxml, highlight, unhighlight };
+}
+//# sourceMappingURL=index.js.map

package/dist/main/services/safe-area/index.d.ts

@@ -0,0 +1,17 @@
+import type { WebContents } from 'electron';
+import type { ConnectionRegistry } from '@dimina-kit/electron-deck/main';
+import type { NativeDeviceInfo } from '../../../shared/ipc-channels.js';
+export interface SafeAreaController {
+    /** Attach the debugger to a freshly-attached render-host guest and push the
+     *  current device's insets. No-op (warn) if the guest is already claimed by an
+     *  external CDP client — env then stays 0 rather than throwing. */
+    applyToGuest(guestWc: WebContents, device: NativeDeviceInfo | null): void;
+    /** Re-push insets to every still-attached guest after a device change. */
+    reapplyAll(device: NativeDeviceInfo | null): void;
+    /** Detach from all guests (teardown). */
+    dispose(): void;
+}
+export declare function createSafeAreaController(options?: {
+    connections?: ConnectionRegistry;
+}): SafeAreaController;
+//# sourceMappingURL=index.d.ts.map

package/dist/main/services/safe-area/index.js

@@ -0,0 +1,59 @@
+function guestInsets(device) {
+    const top = device?.safeAreaInsets.top ?? 0;
+    return { top, topMax: top, right: 0, rightMax: 0, bottom: 0, bottomMax: 0, left: 0, leftMax: 0 };
+}
+export function createSafeAreaController(options = {}) {
+    // Guests we successfully attached `wc.debugger` to (so we don't re-attach,
+    // which throws). Pruned on guest destroy.
+    const attached = new Set();
+    function override(wc, device) {
+        if (wc.isDestroyed())
+            return;
+        void wc.debugger
+            .sendCommand('Emulation.setSafeAreaInsetsOverride', { insets: guestInsets(device) })
+            .catch((err) => {
+            console.warn('[safe-area] setSafeAreaInsetsOverride failed:', err instanceof Error ? err.message : err);
+        });
+    }
+    return {
+        applyToGuest: (wc, device) => {
+            if (!wc || wc.isDestroyed() || attached.has(wc)) {
+                if (wc && !wc.isDestroyed() && attached.has(wc))
+                    override(wc, device);
+                return;
+            }
+            try {
+                wc.debugger.attach('1.3');
+            }
+            catch (err) {
+                // Already attached by an external --remote-debugging-port client (or
+                // DevTools). Degrade: leave env at 0 rather than fail the page.
+                console.warn('[safe-area] debugger.attach failed; env(safe-area-inset-*) stays 0:', err instanceof Error ? err.message : err);
+                return;
+            }
+            attached.add(wc);
+            if (options.connections) {
+                options.connections.acquire(wc).own(() => attached.delete(wc));
+            }
+            else {
+                wc.once('destroyed', () => attached.delete(wc));
+            }
+            override(wc, device);
+        },
+        reapplyAll: (device) => {
+            for (const wc of attached)
+                override(wc, device);
+        },
+        dispose: () => {
+            for (const wc of attached) {
+                try {
+                    if (!wc.isDestroyed())
+                        wc.debugger.detach();
+                }
+                catch { /* already detached / destroyed */ }
+            }
+            attached.clear();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,197 @@
+import { BrowserWindow } from 'electron';
+/**
+ * ServiceHostPool — main-process pre-warm pool for simulator host windows.
+ *
+ * Design source: `packages/devtools/docs/prewarm-webview.md`. WIRED into
+ * native-host via `bridge-router.handleSpawn` (acquire) + `disposeAppSession`
+ * (release / releaseDestroyed), opt-in behind `DIMINA_PREWARM_POOL_SIZE`
+ * (default OFF). Default-arch (`view-manager.attachSimulator`) is NOT pooled —
+ * its simulator is a `<webview>` tag, which Electron can't reparent a pre-warmed
+ * WebContents into (doc §5 Phase 4, blocked by that hard limit, not by missing
+ * work here).
+ *
+ * Lifecycle of a pool entry:
+ *   warming   — BrowserWindow constructed, page loading
+ *   ready     — load settled; can be handed to a caller immediately
+ *   in-use    — acquired by a caller (caller owns the window until release)
+ *   resetting — released; navigated back to a blank page, then storage cleared
+ *   disposing — being torn down; removed from the pool
+ *
+ * ── Phase-3 blockers, both RESOLVED in the wiring (kept here for context) ──
+ * 1. Shared-session storage wipe — the service host shares the
+ *    `persist:simulator` partition with live projects, so clearing it on reset
+ *    would wipe other projects. Resolved by `ServiceHostSpec.clearStorageOnReset`:
+ *    `serviceHostSpec()` sets it `false`, so reset only navigates the
+ *    window to blank (resetting the JS realm) and never clears the shared
+ *    session; cross-spawn isolation rides on appId-namespacing + fresh nav,
+ *    matching the already-shared simulator `<webview>` behavior.
+ * 2. Warming vs preload contract — warming loads `about:blank` (no bridgeId).
+ *    `src/service-host/preload.cjs` now idles (early `return`) when `bridgeId`
+ *    is absent instead of throwing, so a warmed window survives until the real
+ *    spawn navigation re-runs the preload with a bridgeId.
+ *
+ * ── Window-death observation ───────────────────────────────────────────────
+ * A pooled/in-use window can die three ways: a render crash
+ * (`render-process-gone`), a graceful close (`'closed'`), or the owner closing
+ * an acquired window (reported via `releaseDestroyed`). All three funnel through
+ * `reclaim()`: a POOLED death frees a spare → refill toward target; an IN-USE
+ * death is the owner's window → drop the bookkeeping WITHOUT destroying it from
+ * under them, and do not refill (the spare count is unaffected).
+ */
+/** Entry state machine (see class doc). */
+export type EntryState = 'warming' | 'ready' | 'in-use' | 'resetting' | 'disposing';
+/**
+ * A spec fully determines whether a warm window can serve a caller. Reuse is
+ * keyed on `preloadPath`: a different preload means a different runtime surface,
+ * so the pool will not hand a mismatched entry to a caller.
+ *
+ * The process-model flags (`contextIsolation` / `sandbox` / `nodeIntegration`)
+ * default to the simulator service-host contract (all `false`, mirroring
+ * `createServiceHostWindow`) so a warmed window is a faithful stand-in for the
+ * window the caller will actually use. They are part of the spec — not
+ * hardcoded — so a caller with a different runtime can override them.
+ */
+export interface ServiceHostSpec {
+    /** Session partition for the window. Opaque to the pool (see KNOWN BLOCKER 1). */
+    partition: string;
+    /** Absolute path to the preload bundle. The reuse key. */
+    preloadPath: string;
+    /** Initial window size (affects first layout). */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** Open DevTools on the window (dev only). */
+    devTools?: boolean;
+    /** webPreferences.contextIsolation. Default false (service-host contract). */
+    contextIsolation?: boolean;
+    /** webPreferences.sandbox. Default false (service-host contract). */
+    sandbox?: boolean;
+    /** webPreferences.nodeIntegration. Default false (service-host contract). */
+    nodeIntegration?: boolean;
+    /**
+     * Whether `release` clears this window's session storage. Default `true`.
+     * Set `false` when the window shares a session with live consumers (e.g. the
+     * service host on the shared `persist:simulator` partition) — clearing there
+     * would wipe other projects' storage. With `false`, reset still navigates the
+     * window to a blank page (tearing down the old JS realm); cross-spawn state is
+     * handled by appId-namespacing + the fresh navigation, matching the
+     * already-shared, never-cleared simulator `<webview>` behavior.
+     */
+    clearStorageOnReset?: boolean;
+}
+/** Snapshot of pool occupancy, for dev panels / IPC `prewarm:status`. */
+export interface ServiceHostPoolStats {
+    total: number;
+    ready: number;
+    inUse: number;
+    warming: number;
+    resetting: number;
+    spec: ServiceHostSpec | null;
+}
+export interface ServiceHostPoolInitOptions {
+    /** Number of entries to keep warm. Default target after init. */
+    defaultPoolSize: number;
+    /** Spec used to warm the initial entries. */
+    defaultSpec: ServiceHostSpec;
+    /** Hard ceiling on pooled entries. Clamped to ≤ 4 (doc §3.3). Default 3. */
+    maxPoolSize?: number;
+}
+export declare class ServiceHostPool {
+    private readonly entries;
+    private currentSpec;
+    private targetSize;
+    private maxPoolSize;
+    private nextId;
+    private disposed;
+    /**
+     * Warm `defaultPoolSize` entries with `defaultSpec`. Normally resolves once the
+     * pool has reached `defaultPoolSize` ready entries — even if a warming window
+     * crashes mid-init and is refilled. NOTE: `warmUpToTarget` caps its refill loop
+     * with a bounded guard, so under SUSTAINED warm crashes `init` resolves
+     * best-effort (possibly under-filled) rather than spinning forever — treat
+     * `getStats().ready` as advisory after init, not a hard invariant.
+     */
+    init(opts: ServiceHostPoolInitOptions): Promise<void>;
+    /**
+     * Hand a ready window matching `spec` to the caller. If none is ready, fall
+     * back to synchronously constructing a fresh window — never blocking on warm
+     * (doc §3.1 "绝不阻塞 acquire"). Fallback windows carry `entryId === null` and
+     * are destroyed (not pooled) on release.
+     *
+     * A spec change (different `preloadPath`) tears down all *pooled* entries and
+     * re-targets the pool to the new spec; in-use entries are left to their owners
+     * and disposed when returned (see `release`).
+     */
+    acquire(spec: ServiceHostSpec): Promise<{
+        win: BrowserWindow;
+        entryId: string | null;
+    }>;
+    /**
+     * Return a window. Fallback windows (`entryId === null`) and entries whose
+     * spec no longer matches the current pool spec are torn down. Otherwise the
+     * window is reset (navigated to blank, then storage cleared) and re-pooled as
+     * `ready`, unless that would exceed `maxPoolSize`.
+     */
+    release(entryId: string | null, win: BrowserWindow): Promise<void>;
+    /**
+     * The owner of an acquired window reports it died externally (graceful close /
+     * crash) — reclaim its in-use slot so it isn't leaked in `entries` forever
+     * (bridge-router calls this on the `serviceAlreadyClosed` teardown path, where
+     * `release` is intentionally skipped). No-op for an unknown id; idempotent;
+     * never touches the (already-gone) window.
+     */
+    releaseDestroyed(entryId: string | null): void;
+    /**
+     * Re-target the pool. `target` is clamped to `[0, maxPoolSize]`. Pooled
+     * entries beyond the target are disposed OLDEST-FIRST (doc §3.3/§3.6); in-use
+     * entries are untouched. Does not warm new entries up (use `init` / refill).
+     */
+    resize(target: number): void;
+    /** Occupancy snapshot. */
+    getStats(): ServiceHostPoolStats;
+    /** Tear down every entry and stop accepting work. */
+    dispose(): Promise<void>;
+    private matches;
+    /** ready + warming + resetting entries are "pooled" (owned by the pool). */
+    private isWarm;
+    private warmCount;
+    private readyCount;
+    /**
+     * Drive the pool to `targetSize` ready entries and resolve only then. Loops so
+     * a crash that drops a warming entry mid-init (which refills asynchronously
+     * via `onGone`) is awaited too, instead of resolving on a stale snapshot. A
+     * generous iteration guard prevents an unbounded spin if windows keep dying.
+     */
+    private warmUpToTarget;
+    private createWindow;
+    private loadBlank;
+    /** Construct + load a fresh pooled entry, registering crash recovery. */
+    private warmOne;
+    /**
+     * Reset a released window back to a clean, blank state. Order matters
+     * (doc §3.5.3 / §3.4「等待时序」): navigate to blank FIRST so the old document
+     * stops running and in-flight requests are aborted, THEN clear storage — so a
+     * still-live old page cannot re-populate storage after the clear.
+     */
+    private reset;
+    /** A spec change tears down pooled entries and re-targets the pool. */
+    private onSpecChange;
+    /**
+     * Reclaim an entry whose window died externally (render crash, graceful close,
+     * or an owner-reported destruction). A POOLED death frees a spare → refill
+     * toward target; an IN-USE death is the caller's window → drop the bookkeeping
+     * WITHOUT destroying it from under them, and do not refill (the spare count is
+     * unaffected). `destroyIfPooled` destroys the husk for a pooled render crash
+     * (the BrowserWindow object can outlive a dead render process); skip it for a
+     * `'closed'`/owner-reported window that is already gone. No-op if the entry was
+     * already disposed by us (disposeEntry deletes before its own destroy fires
+     * `'closed'`, so this finds nothing).
+     */
+    private reclaim;
+    /** A pooled window's render process died — reclaim + refill (destroy the husk). */
+    private onGone;
+    private disposeEntry;
+    private destroyWindow;
+}
+//# sourceMappingURL=pool.d.ts.map