@openvcs/sdk 0.2.11 → 0.2.13

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

@@ -5,7 +5,7 @@ type MenubarMenuOptions = {
     before?: string;
     after?: string;
 };
-/** Runs one registered action handler by id. */
+/** Runs a registered action handler by id. */
 export declare function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<boolean>;
 export interface MenuHandle {
     id: string;
@@ -17,26 +17,26 @@ export interface MenuHandle {
 }
 /** Returns a menu by id, or null when it does not exist. */
 export declare function getMenu(menuId: string): MenuHandle | null;
-/** Returns a menu by id, creating it when necessary. */
+/** Returns a menu by id, creating it if needed. */
 export declare function getOrCreateMenu(menuId: string, label: string): MenuHandle | null;
-/** Creates a menu at a specific insertion point. */
+/** Creates a menu at a specific position. */
 export declare function createMenu(menuId: string, label: string, options?: MenubarMenuOptions): MenuHandle | null;
-/** Adds one action item to a menu. */
+/** Adds one item to a menu. */
 export declare function addMenuItem(menuId: string, item: MenubarItem): void;
-/** Adds one separator item to a menu. */
+/** Adds one separator to a menu. */
 export declare function addMenuSeparator(menuId: string, beforeAction?: string): void;
-/** Removes one menu entirely. */
+/** Removes one menu from the registry. */
 export declare function removeMenu(menuId: string): void;
-/** Hides one menu from the host UI. */
+/** Hides one menu from the registry. */
 export declare function hideMenu(menuId: string): void;
-/** Shows one previously hidden menu. */
+/** Shows one menu from the registry. */
 export declare function showMenu(menuId: string): void;
 /** Registers an action handler by id. */
 export declare function registerAction(id: string, handler: (...args: unknown[]) => unknown): void;
-/** Invokes a host command when the host exposes a direct invoke helper. */
+/** Invokes a host command when a host helper is available. */
 export declare function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
-/** Emits a user notification when the host exposes one. */
+/** Emits a notification when the host helper is available. */
 export declare function notify(msg: string): void;
-/** Builds the SDK plugin delegates contributed by the menu registry. */
+/** Builds SDK delegates from the local menu/action registries. */
 export declare function createMenuPluginDelegates(): PluginDelegates<PluginRuntimeContext>;
 export {};

package/lib/runtime/menu.js

@@ -18,31 +18,35 @@ exports.createMenuPluginDelegates = createMenuPluginDelegates;
 const menus = new Map();
 const menuOrder = [];
 const actionHandlers = new Map();
-let nextSyntheticId = 0;
-/** Returns the OpenVCS global, when the host exposes one. */
+let syntheticId = 0;
+/** Returns the host-side OpenVCS helper, when the environment provides one. */
 function getOpenVCS() {
     return globalThis.OpenVCS;
 }
-/** Normalizes menu ids for stable map lookups. */
+/** Normalizes a menu id for stable map lookup. */
 function normalizeMenuId(menuId) {
     return String(menuId || '').trim();
 }
-/** Allocates a stable synthetic id for a generated menu item. */
+/** Allocates a stable synthetic id for generated menu entries. */
 function allocateSyntheticId(prefix) {
-    nextSyntheticId += 1;
-    return `${prefix}-${nextSyntheticId}`;
+    syntheticId += 1;
+    return `${prefix}-${syntheticId}`;
 }
-/** Returns a stored menu state or null if it does not exist. */
+/** Returns the stored menu state for one id, if present. */
 function getStoredMenu(menuId) {
     return menus.get(normalizeMenuId(menuId)) || null;
 }
-/** Inserts a menu id into the ordering list. */
+/** Removes one menu id from the ordering list. */
+function removeMenuId(menuId) {
+    const id = normalizeMenuId(menuId);
+    const index = menuOrder.indexOf(id);
+    if (index >= 0)
+        menuOrder.splice(index, 1);
+}
+/** Inserts one menu id into the ordering list. */
 function placeMenuId(menuId, options) {
     const id = normalizeMenuId(menuId);
-    const existingIndex = menuOrder.indexOf(id);
-    if (existingIndex >= 0) {
-        menuOrder.splice(existingIndex, 1);
-    }
+    removeMenuId(id);
     const beforeId = normalizeMenuId(options?.before || '');
     const afterId = normalizeMenuId(options?.after || '');
     if (afterId) {
@@ -61,7 +65,7 @@ function placeMenuId(menuId, options) {
     }
     menuOrder.push(id);
 }
-/** Ensures a menu record exists for the provided id. */
+/** Ensures a menu record exists for one id. */
 function ensureStoredMenu(menuId, label, options) {
     const id = normalizeMenuId(menuId);
     const safeLabel = String(label || '').trim() || id;
@@ -69,46 +73,47 @@ function ensureStoredMenu(menuId, label, options) {
     if (!menu) {
         menu = { id, label: safeLabel, items: [] };
         menus.set(id, menu);
-        placeMenuId(id, options);
-        return menu;
     }
-    menu.label = safeLabel;
+    else {
+        menu.label = safeLabel;
+    }
     placeMenuId(id, options);
     return menu;
 }
-/** Finds one menu item by action id. */
-function findMenuItem(menu, actionId) {
+/** Finds a stored item by action id. */
+function findStoredItem(menu, actionId) {
     const id = normalizeMenuId(actionId);
     return menu.items.find((item) => item.action === id) || null;
 }
-/** Inserts a menu item relative to before/after anchors when provided. */
+/** Inserts a menu item at the requested position. */
 function insertMenuItem(menu, item, before, after) {
     const beforeId = normalizeMenuId(before || '');
     const afterId = normalizeMenuId(after || '');
-    const insertAt = (index) => {
-        const existingIndex = menu.items.findIndex((entry) => entry.id === item.id || entry.action === item.action);
-        if (existingIndex >= 0) {
-            menu.items.splice(existingIndex, 1);
-        }
-        menu.items.splice(index, 0, item);
+    const removeExisting = () => {
+        const index = menu.items.findIndex((entry) => entry.id === item.id || entry.action === item.action);
+        if (index >= 0)
+            menu.items.splice(index, 1);
     };
     if (beforeId) {
         const beforeIndex = menu.items.findIndex((entry) => entry.action === beforeId);
         if (beforeIndex >= 0) {
-            insertAt(beforeIndex);
+            removeExisting();
+            menu.items.splice(beforeIndex, 0, item);
             return;
         }
     }
     if (afterId) {
         const afterIndex = menu.items.findIndex((entry) => entry.action === afterId);
         if (afterIndex >= 0) {
-            insertAt(afterIndex + 1);
+            removeExisting();
+            menu.items.splice(afterIndex + 1, 0, item);
             return;
         }
     }
-    insertAt(menu.items.length);
+    removeExisting();
+    menu.items.push(item);
 }
-/** Converts one stored menu item into a serializable plugin payload element. */
+/** Converts one stored item into a serializable menu payload element. */
 function serializeMenuItem(item) {
     if (item.hidden)
         return null;
@@ -132,7 +137,7 @@ function serializeMenuItem(item) {
         label: item.label,
     };
 }
-/** Serializes the current menu registry for the host runtime. */
+/** Serializes the local registry into plugin menu payloads. */
 function serializeMenus() {
     return menuOrder
         .map((menuId, index) => {
@@ -150,7 +155,7 @@ function serializeMenus() {
     })
         .filter((menu) => Boolean(menu));
 }
-/** Runs one registered action handler by id. */
+/** Runs a registered action handler by id. */
 async function runRegisteredAction(actionId, ...args) {
     const id = String(actionId || '').trim();
     if (!id)
@@ -161,45 +166,33 @@ async function runRegisteredAction(actionId, ...args) {
     await handler(...args);
     return true;
 }
-/** Creates a stable, mutation-based handle for one menu id. */
+/** Creates a stable handle for one stored menu. */
 function createMenuHandle(menuId) {
     const id = normalizeMenuId(menuId);
     return {
         id,
         addItem(item) {
-            const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
             const label = String(item?.label || '').trim();
             const action = String(item?.action || '').trim();
             if (!label || !action)
                 return;
-            const entry = {
+            const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+            insertMenuItem(menu, {
                 kind: 'button',
                 id: action,
                 label,
                 title: item.title,
                 action,
-            };
-            insertMenuItem(menu, entry, item.before, item.after);
-            const openvcs = getOpenVCS();
-            if (!openvcs?.menus)
-                return;
-            openvcs.menus.getOrCreate(menu.id, menu.label);
-            openvcs.menus.addMenuItem(menu.id, item);
+            }, item.before, item.after);
         },
         addSeparator(beforeAction) {
             const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
-            const entry = {
+            insertMenuItem(menu, {
                 kind: 'separator',
                 id: allocateSyntheticId(`${menu.id}-separator`),
                 label: 'Separator',
                 content: '—',
-            };
-            insertMenuItem(menu, entry, beforeAction);
-            const openvcs = getOpenVCS();
-            if (!openvcs?.menus)
-                return;
-            openvcs.menus.getOrCreate(menu.id, menu.label);
-            openvcs.menus.addMenuSeparator(menu.id, beforeAction);
+            }, beforeAction);
         },
         removeItem(actionId) {
             const menu = getStoredMenu(this.id);
@@ -207,37 +200,22 @@ function createMenuHandle(menuId) {
                 return;
             const idToRemove = normalizeMenuId(actionId);
             menu.items = menu.items.filter((item) => item.action !== idToRemove);
-            const openvcs = getOpenVCS();
-            if (openvcs?.menus) {
-                const handle = openvcs.menus.get(this.id);
-                handle?.removeItem(idToRemove);
-            }
         },
         hideItem(actionId) {
             const menu = getStoredMenu(this.id);
             if (!menu)
                 return;
-            const item = findMenuItem(menu, actionId);
+            const item = findStoredItem(menu, actionId);
             if (item)
                 item.hidden = true;
-            const openvcs = getOpenVCS();
-            if (!openvcs?.menus)
-                return;
-            const handle = openvcs.menus.get(this.id);
-            handle?.hideItem(actionId);
         },
         showItem(actionId) {
             const menu = getStoredMenu(this.id);
             if (!menu)
                 return;
-            const item = findMenuItem(menu, actionId);
+            const item = findStoredItem(menu, actionId);
             if (item)
                 item.hidden = false;
-            const openvcs = getOpenVCS();
-            if (!openvcs?.menus)
-                return;
-            const handle = openvcs.menus.get(this.id);
-            handle?.showItem(actionId);
         },
     };
 }
@@ -248,53 +226,41 @@ function getMenu(menuId) {
         return null;
     return createMenuHandle(stored.id);
 }
-/** Returns a menu by id, creating it when necessary. */
+/** Returns a menu by id, creating it if needed. */
 function getOrCreateMenu(menuId, label) {
     const stored = ensureStoredMenu(menuId, label);
     return createMenuHandle(stored.id);
 }
-/** Creates a menu at a specific insertion point. */
+/** Creates a menu at a specific position. */
 function createMenu(menuId, label, options) {
     const stored = ensureStoredMenu(menuId, label, options);
     return createMenuHandle(stored.id);
 }
-/** Adds one action item to a menu. */
+/** Adds one item to a menu. */
 function addMenuItem(menuId, item) {
-    const menu = getStoredMenu(menuId) || ensureStoredMenu(menuId, menuId);
-    const handle = createMenuHandle(menu.id);
-    handle.addItem(item);
+    createMenuHandle(menuId).addItem(item);
 }
-/** Adds one separator item to a menu. */
+/** Adds one separator to a menu. */
 function addMenuSeparator(menuId, beforeAction) {
-    const menu = getStoredMenu(menuId) || ensureStoredMenu(menuId, menuId);
-    const handle = createMenuHandle(menu.id);
-    handle.addSeparator(beforeAction);
+    createMenuHandle(menuId).addSeparator(beforeAction);
 }
-/** Removes one menu entirely. */
+/** Removes one menu from the registry. */
 function removeMenu(menuId) {
     const id = normalizeMenuId(menuId);
     menus.delete(id);
-    const index = menuOrder.indexOf(id);
-    if (index >= 0)
-        menuOrder.splice(index, 1);
-    const openvcs = getOpenVCS();
-    openvcs?.menus?.remove(id);
+    removeMenuId(id);
 }
-/** Hides one menu from the host UI. */
+/** Hides one menu from the registry. */
 function hideMenu(menuId) {
     const menu = getStoredMenu(menuId);
     if (menu)
         menu.hidden = true;
-    const openvcs = getOpenVCS();
-    openvcs?.menus?.hide(normalizeMenuId(menuId));
 }
-/** Shows one previously hidden menu. */
+/** Shows one menu from the registry. */
 function showMenu(menuId) {
     const menu = getStoredMenu(menuId);
     if (menu)
         menu.hidden = false;
-    const openvcs = getOpenVCS();
-    openvcs?.menus?.show(normalizeMenuId(menuId));
 }
 /** Registers an action handler by id. */
 function registerAction(id, handler) {
@@ -302,23 +268,21 @@ function registerAction(id, handler) {
     if (!key)
         return;
     actionHandlers.set(key, handler);
-    const openvcs = getOpenVCS();
-    openvcs?.registerAction(key, handler);
 }
-/** Invokes a host command when the host exposes a direct invoke helper. */
+/** Invokes a host command when a host helper is available. */
 function invoke(cmd, args) {
     const openvcs = getOpenVCS();
     if (!openvcs) {
-        return Promise.reject(new Error('OpenVCS not available'));
+        return Promise.reject(new Error('OpenVCS host is not available in this runtime'));
     }
     return openvcs.invoke(cmd, args);
 }
-/** Emits a user notification when the host exposes one. */
+/** Emits a notification when the host helper is available. */
 function notify(msg) {
     const openvcs = getOpenVCS();
     openvcs?.notify(msg);
 }
-/** Builds the SDK plugin delegates contributed by the menu registry. */
+/** Builds SDK delegates from the local menu/action registries. */
 function createMenuPluginDelegates() {
     return {
         async 'plugin.get_menus'() {
@@ -326,9 +290,9 @@ function createMenuPluginDelegates() {
         },
         async 'plugin.handle_action'(params) {
             const actionId = String(params?.action_id || '').trim();
-            if (!actionId)
-                return null;
-            await runRegisteredAction(actionId);
+            if (actionId) {
+                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;
+    /** Requests the host to open the modal with the current definition. */
+    open(): Promise<void>;
+}

package/lib/runtime/modal.js

@@ -0,0 +1,95 @@
+"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;
+const menu_js_1 = require("./menu.js");
+/** 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 })),
+        };
+    }
+    /** Requests the host to open the modal with the current definition. */
+    async open() {
+        await (0, menu_js_1.invoke)('open_plugin_modal', { modal: this.build() });
+    }
+}
+exports.ModalBuilder = ModalBuilder;

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);