State, events, and routing

Extensions can manage pages using client-side routers, communicate across processes with the IPC wrapper, and react to runtime lifecycle milestones through the system event emitter.

Client-side routing and custom pages

You can add custom page components, register new client-side routes, or replace default view pages:

// Register a custom page to the router and sidebar navigation
lynxAPI.router.addPage(page: {
  id: string;
  title: string;
  icon?: ReactNode;
  component: FC;
  position?: 'top' | 'bottom' | 'hidden';
}): void;

// Register new client routes
lynxAPI.router.add(routes: RouteObject[]): void;

// Replace default pages entirely
lynxAPI.router.replace.homePage(Component: FC): void;
lynxAPI.router.replace.imageGenerationPage(Component: FC): void;
lynxAPI.router.replace.textGenerationPage(Component: FC): void;
lynxAPI.router.replace.audioGenerationPage(Component: FC): void;
lynxAPI.router.replace.toolsPage(Component: FC): void;
lynxAPI.router.replace.gamesPage(Component: FC): void;
lynxAPI.router.replace.dashboardPage(Component: FC): void;
lynxAPI.router.replace.modulesPage(Component: FC): void;
lynxAPI.router.replace.extensionsPage(Component: FC): void;
lynxAPI.router.replace.settingsPage(Component: FC): void;

Event bus (`events`)

The Event Bus enables communication between the application host and active extensions. Use the events property on lynxAPI.

// Register listener. Returns unsubscribe function.
events.on(event: string, callback: (payload: any) => void): () => void;

// Remove listener
events.off(event: string, callback: (payload: any) => void): void;

// Emit custom events
events.emit(event: string, payload: any): void;

// Get listener count
events.getListenerCount(event: string): number;

Hookable system events

The host emits events during critical application milestones:

Event Name	Payload Shape	Description
`before_card_start`	`{ id: string }`	Fires before launching a card module process.
`before_card_install`	`{ id: string }`	Fires before launching a card installation wizard.
`card_install_addStep`	`{ id: string, step: object }`	Fires when registering a step in the installation stepper.
`card_collect_user_input`	`{ id: string, fields: object }`	Fires when collecting user configurations for a card.

Renderer IPC (`rendererIpc`)

The rendererIpc object provides type-safe IPC wrappers to invoke methods or send events to your main process script.

// Invoke a main process handle method (Returns Promise)
rendererIpc.invoke<T = any>(channel: string, ...args: any[]): Promise<T>;

// Send a fire-and-forget message to the main process
rendererIpc.send(channel: string, ...args: any[]): void;

// Listen for messages from the main process. Returns cleanup function.
rendererIpc.on(channel: string, callback: (event: any, ...args: any[]) => void): () => void;

Example: Invoking custom backend IPC

export function InitialExtensions(lynxAPI, rendererIpc) {
  rendererIpc.invoke('hardware:get-status').then(status => {
    console.log('CPU Load:', status.cpu);
  });
}

Read-only modules data

The modulesData property grants access to loaded card modules information.

type ModuleData = {
  allModules: CardModules; // All modules loaded by application
  allCards: CardData[]; // Flat array of all card definitions

  // React hook to retrieve custom arguments for a card ID
  useGetArgumentsByID: (id: string) => ArgumentsData | undefined;

  // React hook to retrieve cards list belonging to a specific page ID
  useGetCardsByPath: (path: AvailablePageIDs) => LoadedCardData[] | undefined;

  // Retrieve a specific method from a card renderer methods object
  getCardMethod: (cards: CardData[], id: string, method: string) => Function | undefined;
};

Toast indicators

You can trigger visual toast notifications:

lynxAPI.toast.top(message: string, options?: any): void;
lynxAPI.toast.bottom(message: string, options?: any): void;

You can programmatically navigate tabs or set the active page for the current active tab:

lynxAPI.tabs.setActivePage(pageID: string, title?: string, isTerminal?: boolean): void;

Example: Navigate to a custom page on click

export function MySidebarWidget({lynxAPI}) {
  return <button onClick={() => lynxAPI.tabs.setActivePage('python-toolkit', 'Python Toolkit')}>Open Python Toolkit</button>;
}

Application

Plugins

AI Agents Setup

State, events, and routing

Client-side routing and custom pages

Event bus (`events`)

Hookable system events

Renderer IPC (`rendererIpc`)

Example: Invoking custom backend IPC

Read-only modules data

Toast indicators

Tab navigation and control

Example: Navigate to a custom page on click

​Client-side routing and custom pages

​Event bus (events)

​Hookable system events

​Renderer IPC (rendererIpc)

​Example: Invoking custom backend IPC

​Read-only modules data

​Toast indicators

​Tab navigation and control

​Example: Navigate to a custom page on click

Client-side routing and custom pages

Event bus (`events`)

Hookable system events

Renderer IPC (`rendererIpc`)

Example: Invoking custom backend IPC

Read-only modules data

Toast indicators

Tab navigation and control

Example: Navigate to a custom page on click