@dimina-kit/devtools 0.4.0-dev.20260701083540 → 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/placement-test-driver.d.ts

@@ -0,0 +1,25 @@
+import type { DesiredView } from '@dimina-kit/electron-deck/layout';
+import { type DevtoolsExtra } from '../../../shared/view-ids.js';
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface SnapshotSink {
+    setPlacementSnapshot(snapshot: {
+        generation: number;
+        epoch: number;
+        views: DesiredView<DevtoolsExtra>[];
+    }): void;
+}
+export declare function hostToolbarBounds(mgr: SnapshotSink, rect: Rect): void;
+export declare function simulatorDevtoolsBounds(mgr: SnapshotSink, rect: Rect): void;
+export declare function workbenchBounds(mgr: SnapshotSink, rect: Rect): void;
+export declare function simulatorBounds(mgr: SnapshotSink, params: Rect & {
+    zoom: number;
+}): void;
+/** Drop a view from this manager's desired table (reconcile detaches it). */
+export declare function removeView(mgr: SnapshotSink, viewId: string): void;
+export {};
+//# sourceMappingURL=placement-test-driver.d.ts.map

package/dist/main/services/views/placement-test-driver.js

@@ -0,0 +1,48 @@
+// Test-only helper: drives the view manager through its real runtime entry
+// point, `setPlacementSnapshot`, the way the renderer's central publisher does
+// — accumulating each view's desired placement (per manager) and publishing the
+// WHOLE table under a monotonic epoch. A single-view update thus keeps the other
+// views' last-declared placement, matching the renderer's level-triggered stream
+// rather than the old per-view setXxxBounds edges. These free functions let the
+// many view-manager tests exercise reconcile behaviour with a drop-in rename
+// (`mgr.setHostToolbarBounds(r)` → `hostToolbarBounds(mgr, r)`).
+import { VIEW_ID, VIEW_LAYER } from '../../../shared/view-ids.js';
+// Monotonic across every push in a test file (vitest isolates module state per
+// file), so a fresh manager (lastEpoch -1) accepts the first push and repeated
+// pushes on one manager never look stale.
+let globalEpoch = 0;
+const desiredByMgr = new WeakMap();
+function toPlacement(r) {
+    return r.width > 0 && r.height > 0 ? { visible: true, bounds: r } : { visible: false };
+}
+function pushView(mgr, view, generation = 1) {
+    let desired = desiredByMgr.get(mgr);
+    if (!desired) {
+        desired = new Map();
+        desiredByMgr.set(mgr, desired);
+    }
+    desired.set(view.viewId, view);
+    mgr.setPlacementSnapshot({ generation, epoch: globalEpoch++, views: [...desired.values()] });
+}
+export function hostToolbarBounds(mgr, rect) {
+    pushView(mgr, { viewId: VIEW_ID.hostToolbar, placement: toPlacement(rect), layer: VIEW_LAYER.hostToolbar });
+}
+export function simulatorDevtoolsBounds(mgr, rect) {
+    pushView(mgr, { viewId: VIEW_ID.simulatorDevtools, placement: toPlacement(rect), layer: VIEW_LAYER.base });
+}
+export function workbenchBounds(mgr, rect) {
+    pushView(mgr, { viewId: VIEW_ID.workbench, placement: toPlacement(rect), layer: VIEW_LAYER.base });
+}
+export function simulatorBounds(mgr, params) {
+    const { zoom, ...rect } = params;
+    pushView(mgr, { viewId: VIEW_ID.simulator, placement: toPlacement(rect), layer: VIEW_LAYER.base, extra: { zoom } });
+}
+/** Drop a view from this manager's desired table (reconcile detaches it). */
+export function removeView(mgr, viewId) {
+    const desired = desiredByMgr.get(mgr);
+    if (!desired)
+        return;
+    desired.delete(viewId);
+    mgr.setPlacementSnapshot({ generation: 1, epoch: globalEpoch++, views: [...desired.values()] });
+}
+//# sourceMappingURL=placement-test-driver.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,8 +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';
+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.
@@ -11,10 +13,10 @@ export interface ViewManagerContext {
     windows: WorkbenchContext['windows'];
     rendererDir: string;
     /**
-     * Per-webContents connection registry (foundation.md §4). The native-host
+     * Per-webContents connection registry. The native-host
      * simulator WebContentsView is acquired here so the registry tracks that
      * trusted webContents and tears its per-wc resources (the custom-api bridge
-     * `ipcMain.on`) down deterministically on destroy — see P1 DoD #3. Required:
+     * `ipcMain.on`) down deterministically on destroy. Required:
      * `createWorkbenchContext` always supplies it.
      */
     connections: WorkbenchContext['connections'];
@@ -67,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 {
     /**
@@ -87,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 —
@@ -135,22 +152,6 @@ export interface ViewManager {
      * always on close-project → reopen) would otherwise be lost forever.
      */
     getHostToolbarHeight(): number;
-    /**
-     * NATIVE-HOST ONLY. Position the simulator content WebContentsView over the
-     * renderer-measured simulator panel REGION rect (the flex:1 placeholder slot,
-     * CSS px from the main window content top-left, which maps 1:1 to overlay
-     * setBounds DIP) and apply the device zoom. The WCV fills the region as a
-     * plain rectangle; DeviceShell draws + scrolls the phone inside. No-op in the
-     * default `<webview>` path (`nativeSimulatorView` is null). See
-     * `computeNativeSimulatorViewParams`.
-     */
-    setNativeSimulatorViewBounds(params: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-        zoom: number;
-    }): void;
     /**
      * NATIVE-HOST ONLY. Re-push the selected device's CSS `env(safe-area-inset-*)`
      * override to every attached render-host guest (on device change). New guests
@@ -164,17 +165,12 @@ export interface ViewManager {
      */
     resize(simWidth: number): void;
     /**
-     * Apply a renderer-measured rectangle to the simulator's Chromium
-     * DevTools overlay view. `{ width: 0, height: 0 }` is treated as "hide" —
-     * the view is removed from the contentView but its WebContents is kept
-     * alive so re-showing it doesn't re-pay the DevTools bootstrap.
+     * Apply the renderer's window-level placement snapshot — the single source of
+     * truth for every managed native view's bounds/visibility/z-order. Merged with
+     * main-owned settings/popover desired state and reconciled against the actual
+     * view tree.
      */
-    setSimulatorDevtoolsBounds(bounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    }): void;
+    setPlacementSnapshot(snapshot: PlacementSnapshot<DevtoolsExtra>): void;
     /**
      * Lazily create the workbench WebContentsView, load `<url>index.html`, and
      * add it to the contentView. `url` is the COI server's base URL (trailing
@@ -188,19 +184,6 @@ export interface ViewManager {
      * `setWorkbenchBounds`, keeping it off the app boot critical path.
      */
     setWorkbenchSource(url: string): void;
-    /**
-     * Apply a renderer-measured rectangle to the workbench editor view. Mirrors
-     * `setSimulatorDevtoolsBounds`: `{ width: 0, height: 0 }` is "hide" — the view
-     * is removed from the contentView (kept under settings/popover when re-added)
-     * but its WebContents stays alive. The first non-zero rect lazily creates +
-     * loads the workbench (from the URL set by `setWorkbenchSource`).
-     */
-    setWorkbenchBounds(bounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    }): void;
     /** Destroy the workbench editor view (teardown). No-op if never attached. */
     detachWorkbench(): void;
     /**
@@ -211,20 +194,6 @@ export interface ViewManager {
      * request was dispatched to the workbench.
      */
     openFileInWorkbench(relPath: string, line: number, column: number): boolean;
-    /**
-     * Apply a renderer-measured rectangle to the host-controllable toolbar
-     * WebContentsView (the strip above the devtools header). Forward anchor,
-     * mirroring `setSimulatorDevtoolsBounds`. `{ width: 0, height: 0 }` is
-     * treated as "hide" — the view is removed from the contentView but its
-     * WebContents (and the host's loaded content) stays alive. Lazily creates
-     * the view on the first non-empty rect.
-     */
-    setHostToolbarBounds(bounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    }): void;
     /**
      * Reverse size-advertiser sink: the toolbar WCV's own renderer advertises
      * its intrinsic content height (block-axis extent); we retain it as the
@@ -319,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