# caique/plugin

> Every export of caique/plugin, with its signature and doc comment: validate, register, reset, registered, widgets, widgetFor and 4 more, plus 5 types.

Source: https://caique.interlace.tools/docs/api/plugin

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { validate, register, reset, … } from 'caique/plugin';
```

## Functions

### kinds

Every kind that can be drawn right now: the six, plus whatever is registered.

```ts
function kinds(): string[];
```

**Returns** `string[]`

### projectionOf

The static projection for *any* kind — the one surface a caller needs.

The six are still drawn by caique; anything else is a registered widget's `static`. A
kind that is neither is a refusal naming what *is* registered, so the reader can see the
typo rather than a text prompt where their rating widget should have been.

```ts
function projectionOf(spec: PromptSpec): string;
```

| Parameter | Type |
| :-- | :-- |
| `spec` | `PromptSpec` |

**Returns** `string`

### register

Register a plugin. Later wins, like ESLint flat config: the array is ordered, a caller
reads it top to bottom, and the last word on a kind is the one nearest the program.

```ts
function register(plugin: unknown): void;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `unknown` |

**Returns** `void`

### registered

The plugins registered, in registration order.

```ts
function registered(): readonly Plugin[];
```

**Returns** `readonly Plugin[]`

### reset

Forget every registered plugin. For tests, and for a program that re-registers at runtime.

```ts
function reset(): void;
```

**Returns** `void`

### validate

Refuse a plugin that cannot contribute a widget, at the door.

Every refusal here is about the `widgets` key or the plugin's own identity. A key another
layer owns is not inspected and not rejected (R1) — caique has no opinion about a spinner.

```ts
function validate(plugin: unknown): asserts plugin is Plugin;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `unknown` |

**Returns** `asserts plugin is Plugin`

### widgetFor

The widget that draws `kind`, or nothing when no plugin registered one.

```ts
function widgetFor(kind: string): Widget | undefined;
```

| Parameter | Type |
| :-- | :-- |
| `kind` | `string` |

**Returns** `Widget \| undefined`

### widgets

Every kind a plugin contributed, with who won it and who it shadowed.

```ts
function widgets(): Contribution[];
```

**Returns** `Contribution[]`

## Classes

### PluginError

A refused plugin says what is wrong and what to do about it — the family's one vocabulary.

```ts
class PluginError extends Error {
    readonly code: PluginErrorCode;
    readonly fix: string;
    constructor(code: PluginErrorCode, message: string, fix: string);
}
```

## Constants

### CONTRACT

The plugin contract version. One number for the family — the same `1` flagstaff and
roundel declare, written out rather than imported for the reason in the file comment.

```ts
const CONTRACT = 1;
```

## Interfaces

### Contribution

Which plugin last contributed each kind — the shadowing a `plugin check` prints.

```ts
interface Contribution {
    kind: string;
    from: string;
    /** Plugins that contributed this kind earlier and were overridden, in order. */
    shadowed: string[];
}
```

### Plugin

The keys caique reads. Declared structurally: any object with these fields is a plugin
here, whatever else it carries.

```ts
interface Plugin {
    name: string;
    contract?: number;
    widgets?: Record<string, Widget>;
}
```

### Widget

How a plugin draws one kind of prompt.

`static(spec)` is what a pipe, an agent and a screen reader get; it is what `projection()`
already returns for the six built-ins, so a plugin widget slots into the same surface
rather than beside it. `frame` is optional and drives `caique/raw`.

```ts
interface Widget {
    static: (spec: PromptSpec) => string;
    frame?: (t: number, spec: PromptSpec) => string;
    sample?: WidgetSample;
}
```

### WidgetSample

Two named states of plain data, which a grader renders a widget with (R7).

It carries no behaviour, so reading it does not mean running the author's code — that is
why an optional `sample` does not turn a plugin into a program.

```ts
interface WidgetSample {
    running: unknown;
    done: unknown;
}
```

## Types

### PluginErrorCode

```ts
type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_STATIC_PROJECTION' | 'E_UNKNOWN_KIND' | 'E_NO_CONTRIBUTION';
```