@nocobase/flow-engine 2.2.0-alpha.1 → 2.2.0-alpha.11

package/src/components/variables/__tests__/VariableInput.test.tsx

@@ -8,6 +8,7 @@
  */
 
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { Input } from 'antd';
 import React from 'react';
 import { describe, expect, it, vi } from 'vitest';
 import type { ContextSelectorItem } from '../types';
@@ -100,6 +101,127 @@ describe('VariableInput', () => {
     );
   });
 
+  it('renders a variable tag when custom converters resolve a non-ctx workflow variable format', async () => {
+    const flowContext = createTestFlowContext();
+    const workflowMetaTree = [
+      {
+        name: '$context',
+        title: 'Trigger variables',
+        type: 'object',
+        paths: ['$context'],
+        children: [
+          {
+            name: 'data',
+            title: 'Trigger data',
+            type: 'object',
+            paths: ['$context', 'data'],
+            children: [
+              {
+                name: 'updatedAt',
+                title: 'Last updated at',
+                type: 'string',
+                paths: ['$context', 'data', 'updatedAt'],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableInput
+          value="{{$context.data.updatedAt}}"
+          metaTree={workflowMetaTree}
+          converters={{
+            resolvePathFromValue: (currentValue) =>
+              currentValue === '{{$context.data.updatedAt}}' ? ['$context', 'data', 'updatedAt'] : undefined,
+            resolveValueFromPath: () => undefined,
+          }}
+        />
+      </TestFlowContextWrapper>,
+    );
+
+    await waitFor(
+      () => {
+        const variableTag = screen.getByText('Trigger variables/Trigger data/Last updated at');
+        expect(variableTag).toBeInTheDocument();
+        expect(variableTag.closest('.ant-tag')).toBeInTheDocument();
+      },
+      { timeout: 3000 },
+    );
+
+    const selectorButton = screen.getByRole('button');
+    expect(selectorButton.className).toContain('ant-btn-primary');
+  });
+
+  it('renders a parsing failure tag when a custom variable path is missing from the meta tree', async () => {
+    const flowContext = createTestFlowContext();
+    const workflowMetaTree = [
+      {
+        name: '$context',
+        title: 'Trigger variables',
+        type: 'object',
+        paths: ['$context'],
+        children: [
+          {
+            name: 'data',
+            title: 'Trigger data',
+            type: 'object',
+            paths: ['$context', 'data'],
+          },
+        ],
+      },
+    ];
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableInput
+          value="{{$context.data.id}}"
+          metaTree={workflowMetaTree}
+          converters={{
+            resolvePathFromValue: (currentValue) =>
+              currentValue === '{{$context.data.id}}' ? ['$context', 'data', 'id'] : undefined,
+            resolveValueFromPath: () => undefined,
+          }}
+        />
+      </TestFlowContextWrapper>,
+    );
+
+    await waitFor(
+      () => {
+        const variableTag = screen.getByText('Variable parsing failed');
+        expect(variableTag).toBeInTheDocument();
+        expect(variableTag.closest('.ant-tag')).toHaveClass('ant-tag-error');
+      },
+      { timeout: 3000 },
+    );
+
+    expect(screen.queryByDisplayValue('{{$context.data.id}}')).not.toBeInTheDocument();
+    expect(screen.getByRole('button').className).toContain('ant-btn-primary');
+  });
+
+  it('disables custom tag input when rendering a selected variable', async () => {
+    const flowContext = createTestFlowContext();
+    const { container } = render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableInput value="{{ ctx.user.name }}" metaTree={() => flowContext.getPropertyMetaTree()} />
+      </TestFlowContextWrapper>,
+    );
+
+    await waitFor(
+      () => {
+        expect(screen.getByText('User/Name')).toBeInTheDocument();
+      },
+      { timeout: 3000 },
+    );
+
+    const selectElement = container.querySelector('.ant-select.variable');
+    expect(selectElement).toBeInTheDocument();
+    expect(selectElement).not.toHaveClass('ant-select-show-search');
+    expect(container.querySelector('.ant-select-selection-search-input')).toHaveAttribute('readonly');
+  });
+
   it('should render FlowContextSelector button', async () => {
     const flowContext = createTestFlowContext();
     render(
@@ -112,6 +234,62 @@ describe('VariableInput', () => {
     expect(selectorButton).toBeInTheDocument();
   });
 
+  it('disables the FlowContextSelector button when disabled', async () => {
+    const flowContext = createTestFlowContext();
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableInput value="test" metaTree={() => flowContext.getPropertyMetaTree()} disabled />
+      </TestFlowContextWrapper>,
+    );
+
+    const selectorButton = await screen.findByRole('button');
+    expect(selectorButton).toBeDisabled();
+  });
+
+  it('should not highlight the selector button for synthetic constant/null paths', async () => {
+    const flowContext = createTestFlowContext();
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableInput
+          value=""
+          metaTree={[
+            { name: 'constant', title: 'Constant', type: 'string', paths: ['constant'] },
+            { name: 'null', title: 'Null', type: 'object', paths: ['null'] },
+            ...flowContext.getPropertyMetaTree(),
+          ]}
+          converters={{
+            renderInputComponent: (meta) => {
+              const first = meta?.paths?.[0];
+              if (first === 'constant') {
+                return (props: any) => <input aria-label="constant-value" {...props} />;
+              }
+              if (first === 'null') {
+                return () => <Input placeholder="<Null>" readOnly />;
+              }
+              return null;
+            },
+            resolveValueFromPath: (meta) => {
+              const first = meta?.paths?.[0];
+              if (first === 'constant') return '';
+              if (first === 'null') return null;
+              return undefined;
+            },
+            resolvePathFromValue: (currentValue) => {
+              if (currentValue === null) return ['null'];
+              const trimmed = typeof currentValue === 'string' ? currentValue.trim() : currentValue;
+              if (trimmed === '') return ['constant'];
+              return undefined;
+            },
+          }}
+        />
+      </TestFlowContextWrapper>,
+    );
+
+    const selectorButton = await screen.findByRole('button');
+    expect(selectorButton.className).not.toContain('ant-btn-primary');
+  });
+
   it('should handle onChange from Input', async () => {
     const onChange = vi.fn();
     const flowContext = createTestFlowContext();
@@ -195,20 +373,21 @@ describe('VariableInput', () => {
 
     const selectElement = container.querySelector('.ant-select');
     expect(selectElement).toBeInTheDocument();
+    if (!selectElement) {
+      throw new Error('Expected variable tag select wrapper to be present');
+    }
 
     // 触发鼠标悬停以显示清除按钮
-    fireEvent.mouseEnter(selectElement!);
+    fireEvent.mouseEnter(selectElement);
 
     // 尝试触发清除功能
     // 方法1: 直接触发 Select 组件的 onClear 事件
-    const selectInstance = selectElement as any;
-
     // 尝试通过键盘事件触发清除
-    fireEvent.keyDown(selectElement!, { key: 'Backspace', code: 'Backspace' });
+    fireEvent.keyDown(selectElement, { key: 'Backspace', code: 'Backspace' });
 
     // 或者尝试触发自定义的清除逻辑
     const clearEvents = new CustomEvent('clear');
-    selectElement!.dispatchEvent(clearEvents);
+    selectElement.dispatchEvent(clearEvents);
 
     // 检查是否调用了清除功能（可能需要调整期望）
     // 如果清除按钮不能直接测试，我们验证组件支持清除功能
@@ -276,7 +455,24 @@ describe('VariableInput', () => {
     expect(input).toHaveClass('custom-class');
 
     // Note: The disabled prop might not be correctly passed through in the current implementation
-    // This is a known limitation of the current component design
+    expect(input).toBeDisabled();
+  });
+
+  it('disables the rendered variable tag when the input is disabled', async () => {
+    const flowContext = createTestFlowContext();
+    const { container } = render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableInput value="{{ ctx.user.name }}" metaTree={() => flowContext.getPropertyMetaTree()} disabled />
+      </TestFlowContextWrapper>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('User/Name')).toBeInTheDocument();
+    });
+
+    const selectElement = container.querySelector('.ant-select.variable');
+    expect(selectElement).toHaveClass('ant-select-disabled');
+    expect(container.querySelector('.ant-select-clear')).not.toBeInTheDocument();
   });
 
   it('should handle empty metaTree', async () => {

package/src/components/variables/__tests__/VariableTag.test.tsx

@@ -54,6 +54,44 @@ describe('VariableTag', () => {
     expect(onClear).toBeInstanceOf(Function);
   });
 
+  it('keeps custom tag input enabled by default', async () => {
+    const onClear = vi.fn();
+    const { container } = renderWithCtx(<VariableTag value="{{ ctx.User.Email }}" onClear={onClear} />);
+
+    await waitFor(
+      () => {
+        expect(screen.getByText('User/Email')).toBeInTheDocument();
+      },
+      { timeout: 3000 },
+    );
+
+    const selectElement = container.querySelector('.ant-select.variable');
+    expect(selectElement).toBeInTheDocument();
+    expect(selectElement).toHaveClass('ant-select-show-search');
+    expect(container.querySelector('.ant-select-selection-search-input')).not.toHaveAttribute('readonly');
+  });
+
+  it('can disable custom tag input while keeping clear enabled', async () => {
+    const onClear = vi.fn();
+    const { container } = renderWithCtx(
+      <VariableTag value="{{ ctx.User.Email }}" onClear={onClear} allowCustomTagInput={false} />,
+    );
+
+    await waitFor(
+      () => {
+        expect(screen.getByText('User/Email')).toBeInTheDocument();
+      },
+      { timeout: 3000 },
+    );
+
+    const selectElement = container.querySelector('.ant-select.variable');
+    expect(selectElement).toBeInTheDocument();
+    expect(selectElement).not.toHaveClass('ant-select-disabled');
+    expect(selectElement).not.toHaveClass('ant-select-show-search');
+    expect(container.querySelector('.ant-select-clear')).toBeInTheDocument();
+    expect(container.querySelector('.ant-select-selection-search-input')).toHaveAttribute('readonly');
+  });
+
   it('should not show close button when onClear is not provided', async () => {
     const { container } = renderWithCtx(<VariableTag value="{{ ctx.User.Name }}" />);
 
@@ -166,6 +204,32 @@ describe('VariableTag', () => {
     }
   });
 
+  it('renders a red failure pill when the variable path cannot be resolved', async () => {
+    renderWithCtx(
+      <VariableTag
+        value="{{ ctx.missing.field }}"
+        metaTree={[
+          {
+            name: 'user',
+            title: 'User',
+            type: 'object',
+            paths: ['user'],
+            children: [{ name: 'name', title: 'Name', type: 'string', paths: ['user', 'name'] }],
+          },
+        ]}
+      />,
+    );
+
+    await waitFor(
+      () => {
+        const tag = screen.getByText('Variable parsing failed');
+        expect(tag).toBeInTheDocument();
+        expect(tag.closest('.ant-tag')).toHaveClass('ant-tag-error');
+      },
+      { timeout: 3000 },
+    );
+  });
+
   it('should render Select component with proper structure', async () => {
     const { container } = render(<VariableTag value="{{ ctx.Test }}" />);
 
@@ -233,6 +297,22 @@ describe('VariableTag', () => {
     expect(selectElement).not.toHaveClass('ant-select-disabled');
   });
 
+  it('does not show clear affordance when disabled even if onClear is provided', async () => {
+    const onClear = vi.fn();
+    const { container } = renderWithCtx(<VariableTag value="{{ ctx.Test }}" onClear={onClear} disabled />);
+
+    await waitFor(
+      () => {
+        expect(screen.getByText('Test')).toBeInTheDocument();
+      },
+      { timeout: 3000 },
+    );
+
+    const selectElement = container.querySelector('.ant-select.variable');
+    expect(selectElement).toHaveClass('ant-select-disabled');
+    expect(container.querySelector('.ant-select-clear')).not.toBeInTheDocument();
+  });
+
   it('should have proper accessibility attributes for Select component', async () => {
     const { container } = renderWithCtx(<VariableTag value="{{ ctx.Test }}" />);
 

package/src/components/variables/types.ts

@@ -16,12 +16,30 @@ export interface FlowContextSelectorProps
   value?: string;
   onChange?: (value: string, metaTreeNode?: MetaTreeNode) => void;
   children?: CascaderProps<ContextSelectorItem>['children'];
+  /**
+   * Controls whether the default `x` trigger button is rendered as active
+   * (`type="primary"`). When omitted, the selector falls back to its parsed
+   * `value` path (`true` iff a valid variable path is currently selected).
+   *
+   * Use this when callers intentionally feed synthetic paths such as
+   * `['constant']` / `['null']` into the cascader to keep menu state aligned,
+   * but only want real variable references to show the blue active button.
+   */
+  active?: boolean;
   metaTree?: MetaTreeNode[] | (() => MetaTreeNode[] | Promise<MetaTreeNode[]>);
   parseValueToPath?: (value: string) => string[] | undefined;
   formatPathToValue?: (item: MetaTreeNode) => string;
   open?: boolean;
   onlyLeafSelectable?: boolean;
   ignoreFieldNames?: string[];
+  /**
+   * Footer rendered at the bottom of the dropdown. Defaults to a muted
+   * "Double click to choose entire object" hint when non-leaf selection is
+   * allowed (`onlyLeafSelectable` is false) — since double-clicking a non-leaf
+   * node selects the whole object. Pass an explicit node to override, or `null`
+   * to hide it.
+   */
+  dropdownFooter?: React.ReactNode;
 }
 
 export interface ContextSelectorItem {
@@ -76,7 +94,10 @@ export interface VariableInputProps {
 
 export interface VariableTagProps {
   value?: string;
+  resolvedPath?: Array<string | number>;
   onClear?: () => void;
+  disabled?: boolean;
+  allowCustomTagInput?: boolean;
   className?: string;
   style?: React.CSSProperties;
   metaTreeNode?: MetaTreeNode | null;

package/src/flowContext.ts

@@ -9,7 +9,7 @@
 
 import { ISchema } from '@formily/json-schema';
 import { observable } from '@formily/reactive';
-import { APIClient, RequestOptions } from '@nocobase/sdk';
+import type { APIClient, RequestOptions } from '@nocobase/sdk';
 import type { Router } from '@remix-run/router';
 import axios from 'axios';
 import { MessageInstance } from 'antd/es/message/interface';
@@ -39,9 +39,11 @@ import {
   extractUsedVariablePaths,
   FlowExitException,
   FLOW_ENGINE_NAMESPACE,
+  createOpenViewRouteState,
   isCtxDatePathPrefix,
   isCssFile,
   prepareRunJsCode,
+  RUNJS_OPEN_VIEW_ROUTE_STATE,
   resolveCtxDatePath,
   resolveDefaultParams,
   resolveExpressions,
@@ -51,6 +53,7 @@ import { FlowExitAllException } from './utils/exceptions';
 import { enqueueVariablesResolve, JSONValue } from './utils/params-resolvers';
 import type { RecordRef } from './utils/serverContextParams';
 import { buildServerContextParams as _buildServerContextParams } from './utils/serverContextParams';
+import { getDirtyAwareApiClient } from './utils/dirtyAwareApiClient';
 import { inferRecordRef } from './utils/variablesParams';
 import { FlowView, FlowViewer } from './views/FlowView';
 import { RunJSContextRegistry, getModelClassName, type RunJSVersion } from './runjs-context/registry';
@@ -2909,19 +2912,20 @@ export class FlowContext {
 
     // 静态值
     if ('value' in options) {
-      return options.value;
+      return key === 'api' ? getDirtyAwareApiClient(options.value, currentContext) : options.value;
     }
 
     // get 方法
     if (options.get) {
       if (options.cache === false) {
-        return options.get(currentContext);
+        const value = options.get(currentContext);
+        return key === 'api' ? getDirtyAwareApiClient(value, currentContext) : value;
       }
 
       const cacheKey = options.observable ? '_observableCache' : '_cache';
 
       if (key in this[cacheKey]) {
-        return this[cacheKey][key];
+        return key === 'api' ? getDirtyAwareApiClient(this[cacheKey][key], currentContext) : this[cacheKey][key];
       }
 
       if (this._pending[key]) return this._pending[key];
@@ -2939,7 +2943,7 @@ export class FlowContext {
           (v) => {
             this[cacheKey][key] = v;
             delete this._pending[key];
-            return v;
+            return key === 'api' ? getDirtyAwareApiClient(v, currentContext) : v;
           },
           (err) => {
             delete this._pending[key];
@@ -2951,7 +2955,7 @@ export class FlowContext {
 
       // sync 直接缓存
       this[cacheKey][key] = result;
-      return result;
+      return key === 'api' ? getDirtyAwareApiClient(result, currentContext) : result;
     }
 
     return undefined;
@@ -3074,7 +3078,7 @@ class BaseFlowEngineContext extends FlowContext {
     this.defineMethod('getModel', (modelName: string, searchInPreviousEngines?: boolean) => {
       return this.engine.getModel(modelName, searchInPreviousEngines);
     });
-    this.defineMethod('request', (options: RequestOptions) => {
+    this.defineMethod('request', function (this: FlowContext, options: RequestOptions) {
       const app = this.app as { getApiUrl?: (pathname?: string) => string } | undefined;
       if (typeof options?.url === 'string' && shouldBypassApiClient(options.url, app)) {
         return axios.request(options);
@@ -3139,6 +3143,37 @@ class BaseFlowModelContext extends BaseFlowEngineContext {
   declare makeResource: <T extends FlowResource = FlowResource>(resourceType: ResourceType<T>) => T;
 }
 
+const OPEN_VIEW_INHERITED_INPUT_ARG_KEYS = [
+  'dataSourceKey',
+  'collectionName',
+  'associationName',
+  'filterByTk',
+  'sourceId',
+  'tabUid',
+];
+
+function pickDefinedKeys(source: Record<string, unknown> | null | undefined, keys: string[]) {
+  const res: Record<string, unknown> = {};
+  for (const key of keys) {
+    if (typeof source?.[key] !== 'undefined') {
+      res[key] = source[key];
+    }
+  }
+  return res;
+}
+
+function pickDefinedOpenViewInputArgs(source?: Record<string, unknown> | null) {
+  return pickDefinedKeys(source, OPEN_VIEW_INHERITED_INPUT_ARG_KEYS);
+}
+
+function applyDefinedDefaults(target: Record<string, unknown>, defaults: Record<string, unknown>) {
+  for (const [key, value] of Object.entries(defaults)) {
+    if (typeof target[key] === 'undefined') {
+      target[key] = value;
+    }
+  }
+}
+
 export class FlowEngineContext extends BaseFlowEngineContext {
   // public dataSourceManager: DataSourceManager;
   constructor(public engine: FlowEngine) {
@@ -3398,7 +3433,19 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       }),
     });
     this.defineProperty('role', {
-      get: () => this.api?.auth?.role,
+      get: () => {
+        const currentRole = this.api?.auth?.role;
+        if (currentRole !== '__union__') {
+          return currentRole;
+        }
+        const roles = this.user?.roles;
+        if (!Array.isArray(roles)) {
+          return [];
+        }
+        return roles
+          .map((role: { name?: string }) => role?.name)
+          .filter((name: string | undefined): name is string => !!name);
+      },
       cache: false,
       // 注意：使用惰性 meta 工厂，避免在 i18n 尚未注入时提前求值导致无法翻译
       meta: Object.assign(() => ({ type: 'string', title: this.t('Current role'), sort: 990 }), {
@@ -3457,11 +3504,12 @@ export class FlowEngineContext extends BaseFlowEngineContext {
     });
     this.defineProperty('auth', {
       get: () => ({
-        roleName: this.api.auth.role,
-        locale: this.api.auth.locale,
-        token: this.api.auth.token,
+        roleName: this.api?.auth?.role,
+        locale: this.api?.auth?.locale,
+        token: this.api?.auth?.token,
         user: this.user,
       }),
+      cache: false,
     });
     this.defineProperty('date', {
       get: () => {
@@ -3561,7 +3609,17 @@ export class FlowEngineContext extends BaseFlowEngineContext {
         doc = {};
       }
       const deprecatedCtx = createRunJSDeprecationProxy(runCtx, { doc });
-      const globals: Record<string, any> = { ctx: deprecatedCtx, ...(options?.globals || {}) };
+      const browserGlobals: Record<string, any> = {};
+      if (typeof window !== 'undefined') {
+        browserGlobals.window = window;
+        if (typeof navigator !== 'undefined') {
+          browserGlobals.navigator = navigator;
+        }
+      }
+      if (typeof document !== 'undefined') {
+        browserGlobals.document = document;
+      }
+      const globals: Record<string, any> = { ctx: deprecatedCtx, ...browserGlobals, ...(options?.globals || {}) };
       const { timeoutMs } = options || {};
       return new JSRunner({ globals, timeoutMs });
     });
@@ -3687,7 +3745,14 @@ export class FlowModelContext extends BaseFlowModelContext {
       },
     });
     this.defineMethod('openView', async function (uid: string, options) {
-      const opts = { ...options };
+      const inheritedInputArgs = {
+        ...(typeof this.model?.['getInputArgs'] === 'function'
+          ? pickDefinedOpenViewInputArgs(this.model['getInputArgs']())
+          : {}),
+        ...pickDefinedOpenViewInputArgs(this.inputArgs),
+      };
+      const opts = { ...(options || {}) };
+      applyDefinedDefaults(opts, inheritedInputArgs);
       // NOTE: when custom context is passed, route navigation must be disabled to avoid losing it after refresh.
       if (opts.defineProperties || opts.defineMethods) {
         opts.navigation = false; // 强制不使用路由导航, 避免刷新页面时丢失上下文
@@ -3695,15 +3760,6 @@ export class FlowModelContext extends BaseFlowModelContext {
       let model: FlowModel | null = null;
       model = await this.engine.loadModel({ uid });
       if (!model) {
-        const pickDefined = (src: Record<string, any>, keys: string[]) => {
-          const res: Record<string, any> = {};
-          for (const k of keys) {
-            if (typeof src?.[k] !== 'undefined') {
-              res[k] = src[k];
-            }
-          }
-          return res;
-        };
         model = this.engine.createModel({
           uid, // 注意： 新建的 model 应该使用 ${parentModel.uid}-xxx 形式的 uid
           use: 'PopupActionModel',
@@ -3714,7 +3770,7 @@ export class FlowModelContext extends BaseFlowModelContext {
             popupSettings: {
               openView: {
                 // 仅在创建时持久化一份默认配置；运行时以本次 opts 为准，避免多个 opener 互相覆盖。
-                ...pickDefined(opts, ['dataSourceKey', 'collectionName', 'associationName', 'mode', 'size']),
+                ...pickDefinedKeys(opts, ['dataSourceKey', 'collectionName', 'associationName', 'mode', 'size']),
               },
             },
           },
@@ -3734,8 +3790,6 @@ export class FlowModelContext extends BaseFlowModelContext {
       // 统一语义：为即将打开的外部视图定义一个 PendingView（占位视图）
       const pendingType = (opts?.isMobileLayout ? 'embed' : opts?.mode || 'drawer') as any;
       const pendingInputArgs = { ...opts, viewUid, navigation: opts.navigation };
-      pendingInputArgs.filterByTk = pendingInputArgs.filterByTk || this.inputArgs?.filterByTk;
-      pendingInputArgs.sourceId = pendingInputArgs.sourceId || this.inputArgs?.sourceId;
 
       const pendingView = {
         type: pendingType,
@@ -3754,17 +3808,10 @@ export class FlowModelContext extends BaseFlowModelContext {
       } else if (on && typeof on === 'object' && typeof (on as any).eventName === 'string' && (on as any).eventName) {
         openEventName = (on as any).eventName;
       }
-      await model.dispatchEvent(
-        openEventName,
-        {
-          // navigation: false, // TODO: 路由模式有bug，不支持多层同样viewId的弹窗，因此这里默认先用false
-          // ...this.model?.['getInputArgs']?.(), // 避免部分关系字段信息丢失, 仿照 ClickableCollectionField 做法
-          ...opts,
-        },
-        {
-          debounce: true,
-        },
-      );
+      await model.dispatchEvent(openEventName, {
+        // navigation: false, // TODO: 路由模式有bug，不支持多层同样viewId的弹窗，因此这里默认先用false
+        ...opts,
+      });
     });
     this.defineMethod('getEvents', function (this: BaseFlowModelContext) {
       return this.model.getEvents();
@@ -4558,6 +4605,27 @@ export class FlowRunJSContext extends FlowContext {
     this.defineProperty('ReactDOM', { value: ReactDOMShim });
 
     setupRunJSLibs(this);
+    this.defineMethod('openView', async function (uid: string, options?: Record<PropertyKey, unknown>) {
+      const delegateOpenView = (
+        delegate as FlowContext & {
+          openView?: (uid: string, options?: Record<PropertyKey, unknown>) => Promise<unknown>;
+        }
+      ).openView;
+
+      if (typeof delegateOpenView !== 'function') {
+        throw new Error('ctx.openView is not available in current context.');
+      }
+
+      const routeState = createOpenViewRouteState(options);
+      if (!routeState) {
+        return delegateOpenView(uid, options);
+      }
+
+      return delegateOpenView(uid, {
+        ...(options || {}),
+        [RUNJS_OPEN_VIEW_ROUTE_STATE]: routeState,
+      });
+    });
 
     // Convenience: ctx.render(<App />[, container])
     // - container defaults to ctx.element if available

package/src/flowEngine.ts

@@ -1343,6 +1343,9 @@ export class FlowEngine {
     if (!this.ensureModelRepository()) return;
     const refresh = !!options?.refresh;
     const bypassLoadedPageCache = this._loadedPageCache.shouldBypass(options, () => this.context.flowSettingsEnabled);
+    if (this.context.flowSettingsEnabled) {
+      this._loadedPageCache.markDirtyForOptions(options);
+    }
     if (!refresh && !bypassLoadedPageCache) {
       const model = this.findModelByParentId(options.parentId, options.subKey);
       if (model) {
@@ -1412,6 +1415,9 @@ export class FlowEngine {
     if (!this.ensureModelRepository()) return;
     const { uid, parentId, subKey } = options;
     const bypassLoadedPageCache = this._loadedPageCache.shouldBypass(options, () => this.context.flowSettingsEnabled);
+    if (this.context.flowSettingsEnabled) {
+      this._loadedPageCache.markDirtyForOptions(options);
+    }
     if (uid && !bypassLoadedPageCache && this._modelInstances.has(uid)) {
       return this._modelInstances.get(uid) as T;
     }