@dimina-kit/devtools 0.4.0-dev.20260701155140 → 0.4.0-dev.20260702145840

package/dist/main/services/views/placement-reconciler.d.ts

@@ -0,0 +1,73 @@
+import type { WebContentsView } from 'electron';
+import * as layout from '../layout/index.js';
+import type { DesiredView, PlacementSnapshot } from '@dimina-kit/electron-deck/layout';
+import type { DevtoolsExtra } from '../../../shared/view-ids.js';
+import type { ViewManagerContext } from './view-manager.js';
+/**
+ * The per-view wiring the reconciler needs to converge the main-process view
+ * tree. Each view domain registers exactly one slot; the reconciler owns no
+ * view references itself, so the domain's own `let viewRef` stays the single
+ * source of truth (the slot exposes accessors into it, never a copy).
+ */
+export interface ViewSlot {
+    /** The live WebContentsView for this slot, or null when not yet created. */
+    getView(): WebContentsView | null;
+    /** Record whether the view is currently added to the contentView. */
+    setAdded?(added: boolean): void;
+    /**
+     * When true, force the desired placement to hidden — the view-creation site
+     * has not produced the WCV yet, so the reconciler must never record an attach
+     * that addChildView can't perform. The creation site calls `reconcileNow()`
+     * to re-open the gate.
+     */
+    gateHidden?(): boolean;
+    /**
+     * Run before the generic attach. Return true when the slot fully handled the
+     * attach itself (e.g. a lazy async load that adds the view on completion), so
+     * the reconciler must NOT addChildView here.
+     */
+    beforeAttach?(): boolean;
+    /** Lazily create the view on attach (host-toolbar); used instead of getView. */
+    ensureView?(): WebContentsView | null;
+    /** Domain-specific setBounds (simulator zoom rides here). */
+    applyBounds?(view: WebContentsView, bounds: layout.Bounds, extra: DevtoolsExtra | undefined): void;
+    /**
+     * Create the lazily-built view BEFORE reconcile when its desired placement is
+     * visible, so the setBounds op — which the core emits before attach — lands
+     * on a live view rather than a not-yet-created one.
+     */
+    ensureLazy?(desired: DesiredView<DevtoolsExtra> | undefined): void;
+}
+/**
+ * Level-triggered placement reconciler (docs/view-placement-reconciler.md). The
+ * renderer publishes a window-level snapshot into `baseDesired`;
+ * settings/popover are main-owned and live in `overlayDesired`. Any change
+ * merges the two, runs the pure reconcile core, and applies the ordered ops
+ * through `viewTarget`. `epochCounter` is a single monotonic tick — main is the
+ * only (serial) reconcile caller, so the core's stale guard passes by
+ * construction; `rendererGeneration` still drives the reset on renderer restart.
+ */
+export interface PlacementReconciler {
+    registerView(viewId: string, slot: ViewSlot): void;
+    reconcileNow(): void;
+    /**
+     * Apply the renderer's window-level placement snapshot — the single source of
+     * truth for every managed native view's bounds/visibility/z-order.
+     */
+    setPlacementSnapshot(snapshot: PlacementSnapshot<DevtoolsExtra>): void;
+    /**
+     * Forget a view's reconciled mount state so the NEXT rebuilt view is treated
+     * as a fresh attach. Required wherever a view instance is replaced/destroyed
+     * via a manual removeChildView that bypasses the reconciler (otherwise the
+     * level-triggered core still records the old instance as attached and never
+     * emits the attach op for the replacement — a sticky invisible view).
+     */
+    forgetActual(viewId: string): void;
+    setBaseDesired(viewId: string, desired: DesiredView<DevtoolsExtra>): void;
+    deleteBaseDesired(viewId: string): void;
+    setOverlayDesired(viewId: string, desired: DesiredView<DevtoolsExtra>): void;
+    deleteOverlayDesired(viewId: string): void;
+    hasOverlayDesired(viewId: string): boolean;
+}
+export declare function createPlacementReconciler(ctx: ViewManagerContext): PlacementReconciler;
+//# sourceMappingURL=placement-reconciler.d.ts.map

package/dist/main/services/views/placement-reconciler.js

@@ -0,0 +1,120 @@
+import { reconcile, createInitialState } from '@dimina-kit/electron-deck/layout';
+import { applyViewOps } from './apply-view-ops.js';
+export function createPlacementReconciler(ctx) {
+    let placementState = createInitialState();
+    let epochCounter = 0;
+    let rendererGeneration = 0;
+    const baseDesired = new Map();
+    const overlayDesired = new Map();
+    const slots = new Map();
+    function gateReadiness(v) {
+        const slot = slots.get(v.viewId);
+        if (slot?.gateHidden?.())
+            return { ...v, placement: { visible: false } };
+        return v;
+    }
+    const viewTarget = {
+        attach(viewId) {
+            if (ctx.windows.mainWindow.isDestroyed())
+                return;
+            const slot = slots.get(viewId);
+            if (!slot)
+                return;
+            if (slot.beforeAttach?.())
+                return;
+            const view = slot.ensureView ? slot.ensureView() : slot.getView();
+            if (!view)
+                return;
+            ctx.windows.mainWindow.contentView.addChildView(view);
+            slot.setAdded?.(true);
+        },
+        detach(viewId) {
+            const slot = slots.get(viewId);
+            const view = slot?.getView() ?? null;
+            if (view && !ctx.windows.mainWindow.isDestroyed()) {
+                try {
+                    ctx.windows.mainWindow.contentView.removeChildView(view);
+                }
+                catch { /* already removed */ }
+            }
+            slot?.setAdded?.(false);
+        },
+        setBounds(viewId, bounds, extra) {
+            const slot = slots.get(viewId);
+            const view = slot?.getView() ?? null;
+            if (!view || view.webContents.isDestroyed())
+                return;
+            if (slot?.applyBounds) {
+                slot.applyBounds(view, bounds, extra);
+                return;
+            }
+            view.setBounds(bounds);
+        },
+        setVisible(viewId, visible) {
+            const view = slots.get(viewId)?.getView() ?? null;
+            if (!view)
+                return;
+            try {
+                view.setVisible(visible);
+            }
+            catch { /* stub may lack setVisible */ }
+        },
+        reorder(order) {
+            // A single attached view is already in place — nothing to reorder.
+            if (order.length <= 1 || ctx.windows.mainWindow.isDestroyed())
+                return;
+            const cv = ctx.windows.mainWindow.contentView;
+            for (const viewId of order) {
+                const view = slots.get(viewId)?.getView() ?? null;
+                if (view) {
+                    try {
+                        cv.addChildView(view);
+                    }
+                    catch { /* already attached */ }
+                }
+            }
+        },
+    };
+    // Create the lazily-built views (host-toolbar, workbench) BEFORE reconcile so
+    // the setBounds op — which the core emits before attach — lands on a live view
+    // rather than a not-yet-created one.
+    function ensureLazyViews() {
+        for (const [viewId, slot] of slots) {
+            slot.ensureLazy?.(baseDesired.get(viewId));
+        }
+    }
+    function reconcileNow() {
+        ensureLazyViews();
+        const views = [];
+        for (const v of baseDesired.values())
+            views.push(gateReadiness(v));
+        for (const v of overlayDesired.values())
+            views.push(v);
+        const result = reconcile(placementState, {
+            generation: rendererGeneration,
+            epoch: ++epochCounter,
+            views,
+        });
+        placementState = result.state;
+        applyViewOps(result.ops, viewTarget);
+    }
+    function setPlacementSnapshot(snapshot) {
+        rendererGeneration = snapshot.generation;
+        baseDesired.clear();
+        for (const v of snapshot.views)
+            baseDesired.set(v.viewId, v);
+        reconcileNow();
+    }
+    return {
+        registerView: (viewId, slot) => { slots.set(viewId, slot); },
+        reconcileNow,
+        setPlacementSnapshot,
+        forgetActual: (viewId) => { placementState.actual.delete(viewId); },
+        setBaseDesired: (viewId, desired) => { baseDesired.set(viewId, desired); },
+        deleteBaseDesired: (viewId) => { baseDesired.delete(viewId); },
+        setOverlayDesired: (viewId, desired) => { overlayDesired.set(viewId, desired); },
+        deleteOverlayDesired: (viewId) => { overlayDesired.delete(viewId); },
+        hasOverlayDesired: (viewId) => overlayDesired.has(viewId),
+    };
+}
+//# sourceMappingURL=placement-reconciler.js.map

package/dist/main/services/views/resolve-project-editor-target.d.ts

@@ -0,0 +1,13 @@
+import { type OpenInEditorRequest } from '../../../shared/open-in-editor.js';
+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;
+//# sourceMappingURL=resolve-project-editor-target.d.ts.map

package/dist/main/services/views/resolve-project-editor-target.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'path';
+import { projectSourceContextFromServiceHostUrl, resourceUrlToProjectRelativePath, } from '../../../shared/open-in-editor.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,
+    };
+}
+//# sourceMappingURL=resolve-project-editor-target.js.map

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

@@ -1,10 +1,10 @@
 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';
+import type { HostToolbarMessageSubscription } from './host-toolbar-port-channel.js';
 import type { PlacementSnapshot } from '@dimina-kit/electron-deck/layout';
-import { type DevtoolsExtra } from '../../../shared/view-ids.js';
+import type { DevtoolsExtra } from '../../../shared/view-ids.js';
+export { resolveProjectEditorTarget, type ProjectEditorTarget, } from './resolve-project-editor-target.js';
 /**
  * Context surface used by the ViewManager. We only need a small slice of the
  * full WorkbenchContext here; typing it this way documents the actual dependency.
@@ -69,6 +69,11 @@ export interface ViewManagerContext {
  * main-process WebContentsView (`attachWorkbench`) hung off the main window's
  * contentView, like the other overlays. The main window's own renderer is the
  * content root and is not managed here.
+ *
+ * This module is the composition root: each view domain lives in its own
+ * factory module (simulator, devtools-host, workbench, host-toolbar, overlay
+ * panels) and shares a single injected placement reconciler; this file wires
+ * them together and exposes their combined method surface.
  */
 export interface ViewManager {
     /**
@@ -89,6 +94,16 @@ export interface ViewManager {
      * geometry is anchor-published.
      */
     attachNativeSimulator(simulatorUrl: string, simWidth: number): Promise<void>;
+    /**
+     * Soft-reload the LIVE native simulator after a watcher rebuild: forward a
+     * SIMULATOR_EVENTS.RELAUNCH (carrying the rebuilt simulator URL) into the
+     * existing WCV so the shell boots a new app session in place and swaps when
+     * it is ready — the phone shell never unmounts. Returns false (no event
+     * sent) when there is no live simulator view or its shell has not finished
+     * its first boot (first render guest did-finish-load); the caller then falls
+     * back to the hard attachNativeSimulator rebuild.
+     */
+    softReloadNativeSimulator(simulatorUrl: string): boolean;
     /**
      * Destroy and null out the simulator view (e.g. on simulator detach).
      * Also destroys the cached settings view and hides the popover —
@@ -273,23 +288,12 @@ 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.
  *
- * All view-related mutable state lives inside this closure and is not exposed
- * on the context object.
+ * All view-related mutable state lives inside the per-domain factory closures
+ * (and the single placement reconciler) below, never on the context object.
  */
 export declare function createViewManager(ctx: ViewManagerContext): ViewManager;
 //# sourceMappingURL=view-manager.d.ts.map