@nocobase/flow-engine 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/runjs-context/contexts/JSBlockRunJSContext.ts

@@ -7,46 +7,58 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
-import { createSafeDocument, createSafeWindow } from '../../utils';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSBlockRunJSContext extends FlowRunJSContext {
-  static injectDefaultGlobals() {
-    return { window: createSafeWindow(), document: createSafeDocument() };
-  }
-  constructor(delegate: any) {
-    super(delegate);
-    // 显式暴露本场景所需属性
-    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('value', { get: () => (this as any)._delegate['value'] });
-  }
-}
+export class JSBlockRunJSContext extends FlowRunJSContext {}
 
 JSBlockRunJSContext.define({
-  label: 'JSBlock RunJS context',
+  label: 'RunJS context',
   properties: {
-    element: 'ElementProxy，安全 DOM 容器。支持 innerHTML/append 等',
-    record: '当前记录（只读，存在于数据块/详情等场景）',
-    value: '当前值（若存在）',
-    React: 'React（已注入）',
-    antd: 'AntD（已注入）',
+    element: {
+      description: `ElementProxy instance providing a safe DOM container.
+      Supports innerHTML, append, and other DOM manipulation methods.
+      Use this to render content in the JS block.`,
+      detail: 'ElementProxy',
+      properties: {
+        innerHTML: 'Set or read the HTML content of the container element.',
+      },
+    },
+    record: `Current record data object (read-only).
+      Available when the JS block is within a data block or detail view context.`,
+    value: 'Current value of the field or component, if available in the current context.',
+    React: 'React library',
+    antd: 'Ant Design library',
   },
   methods: {
-    onRefReady: 'Container ref ready callback:\n```js\nctx.onRefReady(ctx.ref, el => { /* ... */ })\n```',
+    onRefReady: `Wait for container DOM element to be ready before executing callback.
+      Parameters: (ref: React.RefObject, callback: (element: HTMLElement) => void, timeout?: number) => void
+      Example: ctx.onRefReady(ctx.ref, (el) => { el.innerHTML = "Ready!" })`,
     requireAsync: 'Load external library: `const lib = await ctx.requireAsync(url)`',
-  },
-  snipastes: {
-    'Render HTML': { $ref: 'scene/jsblock/render-basic', prefix: 'sn-jsb-html' },
-    'Render React': { $ref: 'scene/jsblock/render-react', prefix: 'sn-jsb-react' },
-    'Init ECharts': { $ref: 'libs/echarts-init', prefix: 'sn-echarts' },
-    'Render card': { $ref: 'scene/jsblock/render-card', prefix: 'sn-jsb-card' },
-    'Button handler': { $ref: 'scene/jsblock/render-button-handler', prefix: 'sn-jsb-button' },
-    'JSX mount': { $ref: 'scene/jsblock/jsx-mount', prefix: 'sn-jsx-mount' },
-    'JSX unmount': { $ref: 'scene/jsblock/jsx-unmount', prefix: 'sn-jsx-unmount' },
-    Notification: { $ref: 'global/notification-open', prefix: 'sn-notify' },
-    'Window open': { $ref: 'global/window-open', prefix: 'sn-window-open' },
-    'Add click listener': { $ref: 'scene/jsblock/add-event-listener', prefix: 'sn-jsb-click' },
-    'Append style': { $ref: 'scene/jsblock/append-style', prefix: 'sn-jsb-style' },
+    importAsync: 'Dynamically import ESM module: `const mod = await ctx.importAsync(url)`',
   },
 });
+
+JSBlockRunJSContext.define(
+  {
+    label: 'RunJS 上下文',
+    properties: {
+      element: {
+        description: 'ElementProxy，安全的 DOM 容器，支持 innerHTML/append 等',
+        detail: 'ElementProxy',
+        properties: {
+          innerHTML: '读取或设置容器的 HTML 内容',
+        },
+      },
+      record: '当前记录（只读，用于数据区块/详情等场景）',
+      value: '当前值（若存在）',
+      React: 'React 库',
+      antd: 'Ant Design 库',
+    },
+    methods: {
+      onRefReady: '容器 ref 就绪回调：\n```js\nctx.onRefReady(ctx.ref, el => { /* ... */ })\n```',
+      requireAsync: '加载外部库：`const lib = await ctx.requireAsync(url)`',
+      importAsync: '按 URL 动态导入 ESM 模块：`const mod = await ctx.importAsync(url)`',
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSCollectionActionRunJSContext.ts

@@ -7,26 +7,25 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSCollectionActionRunJSContext extends FlowRunJSContext {
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('resource', { get: () => (this as any)._delegate['resource'] });
-  }
-}
+export class JSCollectionActionRunJSContext extends FlowRunJSContext {}
 
 JSCollectionActionRunJSContext.define({
   label: 'JSCollectionAction RunJS context',
   properties: {
-    resource: '列表资源（选中行/分页等）',
-  },
-  methods: {
-    runAction: 'Run action',
-    message: 'Message API',
-  },
-  snipastes: {
-    'Selected count': { $ref: 'scene/actions/collection-selected-count', prefix: 'sn-act-selected-count' },
-    'Iterate selected rows': { $ref: 'scene/actions/iterate-selected-rows', prefix: 'sn-act-iterate' },
+    resource: `Collection resource instance providing access to selected rows, pagination, and data operations.
+      Use ctx.resource.selectedRows to get selected records.
+      Use ctx.resource.pagination for page info.`,
   },
 });
+
+JSCollectionActionRunJSContext.define(
+  {
+    label: 'JS 集合动作 RunJS 上下文',
+    properties: {
+      resource: '列表资源（包含选中行/分页信息等）',
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSColumnRunJSContext.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 { FlowRunJSContext } from '../../flowContext';
+
+/**
+ * RunJS context for JSColumnModel (table custom column).
+ * Focused on per-row rendering with access to current record and cell element.
+ */
+export class JSColumnRunJSContext extends FlowRunJSContext {}
+
+JSColumnRunJSContext.define({
+  label: 'JSColumn RunJS context',
+  properties: {
+    element:
+      'ElementProxy instance providing a safe DOM container for the current table cell. Supports innerHTML/append and basic DOM APIs.',
+    record: 'Current row record object (read-only).',
+    recordIndex: 'Index of the current row in the page (0-based).',
+    collection: 'Collection definition metadata (read-only).',
+    viewer:
+      'View controller providing dialog/drawer/embed helpers for interactions initiated from the cell (e.g., open details).',
+    React: 'React library',
+    antd: 'Ant Design library',
+  },
+  methods: {
+    onRefReady:
+      'Wait for cell DOM element to be ready before executing callback. Parameters: (ref, callback, timeout?) => void',
+    requireAsync: 'Load external library by URL: `const lib = await ctx.requireAsync(url)`',
+    importAsync: 'Dynamically import ESM module by URL: `const mod = await ctx.importAsync(url)`',
+  },
+});
+
+JSColumnRunJSContext.define(
+  {
+    label: 'JS 列 RunJS 上下文',
+    properties: {
+      element: 'ElementProxy，表格单元格的安全 DOM 容器，支持 innerHTML/append 等',
+      record: '当前行记录对象（只读）',
+      recordIndex: '当前行索引（从 0 开始）',
+      collection: '集合定义元数据（只读）',
+      viewer: '视图控制器，可用于在单元格中触发抽屉/对话框/内嵌等交互',
+      React: 'React 库',
+      antd: 'Ant Design 库',
+    },
+    methods: {
+      onRefReady: '等待单元格 DOM 就绪后执行回调。参数：(ref, callback, timeout?)',
+      requireAsync: '按 URL 异步加载外部库：`const lib = await ctx.requireAsync(url)`',
+      importAsync: '按 URL 动态导入 ESM 模块：`const mod = await ctx.importAsync(url)`',
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSFieldRunJSContext.ts

@@ -7,37 +7,42 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
-import { createSafeDocument, createSafeWindow } from '../../utils';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSFieldRunJSContext extends FlowRunJSContext {
-  static injectDefaultGlobals() {
-    return { window: createSafeWindow(), document: createSafeDocument() };
-  }
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
-    this.defineProperty('value', { get: () => (this as any)._delegate['value'] });
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('collection', { get: () => (this as any)._delegate['collection'] });
-  }
-}
+export class JSFieldRunJSContext extends FlowRunJSContext {}
 
 JSFieldRunJSContext.define({
   label: 'JSField RunJS context',
   properties: {
-    element: 'ElementProxy，字段渲染容器',
-    value: '字段当前值（只读）',
-    record: '当前记录（只读）',
-    collection: '集合定义（只读）',
+    element: `ElementProxy instance providing a safe DOM container for field rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`,
+    value: `Current value of the field (read-only).
+      Contains the data value stored in this field.`,
+    record: `Current record data object (read-only).
+      Contains all field values of the parent record.`,
+    collection: `Collection definition metadata (read-only).
+      Provides schema information about the collection this field belongs to.`,
   },
   methods: {
-    onRefReady: 'Container ready callback',
-  },
-  snipastes: {
-    'Render value': { $ref: 'scene/jsfield/innerHTML-value', prefix: 'sn-jsf-value' },
-    'Message success': { $ref: 'global/message-success', prefix: 'sn-msg-ok' },
-    'Format number': { $ref: 'scene/jsfield/format-number', prefix: 'sn-jsf-num' },
-    'Color by value': { $ref: 'scene/jsfield/color-by-value', prefix: 'sn-jsf-color' },
+    onRefReady: `Wait for field container DOM element to be ready before executing callback.
+      Parameters: (ref: React.RefObject, callback: (element: HTMLElement) => void, timeout?: number) => void
+      Example: ctx.onRefReady(ctx.ref, (el) => { el.innerHTML = ctx.value })`,
   },
 });
+
+JSFieldRunJSContext.define(
+  {
+    label: 'JS 字段 RunJS 上下文',
+    properties: {
+      element: 'ElementProxy，字段渲染容器，支持 innerHTML/append 等 DOM 操作',
+      value: '字段当前值（只读）',
+      record: '当前记录对象（只读，包含父记录全部字段值）',
+      collection: '集合定义元数据（只读，描述字段所属集合的 Schema）',
+    },
+    methods: {
+      onRefReady:
+        '在字段容器 DOM 就绪后执行回调。参数：(ref, callback, timeout?)；示例：ctx.onRefReady(ctx.ref, el => { el.innerHTML = ctx.value })',
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSItemRunJSContext.ts

@@ -7,33 +7,37 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
-import { createSafeDocument, createSafeWindow } from '../../utils';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSItemRunJSContext extends FlowRunJSContext {
-  static injectDefaultGlobals() {
-    return { window: createSafeWindow(), document: createSafeDocument() };
-  }
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('resource', { get: () => (this as any)._delegate['resource'] });
-  }
-}
+export class JSItemRunJSContext extends FlowRunJSContext {}
 
 JSItemRunJSContext.define({
   label: 'JSItem RunJS context',
   properties: {
-    element: 'ElementProxy，表单项渲染容器',
-    resource: '当前资源（只读）',
-    record: '当前记录（只读）',
+    element: `ElementProxy instance providing a safe DOM container for form item rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`,
+    resource: `Current resource instance (read-only).
+      Provides access to the data resource associated with the current form context.`,
+    record: `Current record data object (read-only).
+      Contains all field values of the parent record.`,
   },
   methods: {
-    onRefReady: 'Container ready callback',
-    requireAsync: 'Load external library',
-  },
-  snipastes: {
-    'Render form item': { $ref: 'scene/jsitem/render-basic', prefix: 'sn-jsitem-basic' },
+    onRefReady: `Wait for form item container DOM element to be ready before executing callback.
+      Parameters: (ref: React.RefObject, callback: (element: HTMLElement) => void, timeout?: number) => void`,
   },
 });
+
+JSItemRunJSContext.define(
+  {
+    label: 'JS 表单项 RunJS 上下文',
+    properties: {
+      element: 'ElementProxy，表单项渲染容器，支持 innerHTML/append 等 DOM 操作',
+      resource: '当前资源（只读）',
+      record: '当前记录（只读）',
+    },
+    methods: {
+      onRefReady: '容器就绪后执行回调。参数：(ref, callback, timeout?)',
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSRecordActionRunJSContext.ts

@@ -7,28 +7,27 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSRecordActionRunJSContext extends FlowRunJSContext {
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('filterByTk', { get: () => (this as any)._delegate['filterByTk'] });
-  }
-}
+export class JSRecordActionRunJSContext extends FlowRunJSContext {}
 
 JSRecordActionRunJSContext.define({
   label: 'JSRecordAction RunJS context',
   properties: {
-    record: '当前记录（只读）',
-    filterByTk: '主键/过滤键（只读）',
-  },
-  methods: {
-    runAction: 'Run action: `await ctx.runAction(name, params)`',
-    message: 'Message API',
-  },
-  snipastes: {
-    'Show record id': { $ref: 'scene/actions/record-id-message', prefix: 'sn-act-record-id' },
-    'Run action': { $ref: 'scene/actions/run-action-basic', prefix: 'sn-act-run' },
+    record: `Current record data object (read-only).
+      Contains all field values of the record associated with this action.`,
+    filterByTk: `Primary key or filter key of the current record (read-only).
+      Used to identify the specific record in database operations.`,
   },
 });
+
+JSRecordActionRunJSContext.define(
+  {
+    label: 'JS 记录动作 RunJS 上下文',
+    properties: {
+      record: '当前记录（只读）',
+      filterByTk: '主键/过滤键（只读）',
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/base.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { FlowRunJSContext } from '../../flowContext';
+
+export function defineBaseContextMeta() {
+  FlowRunJSContext.define({
+    label: 'RunJS base',
+    properties: {
+      logger: 'Pino logger instance for structured logging. Example: `ctx.logger.info({ foo: 1 }, "message")`',
+      message:
+        'Ant Design global message API for displaying temporary messages. Example: `ctx.message.success("Operation completed")`',
+      notification:
+        'Ant Design notification API for displaying notification boxes. Example: `ctx.notification.open({ message: "Title", description: "Content" })`',
+      resource: 'Data resource accessible based on current user permissions',
+      urlSearchParams: 'URLSearchParams object containing query parameters from the current URL',
+      token: 'API authentication token for the current session',
+      role: 'Current user role information',
+      auth: 'Authentication context containing locale, role, user, and token information',
+      api: {
+        description: 'APIClient instance for making HTTP requests.',
+        detail: 'APIClient',
+        properties: {
+          request: {
+            description:
+              'Make an HTTP request using the APIClient instance. Parameters: (options: RequestOptions) => Promise<any>.',
+            detail: 'Promise<any>',
+            completion: {
+              insertText: `await ctx.api.request({ url: '', method: 'get', params: {} })`,
+            },
+          },
+        },
+      },
+      i18n: {
+        description: 'An instance of i18next for managing internationalization.',
+        detail: 'i18next',
+        properties: {
+          language: 'Current active language code.',
+        },
+      },
+      React: 'React namespace providing React library functions and hooks (available in RunJS environment)',
+      ReactDOM: 'ReactDOM client API including createRoot for rendering React components',
+      antd: 'Ant Design component library',
+    },
+    methods: {
+      t: 'Internationalization function for translating text. Parameters: (key: string, variables?: object) => string. Example: `ctx.t("Hello {name}", { name: "World" })`',
+      requireAsync:
+        'Asynchronously load external libraries from URL. Parameters: (url: string) => Promise<any>. Example: `const lodash = await ctx.requireAsync("https://cdn.jsdelivr.net/npm/lodash")`',
+      importAsync:
+        'Dynamically import ESM module by URL. Parameters: (url: string) => Promise<Module>. Example: `const mod = await ctx.importAsync("https://cdn.jsdelivr.net/npm/lit-html@2/+esm")`',
+      resolveJsonTemplate:
+        'Resolve JSON templates containing variable expressions with {{ }} syntax. Parameters: (template: any, context?: object) => any',
+      runAction: {
+        description:
+          'Execute a data action on the current resource. Parameters: (actionName: string, params: object) => Promise<any>. Example: `await ctx.runAction("create", { values: { name: "test" } })`',
+        detail: 'Promise<any>',
+        completion: {
+          insertText: `await ctx.runAction('create', { values: {} })`,
+        },
+      },
+      openView: {
+        description: `Open a view component (page, modal, or drawer) by its unique identifier.
+      Parameters: (viewId: string, options?: OpenViewOptions) => Promise<void>
+      Options:
+        - params: Record<string, any> - Parameters passed to the view component
+        - mode: "page" | "modal" | "drawer" - Display mode (default: "drawer")
+        - title: string - Modal/drawer title
+        - width: number | string - Modal/drawer width
+        - navigation: boolean - Whether to use route navigation
+        - preventClose: boolean - Prevent closing the view
+        - viewUid: string - Custom view UID for routing
+        - isMobileLayout: boolean - Use mobile layout (displays as embed)
+      Examples:
+       - Modal with params: await ctx.openView("user-detail", { params: { id: 123 }, mode: "modal", title: "User Details", width: 800 })
+       - Drawer (default): await ctx.openView("settings-page")
+        - Page navigation: await ctx.openView("dashboard", { mode: "page" })`,
+        detail: 'Promise<void>',
+        completion: {
+          insertText: `await ctx.openView('view-id', { mode: 'drawer', params: {} })`,
+        },
+      },
+    },
+  });
+
+  FlowRunJSContext.define(
+    {
+      label: 'RunJS 基础',
+      properties: {
+        logger: 'Pino 日志实例（结构化日志）。示例：`ctx.logger.info({ foo: 1 }, "message")`',
+        message: 'Ant Design 全局消息 API，用于显示临时提示。示例：`ctx.message.success("操作成功")`',
+        notification:
+          'Ant Design 通知 API，用于显示通知框。示例：`ctx.notification.open({ message: "标题", description: "内容" })`',
+        resource: '基于当前用户权限可访问的数据资源',
+        urlSearchParams: '当前 URL 的查询参数（URLSearchParams 对象）',
+        token: '当前会话的 API 认证 token',
+        role: '当前用户角色信息',
+        auth: '认证上下文，包含 locale、role、user、token 等信息',
+        api: {
+          description: '用于发起 HTTP 请求的 APIClient 实例',
+          detail: 'APIClient',
+          properties: {
+            request: {
+              description: '通过 ctx.api.request 发起 HTTP 请求，入参为 RequestOptions，返回 Promise。',
+              detail: 'Promise<any>',
+              completion: {
+                insertText: `await ctx.api.request({ url: '', method: 'get', params: {} })`,
+              },
+            },
+          },
+        },
+        i18n: {
+          description: 'i18next 实例，可用于管理国际化',
+          detail: 'i18next',
+          properties: {
+            language: '当前激活的语言代码',
+          },
+        },
+        React: 'React 命名空间，提供 React 函数与 hooks（RunJS 环境中可用）',
+        ReactDOM: 'ReactDOM 客户端 API，含 createRoot 等渲染方法',
+        antd: 'Ant Design 组件库（RunJS 环境中可用）',
+      },
+      methods: {
+        t: '国际化函数，用于翻译文案。参数：(key: string, variables?: object) => string。示例：`ctx.t("你好 {name}", { name: "世界" })`',
+        requireAsync:
+          '按 URL 异步加载外部库。参数：(url: string) => Promise<any>。示例：`const lodash = await ctx.requireAsync("https://cdn.jsdelivr.net/npm/lodash")`',
+        importAsync:
+          '按 URL 动态导入 ESM 模块（开发/生产均可用）。参数：(url: string) => Promise<Module>。示例：`const mod = await ctx.importAsync("https://cdn.jsdelivr.net/npm/lit-html@2/+esm")`',
+        resolveJsonTemplate: '解析含 {{ }} 变量表达式的 JSON 模板。参数：(template: any, context?: object) => any',
+        runAction: {
+          description:
+            '对当前资源执行数据动作。参数：(actionName: string, params: object) => Promise<any>。示例：`await ctx.runAction("create", { values: { name: "test" } })`',
+          detail: 'Promise<any>',
+          completion: {
+            insertText: `await ctx.runAction('create', { values: {} })`,
+          },
+        },
+        openView: {
+          description:
+            '根据唯一标识打开视图（页面/弹窗/抽屉）。参数：(viewId: string, options?: OpenViewOptions) => Promise<void>`，常用选项：params、mode、title、width、navigation、preventClose、viewUid、isMobileLayout。',
+          detail: 'Promise<void>',
+          completion: {
+            insertText: `await ctx.openView('view-id', { mode: 'drawer', params: {} })`,
+          },
+        },
+      },
+    },
+    { locale: 'zh-CN' },
+  );
+}

package/src/runjs-context/helpers.ts

@@ -10,47 +10,49 @@
 import type { FlowContext } from '../flowContext';
 import { JSRunner } from '../JSRunner';
 import type { JSRunnerOptions } from '../JSRunner';
-import { FlowRunJSContext, RunJSVersion } from './contexts/FlowRunJSContext';
-import { RunJSContextRegistry, getModelClassName } from './registry';
-import { JSBlockRunJSContext } from './contexts/JSBlockRunJSContext';
-import { JSFieldRunJSContext } from './contexts/JSFieldRunJSContext';
-import { JSItemRunJSContext } from './contexts/JSItemRunJSContext';
-import { FormJSFieldItemRunJSContext } from './contexts/FormJSFieldItemRunJSContext';
-import { JSRecordActionRunJSContext } from './contexts/JSRecordActionRunJSContext';
-import { JSCollectionActionRunJSContext } from './contexts/JSCollectionActionRunJSContext';
-import { LinkageRunJSContext } from './contexts/LinkageRunJSContext';
+import { RunJSContextRegistry, getModelClassName, type RunJSVersion } from './registry';
+
+function getLocale(ctx: any): string | undefined {
+  return ctx?.api?.auth?.locale || ctx?.i18n?.language || ctx?.locale;
+}
 
 export function getRunJSDocFor(ctx: FlowContext, { version = 'v1' as RunJSVersion } = {}) {
   const modelClass = getModelClassName(ctx);
-  const ctor =
-    RunJSContextRegistry.resolve(version, modelClass) ||
-    RunJSContextRegistry.resolve('latest' as RunJSVersion, modelClass) ||
-    FlowRunJSContext;
-  return (ctor as any).getDoc?.() || {};
+  const ctor = RunJSContextRegistry.resolve(version, modelClass) || RunJSContextRegistry.resolve(version, '*');
+  const locale = getLocale(ctx);
+  if ((ctor as any)?.getDoc?.length) {
+    // prefer getDoc(locale)
+    return (ctor as any).getDoc(locale) || {};
+  }
+  return (ctor as any)?.getDoc?.() || {};
 }
 
 export function createJSRunnerWithVersion(this: FlowContext, options?: JSRunnerOptions) {
   const version = (options?.version as RunJSVersion) || ('v1' as RunJSVersion);
   const modelClass = getModelClassName(this);
-  const Ctor =
-    RunJSContextRegistry.resolve(version, modelClass) ||
-    RunJSContextRegistry.resolve('latest' as RunJSVersion, modelClass) ||
-    FlowRunJSContext;
-  const runCtx = new Ctor((this as any).createProxy ? (this as any).createProxy() : (this as any));
-  const def = (Ctor as any).injectDefaultGlobals?.() || {};
-  const globals = { ctx: runCtx, ...def, ...(options?.globals || {}) };
+  const ensureFlowContext = (obj: any): FlowContext => obj as FlowContext;
+  const Ctor = RunJSContextRegistry.resolve(version, modelClass) || RunJSContextRegistry.resolve(version, '*');
+  if (!Ctor) {
+    throw new Error('[RunJS] No RunJSContext registered for version/model.');
+  }
+  const runCtx = new (Ctor as any)(ensureFlowContext(this));
+  const globals: Record<string, any> = { ctx: runCtx, ...(options?.globals || {}) };
+  // 对字段/区块类上下文，默认注入 window/document 以支持在沙箱中访问 DOM API
+  if (modelClass === 'JSFieldModel' || modelClass === 'JSBlockModel') {
+    if (typeof window !== 'undefined') globals.window = window as any;
+    if (typeof document !== 'undefined') globals.document = document as any;
+  }
   // 透传 JSRunnerOptions 其余配置（如 timeoutMs）
   const { timeoutMs } = options || {};
   return new JSRunner({ globals, timeoutMs });
 }
 
-export function registerDefaultMappings() {
-  const v: RunJSVersion = 'v1';
-  RunJSContextRegistry.register(v, 'JSBlockModel', JSBlockRunJSContext);
-  RunJSContextRegistry.register(v, 'JSFieldModel', JSFieldRunJSContext);
-  RunJSContextRegistry.register(v, 'JSItemModel', JSItemRunJSContext);
-  RunJSContextRegistry.register(v, 'FormJSFieldItemModel', FormJSFieldItemRunJSContext);
-  RunJSContextRegistry.register(v, 'JSRecordActionModel', JSRecordActionRunJSContext);
-  RunJSContextRegistry.register(v, 'JSCollectionActionModel', JSCollectionActionRunJSContext);
-  RunJSContextRegistry.register(v, '*', FlowRunJSContext);
+export function getRunJSScenesForModel(modelClass: string, version: RunJSVersion = 'v1'): string[] {
+  const meta = RunJSContextRegistry.getMeta(version, modelClass);
+  return Array.isArray(meta?.scenes) ? [...meta!.scenes!] : [];
+}
+
+export function getRunJSScenesForContext(ctx: FlowContext, { version = 'v1' as RunJSVersion } = {}): string[] {
+  const modelClass = getModelClassName(ctx);
+  return getRunJSScenesForModel(modelClass, version);
 }