@nocobase/flow-engine 2.0.0-beta.8 → 2.0.0

package/src/scheduler/ModelOperationScheduler.ts

@@ -10,6 +10,7 @@
 import { uid as genUid } from 'uid/secure';
 import type { FlowEngine } from '../flowEngine';
 import type { FlowModel } from '../models/flowModel';
+import { FlowExitAllException } from '../utils/exceptions';
 
 type LifecycleType =
   | 'created'
@@ -36,6 +37,8 @@ export interface LifecycleEvent {
   error?: any;
   inputArgs?: Record<string, any>;
   result?: any;
+  flowKey?: string;
+  stepKey?: string;
 }
 
 type ScheduledItem = {
@@ -162,37 +165,37 @@ export class ModelOperationScheduler {
     const emitter = this.engine.emitter;
     if (!emitter || typeof emitter.on !== 'function') return;
 
-    const onCreated = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'created' });
+    const onCreated = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'created' });
     };
     emitter.on('model:created', onCreated);
     this.unbindHandlers.push(() => emitter.off('model:created', onCreated));
 
-    const onMounted = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'mounted' });
+    const onMounted = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'mounted' });
     };
     emitter.on('model:mounted', onMounted);
     this.unbindHandlers.push(() => emitter.off('model:mounted', onMounted));
 
-    const onGenericBeforeStart = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:start' });
+    const onGenericBeforeStart = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:start' });
     };
     emitter.on('model:event:beforeRender:start', onGenericBeforeStart);
     this.unbindHandlers.push(() => emitter.off('model:event:beforeRender:start', onGenericBeforeStart));
 
-    const onGenericBeforeEnd = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:end' });
+    const onGenericBeforeEnd = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:end' });
     };
     emitter.on('model:event:beforeRender:end', onGenericBeforeEnd);
     this.unbindHandlers.push(() => emitter.off('model:event:beforeRender:end', onGenericBeforeEnd));
 
-    const onUnmounted = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'unmounted' });
+    const onUnmounted = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'unmounted' });
     };
     emitter.on('model:unmounted', onUnmounted);
     this.unbindHandlers.push(() => emitter.off('model:unmounted', onUnmounted));
 
-    const onDestroyed = (e: LifecycleEvent) => {
+    const onDestroyed = async (e: LifecycleEvent) => {
       const targetBucket = this.itemsByTargetUid.get(e.uid);
       const event = { ...e, type: 'destroyed' as const };
       if (targetBucket && targetBucket.size) {
@@ -201,7 +204,7 @@ export class ModelOperationScheduler {
           const it = this.itemsById.get(id);
           if (!it) continue;
           if (this.shouldTrigger(it.options.when, event)) {
-            void this.tryExecuteOnce(id, event);
+            await this.tryExecuteOnce(id, event);
           } else {
             this.internalCancel(id);
           }
@@ -220,14 +223,14 @@ export class ModelOperationScheduler {
     if (this.subscribedEventNames.has(name)) return;
     this.subscribedEventNames.add(name);
     const emitter = this.engine.emitter;
-    const onStart = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:start` as const });
+    const onStart = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:start` as LifecycleType });
     };
-    const onEnd = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:end` as const });
+    const onEnd = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:end` as LifecycleType });
     };
-    const onError = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:error` as const });
+    const onError = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:error` as LifecycleType });
     };
     emitter.on(`model:event:${name}:start`, onStart);
     emitter.on(`model:event:${name}:end`, onEnd);
@@ -239,12 +242,12 @@ export class ModelOperationScheduler {
 
   private parseEventWhen(when?: ScheduleWhen): { name: string; phase: 'start' | 'end' | 'error' } | null {
     if (!when || typeof when !== 'string') return null;
-    const m = /^event:([^:]+):(start|end|error)$/.exec(when);
+    const m = /^event:(.+):(start|end|error)$/.exec(when);
     if (!m) return null;
     return { name: m[1], phase: m[2] as 'start' | 'end' | 'error' };
   }
 
-  private processLifecycleEvent(targetUid: string, event: LifecycleEvent) {
+  private async processLifecycleEvent(targetUid: string, event: LifecycleEvent) {
     const targetBucket = this.itemsByTargetUid.get(targetUid);
     if (!targetBucket || targetBucket.size === 0) return;
     const ids = Array.from(targetBucket.keys());
@@ -253,7 +256,7 @@ export class ModelOperationScheduler {
       if (!item) continue;
       const should = this.shouldTrigger(item.options.when, event);
       if (!should) continue;
-      void this.tryExecuteOnce(id, event);
+      await this.tryExecuteOnce(id, event);
     }
   }
 
@@ -271,6 +274,9 @@ export class ModelOperationScheduler {
       if (!model) return;
       await Promise.resolve(item.fn(model));
     } catch (err) {
+      if (err instanceof FlowExitAllException) {
+        throw err;
+      }
       this.engine.logger?.error?.(
         { err, id, fromUid: item.fromUid, toUid: item.toUid, when: item.options.when },
         'ModelOperationScheduler: operation execution failed',

package/src/types.ts

@@ -172,6 +172,18 @@ export interface ActionDefinition<TModel extends FlowModel = FlowModel, TCtx ext
    * - StepDefinition.hideInSettings can override the ActionDefinition value.
    */
   hideInSettings?: boolean | ((ctx: TCtx) => boolean | Promise<boolean>);
+  /**
+   * Whether to disable this step/action in settings menus.
+   * - Supports static boolean and dynamic decision based on runtime context.
+   * - StepDefinition.disabledInSettings can override the ActionDefinition value.
+   */
+  disabledInSettings?: boolean | ((ctx: TCtx) => boolean | Promise<boolean>);
+  /**
+   * Optional reason shown when this step/action is disabled in settings menus.
+   * - Supports static string and dynamic resolver based on runtime context.
+   * - StepDefinition.disabledReasonInSettings can override the ActionDefinition value.
+   */
+  disabledReasonInSettings?: string | ((ctx: TCtx) => string | Promise<string>);
   /**
    * 在执行 Action 前为 ctx 定义临时属性。
    * - 仅支持 PropertyOptions 形态（例如：{ foo: { value: 5 } }）；
@@ -213,12 +225,37 @@ export type FlowEventName =
   // fallback to any string for extensibility
   | (string & {});
 
+/**
+ * 事件流的执行时机（phase）。
+ *
+ * 说明：
+ * - 缺省（phase 未配置）表示保持现有行为；
+ * - 当配置了 phase 时，运行时会将其映射为 `scheduleModelOperation` 的 `when` 锚点；
+ * - phase 同时适用于动态事件流（实例级）与静态流（内置）。
+ */
+export type FlowEventPhase =
+  | 'beforeAllFlows'
+  | 'afterAllFlows'
+  | 'beforeFlow'
+  | 'afterFlow'
+  | 'beforeStep'
+  | 'afterStep';
+
 /**
  * Flow 事件类型（供 FlowDefinitionOptions.on 使用）。
  */
 export type FlowEvent<TModel extends FlowModel = FlowModel> =
   | FlowEventName
-  | { eventName: FlowEventName; defaultParams?: Record<string, any> };
+  | {
+      eventName: FlowEventName;
+      defaultParams?: Record<string, any>;
+      /** 动态事件流的执行时机（默认 beforeAllFlows） */
+      phase?: FlowEventPhase;
+      /** phase 为 beforeFlow/afterFlow/beforeStep/afterStep 时使用 */
+      flowKey?: string;
+      /** phase 为 beforeStep/afterStep 时使用 */
+      stepKey?: string;
+    };
 
 /**
  * 事件分发选项。

package/src/utils/__tests__/dateVariable.test.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 } from 'vitest';
+import {
+  decodeBase64Url,
+  encodeBase64Url,
+  isCompleteCtxDatePath,
+  isCtxDateExpression,
+  parseCtxDateExpression,
+  resolveCtxDatePath,
+  serializeCtxDateValue,
+} from '../dateVariable';
+
+describe('dateVariable utils', () => {
+  it('encodes and decodes base64url', () => {
+    const raw = '2026-02-12 10:11:12';
+    const encoded = encodeBase64Url(raw);
+    const decoded = decodeBase64Url(encoded);
+    expect(decoded).toBe(raw);
+  });
+
+  it('detects ctx.date expression', () => {
+    expect(isCtxDateExpression('{{ ctx.date.preset.today }}')).toBe(true);
+    expect(isCtxDateExpression('{{ ctx.user.name }}')).toBe(false);
+    expect(isCtxDateExpression('')).toBe(false);
+  });
+
+  it('serializes preset/relative/exact single/range', () => {
+    expect(serializeCtxDateValue({ type: 'today' })).toBe('{{ ctx.date.preset.today }}');
+    expect(serializeCtxDateValue({ type: 'next', unit: 'day', number: 12 })).toBe(
+      '{{ ctx.date.relative.next.day.n12 }}',
+    );
+
+    const single = serializeCtxDateValue('2026-02-12');
+    expect(single?.startsWith('{{ ctx.date.exact.single.date.v')).toBe(true);
+
+    const range = serializeCtxDateValue(['2026-02-12', '2026-02-20']);
+    expect(range?.startsWith('{{ ctx.date.exact.range.date.v')).toBe(true);
+    expect(range?.includes('.v')).toBe(true);
+  });
+
+  it('parses expression back to ui value', () => {
+    expect(parseCtxDateExpression('{{ ctx.date.preset.today }}')).toEqual({ type: 'today' });
+    expect(parseCtxDateExpression('{{ ctx.date.relative.past.month.n2 }}')).toEqual({
+      type: 'past',
+      unit: 'month',
+      number: 2,
+    });
+
+    const singleExpr = serializeCtxDateValue('2026-02-12')!;
+    expect(parseCtxDateExpression(singleExpr)).toBe('2026-02-12');
+
+    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20'])!;
+    expect(parseCtxDateExpression(rangeExpr)).toEqual(['2026-02-12', '2026-02-20']);
+  });
+
+  it('resolves preset/relative/exact path', () => {
+    expect(typeof resolveCtxDatePath(['date', 'preset', 'now'])).toBe('string');
+
+    const today = resolveCtxDatePath(['date', 'preset', 'today']);
+    expect(typeof today).toBe('string');
+    expect(today).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+
+    const rel = resolveCtxDatePath(['date', 'relative', 'next', 'day', 'n12']);
+    expect(typeof rel).toBe('string');
+    expect(rel).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+
+    const singleExpr = serializeCtxDateValue('2026-02-12')!;
+    const token = singleExpr.replace('{{ ctx.date.exact.single.date.', '').replace(' }}', '');
+    expect(resolveCtxDatePath(['date', 'exact', 'single', 'date', token])).toBe('2026-02-12');
+
+    const rangeExpr = serializeCtxDateValue(['2026-02-12', '2026-02-20'])!;
+    const parts = rangeExpr.replace('{{ ctx.date.exact.range.date.', '').replace(' }}', '').split('.');
+    expect(resolveCtxDatePath(['date', 'exact', 'range', 'date', parts[0], parts[1]])).toEqual([
+      '2026-02-12',
+      '2026-02-20',
+    ]);
+  });
+
+  it('validates complete ctx.date path', () => {
+    expect(isCompleteCtxDatePath(['date', 'preset', 'today'])).toBe(true);
+    expect(isCompleteCtxDatePath(['date', 'relative', 'next', 'day', 'n12'])).toBe(true);
+    expect(isCompleteCtxDatePath(['date', 'exact', 'single', 'date', 'vabc'])).toBe(true);
+    expect(isCompleteCtxDatePath(['date', 'exact', 'range', 'date', 'vabc', 'vdef'])).toBe(true);
+    expect(isCompleteCtxDatePath(['date', 'relative', 'next', 'day'])).toBe(false);
+    expect(isCompleteCtxDatePath(['user', 'name'])).toBe(false);
+  });
+
+  it('handles invalid base64 and path gracefully', () => {
+    expect(decodeBase64Url('@@@')).toBeUndefined();
+    expect(parseCtxDateExpression('{{ ctx.date.exact.single.date.v@@@ }}')).toBeUndefined();
+    expect(resolveCtxDatePath(['date', 'exact', 'single', 'date', 'v@@@'])).toBeUndefined();
+  });
+});

package/src/utils/__tests__/params-resolvers.test.ts

@@ -491,6 +491,46 @@ describe('resolveExpressions', () => {
         ],
       });
     });
+
+    test('should resolve dot-only path with dashed keys', async () => {
+      ctx.defineProperty('formValues', {
+        value: {
+          'oho-test': {
+            'o2m-users': [1, 2],
+          },
+        },
+      });
+
+      const params = '{{ctx.formValues.oho-test.o2m-users}}';
+
+      const result = await resolveExpressions(params, ctx);
+
+      expect(result).toEqual([1, 2]);
+    });
+
+    test('should resolve dashed keys inside template strings', async () => {
+      ctx.defineProperty('formValues', {
+        value: {
+          'oho-test': {
+            'o2m-users': 'X',
+          },
+        },
+      });
+
+      const params = 'prefix {{ctx.formValues.oho-test.o2m-users}} suffix';
+
+      const result = await resolveExpressions(params, ctx);
+
+      expect(result).toEqual('prefix X suffix');
+    });
+
+    test('should not treat subtraction as dashed key path', async () => {
+      const params = '{{ctx.aa.bb-ctx.cc}}';
+
+      const result = await resolveExpressions(params, ctx);
+
+      expect(result).toEqual(5);
+    });
   });
 
   // 测试高级功能：多表达式模板字符串

package/src/utils/__tests__/runjsRequireAsyncAutoWhitelist.test.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { beforeEach, describe, expect, it } from 'vitest';
+import { runjsRequireAsync } from '../runjsModuleLoader';
+import { __resetRunJSSafeGlobalsRegistryForTests, createSafeWindow } from '../safeGlobals';
+
+beforeEach(() => {
+  __resetRunJSSafeGlobalsRegistryForTests();
+});
+
+describe('runjsRequireAsync auto whitelist', () => {
+  it('should allow safeWindow to access globals introduced during requireAsync', async () => {
+    const key = '__nb_require_async_added_global__';
+    delete (window as any)[key];
+
+    const safeWin: any = createSafeWindow();
+    expect(() => safeWin[key]).toThrow(/not allowed/);
+
+    const requirejs: any = (deps: string[], onLoad: (...args: any[]) => void) => {
+      // Simulate a remote library attaching itself to the real window.
+      (window as any)[key] = { ok: true };
+      onLoad(undefined);
+    };
+
+    await runjsRequireAsync(requirejs, 'https://example.com/fake-lib.js');
+
+    expect(safeWin[key]).toEqual({ ok: true });
+
+    delete (window as any)[key];
+  });
+});

package/src/utils/__tests__/runjsTemplateCompat.test.ts

@@ -0,0 +1,159 @@
+/**
+ * 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, it, expect, vi } from 'vitest';
+import * as jsxTransform from '../../utils/jsxTransform';
+import { prepareRunJsCode, preprocessRunJsTemplates } from '../runjsTemplateCompat';
+
+describe('runjsTemplateCompat', () => {
+  describe('preprocessRunJsTemplates', () => {
+    it('hoists bare {{ }} placeholders into top-level resolved vars', () => {
+      const src = `const a = {{ctx.user.id}};`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`const a = __runjs_ctx_tpl_0;`);
+    });
+
+    it('replaces string literals containing {{ }} via split/join, without injecting await into nested functions', () => {
+      const src = `const s = '{{ctx.user.id}}';`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}")`);
+      expect(out).toContain(`.split("{{ctx.user.id}}").join(`);
+    });
+
+    it('does not transform arguments inside explicit ctx.resolveJsonTemplate(...) call', () => {
+      const src = `const v = await ctx.resolveJsonTemplate('{{ctx.user.id}}');\nconst s = '{{ctx.user.id}}';`;
+      const out = preprocessRunJsTemplates(src);
+      // inside call: keep raw
+      expect(out).toContain(`await ctx.resolveJsonTemplate('{{ctx.user.id}}')`);
+      // outside call: transform
+      expect(out).toContain(`__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}")`);
+    });
+
+    it('keeps template markers in comments unchanged', () => {
+      const src = `// {{ctx.user.id}}\nconst a = 1;`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toBe(src);
+    });
+
+    it('supports template literals containing {{ }}', () => {
+      const src = 'const s = `hi {{ctx.user.name}}`;';
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.name}}");`);
+      expect(out).toContain(`\`hi {{ctx.user.name}}\``);
+      expect(out).toContain(`.split("{{ctx.user.name}}").join(`);
+    });
+
+    it('does not rewrite non-ctx {{ }} patterns (e.g. JSX style object) while still rewriting ctx placeholders', () => {
+      const src = `const id = {{ctx.user.id}};\nctx.render(<div style={{ width: '100%' }} />);`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`style={{ width: '100%' }}`);
+      expect(out).not.toContain(`resolveJsonTemplate("{{ width: '100%' }}")`);
+    });
+
+    it('avoids injecting await into non-async nested function bodies', () => {
+      const src = `
+function f() {
+  return {{ctx.user.id}};
+}
+return f();
+`.trim();
+      const out = preprocessRunJsTemplates(src);
+      // The only await should be in the top-level preamble
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`return __runjs_ctx_tpl_0;`);
+      expect(out).not.toContain(`return (await ctx.resolveJsonTemplate`);
+    });
+
+    it('is tolerant to already-preprocessed code (idempotent heuristic)', () => {
+      const src =
+        `const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");\n` +
+        `const s = ("{{ctx.user.id}}").split("{{ctx.user.id}}").join(__runjs_templateValueToString(__runjs_ctx_tpl_0, "{{ctx.user.id}}"));`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toBe(src);
+    });
+
+    it('rewrites object literal string keys via computed property to keep syntax valid', () => {
+      const src = `const o = { '{{ctx.user.id}}': 1 };`;
+      const out = preprocessRunJsTemplates(src);
+      expect(out).toContain(`const __runjs_ctx_tpl_0 = await ctx.resolveJsonTemplate("{{ctx.user.id}}");`);
+      expect(out).toContain(`{ [`);
+      expect(out).toContain(`]: 1 }`);
+      expect(out).toContain(`.split("{{ctx.user.id}}").join(`);
+    });
+  });
+
+  describe('prepareRunJsCode', () => {
+    it('preprocesses templates and compiles JSX', async () => {
+      const src = `
+const name = '{{ctx.user.name}}';
+ctx.render(<div className="x">{name}</div>);
+`.trim();
+      const out = await prepareRunJsCode(src, { preprocessTemplates: true });
+      expect(out).toMatch(/ctx\.React\.createElement/);
+      expect(out).toMatch(/ctx\.resolveJsonTemplate/);
+    });
+
+    it('injects ctx.libs ensure preamble for member access', async () => {
+      const src = `return ctx.libs.lodash;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`/* __runjs_ensure_libs */`);
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('injects ctx.libs ensure preamble for bracket access with string literal', async () => {
+      const src = `return ctx.libs['lodash'];`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('injects ctx.libs ensure preamble for object destructuring', async () => {
+      const src = `const { lodash } = ctx.libs;\nreturn lodash;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('does not inject ctx.libs preamble when ctx.libs only appears in string/comment', async () => {
+      const src = `// ctx.libs.lodash\nconst s = "ctx.libs.lodash";\nreturn s;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).not.toContain(`__runjs_ensure_libs`);
+    });
+
+    it('is idempotent for already-prepared code', async () => {
+      const src = `return ctx.libs['lodash'];`;
+      const out1 = await prepareRunJsCode(src, { preprocessTemplates: false });
+      const out2 = await prepareRunJsCode(out1, { preprocessTemplates: false });
+      expect(out2).toBe(out1);
+      expect(out2.match(/__runjs_ensure_libs/g)?.length ?? 0).toBe(1);
+    });
+
+    it('does not break JSX attribute string values when preprocessing templates', async () => {
+      const src = `ctx.render(<Input title="{{ctx.user.name}}" />);`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: true });
+      expect(out).toMatch(/ctx\.React\.createElement/);
+      expect(out).toMatch(/title:\s*\(/);
+      expect(out).toContain(`.split("{{ctx.user.name}}").join(`);
+    });
+
+    it('caches prepared code by source and preprocessTemplates option', async () => {
+      const spy = vi.spyOn(jsxTransform, 'compileRunJs');
+      const src = `/* cache-test */\nconst a = 1;\nreturn a;`;
+
+      await prepareRunJsCode(src, { preprocessTemplates: false });
+      await prepareRunJsCode(src, { preprocessTemplates: false });
+      await prepareRunJsCode(src, { preprocessTemplates: true });
+      await prepareRunJsCode(src, { preprocessTemplates: true });
+
+      expect(spy).toHaveBeenCalledTimes(2);
+      spy.mockRestore();
+    });
+  });
+});

package/src/utils/__tests__/runjsValue.test.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 } from 'vitest';
+import { extractUsedVariablePathsFromRunJS, isRunJSValue, normalizeRunJSValue } from '../runjsValue';
+
+describe('runjsValue utils', () => {
+  it('isRunJSValue: strict shape detection', () => {
+    expect(isRunJSValue({ code: 'return 1' })).toBe(true);
+    expect(isRunJSValue({ code: 'return 1', version: 'v1' })).toBe(true);
+
+    expect(isRunJSValue(null)).toBe(false);
+    expect(isRunJSValue('return 1')).toBe(false);
+    expect(isRunJSValue({})).toBe(false);
+    expect(isRunJSValue({ version: 'v1' })).toBe(false);
+    expect(isRunJSValue({ code: 1 })).toBe(false);
+    expect(isRunJSValue({ code: 'return 1', foo: 1 })).toBe(false);
+    expect(isRunJSValue([])).toBe(false);
+  });
+
+  it('normalizeRunJSValue: defaults version to v1', () => {
+    expect(normalizeRunJSValue({ code: 'return 1' })).toEqual({ code: 'return 1', version: 'v1' });
+    expect(normalizeRunJSValue({ code: 'return 1', version: 'v2' })).toEqual({ code: 'return 1', version: 'v2' });
+  });
+
+  it('extractUsedVariablePathsFromRunJS: extracts ctx usage (dot + bracket root)', () => {
+    const code = `
+      // comment: ctx.ignore.me
+      const x = "ctx.ignore.too";
+      return ctx.formValues.a + ctx.record.id + ctx.someVar + ctx['user'].name;
+    `;
+    const out = extractUsedVariablePathsFromRunJS(code);
+    expect(out.formValues).toContain('a');
+    expect(out.record).toContain('id');
+    expect(out.someVar).toContain('');
+    expect(out.user).toContain('name');
+  });
+});

package/src/utils/__tests__/safeGlobals.test.ts

@@ -7,8 +7,19 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, expect, it } from 'vitest';
-import { createSafeDocument, createSafeWindow, createSafeNavigator } from '../safeGlobals';
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  __resetRunJSSafeGlobalsRegistryForTests,
+  createSafeDocument,
+  createSafeNavigator,
+  createSafeWindow,
+  registerRunJSSafeDocumentGlobals,
+  registerRunJSSafeWindowGlobals,
+} from '../safeGlobals';
+
+beforeEach(() => {
+  __resetRunJSSafeGlobalsRegistryForTests();
+});
 
 describe('safeGlobals', () => {
   it('createSafeWindow exposes only allowed globals and extras', () => {
@@ -17,10 +28,36 @@ describe('safeGlobals', () => {
     expect(win.console).toBeDefined();
     expect(win.foo).toBe(123);
     expect(new win.FormData()).toBeInstanceOf(window.FormData);
+    if (typeof window.Blob !== 'undefined') {
+      expect(typeof win.Blob).toBe('function');
+      expect(new win.Blob(['x'])).toBeInstanceOf(window.Blob);
+    }
+    if (typeof window.URL !== 'undefined') {
+      expect(win.URL).toBe(window.URL);
+      expect(typeof win.URL.createObjectURL).toBe('function');
+    }
     // access to location proxy is allowed, but sensitive props throw
     expect(() => win.location.href).toThrow(/not allowed/);
   });
 
+  it('createSafeWindow allows writing new props and reading them back', () => {
+    const win: any = createSafeWindow();
+    win.someLib = { ok: true };
+    expect(win.someLib).toEqual({ ok: true });
+    expect('someLib' in win).toBe(true);
+  });
+
+  it('createSafeWindow can access dynamically registered globals from real window', () => {
+    const key = '__nb_safe_window_global__';
+    (window as any)[key] = { v: 1 };
+    registerRunJSSafeWindowGlobals([key]);
+
+    const win: any = createSafeWindow();
+    expect(win[key]).toEqual({ v: 1 });
+
+    delete (window as any)[key];
+  });
+
   it('createSafeDocument exposes whitelisted methods and extras', () => {
     const doc: any = createSafeDocument({ bar: true });
     expect(typeof doc.createElement).toBe('function');
@@ -28,6 +65,24 @@ describe('safeGlobals', () => {
     expect(() => doc.cookie).toThrow(/not allowed/);
   });
 
+  it('createSafeDocument allows writing new props and reading them back', () => {
+    const doc: any = createSafeDocument();
+    doc.someLib = { ok: true };
+    expect(doc.someLib).toEqual({ ok: true });
+    expect('someLib' in doc).toBe(true);
+  });
+
+  it('createSafeDocument can access dynamically registered globals from real document', () => {
+    const key = '__nb_safe_document_global__';
+    (document as any)[key] = 123;
+    registerRunJSSafeDocumentGlobals([key]);
+
+    const doc: any = createSafeDocument();
+    expect(doc[key]).toBe(123);
+
+    delete (document as any)[key];
+  });
+
   it('createSafeNavigator exposes limited props and guards others', () => {
     const nav: any = createSafeNavigator();
     // clipboard object should always exist