@nocobase/flow-engine 2.1.0-alpha.4 → 2.1.0-alpha.40

package/lib/views/usePage.js

@@ -54,9 +54,106 @@ var import_viewEvents = require("./viewEvents");
 var import_provider = require("../provider");
 var import_ViewScopedFlowEngine = require("../ViewScopedFlowEngine");
 var import_variablesParams = require("../utils/variablesParams");
+var import_runViewBeforeClose = require("./runViewBeforeClose");
 let uuid = 0;
 const GLOBAL_EMBED_CONTAINER_ID = "nocobase-embed-container";
 const EMBED_REPLACING_DATA_KEY = "nocobaseEmbedReplacing";
+function isPromiseLike(value) {
+  return !!value && typeof value.then === "function";
+}
+__name(isPromiseLike, "isPromiseLike");
+function closeReplacingGlobalEmbed(target, activeView) {
+  target.dataset[EMBED_REPLACING_DATA_KEY] = "1";
+  try {
+    const closeResult = activeView.close();
+    if (isPromiseLike(closeResult)) {
+      return Promise.resolve(closeResult).finally(() => {
+        delete target.dataset[EMBED_REPLACING_DATA_KEY];
+      });
+    }
+    delete target.dataset[EMBED_REPLACING_DATA_KEY];
+    return closeResult;
+  } catch (error) {
+    delete target.dataset[EMBED_REPLACING_DATA_KEY];
+    throw error;
+  }
+}
+__name(closeReplacingGlobalEmbed, "closeReplacingGlobalEmbed");
+function createPendingGlobalEmbedView(openedPromise, inputArgs, preventClose) {
+  let openedPage;
+  const pendingActions = {};
+  const readyPromise = openedPromise.then(({ page }) => {
+    openedPage = page;
+    if (openedPage) {
+      if ("beforeClose" in pendingActions) {
+        openedPage.beforeClose = pendingActions.beforeClose;
+      }
+      if ("update" in pendingActions) {
+        openedPage.update(pendingActions.update);
+      }
+      if ("footer" in pendingActions) {
+        openedPage.setFooter(pendingActions.footer);
+      }
+      if ("header" in pendingActions) {
+        openedPage.setHeader(pendingActions.header);
+      }
+      if (pendingActions.destroyed) {
+        openedPage.destroy(pendingActions.destroyed.result);
+      }
+    }
+    return { page };
+  });
+  return Object.assign(
+    readyPromise.then(({ page }) => page ? page : false),
+    {
+      type: "embed",
+      inputArgs,
+      preventClose,
+      Header: null,
+      Footer: null,
+      get beforeClose() {
+        return (openedPage == null ? void 0 : openedPage.beforeClose) ?? pendingActions.beforeClose;
+      },
+      set beforeClose(value) {
+        if (openedPage) {
+          openedPage.beforeClose = value;
+        } else {
+          pendingActions.beforeClose = value;
+        }
+      },
+      close: /* @__PURE__ */ __name((result, force) => readyPromise.then(({ page }) => page ? page.close(result, force) : false), "close"),
+      destroy: /* @__PURE__ */ __name((result) => {
+        if (openedPage) {
+          openedPage.destroy(result);
+        } else {
+          pendingActions.destroyed = { result };
+        }
+      }, "destroy"),
+      update: /* @__PURE__ */ __name((newConfig) => {
+        if (openedPage) {
+          openedPage.update(newConfig);
+        } else {
+          pendingActions.update = { ...pendingActions.update, ...newConfig };
+        }
+      }, "update"),
+      setFooter: /* @__PURE__ */ __name((footer) => {
+        if (openedPage) {
+          openedPage.setFooter(footer);
+        } else {
+          pendingActions.footer = footer;
+        }
+      }, "setFooter"),
+      setHeader: /* @__PURE__ */ __name((header) => {
+        if (openedPage) {
+          openedPage.setHeader(header);
+        } else {
+          pendingActions.header = header;
+        }
+      }, "setHeader")
+    }
+  );
+}
+__name(createPendingGlobalEmbedView, "createPendingGlobalEmbedView");
 const PageElementsHolder = import_react.default.memo(
   import_react.default.forwardRef((props, ref) => {
     const [elements, patchElement] = (0, import_usePatchElement.default)();
@@ -67,168 +164,229 @@ const PageElementsHolder = import_react.default.memo(
 function usePage() {
   const holderRef = import_react.default.useRef(null);
   const globalEmbedActiveRef = import_react.default.useRef(null);
+  const globalEmbedReplacementTokenRef = import_react.default.useRef(0);
   const open = /* @__PURE__ */ __name((config, flowContext) => {
-    var _a, _b, _c;
-    const parentEngine = flowContext == null ? void 0 : flowContext.engine;
-    uuid += 1;
-    const pageRef = import_react.default.createRef();
-    let closeFunc;
-    let resolvePromise;
-    const promise = new Promise((resolve) => {
-      resolvePromise = resolve;
-    });
-    const FooterComponent = /* @__PURE__ */ __name(({ children }) => {
-      import_react.default.useEffect(() => {
-        var _a2;
-        (_a2 = pageRef.current) == null ? void 0 : _a2.setFooter(children);
-        return () => {
-          var _a3;
-          (_a3 = pageRef.current) == null ? void 0 : _a3.setFooter(null);
-        };
-      }, [children]);
-      return null;
-    }, "FooterComponent");
-    const HeaderComponent = /* @__PURE__ */ __name((props) => {
-      import_react.default.useEffect(() => {
-        var _a2;
-        (_a2 = pageRef.current) == null ? void 0 : _a2.setHeader(props);
-        return () => {
-          var _a3;
-          (_a3 = pageRef.current) == null ? void 0 : _a3.setHeader(null);
-        };
-      }, [props]);
-      return null;
-    }, "HeaderComponent");
     const {
       target,
       content,
       preventClose,
       inheritContext = true,
       inputArgs: viewInputArgs = {},
+      onOpenCancelled,
       ...restConfig
     } = config;
     const isGlobalEmbedContainer = target instanceof HTMLElement && target.id === GLOBAL_EMBED_CONTAINER_ID;
-    if (isGlobalEmbedContainer && globalEmbedActiveRef.current) {
-      try {
-        target.dataset[EMBED_REPLACING_DATA_KEY] = "1";
-        globalEmbedActiveRef.current.destroy();
-      } finally {
-        delete target.dataset[EMBED_REPLACING_DATA_KEY];
-        globalEmbedActiveRef.current = null;
+    const openCurrentPage = /* @__PURE__ */ __name(() => {
+      var _a, _b, _c;
+      const parentEngine = flowContext == null ? void 0 : flowContext.engine;
+      uuid += 1;
+      const pageRef = import_react.default.createRef();
+      let closeFunc;
+      let resolvePromise;
+      const promise = new Promise((resolve) => {
+        resolvePromise = resolve;
+      });
+      const FooterComponent = /* @__PURE__ */ __name(({ children }) => {
+        import_react.default.useEffect(() => {
+          var _a2;
+          (_a2 = pageRef.current) == null ? void 0 : _a2.setFooter(children);
+          return () => {
+            var _a3;
+            (_a3 = pageRef.current) == null ? void 0 : _a3.setFooter(null);
+          };
+        }, [children]);
+        return null;
+      }, "FooterComponent");
+      const HeaderComponent = /* @__PURE__ */ __name((props) => {
+        import_react.default.useEffect(() => {
+          var _a2;
+          (_a2 = pageRef.current) == null ? void 0 : _a2.setHeader(props);
+          return () => {
+            var _a3;
+            (_a3 = pageRef.current) == null ? void 0 : _a3.setHeader(null);
+          };
+        }, [props]);
+        return null;
+      }, "HeaderComponent");
+      const ctx = new import_flowContext.FlowContext();
+      const scopedEngine = (0, import_ViewScopedFlowEngine.createViewScopedEngine)(flowContext.engine);
+      const openerEngine = (0, import_viewEvents.resolveOpenerEngine)(parentEngine, scopedEngine);
+      ctx.defineProperty("engine", { value: scopedEngine });
+      ctx.addDelegate(scopedEngine.context);
+      if (inheritContext) {
+        ctx.addDelegate(flowContext);
+      } else {
+        ctx.addDelegate(flowContext.engine.context);
       }
-    }
-    const ctx = new import_flowContext.FlowContext();
-    const scopedEngine = (0, import_ViewScopedFlowEngine.createViewScopedEngine)(flowContext.engine);
-    const openerEngine = (0, import_viewEvents.resolveOpenerEngine)(parentEngine, scopedEngine);
-    ctx.defineProperty("engine", { value: scopedEngine });
-    ctx.addDelegate(scopedEngine.context);
-    if (inheritContext) {
-      ctx.addDelegate(flowContext);
-    } else {
-      ctx.addDelegate(flowContext.engine.context);
-    }
-    const currentPage = {
-      type: "embed",
-      inputArgs: viewInputArgs,
-      preventClose: !!config.preventClose,
-      destroy: /* @__PURE__ */ __name((result) => {
-        var _a2, _b2, _c2, _d, _e;
-        (_a2 = config.onClose) == null ? void 0 : _a2.call(config);
-        resolvePromise == null ? void 0 : resolvePromise(result);
-        (_b2 = pageRef.current) == null ? void 0 : _b2.destroy();
-        closeFunc == null ? void 0 : closeFunc();
-        if (isGlobalEmbedContainer) {
-          globalEmbedActiveRef.current = null;
-        }
-        const isReplacing = isGlobalEmbedContainer && target instanceof HTMLElement && ((_c2 = target.dataset) == null ? void 0 : _c2[EMBED_REPLACING_DATA_KEY]) === "1";
-        if (!isReplacing) {
-          const openerEmitter = openerEngine == null ? void 0 : openerEngine.emitter;
-          (0, import_viewEvents.bumpViewActivatedVersion)(openerEmitter);
-          (_e = openerEmitter == null ? void 0 : openerEmitter.emit) == null ? void 0 : _e.call(openerEmitter, import_viewEvents.VIEW_ACTIVATED_EVENT, { type: "embed", viewUid: (_d = currentPage == null ? void 0 : currentPage.inputArgs) == null ? void 0 : _d.viewUid });
-        }
-        scopedEngine.unlinkFromStack();
-      }, "destroy"),
-      update: /* @__PURE__ */ __name((newConfig) => {
-        var _a2;
-        return (_a2 = pageRef.current) == null ? void 0 : _a2.update(newConfig);
-      }, "update"),
-      close: /* @__PURE__ */ __name((result, force) => {
-        var _a2, _b2;
-        if (preventClose && !force) {
-          return;
+      let destroyed = false;
+      let closingPromise;
+      const currentPage = {
+        type: "embed",
+        inputArgs: viewInputArgs,
+        preventClose: !!config.preventClose,
+        beforeClose: void 0,
+        destroy: /* @__PURE__ */ __name((result) => {
+          var _a2, _b2, _c2, _d, _e;
+          if (destroyed) return;
+          destroyed = true;
+          (_a2 = config.onClose) == null ? void 0 : _a2.call(config);
+          resolvePromise == null ? void 0 : resolvePromise(result);
+          (_b2 = pageRef.current) == null ? void 0 : _b2.destroy();
+          closeFunc == null ? void 0 : closeFunc();
+          if (isGlobalEmbedContainer && globalEmbedActiveRef.current === currentPage) {
+            globalEmbedActiveRef.current = null;
+          }
+          const isReplacing = isGlobalEmbedContainer && target instanceof HTMLElement && ((_c2 = target.dataset) == null ? void 0 : _c2[EMBED_REPLACING_DATA_KEY]) === "1";
+          if (!isReplacing) {
+            const openerEmitter = openerEngine == null ? void 0 : openerEngine.emitter;
+            (0, import_viewEvents.bumpViewActivatedVersion)(openerEmitter);
+            (_e = openerEmitter == null ? void 0 : openerEmitter.emit) == null ? void 0 : _e.call(openerEmitter, import_viewEvents.VIEW_ACTIVATED_EVENT, { type: "embed", viewUid: (_d = currentPage == null ? void 0 : currentPage.inputArgs) == null ? void 0 : _d.viewUid });
+          }
+          scopedEngine.unlinkFromStack();
+        }, "destroy"),
+        update: /* @__PURE__ */ __name((newConfig) => {
+          var _a2;
+          return (_a2 = pageRef.current) == null ? void 0 : _a2.update(newConfig);
+        }, "update"),
+        close: /* @__PURE__ */ __name((result, force) => {
+          if (destroyed) {
+            return Promise.resolve(true);
+          }
+          if (closingPromise) {
+            return closingPromise;
+          }
+          closingPromise = (async () => {
+            var _a2, _b2;
+            try {
+              if (preventClose && !force) {
+                closingPromise = void 0;
+                return false;
+              }
+              const shouldClose = await (0, import_runViewBeforeClose.runViewBeforeClose)(currentPage, { result, force });
+              if (destroyed) {
+                return true;
+              }
+              if (!shouldClose) {
+                closingPromise = void 0;
+                return false;
+              }
+              if (config.triggerByRouter && ((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.navigation) == null ? void 0 : _b2.back)) {
+                config.inputArgs.navigation.back();
+                return true;
+              }
+              currentPage.destroy(result);
+              return true;
+            } catch (error) {
+              if (!destroyed) {
+                closingPromise = void 0;
+              }
+              throw error;
+            }
+          })();
+          return closingPromise;
+        }, "close"),
+        Header: HeaderComponent,
+        Footer: FooterComponent,
+        setFooter: /* @__PURE__ */ __name((footer) => {
+          var _a2;
+          (_a2 = pageRef.current) == null ? void 0 : _a2.setFooter(footer);
+        }, "setFooter"),
+        setHeader: /* @__PURE__ */ __name((header) => {
+          var _a2;
+          (_a2 = pageRef.current) == null ? void 0 : _a2.setHeader(header);
+        }, "setHeader"),
+        navigation: (_a = config.inputArgs) == null ? void 0 : _a.navigation,
+        get record() {
+          return (0, import_variablesParams.getViewRecordFromParent)(flowContext, ctx);
         }
-        if (config.triggerByRouter && ((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.navigation) == null ? void 0 : _b2.back)) {
-          config.inputArgs.navigation.back();
-          return;
+      };
+      ctx.defineProperty("view", {
+        get: /* @__PURE__ */ __name(() => currentPage, "get"),
+        // 仅当访问关联字段或前端无本地记录数据时，才交给服务端解析
+        resolveOnServer: (0, import_variablesParams.createViewRecordResolveOnServer)(ctx, () => (0, import_variablesParams.getViewRecordFromParent)(flowContext, ctx))
+      });
+      (0, import_createViewMeta.registerPopupVariable)(ctx, currentPage);
+      const PageWithContext = (0, import__.observer)(
+        () => {
+          var _a2, _b2, _c2, _d;
+          const mountedRef = import_react.default.useRef(false);
+          const pageContent = import_react.default.useMemo(
+            () => typeof content === "function" ? content(currentPage, ctx) : content,
+            []
+          );
+          void ctx.themeToken;
+          import_react.default.useEffect(() => {
+            var _a3;
+            (_a3 = config.onOpen) == null ? void 0 : _a3.call(config, currentPage, ctx);
+          }, []);
+          if (((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.hidden) == null ? void 0 : _b2.value) && !mountedRef.current) {
+            return null;
+          }
+          mountedRef.current = true;
+          return /* @__PURE__ */ import_react.default.createElement(
+            import_PageComponent.PageComponent,
+            {
+              ref: pageRef,
+              hidden: (_d = (_c2 = config.inputArgs) == null ? void 0 : _c2.hidden) == null ? void 0 : _d.value,
+              ...restConfig,
+              onClose: () => {
+                return currentPage.close(config.result);
+              }
+            },
+            pageContent
+          );
+        },
+        {
+          displayName: "PageWithContext"
         }
-        currentPage.destroy(result);
-      }, "close"),
-      Header: HeaderComponent,
-      Footer: FooterComponent,
-      setFooter: /* @__PURE__ */ __name((footer) => {
-        var _a2;
-        (_a2 = pageRef.current) == null ? void 0 : _a2.setFooter(footer);
-      }, "setFooter"),
-      setHeader: /* @__PURE__ */ __name((header) => {
-        var _a2;
-        (_a2 = pageRef.current) == null ? void 0 : _a2.setHeader(header);
-      }, "setHeader"),
-      navigation: (_a = config.inputArgs) == null ? void 0 : _a.navigation,
-      get record() {
-        return (0, import_variablesParams.getViewRecordFromParent)(flowContext, ctx);
+      );
+      const key = (viewInputArgs == null ? void 0 : viewInputArgs.viewUid) || `page-${uuid}`;
+      const page = /* @__PURE__ */ import_react.default.createElement(import_provider.FlowEngineProvider, { key, engine: scopedEngine }, /* @__PURE__ */ import_react.default.createElement(import_FlowContextProvider.FlowViewContextProvider, { context: ctx }, /* @__PURE__ */ import_react.default.createElement(PageWithContext, null)));
+      if (target && target instanceof HTMLElement) {
+        closeFunc = (_b = holderRef.current) == null ? void 0 : _b.patchElement(import_react_dom.default.createPortal(page, target, key));
+      } else {
+        closeFunc = (_c = holderRef.current) == null ? void 0 : _c.patchElement(page);
       }
-    };
-    ctx.defineProperty("view", {
-      get: /* @__PURE__ */ __name(() => currentPage, "get"),
-      // 仅当访问关联字段或前端无本地记录数据时，才交给服务端解析
-      resolveOnServer: (0, import_variablesParams.createViewRecordResolveOnServer)(ctx, () => (0, import_variablesParams.getViewRecordFromParent)(flowContext, ctx))
-    });
-    (0, import_createViewMeta.registerPopupVariable)(ctx, currentPage);
-    const PageWithContext = (0, import__.observer)(
-      () => {
-        var _a2, _b2, _c2, _d;
-        const mountedRef = import_react.default.useRef(false);
-        const pageContent = import_react.default.useMemo(
-          () => typeof content === "function" ? content(currentPage, ctx) : content,
-          []
-        );
-        void ctx.themeToken;
-        import_react.default.useEffect(() => {
-          var _a3;
-          (_a3 = config.onOpen) == null ? void 0 : _a3.call(config, currentPage, ctx);
-        }, []);
-        if (((_b2 = (_a2 = config.inputArgs) == null ? void 0 : _a2.hidden) == null ? void 0 : _b2.value) && !mountedRef.current) {
-          return null;
-        }
-        mountedRef.current = true;
-        return /* @__PURE__ */ import_react.default.createElement(
-          import_PageComponent.PageComponent,
-          {
-            ref: pageRef,
-            hidden: (_d = (_c2 = config.inputArgs) == null ? void 0 : _c2.hidden) == null ? void 0 : _d.value,
-            ...restConfig,
-            onClose: () => {
-              currentPage.close(config.result);
+      if (isGlobalEmbedContainer) {
+        globalEmbedActiveRef.current = currentPage;
+      }
+      return Object.assign(promise, currentPage);
+    }, "openCurrentPage");
+    if (isGlobalEmbedContainer && globalEmbedActiveRef.current) {
+      const replacementToken = globalEmbedReplacementTokenRef.current += 1;
+      const cancelOpen = /* @__PURE__ */ __name(() => onOpenCancelled == null ? void 0 : onOpenCancelled(), "cancelOpen");
+      let closeResult;
+      try {
+        closeResult = closeReplacingGlobalEmbed(target, globalEmbedActiveRef.current);
+      } catch (error) {
+        cancelOpen();
+        throw error;
+      }
+      if (isPromiseLike(closeResult)) {
+        return createPendingGlobalEmbedView(
+          Promise.resolve(closeResult).then(
+            (closed) => {
+              if (closed === false || replacementToken !== globalEmbedReplacementTokenRef.current) {
+                cancelOpen();
+                return { page: null };
+              }
+              return { page: openCurrentPage() };
+            },
+            (error) => {
+              cancelOpen();
+              throw error;
             }
-          },
-          pageContent
+          ),
+          viewInputArgs,
+          !!config.preventClose
         );
-      },
-      {
-        displayName: "PageWithContext"
       }
-    );
-    const key = (viewInputArgs == null ? void 0 : viewInputArgs.viewUid) || `page-${uuid}`;
-    const page = /* @__PURE__ */ import_react.default.createElement(import_provider.FlowEngineProvider, { key, engine: scopedEngine }, /* @__PURE__ */ import_react.default.createElement(import_FlowContextProvider.FlowViewContextProvider, { context: ctx }, /* @__PURE__ */ import_react.default.createElement(PageWithContext, null)));
-    if (target && target instanceof HTMLElement) {
-      closeFunc = (_b = holderRef.current) == null ? void 0 : _b.patchElement(import_react_dom.default.createPortal(page, target, key));
-    } else {
-      closeFunc = (_c = holderRef.current) == null ? void 0 : _c.patchElement(page);
-    }
-    if (isGlobalEmbedContainer) {
-      globalEmbedActiveRef.current = { destroy: currentPage.destroy };
+      if (closeResult === false) {
+        cancelOpen();
+        return createPendingGlobalEmbedView(Promise.resolve({ page: null }), viewInputArgs, !!config.preventClose);
+      }
     }
-    return Object.assign(promise, currentPage);
+    return openCurrentPage();
   }, "open");
   const api = import_react.default.useMemo(() => ({ open }), []);
   return [api, /* @__PURE__ */ import_react.default.createElement(PageElementsHolder, { key: "page-holder", ref: holderRef })];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.1.0-alpha.4",
+  "version": "2.1.0-alpha.40",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,9 +8,10 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.1.0-alpha.4",
-    "@nocobase/shared": "2.1.0-alpha.4",
+    "@nocobase/sdk": "2.1.0-alpha.40",
+    "@nocobase/shared": "2.1.0-alpha.40",
     "ahooks": "^3.7.2",
+    "axios": "^1.7.0",
     "dayjs": "^1.11.9",
     "dompurify": "^3.0.2",
     "lodash": "^4.x",
@@ -35,6 +36,6 @@
     "workflow"
   ],
   "author": "NocoBase Team",
-  "license": "AGPL-3.0",
-  "gitHead": "32c682485e5f1878b9165be2e9de18000d98f935"
+  "license": "Apache-2.0",
+  "gitHead": "e73f99dd0abefe847f2e50ff0fea1f41a82fd048"
 }

package/src/JSRunner.ts

@@ -16,12 +16,74 @@ export interface JSRunnerOptions {
   version?: string;
   /**
    * Enable RunJS template compatibility preprocessing for `{{ ... }}`.
-   * When enabled via `ctx.runjs(code, vars, { preprocessTemplates: true })` (default),
+   * When enabled (or falling back to version default),
    * the code will be rewritten to call `ctx.resolveJsonTemplate(...)` at runtime.
    */
   preprocessTemplates?: boolean;
 }
 
+/**
+ * Decide whether RunJS `{{ ... }}` compatibility preprocessing should run.
+ *
+ * Priority:
+ * 1. Explicit `preprocessTemplates` option always wins.
+ * 2. Otherwise, `version === 'v2'` disables preprocessing.
+ * 3. Fallback keeps v1-compatible behavior (enabled).
+ */
+export function shouldPreprocessRunJSTemplates(
+  options?: Pick<JSRunnerOptions, 'preprocessTemplates' | 'version'>,
+): boolean {
+  if (typeof options?.preprocessTemplates === 'boolean') {
+    return options.preprocessTemplates;
+  }
+  return options?.version !== 'v2';
+}
+
+// Heuristic: detect likely bare `{{ctx.xxx}}` usage in executable positions (not quoted string literals).
+const BARE_CTX_TEMPLATE_RE = /(^|[=(:,[\s)])(\{\{\s*(ctx(?:\.|\[|\?\.)[^}]*)\s*\}\})/m;
+
+function extractDeprecatedCtxTemplateUsage(code: string): { placeholder: string; expression: string } | null {
+  const src = String(code || '');
+  const m = src.match(BARE_CTX_TEMPLATE_RE);
+  if (!m) return null;
+  const placeholder = String(m[2] || '').trim();
+  const expression = String(m[3] || '').trim();
+  if (!placeholder || !expression) return null;
+  return { placeholder, expression };
+}
+
+function shouldHintCtxTemplateSyntax(err: any, usage: { placeholder: string; expression: string } | null): boolean {
+  const isSyntaxError = err instanceof SyntaxError || String((err as any)?.name || '') === 'SyntaxError';
+  if (!isSyntaxError) return false;
+  if (!usage) return false;
+  const msg = String((err as any)?.message || err || '');
+  return /unexpected token/i.test(msg);
+}
+
+function toCtxTemplateSyntaxHintError(
+  err: any,
+  usage: {
+    placeholder: string;
+    expression: string;
+  },
+): Error {
+  const hint = `"${usage.placeholder}" has been deprecated and cannot be used as executable RunJS syntax. Use await ctx.getVar("${usage.expression}") instead, or keep "${usage.placeholder}" as a plain string.`;
+  const out = new SyntaxError(hint);
+  try {
+    (out as any).cause = err;
+  } catch (_) {
+    // ignore
+  }
+  try {
+    // Hint-only error: avoid leaking internal bundle line numbers from stack parsers in preview UI.
+    (out as any).__runjsHideLocation = true;
+    out.stack = `${out.name}: ${out.message}`;
+  } catch (_) {
+    // ignore
+  }
+  return out;
+}
+
 export class JSRunner {
   private globals: Record<string, any>;
   private timeoutMs: number;
@@ -118,11 +180,13 @@ export class JSRunner {
       if (err instanceof FlowExitAllException) {
         throw err;
       }
-      console.error(err);
+      const usage = extractDeprecatedCtxTemplateUsage(code);
+      const outErr = shouldHintCtxTemplateSyntax(err, usage) && usage ? toCtxTemplateSyntaxHintError(err, usage) : err;
+      console.error(outErr);
       return {
         success: false,
-        error: err,
-        timeout: err.message === 'Execution timed out',
+        error: outErr,
+        timeout: (outErr as any)?.message === 'Execution timed out',
       };
     }
   }

package/src/ViewScopedFlowEngine.ts

@@ -62,6 +62,10 @@ export function createViewScopedEngine(parent: FlowEngine): FlowEngine {
     '_nextEngine',
     // getModel 需要在本地执行以确保全局查找时正确遍历整个引擎栈
     'getModel',
+    // 视图销毁回调需要在本地存储，每个视图引擎有自己的销毁逻辑
+    '_destroyView',
+    'setDestroyView',
+    'destroyView',
   ]);
 
   const handler: ProxyHandler<FlowEngine> = {

package/src/__tests__/JSRunner.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { JSRunner } from '../JSRunner';
+import { JSRunner, shouldPreprocessRunJSTemplates } from '../JSRunner';
 import { createSafeWindow } from '../utils';
 
 describe('JSRunner', () => {
@@ -30,6 +30,18 @@ describe('JSRunner', () => {
     vi.restoreAllMocks();
   });
 
+  it('shouldPreprocessRunJSTemplates: explicit option has highest priority', () => {
+    expect(shouldPreprocessRunJSTemplates({ version: 'v2', preprocessTemplates: true })).toBe(true);
+    expect(shouldPreprocessRunJSTemplates({ version: 'v1', preprocessTemplates: false })).toBe(false);
+  });
+
+  it('shouldPreprocessRunJSTemplates: falls back to version policy', () => {
+    expect(shouldPreprocessRunJSTemplates({ version: 'v1' })).toBe(true);
+    expect(shouldPreprocessRunJSTemplates({ version: 'v2' })).toBe(false);
+    expect(shouldPreprocessRunJSTemplates({})).toBe(true);
+    expect(shouldPreprocessRunJSTemplates()).toBe(true);
+  });
+
   it('executes simple code and returns value', async () => {
     const runner = new JSRunner();
     const result = await runner.run('return 1 + 2 + 3');
@@ -152,6 +164,20 @@ describe('JSRunner', () => {
     expect((result.error as Error).message).toBe('Execution timed out');
   });
 
+  it('returns friendly hint when bare {{ctx.xxx}} appears in syntax error', async () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const runner = new JSRunner();
+    const result = await runner.run('const z = {{ctx.user.id}}');
+    expect(result.success).toBe(false);
+    expect(result.error).toBeInstanceOf(SyntaxError);
+    const msg = String((result.error as any)?.message || '');
+    expect(msg).toContain('"{{ctx.user.id}}" has been deprecated');
+    expect(msg).toContain('await ctx.getVar("ctx.user.id")');
+    expect(msg).not.toContain('(at ');
+    expect((result.error as any)?.__runjsHideLocation).toBe(true);
+    expect(spy).toHaveBeenCalled();
+  });
+
   it('skips execution when URL contains skipRunJs=true', async () => {
     // 模拟预览模式下通过 URL 参数跳过代码执行
     if (typeof window !== 'undefined' && typeof window.history?.pushState === 'function') {