@openvcs/sdk 0.2.18-edge.20260420.21 → 0.2.18-edge.20260422.25

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 - Optional surface target ('menubar' or 'settings'), defaults to 'menubar'
+ */
+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,19 @@ 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 = 'menubar') {
     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;
+        // Preserve surface if already set, otherwise use provided.
+        if (!menu.surface)
+            menu.surface = surface;
     }
     placeMenuId(id, options);
     return menu;
@@ -148,6 +151,7 @@ function serializeMenus() {
             id: menu.id,
             label: menu.label,
             order: index + 1,
+            surface: menu.surface ?? 'menubar',
             elements: menu.items
                 .map((item) => serializeMenuItem(item))
                 .filter((item) => Boolean(item)),
@@ -225,16 +229,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 - Optional surface target ('menubar' or 'settings'), defaults to 'menubar'
+ */
+function getOrCreateMenu(menuId, label, options) {
+    const surface = options?.surface ?? 'menubar';
+    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/runtime/vcs-delegate-base.d.ts

@@ -77,6 +77,8 @@ export declare abstract class VcsDelegateBase<TDeps, TContext = PluginRuntimeCon
     writeMergeResult(_params: VcsTypes.VcsWriteMergeResultParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.stage_patch`. */
     stagePatch(_params: VcsTypes.VcsStagePatchParams, _context: TContext): VcsHandlerResult<null>;
+    /** Handles `vcs.stage_paths`. */
+    stagePaths(_params: VcsTypes.VcsStagePathsParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.discard_paths`. */
     discardPaths(_params: VcsTypes.VcsDiscardPathsParams, _context: TContext): VcsHandlerResult<null>;
     /** Handles `vcs.apply_reverse_patch`. */

package/lib/runtime/vcs-delegate-base.js

@@ -157,6 +157,10 @@ class VcsDelegateBase {
     stagePatch(_params, _context) {
         return this.unimplemented('stagePatch');
     }
+    /** Handles `vcs.stage_paths`. */
+    stagePaths(_params, _context) {
+        return this.unimplemented('stagePaths');
+    }
     /** Handles `vcs.discard_paths`. */
     discardPaths(_params, _context) {
         return this.unimplemented('discardPaths');

package/lib/runtime/vcs-delegate-metadata.d.ts

@@ -30,6 +30,7 @@ export type VcsDelegateBindings<TContext> = {
     checkoutConflictSide: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.checkout_conflict_side']>;
     writeMergeResult: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.write_merge_result']>;
     stagePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_patch']>;
+    stagePaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_paths']>;
     discardPaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.discard_paths']>;
     applyReversePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.apply_reverse_patch']>;
     deleteBranch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.delete_branch']>;
@@ -85,6 +86,7 @@ export declare const VCS_DELEGATE_METHOD_MAPPINGS: {
     readonly checkoutConflictSide: "vcs.checkout_conflict_side";
     readonly writeMergeResult: "vcs.write_merge_result";
     readonly stagePatch: "vcs.stage_patch";
+    readonly stagePaths: "vcs.stage_paths";
     readonly discardPaths: "vcs.discard_paths";
     readonly applyReversePatch: "vcs.apply_reverse_patch";
     readonly deleteBranch: "vcs.delete_branch";

package/lib/runtime/vcs-delegate-metadata.js

@@ -33,6 +33,7 @@ exports.VCS_DELEGATE_METHOD_MAPPINGS = {
     checkoutConflictSide: 'vcs.checkout_conflict_side',
     writeMergeResult: 'vcs.write_merge_result',
     stagePatch: 'vcs.stage_patch',
+    stagePaths: 'vcs.stage_paths',
     discardPaths: 'vcs.discard_paths',
     applyReversePatch: 'vcs.apply_reverse_patch',
     deleteBranch: 'vcs.delete_branch',

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/lib/types/vcs.d.ts

@@ -261,6 +261,11 @@ export interface VcsStagePatchParams extends VcsSessionParams {
     /** Stores the textual patch content. */
     patch: string;
 }
+/** Describes params for staging repository-relative paths into the index. */
+export interface VcsStagePathsParams extends VcsSessionParams {
+    /** Stores the paths to stage. */
+    paths?: string[];
+}
 /** Describes params for discarding path changes. */
 export interface VcsDiscardPathsParams extends VcsSessionParams {
     /** Stores the paths to discard. */
@@ -424,6 +429,8 @@ export interface VcsDelegates<TContext = unknown> {
     'vcs.write_merge_result'?: RpcMethodHandler<VcsWriteMergeResultParams, null, TContext>;
     /** Handles `vcs.stage_patch`. */
     'vcs.stage_patch'?: RpcMethodHandler<VcsStagePatchParams, null, TContext>;
+    /** Handles `vcs.stage_paths`. */
+    'vcs.stage_paths'?: RpcMethodHandler<VcsStagePathsParams, null, TContext>;
     /** Handles `vcs.discard_paths`. */
     'vcs.discard_paths'?: RpcMethodHandler<VcsDiscardPathsParams, null, TContext>;
     /** Handles `vcs.apply_reverse_patch`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.18-edge.20260420.21",
+  "version": "0.2.18-edge.20260422.25",
   "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 (defaults to menubar for back-compat). */
+  surface?: 'menubar' | 'settings';
   items: StoredMenuItem[];
 }
 
@@ -48,6 +51,7 @@ interface SerializedMenuDefinition {
   id: string;
   label: string;
   order: number;
+  surface: 'menubar' | 'settings';
   elements: SerializedMenuItem[];
 }
 
@@ -116,16 +120,19 @@ function ensureStoredMenu(
   menuId: string,
   label: string,
   options?: MenubarMenuOptions,
+  surface: MenuSurface = 'menubar',
 ): 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;
+    // Preserve surface if already set, otherwise use provided.
+    if (!menu.surface) menu.surface = surface;
   }
 
   placeMenuId(id, options);
@@ -207,6 +214,7 @@ function serializeMenus(): SerializedMenuDefinition[] {
         id: menu.id,
         label: menu.label,
         order: index + 1,
+        surface: menu.surface ?? 'menubar',
         elements: menu.items
           .map((item) => serializeMenuItem(item))
           .filter((item): item is SerializedMenuItem => Boolean(item)),
@@ -292,17 +300,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 - Optional surface target ('menubar' or 'settings'), defaults to 'menubar'
+ */
+export function getOrCreateMenu(
+  menuId: string,
+  label: string,
+  options?: MenubarMenuOptions & { surface?: MenuSurface },
+): MenuHandle | null {
+  const surface = options?.surface ?? 'menubar';
+  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/runtime/vcs-delegate-base.ts

@@ -303,6 +303,14 @@ export abstract class VcsDelegateBase<
     return this.unimplemented('stagePatch');
   }
 
+  /** Handles `vcs.stage_paths`. */
+  stagePaths(
+    _params: VcsTypes.VcsStagePathsParams,
+    _context: TContext,
+  ): VcsHandlerResult<null> {
+    return this.unimplemented('stagePaths');
+  }
+
   /** Handles `vcs.discard_paths`. */
   discardPaths(
     _params: VcsTypes.VcsDiscardPathsParams,

package/src/lib/runtime/vcs-delegate-metadata.ts

@@ -53,6 +53,7 @@ export type VcsDelegateBindings<TContext> = {
     VcsTypes.VcsDelegates<TContext>['vcs.write_merge_result']
   >;
   stagePatch: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_patch']>;
+  stagePaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.stage_paths']>;
   discardPaths: NonNullable<VcsTypes.VcsDelegates<TContext>['vcs.discard_paths']>;
   applyReversePatch: NonNullable<
     VcsTypes.VcsDelegates<TContext>['vcs.apply_reverse_patch']
@@ -122,6 +123,7 @@ export const VCS_DELEGATE_METHOD_MAPPINGS = {
   checkoutConflictSide: 'vcs.checkout_conflict_side',
   writeMergeResult: 'vcs.write_merge_result',
   stagePatch: 'vcs.stage_patch',
+  stagePaths: 'vcs.stage_paths',
   discardPaths: 'vcs.discard_paths',
   applyReversePatch: 'vcs.apply_reverse_patch',
   deleteBranch: 'vcs.delete_branch',

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

package/src/lib/types/vcs.ts

@@ -298,6 +298,12 @@ export interface VcsStagePatchParams extends VcsSessionParams {
   patch: string;
 }
 
+/** Describes params for staging repository-relative paths into the index. */
+export interface VcsStagePathsParams extends VcsSessionParams {
+  /** Stores the paths to stage. */
+  paths?: string[];
+}
+
 /** Describes params for discarding path changes. */
 export interface VcsDiscardPathsParams extends VcsSessionParams {
   /** Stores the paths to discard. */
@@ -518,6 +524,8 @@ export interface VcsDelegates<TContext = unknown> {
   >;
   /** Handles `vcs.stage_patch`. */
   'vcs.stage_patch'?: RpcMethodHandler<VcsStagePatchParams, null, TContext>;
+  /** Handles `vcs.stage_paths`. */
+  'vcs.stage_paths'?: RpcMethodHandler<VcsStagePathsParams, null, TContext>;
   /** Handles `vcs.discard_paths`. */
   'vcs.discard_paths'?: RpcMethodHandler<VcsDiscardPathsParams, null, TContext>;
   /** Handles `vcs.apply_reverse_patch`. */