@nocobase/plugin-flow-engine 2.1.0-beta.15 → 2.1.0-beta.17

package/dist/ai/docs/runjs/context/collection.md

@@ -1,18 +1,18 @@
 # ctx.collection
 
-The collection (data table) instance associated with the current RunJS execution context; used to access collection metadata, field definitions, primary key, etc. Usually from `ctx.blockModel.collection` or `ctx.collectionField?.collection`.
+The Collection instance associated with the current RunJS execution context, used to access collection metadata, field definitions, primary keys, and other configurations. It usually originates from `ctx.blockModel.collection` or `ctx.collectionField?.collection`.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock** | Block-bound collection; access `name`, `getFields`, `filterTargetKey`, etc. |
-| **JSField / JSItem / JSColumn** | Collection of current field or parent block; get field list, primary key, etc. |
-| **Table column / detail block** | Render by collection structure, pass `filterByTk` when opening popup, etc. |
+|------|------|
+| **JSBlock** | The collection bound to the block; can access `name`, `getFields`, `filterTargetKey`, etc. |
+| **JSField / JSItem / JSColumn** | The collection the current field belongs to (or the parent block's collection), used to retrieve field lists, primary keys, etc. |
+| **Table Column / Detail Block** | Used for rendering based on collection structure or passing `filterByTk` when opening popups. |
 
-> Note: `ctx.collection` is available when the context is bound to a data block, form block, or table block; a standalone JSBlock with no bound collection may have `null`—check before use.
+> Note: `ctx.collection` is available in scenarios where a data block, form block, or table block is bound to a collection. In an independent JSBlock that is not bound to a collection, it may be `null`. It is recommended to perform a null check before use.
 
-## Type
+## Type Definition
 
 ```ts
 collection: Collection | null | undefined;
@@ -21,39 +21,39 @@ collection: Collection | null | undefined;
 ## Common Properties
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | Collection name (e.g. `users`, `orders`) |
-| `title` | `string` | Collection title (i18n) |
-| `filterTargetKey` | `string \| string[]` | Primary key field name(s); used for `filterByTk`, `getFilterByTK` |
-| `dataSourceKey` | `string` | Data source key (e.g. `main`) |
-| `dataSource` | `DataSource` | Data source instance |
-| `template` | `string` | Collection template (e.g. `general`, `file`, `tree`) |
-| `titleableFields` | `CollectionField[]` | Fields that can be used as title |
-| `titleCollectionField` | `CollectionField` | Title field instance |
+|------|------|------|
+| `name` | `string` | Collection name (e.g., `users`, `orders`) |
+| `title` | `string` | Collection title (includes internationalization) |
+| `filterTargetKey` | `string \| string[]` | Primary key field name, used for `filterByTk` and `getFilterByTK` |
+| `dataSourceKey` | `string` | Data source key (e.g., `main`) |
+| `dataSource` | `DataSource` | The data source instance it belongs to |
+| `template` | `string` | Collection template (e.g., `general`, `file`, `tree`) |
+| `titleableFields` | `CollectionField[]` | List of fields that can be displayed as titles |
+| `titleCollectionField` | `CollectionField` | The title field instance |
 
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `getFields(): CollectionField[]` | All fields (including inherited) |
-| `getField(name: string): CollectionField \| undefined` | Single field by name |
-| `getFieldByPath(path: string): CollectionField \| undefined` | Field by path (supports association, e.g. `user.name`) |
-| `getAssociationFields(types?): CollectionField[]` | Association fields; `types` e.g. `['one']`, `['many']` |
-| `getFilterByTK(record): any` | Primary key value from record for API `filterByTk` |
+|------|------|
+| `getFields(): CollectionField[]` | Get all fields (including inherited ones) |
+| `getField(name: string): CollectionField \| undefined` | Get a single field by field name |
+| `getFieldByPath(path: string): CollectionField \| undefined` | Get a field by path (supports associations, e.g., `user.name`) |
+| `getAssociationFields(types?): CollectionField[]` | Get association fields; `types` can be `['one']`, `['many']`, etc. |
+| `getFilterByTK(record): any` | Extract the primary key value from a record, used for the API's `filterByTk` |
 
-## Relation to ctx.collectionField, ctx.blockModel
+## Relationship with ctx.collectionField and ctx.blockModel
 
-| Need | Recommended |
-|------|-------------|
-| **Collection for current context** | `ctx.collection` (same as `ctx.blockModel?.collection` or `ctx.collectionField?.collection`) |
-| **Collection of current field** | `ctx.collectionField?.collection` |
-| **Target collection of association** | `ctx.collectionField?.targetCollection` |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Collection associated with current context** | `ctx.collection` (equivalent to `ctx.blockModel?.collection` or `ctx.collectionField?.collection`) |
+| **Collection definition of the current field** | `ctx.collectionField?.collection` (the collection the field belongs to) |
+| **Association target collection** | `ctx.collectionField?.targetCollection` (the target collection of an association field) |
 
-In sub-tables etc., `ctx.collection` may be the association target; in normal form/table it is usually the block’s collection.
+In scenarios like sub-tables, `ctx.collection` might be the association target collection; in standard forms/tables, it is usually the collection bound to the block.
 
 ## Examples
 
-### Get primary key and open popup
+### Get Primary Key and Open Popup
 
 ```ts
 const primaryKey = ctx.collection?.filterTargetKey ?? 'id';
@@ -66,7 +66,7 @@ await ctx.openView(popupUid, {
 });
 ```
 
-### Iterate fields for validation or linkage
+### Iterate Through Fields for Validation or Linkage
 
 ```ts
 const fields = ctx.collection?.getFields() ?? [];
@@ -80,21 +80,21 @@ for (const f of requiredFields) {
 }
 ```
 
-### Get association fields
+### Get Association Fields
 
 ```ts
 const oneToMany = ctx.collection?.getAssociationFields(['many']) ?? [];
-// For sub-tables, association resources, etc.
+// Used for building sub-tables, associated resources, etc.
 ```
 
 ## Notes
 
-- `filterTargetKey` is the collection’s primary key field name; some collections use `string[]` composite keys; fallback is often `'id'`.
-- In **sub-tables, association fields**, `ctx.collection` may point to the association target, different from `ctx.blockModel.collection`.
-- `getFields()` merges inherited collection fields; local fields override inherited ones with the same name.
+- `filterTargetKey` is the primary key field name of the collection. Some collections may use a `string[]` for composite primary keys. If not configured, `'id'` is commonly used as a fallback.
+- In scenarios like **sub-tables or association fields**, `ctx.collection` may point to the association target collection, which differs from `ctx.blockModel.collection`.
+- `getFields()` merges fields from inherited collections; local fields override inherited fields with the same name.
 
 ## Related
 
-- [ctx.collectionField](./collection-field.md): current field’s collection field definition
-- [ctx.blockModel](./block-model.md): parent block that hosts current JS; has `collection`
-- [ctx.model](./model.md): current model; may have `collection`
+- [ctx.collectionField](./collection-field.md): The collection field definition of the current field
+- [ctx.blockModel](./block-model.md): The parent block hosting the current JS, containing `collection`
+- [ctx.model](./model.md): The current model, which may contain `collection`

package/dist/ai/docs/runjs/context/data-source-manager.md

@@ -1,18 +1,18 @@
 # ctx.dataSourceManager
 
-The data source manager (`DataSourceManager` instance) for managing and accessing multiple data sources (e.g. main `main`, logging `logging`). Use when you have multiple data sources or need cross–data-source metadata access.
+The Data Source Manager (`DataSourceManager` instance) is used to manage and access multiple data sources (e.g., the main database `main`, logging database `logging`, etc.). It is used when multiple data sources exist or when cross-data source metadata access is required.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Multiple data sources** | Enumerate all data sources, get one by key |
-| **Cross–data-source access** | When context doesn’t know the data source, access by “data source key + collection name” |
-| **Field by full path** | Get field definition with path format `dataSourceKey.collectionName.fieldPath` |
+|------|------|
+| **Multi-data source** | Enumerate all data sources, or get a specific data source by key. |
+| **Cross-data source access** | Access metadata using the "data source key + collection name" format when the data source of the current context is unknown. |
+| **Get fields by full path** | Use the `dataSourceKey.collectionName.fieldPath` format to retrieve field definitions across different data sources. |
 
-> Note: If you only work with the current data source, use `ctx.dataSource`; use `ctx.dataSourceManager` when you need to enumerate or switch data sources.
+> Note: If you are only operating on the current data source, prioritize using `ctx.dataSource`. Use `ctx.dataSourceManager` only when you need to enumerate or switch between data sources.
 
-## Type
+## Type Definition
 
 ```ts
 dataSourceManager: DataSourceManager;
@@ -20,64 +20,74 @@ dataSourceManager: DataSourceManager;
 class DataSourceManager {
   constructor();
 
+  // Data source management
   addDataSource(ds: DataSource | DataSourceOptions): void;
   upsertDataSource(ds: DataSource | DataSourceOptions): void;
   removeDataSource(key: string): void;
   clearDataSources(): void;
 
-  getDataSources(): DataSource[];
-  getDataSource(key: string): DataSource | undefined;
+  // Read data sources
+  getDataSources(): DataSource[];                     // Get all data sources
+  getDataSource(key: string): DataSource | undefined;  // Get data source by key
 
+  // Access metadata directly by data source + collection
   getCollection(dataSourceKey: string, collectionName: string): Collection | undefined;
   getCollectionField(fieldPathWithDataSource: string): CollectionField | undefined;
 }
 ```
 
-## Relation to ctx.dataSource
+## Relationship with ctx.dataSource
 
-| Need | Recommended |
-|------|-------------|
-| **Single data source for context** | `ctx.dataSource` |
-| **Entry to all data sources** | `ctx.dataSourceManager` |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to the current context** | `ctx.dataSource` (e.g., the data source of the current page/block) |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
 | **List or switch data sources** | `ctx.dataSourceManager.getDataSources()` / `getDataSource(key)` |
-| **Collection in current data source** | `ctx.dataSource.getCollection(name)` |
-| **Collection in another data source** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
-| **Field in current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
-| **Field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+| **Get collection within the current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within the current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
 
 ## Examples
 
-### Get a data source
+### Get a Specific Data Source
 
 ```ts
+// Get the data source named 'main'
 const mainDS = ctx.dataSourceManager.getDataSource('main');
+
+// Get all collections under this data source
 const collections = mainDS?.getCollections();
 ```
 
-### Cross–data-source collection metadata
+### Access Collection Metadata Across Data Sources
 
 ```ts
+// Get collection by dataSourceKey + collectionName
 const users = ctx.dataSourceManager.getCollection('main', 'users');
 const orders = ctx.dataSourceManager.getCollection('main', 'orders');
 
+// Get the primary key of the collection
 const primaryKey = users?.filterTargetKey ?? 'id';
 ```
 
-### Field by full path
+### Get Field Definition by Full Path
 
 ```ts
 // Format: dataSourceKey.collectionName.fieldPath
+// Get field definition by "data source key.collection name.field path"
 const field = ctx.dataSourceManager.getCollectionField('main.users.profile.avatar');
 
+// Supports association field paths
 const userNameField = ctx.dataSourceManager.getCollectionField('main.orders.createdBy.name');
 ```
 
-### Iterate all data sources
+### Iterate Through All Data Sources
 
 ```ts
 const dataSources = ctx.dataSourceManager.getDataSources();
 for (const ds of dataSources) {
-  ctx.logger.info(`Data source: ${ds.key}, display: ${ds.displayName}`);
+  ctx.logger.info(`Data Source: ${ds.key}, Display Name: ${ds.displayName}`);
   const collections = ds.getCollections();
   for (const col of collections) {
     ctx.logger.info(`  - Collection: ${col.name}`);
@@ -85,7 +95,7 @@ for (const ds of dataSources) {
 }
 ```
 
-### Dynamic data source from variable
+### Dynamically Select Data Source Based on Variables
 
 ```ts
 const dsKey = ctx.getVar('dataSourceKey') ?? 'main';
@@ -99,12 +109,12 @@ if (col) {
 
 ## Notes
 
-- `getCollectionField` path format is `dataSourceKey.collectionName.fieldPath`; first segment is data source key, then collection name and field path.
-- `getDataSource(key)` returns `undefined` if the data source doesn’t exist—check before use.
-- `addDataSource` throws if key already exists; `upsertDataSource` overwrites or adds.
+- The path format for `getCollectionField` is `dataSourceKey.collectionName.fieldPath`, where the first segment is the data source key, followed by the collection name and the field path.
+- `getDataSource(key)` returns `undefined` if the data source does not exist; it is recommended to perform a null check before use.
+- `addDataSource` will throw an exception if the key already exists; `upsertDataSource` will either overwrite the existing one or add a new one.
 
 ## Related
 
-- [ctx.dataSource](./data-source.md): current data source instance
-- [ctx.collection](./collection.md): collection for current context
-- [ctx.collectionField](./collection-field.md): current field’s collection field definition
+- [ctx.dataSource](./data-source.md): Current data source instance
+- [ctx.collection](./collection.md): Collection associated with the current context
+- [ctx.collectionField](./collection-field.md): Collection field definition for the current field

package/dist/ai/docs/runjs/context/data-source.md

@@ -1,18 +1,18 @@
 # ctx.dataSource
 
-The data source instance (`DataSource`) bound to the current RunJS context; used to access collections, field metadata, and collection config **within that data source**. Usually the current page/block’s data source (e.g. main `main`).
+The `DataSource` instance bound to the current RunJS execution context, used to access collections, field metadata, and manage collection configurations **within the current data source**. It usually corresponds to the data source selected for the current page or block (e.g., the main database `main`).
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Single data source** | Get collections, field metadata when the current data source is known |
-| **Collection management** | Get/add/update/remove collections in the current data source |
-| **Field by path** | Get field definition by `collectionName.fieldPath` (supports association path) |
+|------|------|
+| **Single Data Source Operations** | Get collection and field metadata when the current data source is known. |
+| **Collection Management** | Get, add, update, or delete collections under the current data source. |
+| **Get Fields by Path** | Use the `collectionName.fieldPath` format to get field definitions (supports association paths). |
 
-> Note: `ctx.dataSource` is the single data source for the current context; to enumerate or access other data sources use [ctx.dataSourceManager](./data-source-manager.md).
+> Note: `ctx.dataSource` represents a single data source for the current context. To enumerate or access other data sources, please use [ctx.dataSourceManager](./data-source-manager.md).
 
-## Type
+## Type Definition
 
 ```ts
 dataSource: DataSource;
@@ -20,15 +20,18 @@ dataSource: DataSource;
 class DataSource {
   constructor(options?: Record<string, any>);
 
-  get flowEngine(): FlowEngine;
-  get displayName(): string;
-  get key(): string;
-  get name(): string;
+  // Read-only properties
+  get flowEngine(): FlowEngine;   // Current FlowEngine instance
+  get displayName(): string;      // Display name (supports i18n)
+  get key(): string;              // Data source key, e.g., 'main'
+  get name(): string;             // Same as key
 
-  getCollections(): Collection[];
-  getCollection(name: string): Collection | undefined;
-  getAssociation(associationName: string): CollectionField | undefined;
+  // Collection reading
+  getCollections(): Collection[];                      // Get all collections
+  getCollection(name: string): Collection | undefined; // Get collection by name
+  getAssociation(associationName: string): CollectionField | undefined; // Get association field (e.g., users.roles)
 
+  // Collection management
   addCollection(collection: Collection | CollectionOptions): void;
   updateCollection(newOptions: CollectionOptions): void;
   upsertCollection(options: CollectionOptions): Collection | undefined;
@@ -36,6 +39,7 @@ class DataSource {
   removeCollection(name: string): void;
   clearCollections(): void;
 
+  // Field metadata
   getCollectionField(fieldPath: string): CollectionField | undefined;
 }
 ```
@@ -43,57 +47,61 @@ class DataSource {
 ## Common Properties
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `key` | `string` | Data source key (e.g. `main`) |
+|------|------|------|
+| `key` | `string` | Data source key, e.g., `'main'` |
 | `name` | `string` | Same as key |
-| `displayName` | `string` | Display name (i18n) |
+| `displayName` | `string` | Display name (supports i18n) |
 | `flowEngine` | `FlowEngine` | Current FlowEngine instance |
 
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `getCollections()` | All collections in this data source (sorted, hidden filtered) |
-| `getCollection(name)` | Collection by name; `name` can be `collectionName.fieldName` for association target |
-| `getAssociation(associationName)` | Association field by `collectionName.fieldName` |
-| `getCollectionField(fieldPath)` | Field by `collectionName.fieldPath`; supports paths like `users.profile.avatar` |
+|------|------|
+| `getCollections()` | Gets all collections under the current data source (sorted, with hidden ones filtered). |
+| `getCollection(name)` | Gets a collection by name; `name` can be `collectionName.fieldName` to get the target collection of an association. |
+| `getAssociation(associationName)` | Gets an association field definition by `collectionName.fieldName`. |
+| `getCollectionField(fieldPath)` | Gets a field definition by `collectionName.fieldPath`, supporting association paths like `users.profile.avatar`. |
 
-## Relation to ctx.dataSourceManager
+## Relationship with ctx.dataSourceManager
 
-| Need | Recommended |
-|------|-------------|
-| **Single data source for context** | `ctx.dataSource` |
-| **Entry to all data sources** | `ctx.dataSourceManager` |
-| **Collection in current data source** | `ctx.dataSource.getCollection(name)` |
-| **Collection in another data source** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
-| **Field in current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
-| **Field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to current context** | `ctx.dataSource` |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
+| **Get collection within current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
 
-## Examples
+## Example
 
-### Get collections and fields
+### Get Collections and Fields
 
 ```ts
+// Get all collections
 const collections = ctx.dataSource.getCollections();
 
+// Get collection by name
 const users = ctx.dataSource.getCollection('users');
 const primaryKey = users?.filterTargetKey ?? 'id';
 
+// Get field definition by "collectionName.fieldPath" (supports associations)
 const field = ctx.dataSource.getCollectionField('users.profile.avatar');
 const userNameField = ctx.dataSource.getCollectionField('orders.createdBy.name');
 ```
 
-### Get association field
+### Get Association Fields
 
 ```ts
+// Get association field definition by collectionName.fieldName
 const rolesField = ctx.dataSource.getAssociation('users.roles');
 if (rolesField?.isAssociationField()) {
   const targetCol = rolesField.targetCollection;
-  // ...
+  // Process based on target collection structure
 }
 ```
 
-### Iterate collections
+### Iterate Through Collections for Dynamic Processing
 
 ```ts
 const collections = ctx.dataSource.getCollections();
@@ -104,25 +112,25 @@ for (const col of collections) {
 }
 ```
 
-### Validation or dynamic UI from field metadata
+### Perform Validation or Dynamic UI Based on Field Metadata
 
 ```ts
 const field = ctx.dataSource.getCollectionField('users.status');
 if (field) {
   const options = field.enum ?? [];
   const operators = field.getFilterOperators();
-  // ...
+  // Perform UI logic or validation based on interface, enum, validation, etc.
 }
 ```
 
 ## Notes
 
-- `getCollectionField(fieldPath)` uses path format `collectionName.fieldPath`; first segment is collection name, rest is field path (supports association, e.g. `user.name`).
-- `getCollection(name)` supports `collectionName.fieldName` and returns the association target collection.
-- In RunJS, `ctx.dataSource` is usually determined by the current block/page; if there is no bound data source it may be `undefined`—check before use.
+- The path format for `getCollectionField(fieldPath)` is `collectionName.fieldPath`, where the first segment is the collection name and the subsequent segments are the field path (supports associations, e.g., `user.name`).
+- `getCollection(name)` supports the `collectionName.fieldName` format, returning the target collection of the association field.
+- In the RunJS context, `ctx.dataSource` is usually determined by the data source of the current block or page. If no data source is bound to the context, it may be `undefined`; it is recommended to perform a null check before use.
 
 ## Related
 
-- [ctx.dataSourceManager](./data-source-manager.md): manager for all data sources
-- [ctx.collection](./collection.md): collection for current context
-- [ctx.collectionField](./collection-field.md): current field’s collection field definition
+- [ctx.dataSourceManager](./data-source-manager.md): Data source manager, manages all data sources.
+- [ctx.collection](./collection.md): The collection associated with the current context.
+- [ctx.collectionField](./collection-field.md): The collection field definition for the current field.

package/dist/ai/docs/runjs/context/element.md

@@ -1,57 +1,60 @@
 # ctx.element
 
-The ElementProxy instance for the sandbox DOM container; it is the default render target of `ctx.render()`. Available in JSBlock, JSField, JSItem, JSColumn, and other contexts that have a render container.
+An `ElementProxy` instance pointing to the sandbox DOM container, serving as the default rendering target for `ctx.render()`. It is available in scenarios where a rendering container exists, such as `JSBlock`, `JSField`, `JSItem`, and `JSColumn`.
 
-## Use Cases
+## Applicable Scenarios
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock** | Block’s DOM container for custom content |
-| **JSField / JSItem / FormJSFieldItem** | Field/item render container (often a `<span>`) |
-| **JSColumn** | Table cell DOM container for custom column content |
+|------|------|
+| **JSBlock** | The DOM container for the block, used to render custom block content. |
+| **JSField / JSItem / FormJSFieldItem** | The rendering container for a field or form item (usually a `<span>`). |
+| **JSColumn** | The DOM container for a table cell, used to render custom column content. |
 
-> Note: `ctx.element` is only available in RunJS contexts that have a render container; in contexts without UI (e.g. pure backend) it may be `undefined`—check before use.
+> Note: `ctx.element` is only available in RunJS contexts that have a rendering container. In contexts without a UI (such as pure backend logic), it may be `undefined`. It is recommended to perform a null check before use.
 
-## Type
+## Type Definition
 
 ```typescript
 element: ElementProxy | undefined;
 
+// ElementProxy is a proxy for the raw HTMLElement, exposing a secure API
 class ElementProxy {
-  __el: HTMLElement;  // Internal native DOM (only for specific cases)
-  innerHTML: string;  // Read/write sanitized with DOMPurify
-  outerHTML: string;
+  __el: HTMLElement;  // The internal raw DOM element (accessible only in specific scenarios)
+  innerHTML: string;  // Sanitized via DOMPurify during read/write
+  outerHTML: string; // Same as above
   appendChild(child: HTMLElement | string): void;
-  // Other HTMLElement methods passed through (not recommended)
+  // Other HTMLElement methods are passed through (direct use is not recommended)
 }
 ```
 
-## Security
+## Security Requirements
 
-**Recommended: do all rendering via `ctx.render()`.** Do not use `ctx.element`’s DOM APIs directly (e.g. `innerHTML`, `appendChild`, `querySelector`).
+**Recommended: All rendering should be performed via `ctx.render()`.** Avoid using the DOM APIs of `ctx.element` directly (e.g., `innerHTML`, `appendChild`, `querySelector`, etc.).
 
-### Why use ctx.render()
+### Why ctx.render() is Recommended
 
-| Benefit | Description |
-|---------|-------------|
-| **Security** | Centralized control, avoids XSS and unsafe DOM use |
-| **React** | Full JSX, components, and lifecycle |
-| **Context** | Inherits app ConfigProvider, theme, etc. |
-| **Conflicts** | Manages React root create/unmount, avoids multiple instances |
+| Advantage | Description |
+|------|------|
+| **Security** | Centralized security control to prevent XSS and improper DOM operations. |
+| **React Support** | Full support for JSX, React components, and lifecycles. |
+| **Context Inheritance** | Automatically inherits the application's `ConfigProvider`, themes, etc. |
+| **Conflict Handling** | Automatically manages React root creation/unmounting to avoid multi-instance conflicts. |
 
-### ❌ Not recommended: direct ctx.element use
+### ❌ Not Recommended: Direct Manipulation of ctx.element
 
 ```ts
+// ❌ Not recommended: Using ctx.element APIs directly
 ctx.element.innerHTML = '<div>Content</div>';
 ctx.element.appendChild(node);
 ctx.element.querySelector('.class');
 ```
 
-> `ctx.element.innerHTML` is deprecated; use `ctx.render()` instead.
+> `ctx.element.innerHTML` is deprecated. Please use `ctx.render()` instead.
 
-### ✅ Recommended: ctx.render()
+### ✅ Recommended: Using ctx.render()
 
 ```ts
+// ✅ Rendering a React component
 const { Button, Card } = ctx.libs.antd;
 ctx.render(
   <Card title={ctx.t('Welcome')}>
@@ -59,40 +62,43 @@ ctx.render(
   </Card>
 );
 
+// ✅ Rendering an HTML string
 ctx.render('<div style="padding:16px;">' + ctx.t('Content') + '</div>');
 
+// ✅ Rendering a DOM node
 const div = document.createElement('div');
 div.textContent = ctx.t('Hello');
 ctx.render(div);
 ```
 
-## Exception: popover anchor
+## Special Case: As a Popover Anchor
 
-When you need the current element as a popover anchor, use `ctx.element?.__el` as the native DOM `target`:
+When you need to open a Popover using the current element as an anchor, you can access `ctx.element?.__el` to get the raw DOM as the `target`:
 
 ```ts
+// ctx.viewer.popover requires a raw DOM as the target
 await ctx.viewer.popover({
   target: ctx.element?.__el,
-  content: <div>Popover content</div>,
+  content: <div>Popup Content</div>,
 });
 ```
 
-> Use `__el` only for this “current container as anchor” case; do not touch DOM otherwise.
+> Use `__el` only in scenarios like "using the current container as an anchor"; do not manipulate the DOM directly in other cases.
 
-## Relation to ctx.render
+## Relationship with ctx.render
 
-- `ctx.render(vnode)` without a `container` argument renders into `ctx.element`.
-- If there is no `ctx.element` and no `container`, an error is thrown.
-- You can pass a container: `ctx.render(vnode, customContainer)`.
+- If `ctx.render(vnode)` is called without a `container` argument, it renders into the `ctx.element` container by default.
+- If both `ctx.element` is missing and no `container` is provided, an error will be thrown.
+- You can explicitly specify a container: `ctx.render(vnode, customContainer)`.
 
 ## Notes
 
-- Treat `ctx.element` as the internal container for `ctx.render()`; avoid reading or mutating it directly.
-- In contexts without a render container, `ctx.element` is `undefined`; ensure a container exists or pass `container` to `ctx.render()`.
-- ElementProxy’s `innerHTML`/`outerHTML` are sanitized with DOMPurify, but prefer `ctx.render()` for all rendering.
+- `ctx.element` is intended for internal use by `ctx.render()`. Directly accessing or modifying its properties/methods is not recommended.
+- In contexts without a rendering container, `ctx.element` will be `undefined`. Ensure the container is available or pass a `container` manually before calling `ctx.render()`.
+- Although `innerHTML`/`outerHTML` in `ElementProxy` are sanitized via DOMPurify, it is still recommended to use `ctx.render()` for unified rendering management.
 
 ## Related
 
-- [ctx.render](./render.md): render into container
-- [ctx.view](./view.md): current view controller
-- [ctx.modal](./modal.md): modal APIs
+- [ctx.render](./render.md): Rendering content into a container
+- [ctx.view](./view.md): Current view controller
+- [ctx.modal](./modal.md): Shortcut API for modals