@openvcs/sdk 0.2.11 → 0.2.13

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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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/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

@@ -11,22 +11,10 @@ import type {
 import type { PluginRuntimeContext } from './contracts.js';
 
 type MenubarMenuOptions = { before?: string; after?: string };
-
 type MenuEntryKind = 'button' | 'text' | 'separator';
 
 type OpenVCSGlobal = typeof globalThis & {
   OpenVCS?: {
-    menus?: {
-      get(menuId: string): unknown;
-      getOrCreate(menuId: string, label: string): unknown;
-      create(menuId: string, label: string, options?: MenubarMenuOptions): unknown;
-      addMenuItem(menuId: string, item: MenubarItem): void;
-      addMenuSeparator(menuId: string, beforeAction?: string): void;
-      remove(menuId: string): void;
-      hide(menuId: string): void;
-      show(menuId: string): void;
-    };
-    registerAction(id: string, handler: (...args: unknown[]) => unknown): void;
     invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
     notify(msg: string): void;
   };
@@ -66,36 +54,40 @@ interface SerializedMenuDefinition {
 const menus = new Map<string, StoredMenuState>();
 const menuOrder: string[] = [];
 const actionHandlers = new Map<string, (...args: unknown[]) => unknown>();
-let nextSyntheticId = 0;
+let syntheticId = 0;
 
-/** Returns the OpenVCS global, when the host exposes one. */
+/** Returns the host-side OpenVCS helper, when the environment provides one. */
 function getOpenVCS() {
   return (globalThis as OpenVCSGlobal).OpenVCS;
 }
 
-/** Normalizes menu ids for stable map lookups. */
+/** Normalizes a menu id for stable map lookup. */
 function normalizeMenuId(menuId: string): string {
   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: string): string {
-  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: string): StoredMenuState | null {
   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: string): void {
+  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: string, options?: MenubarMenuOptions): void {
   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 || '');
@@ -119,8 +111,12 @@ function placeMenuId(menuId: string, options?: MenubarMenuOptions): void {
   menuOrder.push(id);
 }
 
-/** Ensures a menu record exists for the provided id. */
-function ensureStoredMenu(menuId: string, label: string, options?: MenubarMenuOptions): StoredMenuState {
+/** Ensures a menu record exists for one id. */
+function ensureStoredMenu(
+  menuId: string,
+  label: string,
+  options?: MenubarMenuOptions,
+): StoredMenuState {
   const id = normalizeMenuId(menuId);
   const safeLabel = String(label || '').trim() || id;
   let menu = menus.get(id);
@@ -128,38 +124,35 @@ function ensureStoredMenu(menuId: string, label: string, options?: MenubarMenuOp
   if (!menu) {
     menu = { id, label: safeLabel, items: [] };
     menus.set(id, menu);
-    placeMenuId(id, options);
-    return menu;
+  } else {
+    menu.label = safeLabel;
   }
 
-  menu.label = safeLabel;
   placeMenuId(id, options);
   return menu;
 }
 
-/** Finds one menu item by action id. */
-function findMenuItem(menu: StoredMenuState, actionId: string): StoredMenuItem | null {
+/** Finds a stored item by action id. */
+function findStoredItem(menu: StoredMenuState, actionId: string): StoredMenuItem | null {
   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: StoredMenuState, item: StoredMenuItem, before?: string, after?: string): void {
   const beforeId = normalizeMenuId(before || '');
   const afterId = normalizeMenuId(after || '');
 
-  const insertAt = (index: number) => {
-    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;
     }
   }
@@ -167,15 +160,17 @@ function insertMenuItem(menu: StoredMenuState, item: StoredMenuItem, before?: st
   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: StoredMenuItem): SerializedMenuItem | null {
   if (item.hidden) return null;
 
@@ -202,7 +197,7 @@ function serializeMenuItem(item: StoredMenuItem): SerializedMenuItem | null {
   };
 }
 
-/** Serializes the current menu registry for the host runtime. */
+/** Serializes the local registry into plugin menu payloads. */
 function serializeMenus(): SerializedMenuDefinition[] {
   return menuOrder
     .map((menuId, index) => {
@@ -214,13 +209,13 @@ function serializeMenus(): SerializedMenuDefinition[] {
         order: index + 1,
         elements: menu.items
           .map((item) => serializeMenuItem(item))
-        .filter((item): item is SerializedMenuItem => Boolean(item)),
+          .filter((item): item is SerializedMenuItem => Boolean(item)),
       };
     })
     .filter((menu): menu is SerializedMenuDefinition => Boolean(menu));
 }
 
-/** Runs one registered action handler by id. */
+/** Runs a registered action handler by id. */
 export async function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<boolean> {
   const id = String(actionId || '').trim();
   if (!id) return false;
@@ -241,80 +236,52 @@ export interface MenuHandle {
   showItem(actionId: string): void;
 }
 
-/** Creates a stable, mutation-based handle for one menu id. */
+/** Creates a stable handle for one stored menu. */
 function createMenuHandle(menuId: string): MenuHandle {
   const id = normalizeMenuId(menuId);
 
   return {
     id,
     addItem(item: MenubarItem) {
-      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: StoredMenuItem = {
+      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?: string) {
       const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
-      const entry: StoredMenuItem = {
+      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: string) {
       const menu = getStoredMenu(this.id);
       if (!menu) 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) as MenuHandle | null;
-        handle?.removeItem(idToRemove);
-      }
     },
     hideItem(actionId: string) {
       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) as MenuHandle | null;
-      handle?.hideItem(actionId);
     },
     showItem(actionId: string) {
       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) as MenuHandle | null;
-      handle?.showItem(actionId);
     },
   };
 }
@@ -326,59 +293,45 @@ export function getMenu(menuId: string): MenuHandle | null {
   return createMenuHandle(stored.id);
 }
 
-/** Returns a menu by id, creating it when necessary. */
+/** Returns a menu by id, creating it if needed. */
 export function getOrCreateMenu(menuId: string, label: string): MenuHandle | null {
   const stored = ensureStoredMenu(menuId, label);
   return createMenuHandle(stored.id);
 }
 
-/** Creates a menu at a specific insertion point. */
+/** Creates a menu at a specific position. */
 export function createMenu(menuId: string, label: string, options?: MenubarMenuOptions): MenuHandle | null {
   const stored = ensureStoredMenu(menuId, label, options);
   return createMenuHandle(stored.id);
 }
 
-/** Adds one action item to a menu. */
+/** Adds one item to a menu. */
 export function addMenuItem(menuId: string, item: MenubarItem): void {
-  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. */
 export function addMenuSeparator(menuId: string, beforeAction?: string): void {
-  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. */
 export function removeMenu(menuId: string): void {
   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. */
 export function hideMenu(menuId: string): void {
   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. */
 export function showMenu(menuId: string): void {
   const menu = getStoredMenu(menuId);
   if (menu) menu.hidden = false;
-
-  const openvcs = getOpenVCS();
-  openvcs?.menus?.show(normalizeMenuId(menuId));
 }
 
 /** Registers an action handler by id. */
@@ -386,27 +339,24 @@ export function registerAction(id: string, handler: (...args: unknown[]) => unkn
   const key = String(id || '').trim();
   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. */
 export function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T> {
   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. */
 export function notify(msg: string): void {
   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. */
 export function createMenuPluginDelegates(): PluginDelegates<PluginRuntimeContext> {
   return {
     async 'plugin.get_menus'(): Promise<PluginMenuDefinition[]> {
@@ -414,8 +364,9 @@ export function createMenuPluginDelegates(): PluginDelegates<PluginRuntimeContex
     },
     async 'plugin.handle_action'(params: PluginHandleActionParams): Promise<null> {
       const actionId = String(params?.action_id || '').trim();
-      if (!actionId) return null;
-      await runRegisteredAction(actionId);
+      if (actionId) {
+        await runRegisteredAction(actionId, params?.payload);
+      }
       return null;
     },
   };