@heybox/hb-sdk 0.8.1-alpha.1 → 0.8.1-alpha.11

package/dist/cli-chunks/{dev-CPBPdpyu.cjs → dev-jz2O-8Sf.cjs}

@@ -1,24 +1,25 @@
 'use strict';
 
+var node_crypto = require('node:crypto');
 var fs = require('node:fs');
 var os = require('node:os');
 var path = require('node:path');
 var net = require('node:net');
-var node_crypto = require('node:crypto');
 var promises = require('node:dns/promises');
 var node_http = require('node:http');
 var node_module = require('node:module');
-var context = require('./context-CzFFRcL4.cjs');
-var runtimePermissionEnv = require('./runtime-permission-env-DdQtxdut.cjs');
+var context = require('./context-cpQKdAv9.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-B0s4KP_U.cjs');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-Buner4kE.cjs');
+var index = require('./index-IeNOfmd0.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-DHbw2Xgh.cjs');
+var session = require('./session-CUPzN2aa.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-B-sK-qup.cjs');
-var version = require('./version-TXwWxKvv.cjs');
+var projectVite = require('./project-vite-DLIFCiZD.cjs');
+var version = require('./version-DOBbqU-f.cjs');
+require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 class Locked extends Error {
@@ -183,6 +184,82 @@ async function getPorts(options) {
 	throw new Error('No available ports found');
 }
 
+/**
+ * network.request 诊断日志的纯脱敏工具。
+ *
+ * @remarks
+ * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
+ * modules observability、devtools Browser Dev Host / proxy 共用，并满足 boundary
+ *（devtools 不得直接 import runtime capability modules）。
+ */
+/** 敏感字段名：header / query / body key 共用。 */
+const SENSITIVE_KEY_PATTERN$1 = /(authorization|cookie|password|passwd|secret|token|pkey|private[_-]?key|access[_-]?key|client[_-]?secret|api[_-]?key|apikey|session|jwt|refresh[_-]?token|csrf)/i;
+/**
+ * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
+ */
+function sanitizeNetworkRequestUrl(url) {
+    if (!url) {
+        return url;
+    }
+    try {
+        const parsed = new URL(url);
+        parsed.username = '';
+        parsed.password = '';
+        redactUrlSearchParams(parsed.searchParams);
+        if (parsed.hash && parsed.hash.length > 1) {
+            const hashBody = parsed.hash.slice(1);
+            if (hashBody.includes('=')) {
+                const hashParams = new URLSearchParams(hashBody);
+                if (redactUrlSearchParams(hashParams)) {
+                    parsed.hash = hashParams.toString();
+                }
+            }
+        }
+        return parsed.toString();
+    }
+    catch {
+        return redactSensitivePairsInRawText(url);
+    }
+}
+/**
+ * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
+ */
+function sanitizeDiagnosticMessage(message) {
+    if (!message) {
+        return message;
+    }
+    return message.replace(/https?:\/\/[^\s]+/gi, matched => sanitizeNetworkRequestUrl(matched.replace(/[),.;]+$/g, '')));
+}
+function isSensitiveNetworkKey(key) {
+    return SENSITIVE_KEY_PATTERN$1.test(key.trim());
+}
+function redactUrlSearchParams(params) {
+    let changed = false;
+    for (const key of [...params.keys()]) {
+        if (isSensitiveNetworkKey(key)) {
+            params.set(key, '[redacted]');
+            changed = true;
+        }
+    }
+    return changed;
+}
+function redactSensitivePairsInRawText(text) {
+    return text.replace(/([?&#]|^|[?&])([^=&#\s]+)=([^&#\s]*)/g, (full, prefix, key, value) => {
+        if (!isSensitiveNetworkKey(key)) {
+            return full;
+        }
+        return `${prefix}${key}=[redacted]`;
+    });
+}
+
+const DEVICE_LOG_PATH = '/__hb_sdk__/device-logs';
+const registryKey = Symbol.for('@heybox/hb-sdk/device-logs');
+const registry = globalThis;
+const stores = (registry[registryKey] ??= new Map());
+function getDeviceLogs(appUrl) {
+    return stores.get(Number(new URL(appUrl).port));
+}
+
 /** Dev Shell 读取局域网 Dev Session endpoint 的 query 参数。 */
 const MINI_PROGRAM_DEV_CONTEXT_QUERY_PARAM = 'dev_context_url';
 /** Browser Dev Host 创建和读取 Dev Session 的固定路径。 */
@@ -546,78 +623,100 @@ function readErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 
-/**
- * network.request 诊断日志的纯脱敏工具。
- *
- * @remarks
- * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
- * modules observability、devtools Browser Dev Host / proxy 共用，并满足 boundary
- *（devtools 不得直接 import runtime capability modules）。
- */
-/** 敏感字段名：header / query / body key 共用。 */
-const SENSITIVE_KEY_PATTERN$1 = /(authorization|cookie|password|passwd|secret|token|pkey|private[_-]?key|access[_-]?key|client[_-]?secret|api[_-]?key|apikey|session|jwt|refresh[_-]?token|csrf)/i;
-/**
- * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
- */
-function sanitizeNetworkRequestUrl(url) {
-    if (!url) {
-        return url;
+const PATHNAME_MAX_DECODE_ROUNDS = 4;
+const OFFICIAL_ROOT_DOMAINS = ['xiaoheihe.cn', 'max-c.com', 'debugmode.cn', 'maxjia.com'];
+const DENIED_REQUEST_HEADERS = new Set([
+    'connection',
+    'content-length',
+    'host',
+    'keep-alive',
+    'proxy-connection',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+/** 任意 origin 都不得通过公开 network.request 访问的 Runtime 私有路径。 */
+const PUBLIC_NETWORK_PROTECTED_PATH_PREFIXES = ['/user_miniprogram/runtime/auth', '/user_miniprogram/openapi/v1'];
+/** 官方 origin 上会签发、恢复或校验账号 credential 的私有路径。 */
+const PUBLIC_NETWORK_OFFICIAL_ACCOUNT_SENSITIVE_PATH_PREFIXES = [
+    '/account/restore_login',
+    '/account/check_login',
+    '/account/login',
+    '/account/get_login_code',
+    '/account/login_code',
+    '/account/get_qrcode_url',
+    '/account/qr_state',
+    '/account/google_2fa_verify',
+    '/account/open/login',
+    '/account/captcha',
+    '/account/get_verify_code',
+    '/account/send_verify_code',
+    '/account/verify_code',
+];
+/** 判断公开网络能力是否命中 Runtime 或官方账号敏感路径。 */
+function isProtectedMiniProgramNetworkPath(pathname, official) {
+    const normalized = normalizePublicNetworkPathname(pathname);
+    if (normalized === null)
+        return true;
+    if (matchesPathPrefix(normalized, PUBLIC_NETWORK_PROTECTED_PATH_PREFIXES))
+        return true;
+    return official && matchesPathPrefix(normalized, PUBLIC_NETWORK_OFFICIAL_ACCOUNT_SENSITIVE_PATH_PREFIXES);
+}
+/** 使用 Runtime 唯一的官方域名分类规则判断请求目标。 */
+function isOfficialMiniProgramNetworkUrl(url) {
+    const hostname = url.hostname.toLowerCase().replace(/\.$/, '');
+    return OFFICIAL_ROOT_DOMAINS.some((rootDomain) => hostname === rootDomain || hostname.endsWith(`.${rootDomain}`));
+}
+/** 判断公开网络能力是否禁止调用方设置该请求头。 */
+function isForbiddenMiniProgramNetworkRequestHeader(name) {
+    const normalized = name.trim().toLowerCase();
+    return DENIED_REQUEST_HEADERS.has(normalized) || /^(?:x-heybox|x-xhh)-(?:access-token|auth|authorization|pkey|session|token)$/.test(normalized);
+}
+function normalizePublicNetworkPathname(pathname) {
+    let decoded = pathname;
+    for (let round = 0; round < PATHNAME_MAX_DECODE_ROUNDS; round += 1) {
+        let next;
+        try {
+            next = decodeURIComponent(decoded);
+        }
+        catch {
+            return null;
+        }
+        if (next === decoded)
+            return normalizeDecodedPathname(decoded);
+        decoded = next;
     }
     try {
-        const parsed = new URL(url);
-        parsed.username = '';
-        parsed.password = '';
-        redactUrlSearchParams(parsed.searchParams);
-        if (parsed.hash && parsed.hash.length > 1) {
-            const hashBody = parsed.hash.slice(1);
-            if (hashBody.includes('=')) {
-                const hashParams = new URLSearchParams(hashBody);
-                if (redactUrlSearchParams(hashParams)) {
-                    parsed.hash = hashParams.toString();
-                }
-            }
-        }
-        return parsed.toString();
+        if (decodeURIComponent(decoded) !== decoded)
+            return null;
     }
     catch {
-        return redactSensitivePairsInRawText(url);
-    }
-}
-/**
- * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
- */
-function sanitizeDiagnosticMessage(message) {
-    if (!message) {
-        return message;
+        return null;
     }
-    return message.replace(/https?:\/\/[^\s]+/gi, matched => sanitizeNetworkRequestUrl(matched.replace(/[),.;]+$/g, '')));
+    return normalizeDecodedPathname(decoded);
 }
-function isSensitiveNetworkKey(key) {
-    return SENSITIVE_KEY_PATTERN$1.test(key.trim());
+function matchesPathPrefix(pathname, prefixes) {
+    return prefixes.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`));
 }
-function redactUrlSearchParams(params) {
-    let changed = false;
-    for (const key of [...params.keys()]) {
-        if (isSensitiveNetworkKey(key)) {
-            params.set(key, '[redacted]');
-            changed = true;
-        }
+function normalizeDecodedPathname(pathname) {
+    const segments = [];
+    for (const segment of pathname.replace(/\\/g, '/').split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..')
+            segments.pop();
+        else
+            segments.push(segment);
     }
-    return changed;
-}
-function redactSensitivePairsInRawText(text) {
-    return text.replace(/([?&#]|^|[?&])([^=&#\s]+)=([^&#\s]*)/g, (full, prefix, key, value) => {
-        if (!isSensitiveNetworkKey(key)) {
-            return full;
-        }
-        return `${prefix}${key}=[redacted]`;
-    });
+    return `/${segments.join('/')}`;
 }
 
 const MAX_BROWSER_DEV_HOST_NETWORK_REQUEST_BODY = 2 * 1024 * 1024;
 const MAX_BROWSER_DEV_HOST_NETWORK_RESPONSE_BODY = 5 * 1024 * 1024;
 const DENIED_NETWORK_TARGETS = createDeniedNetworkTargets();
-const CREDENTIAL_HEADER_RE$1 = /^(?:authentication-info|authorization|cookie|cookie2|proxy-authenticate|proxy-authentication-info|proxy-authorization|set-cookie|set-cookie2|www-authenticate|pkey|x-pkey|x-access-token|x-auth-token|x-api-key)$/i;
+const CREDENTIAL_RESPONSE_HEADER_RE = /^(?:authentication-info|authorization|cookie|cookie2|proxy-authenticate|proxy-authentication-info|proxy-authorization|set-cookie|set-cookie2|www-authenticate|pkey|x-pkey|x-access-token|x-auth-token|x-api-key)$/i;
+const HOST_CONTROLLED_REQUEST_HEADERS = new Set(['origin', 'referer', 'user-agent']);
 async function handleBrowserDevHostNetworkProxy(request, response, fetchImpl, lookupHostname, options) {
     const cors = options.cors === true;
     if (request.method === 'OPTIONS') {
@@ -636,7 +735,7 @@ async function handleBrowserDevHostNetworkProxy(request, response, fetchImpl, lo
         payload = await readJsonRequestBody(request);
         const requestAbort = createBrowserDevHostRequestAbortScope(request, response);
         try {
-            const result = await requestBrowserDevHostNetwork(payload, fetchImpl, lookupHostname, options.allowedHttpOrigins, requestAbort.signal);
+            const result = await requestBrowserDevHostNetwork(payload, fetchImpl, lookupHostname, options.allowedHttpOrigins, requestAbort.signal, options.permission);
             if (typeof result.status === 'number' && (result.status < 200 || result.status >= 300)) {
                 logBrowserDevHostNetworkProxyDiagnostic('http_status', payload, result);
             }
@@ -692,11 +791,12 @@ function writeNetworkJsonResponse(response, status, body, cors) {
     writeJsonResponse(response, status, body);
 }
 const BROWSER_DEV_HOST_NETWORK_MULTIPART_UNSUPPORTED_MESSAGE = 'network.request 不支持 multipart/form-data。App Host 客户端代发仅支持 application/x-www-form-urlencoded（form）与 application/json；请将 data 编码为 form 字符串（例如 new URLSearchParams({...}).toString()）并设置 Content-Type: application/x-www-form-urlencoded。文件上传请使用专用上传能力，勿手写 multipart boundary。';
-async function requestBrowserDevHostNetwork(payload, fetchImpl, lookupHostname, allowedHttpOrigins, requestSignal) {
+async function requestBrowserDevHostNetwork(payload, fetchImpl, lookupHostname, allowedHttpOrigins, requestSignal, permission) {
     if (!isRecord$2(payload) || typeof payload.url !== 'string' || !payload.url.trim()) {
         throw createBrowserDevHostError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是非空字符串');
     }
     const url = createBrowserDevHostNetworkUrl(payload.url, payload.params);
+    assertMiniProgramNetworkPolicy(url, permission);
     const method = typeof payload.method === 'string' && payload.method.trim() ? payload.method.trim().toUpperCase() : 'GET';
     const headers = normalizeBrowserDevHostNetworkHeaders(payload.headers);
     assertSupportedBrowserDevHostNetworkRequestShape(headers, payload.data);
@@ -729,7 +829,7 @@ async function requestBrowserDevHostNetwork(payload, fetchImpl, lookupHostname,
             data: contentType.includes('application/json') ? safeJsonParse(text) : text,
             status: response.status,
             statusText: response.statusText,
-            headers: Object.fromEntries([...response.headers.entries()].filter(([name]) => !isCredentialHeader$1(name))),
+            headers: Object.fromEntries([...response.headers.entries()].filter(([name]) => !isCredentialResponseHeader(name))),
         };
     }
     catch (error) {
@@ -824,9 +924,9 @@ function isDeniedNetworkAddress(address, family) {
     }
     return true;
 }
-function isCredentialHeader$1(name) {
+function isCredentialResponseHeader(name) {
     const normalized = name.trim().toLowerCase();
-    return CREDENTIAL_HEADER_RE$1.test(normalized) || normalized.startsWith('x-heybox-') || normalized.startsWith('x-xhh-');
+    return CREDENTIAL_RESPONSE_HEADER_RE.test(normalized) || normalized.startsWith('x-heybox-') || normalized.startsWith('x-xhh-');
 }
 function createPinnedNetworkDispatcher(pinnedTargets) {
     const connect = undici.buildConnector({});
@@ -899,31 +999,29 @@ function normalizeBrowserDevHostNetworkHeaders(headers) {
         return normalized;
     }
     Object.entries(headers).forEach(([key, value]) => {
-        if (isSensitiveBrowserDevHostNetworkHeader(key)) {
+        if (isForbiddenMiniProgramNetworkRequestHeader(key)) {
             throw createBrowserDevHostError(400, 'INVALID_NETWORK_REQUEST', `network.request 不允许设置敏感请求头: ${key}`);
         }
-        if (typeof value === 'string' && !isBlockedBrowserDevHostNetworkHeader(key)) {
+        if (typeof value === 'string' && !isHostManagedRequestHeader(key)) {
             normalized.set(key, value);
         }
     });
     return normalized;
 }
-function isSensitiveBrowserDevHostNetworkHeader(key) {
-    return ['authorization', 'cookie', 'proxy-authorization'].includes(key.toLowerCase());
+function isHostManagedRequestHeader(name) {
+    const normalized = name.trim().toLowerCase();
+    return HOST_CONTROLLED_REQUEST_HEADERS.has(normalized);
 }
-function isBlockedBrowserDevHostNetworkHeader(key) {
-    return [
-        'connection',
-        'content-length',
-        'host',
-        'keep-alive',
-        'proxy-authenticate',
-        'proxy-authorization',
-        'te',
-        'trailer',
-        'transfer-encoding',
-        'upgrade',
-    ].includes(key.toLowerCase());
+function assertMiniProgramNetworkPolicy(url, permission) {
+    if (!permission)
+        return;
+    const official = isOfficialMiniProgramNetworkUrl(url);
+    if (official && !permission.useOfficialDomain) {
+        throw createBrowserDevHostError(403, 'PERMISSION_DENIED', '当前小程序暂不支持访问官方域名');
+    }
+    if (isProtectedMiniProgramNetworkPath(url.pathname, official)) {
+        throw createBrowserDevHostError(403, 'PERMISSION_DENIED', 'network.request 不允许访问 Runtime 或账号敏感接口');
+    }
 }
 /**
  * 与 App Host 对齐：Mock 不再放行 multipart，避免“本地成功、上线失败”。
@@ -1062,7 +1160,8 @@ function createDevSessionRoutes(options) {
             }
             try {
                 const payload = await readJsonRequestBody(request);
-                const validated = validateDevSessionCreatePayload(payload, options.allowedMiniUrlOrigins);
+                const runtimePermissions = context.createMobileDevSessionRuntimePermissions(await options.readDevContext());
+                const validated = validateDevSessionCreatePayload(payload, options.allowedMiniUrlOrigins, runtimePermissions);
                 reapExpiredDevSessions(devSessions, expiredDevSessions, options.now());
                 const replacedTokens = findDevSessionTokensForOrigin(devSessions, validated.miniUrlOrigin);
                 if (devSessions.size - replacedTokens.length >= MAX_ACTIVE_DEV_SESSIONS) {
@@ -1081,6 +1180,7 @@ function createDevSessionRoutes(options) {
                     expiresAt,
                     miniUrlOrigin: validated.miniUrlOrigin,
                     networkRequestEnabled: validated.networkRequestEnabled,
+                    useOfficialDomain: validated.useOfficialDomain,
                     serialized: JSON.stringify(snapshot),
                 });
                 try {
@@ -1129,7 +1229,7 @@ function createDevSessionRoutes(options) {
         },
     };
 }
-function validateDevSessionCreatePayload(payload, allowedMiniUrlOrigins) {
+function validateDevSessionCreatePayload(payload, allowedMiniUrlOrigins, runtimePermissions) {
     if (!isRecord$2(payload) || Object.keys(payload).some((key) => !['mini_url_origin', 'runtime_permissions'].includes(key))) {
         throw new TypeError('Dev Session body is invalid');
     }
@@ -1149,18 +1249,16 @@ function validateDevSessionCreatePayload(payload, allowedMiniUrlOrigins) {
         !allowedMiniUrlOrigins.has(miniUrlOrigin.origin)) {
         throw new TypeError('mini_url_origin must be an allowed LAN origin');
     }
-    const parsedPermissions = runtimePermissionEnv.parseMiniProgramRuntimePermissions(payload.runtime_permissions);
+    const parsedPermissions = runtimePermissionEnv.parseMiniProgramRuntimePermissions(runtimePermissions);
     if (!parsedPermissions.valid) {
         throw new TypeError('runtime_permissions is invalid');
     }
     const networkPermission = parsedPermissions.permissions.network;
-    if (networkPermission?.config.useOfficialDomain !== false) {
-        throw new TypeError('Dev Session does not allow official domains');
-    }
     return {
         miniUrlOrigin: miniUrlOrigin.origin,
-        networkRequestEnabled: networkPermission.status === 'enabled',
-        runtimePermissions: JSON.parse(JSON.stringify(payload.runtime_permissions)),
+        networkRequestEnabled: networkPermission?.status === 'enabled',
+        useOfficialDomain: networkPermission?.status === 'enabled' && networkPermission.config.useOfficialDomain === true,
+        runtimePermissions: JSON.parse(JSON.stringify(runtimePermissions)),
     };
 }
 async function handleTokenNetworkProxy(request, response, token, runtime) {
@@ -1190,6 +1288,7 @@ async function handleTokenNetworkProxy(request, response, token, runtime) {
     await handleBrowserDevHostNetworkProxy(request, response, runtime.fetchImpl, runtime.lookupHostname, {
         allowedHttpOrigins: new Set([resolved.session.miniUrlOrigin]),
         cors: true,
+        permission: { useOfficialDomain: resolved.session.useOfficialDomain },
     });
 }
 function resolveDevSession(token, devSessions, expiredDevSessions, now) {
@@ -1851,8 +1950,8 @@ const DEFAULT_CHANNEL_TRANSPORT = {
 };
 const IPV4_LOOPBACK_ADDRESSES = new net.BlockList();
 IPV4_LOOPBACK_ADDRESSES.addSubnet('127.0.0.0', 8, 'ipv4');
-const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-CPBPdpyu.cjs', document.baseURI).href)))('ws');
-const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-CPBPdpyu.cjs', document.baseURI).href)))('parse5');
+const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-jz2O-8Sf.cjs', document.baseURI).href)))('ws');
+const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-jz2O-8Sf.cjs', document.baseURI).href)))('parse5');
 const BROWSER_DEV_HOST_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'devtools/browser-dev-host'),
     path.resolve(__dirname, '../devtools/browser-dev-host'),
@@ -1883,9 +1982,11 @@ async function startBrowserDevHostServer(options) {
         lanAddresses: options.lanAddresses ?? [],
         loginAvailable: options.loginService !== undefined,
         miniProgram: options.miniProgram,
+        miniProgramSupportsDesktop: options.miniProgramSupportsDesktop,
         mobileLaunchRedirect: initialMobileLaunchRedirect,
         nativeAppLaunchUnavailableReason: options.nativeAppLaunchUnavailableReason,
         runtimePermissions: options.runtimePermissions,
+        devReadiness: options.devReadiness,
     };
     let bootstrapJson = serializeBrowserDevHostBootstrap(bootstrap);
     const serverRuntime = createBrowserDevHostServer(root, {
@@ -1906,6 +2007,8 @@ async function startBrowserDevHostServer(options) {
         loginAvailable: options.loginService !== undefined,
         cliAuth: options.cliAuth,
         readDevContext: () => bootstrap.devContext ?? { source: 'anonymous', runtimePermissions: bootstrap.runtimePermissions },
+        readMobileDevSessionContext: options.readMobileDevSessionContext ??
+            (() => Promise.resolve(bootstrap.devContext ?? { source: 'anonymous', runtimePermissions: bootstrap.runtimePermissions })),
         readLanAddresses: () => bootstrap.lanAddresses,
         mobileLaunchRedirectRegistry,
         onMobileDevSessionCreated: options.onMobileDevSessionCreated,
@@ -1950,6 +2053,8 @@ async function startBrowserDevHostServer(options) {
             return closePromise;
         },
         updateBootstrap: (next) => {
+            if (next.devReadiness !== undefined)
+                bootstrap.devReadiness = next.devReadiness;
             if (next.devContext !== undefined)
                 bootstrap.devContext = next.devContext;
             if (next.lanAddresses !== undefined) {
@@ -1966,6 +2071,8 @@ async function startBrowserDevHostServer(options) {
             }
             if (next.miniProgram !== undefined)
                 bootstrap.miniProgram = next.miniProgram;
+            if (next.miniProgramSupportsDesktop !== undefined)
+                bootstrap.miniProgramSupportsDesktop = next.miniProgramSupportsDesktop;
             bootstrapJson = serializeBrowserDevHostBootstrap(bootstrap);
         },
         networkUrls: createBrowserDevHostNetworkUrls({
@@ -2073,6 +2180,7 @@ function createBrowserDevHostServer(root, runtime) {
         fetchImpl: runtime.fetchImpl,
         lookupHostname: runtime.lookupHostname,
         now: runtime.now,
+        readDevContext: runtime.readMobileDevSessionContext,
         onCreated: ({ expiresAt, miniUrlOrigin, token }, request) => {
             const origin = new URL(readRequestOrigin(request));
             const hostname = origin.hostname.startsWith('[') && origin.hostname.endsWith(']') ? origin.hostname.slice(1, -1) : origin.hostname;
@@ -2172,6 +2280,44 @@ function createBrowserDevHostServer(root, runtime) {
             writeSerializedJsonResponse(response, 200, runtime.readBootstrapJson());
             return;
         }
+        if (pathname === '/__hb_sdk__/sandbox') {
+            if (!isValidSensitiveRequest(request, loopbackPeer, runtime.sessionController.csrfToken)) {
+                writeForbidden(response);
+                return;
+            }
+            if (request.method !== 'POST') {
+                writeMethodNotAllowed(response, 'POST');
+                return;
+            }
+            try {
+                const input = await readJsonRequestBody(request);
+                if (!isRecord$2(input) || typeof input.device !== 'string' || typeof input.path !== 'string') {
+                    writeBadRequest(response);
+                    return;
+                }
+                const store = getDeviceLogs(runtime.appUrl);
+                writeJsonResponse(response, 200, store ? await store.listSandbox(input.device, input.path) : { error: '设备服务不可用' });
+            }
+            catch {
+                writeBadRequest(response);
+            }
+            return;
+        }
+        if (pathname === DEVICE_LOG_PATH) {
+            const origin = request.headers.origin;
+            if (!loopbackPeer || !hasNumericLoopbackHost(request) ||
+                (origin && origin !== `http://${request.headers.host}`)) {
+                writeForbidden(response);
+                return;
+            }
+            if (request.method !== 'GET') {
+                writeMethodNotAllowed(response, 'GET');
+                return;
+            }
+            const store = getDeviceLogs(runtime.appUrl);
+            writeJsonResponse(response, 200, store ? store.query(requestUrl.searchParams) : { epoch: '', items: [], devices: [], nextCursor: 0, hasMore: false, gap: false });
+            return;
+        }
         if (pathname === '/session/status') {
             if (!loopbackPeer || !hasNumericLoopbackHost(request)) {
                 writeForbidden(response);
@@ -10902,7 +11048,7 @@ function assertNodeRuntimeCapabilities(ctx, settings) {
 function createNodeRealtimeDriverRegistry() {
     const registry = createRuntimeRealtimeDriverRegistry();
     registry.registerLazy('node-websocket', async () => {
-        const mod = await Promise.resolve().then(function () { return require('./index.esm-qwrdRuy-.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-DiC4hnWh.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -13785,9 +13931,10 @@ function readHeyboxWebV4BrowserFingerprint() {
     if (typeof document === 'undefined' || typeof navigator === 'undefined') {
         return '';
     }
+    let webgl = null;
     try {
         const canvas = document.createElement('canvas');
-        const webgl = canvas.getContext('webgl');
+        webgl = canvas.getContext('webgl');
         const debugInfo = webgl?.getExtension('WEBGL_debug_renderer_info');
         let renderer = debugInfo ? String(webgl?.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) ?? '') : '';
         if (!renderer) {
@@ -13806,6 +13953,15 @@ function readHeyboxWebV4BrowserFingerprint() {
     catch {
         return `${navigator.userAgent ?? ''}${navigator.platform ?? ''}${navigator.language ?? ''}`;
     }
+    finally {
+        // 签名请求会反复读取种子，及时释放临时上下文，避免耗尽浏览器的 WebGL 配额。
+        try {
+            webgl?.getExtension('WEBGL_lose_context')?.loseContext();
+        }
+        catch {
+            // 浏览器可能已丢失上下文；清理失败不改变本次签名种子或原降级语义。
+        }
+    }
 }
 /**
  * 根据 pathname、时间和 nonce 计算 Web V4 hkey。
@@ -14862,7 +15018,7 @@ function containsSecret(value, secret) {
 
 const LAUNCH_CORS_HEADERS = {
     'access-control-allow-methods': 'GET',
-    'access-control-allow-origin': '*',
+    'access-control-allow-origin': 'https://www.xiaoheihe.cn',
     'access-control-allow-private-network': 'true',
     'cache-control': 'no-store',
 };
@@ -14877,6 +15033,10 @@ function tryHandleMiniProgramDevLaunchRequest(request, response, readSource) {
     if (requestUrl.pathname !== MINI_PROGRAM_DEV_LAUNCH_PATH || requestUrl.search !== '') {
         return false;
     }
+    if (!isAllowedLaunchOrigin(request.headers.origin)) {
+        writeLaunchResponse(response, 403);
+        return true;
+    }
     if (request.method !== 'GET' && request.method !== 'OPTIONS') {
         response.writeHead(405, { allow: 'GET', ...LAUNCH_CORS_HEADERS });
         response.end();
@@ -14911,6 +15071,16 @@ function createLaunchSnapshot(source, requestOrigin) {
     const localDevLaunchToken = source.localDevLaunchToken?.trim();
     if (localDevLaunchToken)
         snapshot.local_dev_launch_token = localDevLaunchToken;
+    if (source.devSessionId)
+        snapshot.dev_session_id = source.devSessionId;
+    if (source.expiresAt)
+        snapshot.expires_at = source.expiresAt;
+    const companionManifestSha256 = source.companionManifestSha256?.trim();
+    if (companionManifestSha256)
+        snapshot.companion_manifest_sha256 = companionManifestSha256;
+    const companionArtifactAccessToken = source.companionArtifactAccessToken?.trim();
+    if (companionArtifactAccessToken)
+        snapshot.companion_artifact_access_token = companionArtifactAccessToken;
     const storedContextUrl = source.devContextUrlsByMiniUrlOrigin.get(requestOrigin.origin);
     if (storedContextUrl) {
         snapshot.dev_context_url = projectStoredDevContextUrl(storedContextUrl, requestOrigin.hostname);
@@ -14954,6 +15124,9 @@ function readNumericRequestOrigin(request) {
 function isAllowedLaunchPeer(address) {
     return isLoopbackOrPrivateLanAddress(address);
 }
+function isAllowedLaunchOrigin(origin) {
+    return origin === undefined || origin === 'https://www.xiaoheihe.cn';
+}
 function writeLaunchResponse(response, status, body) {
     response.writeHead(status, {
         ...LAUNCH_CORS_HEADERS,
@@ -14970,6 +15143,10 @@ const LOCAL_DEV_URL_HOST = '127.0.0.1';
 // 与 Heybox H5 Vite 插件共享，让 hb-sdk 统一管理启动输出。
 const MANAGED_DEV_OUTPUT_ENV = 'HEYBOX_DEV_SERVER_MANAGED_OUTPUT';
 const VITE_LOG_LEVEL = 'warn';
+const COMPANION_DEV_MANIFEST_PATH = '/__hb_sdk__/companion/manifest.json';
+const COMPANION_DEV_MANIFEST_MAX_BYTES = 1024 * 1024;
+const COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN';
+const COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER = 'x-hb-sdk-companion-dev-token';
 async function runDevCommand(options, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
     const fetchImpl = runtime.fetchImpl ?? fetch;
@@ -14991,6 +15168,9 @@ async function runDevCommand(options, runtime = {}) {
         port: appPort,
     };
     const projectRoot = projectVite.findProjectRoot(runtime.cwd ?? process.cwd());
+    const companionArtifactAccessToken = (runtime.randomBytes ?? node_crypto.randomBytes)(32).toString('base64url');
+    const devSessionId = node_crypto.randomBytes(16).toString('hex');
+    const miniProgramPlatforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
     const { context: devLaunchContext, miniProgram } = await loadDevLaunchContext({
         env: runtime.env,
         fetchImpl,
@@ -14998,22 +15178,59 @@ async function runDevCommand(options, runtime = {}) {
         projectRoot,
         timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
     });
-    const launchRuntimePermissions = context.createBrowserDevRuntimePermissions(devLaunchContext.runtimePermissions, context.createBrowserDevPermissionState(devLaunchContext));
-    const vite = await runDevStartupTask(logger, '正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), '已加载项目 Vite');
-    const appServer = await runDevStartupTask(logger, '正在创建 Vite 开发服务器', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), runtime.env), '已创建 Vite 开发服务器');
+    let currentDevContext = devLaunchContext;
+    let launchRuntimePermissions = context.createBrowserDevRuntimePermissions(devLaunchContext.runtimePermissions, context.createBrowserDevPermissionState(devLaunchContext));
     const mobileDevContextUrlsByOrigin = new Map();
+    let currentCompanionManifestSha256;
     let currentLocalDevLaunchToken = devLaunchContext.localDevLaunchToken;
-    appServer.middlewares.use((request, response, next) => {
-        const handled = tryHandleMiniProgramDevLaunchRequest(request, response, () => ({
-            devContextUrlsByMiniUrlOrigin: mobileDevContextUrlsByOrigin,
-            localDevLaunchToken: currentLocalDevLaunchToken,
-            miniProgramId: devLaunchContext.miniProgramId,
-            runtimePermissions: launchRuntimePermissions,
-            sdkVersion: version.HB_SDK_VERSION,
-        }));
-        if (!handled)
-            next();
+    let currentExpiresAt;
+    let tokenSession;
+    const readLaunchSource = () => ({
+        companionArtifactAccessToken,
+        companionManifestSha256: currentCompanionManifestSha256,
+        devContextUrlsByMiniUrlOrigin: mobileDevContextUrlsByOrigin,
+        localDevLaunchToken: currentLocalDevLaunchToken,
+        devSessionId,
+        expiresAt: currentExpiresAt,
+        miniProgramId: devLaunchContext.miniProgramId,
+        runtimePermissions: launchRuntimePermissions,
+        sdkVersion: version.HB_SDK_VERSION,
     });
+    const launchPlugin = createMiniProgramDevLaunchVitePlugin(readLaunchSource, async (request, response) => {
+        if (request.url !== MINI_PROGRAM_DEV_LAUNCH_PATH || request.headers[COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER] === undefined)
+            return false;
+        response.setHeader('Cache-Control', 'no-store');
+        const token = request.headers[COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER];
+        const remote = request.socket.remoteAddress;
+        if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(token) ||
+            !node_crypto.timingSafeEqual(Buffer.from(token), Buffer.from(companionArtifactAccessToken)) ||
+            !['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(remote ?? '') ||
+            !/^(127\.0\.0\.1|\[::1\]):\d{1,5}$/.test(request.headers.host ?? '')) {
+            response.writeHead(403).end();
+            return true;
+        }
+        if (request.method !== 'GET') {
+            response.writeHead(405, { Allow: 'GET' }).end();
+            return true;
+        }
+        try {
+            const issued = await tokenSession?.getTicket(currentCompanionManifestSha256);
+            if (!issued)
+                response.writeHead(503).end();
+            else
+                response.writeHead(200, { 'Content-Type': 'application/json', 'X-Content-Type-Options': 'nosniff' }).end(JSON.stringify(createLaunchSnapshot({
+                    ...readLaunchSource(), localDevLaunchToken: issued.token, expiresAt: issued.expiresAt,
+                }, new URL(`http://${request.headers.host}`))));
+        }
+        catch (error) {
+            const status = error instanceof index.CliError && (error.httpStatus === 401 || error.httpStatus === 403) ? error.httpStatus : 503;
+            logger.debug(`本地开发会话续票失败：${index.readRedactedErrorMessage(error, { verbose: true })}`);
+            response.writeHead(status).end();
+        }
+        return true;
+    });
+    const vite = await runDevStartupTask(logger, '正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), '已加载项目 Vite');
+    const appServer = await runDevStartupTask(logger, '正在创建 Vite 开发服务器', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withCompanionArtifactAccessTokenEnv(companionArtifactAccessToken, () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions, launchPlugin)), runtime.env), runtime.env), runtime.env), '已创建 Vite 开发服务器');
     await runDevStartupTask(logger, '正在启动 Vite 开发服务器', () => appServer.listen(appPort), 'Vite 开发服务器已启动');
     const appUrl = await runDevStartupTask(logger, '正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), '已确定小程序入口');
     const buildLanAddresses = () => createLanAddressCandidates({
@@ -15032,7 +15249,7 @@ async function runDevCommand(options, runtime = {}) {
     try {
         browserDevHost = await runDevStartupTask(logger, '正在启动浏览器调试页服务', () => startBrowserDevHostServer({
             appUrl,
-            devContext: devLaunchContext,
+            devContext: currentDevContext,
             fetchImpl,
             getPort: getPortImpl,
             defaultLanAddressId: lanAddresses[0]?.id,
@@ -15040,6 +15257,8 @@ async function runDevCommand(options, runtime = {}) {
             lookupHostname: runtime.lookupHostname,
             loginService: runtime.loginService,
             miniProgram,
+            // 只在项目声明了桌面平台时向调试台暴露「在桌面端打开」入口。
+            miniProgramSupportsDesktop: runtimePermissionEnv.hasMiniappDesktopPlatform(miniProgramPlatforms),
             cliAuth: runtime.cliAuth ?? createBrowserDevHostCliAuth({ env: runtime.env, fetchImpl }),
             onMobileDevSessionCreated: ({ devContextUrl, miniUrlOrigin }) => {
                 mobileDevContextUrlsByOrigin.set(miniUrlOrigin, devContextUrl);
@@ -15047,6 +15266,30 @@ async function runDevCommand(options, runtime = {}) {
                     lanAddresses: buildLanAddresses(),
                 });
             },
+            readMobileDevSessionContext: async () => {
+                try {
+                    const refreshed = await loadDevLaunchContext({
+                        env: runtime.env,
+                        fetchImpl,
+                        logger,
+                        projectRoot,
+                        timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
+                    });
+                    currentDevContext = withCurrentLocalDevLaunchToken(refreshed.context, currentLocalDevLaunchToken);
+                    launchRuntimePermissions = context.createMobileDevSessionRuntimePermissions(currentDevContext);
+                    browserDevHost.updateBootstrap({
+                        devContext: currentDevContext,
+                        miniProgram: refreshed.miniProgram,
+                    });
+                    return currentDevContext;
+                }
+                catch (error) {
+                    currentDevContext = { source: 'anonymous' };
+                    launchRuntimePermissions = { schema_version: 1, entries: [] };
+                    browserDevHost.updateBootstrap({ devContext: currentDevContext });
+                    throw error;
+                }
+            },
             port: options.browserDevHostPort ?? DEFAULT_BROWSER_DEV_HOST_PORT,
             root: runtime.browserDevHostRoot,
             rootCandidates: runtime.browserDevHostRootCandidates,
@@ -15059,39 +15302,70 @@ async function runDevCommand(options, runtime = {}) {
     }
     closers.push(() => browserDevHost.close());
     if (devLaunchContext.source === 'remote' && devLaunchContext.miniProgramId) {
-        const tokenSession = startLocalDevLaunchTokenSession({
+        tokenSession = startLocalDevLaunchTokenSession({
             env: runtime.env,
             fetchImpl,
             logger,
+            manifestUrl: new URL(COMPANION_DEV_MANIFEST_PATH, appUrl).toString(),
+            companionArtifactAccessToken,
+            companionApproved: hasCompanionApproval(devLaunchContext.runtimePermissions),
             miniProgramId: devLaunchContext.miniProgramId,
-            onToken: (localDevLaunchToken) => {
+            refreshPermissions: async () => {
+                const refreshed = await loadDevLaunchContext({ env: runtime.env, fetchImpl, logger, projectRoot,
+                    timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS });
+                if (refreshed.context.miniProgramId !== devLaunchContext.miniProgramId)
+                    throw new Error('项目绑定已变更，请重新启动调试');
+                devLaunchContext.runtimePermissions = refreshed.context.runtimePermissions;
+                currentDevContext = withCurrentLocalDevLaunchToken(devLaunchContext, currentLocalDevLaunchToken);
+                launchRuntimePermissions = context.createBrowserDevRuntimePermissions(devLaunchContext.runtimePermissions, context.createBrowserDevPermissionState(devLaunchContext));
+                browserDevHost.updateBootstrap({ devContext: currentDevContext });
+                return hasCompanionApproval(devLaunchContext.runtimePermissions);
+            },
+            onToken: (localDevLaunchToken, companionManifestSha256, expiresAt) => {
+                currentExpiresAt = expiresAt;
+                currentCompanionManifestSha256 = companionManifestSha256;
                 currentLocalDevLaunchToken = localDevLaunchToken;
-                const tokenContext = {
-                    source: 'remote',
-                    miniProgramId: devLaunchContext.miniProgramId,
-                    ...(localDevLaunchToken ? { localDevLaunchToken } : {}),
-                    runtimePermissions: devLaunchContext.runtimePermissions,
-                };
+                currentDevContext = withCurrentLocalDevLaunchToken(currentDevContext, localDevLaunchToken);
                 browserDevHost.updateBootstrap({
-                    devContext: tokenContext,
+                    devContext: currentDevContext,
                     lanAddresses: buildLanAddresses(),
                 });
             },
+            onReadiness: devReadiness => browserDevHost.updateBootstrap({ devReadiness }),
             projectRoot,
             timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
         });
         closers.push(tokenSession.close);
     }
-    logger.success('本地调试已启动');
+    else {
+        const reason = '登录或小程序绑定不可用，请完成 CLI 登录和项目绑定';
+        browserDevHost.updateBootstrap({
+            devReadiness: {
+                browser: { state: 'ready' },
+                mobile: { state: 'blocked', reason },
+                companion: { state: 'blocked', reason },
+            },
+        });
+    }
+    logger.success('Web / Browser Fake 调试已就绪');
     logger.info(`调试页：${browserDevHost.url}`);
     logger.info(`小程序地址：${appUrl}`);
-    logger.info('手机调试：请在调试页扫码');
+    logger.info('手机与 PC Companion 的就绪状态请查看调试页');
     if (options.open !== false) {
         logger.debug('正在打开浏览器调试页');
         void openUrl(browserDevHost.url);
     }
     installShutdownHandlers(closers, runtime.process ?? process);
 }
+function withCurrentLocalDevLaunchToken(context, localDevLaunchToken) {
+    return {
+        source: context.source,
+        ...(context.miniProgramId ? { miniProgramId: context.miniProgramId } : {}),
+        ...(localDevLaunchToken ? { localDevLaunchToken } : {}),
+        ...(context.runtimePermissions !== undefined ? { runtimePermissions: context.runtimePermissions } : {}),
+        ...(context.warning ? { warning: context.warning } : {}),
+    };
+}
 function runDevStartupTask(logger, text, action, successText) {
     if (!logger.verbose) {
         return action();
@@ -15165,10 +15439,26 @@ async function loadRemoteDevContextWithTimeout(options) {
         }
     }
 }
-function createViteServerOptions(projectRoot, options) {
+function createMiniProgramDevLaunchVitePlugin(getSnapshot, handleSession) {
+    return {
+        name: 'heybox-mini-program-dev-launch',
+        enforce: 'pre',
+        configureServer(server) {
+            server.middlewares.use(async (request, response, next) => {
+                if (handleSession && await handleSession(request, response))
+                    return;
+                if (!tryHandleMiniProgramDevLaunchRequest(request, response, getSnapshot))
+                    next();
+            });
+        },
+    };
+}
+function createViteServerOptions(projectRoot, options, launchPlugin) {
     const configFile = resolveProjectViteConfig(projectRoot);
     const server = {
-        cors: true,
+        // launch.json 由 mini-program-dev-launch plugin 自己处理 PNA/CORS 预检；
+        // Vite 通用 CORS 会抢先返回 `*`，缺少 Access-Control-Allow-Private-Network。
+        cors: false,
         hmr: {
             clientPort: options.port ?? DEFAULT_APP_PORT,
         },
@@ -15180,11 +15470,13 @@ function createViteServerOptions(projectRoot, options) {
         return {
             configFile,
             logLevel: VITE_LOG_LEVEL,
+            plugins: [launchPlugin],
             server,
         };
     }
     return {
         logLevel: VITE_LOG_LEVEL,
+        plugins: [launchPlugin],
         root: projectRoot,
         server,
     };
@@ -15298,6 +15590,19 @@ async function withManagedDevOutputEnv(action, env = process.env) {
         }
     }
 }
+async function withCompanionArtifactAccessTokenEnv(token, action, env = process.env) {
+    const previous = env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV];
+    env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV] = token;
+    try {
+        return await action();
+    }
+    finally {
+        if (previous === undefined)
+            delete env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV];
+        else
+            env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV] = previous;
+    }
+}
 function installShutdownHandlers(closers, processLike) {
     const shutdown = async () => {
         await closeAll(closers);
@@ -15318,28 +15623,94 @@ function startLocalDevLaunchTokenSession(options) {
     let expirationTimer;
     let hasReportedTokenFailure = false;
     let refreshTimer;
+    let companionApproved = options.companionApproved;
+    let permissionsRefreshAt = Date.now() + 30_000;
+    let publishedToken;
+    let publishedDigest;
+    let ticket;
+    let pending;
+    const getTicket = async (companionManifestSha256) => {
+        if (closed)
+            return undefined;
+        if (ticket && (companionManifestSha256 === undefined || ticket.companionManifestSha256 === companionManifestSha256) && ticket.refreshAt > Date.now())
+            return ticket;
+        return issueTicket(companionManifestSha256);
+    };
+    const issueTicket = (companionManifestSha256) => {
+        if (pending && pending.digest === companionManifestSha256)
+            return pending.promise;
+        const promise = issueLocalDevLaunchToken({
+            ...options,
+            ...(companionManifestSha256 ? { companionManifestSha256 } : {}),
+        })
+            .then(issued => {
+            ticket = issued;
+            return issued;
+        }).finally(() => { if (pending?.promise === promise)
+            pending = undefined; });
+        pending = { digest: companionManifestSha256, promise };
+        return promise;
+    };
     const refresh = async () => {
         try {
-            const issued = await issueLocalDevLaunchToken(options);
+            if (options.refreshPermissions && Date.now() >= permissionsRefreshAt) {
+                companionApproved = await options.refreshPermissions();
+                permissionsRefreshAt = Date.now() + 30_000;
+            }
+            let manifest;
+            let snapshotError;
+            try {
+                manifest = await loadRemoteDevContextWithTimeout({
+                    fetchImpl: options.fetchImpl,
+                    timeoutMs: options.timeoutMs,
+                    load: fetchImpl => readCompanionManifest(options.manifestUrl, options.companionArtifactAccessToken, fetchImpl),
+                });
+            }
+            catch (error) {
+                snapshotError = error;
+            }
+            const digest = manifest?.digest;
+            const issued = await getTicket(digest);
+            if (!issued)
+                return;
             if (closed)
                 return;
-            options.onToken(issued.token);
+            if (publishedToken !== issued.token || publishedDigest !== digest) {
+                publishedToken = issued.token;
+                publishedDigest = digest;
+                options.onToken(issued.token, digest, issued.expiresAt);
+            }
+            options.onReadiness({
+                browser: { state: 'ready' },
+                mobile: { state: 'ready' },
+                companion: snapshotError
+                    ? { state: snapshotError instanceof Error && snapshotError.message.includes('artifact-updating') ? 'pending' : 'blocked', reason: safeCompanionFailureReason(snapshotError) }
+                    : manifest?.artifacts.length
+                        ? companionApproved
+                            ? { state: 'ready', digest, artifacts: manifest.artifacts, reason: '本地产物和启动票已就绪，PC 授权将在打开后验证' }
+                            : { state: 'blocked', reason: 'Companion 未获 COA 批准或本地权限声明未开启' }
+                        : { state: 'not-configured', reason: '未配置本地 Companion 产物' },
+            });
+            if (snapshotError)
+                options.logger.debug(`PC Companion 快照校验失败：${index.readRedactedErrorMessage(snapshotError, { verbose: true })}`);
             const ttl = Math.max(0, issued.expiresAt - Date.now());
             scheduleExpiration(ttl);
-            schedule(Math.max(1_000, Math.floor(ttl * 0.8)));
+            schedule(Math.min(2_000, Math.max(1_000, Math.floor(ttl * 0.8))));
             if (hasReportedTokenFailure) {
                 hasReportedTokenFailure = false;
-                options.logger.success('手机扫码调试已恢复');
+                options.logger.success('本地调试凭证已恢复');
             }
         }
         catch (error) {
             if (closed)
                 return;
             if (!hasReportedTokenFailure) {
-                options.logger.warn('手机扫码调试凭证获取失败，将自动重试');
+                options.logger.warn('本地调试凭证获取失败，将自动重试；Web / Browser Fake 仍可使用');
             }
             hasReportedTokenFailure = true;
-            options.logger.debug(`手机扫码调试凭证获取失败，详细原因：${index.readRedactedErrorMessage(error, { verbose: true })}`);
+            options.onReadiness({ browser: { state: 'ready' }, mobile: { state: 'blocked', reason: '调试凭证暂不可用' },
+                companion: { state: 'blocked', reason: safeCompanionFailureReason(error) } });
+            options.logger.debug(`本地调试凭证获取失败，详细原因：${index.readRedactedErrorMessage(error, { verbose: true })}`);
             schedule(options.timeoutMs);
         }
     };
@@ -15353,13 +15724,20 @@ function startLocalDevLaunchTokenSession(options) {
         if (expirationTimer)
             clearTimeout(expirationTimer);
         expirationTimer = setTimeout(() => {
-            if (!closed)
-                options.onToken(undefined);
+            if (!closed) {
+                options.onToken(undefined, undefined);
+                publishedToken = undefined;
+                options.onReadiness({ browser: { state: 'ready' }, mobile: { state: 'blocked', reason: '调试凭证已过期' },
+                    companion: { state: 'blocked', reason: '调试凭证已过期' } });
+            }
         }, Math.max(1, ttl));
         expirationTimer.unref?.();
     };
-    void refresh();
+    options.onReadiness({ browser: { state: 'ready' }, mobile: { state: 'pending' }, companion: { state: 'pending' } });
+    const ready = refresh();
     return {
+        getTicket,
+        ready,
         close: () => {
             closed = true;
             if (expirationTimer)
@@ -15373,22 +15751,128 @@ async function issueLocalDevLaunchToken(options) {
     const issued = await loadRemoteDevContextWithTimeout({
         fetchImpl: options.fetchImpl,
         timeoutMs: options.timeoutMs,
-        load: (fetchImpl) => context.createLocalDevLaunchToken({
-            cwd: options.projectRoot,
-            env: options.env,
-            fetchImpl,
-            miniProgramId: options.miniProgramId,
-        }),
+        load: async (fetchImpl) => {
+            const result = await context.createLocalDevLaunchToken({
+                cwd: options.projectRoot,
+                env: options.env,
+                fetchImpl,
+                miniProgramId: options.miniProgramId,
+                ...(options.companionManifestSha256
+                    ? { companionManifestSha256: options.companionManifestSha256 }
+                    : {}),
+            });
+            return { result };
+        },
     });
-    const token = typeof issued.token === 'string' ? issued.token.trim() : '';
+    const token = typeof issued.result.token === 'string' ? issued.result.token.trim() : '';
     if (!token) {
         throw new Error('响应缺少 token');
     }
-    const expiresAt = normalizeExpiresAt(issued.expires_at);
+    const expiresAt = normalizeExpiresAt(issued.result.expires_at);
     if (!expiresAt || expiresAt <= Date.now()) {
         throw new Error('响应缺少有效 expires_at');
     }
-    return { expiresAt, token };
+    return { ...(options.companionManifestSha256 ? { companionManifestSha256: options.companionManifestSha256 } : {}), expiresAt, token,
+        refreshAt: Date.now() + Math.max(1, (expiresAt - Date.now()) * 0.8) };
+}
+function safeCompanionFailureReason(error) {
+    const message = index.readRedactedErrorMessage(error, { verbose: true });
+    if (/artifact-updating/.test(message))
+        return '本地 Companion 产物准备中';
+    if (/artifact-missing/.test(message))
+        return '本地 Companion 产物目录不存在，请先构建产物';
+    if (/snapshot-limit/.test(message))
+        return '本地快照数量或大小已达上限，请结束会话后重启 dev';
+    if (/invalid-manifest/.test(message))
+        return '本地 Manifest 或权限配置无效';
+    if (/invalid-artifact/.test(message))
+        return '本地产物或原生入口校验失败';
+    if (/404|not found/i.test(message))
+        return '调试接口尚未部署或当前登录环境不匹配';
+    if (/403|forbidden|permission|授权|权限/i.test(message))
+        return 'Companion 授权未通过，请检查 COA 批准与开发者身份';
+    if (/401|登录/i.test(message))
+        return 'CLI 登录态已失效，请重新登录';
+    if (/manifest|快照|ZIP|ENOENT/i.test(message))
+        return '本地 Companion ZIP 或 Manifest 校验失败，请检查产物与配置';
+    return 'PC Companion 暂不可用，请检查网络、登录环境和调试接口';
+}
+function hasCompanionApproval(value) {
+    if (!value || typeof value !== 'object' || !('entries' in value) || !Array.isArray(value.entries))
+        return false;
+    return value.entries.some(entry => entry?.key === 'companion' && entry?.status === 'enabled');
+}
+async function readCompanionManifest(manifestUrl, companionArtifactAccessToken, fetchImpl) {
+    try {
+        const response = await fetchImpl(manifestUrl, {
+            cache: 'no-store',
+            credentials: 'omit',
+            headers: {
+                accept: 'application/json',
+                [COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER]: companionArtifactAccessToken,
+            },
+            method: 'GET',
+            redirect: 'error',
+            referrerPolicy: 'no-referrer',
+        });
+        if (response.status === 404) {
+            return undefined;
+        }
+        if (!response.ok) {
+            const code = response.headers.get('x-hb-sdk-companion-error');
+            const safeCode = ['artifact-updating', 'artifact-missing', 'snapshot-limit', 'invalid-manifest', 'invalid-artifact'].includes(code ?? '') ? code : '';
+            throw new Error(`Companion manifest request failed with status ${response.status} ${safeCode}`);
+        }
+        if (!response.headers.get('content-type')?.toLowerCase().includes('application/json')) {
+            throw new Error('Companion manifest response is not JSON');
+        }
+        const contentLength = Number(response.headers.get('content-length'));
+        if (Number.isFinite(contentLength) && contentLength > COMPANION_DEV_MANIFEST_MAX_BYTES) {
+            throw new Error('Companion manifest response is too large');
+        }
+        const bytes = await readBoundedCompanionManifestBytes(response, COMPANION_DEV_MANIFEST_MAX_BYTES);
+        const value = JSON.parse(bytes.toString('utf8'));
+        const artifacts = Object.entries(value.companions ?? {}).flatMap(([alias, definition]) => {
+            if (!/^[a-z][a-z0-9-]{0,31}$/.test(alias) || !definition || typeof definition !== 'object') {
+                throw new Error('Companion invalid-manifest');
+            }
+            return Object.keys(definition.targets ?? {}).map(target => {
+                if (target !== 'windows-x64' && target !== 'macos-arm64')
+                    throw new Error('Companion invalid-manifest');
+                return { alias, target };
+            });
+        });
+        return { digest: node_crypto.createHash('sha256').update(bytes).digest('hex'), artifacts };
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw error;
+        throw new Error('Companion manifest request failed');
+    }
+}
+async function readBoundedCompanionManifestBytes(response, maxBytes) {
+    if (!response.body)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel('Companion manifest response is too large');
+                throw new Error('Companion manifest response is too large');
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks.map(chunk => Buffer.from(chunk)), total);
 }
 function normalizeExpiresAt(value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
@@ -15501,8 +15985,10 @@ function isPrivateIPv4(address) {
 
 var dev = /*#__PURE__*/Object.freeze({
 	__proto__: null,
+	createMiniProgramDevLaunchVitePlugin: createMiniProgramDevLaunchVitePlugin,
 	normalizeExpiresAt: normalizeExpiresAt,
-	runDevCommand: runDevCommand
+	runDevCommand: runDevCommand,
+	startLocalDevLaunchTokenSession: startLocalDevLaunchTokenSession
 });
 
 exports.RuntimeError = RuntimeError;