@openvcs/sdk 0.2.11 → 0.2.12

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);
+            }
             return null;
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "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/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);
+      }
       return null;
     },
   };