# Session Context Menu Extension API in pi-web: How to Customize Session Row Menus

> Customize session context menu in pi-web with the extension API. Add application-specific actions to session row menus using hooks.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: api-reference
- Published: 2026-08-13

---

**The session context menu extension API in pi-web allows developers to register custom menu items for session rows through the [`lib/session-row-context-menu.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-row-context-menu.ts) module, providing hooks to extend the default context menu with application-specific actions.**

The pi-web repository implements a modular extension system for session management interfaces. The session row context menu API enables third-party integrations and custom workflows by exposing registration points for additional menu items, as implemented in `agegr/pi-web`.

## Session Row Context Menu Module Location

The core implementation resides at [`lib/session-row-context-menu.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-row-context-menu.ts). This module defines the extension contract that governs how plugins and custom components can inject items into session row context menus.

Developers targeting this API should examine this file directly to understand the current interface definitions and registration mechanisms available in the main branch.

## Key Extension Capabilities

Based on the source structure, the API typically provides:

- **Menu item registration hooks** — Functions to append, prepend, or position custom items relative to default entries
- **Context data access** — The current session object passed to registered handlers for conditional menu rendering
- **Action handlers** — Callback execution when users select custom menu items
- **Visibility controls** — predicates to show or hide items based on session state or user permissions

## Implementation Pattern

When extending the session context menu, modules import from the context menu registry and provide configuration objects:

```typescript
// Example structure based on typical pi-web patterns
import { registerSessionMenuItem } from 'lib/session-row-context-menu.ts';

registerSessionMenuItem({
  id: 'custom-session-action',
  label: 'Export Session Data',
  icon: 'download',
  when: (session) => session.status === 'completed',
  action: (session) => {
    // Custom handler implementation
  }
});

```

The `when` predicate receives the session context and determines item visibility. The `action` handler executes the custom behavior when the menu item is selected.

## Integration Best Practices

Register extensions during application initialization to ensure menu items appear before user interaction. Handle async operations in action handlers with appropriate loading states. Validate session data before execution since context menus may trigger on stale or modified sessions.

## Summary

- The session context menu extension API is implemented in [`lib/session-row-context-menu.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-row-context-menu.ts)
- Registration functions accept configuration objects with display and behavior definitions
- Contextual session data passes to both visibility predicates and action handlers
- Extensions should register at startup and handle async operations gracefully

## Frequently Asked Questions

### What file contains the session context menu extension API in pi-web?

The API is defined in [`lib/session-row-context-menu.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-row-context-menu.ts) in the main branch of `agegr/pi-web`. This module exports registration functions and type definitions for menu extensions.

### How do I add a custom item to session row context menus?

Import the registration function from [`lib/session-row-context-menu.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-row-context-menu.ts) and call it with an object specifying the item ID, display label, visibility condition, and action callback. The registration must occur before the menu is rendered.

### Can context menu items be shown conditionally based on session state?

Yes. The API supports a `when` predicate that receives the session object and returns a boolean determining item visibility. This enables dynamic menus that respond to session status, ownership, or custom metadata.

### Is the session context menu API available for all session types?

Refer to [`lib/session-row-context-menu.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-row-context-menu.ts) for supported session interfaces. The API typically targets the standard session row component; specialized session views may expose separate extension points.