@dimina-kit/devtools 0.3.2-dev.20260524104239 → 0.3.2-dev.20260601115343

package/dist/main/services/simulator-temp-files/request-handler.js

@@ -0,0 +1,178 @@
+/**
+ * Pure dispatcher for `difile://` URL requests.
+ *
+ * Spec: `packages/devtools/docs/file-system.md` §4.3.
+ *
+ * The shipping implementation in `index.ts` registers a thin
+ * `simSession.protocol.handle('difile')` wrapper that delegates here; the race
+ * waiter on `_tmp/*` lives in `index.ts` because it owns the IPC lifecycle.
+ * For unit tests we assume the bytes are already in the store.
+ *
+ * Response shape:
+ *   - 200: full body, with Content-Type, Cache-Control (immutable), ETag
+ *   - 206: range slice, plus Content-Range
+ *   - 304: empty body when `If-None-Match` matches the on-disk ETag. Per RFC
+ *     9110 §13.1.2 If-None-Match wins over Range.
+ *   - 404: anything `resolveVPath` rejects, plus disk-side ENOENT and any
+ *     other I/O error. The protocol handler in `index.ts` translates this
+ *     into the renderer's network failure surface; we deliberately do not
+ *     leak errno strings.
+ */
+import { resolveVPath } from '../../../shared/vpath.js';
+import { readDiskFile } from './disk.js';
+const CACHE_CONTROL = 'public, max-age=31536000, immutable';
+function getHeader(headers, name) {
+    if (!headers)
+        return undefined;
+    const lc = name.toLowerCase();
+    for (const k of Object.keys(headers)) {
+        if (k.toLowerCase() === lc)
+            return headers[k];
+    }
+    return undefined;
+}
+/**
+ * Weak ETag comparison per RFC 9110 §8.8.3.2: strip the optional `W/` prefix
+ * from each side before comparing. Both our generated ETags and conditional
+ * headers may or may not include the weak prefix; the comparison must accept
+ * `W/"abc"` and `"abc"` as equivalent.
+ */
+function etagsMatch(a, b) {
+    if (!a)
+        return false;
+    const stripped = (s) => (s.startsWith('W/') ? s.slice(2) : s);
+    return stripped(a.trim()) === stripped(b);
+}
+/**
+ * Parse a `Range: bytes=<start>-<end>` header into an inclusive `{start,end}`.
+ * Returns `null` if absent or malformed (callers should treat that as "no
+ * range" — a full 200 response, not a 416). `totalSize` clamps the end.
+ */
+function parseRange(header, totalSize) {
+    if (!header)
+        return null;
+    const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!m)
+        return null;
+    const startStr = m[1];
+    const endStr = m[2];
+    if (startStr === '' && endStr === '')
+        return null;
+    if (startStr === '') {
+        // Suffix range: last N bytes.
+        const n = Number(endStr);
+        if (!Number.isFinite(n) || n <= 0)
+            return null;
+        const start = Math.max(0, totalSize - n);
+        return { start, end: totalSize - 1 };
+    }
+    const start = Number(startStr);
+    if (!Number.isFinite(start) || start < 0)
+        return null;
+    const end = endStr === '' ? totalSize - 1 : Number(endStr);
+    if (!Number.isFinite(end))
+        return null;
+    return { start, end };
+}
+function notFound() {
+    return new Response(null, { status: 404 });
+}
+function notModified(etag) {
+    return new Response(null, {
+        status: 304,
+        headers: {
+            ETag: etag,
+            'Cache-Control': CACHE_CONTROL,
+            'Access-Control-Allow-Origin': '*',
+        },
+    });
+}
+function bufferToBody(bytes) {
+    // Copy into a fresh ArrayBuffer so the result is definitely typed as
+    // `ArrayBuffer` (not `ArrayBufferLike` / `SharedArrayBuffer`) and is
+    // safe to hand to Response without aliasing the Node Buffer pool.
+    const out = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(out).set(bytes);
+    return out;
+}
+function tempBody(bytes, mime) {
+    return new Response(bufferToBody(bytes), {
+        status: 200,
+        headers: {
+            'Content-Type': mime,
+            'Cache-Control': CACHE_CONTROL,
+            'Access-Control-Allow-Origin': '*',
+        },
+    });
+}
+export async function handleDifileRequest(ctx, req) {
+    const v = resolveVPath(req.url);
+    if (!v)
+        return notFound();
+    if (v.kind === 'tmp') {
+        const record = ctx.tempStore.get(req.url);
+        if (!record)
+            return notFound();
+        return tempBody(record.bytes, record.mime || 'application/octet-stream');
+    }
+    if (!v.realPath)
+        return notFound();
+    // Disk-backed: _store or usr.
+    try {
+        // Probe first to learn the ETag/size so If-None-Match can short-circuit
+        // without reading the body. The probe also doubles as our existence /
+        // permission check, so anything that throws here (ENOENT, EACCES, ...)
+        // surfaces as a 404.
+        const probe = await readDiskFile(v.realPath);
+        const etag = probe.etag;
+        const totalSize = probe.totalSize;
+        const mime = probe.mime;
+        const ifNoneMatch = getHeader(req.headers, 'If-None-Match');
+        if (etagsMatch(ifNoneMatch, etag)) {
+            return notModified(etag);
+        }
+        const rangeHeader = getHeader(req.headers, 'Range');
+        const range = parseRange(rangeHeader, totalSize);
+        if (range) {
+            // Range out of bounds → 416 (Range Not Satisfiable) per RFC 9110 §15.4.
+            // Distinct from 404 so callers can tell "wrong file" from "wrong slice".
+            if (range.start < 0 || range.start >= totalSize || range.end < range.start) {
+                return new Response(null, {
+                    status: 416,
+                    headers: {
+                        'Content-Range': `bytes */${totalSize}`,
+                        'Access-Control-Allow-Origin': '*',
+                    },
+                });
+            }
+            const clampedEnd = Math.min(range.end, totalSize - 1);
+            const sliced = await readDiskFile(v.realPath, { range: { start: range.start, end: clampedEnd } });
+            const { bytes } = sliced;
+            const lastByte = range.start + bytes.length - 1;
+            return new Response(bufferToBody(bytes), {
+                status: 206,
+                headers: {
+                    'Content-Type': mime,
+                    'Content-Length': String(bytes.length),
+                    'Content-Range': `bytes ${range.start}-${lastByte}/${totalSize}`,
+                    'Cache-Control': CACHE_CONTROL,
+                    ETag: etag,
+                    'Access-Control-Allow-Origin': '*',
+                },
+            });
+        }
+        return new Response(bufferToBody(probe.bytes), {
+            status: 200,
+            headers: {
+                'Content-Type': mime,
+                'Cache-Control': CACHE_CONTROL,
+                ETag: etag,
+                'Access-Control-Allow-Origin': '*',
+            },
+        });
+    }
+    catch {
+        return notFound();
+    }
+}
+//# sourceMappingURL=request-handler.js.map

package/dist/main/services/simulator-temp-files/resolver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure lookup helper backing the main-process `difile://_tmp/*` protocol
+ * handler. Receives the shared {@link TempFileStore} that the
+ * `simulator:temp-file:*` IPC channels populate from the renderer.
+ *
+ * The full URL (including scheme + host) is used as the Map key — the resolver
+ * never re-parses or normalises it, so any URL with a wrong scheme or host
+ * misses regardless of suffix similarity.
+ */
+export interface TempFileRecord {
+    bytes: Buffer;
+    mime: string;
+}
+export type TempFileStore = Map<string, TempFileRecord>;
+export declare function resolveTempFile(store: TempFileStore, url: string): {
+    status: 200;
+    bytes: Buffer;
+    mime: string;
+} | {
+    status: 404;
+};
+//# sourceMappingURL=resolver.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * Pure lookup helper backing the main-process `difile://_tmp/*` protocol
+ * handler. Receives the shared {@link TempFileStore} that the
+ * `simulator:temp-file:*` IPC channels populate from the renderer.
+ *
+ * The full URL (including scheme + host) is used as the Map key — the resolver
+ * never re-parses or normalises it, so any URL with a wrong scheme or host
+ * misses regardless of suffix similarity.
+ */
+export function resolveTempFile(store, url) {
+    if (!url.startsWith('difile://_tmp/'))
+        return { status: 404 };
+    const record = store.get(url);
+    if (!record)
+        return { status: 404 };
+    return {
+        status: 200,
+        bytes: record.bytes,
+        mime: record.mime || 'application/octet-stream',
+    };
+}
+//# sourceMappingURL=resolver.js.map

package/dist/main/services/simulator-temp-files/store.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Mutators for the shared {@link TempFileStore}. The renderer-side bridge
+ * forwards every `createTempFilePath` / `registerTempFilePath` /
+ * `revokeTempFilePath` / `revokeAllTempFilePaths` call over IPC, and these
+ * helpers translate the payloads into Map writes.
+ *
+ * ArrayBuffer inputs are normalised to Buffer at the boundary so the
+ * resolver hot path can return the bytes directly without re-wrapping.
+ */
+import type { TempFileStore } from './resolver.js';
+export declare function registerTempFile(store: TempFileStore, path: string, mime: string, bytes: ArrayBuffer | Buffer): void;
+export declare function revokeTempFile(store: TempFileStore, path: string): void;
+export declare function revokeAllTempFiles(store: TempFileStore): void;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1,24 @@
+/**
+ * Mutators for the shared {@link TempFileStore}. The renderer-side bridge
+ * forwards every `createTempFilePath` / `registerTempFilePath` /
+ * `revokeTempFilePath` / `revokeAllTempFilePaths` call over IPC, and these
+ * helpers translate the payloads into Map writes.
+ *
+ * ArrayBuffer inputs are normalised to Buffer at the boundary so the
+ * resolver hot path can return the bytes directly without re-wrapping.
+ */
+export function registerTempFile(store, path, mime, bytes) {
+    const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(new Uint8Array(bytes));
+    // delete-then-set so an existing entry's insertion order is refreshed.
+    // Without this, a FIFO cap eviction over `store.keys()` could drop a
+    // recently re-written path.
+    store.delete(path);
+    store.set(path, { bytes: buf, mime });
+}
+export function revokeTempFile(store, path) {
+    store.delete(path);
+}
+export function revokeAllTempFiles(store) {
+    store.clear();
+}
+//# sourceMappingURL=store.js.map

package/dist/main/services/toolbar/toolbar-store.d.ts

@@ -4,8 +4,8 @@ import type { ToolbarAction, ToolbarActionInput } from '../../../shared/types.js
  *
  * The toolbar is modelled as "one table the host recomputes from its current
  * state": `set()` replaces the whole table atomically. The non-serialisable
- * `handler` is kept main-process side; `list()` projects to `{id,label}[]`
- * for the IPC boundary, and `getHandler()` resolves a handler by id.
+ * `handler` is kept main-process side; `list()` projects display metadata for
+ * the IPC boundary, and `getHandler()` resolves a handler by id.
  */
 export interface ToolbarStore {
     /**
@@ -14,7 +14,7 @@ export interface ToolbarStore {
      * a rejected batch leaves the previous table intact.
      */
     set(actions: ToolbarActionInput[]): void;
-    /** Project the current table to `{id,label}[]` — no `handler` leaks out. */
+    /** Project the current table to serialisable display metadata — no `handler` leaks out. */
     list(): ToolbarAction[];
     /** Resolve the handler stored under `id`, or `undefined` if unknown. */
     getHandler(id: string): (() => void | Promise<void>) | undefined;

package/dist/main/services/toolbar/toolbar-store.js

@@ -1,3 +1,20 @@
+function toPublicAction(action) {
+    const projected = {
+        id: action.id,
+        label: action.label,
+    };
+    if (action.kind)
+        projected.kind = action.kind;
+    if (action.placement)
+        projected.placement = action.placement;
+    if (action.icon)
+        projected.icon = action.icon;
+    if (action.displayInitial)
+        projected.displayInitial = action.displayInitial;
+    if (action.avatarUrl)
+        projected.avatarUrl = action.avatarUrl;
+    return projected;
+}
 export function createToolbarStore() {
     let actions = [];
     return {
@@ -13,7 +30,7 @@ export function createToolbarStore() {
             actions = next.slice();
         },
         list() {
-            return actions.map(({ id, label }) => ({ id, label }));
+            return actions.map(toPublicAction);
         },
         getHandler(id) {
             return actions.find((a) => a.id === id)?.handler;

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

@@ -24,6 +24,16 @@ export declare class UpdateManager {
     private getCurrentVersion;
     private latestUpdate;
     private downloadedPath;
+    /**
+     * Whether this instance has already emitted `Available` once. The periodic
+     * check fires forever (interval default 1h), and downstream UI (qdmp 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
+     * already knows "an update exists"; tracking minor version bumps mid-
+     * session is not worth duplicating the toast.
+     */
+    private hasNotified;
     private timer;
     private initialTimer;
     private ipc;

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

@@ -7,6 +7,16 @@ export class UpdateManager {
     getCurrentVersion;
     latestUpdate = null;
     downloadedPath = null;
+    /**
+     * Whether this instance has already emitted `Available` once. The periodic
+     * check fires forever (interval default 1h), and downstream UI (qdmp 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
+     * already knows "an update exists"; tracking minor version bumps mid-
+     * session is not worth duplicating the toast.
+     */
+    hasNotified = false;
     timer = null;
     initialTimer = null;
     ipc;
@@ -85,9 +95,12 @@ export class UpdateManager {
     }
     async checkAndNotify() {
         const result = await this.check();
-        if (result.hasUpdate && result.info) {
-            this.mainWindow.webContents.send(UpdateChannel.Available, result.info);
-        }
+        if (!result.hasUpdate || !result.info)
+            return;
+        if (this.hasNotified)
+            return;
+        this.hasNotified = true;
+        this.mainWindow.webContents.send(UpdateChannel.Available, result.info);
     }
 }
 //# sourceMappingURL=update-manager.js.map

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

@@ -20,13 +20,14 @@ export interface ViewManagerContext {
  * Unified lifecycle manager for Electron WebContentsView overlays.
  *
  * Owns creation / attachment / detachment / positioning / destruction of
- * every overlay view hung off the main window's contentView (simulator,
- * settings, popover). All `new WebContentsView`, `addChildView`,
+ * every overlay view hung off the main window's contentView (simulator
+ * DevTools, settings, popover). All `new WebContentsView`, `addChildView`,
  * `removeChildView`, `webContents.destroy()` and overlay `setBounds` calls
  * should live here — IPC handlers just call into the manager.
  *
- * The main window's own renderer (added in `windows/main-window/create.ts`)
- * is the main content root and is not an overlay, so it is not managed here.
+ * The code editor is NOT an overlay: it renders as an in-renderer
+ * `<MonacoEditor/>` React component inside the main window. The main
+ * window's own renderer is the content root and is not managed here.
  */
 export interface ViewManager {
     /**
@@ -78,6 +79,18 @@ export interface ViewManager {
     resize(simWidth: number): void;
     /** Show or hide the simulator overlay based on visibility flag. */
     setVisible(visible: boolean, 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.
+     */
+    setSimulatorDevtoolsBounds(bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
 }
 /**
  * Build a ViewManager bound to the given context. The returned object is the

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

@@ -23,6 +23,11 @@ export function createViewManager(ctx) {
     let popoverView = null;
     let lastSimWidth = 375;
     let simulatorWebContentsId = null;
+    // Renderer-driven overlay bounds for the simulator DevTools view. When
+    // non-null this takes precedence over the legacy layout computed from the
+    // window content size. A zero-area rectangle means "hide" — the overlay is
+    // removed from the contentView but its WebContents stays alive.
+    let simulatorBoundsOverride = null;
     // ── Internal helpers ────────────────────────────────────────────────────
     function destroyViewInternal(view) {
         if (!view)
@@ -43,9 +48,42 @@ export function createViewManager(ctx) {
     function applySimulatorBounds(simWidth) {
         if (!simulatorView || ctx.windows.mainWindow.isDestroyed())
             return;
+        if (simulatorBoundsOverride) {
+            simulatorView.setBounds(simulatorBoundsOverride);
+            return;
+        }
         const [w = 0, h = 0] = ctx.windows.mainWindow.getContentSize();
         simulatorView.setBounds(layout.computeSimulatorBounds(w, h, simWidth, headerHeight));
     }
+    // Renderer publishes width/height = 0 to mean "hide overlay" — the
+    // surrounding React panel is unmounted/collapsed. We keep the cached
+    // value (so future republishes win over legacy layout) but remove the
+    // child view from the contentView until a non-empty rect arrives.
+    function isHidden(b) {
+        return b.width <= 0 || b.height <= 0;
+    }
+    function setSimulatorDevtoolsBounds(bounds) {
+        simulatorBoundsOverride = bounds;
+        if (!simulatorView || simulatorView.webContents.isDestroyed())
+            return;
+        if (ctx.windows.mainWindow.isDestroyed())
+            return;
+        if (isHidden(bounds)) {
+            if (simulatorViewAdded) {
+                try {
+                    ctx.windows.mainWindow.contentView.removeChildView(simulatorView);
+                }
+                catch { /* already removed */ }
+                simulatorViewAdded = false;
+            }
+            return;
+        }
+        if (!simulatorViewAdded) {
+            ctx.windows.mainWindow.contentView.addChildView(simulatorView);
+            simulatorViewAdded = true;
+        }
+        simulatorView.setBounds(bounds);
+    }
     function applySettingsBounds() {
         if (!settingsView || ctx.windows.mainWindow.isDestroyed())
             return;
@@ -82,9 +120,13 @@ export function createViewManager(ctx) {
         sim.setDevToolsWebContents(simulatorView.webContents);
         sim.openDevTools();
         // Default DevTools to Console panel (Chrome DevTools defaults to Elements).
-        // The DevTools UI renders inside simulatorView.webContents; we click the
-        // Console tab once its header is laid out, and persist the choice via
-        // localStorage so subsequent reloads honor it.
+        // The DevTools UI lives inside closed shadow roots, so a light-DOM
+        // querySelector('[role="tab"]') cannot reach the tab bar to click it.
+        // Instead drive the front-end's own view manager: the bundled DevTools
+        // exposes `UI.ViewManager.instance().showView(id)` on `globalThis.UI`
+        // once the front-end has finished bootstrapping. We poll for it and
+        // request the `console` view, and also persist the choice via the
+        // `panel-selectedTab` localStorage key so subsequent reloads honor it.
         const devtoolsWc = simulatorView.webContents;
         devtoolsWc.once('dom-ready', () => {
             devtoolsWc.executeJavaScript(`
@@ -93,24 +135,35 @@ export function createViewManager(ctx) {
           let tries = 0
           const timer = setInterval(() => {
             tries++
-            const tabs = document.querySelectorAll('[role="tab"], .tabbed-pane-header-tab')
-            for (const tab of tabs) {
-              const label = (tab.getAttribute('aria-label') || tab.textContent || '').trim().toLowerCase()
-              if (label === 'console' || label.startsWith('console')) {
-                tab.click()
+            try {
+              const UI = globalThis.UI
+              const vm = UI && UI.ViewManager && typeof UI.ViewManager.instance === 'function'
+                ? UI.ViewManager.instance()
+                : null
+              if (vm && typeof vm.showView === 'function') {
+                vm.showView('console')
                 clearInterval(timer)
                 return
               }
-            }
-            if (tries > 40) clearInterval(timer)
-          }, 100)
+            } catch {}
+            if (tries > 80) clearInterval(timer)
+          }, 50)
         })()
       `).catch(() => { });
         });
         if (getDefaultTab(ctx) === 'simulator') {
-            ctx.windows.mainWindow.contentView.addChildView(simulatorView);
-            simulatorViewAdded = true;
-            applySimulatorBounds(simWidth);
+            if (simulatorBoundsOverride) {
+                if (!isHidden(simulatorBoundsOverride)) {
+                    ctx.windows.mainWindow.contentView.addChildView(simulatorView);
+                    simulatorViewAdded = true;
+                    simulatorView.setBounds(simulatorBoundsOverride);
+                }
+            }
+            else {
+                ctx.windows.mainWindow.contentView.addChildView(simulatorView);
+                simulatorViewAdded = true;
+                applySimulatorBounds(simWidth);
+            }
         }
     }
     function detachSimulator() {
@@ -123,6 +176,9 @@ export function createViewManager(ctx) {
         simulatorView = null;
         simulatorViewAdded = false;
         simulatorWebContentsId = null;
+        // Drop the renderer-published rect so a stale "hidden" override doesn't
+        // suppress the next view before its renderer republishes.
+        simulatorBoundsOverride = null;
     }
     function showSimulator(simWidth) {
         lastSimWidth = simWidth;
@@ -276,6 +332,7 @@ export function createViewManager(ctx) {
         },
         resize,
         setVisible,
+        setSimulatorDevtoolsBounds,
     };
 }
 //# sourceMappingURL=view-manager.js.map

package/dist/main/services/workbench-context.d.ts

@@ -10,7 +10,7 @@ import { type SimulatorApiRegistry } from './simulator/custom-apis.js';
 import { type ToolbarStore } from './toolbar/toolbar-store.js';
 import { sanitizeTemplates } from './projects/templates.js';
 import type { ProjectsProvider, ProjectTemplate } from './projects/types.js';
-import type { CustomCreateProjectDialogResult } from '../../shared/types.js';
+import type { BeforeOpenProjectResult, CustomCreateProjectDialogResult } from '../../shared/types.js';
 /**
  * Shared mutable state for the workbench application.
  * Passed to each IPC module so they can read/write shared state without closures.
@@ -67,6 +67,11 @@ export interface WorkbenchContext {
         parentWindow: BrowserWindow;
         templates: ProjectTemplate[];
     }) => Promise<CustomCreateProjectDialogResult>;
+    /**
+     * Optional host gate for opening projects. Runs after basic directory
+     * validation and before the current project session is closed.
+     */
+    beforeOpenProject?: (projectPath: string) => BeforeOpenProjectResult | Promise<BeforeOpenProjectResult>;
     /**
      * Trust predicate consulted by `IpcRegistry` for every incoming IPC.
      * Resolves the currently-trusted senders (main renderer + overlays)

package/dist/main/services/workspace/workspace-service.d.ts

@@ -38,6 +38,14 @@ export interface WorkspaceService {
         appInfo: unknown;
     } | null;
     getProjectPath(): string;
+    /**
+     * The project path most recently torn down by `closeProject`, or '' if none
+     * since the last `openProject`. Lets the project-fs sandbox accept an
+     * in-flight write (debounced/teardown flush) that targets the just-closed
+     * project even though `getProjectPath()` has already been cleared. Reset to
+     * '' on the next `openProject` so it never accumulates stale roots.
+     */
+    getLastClosedProjectPath(): string;
     hasActiveSession(): boolean;
     captureThumbnail(projectPath: string): Promise<string | null>;
     getThumbnail(projectPath: string): Promise<string | null>;

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

@@ -6,6 +6,10 @@ import { loadWorkbenchSettings } from '../settings/index.js';
 export function createWorkspaceService(ctx) {
     let currentSession = null;
     let currentProjectPath = '';
+    // The last project path cleared by `closeProject`; consumed by project-fs to
+    // accept an in-flight write that targets the just-closed project. Reset at
+    // the start of every `openProject` so it never accumulates a stale root.
+    let lastClosedProjectPath = '';
     function sendStatus(status, message, hotReload) {
         ctx.notify.projectStatus(hotReload ? { status, message, hotReload: true } : { status, message });
     }
@@ -58,9 +62,6 @@ export function createWorkspaceService(ctx) {
             ? provider.validateProjectDir(dirPath)
             : null,
         async openProject(projectPath) {
-            clearSimulatorServicewechatReferer();
-            await disposeSession();
-            currentProjectPath = '';
             // Reject obviously broken projects up front so we never spin up a
             // compile/server that the simulator will then fetch asset-by-asset.
             // Without this guard, deleted recent-list entries and typo'd CLI paths
@@ -75,6 +76,18 @@ export function createWorkspaceService(ctx) {
                 sendStatus('error', dirError);
                 return { success: false, error: dirError };
             }
+            const gate = ctx.beforeOpenProject ? await ctx.beforeOpenProject(projectPath) : undefined;
+            if (gate && !gate.allow) {
+                const message = gate.userMessage ?? gate.reason;
+                sendStatus('error', message);
+                return { success: false, error: message };
+            }
+            clearSimulatorServicewechatReferer();
+            await disposeSession();
+            currentProjectPath = '';
+            // A fresh open starts a clean sandbox window — drop any previously
+            // recorded last-closed root so it can't accept writes after this point.
+            lastClosedProjectPath = '';
             sendStatus('compiling', '正在编译...');
             const { compile } = loadWorkbenchSettings();
             let session;
@@ -98,7 +111,7 @@ export function createWorkspaceService(ctx) {
                 if (provider.updateLastOpened)
                     provider.updateLastOpened(projectPath);
             });
-            bestEffort('sendStatus', () => sendStatus('ready', '编译完成'));
+            bestEffort('sendStatus', () => sendStatus('ready', gate?.statusMessage ?? '编译完成'));
             bestEffort('applyReferer', () => applyRefererFromSession(session));
             return {
                 success: true,
@@ -109,11 +122,16 @@ export function createWorkspaceService(ctx) {
         async closeProject() {
             clearSimulatorServicewechatReferer();
             await disposeSession();
+            // Record the root being torn down BEFORE clearing it, so a teardown/
+            // debounced write already in flight can still be accepted against it.
+            if (currentProjectPath !== '')
+                lastClosedProjectPath = currentProjectPath;
             currentProjectPath = '';
             ctx.views.disposeAll();
         },
         getSession: () => currentSession,
         getProjectPath: () => currentProjectPath,
+        getLastClosedProjectPath: () => lastClosedProjectPath,
         hasActiveSession: () => currentSession !== null,
         async captureThumbnail(projectPath) {
             const wc = ctx.views.getSimulatorWebContents();

package/dist/main/utils/ipc-registry.d.ts

@@ -1,4 +1,4 @@
-import type { WebContents } from 'electron';
+import type { IpcMainEvent, WebContents } from 'electron';
 import { ipcMain } from 'electron';
 import { type Disposable } from './disposable.js';
 type HandleFn = Parameters<typeof ipcMain.handle>[1];
@@ -32,6 +32,15 @@ export declare class IpcRegistry implements Disposable {
     private registry;
     constructor(policy?: SenderPolicy | undefined);
     handle(channel: string, fn: HandleFn): this;
+    /**
+     * Register a SYNCHRONOUS `ipcRenderer.sendSync` handler. Unlike {@link on}
+     * (fire-and-forget), the renderer is blocked until we set `event.returnValue`,
+     * so `fn` MUST be synchronous and return the value to hand back. The sender
+     * policy gates it like {@link handle}; a rejected sender or a thrown error
+     * yields a structured `{ ok: false, code, message }` returnValue instead of
+     * the silent drop `on` uses, so the blocked renderer always gets an answer.
+     */
+    handleSync(channel: string, fn: (event: IpcMainEvent, ...args: unknown[]) => unknown): this;
     on(channel: string, fn: ListenerFn): this;
     dispose(): Promise<void>;
 }