@nocobase/plugin-flow-engine 2.1.0-alpha.3 → 2.1.0-alpha.30

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

@@ -1,86 +1,89 @@
 # ctx.exit()
 
-Stops the current event flow; later steps in that flow do not run. Often used when business conditions fail, the user cancels, or an unrecoverable error occurs.
+Terminates the execution of the current event flow; subsequent steps will not run. It is commonly used when business conditions are not met, the user cancels, or an irrecoverable error occurs.
 
 ## Use Cases
 
-`ctx.exit()` is used in contexts that execute JS, such as:
+`ctx.exit()` is generally used in the following contexts where JS can be executed:
 
 | Scenario | Description |
-|----------|-------------|
-| **Event flow** | In flows triggered by form submit, button click, etc., stop when conditions are not met |
-| **Linkage rules** | Field or filter linkage; stop when validation fails or execution should be skipped |
-| **Action events** | In custom actions (e.g. delete confirm, pre-save validation), exit when user cancels or validation fails |
+|------|------|
+| **Event Flow** | In event flows triggered by form submissions, button clicks, etc., terminates subsequent steps when conditions are not met. |
+| **Linkage Rules** | In field linkages, filter linkages, etc., terminates the current event flow when validation fails or execution needs to be skipped. |
+| **Action Events** | In custom actions (e.g., delete confirmation, pre-save validation), exits when the user cancels or validation fails. |
 
-> Difference from `ctx.exitAll()`: `ctx.exit()` only stops the **current** event flow; other flows for the same event still run. `ctx.exitAll()` also stops **subsequent** flows for that event.
+> Difference from `ctx.exitAll()`: `ctx.exit()` only terminates the current event flow; other event flows under the same event are not affected. `ctx.exitAll()` terminates the current event flow as well as any subsequent event flows under the same event that have not yet been executed.
 
-## Type
+## Type Definition
 
 ```ts
 exit(): never;
 ```
 
-Calling `ctx.exit()` throws an internal `FlowExitException`, which the event flow engine catches and uses to stop the current flow. Once called, the rest of the current JS does not run.
+Calling `ctx.exit()` throws an internal `FlowExitException`, which is caught by the FlowEngine to stop the current event flow execution. Once called, the remaining statements in the current JS code will not execute.
 
 ## Comparison with ctx.exitAll()
 
-| Method | Scope |
-|--------|--------|
-| `ctx.exit()` | Stops only the current event flow; others unaffected |
-| `ctx.exitAll()` | Stops the current flow and **subsequent** flows for the same event |
+| Method | Scope of Effect |
+|------|----------|
+| `ctx.exit()` | Terminates only the current event flow; subsequent event flows are unaffected. |
+| `ctx.exitAll()` | Terminates the current event flow and aborts subsequent event flows under the same event that are set to **execute sequentially**. |
 
 ## Examples
 
-### Exit on user cancel
+### Exit on User Cancellation
 
 ```ts
+// In a confirmation modal, terminate the event flow if the user clicks cancel
 if (!confirmed) {
-  ctx.message.info('Cancelled');
+  ctx.message.info('Operation cancelled');
   ctx.exit();
 }
 ```
 
-### Exit on validation failure
+### Exit on Parameter Validation Failure
 
 ```ts
+// Prompt and terminate when validation fails
 if (!params.value || params.value.length < 3) {
-  ctx.message.error('Invalid: length must be at least 3');
+  ctx.message.error('Invalid parameters, length must be at least 3');
   ctx.exit();
 }
 ```
 
-### Exit when business condition fails
+### Exit When Business Conditions Are Not Met
 
 ```ts
+// Terminate if conditions are not met; subsequent steps will not execute
 const record = ctx.model?.getValue?.();
 if (!record || record.status !== 'draft') {
-  ctx.notification.warning({ message: 'Only draft can be submitted' });
+  ctx.notification.warning({ message: 'Only drafts can be submitted' });
   ctx.exit();
 }
 ```
 
-### When to use ctx.exit() vs ctx.exitAll()
+### Choosing Between ctx.exit() and ctx.exitAll()
 
 ```ts
-// Only this flow should stop → ctx.exit()
+// Only the current event flow needs to exit → Use ctx.exit()
 if (!params.valid) {
-  ctx.message.error('Invalid params');
-  ctx.exit();
+  ctx.message.error('Invalid parameters');
+  ctx.exit();  // Other event flows are unaffected
 }
 
-// Stop this and all subsequent flows for this event → ctx.exitAll()
+// Need to terminate all subsequent event flows under the current event → Use ctx.exitAll()
 if (!ctx.model?.context?.getPermission?.()) {
-  ctx.notification.warning({ message: 'No permission' });
-  ctx.exitAll();
+  ctx.notification.warning({ message: 'Insufficient permissions' });
+  ctx.exitAll();  // Both the current event flow and subsequent event flows under the same event are terminated
 }
 ```
 
-### Exit after modal confirm
+### Exit Based on User Choice After Modal Confirmation
 
 ```ts
 const ok = await ctx.modal?.confirm?.({
-  title: 'Confirm delete',
-  content: 'Cannot be recovered. Continue?',
+  title: 'Confirm Delete',
+  content: 'This action cannot be undone. Do you want to continue?',
 });
 if (!ok) {
   ctx.message.info('Cancelled');
@@ -90,12 +93,12 @@ if (!ok) {
 
 ## Notes
 
-- After `ctx.exit()`, the rest of the current JS does not run; use `ctx.message`, `ctx.notification`, or a dialog before calling to explain why.
-- You usually do not need to catch `FlowExitException`; the event flow engine handles it.
-- To stop all subsequent flows for the same event, use `ctx.exitAll()`.
+- After calling `ctx.exit()`, subsequent code in the current JS will not execute; it is recommended to explain the reason to the user via `ctx.message`, `ctx.notification`, or a modal before calling it.
+- There is usually no need to catch `FlowExitException` in business code; let the FlowEngine handle it.
+- If you need to terminate all subsequent event flows under the current event, use `ctx.exitAll()`.
 
 ## Related
 
-- [ctx.exitAll()](./exit-all.md): stop current and subsequent flows for the event
-- [ctx.message](./message.md): message API
-- [ctx.modal](./modal.md): confirm dialog
+- [ctx.exitAll()](./exit-all.md): Terminates the current event flow and subsequent event flows under the same event.
+- [ctx.message](./message.md): Message prompts.
+- [ctx.modal](./modal.md): Confirmation modals.

package/dist/ai/docs/runjs/context/filter-manager.md

@@ -1,28 +1,28 @@
 # ctx.filterManager
 
-The filter connection manager that links filter forms (FilterForm) to data blocks (tables, lists, charts, etc.). Provided by `BlockGridModel`; only available in that context (e.g. pages with a filter form block).
+The Filter Connection Manager is used to manage the filter associations between filter forms (FilterForm) and data blocks (tables, lists, charts, etc.). It is provided by `BlockGridModel` and is only available within its context (e.g., filter form blocks, data blocks).
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Filter form block** | Manage connections between filter items and target blocks; refresh targets when filters change |
-| **Data block (table/list)** | Act as filter target; bind filter conditions via `bindToTarget` |
-| **Linkage / custom FilterModel** | In `doFilter`, `doReset`, call `refreshTargetsByFilter` to refresh targets |
-| **Connection field config** | Use `getConnectFieldsConfig`, `saveConnectFieldsConfig` for filter–target field mapping |
+|------|------|
+| **Filter Form Block** | Manages connection configurations between filter items and target blocks; refreshes target data when filters change. |
+| **Data Block (Table/List)** | Acts as a filter target, binding filter conditions via `bindToTarget`. |
+| **Linkage Rules / Custom FilterModel** | Calls `refreshTargetsByFilter` within `doFilter` or `doReset` to trigger target refreshes. |
+| **Connection Field Configuration** | Uses `getConnectFieldsConfig` and `saveConnectFieldsConfig` to maintain field mappings between filters and targets. |
 
-> Note: `ctx.filterManager` is only available in RunJS contexts that have a `BlockGridModel` (e.g. pages with a filter form); in a plain JSBlock or standalone page it is `undefined`—check before use.
+> Note: `ctx.filterManager` is only available in RunJS contexts that have a `BlockGridModel` (e.g., within a page containing a filter form); it is `undefined` in regular JSBlocks or independent pages. It is recommended to use optional chaining before access.
 
-## Type
+## Type Definitions
 
 ```ts
 filterManager: FilterManager;
 
 type FilterConfig = {
-  filterId: string;
-  targetId: string;
-  filterPaths?: string[];
-  operator?: string;
+  filterId: string;   // Filter model UID
+  targetId: string;   // Target data block model UID
+  filterPaths?: string[];  // Field paths of the target block
+  operator?: string;  // Filter operator
 };
 
 type ConnectFieldsConfig = {
@@ -33,24 +33,24 @@ type ConnectFieldsConfig = {
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `getFilterConfigs()` | All filter connection configs |
-| `getConnectFieldsConfig(filterId)` | Connection field config for a filter |
-| `saveConnectFieldsConfig(filterId, config)` | Save connection field config for a filter |
-| `addFilterConfig(config)` | Add filter config (filterId + targetId + filterPaths) |
-| `removeFilterConfig({ filterId?, targetId?, persist? })` | Remove config by filterId and/or targetId |
-| `bindToTarget(targetId)` | Bind filter to target block; its resource applies the filter |
-| `unbindFromTarget(targetId)` | Unbind filter from target |
-| `refreshTargetsByFilter(filterId or filterId[])` | Refresh target block(s) by filter |
+|------|------|
+| `getFilterConfigs()` | Gets all current filter connection configurations. |
+| `getConnectFieldsConfig(filterId)` | Gets the connection field configuration for a specific filter. |
+| `saveConnectFieldsConfig(filterId, config)` | Saves the connection field configuration for a filter. |
+| `addFilterConfig(config)` | Adds a filter configuration (filterId + targetId + filterPaths). |
+| `removeFilterConfig({ filterId?, targetId?, persist? })` | Removes filter configurations by filterId, targetId, or both. |
+| `bindToTarget(targetId)` | Binds the filter configuration to a target block, triggering its resource to apply the filter. |
+| `unbindFromTarget(targetId)` | Unbinds the filter from the target block. |
+| `refreshTargetsByFilter(filterId | filterId[])` | Refreshes associated target block data based on the filter(s). |
 
-## Concepts
+## Core Concepts
 
-- **FilterModel**: Provides filter values (e.g. FilterFormItemModel); must implement `getFilterValue()`.
-- **TargetModel**: Data block being filtered; its `resource` must support `addFilterGroup`, `removeFilterGroup`, `refresh`.
+- **FilterModel**: A model providing filter conditions (e.g., FilterFormItemModel), which must implement `getFilterValue()` to return the current filter value.
+- **TargetModel**: The data block being filtered; its `resource` must support `addFilterGroup`, `removeFilterGroup`, and `refresh`.
 
 ## Examples
 
-### Add filter config
+### Add Filter Configuration
 
 ```ts
 await ctx.filterManager?.addFilterConfig({
@@ -61,19 +61,23 @@ await ctx.filterManager?.addFilterConfig({
 });
 ```
 
-### Refresh target blocks
+### Refresh Target Blocks
 
 ```ts
+// In doFilter / doReset of a filter form
 ctx.filterManager?.refreshTargetsByFilter(ctx.model.uid);
 
+// Refresh targets associated with multiple filters
 ctx.filterManager?.refreshTargetsByFilter(['filter-1', 'filter-2']);
 ```
 
-### Connection field config
+### Connection Field Configuration
 
 ```ts
+// Get connection configuration
 const config = ctx.filterManager?.getConnectFieldsConfig(ctx.model.uid);
 
+// Save connection configuration
 await ctx.filterManager?.saveConnectFieldsConfig(ctx.model.uid, {
   targets: [
     { targetId: 'table-uid', filterPaths: ['status'] },
@@ -82,15 +86,17 @@ await ctx.filterManager?.saveConnectFieldsConfig(ctx.model.uid, {
 });
 ```
 
-### Remove config
+### Remove Configuration
 
 ```ts
+// Delete all configurations for a specific filter
 await ctx.filterManager?.removeFilterConfig({ filterId: 'filter-uid' });
 
+// Delete all filter configurations for a specific target
 await ctx.filterManager?.removeFilterConfig({ targetId: 'table-uid' });
 ```
 
 ## Related
 
-- [ctx.resource](./resource.md): target block’s resource must support filter APIs
-- [ctx.model](./model.md): current model uid for filterId / targetId
+- [ctx.resource](./resource.md): The target block's resource must support the filter interface.
+- [ctx.model](./model.md): Used to get the current model's UID for filterId / targetId.

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

@@ -1,109 +1,109 @@
 # ctx.form
 
-The Ant Design Form instance for the current block; used to read/write form fields, trigger validation, and submit. Same as `ctx.blockModel?.form`; in form blocks (Form, EditForm, sub-forms, etc.) you can use it directly.
+The Ant Design Form instance within the current block, used to read/write form fields, trigger validation, and submission. It is equivalent to `ctx.blockModel?.form` and can be used directly in form-related blocks (Form, Edit Form, Sub-form, etc.).
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSField** | Read/write other fields for linkage, compute or validate from other field values |
-| **JSItem** | Read/write same row or other fields in sub-table items |
-| **JSColumn** | Read row or related field values for column rendering |
-| **Form actions / event flow** | Pre-submit validation, batch field updates, reset form, etc. |
+|------|------|
+| **JSField** | Read/write other form fields to implement linkage, or perform calculations and validation based on other field values. |
+| **JSItem** | Read/write same-row or other fields within sub-table items to achieve in-table linkage. |
+| **JSColumn** | Read the current row or association field values in a table column for rendering. |
+| **Form Actions / Workflow** | Pre-submission validation, batch updating fields, resetting forms, etc. |
 
-> Note: `ctx.form` is only available in RunJS contexts tied to a form block (Form, EditForm, sub-forms, etc.); in non-form contexts (e.g. standalone JSBlock, table block) it may be absent—check before use: `ctx.form?.getFieldsValue()`.
+> Note: `ctx.form` is only available in RunJS contexts related to form blocks (Form, Edit Form, Sub-form, etc.). It may not exist in non-form scenarios (such as independent JSBlocks or Table blocks). It is recommended to perform a null check before use: `ctx.form?.getFieldsValue()`.
 
-## Type
+## Type Definition
 
 ```ts
 form: FormInstance<any>;
 ```
 
-`FormInstance` is the Ant Design Form instance type.
+`FormInstance` is the instance type of Ant Design Form. Common methods are as follows.
 
 ## Common Methods
 
-### Read form values
+### Reading Form Values
 
 ```ts
-// Current registered field values (default: only rendered fields)
+// Read values of currently registered fields (defaults to rendered fields only)
 const values = ctx.form.getFieldsValue();
 
-// All field values (including unrendered, e.g. hidden, collapsed)
+// Read values of all fields (including registered but unrendered fields, e.g., hidden or inside collapsed sections)
 const allValues = ctx.form.getFieldsValue(true);
 
-// Single field
+// Read a single field
 const email = ctx.form.getFieldValue('email');
 
-// Nested (e.g. sub-table)
+// Read nested fields (e.g., in a sub-table)
 const amount = ctx.form.getFieldValue(['orders', 0, 'amount']);
 ```
 
-### Write form values
+### Writing Form Values
 
 ```ts
-// Batch update (e.g. linkage)
+// Batch update (commonly used for linkage)
 ctx.form.setFieldsValue({
   status: 'active',
   updatedAt: new Date(),
 });
 
-// Single field
-ctx.form.setFieldValue('remark', 'Noted');
+// Update a single field
+ctx.form.setFieldValue('remark', 'Updated remark');
 ```
 
-### Validation and submit
+### Validation and Submission
 
 ```ts
-// Trigger validation
+// Trigger form validation
 await ctx.form.validateFields();
 
-// Trigger submit
+// Trigger form submission
 ctx.form.submit();
 ```
 
-### Reset
+### Resetting
 
 ```ts
-// All fields
+// Reset all fields
 ctx.form.resetFields();
 
-// Specific fields
+// Reset only specific fields
 ctx.form.resetFields(['status', 'remark']);
 ```
 
-## Relation to Other Context
+## Relationship with Related Contexts
 
 ### ctx.getValue / ctx.setValue
 
-| Scenario | Recommended |
-|----------|-------------|
-| **Current field** | `ctx.getValue()` / `ctx.setValue(v)` |
-| **Other fields** | `ctx.form.getFieldValue(name)` / `ctx.form.setFieldValue(name, v)` |
+| Scenario | Recommended Usage |
+|------|----------|
+| **Read/Write current field** | `ctx.getValue()` / `ctx.setValue(v)` |
+| **Read/Write other fields** | `ctx.form.getFieldValue(name)` / `ctx.form.setFieldValue(name, v)` |
 
-In the current JS field, use `getValue`/`setValue` for that field; use `ctx.form` for other fields.
+Within the current JS field, prioritize using `getValue`/`setValue` to read/write the field itself; use `ctx.form` when you need to access other fields.
 
 ### ctx.blockModel
 
-| Need | Recommended |
-|------|-------------|
-| **Read/write form fields** | `ctx.form` (same as `ctx.blockModel?.form`) |
-| **Parent block** | `ctx.blockModel` (includes `collection`, `resource`, etc.) |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Read/Write form fields** | `ctx.form` (Equivalent to `ctx.blockModel?.form`, more convenient) |
+| **Access parent block** | `ctx.blockModel` (Contains `collection`, `resource`, etc.) |
 
 ### ctx.getVar('ctx.formValues')
 
-Form values are obtained via `await ctx.getVar('ctx.formValues')`, not as `ctx.formValues`. In form contexts, prefer `ctx.form.getFieldsValue()` for up-to-date values.
+Form values must be obtained via `await ctx.getVar('ctx.formValues')` and are not directly exposed as `ctx.formValues`. In a form context, it is preferred to use `ctx.form.getFieldsValue()` to read the latest values in real-time.
 
 ## Notes
 
-- `getFieldsValue()` by default returns only rendered fields; for unrendered (e.g. collapsed) use `getFieldsValue(true)`.
-- Nested paths use arrays, e.g. `['orders', 0, 'amount']`; you can use `ctx.namePath` to build paths for other columns in the same row.
-- `validateFields()` throws with `errorFields` etc. on failure; use `ctx.exit()` to stop further steps when validation fails.
-- In event flow or linkage, `ctx.form` may not be ready yet; use optional chaining or null checks.
+- `getFieldsValue()` returns only rendered fields by default. To include unrendered fields (e.g., in collapsed sections or hidden by conditional rules), pass `true`: `getFieldsValue(true)`.
+- Paths for nested fields like sub-tables are arrays, e.g., `['orders', 0, 'amount']`. You can use `ctx.namePath` to get the current field's path and construct paths for other columns in the same row.
+- `validateFields()` throws an error object containing `errorFields` and other information. If validation fails before submission, you can use `ctx.exit()` to terminate subsequent steps.
+- In asynchronous scenarios like workflows or linkage rules, `ctx.form` might not be ready yet. It is recommended to use optional chaining or null checks.
 
 ## Examples
 
-### Field linkage by type
+### Field Linkage: Display different content based on type
 
 ```ts
 const type = ctx.form.getFieldValue('type');
@@ -114,7 +114,7 @@ if (type === 'vip') {
 }
 ```
 
-### Compute current field from others
+### Calculate current field based on other fields
 
 ```ts
 const quantity = ctx.form.getFieldValue('quantity') ?? 0;
@@ -122,48 +122,48 @@ const price = ctx.form.getFieldValue('price') ?? 0;
 ctx.setValue(quantity * price);
 ```
 
-### Same row in sub-table
+### Read/Write other columns in the same row within a sub-table
 
 ```ts
-// ctx.namePath is current field path, e.g. ['orders', 0, 'amount']
-// Same row status: ['orders', 0, 'status']
+// ctx.namePath is the path of the current field in the form, e.g., ['orders', 0, 'amount']
+// Read 'status' in the same row: ['orders', 0, 'status']
 const rowIndex = ctx.namePath?.[1];
 const status = ctx.form.getFieldValue(['orders', rowIndex, 'status']);
 ```
 
-### Pre-submit validation
+### Pre-submission Validation
 
 ```ts
 try {
   await ctx.form.validateFields();
-  // Continue submit logic
+  // Validation passed, continue with submission logic
 } catch (e) {
-  ctx.message.error('Please fix form errors');
+  ctx.message.error('Please check the form fields');
   ctx.exit();
 }
 ```
 
-### Confirm then submit
+### Submit after Confirmation
 
 ```ts
 const confirmed = await ctx.modal.confirm({
-  title: 'Confirm submit',
-  content: 'Cannot be changed after submit. Continue?',
-  okText: 'OK',
+  title: 'Confirm Submission',
+  content: 'You will not be able to modify this after submission. Continue?',
+  okText: 'Confirm',
   cancelText: 'Cancel',
 });
 if (confirmed) {
   await ctx.form.validateFields();
   ctx.form.submit();
 } else {
-  ctx.exit();
+  ctx.exit(); // Terminate if user cancels
 }
 ```
 
 ## Related
 
-- [ctx.getValue()](./get-value.md) / [ctx.setValue()](./set-value.md): read/write current field
-- [ctx.blockModel](./block-model.md): parent block; `ctx.form` is `ctx.blockModel?.form`
-- [ctx.modal](./modal.md): confirm dialog, often with `ctx.form.validateFields()` / `ctx.form.submit()`
-- [ctx.exit()](./exit.md): stop flow on validation failure or cancel
-- `ctx.namePath`: current field path in the form (array); use for nested `getFieldValue` / `setFieldValue` names
+- [ctx.getValue()](./get-value.md) / [ctx.setValue()](./set-value.md): Read and write the current field value.
+- [ctx.blockModel](./block-model.md): Parent block model; `ctx.form` is equivalent to `ctx.blockModel?.form`.
+- [ctx.modal](./modal.md): Confirmation dialogs, often used with `ctx.form.validateFields()` and `ctx.form.submit()`.
+- [ctx.exit()](./exit.md): Terminate the process upon validation failure or user cancellation.
+- `ctx.namePath`: The path (array) of the current field in the form, used to construct names for `getFieldValue` / `setFieldValue` in nested fields.

package/dist/ai/docs/runjs/context/get-model.md

@@ -1,18 +1,18 @@
 # ctx.getModel()
 
-Returns a model instance (e.g. BlockModel, PageModel, ActionModel) from the current engine or view stack by its `uid`. Use in RunJS to access other models across blocks, pages, or popups.
+Retrieves a model instance (such as `BlockModel`, `PageModel`, `ActionModel`, etc.) from the current engine or view stack based on the model `uid`. This is used in RunJS to access other models across blocks, pages, or popups.
 
-If you only need the model or block for the current execution context, use `ctx.model` or `ctx.blockModel` instead of `ctx.getModel`.
+If you only need the model or block where the current execution context is located, prioritize using `ctx.model` or `ctx.blockModel` instead of `ctx.getModel`.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSAction** | Get another block’s model by known `uid`; read/write its `resource`, `form`, `setProps`, etc. |
-| **RunJS inside popup** | Access a model on the page that opened the popup; pass `searchInPreviousEngines: true` |
-| **Custom actions** | Find a form or sub-model in the settings panel across the view stack by `uid` |
+|------|------|
+| **JSBlock / JSAction** | Get models of other blocks based on a known `uid` to read or write their `resource`, `form`, `setProps`, etc. |
+| **RunJS in Popups** | When needing to access a model on the page that opened the popup, pass `searchInPreviousEngines: true`. |
+| **Custom Actions** | Locate forms or sub-models in the configuration panel by `uid` across view stacks to read their configuration or state. |
 
-## Type
+## Type Definition
 
 ```ts
 getModel<T extends FlowModel = FlowModel>(
@@ -24,19 +24,19 @@ getModel<T extends FlowModel = FlowModel>(
 ## Parameters
 
 | Parameter | Type | Description |
-|-----------|------|-------------|
-| `uid` | `string` | Unique id of the target model (e.g. from config or creation) |
-| `searchInPreviousEngines` | `boolean` | Optional, default `false`. When `true`, search up the view stack from the current engine to find models in parent views (e.g. the page that opened the popup) |
+|------|------|------|
+| `uid` | `string` | The unique identifier of the target model instance, specified during configuration or creation (e.g., `ctx.model.uid`). |
+| `searchInPreviousEngines` | `boolean` | Optional, defaults to `false`. When `true`, searches from the current engine up to the root in the "view stack," allowing access to models in upper-level engines (e.g., the page that opened a popup). |
 
-## Return value
+## Return Value
 
-- Returns the corresponding `FlowModel` subclass (e.g. `BlockModel`, `FormBlockModel`, `ActionModel`) if found.
+- Returns the corresponding `FlowModel` subclass instance (e.g., `BlockModel`, `FormBlockModel`, `ActionModel`) if found.
 - Returns `undefined` if not found.
 
-## Search scope
+## Search Scope
 
-- **Default (`searchInPreviousEngines: false`)**: Search only in the **current engine** by `uid`. In popups or nested views, each view has its own engine; by default only the current view is searched.
-- **`searchInPreviousEngines: true`**: Search from the current engine along the `previousEngine` chain; returns the first match. Use when RunJS in a popup needs to access a model on the page that opened it.
+- **Default (`searchInPreviousEngines: false`)**: Searches only within the **current engine** by `uid`. In popups or multi-level views, each view has an independent engine; by default, it only searches for models within the current view.
+- **`searchInPreviousEngines: true`**: Searches upwards along the `previousEngine` chain starting from the current engine, returning the first match. This is useful for accessing a model on the page that opened the current popup.
 
 ## Examples
 
@@ -49,16 +49,17 @@ if (block?.resource) {
 }
 ```
 
-### Access page model from inside popup
+### Access a model on the page from a popup
 
 ```ts
+// Access a block on the page that opened the current popup
 const pageBlock = ctx.getModel('page-block-uid', true);
 if (pageBlock) {
   pageBlock.rerender?.();
 }
 ```
 
-### Cross-model update and rerender
+### Cross-model read/write and trigger rerender
 
 ```ts
 const target = ctx.getModel('other-block-uid');
@@ -68,17 +69,17 @@ if (target) {
 }
 ```
 
-### Null check
+### Safety check
 
 ```ts
 const model = ctx.getModel(someUid);
 if (!model) {
-  ctx.message.warning('Target model not found');
+  ctx.message.warning('Target model does not exist');
   return;
 }
 ```
 
 ## Related
 
-- [ctx.model](./model.md): model for current execution context
-- [ctx.blockModel](./block-model.md): parent block of current JS; often no need for `getModel`
+- [ctx.model](./model.md): The model where the current execution context is located.
+- [ctx.blockModel](./block-model.md): The parent block model where the current JS is located; usually accessible without needing `getModel`.