@lark-apaas/coding-html-devserver 0.1.0

package/lib/transform/slardar.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slardarTags = slardarTags;
+/**
+ * HTML 解析时同步执行的内联脚本（早于任何外部资源加载）：建 KSlardarWeb 命令队列
+ * stub + 立即注册 capture 阶段的资源/运行时错误监听，SDK 就绪前入 buffer，onload 后 flush。
+ */
+function buildEarlyResourceErrorScript(globalName) {
+    return `(function(g){
+  if(!window[g]){var q=[];window[g]=function(){q.push([].slice.call(arguments));};window[g].q=q;}
+  window.__slardarErrBuf=window.__slardarErrBuf||[];
+  var ref=document.referrer||'';
+  function _cap(err){
+    if(window[g]&&!window[g].q){
+      window[g]('captureException',err instanceof Error?err:new Error(String(err)),{source:'runtime-error',referrer:ref});
+    }else{
+      (window.__slardarErrBuf=window.__slardarErrBuf||[]).push(err);
+    }
+  }
+  window.addEventListener('error',function(e){
+    if(e.error==null&&e.target instanceof Element){
+      var t=e.target,url=t.src||t.href||'';
+      if(url)window[g]('captureException',new Error('Resource load failed: '+url),{team:'miaoda-sdk',source:'resource-error',resourceType:t.tagName.toLowerCase(),resourceUrl:url,referrer:ref});
+      return;
+    }
+    if(e.error!=null){
+      var err=e.error;
+      if(e.filename&&typeof err.stack==='string'&&err.stack.indexOf(e.filename)<0){
+        try{err.stack+='\\n    at '+e.filename+':'+(e.lineno||0)+':'+(e.colno||0);}catch(ex){}
+      }
+      _cap(err);
+    }else{
+      var msg=e.message||'Script error';
+      var err=new Error(msg);
+      if(e.filename)err.stack=msg+'\\n    at '+e.filename+':'+(e.lineno||0)+':'+(e.colno||0);
+      _cap(err);
+    }
+  },true);
+  window.addEventListener('unhandledrejection',function(e){
+    if(e.reason!=null)_cap(e.reason instanceof Error?e.reason:new Error(String(e.reason)));
+  });
+})('${globalName}');`;
+}
+function buildSlardarScript(bid, globalName) {
+    return `
+    const slardarScript = document.createElement('script');
+    slardarScript.src = 'https://lf3-short.ibytedapm.com/slardar/fe/sdk-web/browser.cn.js?bid=${bid}&globalName=${globalName}';
+    slardarScript.crossOrigin = 'anonymous';
+    slardarScript.onload = function() {
+      if (window.${globalName}) {
+        window.${globalName}('context.merge', {
+          tenantId: window.tenantId ?? '',
+          appId: window.appId ?? '',
+        });
+        window.${globalName}('init', {
+          bid: '${bid}',
+          env: window.ENVIRONMENT || 'online',
+          userId: window.userId ?? '',
+        });
+        window.${globalName}('start');
+        // Flush errors captured before the SDK finished loading
+        var buf = window.__slardarErrBuf || [];
+        window.__slardarErrBuf = [];
+        buf.forEach(function(err) {
+          window.${globalName}('captureException', err instanceof Error ? err : new Error(String(err)), { source: 'pre-sdk-error', referrer: document.referrer || '' });
+        });
+      }
+    };
+    slardarScript.onerror = function() {
+      console.warn('Failed to load Slardar script');
+    };
+    document.head.appendChild(slardarScript);
+  `;
+}
+function buildTeaScript() {
+    return `
+  (function (win, export_obj) {
+    win['LogAnalyticsObject'] = export_obj;
+    if (!win[export_obj]) {
+      function _collect() { _collect.q.push(arguments); }
+      _collect.q = _collect.q || [];
+      win[export_obj] = _collect;
+    }
+    win[export_obj].l = +new Date();
+  })(window, 'collectEvent');
+
+  const teaScript = document.createElement('script');
+  teaScript.src = 'https://lf3-cdn-tos.bytescm.com/obj/static/log-sdk/collect/5.1/collect.js';
+  teaScript.crossOrigin = 'anonymous';
+  teaScript.async = true;
+  teaScript.onerror = function() {
+    console.warn('Failed to load Tea script');
+  };
+  document.head.appendChild(teaScript);
+  `;
+}
+/** Slardar + Performance + Tea 监控埋点的 head-prepend script 清单。 */
+function slardarTags(options = {}) {
+    const { bid = 'apaas_miaoda', globalName = 'KSlardarWeb' } = options;
+    return [
+        // 必须最先：内联资源错误捕获 + KSlardarWeb 命令队列 stub
+        { tag: 'script', children: buildEarlyResourceErrorScript(globalName), injectTo: 'head-prepend' },
+        { tag: 'script', children: buildSlardarScript(bid, globalName), injectTo: 'head-prepend' },
+        {
+            tag: 'script',
+            attrs: {
+                src: 'https://sf3-scmcdn-cn.feishucdn.com/obj/unpkg/byted/performance/0.1.2/dist/performance.iife.js',
+                crossorigin: 'anonymous',
+                defer: true,
+            },
+            injectTo: 'head-prepend',
+        },
+        { tag: 'script', children: buildTeaScript(), injectTo: 'head-prepend' },
+    ];
+}
+//# sourceMappingURL=slardar.js.map

package/lib/transform/slardar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slardar.js","sourceRoot":"","sources":["../../src/transform/slardar.ts"],"names":[],"mappings":";;AAiHA,kCAiBC;AAlHD;;;GAGG;AACH,SAAS,6BAA6B,CAAC,UAAkB;IACvD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiCH,UAAU,KAAK,CAAC;AACtB,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAW,EAAE,UAAkB;IACzD,OAAO;;gGAEuF,GAAG,eAAe,UAAU;;;mBAGzG,UAAU;iBACZ,UAAU;;;;iBAIV,UAAU;kBACT,GAAG;;;;iBAIJ,UAAU;;;;;mBAKR,UAAU;;;;;;;;GAQ1B,CAAC;AACJ,CAAC;AAED,SAAS,cAAc;IACrB,OAAO;;;;;;;;;;;;;;;;;;;GAmBN,CAAC;AACJ,CAAC;AAED,gEAAgE;AAChE,SAAgB,WAAW,CAAC,UAA0B,EAAE;IACtD,MAAM,EAAE,GAAG,GAAG,cAAc,EAAE,UAAU,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IACrE,OAAO;QACL,wCAAwC;QACxC,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,6BAA6B,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE;QAChG,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE;QAC1F;YACE,GAAG,EAAE,QAAQ;YACb,KAAK,EAAE;gBACL,GAAG,EAAE,gGAAgG;gBACrG,WAAW,EAAE,WAAW;gBACxB,KAAK,EAAE,IAAI;aACZ;YACD,QAAQ,EAAE,cAAc;SACzB;QACD,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE;KACxE,CAAC;AACJ,CAAC"}

package/lib/transform/view-context.d.ts

@@ -0,0 +1,27 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { IncomingMessage } from 'node:http';
+import type { HtmlTagDescriptor } from '../html-tags';
+export interface RequestRenderContext {
+    userId: string;
+    tenantId: number | string;
+    userName: string;
+    csrfToken: string;
+    environment: string;
+}
+/** dev 期把每个请求的 render context 绑到这条异步链，transformIndexHtml 读出。 */
+export declare const requestContext: AsyncLocalStorage<RequestRenderContext>;
+/** 从 incoming request 抽出 server 端能拿到的 view-context 字段。 */
+export declare function buildRenderContext(req: IncomingMessage): RequestRenderContext;
+export interface ViewContextOptions {
+    /** appId override；未设则 dev 走 IIFE 从 URL 解析（prod/无 base path 时用）。 */
+    appId?: string;
+}
+/**
+ * view-context inline 脚本 tag。
+ * - build：HBS 占位符（vefaas 渲染替真值）
+ * - dev + ctx：请求上下文真值字面量
+ * - dev 无 ctx：IIFE fallback
+ * head-prepend 且排在 slardar 之前 —— 保证 slardar onload 时 window.tenantId 已就绪。
+ */
+export declare function viewContextTag(mode: 'build' | 'dev', opts?: ViewContextOptions, ctx?: RequestRenderContext): HtmlTagDescriptor;
+//# sourceMappingURL=view-context.d.ts.map

package/lib/transform/view-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-context.d.ts","sourceRoot":"","sources":["../../src/transform/view-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAqBtD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,gEAAgE;AAChE,eAAO,MAAM,cAAc,yCAAgD,CAAC;AA0B5E,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,oBAAoB,CAS7E;AAED,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAwDD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,GAAG,KAAK,EACrB,IAAI,GAAE,kBAAuB,EAC7B,GAAG,CAAC,EAAE,oBAAoB,GACzB,iBAAiB,CAQnB"}

package/lib/transform/view-context.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestContext = void 0;
+exports.buildRenderContext = buildRenderContext;
+exports.viewContextTag = viewContextTag;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * 启动期上下文注入：把 appId/userId/tenantId 等挂到 `window`，供业务代码与 slardar 读。
+ * 能力对齐 `@lark-apaas/coding-preset-vite-react` 的 view-context 插件。
+ *
+ * 三条路径：
+ *   - build：emit `{{tenantId}}` 等 HBS 占位符，部署运行时 (vefaas) 替真值
+ *   - dev + request ctx：解析 suda-webuser header / cookie 拼真值字面量
+ *   - dev 无 ctx：IIFE fallback（csrfToken 从 cookie 读、id 类全空）
+ */
+const SUDA_HEADER = 'x-larkgw-suda-webuser';
+/** dev 期把每个请求的 render context 绑到这条异步链，transformIndexHtml 读出。 */
+exports.requestContext = new node_async_hooks_1.AsyncLocalStorage();
+function parseSudaWebUser(header) {
+    if (typeof header !== 'string' || !header)
+        return null;
+    try {
+        return JSON.parse(decodeURIComponent(header));
+    }
+    catch {
+        return null;
+    }
+}
+function parseCsrfToken(cookieHeader) {
+    if (!cookieHeader)
+        return '';
+    const m = cookieHeader.match(/(?:^|;\s*)suda-csrf-token=([^;]+)/);
+    return m ? decodeURIComponent(m[1]) : '';
+}
+/**
+ * dev 期 environment 来源：`process.env.FORCE_FRAMEWORK_ENVIRONMENT`，未设兜底 'online'。
+ * 不感知域名——技术栈不应依赖 host 推断部署环境。
+ */
+function readDevEnvironment() {
+    const v = process.env.FORCE_FRAMEWORK_ENVIRONMENT;
+    return v && v.trim() ? v.trim() : 'online';
+}
+/** 从 incoming request 抽出 server 端能拿到的 view-context 字段。 */
+function buildRenderContext(req) {
+    const user = parseSudaWebUser(req.headers[SUDA_HEADER]);
+    return {
+        userId: user?.user_id ?? '',
+        tenantId: user?.tenant_id ?? '',
+        userName: user?.user_name?.zh_cn ?? '',
+        csrfToken: parseCsrfToken(req.headers.cookie),
+        environment: readDevEnvironment(),
+    };
+}
+function appIdExpr(appId) {
+    if (appId)
+        return JSON.stringify(appId);
+    return `(function () {
+        var p = location.pathname.match(/\\/app\\/(app_[a-z0-9]+)/i);
+        if (p) return p[1];
+        var h = location.hostname.match(/app_[a-z0-9]+/i);
+        return h ? h[0] : '';
+      })()`;
+}
+/** dev 有 request context：全字面量真值。 */
+function viewContextFromRequest(opts, ctx) {
+    return `
+    window.appId = ${appIdExpr(opts.appId)};
+    window.userId = ${JSON.stringify(ctx.userId)};
+    window.tenantId = ${JSON.stringify(ctx.tenantId)};
+    window.userName = ${JSON.stringify(ctx.userName)};
+    window.csrfToken = ${JSON.stringify(ctx.csrfToken)};
+    window.ENVIRONMENT = ${JSON.stringify(ctx.environment)};
+  `;
+}
+/**
+ * build：emit HBS 占位符，由部署运行时 (vefaas) 替换为真值。
+ *
+ * 与 preset 的差异：html stack **不** emit `window._appInfo`（preset 给 React 业务代码用，
+ * html stack 不消费），appName/appDescription/appAvatar 由 og-meta 注入到 meta 标签即可。
+ */
+function viewContextPlaceholders() {
+    return `
+    window.appId = "{{appId}}";
+    window.userId = "{{userId}}";
+    window.tenantId = "{{tenantId}}";
+    window.userName = "{{userName}}";
+    window.csrfToken = "{{csrfToken}}";
+    window.ENVIRONMENT = "{{environment}}";
+  `;
+}
+/** dev 无 request context（极少触发）：IIFE fallback，id 类全空。 */
+function viewContextDevFallback(opts) {
+    return `
+    window.appId = ${appIdExpr(opts.appId)};
+    window.userId = '';
+    window.tenantId = '';
+    window.userName = '';
+    window.csrfToken = (function () {
+      var m = document.cookie.match(/(?:^|;\\s*)suda-csrf-token=([^;]+)/);
+      return m ? decodeURIComponent(m[1]) : '';
+    })();
+    window.ENVIRONMENT = ${JSON.stringify(readDevEnvironment())};
+  `;
+}
+/**
+ * view-context inline 脚本 tag。
+ * - build：HBS 占位符（vefaas 渲染替真值）
+ * - dev + ctx：请求上下文真值字面量
+ * - dev 无 ctx：IIFE fallback
+ * head-prepend 且排在 slardar 之前 —— 保证 slardar onload 时 window.tenantId 已就绪。
+ */
+function viewContextTag(mode, opts = {}, ctx) {
+    const children = mode === 'build'
+        ? viewContextPlaceholders()
+        : ctx
+            ? viewContextFromRequest(opts, ctx)
+            : viewContextDevFallback(opts);
+    return { tag: 'script', children, injectTo: 'head-prepend' };
+}
+//# sourceMappingURL=view-context.js.map

package/lib/transform/view-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-context.js","sourceRoot":"","sources":["../../src/transform/view-context.ts"],"names":[],"mappings":"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"}

package/lib/vite-config.d.ts

@@ -0,0 +1,24 @@
+import type { InlineConfig } from 'vite';
+export interface HtmlViteOptions {
+    /** 静态根目录（相对 cwd），默认 'src'。 */
+    root?: string;
+    /** dev server 端口，默认 `CLIENT_DEV_PORT` env 或 8001。 */
+    port?: number;
+    /** 绑定 host，默认 '0.0.0.0'。 */
+    host?: string;
+}
+/**
+ * html stack 的 vite dev 配置（仅 dev 用，build 不走 vite）。
+ *
+ * - 绑 0.0.0.0、`allowedHosts: true`（= 网关任意 Host）、不设 `base`（prefix 由网关剥）。
+ * - HMR 走 vite 的 WS：`MIAODA_WS_HOST` 存在时切独立 WS 域名（对齐 vite-react 网关方案）。
+ * - `appType: 'mpa'`：纯静态多页，不做 SPA history fallback。
+ * - 内置 health + 平台注入 + WS 韧性插件（vite-client-patch / ws-watchdog）。
+ *
+ * 沙箱 WS 韧性（dev only，对齐 coding-preset-vite-react）：
+ * - `viteClientPatchPlugin`：删 WS 重连后的 `location.reload()`（休眠唤醒白屏），
+ *   并在 `MIAODA_HMR_WS_TOKEN` 存在时给 HMR 长链 URL 追加 `sandbox_token`（穿网关鉴权）。
+ * - `wsWatchdogPlugin`：检测僵尸 WS，判死后 postMessage 通知沙箱外壳。
+ */
+export declare function createHtmlViteConfig(opts?: HtmlViteOptions): InlineConfig;
+//# sourceMappingURL=vite-config.d.ts.map

package/lib/vite-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-config.d.ts","sourceRoot":"","sources":["../src/vite-config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAkBzC,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,eAAoB,GAAG,YAAY,CAoC7E"}

package/lib/vite-config.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHtmlViteConfig = createHtmlViteConfig;
+const node_path_1 = __importDefault(require("node:path"));
+const health_1 = require("./plugins/health");
+const inject_1 = require("./plugins/inject");
+const vite_client_patch_1 = require("./plugins/vite-client-patch");
+const ws_watchdog_1 = require("./plugins/ws-watchdog");
+/**
+ * 标准化 base path（路径语义，强制 `/` 前缀、去尾斜杠）：
+ *   '' / undefined / '/' → ''；'foo' → '/foo'；'/app/x/' → '/app/x'。
+ * 语义对齐 `@lark-apaas/coding-preset-vite-react` 的 normalizeBasePath。
+ */
+function normalizeBasePath(input) {
+    if (!input)
+        return '';
+    const p = input.trim();
+    if (!p || p === '/')
+        return '';
+    return (p.startsWith('/') ? p : '/' + p).replace(/\/+$/, '');
+}
+/**
+ * html stack 的 vite dev 配置（仅 dev 用，build 不走 vite）。
+ *
+ * - 绑 0.0.0.0、`allowedHosts: true`（= 网关任意 Host）、不设 `base`（prefix 由网关剥）。
+ * - HMR 走 vite 的 WS：`MIAODA_WS_HOST` 存在时切独立 WS 域名（对齐 vite-react 网关方案）。
+ * - `appType: 'mpa'`：纯静态多页，不做 SPA history fallback。
+ * - 内置 health + 平台注入 + WS 韧性插件（vite-client-patch / ws-watchdog）。
+ *
+ * 沙箱 WS 韧性（dev only，对齐 coding-preset-vite-react）：
+ * - `viteClientPatchPlugin`：删 WS 重连后的 `location.reload()`（休眠唤醒白屏），
+ *   并在 `MIAODA_HMR_WS_TOKEN` 存在时给 HMR 长链 URL 追加 `sandbox_token`（穿网关鉴权）。
+ * - `wsWatchdogPlugin`：检测僵尸 WS，判死后 postMessage 通知沙箱外壳。
+ */
+function createHtmlViteConfig(opts = {}) {
+    const root = node_path_1.default.resolve(opts.root ?? 'src');
+    // Number.isFinite 兜底：?? 只挡 null/undefined，挡不住 NaN（防 opts.port 传入脏值）
+    const port = Number.isFinite(opts.port) ? opts.port : Number(process.env.CLIENT_DEV_PORT) || 8001;
+    const host = opts.host ?? '0.0.0.0';
+    // 沙箱网关把 `/app/<id>` 前缀透传给 vite 时，watchdog 的 <script src>、middleware
+    // 匹配路径、以及客户端 import 的 `/@vite/client` 都必须带同一前缀；空串退化到裸路径。
+    const clientBasePath = normalizeBasePath(process.env.CLIENT_BASE_PATH);
+    // 从 `/app/<appId>` 形态的 base path 提取 appId 给 view-context 拼真值；非该形态则
+    // 留空，view-context dev 退化为从 URL 解析。
+    const appId = /^\/app\/[^/]/.test(clientBasePath)
+        ? clientBasePath.split('/').pop()
+        : undefined;
+    return {
+        root,
+        appType: 'mpa',
+        clearScreen: false,
+        server: {
+            host,
+            port,
+            strictPort: true,
+            cors: true,
+            allowedHosts: true,
+            hmr: process.env.MIAODA_WS_HOST
+                ? { protocol: 'wss', host: process.env.MIAODA_WS_HOST, clientPort: 443, path: '/ws' }
+                : { path: '/ws' },
+        },
+        plugins: [
+            (0, health_1.healthPlugin)(),
+            (0, inject_1.platformInjectPlugin)({ appId }),
+            // dev only：apply:'serve' 自带，build 不挂
+            (0, vite_client_patch_1.viteClientPatchPlugin)(),
+            (0, ws_watchdog_1.wsWatchdogPlugin)({ clientBasePath }),
+        ],
+    };
+}
+//# sourceMappingURL=vite-config.js.map

package/lib/vite-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-config.js","sourceRoot":"","sources":["../src/vite-config.ts"],"names":[],"mappings":";;;;;AAyCA,oDAoCC;AA7ED,0DAA6B;AAE7B,6CAAgD;AAChD,6CAAwD;AACxD,mEAAoE;AACpE,uDAAyD;AAEzD;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAyB;IAClD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvB,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC;IAC/B,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC/D,CAAC;AAWD;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAAC,OAAwB,EAAE;IAC7D,MAAM,IAAI,GAAG,mBAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC;IAC9C,oEAAoE;IACpE,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,IAAe,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC;IAC9G,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC;IACpC,oEAAoE;IACpE,yDAAyD;IACzD,MAAM,cAAc,GAAG,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACvE,mEAAmE;IACnE,mCAAmC;IACnC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC;QAC/C,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE;QACjC,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,KAAK;QAClB,MAAM,EAAE;YACN,IAAI;YACJ,IAAI;YACJ,UAAU,EAAE,IAAI;YAChB,IAAI,EAAE,IAAI;YACV,YAAY,EAAE,IAAI;YAClB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;gBAC7B,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE;gBACrF,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE;SACpB;QACD,OAAO,EAAE;YACP,IAAA,qBAAY,GAAE;YACd,IAAA,6BAAoB,EAAC,EAAE,KAAK,EAAE,CAAC;YAC/B,qCAAqC;YACrC,IAAA,yCAAqB,GAAE;YACvB,IAAA,8BAAgB,EAAC,EAAE,cAAc,EAAE,CAAC;SACrC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lark-apaas/coding-html-devserver",
+  "version": "0.1.0",
+  "description": "Dev/build toolchain for the miaoda-coding html (pure HTML) stack. Wraps vite (dev + HMR) behind a bin so the template never sees vite; build is pure-copy + platform-script injection + optional minify.",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "bin": "./bin/coding-html-devserver.js",
+  "files": [
+    "lib",
+    "bin",
+    "src/runtime"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "html-minifier-terser": "^7.2.0",
+    "vite": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/html-minifier-terser": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "miaoda",
+    "coding",
+    "devserver",
+    "html",
+    "vite"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/src/runtime/ws-watchdog-client.mjs

@@ -0,0 +1,148 @@
+/* eslint-env browser */
+
+/**
+ * WebSocket Watchdog Client。在 Vite 沙箱 iframe 内自启动；
+ * 通过 createHotContext 走 HMR 通道发 ping/收 pong；判死后 postMessage 给 parent。
+ *
+ * 设计 spec: docs/superpowers/specs/2026-04-27-sandbox-ws-watchdog-design.md
+ */
+
+/**
+ * @typedef {Object} WatchdogDeps
+ * @property {(event: string, data: unknown) => void} sendCustom
+ * @property {(event: string, cb: (data: unknown) => void) => void} onCustom
+ * @property {(status: 'connected' | 'disconnected') => void} postStatus
+ * @property {(handler: () => void, ms: number) => number} setInterval
+ * @property {(handle: number) => void} clearInterval
+ */
+
+/**
+ * @typedef {Object} WatchdogOptions
+ * @property {number} [intervalMs]        默认 5000
+ * @property {number} [missThreshold]     默认 2
+ * @property {number} [echoFreshnessMs]   默认 15000
+ * @property {string} [pingEvent]         默认 'ws-watchdog:ping'
+ * @property {string} [pongEvent]         默认 'ws-watchdog:pong'
+ */
+
+/**
+ * 不返回 dispose——watchdog 跟 iframe 同生命周期，无独立销毁路径。
+ * @param {WatchdogDeps} deps
+ * @param {WatchdogOptions} [options]
+ */
+export function createWatchdog(deps, options = {}) {
+  const intervalMs = options.intervalMs ?? 5000;
+  const missThreshold = options.missThreshold ?? 2;
+  const echoFreshnessMs = options.echoFreshnessMs ?? 15000;
+  const pingEvent = options.pingEvent ?? 'ws-watchdog:ping';
+  const pongEvent = options.pongEvent ?? 'ws-watchdog:pong';
+
+  let missed = 0;
+  /** @type {'connected' | 'disconnected'} */
+  let reportedStatus = 'connected';
+  let pingSeq = 0;
+  /** @type {Map<number, number>} seq → wall-clock 时间戳 */
+  const recentPings = new Map();
+
+  function onTick() {
+    // missed++ 必须先于 sendCustom：发送侧抛错时 missed 已累加，下一 tick 仍能判死。
+    missed += 1;
+    const seq = ++pingSeq;
+    const now = Date.now();
+    recentPings.set(seq, now);
+    for (const [s, ts] of recentPings) {
+      if (now - ts > echoFreshnessMs) recentPings.delete(s);
+    }
+    deps.sendCustom(pingEvent, { t: seq });
+    if (missed >= missThreshold && reportedStatus !== 'disconnected') {
+      deps.postStatus('disconnected');
+      reportedStatus = 'disconnected';
+    }
+  }
+
+  deps.onCustom(pongEvent, (raw) => {
+    const data = /** @type {{ echo?: number } | undefined} */ (raw);
+    if (typeof data?.echo !== 'number' || !recentPings.has(data.echo)) return;
+    recentPings.delete(data.echo);
+    missed = 0;
+    if (reportedStatus !== 'connected') {
+      deps.postStatus('connected');
+      reportedStatus = 'connected';
+    }
+  });
+
+  deps.setInterval(onTick, intervalMs);
+}
+
+// postMessage 的 targetOrigin 必须显式指定，禁止用 '*'。
+
+const PARENT_ORIGIN_KEY = '__parentOrigin';
+
+function getParentOriginFromParams() {
+  try {
+    const origin = new URLSearchParams(window.location.search).get(PARENT_ORIGIN_KEY);
+    if (origin) {
+      try { sessionStorage.setItem(PARENT_ORIGIN_KEY, origin); } catch { /* 忽略 */ }
+      return origin;
+    }
+  } catch { /* 忽略 URL 解析失败 */ }
+  try { return sessionStorage.getItem(PARENT_ORIGIN_KEY) || undefined; }
+  catch { return undefined; }
+}
+
+function getLegacyParentOrigin() {
+  const { origin } = window.location;
+  if (origin.includes('force.feishuapp.net')) return 'https://force.feishu.cn';
+  if (origin.includes('force-pre.feishuapp.net')) return 'https://force.feishu-pre.cn';
+  if (origin.includes('force.byted.org')) return 'https://force.feishu-boe.cn';
+  if (origin.includes('feishuapp.cn') || origin.includes('miaoda.feishuapp.net')) return 'https://miaoda.feishu.cn';
+  if (origin.includes('fsapp.kundou.cn') || origin.includes('miaoda-pre.feishuapp.net')) return 'https://miaoda.feishu-pre.cn';
+  return 'https://miaoda.feishu-boe.cn';
+}
+
+function resolveParentOrigin() {
+  const paramOrigin = getParentOriginFromParams();
+  if (paramOrigin) return paramOrigin;
+  // plugin middleware 在送出脚本时把这个 token 编译期替换成字符串字面量。
+  return process.env.FORCE_FRAMEWORK_DOMAIN_MAIN || getLegacyParentOrigin();
+}
+
+function postStatus(status) {
+  try {
+    const origin = resolveParentOrigin();
+    if (!origin) return;
+    window.parent.postMessage(
+      { type: 'DevServerMessage', data: { type: 'devServer-status', status } },
+      origin,
+    );
+  } catch (e) {
+    console.error('[fullstack-ws-watchdog] postMessage error:', e);
+  }
+}
+
+// 仅在 iframe 内自启动；jsdom（vitest）下 window.parent === window 自然跳过。
+// 直出的 raw module 拿不到 import.meta.hot，所以借 createHotContext 走 HMR 通道。
+// CLIENT_BASE_PATH 由 plugin 编译期替换；缺前缀会被网关 404。
+const CLIENT_BASE_PATH = process.env.CLIENT_BASE_PATH || '';
+
+if (typeof window !== 'undefined' && window.parent !== window) {
+  (async () => {
+    try {
+      const { createHotContext } = await import(CLIENT_BASE_PATH + '/@vite/client');
+      const hot = createHotContext(CLIENT_BASE_PATH + '/@ws-watchdog.js');
+      createWatchdog({
+        sendCustom: (event, data) => {
+          // 断连时 hot.send 可能抛；吞掉即可——missed 已在 onTick 顶部累加。
+          try { hot.send(event, data); }
+          catch (e) { console.warn('[fullstack-ws-watchdog] send failed:', e); }
+        },
+        onCustom: (event, cb) => hot.on(event, cb),
+        postStatus,
+        setInterval: (handler, ms) => window.setInterval(handler, ms),
+        clearInterval: (handle) => window.clearInterval(handle),
+      });
+    } catch (e) {
+      console.warn('[fullstack-ws-watchdog] bootstrap failed:', e);
+    }
+  })();
+}