@dimina-kit/devtools 0.4.0-dev.20260707070110 → 0.4.0-dev.20260710085051

package/dist/main/app/app.js

@@ -356,7 +356,7 @@ export async function createDevtoolsRuntime(config = {}) {
     const context = createContext(config, mainWindow, rendererDir);
     // Anchor the main window's renderer as the first Connection. Resources
     // scoped to the main webContents (acquired by later wiring) tear down with
-    // it; see packages/electron-deck/docs/foundation.md §4.
+    // it; see packages/electron-deck/docs/foundation.md (teardown paths).
     context.connections.acquire(mainWindow.webContents);
     context.registry.add(registerAppIpc(context));
     // Sandboxed project file-system IPC (the renderer-side project:fs:* surface).

package/dist/main/index.bundle.js

@@ -27,7 +27,10 @@ var DEFAULTS = {
     port: 7789
   },
   compile: {
-    watch: true
+    autoBuild: true
+  },
+  preview: {
+    autoReload: true
   },
   theme: "system",
   lastCreateBaseDir: null
@@ -35,6 +38,9 @@ var DEFAULTS = {
 function getSettingsFile() {
   return path.join(app.getPath("userData"), "dimina-workbench-settings.json");
 }
+function pickBool(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
 function loadWorkbenchSettings() {
   try {
     const data = JSON.parse(fs.readFileSync(getSettingsFile(), "utf-8"));
@@ -49,7 +55,16 @@ function loadWorkbenchSettings() {
         port: data.mcp?.port ?? DEFAULTS.mcp.port
       },
       compile: {
-        watch: data.compile?.watch ?? DEFAULTS.compile.watch
+        // Legacy files persisted a single `compile.watch`; the new schema
+        // splits it into `compile.autoBuild` (recompile on save) and
+        // `preview.autoReload` (reload the simulator afterwards). Prefer the new
+        // key, fall back to the legacy one so an old settings file keeps its
+        // "auto-compile" choice; `preview.autoReload` defaults to true (the old
+        // always-reload behavior) when the file predates the split.
+        autoBuild: pickBool(data.compile?.autoBuild, pickBool(data.compile?.watch, DEFAULTS.compile.autoBuild))
+      },
+      preview: {
+        autoReload: pickBool(data.preview?.autoReload, DEFAULTS.preview.autoReload)
       },
       theme,
       lastCreateBaseDir: typeof data.lastCreateBaseDir === "string" ? data.lastCreateBaseDir : DEFAULTS.lastCreateBaseDir
@@ -59,7 +74,8 @@ function loadWorkbenchSettings() {
       ...DEFAULTS,
       cdp: { ...DEFAULTS.cdp },
       mcp: { ...DEFAULTS.mcp },
-      compile: { ...DEFAULTS.compile }
+      compile: { ...DEFAULTS.compile },
+      preview: { ...DEFAULTS.preview }
     };
   }
 }
@@ -502,12 +518,10 @@ var UpdateChannel = {
 };
 
 // src/main/ipc/project-fs.ts
+import { WATCH_IGNORE_DIRS } from "@dimina-kit/devkit/watch-ignore";
 var LIST_FILE_LIMIT = 5e3;
 var SKIP_DIRS = /* @__PURE__ */ new Set([
-  "node_modules",
-  ".git",
-  ".svn",
-  ".hg",
+  ...WATCH_IGNORE_DIRS,
   "dist",
   "build",
   ".next",
@@ -665,7 +679,18 @@ async function statWithin(root, rel) {
 }
 async function readdirWithin(root, rel) {
   const safe = await resolveWithinProjectRoot(joinRel(root, rel), root);
-  return fs2.readdir(safe, { withFileTypes: true });
+  const dirents = await fs2.readdir(safe, { withFileTypes: true });
+  return Promise.all(
+    dirents.map(async (d) => {
+      if (d.isDirectory()) return { name: d.name, isDirectory: true };
+      try {
+        const st = await fs2.stat(path2.join(safe, d.name));
+        return { name: d.name, isDirectory: false, size: st.size, mtimeMs: st.mtimeMs };
+      } catch {
+        return { name: d.name, isDirectory: false };
+      }
+    })
+  );
 }
 async function readFileBufferWithin(root, rel) {
   return readFileBuffer(root, joinRel(root, rel));
@@ -4095,16 +4120,18 @@ function createWorkspaceService(ctx) {
     }
   }
   async function runCompile(projectPath, sessionGeneration) {
-    const { compile } = loadWorkbenchSettings();
+    const { compile, preview } = loadWorkbenchSettings();
     try {
       const session5 = await ctx.adapter.openProject({
         projectPath,
         sourcemap: true,
         fileTypes: ctx.fileTypes,
-        watch: compile.watch,
+        // Two independent gates: autoBuild = recompile on save; autoReload = refresh the simulator afterwards (off ⇒ page/form state survives; hotReload below stays false so the native simulator, which has no SSE reload, isn't refreshed).
+        watch: compile.autoBuild,
+        autoReload: preview.autoReload,
         onRebuild: () => {
           const { pages } = getProjectPages(projectPath);
-          sendStatus("ready", "\u7F16\u8BD1\u5B8C\u6210\uFF0C\u5DF2\u91CD\u542F", true, pages.length ? pages : void 0);
+          sendStatus("ready", preview.autoReload ? "\u7F16\u8BD1\u5B8C\u6210\uFF0C\u5DF2\u91CD\u542F" : "\u7F16\u8BD1\u5B8C\u6210", preview.autoReload, pages.length ? pages : void 0);
         },
         onBuildError: (err2) => sendStatus("error", String(err2)),
         // Watcher died mid-session (EMFILE, permission loss, …): non-fatal, so 'ready' stays but `watcher: 'dead'` flags that saves no longer auto-rebuild.
@@ -4631,7 +4658,10 @@ var WorkbenchSettingsSaveSchema = z3.tuple([
       port: z3.number().int().min(0).max(65535)
     }),
     compile: z3.looseObject({
-      watch: z3.boolean()
+      autoBuild: z3.boolean()
+    }),
+    preview: z3.looseObject({
+      autoReload: z3.boolean()
     }),
     theme: z3.enum(["system", "light", "dark"]),
     lastCreateBaseDir: z3.union([z3.string(), z3.null()])
@@ -5298,7 +5328,7 @@ var ServiceHostPool = class {
   /**
    * 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
+   * (see prewarm-webview.md's invariants section). Fallback windows carry `entryId === null` and
    * are destroyed (not pooled) on release.
    *
    * A spec change (different `preloadPath`) tears down all *pooled* entries and
@@ -5374,7 +5404,7 @@ var ServiceHostPool = class {
   }
   /**
    * 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 beyond the target are disposed OLDEST-FIRST (see prewarm-webview.md); in-use
    * entries are untouched. Does not warm new entries up (use `init` / refill).
    */
   resize(target) {
@@ -5503,7 +5533,7 @@ var ServiceHostPool = class {
   }
   /**
    * 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
+   * (see prewarm-webview.md's state-machine and reset-ordering sections): 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.
    */
@@ -11044,8 +11074,12 @@ async function fsStat(ctx) {
 }
 async function fsReaddir(ctx) {
   const entries = await readdirWithin(ctx.projectRoot, ctx.rel);
-  const visible = entries.filter((e) => !(e.isDirectory() && SKIP_DIRS.has(e.name)));
-  jsonRes(ctx.res, 200, visible.map((e) => [e.name, e.isDirectory() ? 2 : 1]));
+  const visible = entries.filter((e) => !(e.isDirectory && SKIP_DIRS.has(e.name)));
+  jsonRes(
+    ctx.res,
+    200,
+    visible.map((e) => e.isDirectory ? [e.name, 2] : [e.name, 1, e.size, e.mtimeMs])
+  );
 }
 async function fsRead(ctx) {
   const buf = await readFileBufferWithin(ctx.projectRoot, ctx.rel);

package/dist/main/ipc/bridge-router.d.ts

@@ -108,7 +108,7 @@ export interface BridgeRouterHandle {
      */
     census?(): BridgeResourceCensus;
     /**
-     * The flag-gated debugTap (§7) over the bridge message stream. Exposed so a
+     * The flag-gated debugTap (see foundation.md) over the bridge message stream. Exposed so a
      * hidden devtools panel / automation can read `.entries()` when
      * `DIMINA_DEBUG_TAP=1`; a no-op snapshot otherwise. Optional so the many
      * partial `BridgeRouterHandle` test mocks don't each have to stub it.

package/dist/main/ipc/bridge-router.js

@@ -63,10 +63,11 @@ const STACK_ID = 'stack_0';
  * constant instead of a magic number.
  */
 export const LAUNCH_TIMEOUT_MS = 20_000;
-/** Hard ceiling on the pre-warm pool, mirroring ServiceHostPool/doc §3.3. */
+/** Hard ceiling on the pre-warm pool, mirroring ServiceHostPool/prewarm-webview.md. */
 const PREWARM_MAX_POOL_SIZE = 4;
 /**
- * Resolve the pre-warm pool size from env (doc §6). Returns 0 (OFF) unless
+ * Resolve the pre-warm pool size from env (see prewarm-webview.md's config
+ * section). Returns 0 (OFF) unless
  * `DIMINA_PREWARM_POOL_SIZE` is a positive integer and `DIMINA_PREWARM_DISABLE`
  * is not set. Default OFF — pooling is opt-in so the spawn path is unchanged
  * unless explicitly enabled.
@@ -82,7 +83,7 @@ function resolvePrewarmPoolSize() {
         return 0;
     return Math.min(n, PREWARM_MAX_POOL_SIZE);
 }
-/** debugTap (§7) is opt-in via `DIMINA_DEBUG_TAP=1` — off everywhere else. */
+/** debugTap (see foundation.md) is opt-in via `DIMINA_DEBUG_TAP=1` — off everywhere else. */
 function resolveDebugTapEnabled() {
     return process.env.DIMINA_DEBUG_TAP === '1';
 }
@@ -181,8 +182,8 @@ export function installBridgeRouter(ctx) {
     if (prewarmPoolSize > 0) {
         const pool = new ServiceHostPool();
         state.pool = pool;
-        // Defer warm-up off the cold-start critical path (doc §3.3: app.ready +
-        // idle). Warming eagerly here races main-window startup — it creates an
+        // Defer warm-up off the cold-start critical path (see prewarm-webview.md:
+        // app.ready + idle). Warming eagerly here races main-window startup — it creates an
         // extra hidden BrowserWindow before the workbench renderer has settled,
         // which made the e2e's first-window/preload-readiness flaky. The timer is
         // cancelled on teardown so it can't warm a disposed pool.
@@ -451,7 +452,7 @@ export function installBridgeRouter(ctx) {
     };
     ipcMain.on(C.DISPOSE, onDispose);
     ctx.registry.add(() => { ipcMain.removeListener(C.DISPOSE, onDispose); });
-    // debugTap (§7) ingress recorder — near-free no-op unless DIMINA_DEBUG_TAP=1.
+    // debugTap (see foundation.md) ingress recorder — near-free no-op unless DIMINA_DEBUG_TAP=1.
     // Hung on the bridge dispatch chokepoint so the cross-wc message flow is
     // inspectable (the first real consumer of the workbench debugTap primitive).
     const tapIn = (channel, sender, payload) => {
@@ -753,7 +754,8 @@ async function handleSpawn(state, ctx, event, opts) {
     appSession.pages.set(bridgeId, rootPage);
     bindWc(state.serviceWcIdToAppSessionId, serviceWindow.webContents, appSessionId);
     bindSimulatorWc(state.simulatorWcIdToAppSessionIds, simulatorWc, appSessionId);
-    // Track the service-host webContents as a Connection (foundation.md §4.3) and
+    // Track the service-host webContents as a Connection (the soft-reuse
+    // teardown path documented in foundation.md) and
     // own this session's serviceWc→appSessionId binding on its CURRENT lifetime
     // segment. On a pooled-window REUSE, `disposeAppSession` calls
     // `connections.reset(serviceWc.id)` → this owned cleanup fires + a fresh
@@ -761,7 +763,8 @@ async function handleSpawn(state, ctx, event, opts) {
     // real destroy the connection closes and fires it too. The cleanup is guarded
     // by `appSessionId` so it only clears a binding that is still THIS session's.
     // (The simulatorWc binding stays manual in `disposeAppSession`: the simulator
-    // wc outlives individual app sessions — cross-connection state, §4.4 — so it
+    // wc outlives individual app sessions — cross-connection state documented in
+    // foundation.md — so it
     // cannot hang off any single session's segment.)
     state.connections.acquire(serviceWindow.webContents).own(() => {
         if (state.serviceWcIdToAppSessionId.get(appSession.serviceWc.id) === appSessionId) {
@@ -1732,8 +1735,8 @@ function ensureRenderBound(state, sender, bridgeId) {
         page.renderWc = sender;
         state.wcIdToBridgeId.set(sender.id, bridgeId);
         // Consolidate the render-guest bookkeeping teardown onto the connection
-        // layer (foundation.md §4 / P2): the render guest is its own webContents =
-        // its own connection (§4.4); own() ties this cleanup to its lifetime so it
+        // layer (see foundation.md): the render guest is its own webContents =
+        // its own connection; own() ties this cleanup to its lifetime so it
         // fires on destroy, replacing the bespoke `once('destroyed')`. acquire() is
         // idempotent — re-binding the same sender re-uses its connection.
         state.connections.acquire(sender).own(() => {
@@ -1874,7 +1877,7 @@ function closeSessionPages(state, ap) {
 // the unpooled path.
 async function releaseServiceWindow(state, ap, opts) {
     if (ap.poolEntryId !== null && state.pool && !opts.serviceAlreadyClosed) {
-        // Soft reuse (foundation.md §4.3): the pooled service-host webContents keeps
+        // Soft reuse (see foundation.md): the pooled service-host webContents keeps
         // its wc.id but is about to run a NEW app session. Reset its Connection
         // BEFORE returning it to the pool — dispose this session's owned segment
         // (the serviceWc binding cleanup) and swap a fresh one — so an old in-flight

package/dist/main/ipc/project-fs.d.ts

@@ -2,7 +2,13 @@ import type { WorkbenchContext } from '../services/workbench-context.js';
 import type { Disposable } from '@dimina-kit/electron-deck/main';
 /** Dependency/VCS/build directories invisible to every project-tree consumer:
  * IPC `listFiles`, the `/__fs/readdir` bridge (so the workbench mirror and the
- * WAL ledger seed never walk into them), and the `/__fs/watch` change stream. */
+ * WAL ledger seed never walk into them), and the `/__fs/watch` change stream.
+ * Derived from devkit's `WATCH_IGNORE_DIRS` (the shared never-source core:
+ * node_modules + VCS) so the `node_modules` omission that once wedged
+ * `watcher.close()` can never drift back on this side, PLUS the editor mirror's
+ * own build-output names (`dist`/`build`/tool caches) — which the devkit
+ * recompile watcher deliberately does NOT ignore, since app.json may declare
+ * pages under such paths. */
 export declare const SKIP_DIRS: ReadonlySet<string>;
 /**
  * Synchronous, string-level guard: reject empty root (ENOACTIVE), NUL bytes
@@ -79,8 +85,31 @@ export declare function writeFile(root: string, p: string, content: string | Buf
  * out-of-sandbox metadata. `rel` is a project-root-relative bridge path.
  */
 export declare function statWithin(root: string, rel: string): Promise<import('node:fs').Stats>;
-/** Realpath-contained `fs.readdir` twin (see {@link statWithin}). */
-export declare function readdirWithin(root: string, rel: string): Promise<import('node:fs').Dirent[]>;
+/**
+ * One `readdirWithin` result entry. Directories carry no stat (the caller —
+ * the `/__fs/readdir` bridge handler — never needs it: a directory recurses
+ * instead of being compared). `size`/`mtimeMs` are omitted (not `null`) when
+ * the entry raced a concurrent delete between `readdir` and `stat` — the
+ * bridge wire format then drops them too, which the sync engine's watch
+ * expansion (dimina-kit workbench's wal-audit-watch-expand.ts) treats as
+ * "always changed" rather than risking a false stat match.
+ */
+export interface ReaddirStatEntry {
+    name: string;
+    isDirectory: boolean;
+    size?: number;
+    mtimeMs?: number;
+}
+/**
+ * Realpath-contained `fs.readdir` twin (see {@link statWithin}) that also
+ * `fs.stat`s every FILE entry (size + mtimeMs) — the disk-side half of the
+ * sync engine's stat-diffing (see wal-audit-watch-expand.ts's module doc):
+ * a watch-reported directory is only worth a full content re-read when a
+ * file's stat inside it actually moved, and the `/__fs/readdir` bridge is
+ * the one HTTP round trip cheap enough to do that check on every watch
+ * event without itself re-reading file bytes.
+ */
+export declare function readdirWithin(root: string, rel: string): Promise<ReaddirStatEntry[]>;
 /**
  * Raw-byte read twin of {@link readFileBuffer} taking a project-root-relative
  * bridge path (the COI `/__fs/read` bridge), with the same realpath +

package/dist/main/ipc/project-fs.js

@@ -47,14 +47,21 @@ import { z } from 'zod';
 import { IpcRegistry } from '../utils/ipc-registry.js';
 import { validate } from '../utils/ipc-schema.js';
 import { ProjectFsChannel } from '../../shared/ipc-channels.js';
+import { WATCH_IGNORE_DIRS } from '@dimina-kit/devkit/watch-ignore';
 /** Cap for `listFiles` — huge monorepos would otherwise stall the renderer. */
 const LIST_FILE_LIMIT = 5000;
 /** Dependency/VCS/build directories invisible to every project-tree consumer:
  * IPC `listFiles`, the `/__fs/readdir` bridge (so the workbench mirror and the
- * WAL ledger seed never walk into them), and the `/__fs/watch` change stream. */
+ * WAL ledger seed never walk into them), and the `/__fs/watch` change stream.
+ * Derived from devkit's `WATCH_IGNORE_DIRS` (the shared never-source core:
+ * node_modules + VCS) so the `node_modules` omission that once wedged
+ * `watcher.close()` can never drift back on this side, PLUS the editor mirror's
+ * own build-output names (`dist`/`build`/tool caches) — which the devkit
+ * recompile watcher deliberately does NOT ignore, since app.json may declare
+ * pages under such paths. */
 export const SKIP_DIRS = new Set([
-    'node_modules', '.git', '.svn', '.hg', 'dist', 'build',
-    '.next', '.cache', '.turbo', '.parcel-cache', '.nuxt', '.output', '.vite',
+    ...WATCH_IGNORE_DIRS,
+    'dist', 'build', '.next', '.cache', '.turbo', '.parcel-cache', '.nuxt', '.output', '.vite',
 ]);
 const PathArg = z.string().min(1);
 const ReadFileSchema = z.tuple([PathArg]);
@@ -319,10 +326,31 @@ export async function statWithin(root, rel) {
     const safe = await resolveWithinProjectRoot(joinRel(root, rel), root);
     return fs.stat(safe);
 }
-/** Realpath-contained `fs.readdir` twin (see {@link statWithin}). */
+/**
+ * Realpath-contained `fs.readdir` twin (see {@link statWithin}) that also
+ * `fs.stat`s every FILE entry (size + mtimeMs) — the disk-side half of the
+ * sync engine's stat-diffing (see wal-audit-watch-expand.ts's module doc):
+ * a watch-reported directory is only worth a full content re-read when a
+ * file's stat inside it actually moved, and the `/__fs/readdir` bridge is
+ * the one HTTP round trip cheap enough to do that check on every watch
+ * event without itself re-reading file bytes.
+ */
 export async function readdirWithin(root, rel) {
     const safe = await resolveWithinProjectRoot(joinRel(root, rel), root);
-    return fs.readdir(safe, { withFileTypes: true });
+    const dirents = await fs.readdir(safe, { withFileTypes: true });
+    return Promise.all(dirents.map(async (d) => {
+        if (d.isDirectory())
+            return { name: d.name, isDirectory: true };
+        try {
+            const st = await fs.stat(path.join(safe, d.name));
+            return { name: d.name, isDirectory: false, size: st.size, mtimeMs: st.mtimeMs };
+        }
+        catch {
+            // Entry vanished (or became unreadable) between readdir and stat —
+            // report it stat-less; see this function's doc for why that is safe.
+            return { name: d.name, isDirectory: false };
+        }
+    }));
 }
 /**
  * Raw-byte read twin of {@link readFileBuffer} taking a project-root-relative

package/dist/main/runtime/miniapp-runtime.d.ts

@@ -1,6 +1,6 @@
 /**
- * MiniappRuntime — the stable, host-facing contract surface (foundation.md §3
- * "MiniappRuntime 契约" layer).
+ * MiniappRuntime — the stable, host-facing contract surface documented in
+ * host-migration.md's public-contract section.
  *
  * HAND-WRITTEN, not derived from `WorkbenchContext`. A `Pick`-style projection
  * would drag every nested internal service type (ViewManager,
@@ -18,7 +18,8 @@
  *  - `workspace.openProject` stays writable (no `readonly`) for backward
  *    compat: hosts MAY still gate permissions by reassigning it. The preferred
  *    path is now the declarative `WorkbenchAppConfig.onBeforeOpenProject` hook
- *    (runs before any side effect, throw to veto) — see host-migration.md §7.
+ *    (runs before any side effect, throw to veto) — see host-migration.md's
+ *    `onBeforeOpenProject` hook section.
  *
  * `asMiniappRuntime(ctx)` is an identity return — the contract is a typed
  * VIEW onto the live context, not a snapshot/projection. That is what makes

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

@@ -38,7 +38,7 @@ 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
+     * Connection registry (see foundation.md's teardown-paths section). 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

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

@@ -71,7 +71,7 @@ export function createRenderInspector(options = {}) {
         }
         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
+        // (see foundation.md) when a registry is available; fall back to the
         // bespoke `once('destroyed')` only when omitted (focused unit tests).
         const forget = () => {
             injected.delete(wc.id);

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

@@ -94,7 +94,7 @@ export interface ServiceHostPoolInitOptions {
     defaultPoolSize: number;
     /** Spec used to warm the initial entries. */
     defaultSpec: ServiceHostSpec;
-    /** Hard ceiling on pooled entries. Clamped to ≤ 4 (doc §3.3). Default 3. */
+    /** Hard ceiling on pooled entries. Clamped to ≤ 4 (see prewarm-webview.md). Default 3. */
     maxPoolSize?: number;
 }
 export declare class ServiceHostPool {
@@ -116,7 +116,7 @@ export declare class ServiceHostPool {
     /**
      * 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
+     * (see prewarm-webview.md's invariants section). Fallback windows carry `entryId === null` and
      * are destroyed (not pooled) on release.
      *
      * A spec change (different `preloadPath`) tears down all *pooled* entries and
@@ -144,7 +144,7 @@ export declare class ServiceHostPool {
     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 beyond the target are disposed OLDEST-FIRST (see prewarm-webview.md); in-use
      * entries are untouched. Does not warm new entries up (use `init` / refill).
      */
     resize(target: number): void;
@@ -170,7 +170,7 @@ export declare class ServiceHostPool {
     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
+     * (see prewarm-webview.md's state-machine and reset-ordering sections): 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.
      */

package/dist/main/services/service-host-pool/pool.js

@@ -1,9 +1,9 @@
 import { BrowserWindow } from 'electron';
 /** Blank placeholder URL loaded while warming / after reset. */
 const BLANK_URL = 'about:blank';
-/** Hard ceiling on pool size regardless of requested size (doc §3.3). */
+/** Hard ceiling on pool size regardless of requested size (see prewarm-webview.md). */
 const HARD_MAX_POOL_SIZE = 4;
-/** Storage buckets cleared on every release (doc §3.4 "必须" rows). */
+/** Storage buckets cleared on every release (see prewarm-webview.md's reset checklist). */
 const RESET_STORAGES = [
     'cookies',
     'localstorage',
@@ -37,7 +37,7 @@ export class ServiceHostPool {
     /**
      * 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
+     * (see prewarm-webview.md's invariants section). Fallback windows carry `entryId === null` and
      * are destroyed (not pooled) on release.
      *
      * A spec change (different `preloadPath`) tears down all *pooled* entries and
@@ -129,7 +129,7 @@ export class ServiceHostPool {
     }
     /**
      * 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 beyond the target are disposed OLDEST-FIRST (see prewarm-webview.md); in-use
      * entries are untouched. Does not warm new entries up (use `init` / refill).
      */
     resize(target) {
@@ -275,7 +275,7 @@ export class ServiceHostPool {
     }
     /**
      * 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
+     * (see prewarm-webview.md's state-machine and reset-ordering sections): 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.
      */

package/dist/main/services/settings/index.d.ts

@@ -10,7 +10,13 @@ export interface WorkbenchSettings {
     };
     compile: {
         /** Watch project files and auto-recompile on change. */
-        watch: boolean;
+        autoBuild: boolean;
+    };
+    preview: {
+        /** Reload the simulator once a watcher-triggered rebuild lands. Independent
+         * of `compile.autoBuild`: "auto-compile on save, reload manually" is valid
+         * and preserves the running page stack / form state across a save. */
+        autoReload: boolean;
     };
     theme: ThemeSource;
     /**

package/dist/main/services/settings/index.js

@@ -12,7 +12,10 @@ const DEFAULTS = {
         port: 7789,
     },
     compile: {
-        watch: true,
+        autoBuild: true,
+    },
+    preview: {
+        autoReload: true,
     },
     theme: 'system',
     lastCreateBaseDir: null,
@@ -20,6 +23,13 @@ const DEFAULTS = {
 function getSettingsFile() {
     return path.join(app.getPath('userData'), 'dimina-workbench-settings.json');
 }
+/** Accept `value` only when it is a real boolean, else `fallback`. A bare `??`
+ * chain guards only null/undefined, so a hand-edited or corrupt config with a
+ * stringy `"false"` would pass through and read as truthy downstream — silently
+ * keeping a toggle ON when the user meant OFF. */
+function pickBool(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
 export function loadWorkbenchSettings() {
     try {
         const data = JSON.parse(fs.readFileSync(getSettingsFile(), 'utf-8'));
@@ -36,7 +46,16 @@ export function loadWorkbenchSettings() {
                 port: data.mcp?.port ?? DEFAULTS.mcp.port,
             },
             compile: {
-                watch: data.compile?.watch ?? DEFAULTS.compile.watch,
+                // Legacy files persisted a single `compile.watch`; the new schema
+                // splits it into `compile.autoBuild` (recompile on save) and
+                // `preview.autoReload` (reload the simulator afterwards). Prefer the new
+                // key, fall back to the legacy one so an old settings file keeps its
+                // "auto-compile" choice; `preview.autoReload` defaults to true (the old
+                // always-reload behavior) when the file predates the split.
+                autoBuild: pickBool(data.compile?.autoBuild, pickBool(data.compile?.watch, DEFAULTS.compile.autoBuild)),
+            },
+            preview: {
+                autoReload: pickBool(data.preview?.autoReload, DEFAULTS.preview.autoReload),
             },
             theme,
             lastCreateBaseDir: typeof data.lastCreateBaseDir === 'string'
@@ -50,6 +69,7 @@ export function loadWorkbenchSettings() {
             cdp: { ...DEFAULTS.cdp },
             mcp: { ...DEFAULTS.mcp },
             compile: { ...DEFAULTS.compile },
+            preview: { ...DEFAULTS.preview },
         };
     }
 }

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

@@ -2,7 +2,7 @@
  * Main-process disk reader/writer backing `difile://_store/*` and
  * `difile://<usr-rel>` URLs.
  *
- * Spec: `packages/devtools/docs/file-system.md` §6 P1-1 / P1-3.
+ * Spec: `packages/devtools/docs/file-system.md`.
  *
  *   - `readDiskFile(realPath, opts?)`: read a (possibly ranged) slice of a
  *     file inside the USER_DATA_PATH sandbox. Returns `bytes` plus the

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

@@ -2,7 +2,7 @@
  * Main-process disk reader/writer backing `difile://_store/*` and
  * `difile://<usr-rel>` URLs.
  *
- * Spec: `packages/devtools/docs/file-system.md` §6 P1-1 / P1-3.
+ * Spec: `packages/devtools/docs/file-system.md`.
  *
  *   - `readDiskFile(realPath, opts?)`: read a (possibly ranged) slice of a
  *     file inside the USER_DATA_PATH sandbox. Returns `bytes` plus the

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

@@ -1,7 +1,7 @@
 /**
  * Main-process `simulator:fs:*` IPC channel handlers.
  *
- * Spec: `packages/devtools/docs/file-system.md` §4.4, §6 P1-7.
+ * Spec: `packages/devtools/docs/file-system.md`.
  *
  * Each handler is the pure function that backs one IPC channel:
  *

package/dist/main/services/simulator-temp-files/fs-channels.js

@@ -1,7 +1,7 @@
 /**
  * Main-process `simulator:fs:*` IPC channel handlers.
  *
- * Spec: `packages/devtools/docs/file-system.md` §4.4, §6 P1-7.
+ * Spec: `packages/devtools/docs/file-system.md`.
  *
  * Each handler is the pure function that backs one IPC channel:
  *

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

@@ -1,7 +1,7 @@
 /**
  * Pure dispatcher for `difile://` URL requests.
  *
- * Spec: `packages/devtools/docs/file-system.md` §4.3.
+ * Spec: `packages/devtools/docs/file-system.md`.
  *
  * The shipping implementation in `index.ts` registers a thin
  * `simSession.protocol.handle('difile')` wrapper that delegates here; the race

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

@@ -1,7 +1,7 @@
 /**
  * Pure dispatcher for `difile://` URL requests.
  *
- * Spec: `packages/devtools/docs/file-system.md` §4.3.
+ * Spec: `packages/devtools/docs/file-system.md`.
  *
  * The shipping implementation in `index.ts` registers a thin
  * `simSession.protocol.handle('difile')` wrapper that delegates here; the race

package/dist/main/services/workbench-coi-server.js

@@ -206,8 +206,15 @@ async function fsReaddir(ctx) {
     // every level: the workbench mirror and the WAL ledger seed walk whatever
     // this returns, so listing them would pull entire dependency trees into the
     // editor memfs and the OPFS ledger. Same-named FILES stay visible.
-    const visible = entries.filter((e) => !(e.isDirectory() && SKIP_DIRS.has(e.name)));
-    jsonRes(ctx.res, 200, visible.map((e) => [e.name, e.isDirectory() ? 2 : 1]));
+    const visible = entries.filter((e) => !(e.isDirectory && SKIP_DIRS.has(e.name)));
+    // Wire shape: `[name, type]` for a directory, `[name, type, size, mtimeMs]`
+    // for a file — the sync engine's watch-batch stat-diffing (workbench's
+    // wal-audit-watch-expand.ts) needs size+mtimeMs to tell a stat-unchanged
+    // survivor from an actually-modified file without re-reading its content.
+    // `size`/`mtimeMs` are simply absent (not `null`) for a stat-less entry
+    // (readdirWithin's readdir/stat race) — the client side then always
+    // treats it as changed.
+    jsonRes(ctx.res, 200, visible.map((e) => (e.isDirectory ? [e.name, 2] : [e.name, 1, e.size, e.mtimeMs])));
 }
 async function fsRead(ctx) {
     const buf = await readFileBufferWithin(ctx.projectRoot, ctx.rel);