wo/electron/types/README.md

wo-types

Type definitions for the Wo Wayland compositor Electron integration.

This package provides fully-typed interfaces for the compositor APIs exposed to Electron windows running within the Wo compositor.

Installation

bun install wo-types
# or
npm install wo-types

Usage

In Preload Scripts

import type { CompositorAPI, WoClientAPI } from 'wo-types';

// These are already exposed as window.compositor and window.woClient
const compositorAPI: CompositorAPI = window.compositor;
const clientAPI: WoClientAPI = window.woClient;

In React Components

import type { WoWindow, WindowMetadataEvent } from 'wo-types';
import { useEffect, useState } from 'react';

function MyComponent() {
  const [windows, setWindows] = useState<WoWindow[]>([]);
  const [metadata, setMetadata] = useState<WindowMetadataEvent | null>(null);

  useEffect(() => {
    // Subscribe to window updates
    const unsubWindows = window.woClient?.onWindows((windowList) => {
      setWindows(windowList);
    });

    // Subscribe to metadata updates
    const unsubMetadata = window.compositor?.onWindowMetadata((meta) => {
      setMetadata(meta);
    });

    return () => {
      unsubWindows?.();
      unsubMetadata?.();
    };
  }, []);

  return (
    <div>
      <p>Active windows: {metadata?.count ?? 0}</p>
    </div>
  );
}

API Reference

CompositorAPI

Exposed as window.compositor in Electron windows.

Methods

• action(name: string, payload?: Record<string, unknown>): Promise<unknown>

  • Send an action to the compositor

• actionSync(name: string, payload?: Record<string, unknown>): void

  • Send an action synchronously (fire and forget)

• quit(code?: number): Promise<unknown>

  • Request the compositor to quit

• reload(): Promise<unknown>

  • Reload the current window

• toggleDevTools(): Promise<unknown>

  • Toggle DevTools for the current window

• onFocusChange(callback: (window: string, focused: boolean) => void): () => void

  • Register focus change notification callback

• onWindowMetadata(callback: (metadata: WindowMetadataEvent) => void): () => void

  • Register window metadata update callback

• syscall(type: string, params: Record<string, unknown>): Promise<unknown>

  • Execute a syscall in the compositor

WoClientAPI

Exposed as window.woClient in Electron windows.

Methods

• getWindows(): Promise<WoWindow[]>

  • Get list of all windows

• onWindows(callback: (windows: WoWindow[]) => void): () => void

  • Register window list update callback

• sendAction(action: string): void

  • Send a keybind action to the compositor

Types

WindowMetadata

Describes a Wayland surface or application window.

interface WindowMetadata {
  name: string;
  title?: string;
  width: number;
  height: number;
  x: number;
  y: number;
  z_order: number;
  fps: number;
  focused?: boolean;
  focusable: boolean;
  interactive: boolean;
}

WoWindow

Window information returned by the client API.

interface WoWindow {
  name: string;
  title?: string;
  x: number;
  y: number;
  width: number;
  height: number;
  z_order: number;
  fps: number;
  focused: boolean;
}

WindowMetadataEvent

Event data for window metadata updates.

interface WindowMetadataEvent {
  windows: WindowMetadata[];
  count: number;
}

FocusChangeEvent

Event data for focus change notifications.

interface FocusChangeEvent {
  window: string;
  focused: boolean;
}

S2CAction

Enum of server-to-client actions.

enum S2CAction {
  WindowMetadataUpdate = 'window-metadata-update',
  FocusChange = 'focus-change',
  SyscallResponse = 'syscall-response',
  InputEvent = 'input-event',
}

License

MIT