miaoda-expo-devkit 0.1.1-beta.99 → 0.1.1-dev.development-build.2

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

@@ -0,0 +1,712 @@
+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)=>{
+     }
+     // 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 @@
++"use strict";
++Object.defineProperty(exports, "__esModule", {
++    value: true
++});
++Object.defineProperty(exports, "createAiErrorCollector", {
++    enumerable: true,
++    get: function() {
++        return createAiErrorCollector;
++    }
++});
++const fs = require("fs");
++const os = require("os");
++const path = require("path");
++
++const MAX_VALUE_DEPTH = 4;
++const MAX_STRING_LENGTH = 20000;
++
++function isEnabled() {
++    return process.env.EXPO_AI_ERROR_COLLECTOR === '1';
++}
++
++function getOutputPath(projectRoot) {
++    const configured = process.env.EXPO_AI_ERROR_FILE;
++    if (!configured) return path.join(projectRoot, 'node_modules', '.miaoda-expo', 'ai-error.json');
++    return path.isAbsolute(configured) ? configured : path.resolve(projectRoot, configured);
++}
++
++function toSerializable(value, depth = 0, seen = new Set()) {
++    if (value == null || typeof value === 'boolean' || typeof value === 'number') return value;
++    if (typeof value === 'string') return value.length > MAX_STRING_LENGTH ? value.slice(0, MAX_STRING_LENGTH) + '...[truncated]' : value;
++    if (depth >= MAX_VALUE_DEPTH) return '[truncated]';
++    if (typeof value === 'function' || typeof value === 'symbol') return String(value);
++    if (seen.has(value)) return '[circular]';
++    seen.add(value);
++    if (value instanceof Error) {
++        const error = {
++            name: value.name,
++            message: value.message,
++            stack: value.stack
++        };
++        for (const key of Object.keys(value)) error[key] = toSerializable(value[key], depth + 1, seen);
++        seen.delete(value);
++        return error;
++    }
++    if (Array.isArray(value)) {
++        const result = value.map((item)=>toSerializable(item, depth + 1, seen));
++        seen.delete(value);
++        return result;
++    }
++    if (typeof value === 'object') {
++        const result = {};
++        for (const key of Object.keys(value)) result[key] = toSerializable(value[key], depth + 1, seen);
++        seen.delete(value);
++        return result;
++    }
++    return String(value);
++}
++
++function normalizeError(error, projectRoot, buildID) {
++    const raw = error && typeof error === 'object' ? error : {
++        message: String(error ?? 'Metro bundling failed')
++    };
++    const message = String(raw.message ?? raw.reason ?? error ?? 'Metro bundling failed');
++    const record = {
++        schemaVersion: 1,
++        id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
++        timestamp: new Date().toISOString(),
++        source: 'metro',
++        eventType: 'bundling_error',
++        buildID: buildID ?? undefined,
++        projectRoot,
++        type: String(raw.type ?? raw.name ?? 'MetroError'),
++        name: raw.name == null ? undefined : String(raw.name),
++        message,
++        filename: raw.filename == null ? undefined : String(raw.filename),
++        lineNumber: typeof raw.lineNumber === 'number' ? raw.lineNumber : undefined,
++        column: typeof raw.column === 'number' ? raw.column : undefined,
++        errors: Array.isArray(raw.errors) ? toSerializable(raw.errors) : [],
++        stack: raw.stack == null ? undefined : String(raw.stack),
++        cause: raw.cause == null ? undefined : toSerializable(raw.cause)
++    };
++    const extra = {};
++    for (const key of Object.keys(raw)) {
++        if (!['type', 'name', 'message', 'filename', 'lineNumber', 'column', 'errors', 'stack', 'cause'].includes(key)) {
++            extra[key] = toSerializable(raw[key]);
++        }
++    }
++    if (Object.keys(extra).length) record.extra = extra;
++    return omitUndefined(record);
++}
++
++function omitUndefined(value) {
++    if (!value || typeof value !== 'object') return value;
++    if (Array.isArray(value)) return value.map(omitUndefined);
++    const result = {};
++    for (const [key, item] of Object.entries(value)) {
++        if (item !== undefined) result[key] = omitUndefined(item);
++    }
++    return result;
++}
++
++function createAiErrorCollector(projectRoot) {
++    if (!isEnabled()) return null;
++    const outputFile = getOutputPath(projectRoot);
++    let activeBuildID = null;
++    let lastFailedBuildID = null;
++    let activeHmrChangeID = null;
++    let state = {
++        schemaVersion: 1,
++        status: 'compiling',
++        buildID: null,
++        updatedAt: new Date().toISOString(),
++        error: null
++    };
++    let warned = false;
++    const publish = (nextState)=>{
++        state = omitUndefined({ ...nextState, updatedAt: new Date().toISOString() });
++        let temporaryFile;
++        try {
++            fs.mkdirSync(path.dirname(outputFile), { recursive: true });
++            temporaryFile = `${outputFile}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
++            fs.writeFileSync(temporaryFile, JSON.stringify(state, null, 2) + os.EOL, 'utf8');
++            fs.renameSync(temporaryFile, outputFile);
++        } catch (error) {
++            try {
++                if (temporaryFile) fs.rmSync(temporaryFile, { force: true });
++            } catch {}
++            if (!warned) {
++                warned = true;
++                console.warn(`[expo-ai-error] Could not write ${outputFile}: ${error.message}`);
++            }
++        }
++    };
++    const isCurrentBuild = (buildID, allowMissing = false)=>buildID == null ? allowMissing || activeBuildID == null : activeBuildID == null || buildID === activeBuildID;
++    return {
++        getState() {
++            return state;
++        },
++        handleMetroEvent(event) {
++            if (!event || typeof event !== 'object') return;
++            const type = event.type;
++            const buildID = event.buildID ?? event.bundleDetails?.buildID ?? null;
++            if (type === 'hmr_update_started') {
++                activeHmrChangeID = typeof event.changeID === 'string' ? event.changeID : null;
++                lastFailedBuildID = null;
++                publish({
++                    schemaVersion: 1,
++                    status: 'compiling',
++                    buildID: activeBuildID,
++                    error: null
++                });
++                return;
++            }
++            if (type === 'hmr_update_failed') {
++                if (activeHmrChangeID == null || event.changeID !== activeHmrChangeID) return;
++                publish({
++                    schemaVersion: 1,
++                    status: 'failed',
++                    buildID: activeBuildID,
++                    error: normalizeError(event.error, projectRoot, activeBuildID)
++                });
++                return;
++            }
++            if (type === 'hmr_update_done') {
++                if (activeHmrChangeID == null || event.changeID !== activeHmrChangeID) return;
++                activeHmrChangeID = null;
++                publish({
++                    schemaVersion: 1,
++                    status: 'succeeded',
++                    buildID: activeBuildID,
++                    error: null
++                });
++                return;
++            }
++            if (type === 'bundle_build_started') {
++                activeBuildID = buildID;
++                activeHmrChangeID = null;
++                lastFailedBuildID = null;
++                publish({ schemaVersion: 1, status: 'compiling', buildID, error: null });
++                return;
++            }
++            if (type === 'bundle_build_failed') {
++                if (!isCurrentBuild(buildID)) return;
++                lastFailedBuildID = buildID ?? activeBuildID;
++                publish({
++                    schemaVersion: 1,
++                    status: 'failed',
++                    buildID: lastFailedBuildID,
++                    error: normalizeError(event.error ?? { type: 'MetroBundleError', message: 'Metro bundling failed' }, projectRoot, lastFailedBuildID)
++                });
++                return;
++            }
++            if (type === 'bundling_error') {
++                const isHmrError = event.isHmr === true;
++                if (isHmrError && activeHmrChangeID != null && event.changeID !== activeHmrChangeID) return;
++                const errorBuildID = isHmrError ? activeBuildID : buildID ?? lastFailedBuildID ?? activeBuildID;
++                if (!isCurrentBuild(errorBuildID, true)) return;
++                if (isHmrError) {
++                    // HMR 错误不携带 Metro build ID，保留变更标识以匹配后续恢复事件。
++                    activeHmrChangeID = event.changeID ?? activeHmrChangeID;
++                }
++                lastFailedBuildID = errorBuildID;
++
++                publish({
++                    schemaVersion: 1,
++                    status: 'failed',
++                    buildID: errorBuildID,
++                    error: normalizeError(event.error, projectRoot, errorBuildID)
++                });
++                return;
++            }
++            if (type === 'bundle_build_done') {
++                if (!isCurrentBuild(buildID)) return;
++                activeHmrChangeID = null;
++                lastFailedBuildID = null;
++                publish({ schemaVersion: 1, status: 'succeeded', buildID: buildID ?? activeBuildID, error: null });
++            }
++        }
++    };
++}
++
++//# sourceMappingURL=aiErrorCollector.js.map
+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,326 @@
++"use strict";
++
++// 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';
++const ROUTES = new Map([
++  ['/innerapi/v1/sourcecode/__hmr_off', 'pause'],
++  ['/innerapi/v1/sourcecode/__hmr_on', 'resume'],
++  ['/innerapi/v1/sourcecode/__hmr_reload', 'reload'],
++  ['/innerapi/v1/sourcecode/__hmr_status', 'status'],
++]);
++
++function attachMiaodaHmrControl({hmrServer: hmr, metro, middleware, stateFile, timeout = 5000}) {
++  let paused = false;
++  let reloadPending = false;
++  let stateVersion = 0;
++  let lastMode = null;
++  // 一次编辑批次可能跨越 Metro 重启：状态文件让新进程恢复暂停状态，
++  // 继续闸门重连上来的客户端。
++  if (stateFile && fs.existsSync(stateFile)) {
++    try {
++      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
++      paused = state.paused === true;
++      reloadPending = state.reloadPending === true;
++      stateVersion = Number.isInteger(state.stateVersion) ? state.stateVersion : 0;
++      lastMode = typeof state.lastMode === 'string' ? state.lastMode : null;
++    } catch {
++      // 损坏的状态文件绝不能放行一个未完成的编辑批次。
++      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();
++  const registrations = new Set();
++  let serial = Promise.resolve();
++  let controlId = 0;
++  let restoring = null;
++
++  // 崩溃安全的原子写：临时文件 + rename。调用方依赖「持久化状态绝不比
++  // 已告知客户端的内容更新」这一不变量（见 run()）。
++  function persist() {
++    if (!stateFile) return;
++    fs.mkdirSync(path.dirname(stateFile), {recursive: true});
++    const temp = `${stateFile}.${process.pid}.tmp`;
++    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}));
++  }
++  function transition(mode) {
++    stateVersion += 1;
++    lastMode = mode;
++  }
++  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;
++    let resolve;
++    const promise = new Promise(done => { resolve = done; });
++    info.ack = {id, promise, resolve};
++    control(info, 'pause', {id});
++  }
++  function fail(status, message) {
++    const error = new Error(message);
++    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.');
++    }
++    for (const info of clients.values()) pauseClient(info);
++    let timer;
++    try {
++      await Promise.race([
++        Promise.all([...clients.values()].filter(info => info.ack).map(info => info.ack.promise)),
++        new Promise((_, reject) => {
++          timer = setTimeout(() => {
++            const error = new Error('Timed out waiting for HMR pause acknowledgement; HMR remains paused.');
++            error.status = 504;
++            reject(error);
++          }, timeout);
++        }),
++      ]);
++    } finally { clearTimeout(timer); }
++  }
++
++  // 立即闸门输出，包括 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};
++    const client = await connect(url, message => {
++      const type = JSON.parse(String(message)).type;
++      if (paused && ['update-start', 'update', 'update-done', 'error'].includes(type)) {
++        info.buffer.push(message);
++      } else send(message);
++    });
++    clients.set(client, info);
++    return client;
++  };
++  const onMessage = hmr.onClientMessage.bind(hmr);
++  hmr.onClientMessage = async (client, message, send) => {
++    let data;
++    try { data = JSON.parse(String(message)); } catch { return onMessage(client, message, send); }
++    const info = clients.get(client);
++    if (data?.type === 'miaoda-hmr-ack' && info) {
++      if (data.version === 1 && data.id === info.ack?.id) info.ack.resolve();
++      return;
++    }
++    if (data?.type === 'register-entrypoints' && info) {
++      // 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');
++    }
++    // 注册错误与图更新一样走受控发送器。
++    // 跟踪注册任务，resume 才能先等新连入客户端的初始图构建完成，再计算最终增量。
++    const task = onMessage(client, message, client.sendFn);
++    if (data?.type !== 'register-entrypoints') return task;
++    registrations.add(task);
++    try { return await task; } finally { registrations.delete(task); }
++  };
++  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);
++    results.set(args[0], result);
++    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 () => {
++      // 保持 DeltaCalculator 的累积不变。绝不丢弃已构建的 revision。
++      if (paused && !force) return;
++      await handle(group, options, event);
++    });
++    groupTasks.set(group, task);
++    return task;
++  }
++  hmr._handleFileChange = (group, options, event) => enqueue(group, options, event);
++
++  async function run(action) {
++    if (action === 'pause') {
++      paused = true;
++      transition('paused');
++      persist();
++      await awaitPaused();
++      return {status: 0, paused, mode: 'paused'};
++    }
++    // 批次中途请求的 reload 会被推迟：暂停的意义就是不让中间态代码执行，
++    // 而 reload 加载的恰恰就是这些中间态。
++    if (action === 'reload' && paused) {
++      reloadPending = true;
++      transition('reload-deferred');
++      persist();
++      return {...status(), mode: 'reload-deferred'};
++    }
++    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');
++    persist();
++    await awaitPaused();
++    let release;
++    restoring = new Promise(done => { release = done; });
++    try {
++      await Promise.all([...registrations]);
++      const graph = await metro.getBundler().getBundler().getDependencyGraph();
++      const fileMap = graph.getWatcher();
++      if (typeof fileMap.miaodaFlushChanges !== 'function') {
++        fail(503, 'Metro file-map barrier patch is missing; HMR remains paused.');
++      }
++      // 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.');
++      }
++      const reload = reloadPending || errors.some(result => staleGraph(result.body)) || [...clients.values()].some(info => info.buffer.some(message => {
++        const data = JSON.parse(String(message));
++        return data.type === 'error' && staleGraph(data.body);
++      }));
++      // 先持久化再放行客户端。如果进程在放行与持久化之间崩溃，重启后会读到
++      // 陈旧的 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 {
++          for (const message of info.buffer) info.send(message);
++          control(info, 'resume');
++        }
++        info.buffer = [];
++        info.ack = null;
++      }
++      return {...status(), mode: reload ? 'reload' : 'fast-refresh', clients: clients.size};
++    } finally {
++      restoring = null;
++      release();
++    }
++  }
++  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') {
++        res.statusCode = 405;
++        res.setHeader('Allow', 'GET');
++        return res.end();
++      }
++      res.statusCode = 200;
++      res.setHeader('Cache-Control', 'no-store');
++      res.setHeader('Content-Type', 'application/json');
++      return res.end(JSON.stringify(status()));
++    }
++    if (req.method !== 'POST') {
++      res.statusCode = 405;
++      res.setHeader('Allow', 'POST');
++      return res.end();
++    }
++    // 控制操作串行化：并发调用方的 pause 与 resume 一个接一个执行，绝不交错。
++    const task = serial.catch(() => {}).then(() => run(action));
++    serial = task;
++    task.then(body => {
++      res.statusCode = body.mode === 'reload-deferred' ? 202 : 200;
++      res.setHeader('Content-Type', 'application/json');
++      res.end(JSON.stringify(body));
++    }, error => {
++      res.statusCode = error.status || 503;
++      res.setHeader('Content-Type', 'application/json');
++      res.end(JSON.stringify({status: 1, paused, msg: error.message}));
++    });
++  };
++  // Metro 自带兜底 middleware：append 会让这些路由永远不可达。
++  middleware.use(handler);
++  middleware.stack.unshift(middleware.stack.pop());
++  return {run: action => {
++    const task = serial.catch(() => {}).then(() => run(action));
++    serial = task;
++    return task;
++  }};
++}
++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