@openvcs/sdk 0.2.18-edge.20260422.24 → 0.2.18-edge.20260422.26

package/lib/runtime/menu.d.ts

@@ -5,6 +5,7 @@ type MenubarMenuOptions = {
     before?: string;
     after?: string;
 };
+type MenuSurface = 'menubar' | 'settings';
 /** Runs a registered action handler by id. */
 export declare function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<unknown>;
 export interface MenuHandle {
@@ -17,10 +18,16 @@ 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 if needed. */
-export declare function getOrCreateMenu(menuId: string, label: string): MenuHandle | null;
-/** Creates a menu at a specific position. */
-export declare function createMenu(menuId: string, label: string, options?: MenubarMenuOptions): MenuHandle | null;
+/** Returns a menu by id, creating it if needed.
+ * @param menuId - Menu identifier
+ * @param label - User-visible label
+ * @param options - Surface target ('menubar' or 'settings'), MUST be explicitly provided
+ */
+export declare function getOrCreateMenu(menuId: string, label: string, options: MenubarMenuOptions & {
+    surface: MenuSurface;
+}): MenuHandle | null;
+/** Creates a menu at a specific position (alias for getOrCreateMenu). */
+export declare const createMenu: typeof getOrCreateMenu;
 /** Adds one item to a menu. */
 export declare function addMenuItem(menuId: string, item: MenubarItem): void;
 /** Adds one separator to a menu. */

package/lib/runtime/menu.js

@@ -2,10 +2,10 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMenu = void 0;
 exports.runRegisteredAction = runRegisteredAction;
 exports.getMenu = getMenu;
 exports.getOrCreateMenu = getOrCreateMenu;
-exports.createMenu = createMenu;
 exports.addMenuItem = addMenuItem;
 exports.addMenuSeparator = addMenuSeparator;
 exports.removeMenu = removeMenu;
@@ -66,16 +66,17 @@ function placeMenuId(menuId, options) {
     menuOrder.push(id);
 }
 /** Ensures a menu record exists for one id. */
-function ensureStoredMenu(menuId, label, options) {
+function ensureStoredMenu(menuId, label, options, surface) {
     const id = normalizeMenuId(menuId);
     const safeLabel = String(label || '').trim() || id;
     let menu = menus.get(id);
     if (!menu) {
-        menu = { id, label: safeLabel, items: [] };
+        menu = { id, label: safeLabel, surface, items: [] };
         menus.set(id, menu);
     }
     else {
         menu.label = safeLabel;
+        menu.surface = surface;
     }
     placeMenuId(id, options);
     return menu;
@@ -148,6 +149,7 @@ function serializeMenus() {
             id: menu.id,
             label: menu.label,
             order: index + 1,
+            surface: menu.surface,
             elements: menu.items
                 .map((item) => serializeMenuItem(item))
                 .filter((item) => Boolean(item)),
@@ -175,7 +177,11 @@ function createMenuHandle(menuId) {
             const action = String(item?.action || '').trim();
             if (!label || !action)
                 return;
-            const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+            let menu = getStoredMenu(this.id);
+            if (!menu) {
+                // Default to menubar for internal menu handle operations.
+                menu = ensureStoredMenu(this.id, this.id, {}, 'menubar');
+            }
             insertMenuItem(menu, {
                 kind: 'button',
                 id: action,
@@ -185,7 +191,11 @@ function createMenuHandle(menuId) {
             }, item.before, item.after);
         },
         addSeparator(beforeAction) {
-            const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+            let menu = getStoredMenu(this.id);
+            if (!menu) {
+                // Default to menubar for internal menu handle operations.
+                menu = ensureStoredMenu(this.id, this.id, {}, 'menubar');
+            }
             insertMenuItem(menu, {
                 kind: 'separator',
                 id: allocateSyntheticId(`${menu.id}-separator`),
@@ -225,16 +235,19 @@ function getMenu(menuId) {
         return null;
     return createMenuHandle(stored.id);
 }
-/** 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 position. */
-function createMenu(menuId, label, options) {
-    const stored = ensureStoredMenu(menuId, label, options);
+/** Returns a menu by id, creating it if needed.
+ * @param menuId - Menu identifier
+ * @param label - User-visible label
+ * @param options - Surface target ('menubar' or 'settings'), MUST be explicitly provided
+ */
+function getOrCreateMenu(menuId, label, options) {
+    const surface = options.surface;
+    const { surface: _, ...restOptions } = options;
+    const stored = ensureStoredMenu(menuId, label, restOptions, surface);
     return createMenuHandle(stored.id);
 }
+/** Creates a menu at a specific position (alias for getOrCreateMenu). */
+exports.createMenu = getOrCreateMenu;
 /** Adds one item to a menu. */
 function addMenuItem(menuId, item) {
     createMenuHandle(menuId).addItem(item);

package/lib/types/plugin.d.ts

@@ -15,8 +15,41 @@ export interface PluginInitializeResult {
 }
 /** Describes one optional override returned by a custom initialize handler. */
 export type PluginInitializeOverride = Partial<PluginInitializeResult>;
+/** Describes the UI surface targeted by one plugin menu definition. */
+export type PluginMenuSurface = 'menubar' | 'settings';
+/** Describes one static text element contributed to a plugin menu. */
+export interface PluginMenuTextElement {
+    /** Stores the serialized element kind. */
+    type: 'text';
+    /** Stores the stable plugin-local element id. */
+    id: string;
+    /** Stores the rendered text content. */
+    content: string;
+}
+/** Describes one button element contributed to a plugin menu. */
+export interface PluginMenuButtonElement {
+    /** Stores the serialized element kind. */
+    type: 'button';
+    /** Stores the stable action id dispatched back to the plugin. */
+    id: string;
+    /** Stores the user-visible button label. */
+    label: string;
+}
+/** Describes one renderable plugin menu element. */
+export type PluginMenuElement = PluginMenuTextElement | PluginMenuButtonElement;
 /** Describes one plugin-contributed menu definition. */
-export type PluginMenuDefinition = Record<string, unknown>;
+export interface PluginMenuDefinition {
+    /** Stores the stable plugin-local menu id. */
+    id: string;
+    /** Stores the user-visible menu label. */
+    label: string;
+    /** Stores the display ordering hint assigned by the runtime. */
+    order: number;
+    /** Stores the target UI surface for the menu. */
+    surface: PluginMenuSurface;
+    /** Stores the renderable elements contributed under the menu. */
+    elements: PluginMenuElement[];
+}
 /** Describes one plugin settings value payload. */
 export type PluginSettingsValue = Record<string, unknown>;
 /** Describes the params shape for plugin action handling. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.18-edge.20260422.24",
+  "version": "0.2.18-edge.20260422.26",
   "description": "OpenVCS SDK CLI for plugin scaffolding and runtime asset builds",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",

package/src/lib/runtime/menu.ts

@@ -12,6 +12,7 @@ import type { PluginRuntimeContext } from './contracts.js';
 
 type MenubarMenuOptions = { before?: string; after?: string };
 type MenuEntryKind = 'button' | 'text' | 'separator';
+type MenuSurface = 'menubar' | 'settings';
 
 type OpenVCSGlobal = typeof globalThis & {
   OpenVCS?: {
@@ -34,6 +35,8 @@ interface StoredMenuState {
   id: string;
   label: string;
   hidden?: boolean;
+  /** Surface target for rendering ('menubar' or 'settings'), must be explicitly provided. */
+  surface: MenuSurface;
   items: StoredMenuItem[];
 }
 
@@ -48,6 +51,7 @@ interface SerializedMenuDefinition {
   id: string;
   label: string;
   order: number;
+  surface: 'menubar' | 'settings';
   elements: SerializedMenuItem[];
 }
 
@@ -115,17 +119,19 @@ function placeMenuId(menuId: string, options?: MenubarMenuOptions): void {
 function ensureStoredMenu(
   menuId: string,
   label: string,
-  options?: MenubarMenuOptions,
+  options: MenubarMenuOptions,
+  surface: MenuSurface,
 ): StoredMenuState {
   const id = normalizeMenuId(menuId);
   const safeLabel = String(label || '').trim() || id;
   let menu = menus.get(id);
 
   if (!menu) {
-    menu = { id, label: safeLabel, items: [] };
+    menu = { id, label: safeLabel, surface, items: [] };
     menus.set(id, menu);
   } else {
     menu.label = safeLabel;
+    menu.surface = surface;
   }
 
   placeMenuId(id, options);
@@ -207,6 +213,7 @@ function serializeMenus(): SerializedMenuDefinition[] {
         id: menu.id,
         label: menu.label,
         order: index + 1,
+        surface: menu.surface,
         elements: menu.items
           .map((item) => serializeMenuItem(item))
           .filter((item): item is SerializedMenuItem => Boolean(item)),
@@ -246,7 +253,11 @@ function createMenuHandle(menuId: string): MenuHandle {
       const action = String(item?.action || '').trim();
       if (!label || !action) return;
 
-      const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+      let menu = getStoredMenu(this.id);
+      if (!menu) {
+        // Default to menubar for internal menu handle operations.
+        menu = ensureStoredMenu(this.id, this.id, {}, 'menubar');
+      }
       insertMenuItem(menu, {
         kind: 'button',
         id: action,
@@ -256,7 +267,11 @@ function createMenuHandle(menuId: string): MenuHandle {
       }, item.before, item.after);
     },
     addSeparator(beforeAction?: string) {
-      const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+      let menu = getStoredMenu(this.id);
+      if (!menu) {
+        // Default to menubar for internal menu handle operations.
+        menu = ensureStoredMenu(this.id, this.id, {}, 'menubar');
+      }
       insertMenuItem(menu, {
         kind: 'separator',
         id: allocateSyntheticId(`${menu.id}-separator`),
@@ -292,17 +307,24 @@ export function getMenu(menuId: string): MenuHandle | null {
   return createMenuHandle(stored.id);
 }
 
-/** Returns a menu by id, creating it if needed. */
-export function getOrCreateMenu(menuId: string, label: string): MenuHandle | null {
-  const stored = ensureStoredMenu(menuId, label);
+/** Returns a menu by id, creating it if needed.
+ * @param menuId - Menu identifier
+ * @param label - User-visible label
+ * @param options - Surface target ('menubar' or 'settings'), MUST be explicitly provided
+ */
+export function getOrCreateMenu(
+  menuId: string,
+  label: string,
+  options: MenubarMenuOptions & { surface: MenuSurface },
+): MenuHandle | null {
+  const surface = options.surface;
+  const { surface: _, ...restOptions } = options;
+  const stored = ensureStoredMenu(menuId, label, restOptions, surface);
   return createMenuHandle(stored.id);
 }
 
-/** 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);
-}
+/** Creates a menu at a specific position (alias for getOrCreateMenu). */
+export const createMenu = getOrCreateMenu;
 
 /** Adds one item to a menu. */
 export function addMenuItem(menuId: string, item: MenubarItem): void {

package/src/lib/types/plugin.ts

@@ -22,8 +22,45 @@ export interface PluginInitializeResult {
 /** Describes one optional override returned by a custom initialize handler. */
 export type PluginInitializeOverride = Partial<PluginInitializeResult>;
 
+/** Describes the UI surface targeted by one plugin menu definition. */
+export type PluginMenuSurface = 'menubar' | 'settings';
+
+/** Describes one static text element contributed to a plugin menu. */
+export interface PluginMenuTextElement {
+  /** Stores the serialized element kind. */
+  type: 'text';
+  /** Stores the stable plugin-local element id. */
+  id: string;
+  /** Stores the rendered text content. */
+  content: string;
+}
+
+/** Describes one button element contributed to a plugin menu. */
+export interface PluginMenuButtonElement {
+  /** Stores the serialized element kind. */
+  type: 'button';
+  /** Stores the stable action id dispatched back to the plugin. */
+  id: string;
+  /** Stores the user-visible button label. */
+  label: string;
+}
+
+/** Describes one renderable plugin menu element. */
+export type PluginMenuElement = PluginMenuTextElement | PluginMenuButtonElement;
+
 /** Describes one plugin-contributed menu definition. */
-export type PluginMenuDefinition = Record<string, unknown>;
+export interface PluginMenuDefinition {
+  /** Stores the stable plugin-local menu id. */
+  id: string;
+  /** Stores the user-visible menu label. */
+  label: string;
+  /** Stores the display ordering hint assigned by the runtime. */
+  order: number;
+  /** Stores the target UI surface for the menu. */
+  surface: PluginMenuSurface;
+  /** Stores the renderable elements contributed under the menu. */
+  elements: PluginMenuElement[];
+}
 
 /** Describes one plugin settings value payload. */
 export type PluginSettingsValue = Record<string, unknown>;