miaoda-expo-devkit 0.1.1-dev.development-build.1 → 0.1.1-dev.development-build.2

package/pnpm-patches/@expo__cli@55.0.16-55.0.22.patch

@@ -1,118 +1,34 @@
-diff --git a/build/src/start/server/metro/instantiateMetro.js b/build/src/start/server/metro/instantiateMetro.js
---- a/build/src/start/server/metro/instantiateMetro.js
-+++ b/build/src/start/server/metro/instantiateMetro.js
-@@ -90,6 +90,8 @@
- const _attachAtlas = require("./debugging/attachAtlas");
- const _createDebugMiddleware = require("./debugging/createDebugMiddleware");
- const _createMetroMiddleware = require("./dev-server/createMetroMiddleware");
-+const _aiErrorCollector = require("./aiErrorCollector");
-+const _miaodaHmrControl = require("./miaodaHmrControl");
- const _runServerfork = require("./runServer-fork");
- const _withMetroMultiPlatform = require("./withMetroMultiPlatform");
- const _events = require("../../../events");
-@@ -273,6 +275,7 @@
-     const { middleware, messagesSocket, eventsSocket, websocketEndpoints } = (0, _createMetroMiddleware.createMetroMiddleware)(metroConfig, {
-         getMetroBundler
-     });
-+    const aiErrorCollector = !isExporting ? (0, _aiErrorCollector.createAiErrorCollector)(projectRoot) : null;
-     // Get local URL to Metro bundler server (typically configured as 127.0.0.1:8081)
-     const serverBaseUrl = metroBundler.getUrlCreator().constructUrl({
-         scheme: 'http',
-@@ -347,7 +350,10 @@
-             }
-         }), fileBuffer);
-     };
--    setEventReporter(eventsSocket.reportMetroEvent);
-+    setEventReporter((event)=>{
-+        eventsSocket.reportMetroEvent(event);
-+        aiErrorCollector == null ? void 0 : aiErrorCollector.handleMetroEvent(event);
-+    });
-     // This function ensures that modules in source maps are sorted in the same
-     // order as in a plain JS bundle.
-     metro._getSortedModules = function(graph) {
-@@ -381,13 +387,24 @@
-             // Fork of https://github.com/facebook/metro/blob/3b3e0aaf725cfa6907bf2c8b5fbc0da352d29efe/packages/metro/src/HmrServer.js#L327-L393
-             // with patch for `_createModuleId`.
-             const logger = !options.isInitialUpdate ? changeEvent == null ? void 0 : changeEvent.logger : null;
-+            const hmrChangeID = `${changeEvent == null ? 'initial' : changeEvent.changeId}:${group.revisionId}`;
-+            aiErrorCollector == null ? void 0 : aiErrorCollector.handleMetroEvent({
-+                type: 'hmr_update_started',
-+                changeID: hmrChangeID
-+            });
-             try {
-                 var _revision_graph_transformOptions_customTransformOptions;
-                 const revPromise = this._bundler.getRevision(group.revisionId);
-                 if (!revPromise) {
-+                    const revisionError = new (_RevisionNotFoundError()).default(group.revisionId);
-+                    aiErrorCollector == null ? void 0 : aiErrorCollector.handleMetroEvent({
-+                        type: 'hmr_update_failed',
-+                        changeID: hmrChangeID,
-+                        error: revisionError
-+                    });
-                     return {
-                         type: 'error',
--                        body: (0, _formatBundlingError().default)(new (_RevisionNotFoundError()).default(group.revisionId))
-+                        body: (0, _formatBundlingError().default)(revisionError)
-                     };
-                 }
-                 logger == null ? void 0 : logger.point('updateGraph_start');
-@@ -418,6 +435,10 @@
-                     serverRoot: this._config.server.unstable_serverRoot ?? this._config.projectRoot
-                 });
-                 logger == null ? void 0 : logger.point('serialize_end');
-+                aiErrorCollector == null ? void 0 : aiErrorCollector.handleMetroEvent({
-+                    type: 'hmr_update_done',
-+                    changeID: hmrChangeID
-+                });
-                 return {
-                     type: 'update',
-                     body: {
-@@ -430,7 +451,9 @@
-                 const formattedError = (0, _formatBundlingError().default)(error);
-                 this._config.reporter.update({
-                     type: 'bundling_error',
--                    error
-+                    error,
-+                    isHmr: true,
-+                    changeID: hmrChangeID
-                 });
-                 return {
-                     type: 'error',
-@@ -438,6 +461,11 @@
-                 };
-             }
-         };
-+    }
-+    if (hmrServer && process.env.EXPO_MIAODA_HMR_CONTROL === '1') {
-+        hmrServer._miaodaAttach({
-+            stateFile: process.env.EXPO_MIAODA_HMR_STATE_FILE
-+        });
+diff --git a/build/src/install/index.js b/build/src/install/index.js
+index a374fca..d1229c1 100644
+--- a/build/src/install/index.js
++++ b/build/src/install/index.js
+@@ -55,10 +55,20 @@ const expoInstall = async (argv)=>{
      }
-     return {
-         metro,
-diff --git a/build/src/start/server/metro/runServer-fork.js b/build/src/start/server/metro/runServer-fork.js
---- a/build/src/start/server/metro/runServer-fork.js
-+++ b/build/src/start/server/metro/runServer-fork.js
-@@ -63,6 +63,7 @@
-     return data;
- }
- const _log = require("../../../log");
-+const _miaodaHmrControl = require("./miaodaHmrControl");
- function _interop_require_default(obj) {
-     return obj && obj.__esModule ? obj : {
-         default: obj
-@@ -150,6 +151,9 @@
-                 onReady(httpServer);
-             }
-             const hmrServer = new (_HmrServer()).default(metroServer.getBundler(), metroServer.getCreateModuleId(), config);
-+            hmrServer._miaodaAttach = (options = {}) => (0, _miaodaHmrControl.attachMiaodaHmrControl)({
-+                hmrServer, metro: metroServer, middleware: serverApp, ...options
-+            });
-             Object.assign(websocketEndpoints, {
-                 '/hot': (0, _createWebsocketServer().default)({
-                     websocketServer: hmrServer
+     // Load modules after the help prompt so `npx expo install -h` shows as fast as possible.
+     const { installAsync } = require('./installAsync');
+-    const { logCmdError } = require('../utils/errors');
++    const { logCmdError, SilentError } = require('../utils/errors');
+     const { resolveArgsAsync } = require('./resolveOptions');
+     const { variadic, options, extras } = await resolveArgsAsync(process.argv.slice(3)).catch(logCmdError);
+-    return installAsync(variadic, options, extras).catch(logCmdError);
++    return installAsync(variadic, options, extras).catch((error)=>{
++        if (
++            error &&
++            typeof error === 'object' &&
++            typeof error.status === 'number' &&
++            Array.isArray(error.output)
++        ) {
++            return logCmdError(new SilentError(error));
++        }
++        return logCmdError(error);
++    });
+ };
+ 
+ //# sourceMappingURL=index.js.map
+
 diff --git a/build/src/start/server/metro/aiErrorCollector.js b/build/src/start/server/metro/aiErrorCollector.js
 new file mode 100644
+index 0000000..febccaf
 --- /dev/null
 +++ b/build/src/start/server/metro/aiErrorCollector.js
 @@ -0,0 +1,222 @@
@@ -338,38 +254,135 @@ new file mode 100644
 +}
 +
 +//# sourceMappingURL=aiErrorCollector.js.map
-diff --git a/build/src/install/index.js b/build/src/install/index.js
---- a/build/src/install/index.js
-+++ b/build/src/install/index.js
-@@ -55,8 +55,18 @@
-     }
-     // Load modules after the help prompt so `npx expo install -h` shows as fast as possible.
-     const { installAsync } = require('./installAsync');
--    const { logCmdError } = require('../utils/errors');
-+    const { logCmdError, SilentError } = require('../utils/errors');
-     const { resolveArgsAsync } = require('./resolveOptions');
-     const { variadic, options, extras } = await resolveArgsAsync(process.argv.slice(3)).catch(logCmdError);
--    return installAsync(variadic, options, extras).catch(logCmdError);
-+    return installAsync(variadic, options, extras).catch((error)=>{
-+        if (
-+            error &&
-+            typeof error === 'object' &&
-+            typeof error.status === 'number' &&
-+            Array.isArray(error.output)
-+        ) {
-+            return logCmdError(new SilentError(error));
-+        }
-+        return logCmdError(error);
+diff --git a/build/src/start/server/metro/instantiateMetro.js b/build/src/start/server/metro/instantiateMetro.js
+index bd1d604..02db474 100644
+--- a/build/src/start/server/metro/instantiateMetro.js
++++ b/build/src/start/server/metro/instantiateMetro.js
+@@ -90,6 +90,8 @@ const _MetroTerminalReporter = require("./MetroTerminalReporter");
+ const _attachAtlas = require("./debugging/attachAtlas");
+ const _createDebugMiddleware = require("./debugging/createDebugMiddleware");
+ const _createMetroMiddleware = require("./dev-server/createMetroMiddleware");
++const _aiErrorCollector = require("./aiErrorCollector");
++const _miaodaHmrControl = require("./miaodaHmrControl");
+ const _runServerfork = require("./runServer-fork");
+ const _withMetroMultiPlatform = require("./withMetroMultiPlatform");
+ const _events = require("../../../events");
+@@ -273,6 +275,7 @@ async function instantiateMetroAsync(metroBundler, options, { isExporting, exp =
+     const { middleware, messagesSocket, eventsSocket, websocketEndpoints } = (0, _createMetroMiddleware.createMetroMiddleware)(metroConfig, {
+         getMetroBundler
+     });
++    const aiErrorCollector = !isExporting ? (0, _aiErrorCollector.createAiErrorCollector)(projectRoot) : null;
+     // Get local URL to Metro bundler server (typically configured as 127.0.0.1:8081)
+     const serverBaseUrl = metroBundler.getUrlCreator().constructUrl({
+         scheme: 'http',
+@@ -347,7 +350,10 @@ async function instantiateMetroAsync(metroBundler, options, { isExporting, exp =
+             }
+         }), fileBuffer);
+     };
+-    setEventReporter(eventsSocket.reportMetroEvent);
++    setEventReporter((event)=>{
++        eventsSocket.reportMetroEvent(event);
++        aiErrorCollector == null ? void 0 : aiErrorCollector.handleMetroEvent(event);
 +    });
- };
+     // This function ensures that modules in source maps are sorted in the same
+     // order as in a plain JS bundle.
+     metro._getSortedModules = function(graph) {
+@@ -381,13 +387,24 @@ async function instantiateMetroAsync(metroBundler, options, { isExporting, exp =
+             // Fork of https://github.com/facebook/metro/blob/3b3e0aaf725cfa6907bf2c8b5fbc0da352d29efe/packages/metro/src/HmrServer.js#L327-L393
+             // with patch for `_createModuleId`.
+             const logger = !options.isInitialUpdate ? changeEvent == null ? void 0 : changeEvent.logger : null;
++            const hmrChangeID = `${changeEvent == null ? 'initial' : changeEvent.changeId}:${group.revisionId}`;
++            aiErrorCollector == null ? void 0 : aiErrorCollector.handleMetroEvent({
++                type: 'hmr_update_started',
++                changeID: hmrChangeID
++            });
+             try {
+                 var _revision_graph_transformOptions_customTransformOptions;
+                 const revPromise = this._bundler.getRevision(group.revisionId);
+                 if (!revPromise) {
++                    const revisionError = new (_RevisionNotFoundError()).default(group.revisionId);
++                    aiErrorCollector == null ? void 0 : aiErrorCollector.handleMetroEvent({
++                        type: 'hmr_update_failed',
++                        changeID: hmrChangeID,
++                        error: revisionError
++                    });
+                     return {
+                         type: 'error',
+-                        body: (0, _formatBundlingError().default)(new (_RevisionNotFoundError()).default(group.revisionId))
++                        body: (0, _formatBundlingError().default)(revisionError)
+                     };
+                 }
+                 logger == null ? void 0 : logger.point('updateGraph_start');
+@@ -418,6 +435,10 @@ async function instantiateMetroAsync(metroBundler, options, { isExporting, exp =
+                     serverRoot: this._config.server.unstable_serverRoot ?? this._config.projectRoot
+                 });
+                 logger == null ? void 0 : logger.point('serialize_end');
++                aiErrorCollector == null ? void 0 : aiErrorCollector.handleMetroEvent({
++                    type: 'hmr_update_done',
++                    changeID: hmrChangeID
++                });
+                 return {
+                     type: 'update',
+                     body: {
+@@ -430,7 +451,9 @@ async function instantiateMetroAsync(metroBundler, options, { isExporting, exp =
+                 const formattedError = (0, _formatBundlingError().default)(error);
+                 this._config.reporter.update({
+                     type: 'bundling_error',
+-                    error
++                    error,
++                    isHmr: true,
++                    changeID: hmrChangeID
+                 });
+                 return {
+                     type: 'error',
+@@ -439,6 +462,16 @@ async function instantiateMetroAsync(metroBundler, options, { isExporting, exp =
+             }
+         };
+     }
++    // Miaoda HMR 批量编辑控制的环境变量开关：只有显式设置
++    // EXPO_MIAODA_HMR_CONTROL=1 才挂载控制端点与消息闸门，普通本地开发
++    // 不受影响。stateFile 指定暂停状态的持久化位置，使编辑批次可以跨越
++    // Metro 重启。注意此处位于 Expo 替换 HMR serializer 之后，attach 包装到
++    // 的才是最终生效的 _prepareMessage。
++    if (hmrServer && process.env.EXPO_MIAODA_HMR_CONTROL === '1') {
++        hmrServer._miaodaAttach({
++            stateFile: process.env.EXPO_MIAODA_HMR_STATE_FILE
++        });
++    }
+     return {
+         metro,
+         hmrServer,
 diff --git a/build/src/start/server/metro/miaodaHmrControl.js b/build/src/start/server/metro/miaodaHmrControl.js
 new file mode 100644
+index 0000000..8d5d129
 --- /dev/null
 +++ b/build/src/start/server/metro/miaodaHmrControl.js
-@@ -0,0 +1,258 @@
+@@ -0,0 +1,326 @@
 +"use strict";
 +
-+// SDK 55 / Metro 0.83.3. Attach after Expo replaces the HMR serializer.
++// Miaoda HMR 批量编辑控制，适配 SDK 55 / Metro 0.83.3。
++//
++// Agent 批量改写工程文件期间，本模块暂停已连接 Development Build 的 HMR 通道，
++// 让设备继续运行上一份完好的 JS，而不是执行中间态文件或展示其编译错误。
++// 批次结束后，一次 resume 只应用一份最终增量。
++//
++// 两条传输通道协作：
++//   - 控制消息复用 Metro 已有的 `/hot` WebSocket，以
++//     {type: 'miaoda-hmr-control', version: 1, action} 帧传输（pause / resume /
++//     reload / error）。pause 携带 `id`，客户端在运行时停止应用更新后回复
++//     {type: 'miaoda-hmr-ack', version: 1, id}，因此 pause 成功即意味着
++//     不会再有在途更新落到设备上。
++//   - 客户端每 2 秒轮询 GET __hmr_status，作为 WebSocket 消息丢失时的兜底。
++//     每次状态变化都会递增 `stateVersion`；轮询方若发现一个从未通过 socket
++//     收到的版本号，则执行完整 Bundle reload 而不是 resume，因为此时已无法
++//     证明增量 revision 的连续性。
++//
++// 本模块整体遵循 fail-closed：ack 超时（504）、未协商协议的老客户端（409）、
++// watcher 栅栏缺失或持久化失败（503）、最终编译错误（422）都会让闸门保持
++// 暂停，任何一次调用失败都不会把写了一半的代码放到设备上。
++//
++// 必须在 Expo 替换 HMR serializer 之后再 attach（见 instantiateMetro.js）；
++// 提前包装会包住错误的 _prepareMessage。
 +const fs = require('node:fs');
 +const path = require('node:path');
 +const CONTROL = 'miaoda-hmr-control';
@@ -385,6 +398,8 @@ new file mode 100644
 +  let reloadPending = false;
 +  let stateVersion = 0;
 +  let lastMode = null;
++  // 一次编辑批次可能跨越 Metro 重启：状态文件让新进程恢复暂停状态，
++  // 继续闸门重连上来的客户端。
 +  if (stateFile && fs.existsSync(stateFile)) {
 +    try {
 +      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
@@ -393,10 +408,13 @@ new file mode 100644
 +      stateVersion = Number.isInteger(state.stateVersion) ? state.stateVersion : 0;
 +      lastMode = typeof state.lastMode === 'string' ? state.lastMode : null;
 +    } catch {
-+      // A damaged state file must not release an unfinished edit batch.
++      // 损坏的状态文件绝不能放行一个未完成的编辑批次。
 +      paused = true;
 +    }
 +  }
++  // client -> {send, version, registered, buffer, ack}。`send` 是原始 socket
++  // 写入器；HMR 输出走 onClientConnect 里安装的受控包装。`version` 在客户端
++  // 通过 register-entrypoints 协商控制协议后为 1，未协商的老客户端为 null。
 +  const clients = new Map();
 +  const groupTasks = new WeakMap();
 +  const results = new WeakMap();
@@ -405,6 +423,8 @@ new file mode 100644
 +  let controlId = 0;
 +  let restoring = null;
 +
++  // 崩溃安全的原子写：临时文件 + rename。调用方依赖「持久化状态绝不比
++  // 已告知客户端的内容更新」这一不变量（见 run()）。
 +  function persist() {
 +    if (!stateFile) return;
 +    fs.mkdirSync(path.dirname(stateFile), {recursive: true});
@@ -412,6 +432,8 @@ new file mode 100644
 +    fs.writeFileSync(temp, JSON.stringify({version: 1, paused, reloadPending, stateVersion, lastMode}));
 +    fs.renameSync(temp, stateFile);
 +  }
++  // 控制帧只发给已协商的客户端——未协商的客户端不认识这些帧。
++  // stateVersion 随帧捎带，供轮询兜底检测是否有丢失的帧。
 +  function control(info, action, extra = {}) {
 +    if (info.version === 1) info.send(JSON.stringify({type: CONTROL, version: 1, action, stateVersion, ...extra}));
 +  }
@@ -422,6 +444,8 @@ new file mode 100644
 +  function status() {
 +    return {status: 0, paused, reloadPending, stateVersion, lastMode, protocolVersion: 1};
 +  }
++  // 单客户端暂停握手：客户端必须在运行时停止应用更新后 ack 这个 id，
++  // 以此证明不会再有缓冲的更新落到设备上。
 +  function pauseClient(info) {
 +    if (info.version !== 1 || info.ack) return;
 +    const id = ++controlId;
@@ -435,6 +459,8 @@ new file mode 100644
 +    error.status = status;
 +    throw error;
 +  }
++  // 只有当所有已协商客户端都确认后，暂停才算完成。
++  // Agent 必须等它 resolve 之后才能开始写文件。
 +  async function awaitPaused() {
 +    if ([...clients.values()].some(info => info.registered && info.version !== 1)) {
 +      fail(409, 'Connected client lacks Miaoda HMR protocol v1; update its JS dependencies and reload.');
@@ -455,7 +481,10 @@ new file mode 100644
 +    } finally { clearTimeout(timer); }
 +  }
 +
-+  // Gate output immediately, including updates already compiling when pause arrives.
++  // 立即闸门输出，包括 pause 到达时已在编译中的更新：paused 期间 HMR 帧
++  // （update-start/update/update-done/error）按客户端缓冲而不发送。
++  // 控制帧和日志不受闸门限制；缓冲在 resume 时回放，客户端仍能收到基于
++  // 其最后应用 revision 计算的最终增量。
 +  const connect = hmr.onClientConnect.bind(hmr);
 +  hmr.onClientConnect = async (url, send) => {
 +    const info = {send, version: null, registered: false, buffer: [], ack: null};
@@ -478,14 +507,18 @@ new file mode 100644
 +      return;
 +    }
 +    if (data?.type === 'register-entrypoints' && info) {
-+      // Registration during a resume joins only after that operation has committed.
++      // resume 进行中注册的客户端，绝不能先于 resume 提交状态迁移就看到
++      // 已释放的缓冲。
 +      if (restoring) await restoring;
 +      info.registered = true;
 +      info.version = data.miaodaHmr === 1 ? 1 : null;
++      // 在暂停批次中（重）连入的客户端立即被暂停；连入空闲服务端的客户端
++      // 会收到一条 resume，用来清除上一次会话遗留的本地闸门。
 +      if (paused) pauseClient(info);
 +      else control(info, 'resume');
 +    }
-+    // Use the gated sender for registration errors as well as graph updates.
++    // 注册错误与图更新一样走受控发送器。
++    // 跟踪注册任务，resume 才能先等新连入客户端的初始图构建完成，再计算最终增量。
 +    const task = onMessage(client, message, client.sendFn);
 +    if (data?.type !== 'register-entrypoints') return task;
 +    registrations.add(task);
@@ -493,11 +526,15 @@ new file mode 100644
 +  };
 +  const disconnect = hmr.onClientDisconnect.bind(hmr);
 +  hmr.onClientDisconnect = client => {
++    // 已断开的客户端不可能再应用更新，直接 resolve 它的挂起 ack，
++    // 避免 pause 干等到 504 超时。
 +    clients.get(client)?.ack?.resolve();
 +    clients.delete(client);
 +    return disconnect(client);
 +  };
 +
++  // 记录每个分组的构建结果，resume 据此检查最终编译结果，
++  // 在 fast-refresh、reload 与 422 之间做决策。
 +  const prepare = hmr._prepareMessage.bind(hmr);
 +  hmr._prepareMessage = async (...args) => {
 +    const result = await prepare(...args);
@@ -505,10 +542,13 @@ new file mode 100644
 +    return result;
 +  };
 +  const handle = hmr._handleFileChange.bind(hmr);
++  // 文件变更按分组严格串行处理。paused 时跳过 handler，但这只闸门「投递」：
++  // 各分组的 DeltaCalculator 内部仍在持续累积文件事件，客户端运行时也会合并
++  // disable 期间收到的更新，因此不会丢失任何中间态。
 +  function enqueue(group, options, event, force = false) {
 +    const previous = groupTasks.get(group) || Promise.resolve();
 +    const task = previous.catch(() => {}).then(async () => {
-+      // Leave DeltaCalculator's changes intact. Never drop an already-built revision.
++      // 保持 DeltaCalculator 的累积不变。绝不丢弃已构建的 revision。
 +      if (paused && !force) return;
 +      await handle(group, options, event);
 +    });
@@ -525,6 +565,8 @@ new file mode 100644
 +      await awaitPaused();
 +      return {status: 0, paused, mode: 'paused'};
 +    }
++    // 批次中途请求的 reload 会被推迟：暂停的意义就是不让中间态代码执行，
++    // 而 reload 加载的恰恰就是这些中间态。
 +    if (action === 'reload' && paused) {
 +      reloadPending = true;
 +      transition('reload-deferred');
@@ -533,6 +575,8 @@ new file mode 100644
 +    }
 +    if (action === 'status') return status();
 +    if (action === 'resume' && !paused) return {...status(), mode: 'unchanged'};
++    // resume 与 reload 共用前置的暂停握手：必须先把客户端静默下来再计算
++    // 最终增量，否则仍可能放出一个基于写了一半的目录树编译的更新。
 +    paused = true;
 +    if (action === 'reload') reloadPending = true;
 +    transition(action === 'reload' ? 'reload-requested' : 'paused');
@@ -547,14 +591,22 @@ new file mode 100644
 +      if (typeof fileMap.miaodaFlushChanges !== 'function') {
 +        fail(503, 'Metro file-map barrier patch is missing; HMR remains paused.');
 +      }
-+      // Watcher cookie -> file-map processing queue -> change event -> final graph build.
++      // Agent 通过调用 resume 表示「所有写入已完成」。栅栏让这一点对 Metro
++      // 同样成立：watcher cookie -> file-map 处理队列 -> change 事件，
++      // 保证下面的最终构建一定包含最后写入的字节。
 +      await fileMap.miaodaFlushChanges(timeout);
 +      const groups = [...new Set(hmr._clientGroups.values())];
++      // 每个分组强制构建一次，使最终增量（以及任何编译错误）在放行客户端
++      // 之前就算出来。
 +      await Promise.all(groups.map(group => enqueue(group, {isInitialUpdate: false}, undefined, true)));
 +      const errors = groups.map(group => results.get(group)).filter(result => result?.type === 'error');
++      // 图/revision 丢失不是代码错误：增量链已断，唯一安全的放行方式是
++      // 完整 Bundle reload。
 +      const staleGraph = error => ['GraphNotFoundError', 'RevisionNotFoundError'].includes(error?.type);
 +      const compileErrors = errors.filter(result => !staleGraph(result.body));
 +      if (compileErrors.length) {
++        // 把最终错误告知客户端（设备端可以据此行动），但保持闸门关闭，
++        // 让 Agent 修好代码后重试。
 +        for (const info of clients.values()) control(info, 'error', {error: compileErrors[0].body});
 +        fail(422, 'Final code failed to compile; HMR remains paused. Fix the code and retry __hmr_on.');
 +      }
@@ -562,12 +614,16 @@ new file mode 100644
 +        const data = JSON.parse(String(message));
 +        return data.type === 'error' && staleGraph(data.body);
 +      }));
-+      // Persist before releasing clients. A persistence failure must leave the gate closed.
++      // 先持久化再放行客户端。如果进程在放行与持久化之间崩溃，重启后会读到
++      // 陈旧的 paused 状态，把已经 resume 的客户端再次暂停；因此持久化失败
++      // 必须让闸门保持关闭。
 +      const previousReloadPending = reloadPending;
 +      paused = false;
 +      reloadPending = false;
 +      transition(reload ? 'reload' : 'fast-refresh');
 +      try { persist(); } catch (error) { paused = true; reloadPending = previousReloadPending; throw error; }
++      // 缓冲帧先于 resume 发出：运行时先把它们与最终增量合并，
++      // resume 到达时通道已安静。
 +      for (const info of clients.values()) {
 +        if (reload) control(info, 'reload');
 +        else {
@@ -586,6 +642,8 @@ new file mode 100644
 +  const handler = (req, res, next) => {
 +    const pathname = new URL(req.url, 'http://localhost').pathname.replace(/\/$/, '');
 +    const action = ROUTES.get(pathname);
++    // OPTIONS 直接放行：这些端点服务 native 客户端，native 不强制 CORS，
++    // 而 Web 端按设计不轮询。
 +    if (!action || req.method === 'OPTIONS') return next();
 +    if (action === 'status') {
 +      if (req.method !== 'GET') {
@@ -603,6 +661,7 @@ new file mode 100644
 +      res.setHeader('Allow', 'POST');
 +      return res.end();
 +    }
++    // 控制操作串行化：并发调用方的 pause 与 resume 一个接一个执行，绝不交错。
 +    const task = serial.catch(() => {}).then(() => run(action));
 +    serial = task;
 +    task.then(body => {
@@ -615,7 +674,7 @@ new file mode 100644
 +      res.end(JSON.stringify({status: 1, paused, msg: error.message}));
 +    });
 +  };
-+  // Metro has a catch-all middleware: append would make these routes unreachable.
++  // Metro 自带兜底 middleware：append 会让这些路由永远不可达。
 +  middleware.use(handler);
 +  middleware.stack.unshift(middleware.stack.pop());
 +  return {run: action => {
@@ -625,3 +684,29 @@ new file mode 100644
 +  }};
 +}
 +module.exports = {attachMiaodaHmrControl};
+diff --git a/build/src/start/server/metro/runServer-fork.js b/build/src/start/server/metro/runServer-fork.js
+index 652bee8..a08f26a 100644
+--- a/build/src/start/server/metro/runServer-fork.js
++++ b/build/src/start/server/metro/runServer-fork.js
+@@ -63,6 +63,7 @@ function _url() {
+     return data;
+ }
+ const _log = require("../../../log");
++const _miaodaHmrControl = require("./miaodaHmrControl");
+ function _interop_require_default(obj) {
+     return obj && obj.__esModule ? obj : {
+         default: obj
+@@ -150,6 +151,13 @@ const runServer = async (_metroBundler, config, { hasReducedPerformance = false,
+                 onReady(httpServer);
+             }
+             const hmrServer = new (_HmrServer()).default(metroServer.getBundler(), metroServer.getCreateModuleId(), config);
++            // 挂载 Miaoda HMR 控制的挂点：此处能同时拿到 hmrServer、metroServer
++            // 与 middleware 三元组（attach 三者都需要），但真正的挂载由
++            // instantiateMetro 在环境变量开启时触发，保证 attach 发生在 Expo
++            // 替换 HMR serializer 之后。
++            hmrServer._miaodaAttach = (options = {}) => (0, _miaodaHmrControl.attachMiaodaHmrControl)({
++                hmrServer, metro: metroServer, middleware: serverApp, ...options
++            });
+             Object.assign(websocketEndpoints, {
+                 '/hot': (0, _createWebsocketServer().default)({
+                     websocketServer: hmrServer