@proteus-vue/render-backend 0.3.0-beta.28 → 0.3.0-beta.31

package/dist/index.d.ts

@@ -56,6 +56,8 @@ export type { ScreenCommandLike, ScreenTreeHost, ScreenAnimHost, RouteTransition
 export { createHostScreenPorts, SCREEN_ANIM_DONE_KEY } from './screen-executor-host';
 export { createScreenRuntime } from './screen-runtime';
 export type { ScreenRuntime, ScreenRuntimeInstance, ScreenRuntimeArtifact, CreateScreenRuntimeOptions } from './screen-runtime';
+export { createRuntimeProfiler, NULL_PROFILER } from './runtime-profiler';
+export type { RuntimeProfiler, ProfEntry } from './runtime-profiler';
 export { HOST_INVOKE_METHODS, HOST_SCREEN_METHODS, HOST_CAPABILITY_METHODS, HOST_METHOD_OPTIONAL } from './host-invoke-contract';
 export { TAB_BAR_SPEC } from './tab-bar-spec';
 export type { TabBarSpec } from './tab-bar-spec';

package/dist/index.js

@@ -3434,6 +3434,7 @@ function instantiateTemplate(tpl, opts) {
     }
     if (n.tag) out.tag = n.tag;
     if (n.component) out.component = n.component;
+    if (n.loc) out.loc = n.loc;
     if (n.slotOutlet) out.slotOutlet = n.slotOutlet;
     if (n.slotFor) out.slotFor = n.slotFor;
     out.id = id + idOffset;
@@ -7277,6 +7278,46 @@ function createHostScreenPorts(opts) {
   };
 }
 
+// src/runtime-profiler.ts
+var NULL_PROFILER = {
+  time: (_label, fn) => fn(),
+  drain: () => []
+};
+var round1 = (v) => Math.round(v * 10) / 10;
+function createRuntimeProfiler() {
+  const perf = globalThis.performance;
+  const now = perf && typeof perf.now === "function" ? () => perf.now() : () => Date.now();
+  const acc = /* @__PURE__ */ new Map();
+  return {
+    time(label, fn, loc) {
+      const t0 = now();
+      try {
+        return fn();
+      } finally {
+        const ms = now() - t0;
+        let e = acc.get(label);
+        if (!e) {
+          e = { count: 0, totalMs: 0, maxMs: 0 };
+          acc.set(label, e);
+        }
+        e.count += 1;
+        e.totalMs += ms;
+        if (ms > e.maxMs) e.maxMs = ms;
+        if (loc && !e.loc) e.loc = loc;
+      }
+    },
+    drain() {
+      const out = [];
+      for (const [label, e] of acc) {
+        out.push({ label, count: e.count, totalMs: round1(e.totalMs), maxMs: round1(e.maxMs), ...e.loc ? { loc: e.loc } : {} });
+      }
+      acc.clear();
+      out.sort((a, b) => b.totalMs - a.totalMs);
+      return out;
+    }
+  };
+}
+
 // src/screen-runtime.ts
 function createScreenRuntime(opts) {
   const base = opts.contentIdBase;
@@ -7286,12 +7327,13 @@ function createScreenRuntime(opts) {
   function make(name) {
     const art = opts.artifacts[name];
     if (!art) throw new Error(`[screen-runtime] \u65E0\u8BE5\u5C4F\u4EA7\u7269\uFF1A${name}`);
+    const prof = opts.profile ? createRuntimeProfiler() : NULL_PROFILER;
     const data = { ...art.data, ...opts.seedData?.[name] ?? {} };
     const read = (n) => data[n];
-    let inst = instantiateTemplate(art.tpl, { viewport: opts.viewport, read, table: art.table, registry: new ListRegistry() });
+    let inst = prof.time("instantiate", () => instantiateTemplate(art.tpl, { viewport: opts.viewport, read, table: art.table, registry: new ListRegistry() }));
     let localIdsOrdered = inst.nodes.map((n) => n.id);
     function rebuild() {
-      inst = instantiateTemplate(art.tpl, { viewport: opts.viewport, read, table: art.table, registry: new ListRegistry() });
+      inst = prof.time("instantiate", () => instantiateTemplate(art.tpl, { viewport: opts.viewport, read, table: art.table, registry: new ListRegistry() }));
       localIdsOrdered = inst.nodes.map((n) => n.id);
     }
     if (inst.stats.componentNodes === 0 && inst.nodes.some((n) => n.component)) {
@@ -7306,10 +7348,16 @@ function createScreenRuntime(opts) {
     const evalCtx = { read };
     vapor.load(evalCtx, () => {
     });
-    vapor.relink(evalCtx);
-    slotRt.flush();
+    prof.time("relink", () => vapor.relink(evalCtx));
+    prof.time("flush", () => slotRt.flush());
     const byNodeEvent = indexEventBindings(art.events);
     const dispatchState = createDispatchState();
+    const locByHandler = /* @__PURE__ */ new Map();
+    for (const e of art.events ?? []) {
+      const b = e;
+      if (b.handler && b.loc) locByHandler.set(b.handler, b.loc);
+    }
+    const handlerErrors = [];
     function runHandler(handlerName, _nodeId, payload) {
       const acts = art.handlers[handlerName];
       if (!acts) return false;
@@ -7325,7 +7373,20 @@ function createScreenRuntime(opts) {
           continue;
         }
         const ctx2 = { read: (n) => n === "$event" ? payload : data[n] };
-        const v = evalExpr(a.program, ctx2);
+        let v;
+        try {
+          v = prof.time(`handler\u300C${handlerName}\u300D`, () => evalExpr(a.program, ctx2), locByHandler.get(handlerName));
+        } catch (e) {
+          const msg = String(e?.message ?? e);
+          const loc = locByHandler.get(handlerName);
+          const at = loc ? `\uFF08\u6A21\u677F ${name}.vue:${loc.line}:${loc.column}\uFF09` : "";
+          const detail = `[screen-runtime] ${name}: handler\u300C${handlerName}\u300D\u8282\u70B9 #${_nodeId}${at} \u8868\u8FBE\u5F0F \`${a.source ?? "(?)"}\` \u6C42\u503C\u5931\u8D25\uFF1A${msg}`;
+          handlerErrors.push(detail);
+          if (handlerErrors.length > 50) handlerErrors.shift();
+          note(detail);
+          opts.onError?.(detail);
+          continue;
+        }
         if (!a.source) continue;
         if (a.op === "add") {
           const cur = data[a.source];
@@ -7343,8 +7404,8 @@ function createScreenRuntime(opts) {
     }
     function refreshData() {
       rebuild();
-      vapor.relink(evalCtx);
-      slotRt.flush();
+      prof.time("relink", () => vapor.relink(evalCtx));
+      prof.time("flush", () => slotRt.flush());
     }
     return {
       content() {
@@ -7352,12 +7413,17 @@ function createScreenRuntime(opts) {
       },
       dispatch(type, chain) {
         const localChain = chain.map(localIdOf);
-        const r = dispatchGesture(localChain, type, byNodeEvent, dispatchState, (h, id) => runHandler(h, id));
+        const fired = [];
+        const r = prof.time("dispatch", () => dispatchGesture(localChain, type, byNodeEvent, dispatchState, (h, id) => {
+          const ok = runHandler(h, id);
+          if (ok) fired.push({ handler: h, nodeId: id, ...locByHandler.has(h) ? { loc: locByHandler.get(h) } : {} });
+          return ok;
+        }));
         if (r.fired.length > 0) refreshData();
-        return { handled: r.fired.length > 0, fired: r.fired };
+        return { handled: r.fired.length > 0, fired: r.fired, firedHandlers: fired };
       },
       flush() {
-        slotRt.flush();
+        prof.time("flush", () => slotRt.flush());
       },
       refresh() {
         refreshData();
@@ -7367,6 +7433,14 @@ function createScreenRuntime(opts) {
       },
       snapshot() {
         return { ...data };
+      },
+      handlerErrors() {
+        const out = handlerErrors.slice();
+        handlerErrors.length = 0;
+        return out;
+      },
+      profileStats() {
+        return prof.drain();
       }
     };
   }
@@ -7385,6 +7459,15 @@ function createScreenRuntime(opts) {
       const out = {};
       for (const [name, it] of instances) out[name] = it.snapshot();
       return out;
+    },
+    /** ★★★排空各屏阶段耗时（CPU Profiler · 决策 #715）——按屏归并（每屏只在其有数据时出现）。 */
+    profileStats() {
+      const out = {};
+      for (const [name, it] of instances) {
+        const entries = it.profileStats();
+        if (entries.length > 0) out[name] = entries;
+      }
+      return out;
     }
   };
 }
@@ -7459,7 +7542,10 @@ function createSuperappRuntime(opts) {
     viewport: opts.viewport,
     ...opts.navigate ? { navigate: opts.navigate } : {},
     ...opts.seedData ? { seedData: opts.seedData } : {},
-    onNote: note
+    onNote: note,
+    ...opts.onError ? { onError: opts.onError } : {},
+    ...opts.profile ? { profile: true } : {}
+    // ★CPU Profiler（决策 #715）
   });
   let cur = "";
   let lastHostReply = null;
@@ -7476,9 +7562,18 @@ function createSuperappRuntime(opts) {
       note(`[superapp-runtime] \u624B\u52BF\u94FE JSON \u89E3\u6790\u5931\u8D25\uFF1A${String(chainJson).slice(0, 40)}`);
     }
     const r = dispatch(type, chain);
-    devEvents.push({ type, id: kernelId, chain, handled: r.handled, fired: r.fired, time: Date.now() });
+    const srcLoc = r.firedHandlers?.find((h) => h.loc)?.loc;
+    devEvents.push({
+      type,
+      id: kernelId,
+      chain,
+      handled: r.handled,
+      fired: r.fired,
+      time: Date.now(),
+      ...srcLoc ? { src: `${cur}.vue:${srcLoc.line}:${srcLoc.column}` } : {}
+    });
     if (devEvents.length > 200) devEvents.shift();
-    return JSON.stringify(r);
+    return JSON.stringify({ ...r, screen: cur });
   };
   function hostOk(reply) {
     try {
@@ -7550,7 +7645,9 @@ function createSuperappRuntime(opts) {
     currentContent: () => {
       if (!cur) return null;
       try {
-        return rt.instance(cur).content();
+        const c = rt.instance(cur).content();
+        const file = opts.artifacts[cur]?.file;
+        return { ...c, screen: cur, ...file ? { file } : {} };
       } catch {
         return null;
       }
@@ -7561,6 +7658,10 @@ function createSuperappRuntime(opts) {
       devEvents.length = 0;
       return out;
     },
+    // ★排空式：当前屏页面处理器运行期错误（带模板源位置）——宿主 dev-watch 转发面板 Console。
+    handlerErrors: () => cur ? rt.instance(cur).handlerErrors() : [],
+    // ★排空式：运行期阶段耗时（CPU Profiler · 决策 #715）——宿主 dev-watch 取走随 /ping?perf= 上报。
+    profileStats: () => rt.profileStats(),
     snapshot: () => rt.snapshot(),
     lastHostReply: () => lastHostReply
   };
@@ -7581,6 +7682,7 @@ export {
   HOST_SCREEN_METHODS,
   Managed,
   ManagedRegistry,
+  NULL_PROFILER,
   OWNERSHIP_ERRORS,
   Owned,
   OwnershipError,
@@ -7621,6 +7723,7 @@ export {
   createQuotaManager,
   createQuotaTracker,
   createResourcePool,
+  createRuntimeProfiler,
   createScreenExecutor,
   createScreenRuntime,
   createSelfDrawBatchAdapter,

package/dist/runtime-profiler.d.ts

@@ -0,0 +1,34 @@
+/** 一条阶段采样（窗口内累加） */
+export interface ProfEntry {
+    /** 标签（`instantiate` / `flush` / `dispatch` / `handler「h0」`…） */
+    label: string;
+    /** 调用次数 */
+    count: number;
+    /** 累计耗时（ms；窗口内） */
+    totalMs: number;
+    /** 单次最长（ms） */
+    maxMs: number;
+    /** 模板源位置（handler 类才有；1 基，整份 `.vue` 行） */
+    loc?: {
+        line: number;
+        column: number;
+    };
+}
+/** 阶段采样出口（宿主/dev server 取走即清——排空式） */
+export interface RuntimeProfiler {
+    /** 包一层计时：跑 `fn` 并把它耗时累加到 `label`（`loc` 仅首见记录）。 */
+    time<T>(label: string, fn: () => T, loc?: {
+        line: number;
+        column: number;
+    }): T;
+    /** 读并**清零**本窗口（按累计耗时降序）。 */
+    drain(): ProfEntry[];
+}
+/** 空实现（未启用 profiling 时用——`time` 直接透传，零开销）。 */
+export declare const NULL_PROFILER: RuntimeProfiler;
+/**
+ * 建一个阶段采样器。`now()` 优先用 `performance.now()`（亚毫秒），无则回落 `Date.now()`（ms）。
+ *   ★诚实边界：`Date.now()` 的毫秒分辨率会把"微秒级 handler"记成 0ms——**不影响找热点**
+ *   （热点本就是 ms 级），但别把 0 读成"绝对没花时间"。
+ */
+export declare function createRuntimeProfiler(): RuntimeProfiler;

package/dist/screen-runtime.d.ts

@@ -1,4 +1,5 @@
 import type { LayoutTemplate, SubscriptionTable, EventBinding, DispatchState } from '@proteus-vue/slot-runtime';
+import { type ProfEntry } from './runtime-profiler';
 /** 一屏的运行期产物（与 `packages/cli/src/app-runtime-content.ts` 的 `ScreenRuntimeArtifact` 同形） */
 export interface ScreenRuntimeArtifact {
     tpl: LayoutTemplate;
@@ -40,11 +41,24 @@ export interface CreateScreenRuntimeOptions {
     seedData?: Record<string, Record<string, unknown>>;
     /** 诊断出口（不静默） */
     onNote?: (note: string) => void;
+    /**
+     * ★★★**页面处理器运行期错误出口**（决策 #712）——handler 表达式求值失败时逐条调用（带**模板源位置**）。
+     *   与 `onNote` 分开：note 是"诊断信息"（console.log 级），本出口是**用户代码出错**
+     *   （宿主/桥应转发到面板 Console 的 `error` 级 + 如实回传，不得静默吞掉）。
+     *   缺省 ⇒ 仅落进 `handlerErrors()` 排空缓冲（仍可读，不静默）。
+     */
+    onError?: (error: string) => void;
     /**
      * ★导航出口（B1）：handler 里的 `$nav('目标')` 动作 → 交给宿主/装配层执行导航
      *   （App 壳 = `router.push(target)`；与 `<navigator>` 同语义）。缺省 ⇒ 只记 note（不静默）。
      */
     navigate?: (target: string) => void;
+    /**
+     * ★★★**运行期阶段耗时自采样**（CPU Profiler · 决策 #715）——dev 构建开启：给 `instantiate` /
+     *   `flush` / `dispatch` / 每个 handler 计时，归因"卡在哪一段"。缺省 false ⇒ **零开销**（空实现）。
+     *   采样经 `profileStats()` 排空 ⇒ 宿主每 tick 取走（随 `/ping?perf=` 上报面板）。
+     */
+    profile?: boolean;
 }
 /** 一屏的运行期实例（挂载 + 事件 + 增量） */
 export interface ScreenRuntimeInstance {
@@ -60,6 +74,15 @@ export interface ScreenRuntimeInstance {
     dispatch(type: string, chain: readonly number[], state?: DispatchState): {
         handled: boolean;
         fired: number[];
+        /** ★跑了哪些 handler + 各自**模板源位置**（决策 #712·source map）——面板 Events 锚回 `.vue:line:col` */
+        firedHandlers?: Array<{
+            handler: string;
+            nodeId: number;
+            loc?: {
+                line: number;
+                column: number;
+            };
+        }>;
     };
     /** 立即把脏槽位编成指令并交给 `applyOps`（确定性驱动入口） */
     flush(): void;
@@ -73,6 +96,17 @@ export interface ScreenRuntimeInstance {
     data(): Record<string, unknown>;
     /** ★跨调用状态导出（浅拷贝）——供宿主（一次性 VM）在下次调用回灌为 `seedData`（见 CreateScreenRuntimeOptions.seedData） */
     snapshot(): Record<string, unknown>;
+    /**
+     * ★★★**排空本屏页面处理器错误**（决策 #712）——自上次调用以来的 handler 求值失败（带模板源位置）。
+     *   排空式（取走即清）：供宿主 dev-watch / 面板 Console 消费（与 `SuperappRuntime.devEvents` 同形态）。
+     */
+    handlerErrors(): string[];
+    /**
+     * ★★★**排空本屏运行期阶段耗时**（CPU Profiler · 决策 #715）——自上次调用以来的阶段采样
+     *   （`instantiate` / `relink` / `flush` / `dispatch` / `handler「hN」`，按累计耗时降序）。
+     *   排空式；未启用 profiling（`profile` 未开）⇒ 恒空数组。
+     */
+    profileStats(): ProfEntry[];
 }
 export interface ScreenRuntime {
     /** 取（或按需创建）某屏的运行期实例 */
@@ -81,6 +115,8 @@ export interface ScreenRuntime {
     has(name: string): boolean;
     /** ★跨调用状态导出（`{屏名: 数据}`）——一次性 VM 宿主回灌用 */
     snapshot(): Record<string, Record<string, unknown>>;
+    /** ★★★排空**当前所有已建实例**的运行期阶段耗时（CPU Profiler · 决策 #715）——排空式、按屏归并。 */
+    profileStats(): Record<string, ProfEntry[]>;
 }
 /**
  * 创建 App 壳的统一运行期。

package/dist/superapp-runtime.d.ts

@@ -1,4 +1,5 @@
 import type { ScreenRuntimeArtifact } from './screen-runtime';
+import type { ProfEntry } from './runtime-profiler';
 /** 宿主原语（App 壳各端 `proteusHost` 的**子集**；平台无关形状） */
 export interface SuperappHostPorts {
     /** 建树 + 上屏（内核排版 + 宿主自绘）；返回宿主回执 JSON 串 */
@@ -40,6 +41,10 @@ export interface SuperappRuntimeOptions {
     seedData?: Record<string, Record<string, unknown>>;
     /** 诊断（不静默） */
     onNote?: (note: string) => void;
+    /** ★页面处理器运行期错误出口（决策 #712·source map）——转发给 `createScreenRuntime.onError`。 */
+    onError?: (error: string) => void;
+    /** ★★★**运行期阶段耗时自采样**（CPU Profiler · 决策 #715）——dev 构建开启；缺省零开销。 */
+    profile?: boolean;
 }
 export interface SuperappRuntime {
     /** 挂载（或重挂载）某屏：实例化 → `host.mount`；并记忆为"当前屏"（手势派发用） */
@@ -54,16 +59,27 @@ export interface SuperappRuntime {
     dispatchGesture(type: string, chain: readonly number[]): {
         handled: boolean;
         fired: number[];
+        firedHandlers?: Array<{
+            handler: string;
+            nodeId: number;
+            loc?: {
+                line: number;
+                column: number;
+            };
+        }>;
     };
     /** 当前屏名 */
     current(): string;
-    /** ★DevTools 元素内省（决策 #674）：当前屏**已实例化节点**（Template 实例化产物：id/parentId/tag/style/text）——供面板"元素"树。 */
+    /** ★DevTools 元素内省（决策 #674）：当前屏**已实例化节点**（Template 实例化产物：id/parentId/tag/style/text）——供面板"元素"树。
+     *  ★（决策 #713）`:file` = 当前屏源文件（dev 构建；面板据节点 `loc` 拼 `file:line:col`）。 */
     currentContent(): {
         viewport?: {
             width: number;
             height: number;
         };
         nodes: readonly unknown[];
+        screen?: string;
+        file?: string;
     } | null;
     /** ★DevTools 事件 trace（决策 #675）：自上次调用以来发生的手势派发（type/命中 id/冒泡链/handled/fired）——排空式。 */
     devEvents(): ReadonlyArray<{
@@ -72,8 +88,19 @@ export interface SuperappRuntime {
         chain: readonly number[];
         handled: boolean;
         fired: readonly number[];
+        src?: string;
         time: number;
     }>;
+    /**
+     * ★★★**排空当前屏页面处理器运行期错误**（决策 #712 · source map 生态链）——自上次调用以来的
+     *   handler 求值失败（带**模板源位置** `.vue:line:col`）。排空式，供宿主 dev-watch 转发面板 Console。
+     */
+    handlerErrors(): string[];
+    /**
+     * ★★★**排空运行期阶段耗时**（CPU Profiler · 决策 #715）——自上次调用以来的各屏阶段采样
+     *   （`{屏名: [{label,count,totalMs,maxMs,loc?}]}`，按累计耗时降序）。排空式；未开 profiling ⇒ 空。
+     */
+    profileStats(): Record<string, ProfEntry[]>;
     /** ★跨调用状态导出（`{屏名: 数据}`）——一次性 VM 宿主持有、下次回灌 `seedData` */
     snapshot(): Record<string, Record<string, unknown>>;
     /**

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@proteus-vue/render-backend",
-  "version": "0.3.0-beta.28",
+  "version": "0.3.0-beta.31",
   "description": "G-27 ProteusRenderBackend SPI：可插拔渲染后端接口 + conformance test + 官方后端原型（Headless/VueDom） + G-41 nodeOps Dispatcher——Render anywhere, on any engine（M1.4）",
   "type": "module",
   "license": "Apache-2.0",
   "dependencies": {
     "@proteus-vue/animation": "0.3.0-beta.28",
-    "@proteus-vue/component-ir": "0.3.0-beta.28",
+    "@proteus-vue/component-ir": "0.3.0-beta.31",
     "@proteus-vue/contracts": "0.3.0-beta.28",
     "@proteus-vue/router": "0.3.0-beta.28",
-    "@proteus-vue/slot-runtime": "0.3.0-beta.28"
+    "@proteus-vue/slot-runtime": "0.3.0-beta.31"
   },
   "peerDependencies": {
     "@vue/runtime-core": "^3.4.0"