@openvcs/sdk 0.2.12 → 0.2.14

package/lib/runtime/index.d.ts

@@ -5,6 +5,7 @@ export { createDefaultPluginDelegates, createRuntimeDispatcher } from './dispatc
 export { isPluginFailure, pluginError } from './errors';
 export { createPluginRuntime } from './factory';
 export { createHost } from './host';
+export { ModalBuilder } from './modal';
 export { bootstrapPluginModule, createRegisteredPluginRuntime, } from './registration';
 export { VcsDelegateBase } from './vcs-delegate-base';
 export type { VcsDelegateAssignments } from './vcs-delegate-metadata';

package/lib/runtime/index.js

@@ -2,7 +2,7 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.notify = exports.invoke = exports.registerAction = exports.showMenu = exports.hideMenu = exports.removeMenu = exports.addMenuSeparator = exports.addMenuItem = exports.createMenu = exports.getOrCreateMenu = exports.getMenu = exports.VcsDelegateBase = exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
+exports.notify = exports.invoke = exports.registerAction = exports.showMenu = exports.hideMenu = exports.removeMenu = exports.addMenuSeparator = exports.addMenuItem = exports.createMenu = exports.getOrCreateMenu = exports.getMenu = exports.VcsDelegateBase = exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.ModalBuilder = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
 exports.startPluginRuntime = startPluginRuntime;
 var dispatcher_1 = require("./dispatcher");
 Object.defineProperty(exports, "createDefaultPluginDelegates", { enumerable: true, get: function () { return dispatcher_1.createDefaultPluginDelegates; } });
@@ -14,6 +14,8 @@ var factory_1 = require("./factory");
 Object.defineProperty(exports, "createPluginRuntime", { enumerable: true, get: function () { return factory_1.createPluginRuntime; } });
 var host_1 = require("./host");
 Object.defineProperty(exports, "createHost", { enumerable: true, get: function () { return host_1.createHost; } });
+var modal_1 = require("./modal");
+Object.defineProperty(exports, "ModalBuilder", { enumerable: true, get: function () { return modal_1.ModalBuilder; } });
 var registration_1 = require("./registration");
 Object.defineProperty(exports, "bootstrapPluginModule", { enumerable: true, get: function () { return registration_1.bootstrapPluginModule; } });
 Object.defineProperty(exports, "createRegisteredPluginRuntime", { enumerable: true, get: function () { return registration_1.createRegisteredPluginRuntime; } });

package/lib/runtime/menu.d.ts

@@ -6,7 +6,7 @@ type MenubarMenuOptions = {
     after?: string;
 };
 /** Runs a registered action handler by id. */
-export declare function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<boolean>;
+export declare function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<unknown>;
 export interface MenuHandle {
     id: string;
     addItem(item: MenubarItem): void;

package/lib/runtime/menu.js

@@ -159,12 +159,11 @@ function serializeMenus() {
 async function runRegisteredAction(actionId, ...args) {
     const id = String(actionId || '').trim();
     if (!id)
-        return false;
+        return null;
     const handler = actionHandlers.get(id);
     if (!handler)
-        return false;
-    await handler(...args);
-    return true;
+        return null;
+    return await handler(...args);
 }
 /** Creates a stable handle for one stored menu. */
 function createMenuHandle(menuId) {
@@ -291,7 +290,7 @@ function createMenuPluginDelegates() {
         async 'plugin.handle_action'(params) {
             const actionId = String(params?.action_id || '').trim();
             if (actionId) {
-                await runRegisteredAction(actionId);
+                return await runRegisteredAction(actionId, params?.payload);
             }
             return null;
         },

package/lib/runtime/modal.d.ts

@@ -0,0 +1,74 @@
+import type { ModalButtonVariant, ModalContentAlign, ModalInputKind, ModalListRowDefinition, ModalSelectOptionDefinition, PluginModalDefinition } from '../types/modal.js';
+/** Describes the options accepted by `ModalBuilder.button()`. */
+export interface ModalBuilderButtonOptions {
+    /** Stores the optional tooltip text. */
+    title?: string;
+    /** Stores the visual button variant. */
+    variant?: ModalButtonVariant;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+    /** Stores a static payload merged into the action payload. */
+    payload?: Record<string, unknown>;
+}
+/** Describes the options accepted by `ModalBuilder.text()`. */
+export interface ModalBuilderTextOptions {
+    /** Stores the optional tooltip text. */
+    title?: string;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+}
+/** Describes the options accepted by `ModalBuilder.input()`. */
+export interface ModalBuilderInputOptions {
+    /** Stores the input kind. */
+    kind?: ModalInputKind;
+    /** Stores the default value. */
+    value?: string;
+    /** Stores the placeholder text. */
+    placeholder?: string;
+    /** Stores whether the field is required. */
+    required?: boolean;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+}
+/** Describes the options accepted by `ModalBuilder.select()`. */
+export interface ModalBuilderSelectOptions {
+    /** Stores the available options. */
+    options: ModalSelectOptionDefinition[];
+    /** Stores the default value. */
+    value?: string;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+}
+/** Describes the options accepted by `ModalBuilder.list()`. */
+export interface ModalBuilderListOptions {
+    /** Stores the list label. */
+    label?: string;
+    /** Stores the empty-state text. */
+    emptyText?: string;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+    /** Stores the list rows. */
+    items: ModalListRowDefinition[];
+}
+/** Builds a structured modal definition with a fluent class API. */
+export declare class ModalBuilder {
+    private readonly definition;
+    /** Creates a new modal builder with the provided title. */
+    constructor(title: string);
+    /** Adds a text block to the modal body. */
+    text(content: string, options?: ModalBuilderTextOptions): this;
+    /** Adds a separator to the modal body. */
+    separator(): this;
+    /** Adds a button to the modal body. */
+    button(id: string, content: string, options?: ModalBuilderButtonOptions): this;
+    /** Adds a text input to the modal body. */
+    input(id: string, label: string, options?: ModalBuilderInputOptions): this;
+    /** Adds a select field to the modal body. */
+    select(id: string, label: string, options: ModalBuilderSelectOptions): this;
+    /** Adds a list block to the modal body. */
+    list(id: string, options: ModalBuilderListOptions): this;
+    /** Returns the serialized modal payload. */
+    build(): PluginModalDefinition;
+    /** Returns the serialized modal payload for a host request. */
+    open(): Promise<PluginModalDefinition>;
+}

package/lib/runtime/modal.js

@@ -0,0 +1,94 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModalBuilder = void 0;
+/** Builds a structured modal definition with a fluent class API. */
+class ModalBuilder {
+    definition;
+    /** Creates a new modal builder with the provided title. */
+    constructor(title) {
+        this.definition = {
+            title: String(title || '').trim(),
+            content: [],
+        };
+    }
+    /** Adds a text block to the modal body. */
+    text(content, options = {}) {
+        this.definition.content.push({
+            type: 'text',
+            content: String(content || ''),
+            ...(options.title ? { title: options.title } : {}),
+            ...(options.align ? { align: options.align } : {}),
+        });
+        return this;
+    }
+    /** Adds a separator to the modal body. */
+    separator() {
+        this.definition.content.push({ type: 'separator' });
+        return this;
+    }
+    /** Adds a button to the modal body. */
+    button(id, content, options = {}) {
+        this.definition.content.push({
+            type: 'button',
+            id: String(id || '').trim(),
+            content: String(content || ''),
+            ...(options.title ? { title: options.title } : {}),
+            ...(options.variant && options.variant !== 'default' ? { variant: options.variant } : {}),
+            ...(options.align ? { align: options.align } : {}),
+            ...(options.payload ? { payload: options.payload } : {}),
+        });
+        return this;
+    }
+    /** Adds a text input to the modal body. */
+    input(id, label, options = {}) {
+        this.definition.content.push({
+            type: 'input',
+            id: String(id || '').trim(),
+            label: String(label || '').trim(),
+            ...(options.kind ? { kind: options.kind } : {}),
+            ...(options.value !== undefined ? { value: options.value } : {}),
+            ...(options.placeholder ? { placeholder: options.placeholder } : {}),
+            ...(options.required ? { required: true } : {}),
+            ...(options.align ? { align: options.align } : {}),
+        });
+        return this;
+    }
+    /** Adds a select field to the modal body. */
+    select(id, label, options) {
+        this.definition.content.push({
+            type: 'select',
+            id: String(id || '').trim(),
+            label: String(label || '').trim(),
+            options: Array.isArray(options.options) ? options.options : [],
+            ...(options.value !== undefined ? { value: options.value } : {}),
+            ...(options.align ? { align: options.align } : {}),
+        });
+        return this;
+    }
+    /** Adds a list block to the modal body. */
+    list(id, options) {
+        this.definition.content.push({
+            type: 'list',
+            id: String(id || '').trim(),
+            ...(options.label ? { label: options.label } : {}),
+            ...(options.emptyText ? { emptyText: options.emptyText } : {}),
+            ...(options.align ? { align: options.align } : {}),
+            items: Array.isArray(options.items) ? options.items : [],
+        });
+        return this;
+    }
+    /** Returns the serialized modal payload. */
+    build() {
+        return {
+            title: this.definition.title,
+            content: this.definition.content.map((item) => ({ ...item })),
+        };
+    }
+    /** Returns the serialized modal payload for a host request. */
+    async open() {
+        return this.build();
+    }
+}
+exports.ModalBuilder = ModalBuilder;

package/lib/runtime/registration.js

@@ -27,8 +27,11 @@ function createRegisteredPluginRuntime(definition = {}) {
             },
             'plugin.handle_action': async (params, ctx) => {
                 const actionId = String(params?.action_id || '').trim();
-                if (actionId && (await (0, menu_1.runRegisteredAction)(actionId))) {
-                    return null;
+                if (actionId) {
+                    const result = await (0, menu_1.runRegisteredAction)(actionId, params?.payload);
+                    if (result !== null && result !== undefined) {
+                        return result;
+                    }
                 }
                 if (explicitHandleAction) {
                     return explicitHandleAction(params, ctx);

package/lib/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './host';
+export * from './modal';
 export * from './menubar';
 export * from './plugin';
 export * from './protocol';

package/lib/types/index.js

@@ -17,6 +17,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./host"), exports);
+__exportStar(require("./modal"), exports);
 __exportStar(require("./menubar"), exports);
 __exportStar(require("./plugin"), exports);
 __exportStar(require("./protocol"), exports);

package/lib/types/modal.d.ts

@@ -0,0 +1,129 @@
+/** Describes horizontal alignment hints for modal content. */
+export type ModalContentAlign = 'left' | 'centered' | 'right';
+/** Describes visual emphasis for modal buttons. */
+export type ModalButtonVariant = 'default' | 'primary' | 'danger';
+/** Describes the text input kinds supported by plugin modals. */
+export type ModalInputKind = 'text' | 'search' | 'password' | 'url' | 'number';
+/** Describes one button option rendered inside a modal. */
+export interface ModalButtonDefinition {
+    /** Stores the action id triggered when the button is pressed. */
+    id: string;
+    /** Stores the button label. */
+    content: string;
+    /** Stores the optional tooltip text. */
+    title?: string;
+    /** Stores the visual button variant. */
+    variant?: ModalButtonVariant;
+    /** Stores the button alignment hint. */
+    align?: ModalContentAlign;
+    /** Stores a static payload merged into the action payload. */
+    payload?: Record<string, unknown>;
+}
+/** Describes one text block rendered inside a modal. */
+export interface ModalTextDefinition {
+    /** Always stores `text`. */
+    type: 'text';
+    /** Stores the block text. */
+    content: string;
+    /** Stores an optional tooltip. */
+    title?: string;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+}
+/** Describes one separator rendered inside a modal. */
+export interface ModalSeparatorDefinition {
+    /** Always stores `separator`. */
+    type: 'separator';
+}
+/** Describes one button rendered inside a modal body. */
+export interface ModalButtonItemDefinition extends ModalButtonDefinition {
+    /** Always stores `button`. */
+    type: 'button';
+}
+/** Describes one text input rendered inside a modal. */
+export interface ModalInputDefinition {
+    /** Always stores `input`. */
+    type: 'input';
+    /** Stores the input field id. */
+    id: string;
+    /** Stores the label text. */
+    label: string;
+    /** Stores the input kind. */
+    kind?: ModalInputKind;
+    /** Stores the default value. */
+    value?: string;
+    /** Stores the placeholder text. */
+    placeholder?: string;
+    /** Stores whether the field is required. */
+    required?: boolean;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+}
+/** Describes one select option rendered inside a modal. */
+export interface ModalSelectOptionDefinition {
+    /** Stores the option label. */
+    label: string;
+    /** Stores the option value. */
+    value: string;
+    /** Stores whether the option is selected by default. */
+    selected?: boolean;
+}
+/** Describes one select field rendered inside a modal. */
+export interface ModalSelectDefinition {
+    /** Always stores `select`. */
+    type: 'select';
+    /** Stores the field id. */
+    id: string;
+    /** Stores the label text. */
+    label: string;
+    /** Stores the available options. */
+    options: ModalSelectOptionDefinition[];
+    /** Stores the default value. */
+    value?: string;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+}
+/** Describes one row-level action rendered in a list item. */
+export interface ModalListActionDefinition extends ModalButtonDefinition {
+    /** Always stores `button`. */
+    type: 'button';
+}
+/** Describes one list row rendered inside a modal list. */
+export interface ModalListRowDefinition {
+    /** Stores the row id. */
+    id: string;
+    /** Stores the row title. */
+    title: string;
+    /** Stores a short status label. */
+    status?: string;
+    /** Stores a secondary metadata label. */
+    meta?: string;
+    /** Stores longer descriptive text. */
+    description?: string;
+    /** Stores the row actions. */
+    actions?: ModalListActionDefinition[];
+}
+/** Describes one list block rendered inside a modal. */
+export interface ModalListDefinition {
+    /** Always stores `list`. */
+    type: 'list';
+    /** Stores the list id. */
+    id: string;
+    /** Stores the list label. */
+    label?: string;
+    /** Stores the empty-state text. */
+    emptyText?: string;
+    /** Stores the alignment hint. */
+    align?: ModalContentAlign;
+    /** Stores the list rows. */
+    items: ModalListRowDefinition[];
+}
+/** Describes one plugin modal content item. */
+export type PluginModalContentItem = ModalTextDefinition | ModalSeparatorDefinition | ModalButtonItemDefinition | ModalInputDefinition | ModalSelectDefinition | ModalListDefinition;
+/** Describes the structured payload used to render a plugin modal. */
+export interface PluginModalDefinition {
+    /** Stores the modal title. */
+    title: string;
+    /** Stores the ordered list of modal content items. */
+    content: PluginModalContentItem[];
+}

package/lib/types/modal.js

@@ -0,0 +1,4 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/plugin.d.ts

@@ -23,6 +23,8 @@ export type PluginSettingsValue = Record<string, unknown>;
 export interface PluginHandleActionParams extends RequestParams {
     /** Stores the action id selected by the user. */
     action_id?: string;
+    /** Stores an optional payload supplied by the triggering UI. */
+    payload?: Record<string, unknown>;
 }
 /** Describes the params shape for plugin settings callbacks. */
 export interface PluginSettingsValuesParams extends RequestParams {
@@ -42,7 +44,7 @@ export interface PluginDelegates<TContext = unknown> {
     /** Returns plugin-contributed menus. */
     'plugin.get_menus'?: RpcMethodHandler<RequestParams, PluginMenuDefinition[], TContext>;
     /** Handles a contributed plugin action. */
-    'plugin.handle_action'?: RpcMethodHandler<PluginHandleActionParams, null, TContext>;
+    'plugin.handle_action'?: RpcMethodHandler<PluginHandleActionParams, unknown, TContext>;
     /** Returns the default settings values for the plugin. */
     'plugin.settings.defaults'?: RpcMethodHandler<RequestParams, PluginSettingsValue[], TContext>;
     /** Transforms settings values when they are loaded. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "OpenVCS SDK CLI for plugin scaffolding and .ovcsp tar.gz packaging",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",

package/src/lib/runtime/dispatcher.ts

@@ -48,7 +48,7 @@ export function createDefaultPluginDelegates<
     async 'plugin.get_menus'(): Promise<[]> {
       return [];
     },
-    async 'plugin.handle_action'(): Promise<null> {
+    async 'plugin.handle_action'(): Promise<unknown> {
       return null;
     },
     async 'plugin.settings.defaults'(): Promise<[]> {

package/src/lib/runtime/index.ts

@@ -22,6 +22,7 @@ export { createDefaultPluginDelegates, createRuntimeDispatcher } from './dispatc
 export { isPluginFailure, pluginError } from './errors';
 export { createPluginRuntime } from './factory';
 export { createHost } from './host';
+export { ModalBuilder } from './modal';
 export {
   bootstrapPluginModule,
   createRegisteredPluginRuntime,

package/src/lib/runtime/menu.ts

@@ -216,15 +216,14 @@ function serializeMenus(): SerializedMenuDefinition[] {
 }
 
 /** Runs a registered action handler by id. */
-export async function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<boolean> {
+export async function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<unknown> {
   const id = String(actionId || '').trim();
-  if (!id) return false;
+  if (!id) return null;
 
   const handler = actionHandlers.get(id);
-  if (!handler) return false;
+  if (!handler) return null;
 
-  await handler(...args);
-  return true;
+  return await handler(...args);
 }
 
 export interface MenuHandle {
@@ -362,10 +361,10 @@ export function createMenuPluginDelegates(): PluginDelegates<PluginRuntimeContex
     async 'plugin.get_menus'(): Promise<PluginMenuDefinition[]> {
       return serializeMenus() as unknown as PluginMenuDefinition[];
     },
-    async 'plugin.handle_action'(params: PluginHandleActionParams): Promise<null> {
+    async 'plugin.handle_action'(params: PluginHandleActionParams): Promise<unknown> {
       const actionId = String(params?.action_id || '').trim();
       if (actionId) {
-        await runRegisteredAction(actionId);
+        return await runRegisteredAction(actionId, params?.payload);
       }
       return null;
     },

package/src/lib/runtime/modal.ts

@@ -0,0 +1,170 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  ModalButtonDefinition,
+  ModalButtonVariant,
+  ModalContentAlign,
+  ModalInputDefinition,
+  ModalInputKind,
+  ModalListDefinition,
+  ModalListRowDefinition,
+  ModalSelectDefinition,
+  ModalSelectOptionDefinition,
+  PluginModalContentItem,
+  PluginModalDefinition,
+} from '../types/modal.js';
+
+/** Describes the options accepted by `ModalBuilder.button()`. */
+export interface ModalBuilderButtonOptions {
+  /** Stores the optional tooltip text. */
+  title?: string;
+  /** Stores the visual button variant. */
+  variant?: ModalButtonVariant;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+  /** Stores a static payload merged into the action payload. */
+  payload?: Record<string, unknown>;
+}
+
+/** Describes the options accepted by `ModalBuilder.text()`. */
+export interface ModalBuilderTextOptions {
+  /** Stores the optional tooltip text. */
+  title?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes the options accepted by `ModalBuilder.input()`. */
+export interface ModalBuilderInputOptions {
+  /** Stores the input kind. */
+  kind?: ModalInputKind;
+  /** Stores the default value. */
+  value?: string;
+  /** Stores the placeholder text. */
+  placeholder?: string;
+  /** Stores whether the field is required. */
+  required?: boolean;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes the options accepted by `ModalBuilder.select()`. */
+export interface ModalBuilderSelectOptions {
+  /** Stores the available options. */
+  options: ModalSelectOptionDefinition[];
+  /** Stores the default value. */
+  value?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes the options accepted by `ModalBuilder.list()`. */
+export interface ModalBuilderListOptions {
+  /** Stores the list label. */
+  label?: string;
+  /** Stores the empty-state text. */
+  emptyText?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+  /** Stores the list rows. */
+  items: ModalListRowDefinition[];
+}
+
+/** Builds a structured modal definition with a fluent class API. */
+export class ModalBuilder {
+  private readonly definition: PluginModalDefinition;
+
+  /** Creates a new modal builder with the provided title. */
+  constructor(title: string) {
+    this.definition = {
+      title: String(title || '').trim(),
+      content: [],
+    };
+  }
+
+  /** Adds a text block to the modal body. */
+  text(content: string, options: ModalBuilderTextOptions = {}): this {
+    this.definition.content.push({
+      type: 'text',
+      content: String(content || ''),
+      ...(options.title ? { title: options.title } : {}),
+      ...(options.align ? { align: options.align } : {}),
+    });
+    return this;
+  }
+
+  /** Adds a separator to the modal body. */
+  separator(): this {
+    this.definition.content.push({ type: 'separator' });
+    return this;
+  }
+
+  /** Adds a button to the modal body. */
+  button(id: string, content: string, options: ModalBuilderButtonOptions = {}): this {
+    this.definition.content.push({
+      type: 'button',
+      id: String(id || '').trim(),
+      content: String(content || ''),
+      ...(options.title ? { title: options.title } : {}),
+      ...(options.variant && options.variant !== 'default' ? { variant: options.variant } : {}),
+      ...(options.align ? { align: options.align } : {}),
+      ...(options.payload ? { payload: options.payload } : {}),
+    });
+    return this;
+  }
+
+  /** Adds a text input to the modal body. */
+  input(id: string, label: string, options: ModalBuilderInputOptions = {}): this {
+    this.definition.content.push({
+      type: 'input',
+      id: String(id || '').trim(),
+      label: String(label || '').trim(),
+      ...(options.kind ? { kind: options.kind } : {}),
+      ...(options.value !== undefined ? { value: options.value } : {}),
+      ...(options.placeholder ? { placeholder: options.placeholder } : {}),
+      ...(options.required ? { required: true } : {}),
+      ...(options.align ? { align: options.align } : {}),
+    });
+    return this;
+  }
+
+  /** Adds a select field to the modal body. */
+  select(id: string, label: string, options: ModalBuilderSelectOptions): this {
+    this.definition.content.push({
+      type: 'select',
+      id: String(id || '').trim(),
+      label: String(label || '').trim(),
+      options: Array.isArray(options.options) ? options.options : [],
+      ...(options.value !== undefined ? { value: options.value } : {}),
+      ...(options.align ? { align: options.align } : {}),
+    });
+    return this;
+  }
+
+  /** Adds a list block to the modal body. */
+  list(id: string, options: ModalBuilderListOptions): this {
+    this.definition.content.push({
+      type: 'list',
+      id: String(id || '').trim(),
+      ...(options.label ? { label: options.label } : {}),
+      ...(options.emptyText ? { emptyText: options.emptyText } : {}),
+      ...(options.align ? { align: options.align } : {}),
+      items: Array.isArray(options.items) ? options.items : [],
+    });
+    return this;
+  }
+
+  /** Returns the serialized modal payload. */
+  build(): PluginModalDefinition {
+    return {
+      title: this.definition.title,
+      content: this.definition.content.map((item) => ({ ...item })) as PluginModalContentItem[],
+    };
+  }
+
+  /** Returns the serialized modal payload for a host request. */
+  async open(): Promise<PluginModalDefinition> {
+    return this.build();
+  }
+}

package/src/lib/runtime/registration.ts

@@ -80,8 +80,11 @@ export function createRegisteredPluginRuntime(
       },
       'plugin.handle_action': async (params, ctx) => {
         const actionId = String(params?.action_id || '').trim();
-        if (actionId && (await runRegisteredAction(actionId))) {
-          return null;
+        if (actionId) {
+          const result = await runRegisteredAction(actionId, params?.payload);
+          if (result !== null && result !== undefined) {
+            return result;
+          }
         }
         if (explicitHandleAction) {
           return explicitHandleAction(params, ctx);

package/src/lib/types/index.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 export * from './host';
+export * from './modal';
 export * from './menubar';
 export * from './plugin';
 export * from './protocol';

package/src/lib/types/modal.ts

@@ -0,0 +1,152 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/** Describes horizontal alignment hints for modal content. */
+export type ModalContentAlign = 'left' | 'centered' | 'right';
+
+/** Describes visual emphasis for modal buttons. */
+export type ModalButtonVariant = 'default' | 'primary' | 'danger';
+
+/** Describes the text input kinds supported by plugin modals. */
+export type ModalInputKind = 'text' | 'search' | 'password' | 'url' | 'number';
+
+/** Describes one button option rendered inside a modal. */
+export interface ModalButtonDefinition {
+  /** Stores the action id triggered when the button is pressed. */
+  id: string;
+  /** Stores the button label. */
+  content: string;
+  /** Stores the optional tooltip text. */
+  title?: string;
+  /** Stores the visual button variant. */
+  variant?: ModalButtonVariant;
+  /** Stores the button alignment hint. */
+  align?: ModalContentAlign;
+  /** Stores a static payload merged into the action payload. */
+  payload?: Record<string, unknown>;
+}
+
+/** Describes one text block rendered inside a modal. */
+export interface ModalTextDefinition {
+  /** Always stores `text`. */
+  type: 'text';
+  /** Stores the block text. */
+  content: string;
+  /** Stores an optional tooltip. */
+  title?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes one separator rendered inside a modal. */
+export interface ModalSeparatorDefinition {
+  /** Always stores `separator`. */
+  type: 'separator';
+}
+
+/** Describes one button rendered inside a modal body. */
+export interface ModalButtonItemDefinition extends ModalButtonDefinition {
+  /** Always stores `button`. */
+  type: 'button';
+}
+
+/** Describes one text input rendered inside a modal. */
+export interface ModalInputDefinition {
+  /** Always stores `input`. */
+  type: 'input';
+  /** Stores the input field id. */
+  id: string;
+  /** Stores the label text. */
+  label: string;
+  /** Stores the input kind. */
+  kind?: ModalInputKind;
+  /** Stores the default value. */
+  value?: string;
+  /** Stores the placeholder text. */
+  placeholder?: string;
+  /** Stores whether the field is required. */
+  required?: boolean;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes one select option rendered inside a modal. */
+export interface ModalSelectOptionDefinition {
+  /** Stores the option label. */
+  label: string;
+  /** Stores the option value. */
+  value: string;
+  /** Stores whether the option is selected by default. */
+  selected?: boolean;
+}
+
+/** Describes one select field rendered inside a modal. */
+export interface ModalSelectDefinition {
+  /** Always stores `select`. */
+  type: 'select';
+  /** Stores the field id. */
+  id: string;
+  /** Stores the label text. */
+  label: string;
+  /** Stores the available options. */
+  options: ModalSelectOptionDefinition[];
+  /** Stores the default value. */
+  value?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+}
+
+/** Describes one row-level action rendered in a list item. */
+export interface ModalListActionDefinition extends ModalButtonDefinition {
+  /** Always stores `button`. */
+  type: 'button';
+}
+
+/** Describes one list row rendered inside a modal list. */
+export interface ModalListRowDefinition {
+  /** Stores the row id. */
+  id: string;
+  /** Stores the row title. */
+  title: string;
+  /** Stores a short status label. */
+  status?: string;
+  /** Stores a secondary metadata label. */
+  meta?: string;
+  /** Stores longer descriptive text. */
+  description?: string;
+  /** Stores the row actions. */
+  actions?: ModalListActionDefinition[];
+}
+
+/** Describes one list block rendered inside a modal. */
+export interface ModalListDefinition {
+  /** Always stores `list`. */
+  type: 'list';
+  /** Stores the list id. */
+  id: string;
+  /** Stores the list label. */
+  label?: string;
+  /** Stores the empty-state text. */
+  emptyText?: string;
+  /** Stores the alignment hint. */
+  align?: ModalContentAlign;
+  /** Stores the list rows. */
+  items: ModalListRowDefinition[];
+}
+
+/** Describes one plugin modal content item. */
+export type PluginModalContentItem =
+  | ModalTextDefinition
+  | ModalSeparatorDefinition
+  | ModalButtonItemDefinition
+  | ModalInputDefinition
+  | ModalSelectDefinition
+  | ModalListDefinition;
+
+/** Describes the structured payload used to render a plugin modal. */
+export interface PluginModalDefinition {
+  /** Stores the modal title. */
+  title: string;
+  /** Stores the ordered list of modal content items. */
+  content: PluginModalContentItem[];
+}

package/src/lib/types/plugin.ts

@@ -32,6 +32,8 @@ export type PluginSettingsValue = Record<string, unknown>;
 export interface PluginHandleActionParams extends RequestParams {
   /** Stores the action id selected by the user. */
   action_id?: string;
+  /** Stores an optional payload supplied by the triggering UI. */
+  payload?: Record<string, unknown>;
 }
 
 /** Describes the params shape for plugin settings callbacks. */
@@ -74,7 +76,7 @@ export interface PluginDelegates<TContext = unknown> {
   /** Handles a contributed plugin action. */
   'plugin.handle_action'?: RpcMethodHandler<
     PluginHandleActionParams,
-    null,
+    unknown,
     TContext
   >;
   /** Returns the default settings values for the plugin. */

package/test/modal.test.ts

@@ -0,0 +1,24 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { ModalBuilder } from '../src/lib/runtime/index.js';
+
+describe('ModalBuilder', () => {
+  it('builds a structured modal definition', () => {
+    const modal = new ModalBuilder('Manage Submodules')
+      .text('Hello, World!')
+      .button('new-button', 'Test button, push me!', { align: 'centered' })
+      .build();
+
+    assert.deepStrictEqual(modal, {
+      title: 'Manage Submodules',
+      content: [
+        { type: 'text', content: 'Hello, World!' },
+        { type: 'button', id: 'new-button', content: 'Test button, push me!', align: 'centered' },
+      ],
+    });
+  });
+});