@nocobase/flow-engine 2.0.0-alpha.3 → 2.0.0-alpha.30

package/lib/views/useDrawer.js

@@ -50,12 +50,31 @@ var import_DrawerComponent = __toESM(require("./DrawerComponent"));
 var import_usePatchElement = __toESM(require("./usePatchElement"));
 var import_provider = require("../provider");
 var import_ViewScopedFlowEngine = require("../ViewScopedFlowEngine");
-let uuid = 0;
 function useDrawer() {
   const holderRef = React.useRef(null);
+  const drawerList = React.useMemo(() => import__.observable.shallow({ value: [] }), []);
+  const RenderNestedDrawer = React.memo((props) => {
+    const { index } = props;
+    const [RenderDrawer, setRenderDrawer] = React.useState(null);
+    React.useEffect(() => {
+      (0, import__.autorun)(() => {
+        const list = drawerList.value;
+        if (list[index] && RenderDrawer !== list[index]) {
+          setRenderDrawer(list[index]);
+        }
+        if (!list[index]) {
+          setRenderDrawer(null);
+        }
+      });
+    }, [RenderDrawer, index]);
+    if (!RenderDrawer) {
+      return null;
+    }
+    return /* @__PURE__ */ React.createElement(RenderDrawer, null, /* @__PURE__ */ React.createElement(RenderNestedDrawer, { index: index + 1 }));
+  });
+  RenderNestedDrawer.displayName = "RenderNestedDrawer";
   const open = /* @__PURE__ */ __name((config, flowContext) => {
     var _a, _b;
-    uuid += 1;
     const drawerRef = React.createRef();
     let closeFunc;
     let resolvePromise;
@@ -64,7 +83,7 @@ function useDrawer() {
     });
     let currentFooter = null;
     let currentHeader = null;
-    const FooterComponent = /* @__PURE__ */ __name(({ children, ...props }) => {
+    const FooterComponent = /* @__PURE__ */ __name(({ children }) => {
       React.useEffect(() => {
         var _a2;
         currentFooter = children;
@@ -77,7 +96,7 @@ function useDrawer() {
       }, [children]);
       return null;
     }, "FooterComponent");
-    const HeaderComponent = /* @__PURE__ */ __name(({ ...props }) => {
+    const HeaderComponent = /* @__PURE__ */ __name((props) => {
       React.useEffect(() => {
         var _a2;
         currentHeader = props;
@@ -126,11 +145,6 @@ function useDrawer() {
       navigation: (_a = config.inputArgs) == null ? void 0 : _a.navigation
     };
     const ctx = new import_flowContext.FlowContext();
-    ctx.defineProperty("view", {
-      get: /* @__PURE__ */ __name(() => currentDrawer, "get"),
-      meta: (0, import_createViewMeta.createViewMeta)(ctx, () => currentDrawer),
-      resolveOnServer: /* @__PURE__ */ __name((p) => p === "record" || p.startsWith("record."), "resolveOnServer")
-    });
     const scopedEngine = (0, import_ViewScopedFlowEngine.createViewScopedEngine)(flowContext.engine);
     ctx.defineProperty("engine", { value: scopedEngine });
     ctx.addDelegate(scopedEngine.context);
@@ -139,8 +153,14 @@ function useDrawer() {
     } else {
       ctx.addDelegate(flowContext.engine.context);
     }
-    const DrawerWithContext = (0, import__.observer)(
-      (props) => {
+    ctx.defineProperty("view", {
+      get: /* @__PURE__ */ __name(() => currentDrawer, "get"),
+      // meta: createViewMeta(ctx),
+      resolveOnServer: /* @__PURE__ */ __name((p) => p === "record" || p.startsWith("record."), "resolveOnServer")
+    });
+    (0, import_createViewMeta.registerPopupVariable)(ctx, currentDrawer);
+    const DrawerWithContext = React.memo(
+      (0, import__.observer)((props) => {
         var _a2, _b2, _c, _d;
         const mountedRef = React.useRef(false);
         const rawContent = typeof config.content === "function" ? config.content(currentDrawer, ctx) : config.content;
@@ -172,13 +192,12 @@ function useDrawer() {
           content,
           props.children
         );
-      },
-      {
-        displayName: "DrawerWithContext"
-      }
+      })
     );
-    const renderDrawer = /* @__PURE__ */ __name((children) => /* @__PURE__ */ React.createElement(import_provider.FlowEngineProvider, { engine: scopedEngine }, /* @__PURE__ */ React.createElement(import_FlowContextProvider.FlowViewContextProvider, { context: ctx }, /* @__PURE__ */ React.createElement(DrawerWithContext, null, children))), "renderDrawer");
-    closeFunc = (_b = holderRef.current) == null ? void 0 : _b.patchElement(renderDrawer);
+    DrawerWithContext.displayName = "DrawerWithContext";
+    const RenderDrawer = React.memo(({ children }) => /* @__PURE__ */ React.createElement(import_provider.FlowEngineProvider, { engine: scopedEngine }, /* @__PURE__ */ React.createElement(import_FlowContextProvider.FlowViewContextProvider, { context: ctx }, /* @__PURE__ */ React.createElement(DrawerWithContext, null, children))));
+    RenderDrawer.displayName = "RenderDrawer";
+    closeFunc = (_b = holderRef.current) == null ? void 0 : _b.patchElement(RenderDrawer);
     return Object.assign(promise, currentDrawer);
   }, "open");
   const api = React.useMemo(() => ({ open }), []);
@@ -186,15 +205,10 @@ function useDrawer() {
     React.forwardRef((props, ref) => {
       const [elements, patchElement] = (0, import_usePatchElement.default)();
       React.useImperativeHandle(ref, () => ({ patchElement }), [patchElement]);
-      const renderNestedElements = /* @__PURE__ */ __name(() => {
-        if (elements.length === 0) {
-          return null;
-        }
-        return elements.reduceRight((children, renderElement) => {
-          return renderElement(children);
-        }, null);
-      }, "renderNestedElements");
-      return /* @__PURE__ */ React.createElement(React.Fragment, null, renderNestedElements());
+      React.useEffect(() => {
+        drawerList.value = elements;
+      }, [elements]);
+      return /* @__PURE__ */ React.createElement(RenderNestedDrawer, { index: 0 });
     })
   );
   return [api, /* @__PURE__ */ React.createElement(ElementsHolder, { key: "drawer-holder", ref: holderRef })];

package/lib/views/usePage.d.ts

@@ -9,19 +9,19 @@
 import React from 'react';
 export declare function usePage(): (React.JSX.Element | {
     open: (config: any, flowContext: any) => Promise<unknown> & {
-        type: string;
+        type: "embed";
         inputArgs: any;
         preventClose: boolean;
         destroy: () => void;
         update: (newConfig: any) => void;
         close: (result?: any, force?: boolean) => void;
-        Header: ({ ...props }: {
-            [x: string]: any;
-        }) => any;
-        Footer: ({ children, ...props }: {
-            [x: string]: any;
-            children: any;
-        }) => any;
+        Header: React.FC<{
+            title?: React.ReactNode;
+            extra?: React.ReactNode;
+        }>;
+        Footer: React.FC<{
+            children?: React.ReactNode;
+        }>;
         setFooter: (footer: React.ReactNode) => void;
         setHeader: (header: {
             title?: React.ReactNode;

package/lib/views/usePage.js

@@ -69,7 +69,7 @@ function usePage() {
     const promise = new Promise((resolve) => {
       resolvePromise = resolve;
     });
-    const FooterComponent = /* @__PURE__ */ __name(({ children, ...props }) => {
+    const FooterComponent = /* @__PURE__ */ __name(({ children }) => {
       import_react.default.useEffect(() => {
         var _a2;
         (_a2 = pageRef.current) == null ? void 0 : _a2.setFooter(children);
@@ -80,7 +80,7 @@ function usePage() {
       }, [children]);
       return null;
     }, "FooterComponent");
-    const HeaderComponent = /* @__PURE__ */ __name(({ ...props }) => {
+    const HeaderComponent = /* @__PURE__ */ __name((props) => {
       import_react.default.useEffect(() => {
         var _a2;
         (_a2 = pageRef.current) == null ? void 0 : _a2.setHeader(props);
@@ -126,11 +126,6 @@ function usePage() {
       navigation: (_a = config.inputArgs) == null ? void 0 : _a.navigation
     };
     const ctx = new import_flowContext.FlowContext();
-    ctx.defineProperty("view", {
-      get: /* @__PURE__ */ __name(() => currentPage, "get"),
-      meta: (0, import_createViewMeta.createViewMeta)(ctx, () => currentPage),
-      resolveOnServer: /* @__PURE__ */ __name((p) => p === "record" || p.startsWith("record."), "resolveOnServer")
-    });
     const scopedEngine = (0, import_ViewScopedFlowEngine.createViewScopedEngine)(flowContext.engine);
     ctx.defineProperty("engine", { value: scopedEngine });
     ctx.addDelegate(scopedEngine.context);
@@ -139,6 +134,12 @@ function usePage() {
     } else {
       ctx.addDelegate(flowContext.engine.context);
     }
+    ctx.defineProperty("view", {
+      get: /* @__PURE__ */ __name(() => currentPage, "get"),
+      // meta: createViewMeta(ctx),
+      resolveOnServer: /* @__PURE__ */ __name((p) => p === "record" || p.startsWith("record."), "resolveOnServer")
+    });
+    (0, import_createViewMeta.registerPopupVariable)(ctx, currentPage);
     const PageWithContext = (0, import__.observer)(
       () => {
         var _a2, _b2, _c2, _d;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.30",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,7 +8,8 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "1.8.0-beta.4",
+    "@nocobase/sdk": "2.0.0-alpha.30",
+    "@nocobase/shared": "2.0.0-alpha.30",
     "ahooks": "^3.7.2",
     "dompurify": "^3.0.2",
     "lodash": "^4.x",
@@ -17,6 +18,7 @@
     "slate": "^0.103.0",
     "slate-history": "^0.109.0",
     "slate-react": "^0.110.3",
+    "sucrase": "^3.35.0",
     "uid": "^2.0.2"
   },
   "peerDependencies": {
@@ -33,5 +35,5 @@
   ],
   "author": "NocoBase Team",
   "license": "AGPL-3.0",
-  "gitHead": "8efc23aa78058d871e98a91419f3c4a61762cc15"
+  "gitHead": "cdac55c9cdf0dbdbe57a21815f323b975792bfc0"
 }

package/src/BlockScopedFlowEngine.ts

@@ -0,0 +1,86 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { FlowEngine } from './flowEngine';
+
+/**
+ * BlockScopedFlowEngine（区块作用域引擎）
+ *
+ * 设计目标：
+ * - 仅在“区块”作用域内隔离“模型实例表”和“事件缓存”；
+ * - 其余能力（动作/事件/模型类/资源/仓库/设置/日志/翻译等）全部直接代理到父引擎；
+ * - 使用 Proxy 实现“最小代理”，保持与父引擎的全局一致性。
+ *
+ * 注意：
+ * - 本地化的字段仅有：`_modelInstances`、`_applyFlowCache`、`executor`、`context`、栈指针；
+ * - 其它字段/方法均通过 Proxy 转发到父引擎；
+ * - 这样可满足“同一 uid 的模型可在不同区块隔离出现（实例/缓存隔离）”与“共享全局注册/仓库”的诉求。
+ */
+export function createBlockScopedEngine(parent: FlowEngine): FlowEngine {
+  const local = new FlowEngine();
+  if (parent.modelRepository) {
+    local.setModelRepository(parent.modelRepository);
+  }
+  // 继承父级上下文能力
+  local.context.addDelegate(parent.context);
+
+  // 覆盖 unlinkFromStack：BlockScoped 引擎被移除时，修复前后指针，避免“截断”后续视图/作用域
+  const originalUnlink = local.unlinkFromStack.bind(local);
+  local.unlinkFromStack = function () {
+    // 修复指针：prev -> next，next -> prev，然后清理自身指针
+    // 若不这么做，移除位于中间的 block 引擎会导致后续整段链丢失
+    const prev = (local as any)._previousEngine as FlowEngine | undefined;
+    const next = (local as any)._nextEngine as FlowEngine | undefined;
+    if (prev) (prev as any)._nextEngine = next;
+    if (next) (next as any)._previousEngine = prev;
+    (local as any)._previousEngine = undefined as any;
+    (local as any)._nextEngine = undefined as any;
+  };
+
+  // 默认全部代理到父引擎，只有少数字段（实例/缓存/执行器/上下文/链表指针）使用本地值
+  const localOnly = new Set<keyof FlowEngine | string>([
+    '_modelInstances',
+    '_applyFlowCache',
+    'executor',
+    'context',
+    'previousEngine',
+    'nextEngine',
+    // 栈指针维护方法需要在本地执行，而非代理到父引擎
+    'unlinkFromStack',
+    'linkAfter',
+    '_previousEngine',
+    '_nextEngine',
+  ]);
+
+  const handler: ProxyHandler<FlowEngine> = {
+    get(target, prop: string, receiver) {
+      if (localOnly.has(prop)) {
+        return Reflect.get(target, prop, receiver);
+      }
+      const value = Reflect.get(parent, prop, receiver);
+      if (prop === 'registerModels' && typeof value === 'function') {
+        return value.bind(parent);
+      }
+      return value;
+    },
+    set(target, prop: string, value: unknown) {
+      if (localOnly.has(prop)) {
+        return Reflect.set(target, prop, value);
+      }
+      return Reflect.set(parent, prop, value);
+    },
+    has(target, prop: string) {
+      return prop in target || prop in parent;
+    },
+  };
+
+  // 与父引擎形成栈式关系，便于在多层作用域间进行全局查找
+  local.linkAfter(parent);
+  return new Proxy(local, handler) as FlowEngine;
+}

package/src/FlowContextProvider.tsx

@@ -18,13 +18,15 @@ export function FlowContextProvider(props: { children: React.ReactNode; context:
   return <FlowReactContext.Provider value={props.context}>{props.children}</FlowReactContext.Provider>;
 }
 
-export function FlowViewContextProvider(props: { children: React.ReactNode; context: FlowContext }) {
+export const FlowViewContextProvider = React.memo((props: { children: React.ReactNode; context: FlowContext }) => {
   return (
     <FlowViewContext.Provider value={props.context}>
       <FlowReactContext.Provider value={props.context}>{props.children}</FlowReactContext.Provider>
     </FlowViewContext.Provider>
   );
-}
+});
+
+FlowViewContextProvider.displayName = 'FlowViewContextProvider';
 
 export function useFlowContext<T = FlowEngineContext>() {
   return useContext(FlowReactContext) as T;

package/src/JSRunner.ts

@@ -55,6 +55,9 @@ export class JSRunner {
     error?: any;
     timeout?: boolean;
   }> {
+    if (location?.search.includes('skipRunJs=true')) {
+      return { success: true, value: null };
+    }
     const wrapped = `(async () => {
       try {
         ${code};

package/src/ViewScopedFlowEngine.ts

@@ -13,7 +13,7 @@ import { FlowEngine } from './flowEngine';
  * ViewScopedFlowEngine（视图作用域引擎）
  *
  * 设计目标：
- * - 仅在视图（dialog/drawer/embed）作用域内隔离“模型实例表”和“自动流缓存”；
+ * - 仅在视图（dialog/drawer/embed）作用域内隔离“模型实例表”和“事件缓存”；
  * - 其余能力（动作/事件/模型类/资源/仓库/设置/日志/翻译等）全部直接代理到父引擎；
  * - 使用 Proxy 实现“最小代理”，保持与父引擎的全局一致性。
  *

package/src/__tests__/JSRunner.test.ts

@@ -7,86 +7,95 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { JSRunner } from '../JSRunner';
 
 describe('JSRunner', () => {
-  it('should run simple code successfully', async () => {
-    const runner = new JSRunner();
-    const result = await runner.run(`
-      const x = 10;
-      return x + 5;    
-    `);
-    expect(result.success).toBe(true);
-    expect(result.value).toBe(15);
+  let originalSearch: string;
+
+  beforeEach(() => {
+    originalSearch = globalThis.location?.search || '';
   });
 
-  it('should handle syntax errors in the code', async () => {
-    const runner = new JSRunner();
-    const result = await runner.run('const x = 10 x + 5;'); // Syntax error
-    expect(result.success).toBe(false);
-    expect(result.error).toBeInstanceOf(SyntaxError);
+  afterEach(() => {
+    // 恢复 URL 查询参数，避免影响其他用例
+    try {
+      if (typeof window !== 'undefined' && typeof window.history?.replaceState === 'function') {
+        window.history.replaceState({}, '', originalSearch || '');
+      }
+    } catch (_) {
+      // ignore
+    }
+    vi.restoreAllMocks();
   });
 
-  it('should handle runtime errors in the code', async () => {
+  it('executes simple code and returns value', async () => {
     const runner = new JSRunner();
-    const result = await runner.run(`
-      const x = 10;
-      throw new Error('Test error');
-    `);
-    expect(result.success).toBe(false);
-    expect(result.error).toBeInstanceOf(Error);
-    expect(result.error.message).toBe('Test error');
+    const result = await runner.run('return 1 + 2 + 3');
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(6);
   });
 
-  it('should handle timeout errors', async () => {
-    const runner = new JSRunner({ timeoutMs: 100 }); // Set a short timeout
-    const result = await runner.run(`
-      await new Promise(resolve => setTimeout(resolve, 500)); // Exceeds timeout
-      return 'Done';
-    `);
-    console.log(result);
-    expect(result.success).toBe(false);
-    expect(result.timeout).toBe(true);
-    expect(result.error.message).toBe('Execution timed out');
+  it('injects custom globals and supports register()', async () => {
+    const runner = new JSRunner({ globals: { foo: 42 } });
+    const res1 = await runner.run('return foo');
+    expect(res1.success).toBe(true);
+    expect(res1.value).toBe(42);
+
+    runner.register('bar', 'baz');
+    const res2 = await runner.run('return bar');
+    expect(res2.success).toBe(true);
+    expect(res2.value).toBe('baz');
   });
 
-  it('should use registered globals', async () => {
+  it('exposes console in sandbox by default', async () => {
     const runner = new JSRunner();
-    runner.register('globalVar', 42);
-    const result = await runner.run(`
-      return globalVar + 8;
-    `);
+    const result = await runner.run('return typeof console !== "undefined"');
     expect(result.success).toBe(true);
-    expect(result.value).toBe(50);
+    expect(result.value).toBe(true);
   });
 
-  it('should handle code with async/await', async () => {
+  it('supports timers (setTimeout) inside evaluated code', async () => {
     const runner = new JSRunner();
     const result = await runner.run(`
-      const fetchData = async () => {
-        return new Promise(resolve => setTimeout(() => resolve(100), 50));
-      };
-      const data = await fetchData();
-      return data + 50;
+      return new Promise((resolve) => {
+        setTimeout(() => resolve('ok'), 20);
+      });
     `);
     expect(result.success).toBe(true);
-    expect(result.value).toBe(150);
+    expect(result.value).toBe('ok');
   });
 
-  it('should handle empty code', async () => {
+  it('handles thrown errors and marks as non-timeout', async () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
     const runner = new JSRunner();
-    const result = await runner.run('');
-    expect(result.success).toBe(true);
-    expect(result.value).toBe(undefined);
+    const result = await runner.run('throw new Error("boom")');
+    expect(result.success).toBe(false);
+    expect(result.timeout).toBe(false);
+    expect(result.error).toBeInstanceOf(Error);
+    expect((result.error as Error).message).toBe('boom');
+    expect(spy).toHaveBeenCalled();
   });
 
-  it('should handle code returning undefined explicitly', async () => {
-    const runner = new JSRunner();
+  it('respects timeout setting and marks timeout=true', async () => {
+    const runner = new JSRunner({ timeoutMs: 10 });
     const result = await runner.run(`
-      const x = 10;
-      return undefined;
+      return new Promise((resolve) => setTimeout(() => resolve('late'), 100));
     `);
+    expect(result.success).toBe(false);
+    expect(result.timeout).toBe(true);
+    expect(result.error).toBeInstanceOf(Error);
+    expect((result.error as Error).message).toBe('Execution timed out');
+  });
+
+  it('skips execution when URL contains skipRunJs=true', async () => {
+    // 模拟预览模式下通过 URL 参数跳过代码执行
+    if (typeof window !== 'undefined' && typeof window.history?.pushState === 'function') {
+      window.history.pushState({}, '', '?skipRunJs=true');
+    }
+    const runner = new JSRunner();
+    const result = await runner.run('throw new Error("should not run")');
     expect(result.success).toBe(true);
-    expect(result.value).toBe(undefined);
+    expect(result.value).toBeNull();
   });
 });

package/src/__tests__/blockScopedFlowEngine.test.ts

@@ -0,0 +1,154 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { APIClient as SDKApiClient } from '@nocobase/sdk';
+import { FlowEngine } from '../flowEngine';
+import { createBlockScopedEngine } from '../BlockScopedFlowEngine';
+import { FlowModel } from '../models';
+
+describe('BlockScopedFlowEngine', () => {
+  it('shares global actions/events and model classes with parent', async () => {
+    const parent = new FlowEngine();
+    // 在运行时 host app 会注入 api，这里补一个最小 mock，避免偶发访问 ctx.auth 抛错
+    const api = new SDKApiClient({ storageType: 'memory' });
+    api.auth.role = 'guest';
+    api.auth.locale = 'en-US';
+    api.auth.token = 't';
+    parent.context.defineProperty('api', { value: api });
+    parent.registerActions({
+      ping: {
+        name: 'ping',
+        handler: () => 'pong',
+      },
+    });
+    const child = createBlockScopedEngine(parent);
+
+    // child can read parent's action
+    expect(child.getAction('ping')).toBeDefined();
+
+    // registering via child should affect parent
+    child.registerActions({ pong: { name: 'pong', handler: () => 'ok' } });
+    expect(parent.getAction('pong')).toBeDefined();
+
+    // model class resolution is proxied
+    class TestModel extends FlowModel {}
+    parent.registerModels({ TestModel });
+    expect(child.getModelClass('TestModel')).toBeDefined();
+  });
+
+  it('isolates model instances map and beforeRender cache across engines with identical model uid', async () => {
+    const parent = new FlowEngine();
+    // 提供最小 api mock，满足 ctx.auth 相关 getter
+    const api = new SDKApiClient({ storageType: 'memory' });
+    api.auth.role = 'guest';
+    api.auth.locale = 'en-US';
+    api.auth.token = 't';
+    parent.context.defineProperty('api', { value: api });
+    const child = createBlockScopedEngine(parent);
+
+    let count = 0;
+    class CounterModel extends FlowModel {}
+    CounterModel.registerFlow({
+      key: 'autoCounter',
+      steps: {
+        s1: {
+          handler: async () => {
+            count += 1;
+            return count;
+          },
+        },
+      },
+    });
+
+    const uid = 'model-uid-cache';
+    const pm = parent.createModel<CounterModel>({ use: CounterModel, uid });
+    const cm = child.createModel<CounterModel>({ use: CounterModel, uid });
+
+    await pm.dispatchEvent('beforeRender');
+    expect(count).toBe(1);
+
+    // If cache was shared, the next call would hit cache and not increment.
+    await cm.dispatchEvent('beforeRender');
+    expect(count).toBe(2);
+  });
+
+  it('stacks engines and repairs chain when unlinking a middle block-scoped engine', () => {
+    const root = new FlowEngine();
+    // 提供最小 api mock，满足 ctx.auth 相关 getter
+    const api = new SDKApiClient({ storageType: 'memory' });
+    api.auth.role = 'guest';
+    api.auth.locale = 'en-US';
+    api.auth.token = 't';
+    root.context.defineProperty('api', { value: api });
+    const c1 = createBlockScopedEngine(root);
+    const c2 = createBlockScopedEngine(root);
+    const c3 = createBlockScopedEngine(root);
+
+    // chain root -> c1 -> c2 -> c3
+    expect(root.nextEngine).toBeTruthy();
+    expect(root.nextEngine?.nextEngine).toBeTruthy();
+    expect(root.nextEngine?.nextEngine?.nextEngine).toBeTruthy();
+
+    // unlink middle (c2) should link c1 <-> c3 and keep the tail intact
+    c2.unlinkFromStack();
+
+    // root.nextEngine 指向的是被代理的本地 FlowEngine 实例，不与 c1 的 Proxy 引用相等
+    // 这里通过前后指针关系来校验链修复是否正确
+    const first = root.nextEngine;
+    const second = first?.nextEngine;
+    expect(first?.previousEngine).toBe(root);
+    expect(second?.previousEngine).toBe(first);
+    expect(second?.nextEngine).toBeUndefined();
+  });
+
+  it('global model lookup traverses from top to root across stack', () => {
+    const root = new FlowEngine();
+    // 提供最小 api mock，满足 ctx.auth 相关 getter
+    const api = new SDKApiClient({ storageType: 'memory' });
+    api.auth.role = 'guest';
+    api.auth.locale = 'en-US';
+    api.auth.token = 't';
+    root.context.defineProperty('api', { value: api });
+    const c1 = createBlockScopedEngine(root);
+    const c2 = createBlockScopedEngine(root);
+
+    class TM extends FlowModel {}
+    const uid = 'same-uid-global-lookup';
+    const mRoot = root.createModel<TM>({ use: TM, uid });
+    const m1 = c1.createModel<TM>({ use: TM, uid });
+    const m2 = c2.createModel<TM>({ use: TM, uid });
+
+    // sanity: each scope returns its own when not global
+    expect(root.getModel(uid)).toBe(mRoot);
+    expect(c1.getModel(uid)).toBe(m1);
+    expect(c2.getModel(uid)).toBe(m2);
+
+    // global search from any engine hits the top-most engine's instance first
+    expect(root.getModel(uid, true)).toBe(m2);
+    expect(c1.getModel(uid, true)).toBe(m2);
+    expect(c2.getModel(uid, true)).toBe(m2);
+  });
+
+  it('delegates saveModel to parent (concurrency gate sharing)', async () => {
+    const parent = new FlowEngine();
+    // 提供最小 api mock，满足 ctx.auth 相关 getter
+    const api = new SDKApiClient({ storageType: 'memory' });
+    api.auth.role = 'guest';
+    api.auth.locale = 'en-US';
+    api.auth.token = 't';
+    parent.context.defineProperty('api', { value: api });
+    const child = createBlockScopedEngine(parent);
+    const spy = vi.spyOn(parent, 'saveModel').mockResolvedValueOnce(true);
+    class T extends FlowModel {}
+    const m = child.createModel<T>({ use: T });
+    await child.saveModel(m);
+    expect(spy).toHaveBeenCalledOnce();
+  });
+});