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

package/src/runjs-context/snippets/scene/table/cell-open-dialog.snippet.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { SnippetModule } from '../../types';
+import { JSColumnRunJSContext } from '../../../contexts/JSColumnRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSColumnRunJSContext],
+  prefix: 'sn-col-open-dialog',
+  label: 'Cell dialog with row data',
+  description: 'Render a button in cell to open dialog via ctx.openView with current row context',
+  locales: {
+    'zh-CN': {
+      label: '单元格对话框（显示行数据）',
+      description: '在单元格渲染按钮，点击后通过 ctx.openView 打开弹窗并传入当前行上下文',
+    },
+  },
+  content: `
+// Render a button inside the cell
+ctx.element.innerHTML = '<button class="nb-cell-btn" style="padding:4px 8px">' + ctx.t('View') + '</button>';
+
+const button = ctx.element.querySelector('.nb-cell-btn');
+const popupUid = ctx.model.uid + '-1'; // popupUid should be stable and better bound to ctx.model.uid
+const primaryKey = ctx.collection?.primaryKey || 'id';
+
+button?.addEventListener('click', async () => {
+  await ctx.openView(popupUid, {
+    mode: 'dialog',
+    title: ctx.t('Row detail'),
+    params: {
+      filterByTk: ctx.record?.[primaryKey],
+      record: ctx.record,
+    },
+  });
+});
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/scene/{actions → table}/collection-selected-count.snippet.ts

@@ -7,10 +7,20 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-export default {
-  contexts: ['JSCollectionActionRunJSContext'],
+import type { SnippetModule } from '../../types';
+import { JSCollectionActionRunJSContext } from '../../../contexts/JSCollectionActionRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSCollectionActionRunJSContext],
   prefix: 'sn-act-selected-count',
   label: 'Selected count',
+  description: 'Show number of selected rows in list action',
+  locales: {
+    'zh-CN': {
+      label: '选中数量',
+      description: '提示当前选中行的数量',
+    },
+  },
   content: `
 const rows = ctx.resource?.getSelectedRows?.() || [];
 if (!rows.length) {
@@ -20,3 +30,5 @@ if (!rows.length) {
 }
 `,
 };
+
+export default snippet;

package/src/runjs-context/snippets/scene/table/concat-fields.snippet.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 type { SnippetModule } from '../../types';
+import { JSColumnRunJSContext } from '../../../contexts/JSColumnRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSColumnRunJSContext],
+  prefix: 'sn-col-concat',
+  label: 'Concat two fields',
+  description: 'Combine two field values into the current column cell',
+  locales: {
+    'zh-CN': {
+      label: '拼接两个字段值',
+      description: '在自定义列中拼接两个字段的值作为显示内容',
+    },
+  },
+  content: `
+// Demo helper: infer previous columns' dataIndex values based on the current column position
+// In production, hardcode field names to avoid surprises when columns are reordered
+function resolvePreviousDataIndexes() {
+  const parent = ctx.model?.parent;
+  const list = parent?.subModels?.columns;
+  if (!Array.isArray(list)) return [];
+  const currentUid = ctx.model?.uid;
+  const currentIndex = list.findIndex((item) => item?.uid === currentUid);
+  if (currentIndex <= 0) return [];
+  return list
+    .slice(Math.max(0, currentIndex - 2), currentIndex)
+    .map((item) => (item && item.props ? item.props.dataIndex : undefined))
+    .filter((key) => typeof key === 'string' && key.length > 0);
+}
+
+const [autoFieldA, autoFieldB] = resolvePreviousDataIndexes();
+
+// Fallback: manually specify field keys when auto detection is not enough
+const fieldA = autoFieldA || 'firstName';
+const fieldB = autoFieldB || 'lastName';
+
+const normalize = (value) => {
+  if (value === undefined || value === null) return '';
+  return String(value).trim();
+};
+
+const valueA = normalize(ctx.record?.[fieldA]);
+const valueB = normalize(ctx.record?.[fieldB]);
+
+const parts = [valueA, valueB].filter((item) => item.length > 0);
+
+ctx.element.textContent = parts.length ? parts.join(' / ') : ctx.t('N/A');
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/scene/table/destroy-selected.snippet.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { SnippetModule } from '../../types';
+import { JSCollectionActionRunJSContext } from '../../../contexts/JSCollectionActionRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSCollectionActionRunJSContext],
+  prefix: 'sn-act-destroy-selected',
+  label: 'Destroy selected rows',
+  description: 'Delete selected rows via resource.destroySelectedRows()',
+  locales: {
+    'zh-CN': {
+      label: '删除选中行',
+      description: '通过 resource.destroySelectedRows() 删除选中行',
+    },
+  },
+  content: `
+const rows = ctx.resource?.getSelectedRows?.() || [];
+if (!rows.length) {
+  ctx.message.warning(ctx.t('Please select data'));
+  return;
+}
+
+await ctx.resource.destroySelectedRows();
+ctx.message.success(ctx.t('Deleted {{count}} rows', { count: rows.length }));
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/scene/table/export-selected-json.snippet.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { SnippetModule } from '../../types';
+import { JSCollectionActionRunJSContext } from '../../../contexts/JSCollectionActionRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSCollectionActionRunJSContext],
+  prefix: 'sn-act-export',
+  label: 'Export selected rows as JSON',
+  description: 'Download selected rows as a JSON file',
+  locales: {
+    'zh-CN': {
+      label: '导出选中行为 JSON',
+      description: '将选中的行导出为 JSON 文件下载',
+    },
+  },
+  content: `
+const rows = ctx.resource?.getSelectedRows?.() || [];
+if (!rows.length) {
+  ctx.message.warning(ctx.t('Please select at least one row'));
+  return;
+}
+
+// Create JSON file and download
+const jsonStr = JSON.stringify(rows, null, 2);
+const blob = new Blob([jsonStr], { type: 'application/json' });
+const url = URL.createObjectURL(blob);
+const link = document.createElement('a');
+link.href = url;
+link.download = \`export-\${new Date().toISOString().split('T')[0]}.json\`;
+link.click();
+URL.revokeObjectURL(url);
+
+ctx.message.success(ctx.t('Exported {{count}} records', { count: rows.length }));
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/scene/{actions → table}/iterate-selected-rows.snippet.ts

@@ -7,10 +7,20 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-export default {
-  contexts: ['JSCollectionActionRunJSContext'],
+import type { SnippetModule } from '../../types';
+import { JSCollectionActionRunJSContext } from '../../../contexts/JSCollectionActionRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSCollectionActionRunJSContext],
   prefix: 'sn-act-iterate',
   label: 'Iterate selected rows',
+  description: 'Loop through selected rows and process each record',
+  locales: {
+    'zh-CN': {
+      label: '遍历选中行',
+      description: '遍历选中行并处理每条记录',
+    },
+  },
   content: `
 const rows = ctx.resource?.getSelectedRows?.() || [];
 for (const row of rows) {
@@ -19,3 +29,5 @@ for (const row of rows) {
 ctx.message.success(ctx.t('Processed {{count}} rows', { count: rows.length }));
 `,
 };
+
+export default snippet;

package/src/runjs-context/snippets/types.ts

@@ -7,11 +7,15 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
+export type SnippetContextSpecifier = string | { name: string } | (new (...args: any[]) => any);
+
 export type SnippetModule = {
   content: string;
-  contexts?: string[]; // e.g., ['JSBlockRunJSContext'] or ['*']
+  contexts?: SnippetContextSpecifier[]; // e.g., [JSBlockRunJSContext] or ['*']
   versions?: string[]; // e.g., ['v1'] or ['*']
+  scenes?: string[]; // logical placement hints like ['form', 'table']
   prefix?: string; // completion trigger text
   label?: string; // display name in snippets list
   description?: string; // optional longer description
+  locales?: Record<string, { label?: string; description?: string }>;
 };

package/src/types.ts

@@ -10,6 +10,7 @@
 import { ISchema } from '@formily/json-schema';
 import { SubModelItem } from './components';
 import { FlowContext, FlowModelContext, FlowRuntimeContext, FlowSettingsContext } from './flowContext';
+import type { PropertyOptions } from './flowContext';
 import type { FlowEngine } from './flowEngine';
 import type { FlowModel } from './models';
 import { FilterGroupOptions } from './resources';
@@ -134,6 +135,8 @@ export enum ActionScene {
   BLOCK_LINKAGE_RULES = 1,
   /** 表单字段级联动规则可用 */
   FIELD_LINKAGE_RULES,
+  /** 子表单字段级联动规则可用 */
+  SUB_FORM_FIELD_LINKAGE_RULES,
   /** 详情字段级联动规则可用 */
   DETAILS_FIELD_LINKAGE_RULES,
   /** 按钮级联动规则可用 */
@@ -157,6 +160,26 @@ export interface ActionDefinition<TModel extends FlowModel = FlowModel, TCtx ext
   uiMode?: StepUIMode | ((ctx: FlowRuntimeContext<TModel>) => StepUIMode | Promise<StepUIMode>);
   scene?: ActionScene | ActionScene[];
   sort?: number;
+  /**
+   * 在执行 Action 前为 ctx 定义临时属性。
+   * - 仅支持 PropertyOptions 形态（例如：{ foo: { value: 5 } }）；
+   * - 或函数形式（接收 ctx，返回 PropertyOptions 对象；支持 Promise）。
+   */
+  defineProperties?:
+    | Record<string, PropertyOptions>
+    | ((ctx: TCtx) => Record<string, PropertyOptions> | Promise<Record<string, PropertyOptions>>);
+  /**
+   * 在执行 Action 前为 ctx 定义临时方法。
+   * - 支持 JSON 形式（对象的值应为函数）
+   * - 或函数形式（接收 ctx，返回方法对象；支持 Promise）
+   */
+  defineMethods?:
+    | Record<string, (this: TCtx, ...args: any[]) => any>
+    | ((
+        ctx: TCtx,
+      ) =>
+        | Record<string, (this: TCtx, ...args: any[]) => any>
+        | Promise<Record<string, (this: TCtx, ...args: any[]) => any>>);
 }
 
 /**
@@ -185,6 +208,16 @@ export type FlowEvent<TModel extends FlowModel = FlowModel> =
   | FlowEventName
   | { eventName: FlowEventName; defaultParams?: Record<string, any> };
 
+/**
+ * 事件分发选项。
+ */
+export interface DispatchEventOptions {
+  /** 是否顺序执行（默认并行） */
+  sequential?: boolean;
+  /** 是否使用缓存（默认 false；beforeRender 的默认值为 true，可覆盖） */
+  useCache?: boolean;
+}
+
 /**
  * 事件定义：用于事件注册表（全局/模型类级）。
  */
@@ -300,6 +333,7 @@ export interface IFlowModelRepository<T extends FlowModel = FlowModel> {
   save(model: T, options?: { onlyStepParams?: boolean }): Promise<Record<string, any>>;
   destroy(uid: string): Promise<boolean>;
   move(sourceId: string, targetId: string, position: 'before' | 'after'): Promise<void>;
+  duplicate(uid: string): Promise<Record<string, any> | null>;
 }
 
 /**

package/src/utils/__tests__/jsxTransform.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 { describe, it, expect } from 'vitest';
+import { compileRunJs } from '../../utils/jsxTransform';
+
+describe('compileRunJs', () => {
+  it('returns original code when no JSX is present', async () => {
+    const src = `const a = 1; const b = a + 1;`;
+    const out = await compileRunJs(src);
+    expect(out).toBe(src);
+  });
+
+  it('transforms JSX when sucrase is available (skip if missing)', async () => {
+    const src = `ctx.render(<div className="x">hi</div>);`;
+
+    // Try to import sucrase to decide if this environment has it installed
+    const hasSucrase = await import('sucrase').then(() => true).catch(() => false);
+
+    const out = await compileRunJs(src);
+
+    if (!hasSucrase) {
+      // Environment without sucrase: current implementation falls back to original code
+      expect(out).toBe(src);
+      return;
+    }
+
+    // sucrase available: output should contain React.createElement mapping
+    expect(out).not.toBe(src);
+    expect(out).toMatch(/ctx\.React\.createElement/);
+  });
+});

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

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import { createSafeDocument, createSafeWindow } from '../safeGlobals';
+import { createSafeDocument, createSafeWindow, createSafeNavigator } from '../safeGlobals';
 
 describe('safeGlobals', () => {
   it('createSafeWindow exposes only allowed globals and extras', () => {
@@ -26,4 +26,25 @@ describe('safeGlobals', () => {
     expect(doc.bar).toBe(true);
     expect(() => doc.cookie).toThrow(/not allowed/);
   });
+
+  it('createSafeNavigator exposes limited props and guards others', () => {
+    const nav: any = createSafeNavigator();
+    // clipboard object should always exist
+    expect(typeof nav.clipboard).toBe('object');
+    // writeText may or may not exist depending on environment
+    if (typeof navigator !== 'undefined' && (navigator as any).clipboard?.writeText) {
+      expect(typeof nav.clipboard.writeText).toBe('function');
+    } else {
+      expect(typeof nav.clipboard.writeText === 'undefined' || typeof nav.clipboard.writeText === 'function').toBe(
+        true,
+      );
+    }
+    // readable properties
+    expect(() => void nav.onLine).not.toThrow();
+    expect(() => void nav.language).not.toThrow();
+    expect(() => void nav.languages).not.toThrow();
+    // blocked properties
+    expect(() => (nav as any).geolocation).toThrow(/not allowed/);
+    expect(() => (nav as any).userAgent).toThrow(/not allowed/);
+  });
 });

package/src/utils/buildSettingsViewInputArgs.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 type { FlowModel } from '../models';
+import { inferRecordRef } from './variablesParams';
+
+/**
+ * 统一构造设置弹窗 openView 的 inputArgs：
+ * - collectionName/dataSourceKey/filterByTk：优先从 model.context 推断；否则回退父视图 inputArgs
+ * - sourceId：优先从 resource.getSourceId()；否则回退父视图 inputArgs
+ * - associationName：来自 association.resourceName 或 resource.getResourceName()
+ * - navigation：父视图 navigation 或传入的 navigationOverride
+ */
+export function buildSettingsViewInputArgs(
+  model: FlowModel,
+  extra?: Record<string, any>,
+  options?: { navigationOverride?: any },
+): Record<string, any> {
+  const defaults: Record<string, any> = {};
+
+  try {
+    // 1) 当前记录/集合
+    const ref = inferRecordRef((model as any).context);
+    if (ref?.collection) {
+      defaults.collectionName = ref.collection;
+      defaults.dataSourceKey = ref.dataSourceKey || 'main';
+      defaults.filterByTk = ref.filterByTk;
+    }
+
+    // 2) 回退父视图 inputArgs（如在抽屉/页面中）
+    const parentArgs = (model as any)?.context?.view?.inputArgs || {};
+    if (!defaults.collectionName && parentArgs?.collectionName) {
+      defaults.collectionName = parentArgs.collectionName;
+      defaults.dataSourceKey = parentArgs.dataSourceKey || defaults.dataSourceKey || 'main';
+    }
+    if (defaults.filterByTk == null && parentArgs?.filterByTk != null) {
+      defaults.filterByTk = parentArgs.filterByTk;
+    }
+    if (defaults.sourceId == null && parentArgs?.sourceId != null) {
+      defaults.sourceId = parentArgs.sourceId;
+    }
+
+    // 3) 导航（用于推断“上级弹窗”）
+    const nav = options?.navigationOverride ?? (model as any)?.context?.view?.navigation;
+    if (nav) {
+      defaults.navigation = nav;
+    }
+
+    // 4) 直接从资源读取 sourceId（优先级高于父视图）
+    const sid = (model as any)?.context?.resource?.getSourceId?.();
+    if (sid !== undefined && sid !== null && String(sid) !== '') {
+      defaults.sourceId = sid;
+    }
+
+    // 5) 关联名（用于“上级记录”）
+    const assocName =
+      (model as any)?.context?.association?.resourceName || (model as any)?.context?.resource?.getResourceName?.();
+    if (typeof assocName === 'string' && assocName) {
+      defaults.associationName = assocName;
+    }
+  } catch (_) {
+    // 忽略推断异常
+  }
+
+  return { ...defaults, ...(extra || {}) };
+}

package/src/utils/createEphemeralContext.ts

@@ -0,0 +1,142 @@
+/**
+ * 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 { FlowContext } from '../flowContext';
+import type { ActionDefinition } from '../types';
+import type { PropertyOptions } from '../flowContext';
+
+// 临时上下文：
+// - 读：优先从 scoped（临时定义）读取，兜底 parent；
+// - 写：统一写入 parent（不污染 scoped）；
+// - 注入：create 阶段 define* 写入 scoped；运行阶段 define* 写入 parent。
+type ContextDefsLike<TCtx extends FlowContext> =
+  | Partial<Pick<ActionDefinition<any, TCtx>, 'defineProperties' | 'defineMethods'>>
+  | null
+  | undefined;
+
+export async function createEphemeralContext<TCtx extends FlowContext>(
+  parent: TCtx,
+  contextDefs?: ContextDefsLike<TCtx>,
+): Promise<TCtx> {
+  // 若未提供任何上下文定义，直接复用父级上下文，避免不必要的代理包装
+  if (contextDefs == null || (!contextDefs.defineProperties && !contextDefs.defineMethods)) {
+    return parent;
+  }
+  // 1) 创建一个新的 FlowContext，专门承载“临时定义”（defineProperty/defineMethod）
+  const scoped = new FlowContext();
+  // 2) 读取优先：先从 scoped 自身取（_props/_methods），否则委托到 parent（仅 _props/_methods）
+  scoped.addDelegate(parent);
+
+  // 3) 先创建 scoped 的代理，用于注入阶段（define* 直达 scoped；读写行为与最终代理一致）
+  const scopedProxy = scoped.createProxy();
+  const scopedObj = scopedProxy as unknown as object;
+  const parentObj = parent as unknown as object;
+  const getFromParent = (key: PropertyKey) => {
+    const val = Reflect.get(parentObj, key, parentObj);
+    return typeof val === 'function' ? (val as Function).bind(parent) : val;
+  };
+  const hasInScopedOrParent = (key: PropertyKey) =>
+    key === 'defineProperty' || key === 'defineMethod' || Reflect.has(scopedObj, key) || Reflect.has(parentObj, key);
+  const injectionProxy = new Proxy(scopedProxy as TCtx, {
+    get(_t, key: PropertyKey, receiver) {
+      if (typeof key === 'string') {
+        // 注入阶段：允许在 defLike 的函数体中调用 ctx.defineProperty/defineMethod 写入 scoped
+        if (key === 'defineProperty') {
+          return (propKey: string, options: any) => (scoped as FlowContext).defineProperty(propKey, options);
+        }
+        if (key === 'defineMethod') {
+          return (name: string, fn: any, des?: string) => (scoped as FlowContext).defineMethod(name, fn, des);
+        }
+        if (Reflect.has(scopedObj, key)) {
+          return Reflect.get(scopedObj, key, receiver);
+        }
+        return getFromParent(key);
+      }
+      return Reflect.get(scopedObj, key, receiver);
+    },
+    set(_t, key: PropertyKey, value: unknown) {
+      return Reflect.set(parentObj, key, value);
+    },
+    has(_t, key: PropertyKey) {
+      return hasInScopedOrParent(key);
+    },
+    getOwnPropertyDescriptor(_t, key: PropertyKey) {
+      return Object.getOwnPropertyDescriptor(scopedObj, key) || Object.getOwnPropertyDescriptor(parentObj, key);
+    },
+  });
+
+  // 如果提供了 contextDefs，则在创建时即注入定义，便于外部更简洁地使用
+  if (contextDefs) {
+    const defs = Array.isArray(contextDefs) ? contextDefs : [contextDefs];
+    for (const defLike of defs) {
+      if (!defLike) continue;
+      // 1) defineProperties -> 写入到 scoped（避免污染父级）
+      const dp = (defLike as any).defineProperties;
+      if (dp) {
+        const raw = typeof dp === 'function' ? await dp(injectionProxy as TCtx) : dp;
+        if (!raw || typeof raw !== 'object') {
+          throw new TypeError('defineProperties must return an object of PropertyOptions');
+        }
+        const propsDef = raw as Record<string, PropertyOptions>;
+        for (const [key, options] of Object.entries(propsDef)) {
+          if (!options || typeof options !== 'object') {
+            throw new TypeError(`defineProperties['${key}'] must be a PropertyOptions object`);
+          }
+          // 直接在 scoped 上定义，确保仅限本次临时作用域
+          (scoped as FlowContext).defineProperty(key, options);
+        }
+      }
+      // 2) defineMethods -> 写入到 scoped（避免污染父级）
+      const dm = (defLike as any).defineMethods;
+      if (dm) {
+        const raw = typeof dm === 'function' ? await dm(injectionProxy as TCtx) : dm;
+        if (!raw || typeof raw !== 'object') {
+          throw new TypeError('defineMethods must return an object of functions');
+        }
+        const methodsDef = raw as Record<string, (this: TCtx, ...args: any[]) => any>;
+        for (const [key, fn] of Object.entries(methodsDef)) {
+          if (typeof fn !== 'function') {
+            throw new TypeError(`defineMethods['${key}'] must be a function`);
+          }
+          (scoped as FlowContext).defineMethod(key, fn as any);
+        }
+      }
+    }
+  }
+
+  // 4) 创建最终对外代理：读取优先 scoped，兜底父级，且后续 define* 写入父级
+  const outerProxy = new Proxy(scopedProxy as TCtx, {
+    get(_t, key: PropertyKey, receiver) {
+      if (typeof key === 'string') {
+        if (key === 'defineProperty') {
+          return (propKey: string, options: any) => (parent as FlowContext).defineProperty(propKey, options);
+        }
+        if (key === 'defineMethod') {
+          return (name: string, fn: any, des?: string) => (parent as FlowContext).defineMethod(name, fn, des);
+        }
+        if (Reflect.has(scopedObj, key)) {
+          return Reflect.get(scopedObj, key, receiver);
+        }
+        return getFromParent(key);
+      }
+      return Reflect.get(scopedObj, key, receiver);
+    },
+    set(_t, key: PropertyKey, value: unknown) {
+      return Reflect.set(parentObj, key, value);
+    },
+    has(_t, key: PropertyKey) {
+      return hasInScopedOrParent(key);
+    },
+    getOwnPropertyDescriptor(_t, key: PropertyKey) {
+      return Object.getOwnPropertyDescriptor(scopedObj, key) || Object.getOwnPropertyDescriptor(parentObj, key);
+    },
+  });
+
+  return outerProxy as TCtx;
+}

package/src/utils/index.ts

@@ -48,7 +48,6 @@ export {
   createRecordMetaFactory,
   extractUsedVariableNames,
   extractUsedVariablePaths,
-  inferParentRecordRef,
   inferRecordRef,
   type RecordParamsBuilder,
 } from './variablesParams';
@@ -58,6 +57,7 @@ export { extractPropertyPath, formatPathToVariable, isVariableExpression } from
 
 export { clearAutoFlowError, getAutoFlowError, setAutoFlowError, type AutoFlowError } from './autoFlowError';
 export { parsePathnameToViewParams, type ViewParam } from './parsePathnameToViewParams';
+export { buildSettingsViewInputArgs } from './buildSettingsViewInputArgs';
 
 // 安全全局对象（window/document）
-export { createSafeDocument, createSafeWindow } from './safeGlobals';
+export { createSafeDocument, createSafeWindow, createSafeNavigator } from './safeGlobals';