haloforge-plugin-api 0.2.4

# @haloforge/plugin-sdk

The official frontend SDK for building HaloForge plugins.

## Install

```bash
npm i @haloforge/plugin-sdk react react-dom @tauri-apps/api lucide-react
npm i -D typescript @types/react @types/react-dom
```

`react`, `react-dom`, `@tauri-apps/api`, and `lucide-react` are peer dependencies and should be installed in the plugin frontend project.

## Minimal Frontend Entry

```tsx
import { definePlugin, invokePlugin, registerPlugin } from "@haloforge/plugin-sdk";

function HelloButton() {
  async function handleClick() {
    const result = await invokePlugin<{ message: string }>("hello", { name: "HaloForge" });
    alert(result.message);
  }

  return <button onClick={() => void handleClick()}>Greet</button>;
}

export default registerPlugin("com.example.hello-plugin", definePlugin({
  slots: {
    "devkit.toolbar": HelloButton,
  },
}));
```

## What To Use

- `definePlugin`: Level 1 and Level 2 plugins such as tabs and slot injections.
- `defineModulePlugin`: Level 0 plugins that provide a full module panel.
- `defineAssistantPlugin`: Level 3 plugins that register an assistant UI.
- `registerPlugin`: register the bundle with HaloForge's runtime registry.
- `invokePlugin`: call commands exposed by your Rust backend.
- `useHostNavigation`, `useHostFileIntent`, `useHostModels`, `useHostAI`: stable host integration hooks for black-box-compatible plugins.
- `pickHostFile`, `pickHostDirectory`, `saveHostFile`: stable host file dialog helpers.
- `usePluginSettings`, `useHostData`, `useSlotContext`: read plugin and host state inside your React components.
- `useAppTheme`: read HaloForge theme mode and CSS variables inside your plugin.
- `AppSelect`: use the same host-styled dropdown/listbox HaloForge uses in the app.

## Public Host API

Prefer these host helpers over reading `window.__HF_HOST` directly:

- `useHostNavigation()` for module switches and settings tabs
- `useHostFileIntent()` for startup/external file-open intents
- `pickHostFile()` / `pickHostDirectory()` / `saveHostFile()` for host-owned file dialogs
- `useHostModels()` / `useAvailableModels()` for model lists and current selection
- `useHostAI()` for AI transport, session creation, stream-state polling, and generation stop
- `enterpriseGateway()` for host-mediated enterprise image generation/edit access without exposing session tokens
- `useHostTheme()` for theme tokens
- `useHostEvent()` for stable host events

These helpers currently adapt to HaloForge's existing host bridge internally, but they give plugin authors one documented surface that can keep working as HaloForge evolves.

## Enterprise Image Gateway

Plugins that need enterprise model gateway access must declare and receive approval for:

```json
{ "type": "host_enterprise_gateway_access" }
```

Then call the SDK helper from registered plugin UI:

```tsx
import { enterpriseGateway } from "@haloforge/plugin-sdk";

export function ImageStudioPanel() {
  async function generate() {
    const gateway = enterpriseGateway();
    const result = await gateway.generateImages({
      model: "gpt-image-1",
      prompt: "Create a polished HaloForge plugin icon.",
      size: "1024x1024",
      n: 1,
    });
    console.log(result.hf_output_assets?.[0]?.public_url ?? result.data?.[0]?.url);
  }

  return <button onClick={() => void generate()}>Generate</button>;
}
```

The host performs permission checks and forwards the request with the signed-in enterprise session. Plugins never receive the cloud session token.

## Host-styled Selects

```tsx
import { AppSelect } from "@haloforge/plugin-sdk";

export function ModelPicker({
  value,
  onChange,
}: {
  value: string;
  onChange: (next: string) => void;
}) {
  return (
    <AppSelect
      value={value}
      onChange={(event) => onChange(event.target.value)}
      className="w-full rounded-xl border border-border bg-background px-3 py-2 text-sm text-foreground"
    >
      <option value="gpt-5.4">GPT-5.4</option>
      <option value="claude-sonnet-4.6">Claude Sonnet 4.6</option>
    </AppSelect>
  );
}
```

`AppSelect` follows the active HaloForge theme automatically, so plugin dropdowns match the host app in both light and dark mode.

## Typical Setup

1. Build the native backend with `haloforge-plugin-api`.
2. Build the frontend bundle with this SDK.
3. Point `manifest.json` to the emitted frontend file via `entry.frontend`.
4. Load the plugin inside HaloForge and call `invokePlugin` from mounted components.

## Related Packages

- Rust backend crate: `haloforge-plugin-api`
- Repository: https://github.com/HaloForgeAI/haloforge-plugin-api
- HaloForge homepage: https://github.com/HaloForgeAI