API_REFERENCE.md

XE IWA Launcher API Reference

Complete API reference for all plugins in the XE IWA Launcher ecosystem.

Table of Contents

• Chrome Manager Plugin
• Podman Plugin
• Workerd Plugin
• Caps Lock Remap Plugin
• Ollama Plugin
• Keyboard Plugin
• Event System
• Error Handling

---

Chrome Manager Plugin

Import: import * as chromeManager from 'tauri-plugin-chrome-manager';

Functions

launchChrome(options?: LaunchOptions): Promise<LaunchResponse>

Launches Chrome with specified configuration.

Parameters:

interface LaunchOptions {
  startingUrl?: string;      // Default: "https://www.userandagents.com"
  installIwaUrl?: string;    // Default: "http://localhost:5193"
  chromeFlags?: string[];    // Additional command-line flags
}

Returns:

interface LaunchResponse {
  success: boolean;
  pid?: number;      // Process ID if successful
  error?: string;    // Error message if failed
}

Example:

const result = await chromeManager.launchChrome({
  startingUrl: 'chrome://web-app-internals',
  chromeFlags: ['--disable-web-security']
});

killChrome(): Promise<string>

Terminates the Chrome instance launched by this plugin.

Returns: Success message or throws error

---

Podman Plugin

Import: import * as podman from 'tauri-plugin-podman';

Functions

checkPodmanInstalled(): Promise<boolean>

Checks if Podman is installed and machine is initialized.

Returns: true if ready, false if not installed

initializePodmanMachine(): Promise<string>

Initializes Podman machine if not already initialized.

Returns: Success message

listContainers(): Promise<ContainerInfo[]>

Lists all containers (running and stopped).

Returns:

interface ContainerInfo {
  id: string;
  name: string;
  status: string;
}

createContainer(options: CreateContainerOptions): Promise<ContainerInfo>

Creates a new container.

Parameters:

interface CreateContainerOptions {
  name: string;
  image: string;
  installDevTools: boolean;
}

startContainer(containerId: string): Promise<void>

Starts a stopped container.

stopContainer(containerId: string): Promise<void>

Stops a running container.

removeContainer(containerId: string): Promise<void>

Removes a container (must be stopped first).

getContainerLogs(request: ContainerLogsRequest): Promise<string>

Retrieves container logs.

Parameters:

interface ContainerLogsRequest {
  containerId: string;
  follow: boolean;
  tail?: string;
}

Events

• podman://terminal-output: Terminal output during operations

---

Workerd Plugin

Import: import * as workerd from 'tauri-plugin-workerd';

Functions

checkWorkerdInstalled(): Promise<WorkerdInfo>

Checks workerd installation status.

Returns:

interface WorkerdInfo {
  installed: boolean;
  version?: string;
  running: boolean;
}

downloadWorkerd(): Promise<string>

Downloads workerd binary for current platform.

listWorkers(): Promise<WorkerInfo[]>

Lists all registered workers.

Returns:

interface WorkerInfo {
  id: string;
  name: string;
  status: 'Running' | 'Stopped' | 'Error';
  url?: string;
  scriptPath?: string;
  createdAt: string;
}

createWorker(options: CreateWorkerOptions): Promise<WorkerInfo>

Creates a new worker.

Parameters:

interface CreateWorkerOptions {
  name: string;
  scriptPath: string;
  compatibilityDate?: string;
  envVars?: Array<{
    name: string;
    value: string;
  }>;
}

startWorker(workerId: string): Promise<void>

Starts a stopped worker.

stopWorker(workerId: string): Promise<void>

Stops a running worker.

removeWorker(workerId: string): Promise<void>

Removes a worker from registry.

getWorkerLogs(request: WorkerLogsRequest): Promise<WorkerLogs>

Gets worker logs.

Parameters:

interface WorkerLogsRequest {
  workerId: string;
  follow: boolean;
  tail?: string;
}

Returns:

interface WorkerLogs {
  stdout: string;
  stderr: string;
}

Events

• workerd://terminal-output: Worker process output

---

Caps Lock Remap Plugin

Import: import { invoke } from '@tauri-apps/api/core';

Functions

start_capslock_interceptor(): Promise<void>

Starts the Caps Lock interceptor.

Invoke: plugin:capslock-remap|start_capslock_interceptor

stop_capslock_interceptor(): Promise<void>

Stops the Caps Lock interceptor.

Invoke: plugin:capslock-remap|stop_capslock_interceptor

get_capslock_state(): Promise<CapsLockState>

Gets current state.

Returns:

interface CapsLockState {
  interceptorRunning: boolean;
  capsLockEnabled: boolean;
  listenModeActive: boolean;
  currentPattern: {
    singleTapDelay: number;
    doubleTapDelay: number;
    tripleTapDelay: number;
    holdThreshold: number;
  };
}

set_capslock_state(enabled: boolean): Promise<boolean>

Sets Caps Lock state.

configure_patterns(config: PatternConfiguration): Promise<void>

Configures detection patterns.

Parameters:

interface PatternConfiguration {
  patterns: {
    singleTapDelay: number;
    doubleTapDelay: number;
    tripleTapDelay: number;
    holdThreshold: number;
  };
  enableLedFeedback: boolean;
  enableSingleTap: boolean;
  enableDoubleTap: boolean;
  enableTripleTap: boolean;
  enableHold: boolean;
}

get_accessibility_status(): Promise<AccessibilityStatus>

Checks accessibility permissions.

Returns:

interface AccessibilityStatus {
  hasPermission: boolean;
  canRequest: boolean;
  instructions: string;
}

Events

• capslock-single-tap: Single tap detected
• capslock-double-tap: Double tap detected
• capslock-triple-tap: Triple tap detected
• capslock-hold-start: Hold started
• capslock-hold-end: Hold ended

---

Ollama Plugin

Import: import * as ollama from 'tauri-plugin-ollama';

Functions

checkConnection(): Promise<boolean>

Checks connection to Ollama server.

listModels(): Promise<ModelInfo[]>

Lists available models.

Returns:

interface ModelInfo {
  name: string;
  modified_at: string;
  size: number;
  digest: string;
}

pullModel(model: string): Promise<string>

Downloads a model.

generate(request: GenerateRequest): Promise<GenerateResponse>

Generates text completion.

Parameters:

interface GenerateRequest {
  model: string;
  prompt: string;
  system?: string;
  template?: string;
  context?: number[];
  options?: {
    temperature?: number;
    top_k?: number;
    top_p?: number;
    num_predict?: number;
    stop?: string[];
  };
}

Returns:

interface GenerateResponse {
  response: string;
  done: boolean;
  context?: number[];
  total_duration?: number;
  prompt_eval_count?: number;
  eval_count?: number;
}

chat(request: ChatRequest): Promise<string>

Conducts chat conversation.

Parameters:

interface ChatRequest {
  model: string;
  messages: Array<{
    role: string;
    content: string;
    images?: string[];
  }>;
  stream?: boolean;
  options?: GenerateOptions;
}

embeddings(request: EmbeddingRequest): Promise<EmbeddingResponse>

Generates text embeddings.

Parameters:

interface EmbeddingRequest {
  model: string;
  prompt: string;
}

Returns:

interface EmbeddingResponse {
  embedding: number[];
}

---

Keyboard Plugin

Status: 🚧 Under Development

Import: import * as keyboard from 'tauri-plugin-keyboard';

Planned Functions

registerHotkey(request: RegisterHotkeyRequest): Promise<void>

Registers a global hotkey.

Parameters:

interface RegisterHotkeyRequest {
  id: string;
  key: {
    keyCode: string;
    modifiers: string[];
  };
  description?: string;
}

unregisterHotkey(id: string): Promise<void>

Unregisters a hotkey.

startKeyMonitoring(): Promise<void>

Starts monitoring keyboard events.

stopKeyMonitoring(): Promise<void>

Stops monitoring keyboard events.

getKeyboardState(): Promise<KeyboardState>

Gets keyboard lock states.

Returns:

interface KeyboardState {
  capsLock: boolean;
  numLock: boolean;
  scrollLock: boolean;
}

simulateKey(request: SimulateKeyRequest): Promise<void>

Simulates a key press.

Parameters:

interface SimulateKeyRequest {
  keyCode: string;
  modifiers?: string[];
  eventType: 'keyDown' | 'keyUp' | 'keyPress';
}

Planned Events

• keyboard://hotkey: Hotkey triggered
• keyboard://key-event: Key event detected

---

Event System

Listening to Events

import { listen } from '@tauri-apps/api/event';

// Listen to plugin events
const unlisten = await listen('plugin-name://event-name', (event) => {
  console.log('Event payload:', event.payload);
});

// Stop listening
unlisten();

Event Naming Convention

• Chrome Manager: chrome://event-name
• Podman: podman://event-name
• Workerd: workerd://event-name
• Caps Lock: capslock-event-name (no prefix)
• Ollama: No events currently
• Keyboard: keyboard://event-name

---

Error Handling

Common Error Types

All plugins use consistent error patterns:

try {
  await pluginFunction();
} catch (error) {
  if (error.includes('not installed')) {
    // Handle missing dependency
  } else if (error.includes('permission')) {
    // Handle permission issues
  } else {
    // Handle other errors
  }
}

Plugin-Specific Errors

Chrome Manager

• Chrome not found: Chrome not installed
• Process management: Failed to track PID

Podman

• NotInstalled: Podman not found
• CommandFailed: Podman command failed
• ContainerError: Container operation failed

Workerd

• Not installed: Workerd not found
• Worker error: Worker operation failed
• Port conflict: Port already in use

Caps Lock Remap

• AccessibilityDenied: Missing permissions
• PlatformNotSupported: Wrong OS
• ListenerAlreadyRunning: Already active

Ollama

• Connection: Can't reach Ollama server
• ModelNotFound: Model not available
• Generation: Generation failed

Keyboard

• InvalidKeyCode: Unknown key
• ListenerError: Event monitoring failed
• PlatformError: OS-specific error

---

Best Practices

Performance

1. Batch Operations: Use Promise.all for multiple async calls
2. Event Cleanup: Always unlisten when component unmounts
3. Resource Management: Stop services when not needed

Security

1. Input Validation: Validate all user inputs
2. Permission Checks: Check permissions before operations
3. Error Messages: Don't expose sensitive information

Cross-Platform

1. Feature Detection: Check platform support
2. Fallbacks: Provide alternatives when unavailable
3. Testing: Test on all supported platforms

Example: Complete Plugin Usage

import { onMount, onCleanup } from 'solid-js';
import * as workerd from 'tauri-plugin-workerd';
import { listen } from '@tauri-apps/api/event';

function WorkerManager() {
  let unlisten;

  onMount(async () => {
    // Check installation
    const info = await workerd.checkWorkerdInstalled();
    if (!info.installed) {
      await workerd.downloadWorkerd();
    }

    // Listen for logs
    unlisten = await listen('workerd://terminal-output', (event) => {
      console.log(event.payload.line);
    });

    // Create and start worker
    const worker = await workerd.createWorker({
      name: 'api-worker',
      scriptPath: './worker.js'
    });
    
    await workerd.startWorker(worker.id);
  });

  onCleanup(() => {
    if (unlisten) unlisten();
  });
}

---

Version Compatibility

Plugin	Tauri Version	Minimum OS Version
Chrome Manager	2.0+	macOS 10.15+, Windows 10+, Ubuntu 20.04+
Podman	2.0+	macOS 11+, Windows 10+, Ubuntu 20.04+
Workerd	2.0+	macOS 10.15+, Windows 10+, Ubuntu 20.04+
Caps Lock Remap	2.0+	macOS 10.15+
Ollama	2.0+	macOS 10.15+, Windows 10+, Ubuntu 20.04+
Keyboard	2.0+	macOS 10.15+, Windows 10+, Ubuntu 20.04+