@nocobase/flow-engine 2.0.0-beta.8 → 2.0.0

package/src/__tests__/flowEngine.dataSourceDirty.test.ts

@@ -0,0 +1,63 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { FlowEngine } from '../flowEngine';
+import { MultiRecordResource } from '../resources/multiRecordResource';
+import { SingleRecordResource } from '../resources/singleRecordResource';
+
+describe('FlowEngine dataSource dirty registry', () => {
+  it('tracks versions per dataSourceKey + resourceName', () => {
+    const engine = new FlowEngine();
+
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+    expect(engine.markDataSourceDirty('main', 'posts')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+
+    expect(engine.markDataSourceDirty('main', 'posts')).toBe(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(2);
+
+    // different resource
+    expect(engine.getDataSourceDirtyVersion('main', 'users')).toBe(0);
+    expect(engine.markDataSourceDirty('main', 'users')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'users')).toBe(1);
+
+    // different data source
+    expect(engine.getDataSourceDirtyVersion('ds2', 'posts')).toBe(0);
+    expect(engine.markDataSourceDirty('ds2', 'posts')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('ds2', 'posts')).toBe(1);
+    // main unchanged
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(2);
+  });
+
+  it('marks dirty on record write operations (single & multi)', async () => {
+    const engine = new FlowEngine();
+    const markSpy = vi.spyOn(engine, 'markDataSourceDirty');
+
+    const single = engine.createResource(SingleRecordResource);
+    single.setDataSourceKey('main');
+    single.setResourceName('posts');
+    // avoid network: stub runAction + refresh
+    (single as any).runAction = vi.fn().mockResolvedValue({ data: {}, meta: {} });
+    (single as any).refresh = vi.fn().mockResolvedValue(undefined);
+    await single.save({ title: 't' } as any, { refresh: false });
+    expect(markSpy).toHaveBeenCalledWith('main', 'posts');
+
+    const multi = engine.createResource(MultiRecordResource);
+    multi.setDataSourceKey('main');
+    multi.setResourceName('users.profile');
+    (multi as any).runAction = vi.fn().mockResolvedValue({ data: [], meta: {} });
+    (multi as any).refresh = vi.fn().mockResolvedValue(undefined);
+    await multi.create({ name: 'n' } as any, { refresh: false });
+    // exact association
+    expect(markSpy).toHaveBeenCalledWith('main', 'users.profile');
+    // plus root collection (safety)
+    expect(markSpy).toHaveBeenCalledWith('main', 'users');
+  });
+});

package/src/__tests__/flowModel.openView.navigation.test.ts

@@ -76,4 +76,32 @@ describe('FlowModelContext.openView - navigation enforcement', () => {
     const dispatchedParams = child.dispatchEvent.mock.calls[0][1];
     expect(dispatchedParams.navigation).toBe(false);
   });
+
+  it('dispatches the popupSettings bound event (object form) when opening external popup', async () => {
+    const { parent, child } = setup();
+
+    child.getFlow = vi.fn((key: string) => {
+      if (key !== 'popupSettings') return undefined;
+      return { on: { eventName: 'openDuplicatePopup' } };
+    });
+
+    await (parent.context as any).openView('child-uid', { mode: 'drawer' });
+
+    expect(child.dispatchEvent).toHaveBeenCalledTimes(1);
+    expect(child.dispatchEvent.mock.calls[0][0]).toBe('openDuplicatePopup');
+  });
+
+  it('falls back to click when popupSettings has no explicit on event', async () => {
+    const { parent, child } = setup();
+
+    child.getFlow = vi.fn((key: string) => {
+      if (key !== 'popupSettings') return undefined;
+      return { on: undefined };
+    });
+
+    await (parent.context as any).openView('child-uid', { mode: 'drawer' });
+
+    expect(child.dispatchEvent).toHaveBeenCalledTimes(1);
+    expect(child.dispatchEvent.mock.calls[0][0]).toBe('click');
+  });
 });

package/src/__tests__/flowRunJSContextDefine.test.ts

@@ -61,6 +61,69 @@ describe('FlowRunJSContext.define() and getDoc() deep tests', () => {
       expect(apiProp.properties?.auth?.description).toBe('Auth info');
     });
 
+    it('should treat string doc as description when overriding object docs', () => {
+      class BaseDocContext extends FlowRunJSContext {}
+      class ChildDocContext extends BaseDocContext {}
+
+      BaseDocContext.define({
+        properties: {
+          foo: {
+            description: 'Base foo',
+            detail: 'FooDetail',
+            hidden: true,
+            completion: { insertText: 'ctx.foo' },
+            properties: {
+              bar: { description: 'Bar desc' },
+            },
+          },
+        },
+      });
+
+      ChildDocContext.define({
+        properties: {
+          foo: 'Child foo',
+        },
+      });
+
+      const doc = ChildDocContext.getDoc();
+      const foo: any = doc.properties?.foo;
+      expect(foo).toBeTruthy();
+      expect(typeof foo).toBe('object');
+      expect(foo.description).toBe('Child foo');
+      expect(foo.hidden).toBe(true);
+      expect(foo.detail).toBe('FooDetail');
+      expect(foo.completion?.insertText).toBe('ctx.foo');
+      expect(foo.properties?.bar?.description).toBe('Bar desc');
+    });
+
+    it('should preserve base string description when patch adds object doc', () => {
+      class BaseStringDocContext extends FlowRunJSContext {}
+      class ChildObjectDocContext extends BaseStringDocContext {}
+
+      BaseStringDocContext.define({
+        properties: {
+          foo: 'Base foo',
+        },
+      });
+
+      ChildObjectDocContext.define({
+        properties: {
+          foo: {
+            properties: {
+              bar: 'Bar',
+            },
+          },
+        },
+      });
+
+      const doc = ChildObjectDocContext.getDoc();
+      const foo: any = doc.properties?.foo;
+      expect(foo).toBeTruthy();
+      expect(typeof foo).toBe('object');
+      expect(foo.description).toBe('Base foo');
+      expect(foo.properties?.bar).toBe('Bar');
+    });
+
     it('should deep merge method documentation', () => {
       class MethodMergeContext extends FlowRunJSContext {}
 

package/src/__tests__/flowRuntimeContext.test.ts

@@ -11,6 +11,7 @@ import { ContextPathProxy } from '../ContextPathProxy';
 import { FlowRuntimeContext } from '../flowContext';
 import { FlowEngine } from '../flowEngine';
 import { FlowModel } from '../models/flowModel';
+import { FlowExitAllException } from '../utils/exceptions';
 
 describe('FlowRuntimeContext', () => {
   let engine: FlowEngine;
@@ -46,7 +47,7 @@ describe('FlowRuntimeContext', () => {
 
   it('should throw on exit()', () => {
     const ctx = new FlowRuntimeContext(model, 'flow1', 'runtime');
-    expect(() => ctx.exit()).toThrow();
+    expect(() => ctx.exit()).toThrow(FlowExitAllException);
   });
 });
 

package/src/__tests__/flowSettings.open.test.tsx

@@ -12,6 +12,7 @@ import { screen } from '@testing-library/react';
 import { FlowSettings } from '../flowSettings';
 import { FlowModel } from '../models';
 import { FlowEngine } from '../flowEngine';
+import { GLOBAL_EMBED_CONTAINER_ID } from '../views';
 
 // We will stub viewer directly on model.context in tests
 
@@ -1087,18 +1088,18 @@ describe('FlowSettings.open rendering behavior', () => {
 
     // Create mock DOM element for embed target
     const mockTarget = document.createElement('div');
-    mockTarget.id = 'nocobase-embed-container';
+    mockTarget.id = GLOBAL_EMBED_CONTAINER_ID;
     mockTarget.style.width = 'auto';
     mockTarget.style.maxWidth = 'none';
     document.body.appendChild(mockTarget);
 
     // Mock querySelector to return our mock element
-    const originalQuerySelector = document.querySelector;
-    document.querySelector = vi.fn((selector) => {
-      if (selector === '#nocobase-embed-container') {
+    const originalQuerySelector = document.querySelector.bind(document);
+    const querySelectorSpy = vi.spyOn(document, 'querySelector').mockImplementation((selector: string) => {
+      if (selector === `#${GLOBAL_EMBED_CONTAINER_ID}`) {
         return mockTarget;
       }
-      return originalQuerySelector.call(document, selector);
+      return originalQuerySelector(selector);
     });
 
     const M = model.constructor as any;
@@ -1164,7 +1165,61 @@ describe('FlowSettings.open rendering behavior', () => {
 
     // Cleanup
     document.body.removeChild(mockTarget);
-    document.querySelector = originalQuerySelector;
+    querySelectorSpy.mockRestore();
+  });
+
+  it('does not clear embed target DOM before opening (avoids portal unmount errors)', async () => {
+    const engine = new FlowEngine();
+    const flowSettings = new FlowSettings(engine);
+    const model = new FlowModel({ uid: 'm-embed-no-clear', flowEngine: engine });
+
+    const mockTarget = document.createElement('div');
+    mockTarget.id = GLOBAL_EMBED_CONTAINER_ID;
+    mockTarget.innerHTML = '<div data-testid="existing">Existing</div>';
+    document.body.appendChild(mockTarget);
+
+    const originalQuerySelector = document.querySelector.bind(document);
+    const querySelectorSpy = vi.spyOn(document, 'querySelector').mockImplementation((selector: string) => {
+      if (selector === `#${GLOBAL_EMBED_CONTAINER_ID}`) {
+        return mockTarget;
+      }
+      return originalQuerySelector(selector);
+    });
+
+    const M = model.constructor as any;
+    M.registerFlow({
+      key: 'embedNoClearFlow',
+      steps: {
+        step: {
+          title: 'Step',
+          uiSchema: { f: { type: 'string', 'x-component': 'Input' } },
+        },
+      },
+    });
+
+    const embed = vi.fn((opts: any) => {
+      // The existing DOM should not be wiped out before opening the embed view.
+      expect(mockTarget.querySelector('[data-testid="existing"]')).toBeTruthy();
+      const dlg = { close: vi.fn(), Footer: (p: any) => null } as any;
+      if (typeof opts.content === 'function') opts.content(dlg, { defineMethod: vi.fn() });
+      return dlg;
+    });
+
+    model.context.defineProperty('viewer', { value: { embed } });
+    model.context.defineProperty('message', { value: { info: vi.fn(), error: vi.fn(), success: vi.fn() } });
+
+    await flowSettings.open({
+      model,
+      flowKey: 'embedNoClearFlow',
+      stepKey: 'step',
+      uiMode: 'embed',
+    } as any);
+
+    expect(embed).toHaveBeenCalledTimes(1);
+    expect(mockTarget.querySelector('[data-testid="existing"]')).toBeTruthy();
+
+    document.body.removeChild(mockTarget);
+    querySelectorSpy.mockRestore();
   });
 
   it('uses embed uiMode with default props when target element exists', async () => {
@@ -1174,16 +1229,16 @@ describe('FlowSettings.open rendering behavior', () => {
 
     // Create mock DOM element for embed target
     const mockTarget = document.createElement('div');
-    mockTarget.id = 'nocobase-embed-container';
+    mockTarget.id = GLOBAL_EMBED_CONTAINER_ID;
     document.body.appendChild(mockTarget);
 
     // Mock querySelector
-    const originalQuerySelector = document.querySelector;
-    document.querySelector = vi.fn((selector) => {
-      if (selector === '#nocobase-embed-container') {
+    const originalQuerySelector = document.querySelector.bind(document);
+    const querySelectorSpy = vi.spyOn(document, 'querySelector').mockImplementation((selector: string) => {
+      if (selector === `#${GLOBAL_EMBED_CONTAINER_ID}`) {
         return mockTarget;
       }
-      return originalQuerySelector.call(document, selector);
+      return originalQuerySelector(selector);
     });
 
     const M = model.constructor as any;
@@ -1223,7 +1278,7 @@ describe('FlowSettings.open rendering behavior', () => {
 
     // Cleanup
     document.body.removeChild(mockTarget);
-    document.querySelector = originalQuerySelector;
+    querySelectorSpy.mockRestore();
   });
 
   it('handles embed uiMode when target element is not found', async () => {
@@ -1232,8 +1287,7 @@ describe('FlowSettings.open rendering behavior', () => {
     const model = new FlowModel({ uid: 'm-embed-no-target', flowEngine: engine });
 
     // Mock querySelector to return null (target not found)
-    const originalQuerySelector = document.querySelector;
-    document.querySelector = vi.fn(() => null);
+    const querySelectorSpy = vi.spyOn(document, 'querySelector').mockReturnValue(null);
 
     const M = model.constructor as any;
     M.registerFlow({
@@ -1266,7 +1320,7 @@ describe('FlowSettings.open rendering behavior', () => {
     expect(embed).toHaveBeenCalledTimes(1);
 
     // Restore querySelector
-    document.querySelector = originalQuerySelector;
+    querySelectorSpy.mockRestore();
   });
 
   it('handles error in function-based step uiMode gracefully', async () => {
@@ -1718,8 +1772,8 @@ describe('FlowSettings.open rendering behavior', () => {
     expect(capturedDialog.close).toHaveBeenCalled();
   });
 
-  it('submit method handles FlowExitException by closing dialog without error message', async () => {
-    const { FlowExitException } = await import('../utils/exceptions');
+  it('submit method handles FlowExitAllException by closing dialog without error message', async () => {
+    const { FlowExitAllException } = await import('../utils/exceptions');
 
     const engine = new FlowEngine();
     const flowSettings = new FlowSettings(engine);
@@ -1732,7 +1786,7 @@ describe('FlowSettings.open rendering behavior', () => {
         step: {
           title: 'Step',
           beforeParamsSave: () => {
-            throw new FlowExitException('exitFlow', 'm-submit-exit', 'Exit requested');
+            throw new FlowExitAllException('exitFlow', 'm-submit-exit', 'Exit requested');
           },
           uiSchema: { field: { type: 'string', 'x-component': 'Input' } },
         },
@@ -1764,12 +1818,62 @@ describe('FlowSettings.open rendering behavior', () => {
     // Call submit method
     await capturedDialog.submit();
 
-    // Verify FlowExitException handling
+    // Verify FlowExitAllException handling
     expect(error).not.toHaveBeenCalled(); // Should not show error message
     expect(success).not.toHaveBeenCalled(); // Should not show success message
     expect(capturedDialog.close).toHaveBeenCalled(); // Should close dialog
   });
 
+  it('submit method keeps dialog open on FlowCancelSaveException', async () => {
+    const { FlowCancelSaveException } = await import('../utils/exceptions');
+
+    const engine = new FlowEngine();
+    const flowSettings = new FlowSettings(engine);
+    const TestFlowModel = createIsolatedFlowModel('test-submit-cancel-save');
+    const model = new TestFlowModel({ uid: 'm-submit-cancel-save', flowEngine: engine });
+
+    TestFlowModel.registerFlow({
+      key: 'cancelSaveFlow',
+      steps: {
+        step: {
+          title: 'Step',
+          beforeParamsSave: () => {
+            throw new FlowCancelSaveException();
+          },
+          uiSchema: { field: { type: 'string', 'x-component': 'Input' } },
+        },
+      },
+    });
+
+    const info = vi.fn();
+    const error = vi.fn();
+    const success = vi.fn();
+    model.context.defineProperty('message', { value: { info, error, success } });
+
+    const saveStepParams = vi.spyOn(model as any, 'saveStepParams').mockResolvedValue(undefined);
+
+    let capturedDialog: any;
+    model.context.defineProperty('viewer', {
+      value: {
+        dialog: ({ content }) => {
+          capturedDialog = { close: vi.fn(), Footer: (p: any) => null };
+          if (typeof content === 'function') {
+            content(capturedDialog, { defineMethod: vi.fn() });
+          }
+          return capturedDialog;
+        },
+      },
+    });
+
+    await flowSettings.open({ model, flowKey: 'cancelSaveFlow', stepKey: 'step' } as any);
+    await capturedDialog.submit();
+
+    expect(capturedDialog.close).not.toHaveBeenCalled();
+    expect(saveStepParams).not.toHaveBeenCalled();
+    expect(error).not.toHaveBeenCalled();
+    expect(success).not.toHaveBeenCalled();
+  });
+
   it('submit method handles general errors by showing error message and keeping dialog open', async () => {
     const engine = new FlowEngine();
     const flowSettings = new FlowSettings(engine);

package/src/__tests__/runjsContext.test.ts

@@ -7,17 +7,17 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, it, expect, beforeAll } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 import {
   RunJSContextRegistry,
-  getRunJSDocFor,
   createJSRunnerWithVersion,
-  getRunJSScenesForModel,
+  getRunJSDocFor,
   getRunJSScenesForContext,
+  getRunJSScenesForModel,
 } from '..';
-import { setupRunJSContexts } from '../runjs-context/setup';
 import { FlowContext } from '../flowContext';
 import { JSRunner } from '../JSRunner';
+import { setupRunJSContexts } from '../runjs-context/setup';
 
 describe('flowRunJSContext registry and doc', () => {
   beforeAll(async () => {
@@ -80,7 +80,10 @@ describe('flowRunJSContext registry and doc', () => {
       (ctx as any).defineProperty('model', { value: { constructor: { name: 'JSFieldModel' } } });
       (ctx as any).defineProperty('api', { value: { auth: { locale: 'zh-CN' } } });
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
-      expect(doc?.properties?.message).toMatch(/Ant Design 全局消息/);
+      const message = doc?.properties?.message;
+      const messageText =
+        typeof message === 'string' ? message : (message as any)?.description ?? (message as any)?.detail ?? '';
+      expect(String(messageText)).toMatch(/Ant Design 全局消息/);
     });
 
     it('should fallback to English when locale is not found', () => {
@@ -208,10 +211,10 @@ describe('flowRunJSContext registry and doc', () => {
       expect(doc?.properties?.message).toBeTruthy();
     });
 
-    it('should have api property in base context', () => {
+    it('should have request method in base context', () => {
       const ctx: any = { model: { constructor: { name: '*' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
-      expect(doc?.properties?.api).toBeTruthy();
+      expect(doc?.methods?.request).toBeTruthy();
     });
 
     it('should have t method in base context', () => {

package/src/__tests__/runjsContextImplementations.test.ts

@@ -7,10 +7,10 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, it, expect, beforeAll } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 import { RunJSContextRegistry, getRunJSDocFor } from '..';
-import { setupRunJSContexts } from '../runjs-context/setup';
 import { FlowContext } from '../flowContext';
+import { setupRunJSContexts } from '../runjs-context/setup';
 
 describe('Specific RunJSContext implementations', () => {
   beforeAll(async () => {
@@ -34,7 +34,8 @@ describe('Specific RunJSContext implementations', () => {
       const ctx: any = { model: { constructor: { name: 'JSColumnModel' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
       expect(doc?.properties?.record).toBeTruthy();
-      expect(doc?.properties?.record).toContain('row record');
+      const recordDoc: any = doc?.properties?.record;
+      expect(String(recordDoc?.description ?? recordDoc ?? '')).toContain('row record');
     });
 
     it('should have recordIndex property in doc', () => {
@@ -86,6 +87,14 @@ describe('Specific RunJSContext implementations', () => {
       expect(doc?.properties?.antd).toBeTruthy();
     });
 
+    it('should have ctx.auth.locale / ctx.viewer.drawer in doc', () => {
+      const ctx: any = { model: { constructor: { name: 'JSBlockModel' } } };
+      const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+
+      expect(doc?.properties?.auth?.properties?.locale).toBeTruthy();
+      expect(doc?.properties?.viewer?.properties?.drawer).toBeTruthy();
+    });
+
     it('should have element property', () => {
       const ctx: any = { model: { constructor: { name: 'JSBlockModel' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
@@ -214,4 +223,26 @@ describe('Specific RunJSContext implementations', () => {
       expect(doc?.label).toMatch(/表单 JS 字段项/);
     });
   });
+
+  describe('JSEditableFieldRunJSContext', () => {
+    it('should be registered for JSEditableFieldModel', () => {
+      const ctor = RunJSContextRegistry['resolve']('v1' as any, 'JSEditableFieldModel');
+      expect(ctor).toBeTruthy();
+    });
+
+    it('should have getValue/setValue methods in doc', () => {
+      const ctx: any = { model: { constructor: { name: 'JSEditableFieldModel' } } };
+      const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+      expect(doc?.methods?.getValue).toBeTruthy();
+      expect(doc?.methods?.setValue).toBeTruthy();
+    });
+
+    it('should support zh-CN locale', () => {
+      const ctx = new FlowContext();
+      (ctx as any).defineProperty('model', { value: { constructor: { name: 'JSEditableFieldModel' } } });
+      (ctx as any).defineProperty('api', { value: { auth: { locale: 'zh-CN' } } });
+      const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+      expect(doc?.label).toMatch(/可编辑字段/);
+    });
+  });
 });

package/src/__tests__/runjsContextRuntime.test.ts

@@ -7,9 +7,9 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, it, expect, beforeAll } from 'vitest';
-import { FlowContext } from '../flowContext';
+import { beforeAll, describe, expect, it } from 'vitest';
 import { createJSRunnerWithVersion, getRunJSDocFor } from '..';
+import { FlowContext } from '../flowContext';
 import { setupRunJSContexts } from '../runjs-context/setup';
 
 describe('RunJS Context Runtime Behavior', () => {
@@ -224,7 +224,7 @@ describe('RunJS Context Runtime Behavior', () => {
         // Base properties from FlowRunJSContext
         expect(doc?.properties?.logger).toBeTruthy();
         expect(doc?.properties?.message).toBeTruthy();
-        expect(doc?.properties?.api).toBeTruthy();
+        expect(doc?.methods?.request).toBeTruthy();
         expect(doc?.methods?.t).toBeTruthy();
         expect(doc?.methods?.requireAsync).toBeTruthy();
       }

package/src/__tests__/runjsContributions.test.ts

@@ -0,0 +1,89 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+describe('RunJS context contributions', () => {
+  it('should apply contribution during setupRunJSContexts()', async () => {
+    vi.resetModules();
+    const mod: any = await import('..');
+    const {
+      registerRunJSContextContribution,
+      setupRunJSContexts,
+      RunJSContextRegistry,
+      getRunJSDocFor,
+      FlowRunJSContext,
+    } = mod;
+
+    registerRunJSContextContribution(({ version, RunJSContextRegistry: Registry, FlowRunJSContext: BaseCtx }: any) => {
+      if (version !== 'v1') return;
+      class PluginTestRunJSContext extends BaseCtx {}
+      PluginTestRunJSContext.define({
+        properties: {
+          plugin: { description: 'plugin namespace', detail: 'object' },
+        },
+      });
+      Registry.register('v1', 'PluginTestModel', PluginTestRunJSContext, { scenes: ['block'] });
+    });
+
+    await setupRunJSContexts();
+
+    const ctor = RunJSContextRegistry.resolve('v1', 'PluginTestModel');
+    expect(ctor).toBeTruthy();
+    expect((ctor as any).name).toBe('PluginTestRunJSContext');
+
+    const ctx: any = { model: { constructor: { name: 'PluginTestModel' } } };
+    const doc = getRunJSDocFor(ctx, { version: 'v1' });
+    expect(doc?.properties?.plugin).toBeTruthy();
+
+    // Ensure FlowRunJSContext stays usable
+    expect(typeof FlowRunJSContext.getDoc).toBe('function');
+  });
+
+  it('should apply late contribution immediately after setup', async () => {
+    vi.resetModules();
+    const mod: any = await import('..');
+    const { registerRunJSContextContribution, setupRunJSContexts, getRunJSDocFor, FlowContext } = mod;
+
+    await setupRunJSContexts();
+
+    registerRunJSContextContribution(({ version, FlowRunJSContext }: any) => {
+      if (version !== 'v1') return;
+      FlowRunJSContext.define({
+        properties: {
+          pluginLate: { description: 'late-added', detail: 'string' },
+        },
+      });
+    });
+
+    const ctx = new FlowContext();
+    const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+    expect(doc?.properties?.pluginLate).toBeTruthy();
+  });
+
+  it('should run each contribution at most once per version', async () => {
+    vi.resetModules();
+    const mod: any = await import('..');
+    const { registerRunJSContextContribution, setupRunJSContexts } = mod;
+
+    let count = 0;
+    const fn = ({ version }: any) => {
+      if (version !== 'v1') return;
+      count += 1;
+    };
+
+    registerRunJSContextContribution(fn);
+    registerRunJSContextContribution(fn); // duplicate registration should be ignored
+
+    await setupRunJSContexts();
+    await setupRunJSContexts();
+
+    expect(count).toBe(1);
+  });
+});