# zidane-ui/extensions/headless

Import: `import { … } from 'zidane-ui/extensions/headless'`. Source: [ui/src/extensions/headless/index.ts](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/index.ts).

## Functions

### `clampSettingNumber`

Function.

Clamps and snaps a number the way zidane does (`clampExtensionConfigNumber`), so a typed value
persists the same from every client.

```ts
function clampSettingNumber(
  item: Omit<ExtensionConfigNumberItem, 'validate'> & WireConfigExtras,
  n: number,
): number
```

**Parameters**

- `item` (`Omit<ExtensionConfigNumberItem, 'validate'> & WireConfigExtras`): A number row.
- `n` (`number`): The typed number.

**Returns** `number`

Source: [ui/src/extensions/headless/select.ts:229](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L229)

### `createDialogQueue`

Function.

Creates an empty [`DialogQueue`](https://zidane.si/docs/reference/ui-extensions-headless.md#DialogQueue).

```ts
function createDialogQueue(): DialogQueue
```

**Returns** `DialogQueue`

Source: [ui/src/extensions/headless/dialog-queue.ts:39](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/dialog-queue.ts#L39)

### `createEffectRouter`

Function.

Creates an [`ExtensionEffectRouter`](https://zidane.si/docs/reference/ui-extensions-headless.md#ExtensionEffectRouter) over a host's effects.

```ts
function createEffectRouter(effects: ExtensionUiEffects): ExtensionEffectRouter
```

**Parameters**

- `effects` (`ExtensionUiEffects`): The host's `effects`.

**Returns** `ExtensionEffectRouter`

Source: [ui/src/extensions/headless/effect-router.ts:55](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/effect-router.ts#L55)

### `createUiEffectChannel`

Function.

Creates a [`UiEffectChannel`](https://zidane.si/docs/reference/ui-extensions-headless.md#UiEffectChannel).

```ts
function createUiEffectChannel(): UiEffectChannel
```

**Returns** `UiEffectChannel`

Source: [ui/src/extensions/headless/effect-channel.ts:23](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/effect-channel.ts#L23)

### `createWebviewRpcBridge`

Function.

Creates the bridge for one webview page.

```ts
function createWebviewRpcBridge(options: WebviewRpcBridgeOptions): WebviewRpcBridge
```

**Parameters**

- `options` (`WebviewRpcBridgeOptions`): The extension, the contracts it lists, the host's RPC and how to post back.

**Returns** `WebviewRpcBridge`

Source: [ui/src/extensions/headless/webview-bridge.ts:85](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L85)

### `extensionsErrorOf`

Function.

The typed error behind any rejection: an [`ExtensionsHostError`](https://zidane.si/docs/reference/ui-extensions-headless.md#ExtensionsHostError)'s own, else `failed` with the message.

```ts
function extensionsErrorOf(err: unknown): ExtensionsError
```

**Parameters**

- `err` (`unknown`): What a host action rejected with.

**Returns** `ExtensionsError`

Source: [ui/src/extensions/headless/host.ts:62](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L62)

### `filterSelectOptions`

Function.

The options whose label, description or group contains every word of `query` (case-insensitive).

```ts
function filterSelectOptions(
  options: readonly SelectOption[],
  query: string,
): readonly SelectOption[]
```

**Parameters**

- `options` (`readonly SelectOption[]`): A select dialog's options.
- `query` (`string`): What the user typed.

**Returns** `readonly SelectOption[]`

Source: [ui/src/extensions/headless/select.ts:149](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L149)

### `groupSelectOptions`

Function.

Options grouped in first-seen group order; ungrouped options come first under `group: undefined`.

```ts
function groupSelectOptions(
  options: readonly SelectOption[],
): readonly { group: string | undefined; options: readonly SelectOption[] }[]
```

**Parameters**

- `options` (`readonly SelectOption[]`): The options to group.

**Returns** `readonly { group: string | undefined; options: readonly SelectOption[] }[]`

Source: [ui/src/extensions/headless/select.ts:163](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L163)

### `isSettingLocked`

Function.

Whether a declarative config entry sets this setting (shown, not editable).

```ts
function isSettingLocked(
  settings: WireSettings,
  extension: string,
  key: string,
): boolean
```

**Parameters**

- `settings` (`WireSettings`): The wire settings.
- `extension` (`string`): The extension.
- `key` (`string`): The setting.

**Returns** `boolean`

Source: [ui/src/extensions/headless/select.ts:218](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L218)

### `isWebviewRpcRequest`

Function.

Whether `data` is a well-formed bridge request.

```ts
function isWebviewRpcRequest(data: unknown): data is WebviewRpcRequest
```

**Parameters**

- `data` (`unknown`): A message from the page.

**Returns** `data is WebviewRpcRequest`

Source: [ui/src/extensions/headless/webview-bridge.ts:69](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L69)

### `missingScope`

Function.

The scope an action needs that this client's token lacks, or `null` when it may run it: the token
grants `granted` (`null` or absent: not limited, as a local or in-process host), the action needs
`required` (default `admin`, as zidane's).

```ts
function missingScope(
  granted: ExtensionAccessScope | null | undefined,
  required: ExtensionAccessScope | undefined,
): ExtensionAccessScope | null
```

**Parameters**

- `granted` (`ExtensionAccessScope | null | undefined`): The token's scope (`ExtensionsHost.scope`).
- `required` (`ExtensionAccessScope | undefined`): The action's `scope`.

**Returns** `ExtensionAccessScope | null`

Source: [ui/src/extensions/headless/select.ts:59](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L59)

### `openInNewTab`

Function.

Opens `url` in a new browser tab (in the desktop app, main's window-open handler hands it to the
system): the app's way for a web link.

```ts
function openInNewTab(url: string): void
```

**Parameters**

- `url` (`string`): The link.

Source: [ui/src/extensions/headless/links.ts:54](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/links.ts#L54)

### `qualifyPanelId`

Function.

The full id of a panel an extension names: `<extension>/<id>` when that extension has one by
that id, else the id as given (already full, or a built-in tab such as `todos`).

```ts
function qualifyPanelId(
  extension: string,
  panel: string,
  panels: readonly ExtensionItem<'panel'>[],
): string
```

**Parameters**

- `extension` (`string`): The naming extension.
- `panel` (`string`): The id it named.
- `panels` (`readonly ExtensionItem<'panel'>[]`): Every panel item.

**Returns** `string`

Source: [ui/src/extensions/headless/select.ts:137](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L137)

### `rendererMatches`

Function.

Whether a renderer draws `target`. Languages compare case-insensitively; a renderer for several
tools draws each of them, and one for `'*'` draws every tool. A block id matches as given or, with
`extension`, under the extension that registered the renderer (`<extension>/<id>`, the form
`CommandOutputBlock.custom.renderer` and `PanelCustomItem.renderer` carry).

```ts
function rendererMatches(
  renderer: RendererWire,
  target: RendererTarget,
  extension?: string,
): boolean
```

**Parameters**

- `renderer` (`RendererWire`): A renderer's wire form.
- `target` (`RendererTarget`): What needs drawing (one tool name for a tool).
- `extension?` (`string`): The extension that registered the renderer.

**Returns** `boolean`

Source: [ui/src/extensions/headless/select.ts:100](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L100)

### `renderersFor`

Function.

The renderers for `target`, in the host's order: the first draws, the next ones take over when a
`fallthrough` renderer draws nothing.

```ts
function renderersFor(
  items: readonly ExtensionItem<'renderer'>[],
  target: RendererTarget,
): readonly ExtensionItem<'renderer'>[]
```

**Parameters**

- `items` (`readonly ExtensionItem<'renderer'>[]`): Every renderer item.
- `target` (`RendererTarget`): What needs drawing.

**Returns** `readonly ExtensionItem<'renderer'>[]`

Source: [ui/src/extensions/headless/select.ts:122](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L122)

### `routeLink`

Function.

Opens `url`: through the extensions' link handlers first, else `fallback` (the app's own way).
Resolves `true` when a handler opened it. A handler that fails counts as not opening it.

```ts
function routeLink(
  openLink: ((request: ExtensionLinkRequest) => Promise<boolean>) | undefined,
  url: string,
  options: LinkRouteOptions,
  fallback: () => void,
): Promise<boolean>
```

**Parameters**

- `openLink` (`((request: ExtensionLinkRequest) => Promise<boolean>) | undefined`): The host's `openLink`. Absent: `fallback` at once.
- `url` (`string`): The link.
- `options` (`LinkRouteOptions`): Where it was clicked, the session, and whether to bypass the handlers.
- `fallback` (`() => void`): Opens the link the app's way.

**Returns** `Promise<boolean>`

Source: [ui/src/extensions/headless/links.ts:29](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/links.ts#L29)

### `settingsValues`

Function.

Every row's starting value, by `extension` then key.

```ts
function settingsValues(
  settings: WireSettings,
): Record<string, Record<string, SettingValue>>
```

**Parameters**

- `settings` (`WireSettings`): The wire settings.

**Returns** `Record<string, Record<string, SettingValue>>`

Source: [ui/src/extensions/headless/select.ts:203](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L203)

### `settingValue`

Function.

The value a row shows: the stored value when its type fits, else the default.

```ts
function settingValue(
  item: WireExtensionConfigItem,
  stored: unknown,
): ExtensionConfigValue
```

**Parameters**

- `item` (`WireExtensionConfigItem`): The row.
- `stored` (`unknown`): The stored value, if any.

**Returns** `ExtensionConfigValue`

Source: [ui/src/extensions/headless/select.ts:185](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L185)

### `slotIsActionable`

Function.

Whether a slot item does something on click: opens a panel or runs a command.

```ts
function slotIsActionable(item: SlotWire): boolean
```

**Parameters**

- `item` (`SlotWire`): The slot item.

**Returns** `boolean`

Source: [ui/src/extensions/headless/select.ts:247](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L247)

### `slotItems`

Function.

The slot items for one place, lowest `order` first (stable). Items scoped to a session show only
beside that session; unscoped items show everywhere. A `transcript.turn-end` item that names a turn
shows only after that turn (`turnId`); one that names none, only where no turn is given (the end of
the transcript).

```ts
function slotItems(
  items: readonly ExtensionItem<'slot'>[],
  at: SlotName,
  sessionId?: string,
  turnId?: string,
): readonly ExtensionItem<'slot'>[]
```

**Parameters**

- `items` (`readonly ExtensionItem<'slot'>[]`): Every slot item.
- `at` (`SlotName`): The place.
- `sessionId?` (`string`): The session the place belongs to, if any.
- `turnId?` (`string`): `transcript.turn-end`: the turn the place follows. Absent: the end of the transcript.

**Returns** `readonly ExtensionItem<'slot'>[]`

Source: [ui/src/extensions/headless/select.ts:31](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L31)

### `titlebarItems`

Function.

The `app.titlebar` items, lowest `order` first, at most [`TITLEBAR_ITEMS_PER_EXTENSION`](https://zidane.si/docs/reference/ui-extensions-headless.md#TITLEBAR_ITEMS_PER_EXTENSION) per
extension (its first ones in that order).

```ts
function titlebarItems(
  items: readonly ExtensionItem<'slot'>[],
  sessionId?: string,
): readonly ExtensionItem<'slot'>[]
```

**Parameters**

- `items` (`readonly ExtensionItem<'slot'>[]`): Every slot item.
- `sessionId?` (`string`): The session on screen: its session-scoped items show too.

**Returns** `readonly ExtensionItem<'slot'>[]`

Source: [ui/src/extensions/headless/select.ts:78](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L78)

## Classes

### `ExtensionsHostError`

Class.

What a host action rejects with.

```ts
class ExtensionsHostError extends Error
```

**Constructor**

```ts
new ExtensionsHostError(error: ExtensionsError)
```

**Parameters**

- `error` (`ExtensionsError`): Why it failed.

**Returns** `ExtensionsHostError`

**Properties**

- `error` (`ExtensionsError`, readonly): Why it failed.

Source: [ui/src/extensions/headless/host.ts:41](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L41)

## Constants

### `DEFAULT_EXTENSIONS_LABELS`

Constant.

The default English strings of the extensions components.

```ts
const DEFAULT_EXTENSIONS_LABELS: { extensionCatalogKind: (kind: CatalogKind) => string; extensionDialogCancel: string; extensionDialogConfirm: string; extensionDialogDone: string; extensionDialogOk: string; extensionDialogSubmit: string; extensionError: (error: ExtensionsError) => string; extensionIntegrationAccountCount: (count: number) => string; extensionIntegrationAccounts: (integration: string) => string; extensionIntegrationAddAccount: string; extensionIntegrationAddAccountWith: (method: string) => string; extensionIntegrationConnect: string; extensionIntegrationConnected: string; extensionIntegrationDefault: string; extensionIntegrationDisconnect: string; extensionIntegrationDisconnectLabel: (account: string) => string; extensionIntegrationError: (error: ExtensionsError) => string; extensionIntegrationMakeDefault: string; extensionIntegrationMakeDefaultLabel: (account: string) => string; extensionIntegrationNotConnected: string; extensionProvenance: (p: ExtensionProvenanceWire) => string; extensionRegion: (extension: string) => string; extensionScreenClose: string; extensionScreenMissing: string; extensionSelectNoMatch: string; extensionSelectSearch: string; extensionSettingLocked: string; extensionSettingRun: string; extensionSettingRunning: string; extensionSettingsChangesHeading: string; extensionSettingsIntegrationsHeading: string; extensionSettingsLockedHeading: string; extensionSettingsLockedTag: string; extensionSettingsNone: string; extensionSettingsSection: string; extensionToastDismiss: string; extensionToasts: string; extensionWorking: string }
```

Source: [ui/src/extensions/headless/labels.ts:20](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/labels.ts#L20)

### `EXTENSION_TOKENS`

Constant.

Every token the kit draws, in a fixed order.

```ts
const EXTENSION_TOKENS: readonly ExtensionTokenName[]
```

Source: [ui/src/extensions/headless/wire.ts:133](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L133)

### `SLOT_NAMES`

Constant.

Every slot name, in a fixed order.

```ts
const SLOT_NAMES: readonly SlotName[]
```

Source: [ui/src/extensions/headless/wire.ts:19](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L19)

### `TITLEBAR_ITEMS_PER_EXTENSION`

Constant.

How many `app.titlebar` items one extension shows: as many as its composer badges.

```ts
const TITLEBAR_ITEMS_PER_EXTENSION = 8
```

Source: [ui/src/extensions/headless/select.ts:69](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L69)

### `WEBVIEW_RPC_NOT_ALLOWED`

Constant.

Error type for a contract the webview does not list.

```ts
const WEBVIEW_RPC_NOT_ALLOWED = 'rpc.not-allowed'
```

Source: [ui/src/extensions/headless/webview-bridge.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L16)

### `WEBVIEW_RPC_REQUEST`

Constant.

The `type` of a request the page posts.

```ts
const WEBVIEW_RPC_REQUEST = 'zidane:rpc'
```

Source: [ui/src/extensions/headless/webview-bridge.ts:11](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L11)

### `WEBVIEW_RPC_RESULT`

Constant.

The `type` of the reply the bridge posts.

```ts
const WEBVIEW_RPC_RESULT = 'zidane:rpc:result'
```

Source: [ui/src/extensions/headless/webview-bridge.ts:13](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L13)

### `WEBVIEW_RPC_UNAVAILABLE`

Constant.

Error type when the host offers no RPC.

```ts
const WEBVIEW_RPC_UNAVAILABLE = 'rpc.unavailable'
```

Source: [ui/src/extensions/headless/webview-bridge.ts:18](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L18)

## Interfaces

### `DialogQueue`

Interface.

A dialog queue: the stores the UI reads, and the entry the backend calls.

```ts
interface DialogQueue
```

**Properties**

- `dialogs` (`ExtensionDialogs`): `ExtensionsHost.dialogs`.
- `clear` (`() => void`): Drops every pending dialog unanswered (the client goes away).
- `show` (`(request: DialogRequest, ctx: DialogQueueShowContext) => Promise<unknown>`): Queues a dialog; resolves with the answer (`undefined` for a cancel), rejects with the signal's reason.

Source: [ui/src/extensions/headless/dialog-queue.ts:23](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/dialog-queue.ts#L23)

### `DialogQueueShowContext`

Interface.

Where a request comes from.

```ts
interface DialogQueueShowContext
```

**Properties**

- `extensionId` (`string`): The extension that asked.
- `id?` (`string`): The dialog's id; default: a fresh one.
- `sessionId?` (`string`): The session the dialog belongs to, when it has one.
- `signal?` (`AbortSignal`): Aborts when the backend withdraws the dialog (timeout, abort, the extension unloaded).

Source: [ui/src/extensions/headless/dialog-queue.ts:11](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/dialog-queue.ts#L11)

### `ExtensionCallbacks`

Interface.

The extension callbacks a host can invoke, by id: their arguments and what they answer.

```ts
interface ExtensionCallbacks
```

**Properties**

- `badge.menu` (`{ args: { target: BadgeTarget }; result: readonly BadgeMenuItem[] }`): The badge action menu for a target.
- `badge.run` (`{ args: { actionId: string; cwd?: string; sessionId?: string; source: string; target: BadgeTarget }; result: BadgeActionEffect }`): Runs one badge action.
- `panel.action` (`{ args: { actionId: string; context?: unknown; cwd: string; panelId: string; payload?: unknown }; result: boolean }`): A panel's `onAction`. Whether it ran.
- `panel.load` (`{ args: { context?: unknown; cwd: string; panelId: string }; result: PanelContent }`): A panel's `load` in a folder.
- `reference.resolve` (`{ args: { key: string; providerId: string }; result: ExtensionReferenceView | null }`): A reference provider's `resolve`. `null`: nothing to show.
- `setting.action` (`{ args: { key: string; pageId: string }; result: { message?: string; patch?: Readonly<Record<string, string | number | boolean | readonly string[]>>; tone?: 'error' | 'success' | 'warn' | 'info' } | undefined }`): Runs an action setting of a settings page (or of an extension's settings: `pageId` is then the extension id).
- `setting.status` (`{ args: { key: string; pageId: string }; result: { text: string; tone?: 'error' | 'muted' | 'success' | 'warn' } | undefined }`): An action setting's passive status line.

Source: [ui/src/extensions/headless/host.ts:68](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L68)

### `ExtensionCommands`

Interface.

The unified commands.

```ts
interface ExtensionCommands
```

**Properties**

- `list` (`Readable<readonly ExtensionCommandWire[]>`): Every command, built-ins and extensions'.
- `run` (`(id: string, opts?: { args?: string; sessionId?: string }) => Promise<boolean>`): Runs one. Whether a command by that id ran.

Source: [ui/src/extensions/headless/host.ts:297](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L297)

### `ExtensionCommandWire`

Interface.

A command on the wire: zidane's `CommandListing`, plus what a palette shows.

```ts
interface ExtensionCommandWire
```

**Properties**

- `bind?` (`readonly string[]`): Effective chords.
- `description?` (`string`): A line under the title.
- `extensionId?` (`string`): The registering extension; absent for a built-in.
- `id` (`string`): Published id: `<extension>.<id>`, or a built-in's.
- `slash?` (`string`): The `/` name, without the slash.
- `title` (`string`): What a palette shows for it.

Source: [ui/src/extensions/headless/host.ts:281](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L281)

### `ExtensionDialog`

Interface.

A dialog waiting on the user.

```ts
interface ExtensionDialog
```

**Properties**

- `extensionId` (`string`): The extension asking.
- `id` (`string`): Unique per dialog: answers name it.
- `request` (`DialogRequest`): What to show.
- `sessionId?` (`string`): The session it is about.

Source: [ui/src/extensions/headless/host.ts:110](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L110)

### `ExtensionDialogs`

Interface.

`ctx.ui` dialogs routed to this client. A dialog the extension withdraws (timeout, abort) leaves the
stores without an answer.

```ts
interface ExtensionDialogs
```

**Properties**

- `current` (`Readable<ExtensionDialog | null>`): The dialog to show now (the oldest non-toast one), or `null`.
- `toasts` (`Readable<readonly ExtensionDialog[]>`): The toasts showing now, oldest first.
- `answer` (`(id: string, answer: unknown) => Promise<void>`): Answers a dialog. The answer per kind: `confirm` a boolean, `prompt` the text, `select`
  `{ ids, action? }`, `form` a value per key, `askUser` a `QuestionResponse`, `presentPlan` a
  `PlanResponse`, `toast` the clicked action id. `undefined` cancels (or dismisses a toast).

Source: [ui/src/extensions/headless/host.ts:125](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L125)

### `ExtensionEffectRoute`

Interface.

One route: what it applies, and which effects it takes.

```ts
interface ExtensionEffectRoute
```

**Properties**

- `apply` (`ExtensionEffectApply`): Applies an effect it accepted.
- `priority?` (`number`): Higher first. Default 0 (an app's handler); the kit's narrow routes use more, so they win.
- `accepts?` (`(effect: ExtensionUiEffect) => boolean`): Whether it takes this effect. Absent: every effect.

Source: [ui/src/extensions/headless/effect-router.ts:27](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/effect-router.ts#L27)

### `ExtensionEffectRouter`

Interface.

An effect router.

```ts
interface ExtensionEffectRouter
```

**Properties**

- `apply` (`(effect: ExtensionUiEffect) => Promise<boolean | readonly string[]>`): Applies an effect this client asks for itself (no extension sent it), through the route that takes it.
  Resolves with what it gave: "did nothing" (`false`, no panels) when no route takes it or the route failed.
  Session ids are the ones the host's own effects carry.
- `register` (`(route: ExtensionEffectRoute) => () => void`): Adds a route. Returns its removal.

Source: [ui/src/extensions/headless/effect-router.ts:37](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/effect-router.ts#L37)

### `ExtensionIntegrationConnectionWire`

Interface.

One account connected to an integration.

```ts
interface ExtensionIntegrationConnectionWire
```

**Properties**

- `account` (`string`): The account's stable id (`'default'` when the integration names none).
- `connectedAt` (`number`): When it connected, in ms since the epoch.
- `isDefault?` (`boolean`): The integration's default connection.
- `label?` (`string`): What to show for it. Absent: the account.
- `methodId` (`string`): The method it connected through.

Source: [ui/src/extensions/headless/host.ts:226](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L226)

### `ExtensionIntegrations`

Interface.

Integrations: Settings' Connect, Disconnect and default account.

```ts
interface ExtensionIntegrations
```

**Properties**

- `list` (`Readable<readonly ExtensionIntegrationWire[]>`): Every integration with its connections.
- `connect` (`(integrationId: string, opts: { key?: string; methodId: string }) => Promise<void>`): Adds a connection: with `key` through an `apiKey` method, else runs the method (the host shows its UI).
  The same account replaces its connection; the first one becomes the default.
- `disconnect` (`(integrationId: string, opts?: { account?: string }) => Promise<void>`): Removes `account`'s connection, or every connection with no `account`.
- `setDefault` (`(integrationId: string, account: string) => Promise<void>`): Makes `account`'s connection the default.

Source: [ui/src/extensions/headless/host.ts:266](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L266)

### `ExtensionIntegrationWire`

Interface.

An integration on the wire: its spec without callbacks, and its connections.

```ts
interface ExtensionIntegrationWire
```

**Properties**

- `connection?` (`ExtensionIntegrationConnectionWire`): The default connection. Absent: not connected.
- `connections?` (`readonly ExtensionIntegrationConnectionWire[]`): Every connection, one per account, the default first. Absent: none.
- `description?` (`string`): A line saying what it connects to.
- `extensionId` (`string`): The extension that registered it.
- `icon?` (`ExtensionBadgeIcon`): Its glyph.
- `id` (`string`): The integration's id.
- `methods` (`readonly { help?: string; id: string; label: string; placeholder?: string; type: 'custom' | 'command' | 'oauth' | 'apiKey' }[]`): The ways to connect.
- `name` (`string`): What to show for it.

Source: [ui/src/extensions/headless/host.ts:240](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L240)

### `ExtensionItem`

Interface.

One contribution: zidane's `UiEntry`.

```ts
interface ExtensionItem<N extends ExtensionTokenName = ExtensionTokenName>
```

**Type parameters**

- `N` (`extends ExtensionTokenName`, default `ExtensionTokenName`)

**Properties**

- `extension` (`string`, readonly): The contributing extension's id.
- `item` (`ExtensionWireMap[N]`, readonly): The wire form.
- `key` (`string`, readonly): Unique across the host; stable for the item's life.
- `token` (`N`, readonly): The kind of contribution; picks the type of `item`.

Source: [ui/src/extensions/headless/wire.ts:154](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L154)

### `ExtensionLinkRequest`

Interface.

A link the user opened, as `ExtensionsHost.openLink` offers it to the extensions' link handlers.

```ts
interface ExtensionLinkRequest
```

**Properties**

- `sessionId?` (`string`): The session it was clicked in.
- `source` (`ExtensionLinkSource`): Where it was clicked.
- `url` (`string`): The link as clicked (a URL, or a path a file chip names).

Source: [ui/src/extensions/headless/host.ts:333](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L333)

### `ExtensionPanelChange`

Interface.

A panel that would load something new: its `subscribe` emitted, or its handle was updated.

```ts
interface ExtensionPanelChange
```

**Properties**

- `extensionId` (`string`): The extension that owns the panel.
- `panelId` (`string`): The panel's full id (`<extension>/<id>`).
- `sessionId?` (`string`): Set when only this session's content changed.

Source: [ui/src/extensions/headless/host.ts:320](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L320)

### `ExtensionProvenanceWire`

Interface.

Who changed a catalog item (Settings shows it): zidane's `CatalogItemProvenance`, with the catalog it is in.

```ts
interface ExtensionProvenanceWire extends CatalogItemProvenance
```

**Properties**

- `changedBy` (`readonly string[]`, readonly, from `CatalogItemProvenance`): Extensions that added, edited or removed the item, in replay order, without duplicates.
- `id` (`string`, readonly, from `CatalogItemProvenance`): The item id (for models, `<providerId>/<modelId>`).
- `kind` (`CatalogKind`): The catalog the item is in.
- `origin` (`ItemOrigin`, readonly, from `CatalogItemProvenance`): Who put the item in the catalog.
- `removed` (`boolean`, readonly, from `CatalogItemProvenance`): A transform removed the item: turning `removedBy` off brings it back.
- `removedBy?` (`string`, readonly, from `CatalogItemProvenance`): The extension whose transform removed it.
- `replaced?` (`ItemOrigin`, readonly, from `CatalogItemProvenance`): The origin of an item this one replaced at registration (same id).
- `source` (`string`, readonly, from `CatalogItemProvenance`): A label for `origin`: `Built in`, `Config`, `MCP server x`, `Extension x`.

Source: [ui/src/extensions/headless/host.ts:206](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L206)

### `ExtensionRpcOptions`

Interface.

Options of `ExtensionsHost.rpc`.

```ts
interface ExtensionRpcOptions
```

**Properties**

- `extensionId?` (`string`): The extension whose UI calls: its own contracts count as local (internal methods allowed).
- `signal?` (`AbortSignal`): Aborts the call: it rejects as aborted.

Source: [ui/src/extensions/headless/host.ts:349](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L349)

### `ExtensionSettings`

Interface.

The extensions' settings.

```ts
interface ExtensionSettings
```

**Properties**

- `wire` (`Readable<ExtensionSettingsWire>`): The settings of every extension, merged.
- `set?` (`(extensionId: string, key: string, value: unknown) => Promise<void>`): Writes one value. Rejects `refused` (`locked`, `invalid`). Absent: read-only here.

Source: [ui/src/extensions/headless/host.ts:218](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L218)

### `ExtensionSettingsWire`

Interface.

Every extension's settings, as Settings draws them.

```ts
interface ExtensionSettingsWire extends WireSettings
```

**Properties**

- `actions` (`WireSettingsAction[]`, from `WireSettings`): The action rows, as `listActionSummaries` produces them, with their scope.
- `category?` (`SettingsCategory`, from `WireSettings`): One extension's wire: its own sidebar group (`SettingsSchema.category`). Absent on a merged wire (see `extensionCategories`).
- `extensionCategories?` (`Record<string, SettingsCategory>`, from `WireSettings`): A merged wire: each extension's category, by extension id.
- `extensions?` (`Record<string, WireSettingsExtension>`, from `WireSettings`): Each extension's display name and icon, by extension id: the settings
  sidebar's labels and glyphs. Set by `toWireSettings` (its extension),
  `mergeWireSettings` (every part's) and `runtimeSettingsWire` (the
  definition's `displayName` and `icon`). Absent on older wires: apps
  fall back to the implicit page's label, else the id.
- `locked` (`string[]`, from `WireSettings`): Locked settings (set by a declarative config entry), as `extension:key`.
- `pages?` (`WireSettingsPage[]`, from `WireSettings`): The settings pages in sidebar order: per extension, the schema's pages,
  then its `ui` pages by `order`. Always set by `toWireSettings` and
  `mergeWireSettings`; optional so older wires (and hand-built empty ones) still type.
- `provenance?` (`readonly ExtensionProvenanceWire[]`): The catalog items extensions changed. Absent: not reported by this host.
- `schema` (`WireExtensionConfigSchema`, from `WireSettings`): The value rows, as `toWireConfigSchema` produces them.
- `values` (`Record<string, Record<string, ExtensionConfigValue>>`, from `WireSettings`): Values by extension then key, the shape of `Settings.extensionConfig`. Secrets are left out.

Source: [ui/src/extensions/headless/host.ts:212](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L212)

### `ExtensionsHost`

Interface.

The extensions host.

```ts
interface ExtensionsHost
```

**Properties**

- `commands?` (`ExtensionCommands`): The unified commands.
- `dialogs?` (`ExtensionDialogs`): `ctx.ui` dialogs and toasts routed to this client. Absent: this client shows none.
- `effects?` (`ExtensionUiEffects`): `ctx.ui` panels, navigation, composer edits and notifications routed to this client.
- `integrations?` (`ExtensionIntegrations`): Integrations and their connections.
- `items` (`ExtensionItemStores`): Every contribution, per token.
- `scope?` (`Readable<ExtensionAccessScope | null>`): The scope this client's token grants (`null`: not limited, as a local or in-process host). Action
  settings above it show disabled with why. Absent: never limited.
- `settings?` (`ExtensionSettings`): The extensions' settings, locked keys and provenance included.
- `storage?` (`ExtensionStorage`): The extensions' typed stores.
- `webviews?` (`ExtensionWebviews`): Where webviews load from. Absent: a `url` source loads as given, a `file` source shows nothing.
- `invoke?` (`<K extends keyof ExtensionCallbacks>(callbackId: K, args: ExtensionCallbacks[K]['args']) => Promise<ExtensionCallbacks[K]['result']>`): Calls an extension callback by id. Absent: nothing invokes (panels don't load, menus stay empty).
- `openLink?` (`(request: ExtensionLinkRequest) => Promise<boolean>`): Offers a link the user opened to the extensions' link handlers (`LinkHandler`, higher `priority`
  first). Resolves `true` when one opened it; `false` (or a rejection): open it the app's way. The kit
  skips it while Alt is held (`routeLink`). Absent: links open the app's way.
- `panelChanged?` (`(listener: (change: ExtensionPanelChange) => void) => () => void`): A panel would load something new (its `subscribe` emitted, or its handle was updated): reload it where
  visible. `sessionId`: only that session's content changed. Returns the unsubscribe. Absent: panels the kit
  draws reload only after an action or a folder change.
- `rpc?` (`(contract: string, method: string, input?: unknown, opts?: ExtensionRpcOptions) => Promise<unknown>`): Calls an RPC method. Rejects `rpc` with the method's error. Absent: no RPC from the UI.

Source: [ui/src/extensions/headless/host.ts:357](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L357)

### `ExtensionStorage`

Interface.

The extensions' typed stores, as the UI reads and writes them.

```ts
interface ExtensionStorage
```

**Properties**

- `set` (`(ref: ExtensionStoreRef, value: unknown) => Promise<void>`): Writes the store's value. The extension validates it; a refusal rejects (`refused` / `invalid`).
- `store` (`(ref: ExtensionStoreRef) => Readable<unknown>`): The store's value (`undefined` until known or when nothing is stored). Same ref, same store.

Source: [ui/src/extensions/headless/host.ts:198](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L198)

### `ExtensionStoreRef`

Interface.

One typed store of an extension (`ctx.storage.store`).

```ts
interface ExtensionStoreRef
```

**Properties**

- `extensionId` (`string`): The extension that owns the store.
- `name` (`string`): The store's name.
- `scope` (`'user' | 'project' | 'session'`): Where the store keeps its value: for the user, the project or one session.
- `sessionId?` (`string`): For `session` scope.

Source: [ui/src/extensions/headless/host.ts:186](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L186)

### `ExtensionUiEffectRequest`

Interface.

An effect and the id its result goes back under.

```ts
interface ExtensionUiEffectRequest
```

**Properties**

- `effect` (`ExtensionUiEffect`): What to apply.
- `id` (`string`): Names the effect in `ExtensionUiEffects.settle`.

Source: [ui/src/extensions/headless/host.ts:170](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L170)

### `ExtensionUiEffects`

Interface.

The `ctx.ui` / `ctx.composer` calls routed to this client, for the app to apply.

```ts
interface ExtensionUiEffects
```

**Properties**

- `settle` (`(id: string, result: boolean | readonly string[]) => void`): Reports what applying an effect gave (`boolean`, or the panel ids for `panel-state`).
- `subscribe` (`(listener: (request: ExtensionUiEffectRequest) => void) => () => void`): Calls `listener` for each effect, in order. Returns the unsubscribe.

Source: [ui/src/extensions/headless/host.ts:178](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L178)

### `ExtensionWebviews`

Interface.

Where the extensions' webviews load from: the app's origin policy, so every webview the kit draws follows it.

```ts
interface ExtensionWebviews
```

**Properties**

- `origin?` (`string`): The origin a page's messages must come from, and the target of replies. Default `'*'`.
- `sandbox?` (`string`): The iframe's sandbox flags. Default `'allow-scripts allow-forms'`.
- `resolveSrc` (`(webview: WebviewWire, extension: string) => string | null`): The URL a webview loads (a `file` source made a URL the app serves), or `null`: not served here, or
  not yet (`subscribe` tells when it may have changed).
- `subscribe?` (`(listener: () => void) => () => void`): Calls `listener` when a URL may have changed (one minted later). Returns the unsubscribe.

Source: [ui/src/extensions/headless/host.ts:305](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L305)

### `ExtensionWireMap`

Interface.

The wire form of each token the kit draws, by token name.

```ts
interface ExtensionWireMap
```

**Properties**

- `badge-action` (`BadgeActionWire`): An action offered on composer badges.
- `context-section` (`ContextSectionWire`): A section of the context breakdown or the context panel.
- `link-handler` (`LinkHandlerWire`): Opens matching links before the app (the kit routes links only while one exists).
- `panel` (`PanelWire`): A side or home panel.
- `reference` (`ReferenceProviderWire`): A source of references the user can add to a message.
- `renderer` (`RendererWire`): A component that draws a block, a code language, a tool result or an artifact.
- `screen` (`ScreenWire`): A full-screen view, or a modal.
- `settings-page` (`SettingsPageWire`): A Settings page under an extension.
- `sidebar-decoration` (`SidebarDecorationWire`): Extra data on session rows.
- `sidebar-filter` (`SidebarFilterWire`): A filter in the sidebar's filter menu.
- `sidebar-group` (`SidebarGroupWire`): A grouping in the sidebar's filter menu.
- `sidebar-row` (`SidebarRowWire`): A row among a space's sessions.
- `sidebar-sort` (`SidebarSortWire`): A sort in the sidebar's filter menu.
- `slot` (`SlotWire`): A small item in a named place of the app.
- `space` (`SpaceWire`): A space in the switcher, with its base query.
- `theme` (`Theme`): A color theme.
- `webview` (`WebviewWire`): A sandboxed web page.

Source: [ui/src/extensions/headless/wire.ts:92](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L92)

### `LinkRouteOptions`

Interface.

Where and how a link was opened.

```ts
interface LinkRouteOptions
```

**Properties**

- `bypass?` (`boolean`): Opens it the app's way at once (the user held Alt).
- `sessionId?` (`string`): The session it was clicked in.
- `source` (`ExtensionLinkSource`): Where it was clicked.

Source: [ui/src/extensions/headless/links.ts:11](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/links.ts#L11)

### `UiEffectChannel`

Interface.

An effect channel.

```ts
interface UiEffectChannel
```

**Properties**

- `effects` (`ExtensionUiEffects`): `ExtensionsHost.effects`.
- `apply` (`(effect: ExtensionUiEffect) => Promise<ExtensionUiEffectResult>`): Hands an effect to the app; resolves with what it settled.

Source: [ui/src/extensions/headless/effect-channel.ts:12](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/effect-channel.ts#L12)

### `WebviewRpcBridge`

Interface.

A bridge for one page.

```ts
interface WebviewRpcBridge
```

**Properties**

- `dispose` (`() => void`): Aborts calls in flight and posts nothing more.
- `handle` (`(data: unknown) => boolean`): Handles one message from the page. `false`: not a bridge request (ignored).

Source: [ui/src/extensions/headless/webview-bridge.ts:57](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L57)

### `WebviewRpcBridgeOptions`

Interface.

Options of [`createWebviewRpcBridge`](https://zidane.si/docs/reference/ui-extensions-headless.md#createWebviewRpcBridge).

```ts
interface WebviewRpcBridgeOptions
```

**Properties**

- `contracts` (`readonly string[]`): The contract ids the webview lists (`WebviewWire.rpc`).
- `extensionId` (`string`): The webview's extension: its UI is the caller.
- `rpc?` (`(contract: string, method: string, input?: unknown, opts?: ExtensionRpcOptions) => Promise<unknown>`): The host's RPC. Absent: every call answers `rpc.unavailable`.
- `post` (`(message: WebviewRpcResult) => void`): Posts a reply to the page.

Source: [ui/src/extensions/headless/webview-bridge.ts:45](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L45)

### `WebviewRpcRequest`

Interface.

A request from the page.

```ts
interface WebviewRpcRequest
```

**Properties**

- `contract` (`string`): The RPC contract to call; the webview's `rpc` list must name it.
- `id` (`string | number`): The page's id for the call; the reply carries it.
- `input?` (`unknown`): The method's input.
- `method` (`string`): The contract's method to call.
- `type` (`'zidane:rpc'`): Marks the message as an RPC request.

Source: [ui/src/extensions/headless/webview-bridge.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L21)

## Types

### `BadgeActionWire`

Type.

Badge actions, and the badges they apply to: zidane's `BadgeActionWire` (`zidane/extensions`).

```ts
type BadgeActionWire = Api.BadgeActionWire
```

Source: [ui/src/extensions/headless/wire.ts:62](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L62)

### `ComponentWire`

Type.

A component an item names, an export of the extension's `ui.tsx` bundle and its JSON props: zidane's `ComponentWire` (`zidane/extensions`).

```ts
type ComponentWire = Api.ComponentWire
```

Source: [ui/src/extensions/headless/wire.ts:13](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L13)

### `ContextSectionWire`

Type.

A context breakdown or context panel section: zidane's `ContextSectionWire` (`zidane/extensions`).

```ts
type ContextSectionWire = Api.ContextSectionWire
```

Source: [ui/src/extensions/headless/wire.ts:65](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L65)

### `DialogKind`

Type.

The kinds of [`DialogRequestWire`](https://zidane.si/docs/reference/ui-extensions-headless.md#DialogRequestWire).

```ts
type DialogKind = DialogRequestWire['kind']
```

Source: [ui/src/extensions/headless/wire.ts:175](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L175)

### `DialogRequestWire`

Type.

A dialog `ctx.ui` asked for, by kind: zidane's `DialogRequest` (`zidane/extensions`). A `form`'s
`settings` holds the initial values, and its answer is a value per key.

```ts
type DialogRequestWire = Api.DialogRequest
```

Source: [ui/src/extensions/headless/wire.ts:172](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L172)

### `ExtensionAccessScope`

Type.

The least client token scope that may run something (`chat` ⊂ `approve` ⊂ `admin`): zidane's
`AccessScope`, the scope of an action setting.

```ts
type ExtensionAccessScope = 'chat' | 'admin'
```

Source: [ui/src/extensions/headless/host.ts:346](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L346)

### `ExtensionCallbackId`

Type.

A callback id.

```ts
type ExtensionCallbackId = keyof ExtensionCallbacks
```

Source: [ui/src/extensions/headless/host.ts:104](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L104)

### `ExtensionComposerFile`

Type.

A file `ctx.composer.attach` sends: a path, or bytes in base64.

```ts
type ExtensionComposerFile =
  | { path: string }
  | { data: string; mimeType: string; name: string }
```

Source: [ui/src/extensions/headless/host.ts:139](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L139)

### `ExtensionEffectApply`

Type.

Applies one effect. A throw or a rejection reports "did nothing".

```ts
type ExtensionEffectApply = (effect: ExtensionUiEffect) => ExtensionEffectOutcome | Promise<ExtensionEffectOutcome>
```

Source: [ui/src/extensions/headless/effect-router.ts:22](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/effect-router.ts#L22)

### `ExtensionEffectOutcome`

Type.

What applying an effect gave: whether it did, the open panel ids for `panel-state`, nothing for `notify`.

```ts
type ExtensionEffectOutcome = boolean | readonly string[] | void
```

Source: [ui/src/extensions/headless/effect-router.ts:19](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/effect-router.ts#L19)

### `ExtensionItemStores`

Type.

The items of every token, each a store.

```ts
type ExtensionItemStores = { readonly [N in ExtensionTokenName]: Readable<readonly ExtensionItem<N>[]> }
```

Source: [ui/src/extensions/headless/host.ts:107](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L107)

### `ExtensionLinkSource`

Type.

Where a link was clicked: zidane's `LinkSource`.

```ts
type ExtensionLinkSource =
  | 'transcript'
  | 'chip'
  | 'panel'
  | 'badge'
  | 'terminal'
  | 'other'
```

Source: [ui/src/extensions/headless/host.ts:330](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L330)

### `ExtensionNavigateTarget`

Type.

Where `ctx.ui.navigate` goes. Screen ids are full (`<extension>/<id>`).

```ts
type ExtensionNavigateTarget =
  | { screen: string }
  | { session: string }
  | { newSession: true }
```

Source: [ui/src/extensions/headless/host.ts:142](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L142)

### `ExtensionsError`

Type.

Why a host call failed, for the UI to word through its labels.

```ts
type ExtensionsError =
  | { code: 'unavailable' }
  | { code: 'failed'; message: string }
  | { code: 'rpc'; data?: unknown; message: string; type: string }
  | { code: 'refused'; message?: string; reason: 'locked' | 'invalid' | 'not-allowed' }
```

Source: [ui/src/extensions/headless/host.ts:30](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L30)

### `ExtensionsLabels`

Type.

The shape of the extensions label dictionary.

```ts
type ExtensionsLabels = typeof DEFAULT_EXTENSIONS_LABELS
```

Source: [ui/src/extensions/headless/labels.ts:124](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/labels.ts#L124)

### `ExtensionTokenName`

Type.

A token the kit draws. (Native menus are the desktop app's own.)

```ts
type ExtensionTokenName = keyof ExtensionWireMap
```

Source: [ui/src/extensions/headless/wire.ts:130](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L130)

### `ExtensionUiEffect`

Type.

One `ctx.ui` / `ctx.composer` call for the app to apply: zidane's `UiClientPort` calls.

```ts
type ExtensionUiEffect =
  | { action: 'open' | 'close' | 'toggle'; focus?: PanelFocus; kind: 'panel'; panelId: string; sessionId?: string }
  | { kind: 'panel-state'; sessionId?: string }
  | { kind: 'navigate'; to: ExtensionNavigateTarget }
  | { kind: 'composer'; op: { op: 'insert'; text: string } | { op: 'setText'; text: string } | { files: readonly ExtensionComposerFile[]; op: 'attach' }; sessionId?: string }
  | { body?: string; extensionId: string; kind: 'notify'; sessionId?: string; sound?: boolean; title: string }
  | { chord: string; kind: 'keymap'; sessionId?: string }
```

Source: [ui/src/extensions/headless/host.ts:145](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/host.ts#L145)

### `ExtensionUiEffectResult`

Type.

What applying an effect gave: whether it did, the open panels, or nothing for a notification.

```ts
type ExtensionUiEffectResult = boolean | readonly string[] | undefined
```

Source: [ui/src/extensions/headless/effect-channel.ts:9](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/effect-channel.ts#L9)

### `LinkHandlerWire`

Type.

A link handler (its `match` and `open` stay with the extension): zidane's `LinkHandlerWire` (`zidane/extensions`).

```ts
type LinkHandlerWire = Api.LinkHandlerWire
```

Source: [ui/src/extensions/headless/wire.ts:89](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L89)

### `PanelWire`

Type.

A side or home panel (its `load`, `onAction` and `subscribe` stay with the extension): zidane's `PanelWire` (`zidane/extensions`).

```ts
type PanelWire = Api.PanelWire
```

Source: [ui/src/extensions/headless/wire.ts:35](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L35)

### `RendererTarget`

Type.

What a renderer draws: a custom block id, a code-block language, a tool's result, or an artifact kind's detail.

```ts
type RendererTarget = Api.RendererWire['for']
```

Source: [ui/src/extensions/headless/wire.ts:44](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L44)

### `RendererWire`

Type.

A renderer: a component, with a markdown fallback: zidane's `RendererWire` (`zidane/extensions`).

```ts
type RendererWire = Api.RendererWire
```

Source: [ui/src/extensions/headless/wire.ts:47](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L47)

### `ScreenWire`

Type.

A full-screen view, or a modal: zidane's `ScreenWire` (`zidane/extensions`).

```ts
type ScreenWire = Api.ScreenWire
```

Source: [ui/src/extensions/headless/wire.ts:41](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L41)

### `SelectOptionWire`

Type.

One option of a select dialog.

```ts
type SelectOptionWire = Extract<DialogRequestWire, { kind: 'select' }>['options'][number]
```

Source: [ui/src/extensions/headless/wire.ts:166](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L166)

### `SettingsPageWire`

Type.

A Settings page under an extension: zidane's `SettingsPageWire` (`zidane/extensions`).

```ts
type SettingsPageWire = Api.SettingsPageWire
```

Source: [ui/src/extensions/headless/wire.ts:56](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L56)

### `SettingValue`

Type.

A setting's value as a form holds it.

```ts
type SettingValue = ExtensionConfigValue
```

Source: [ui/src/extensions/headless/select.ts:177](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/select.ts#L177)

### `SidebarDecorationWire`

Type.

Extra data on the rows of matching sessions: zidane's `SidebarDecorationWire` (`zidane/extensions`).

```ts
type SidebarDecorationWire = Api.SidebarDecorationWire
```

Source: [ui/src/extensions/headless/wire.ts:80](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L80)

### `SidebarFilterWire`

Type.

A filter an extension offers in every space's filter menu: zidane's `SidebarFilterWire` (`zidane/extensions`).

```ts
type SidebarFilterWire = Api.SidebarFilterWire
```

Source: [ui/src/extensions/headless/wire.ts:71](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L71)

### `SidebarGroupWire`

Type.

A grouping an extension offers in the filter menu: zidane's `SidebarGroupWire` (`zidane/extensions`).

```ts
type SidebarGroupWire = Api.SidebarGroupWire
```

Source: [ui/src/extensions/headless/wire.ts:77](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L77)

### `SidebarRowActionWire`

Type.

One action of a sidebar row's menu: zidane's `SidebarRowActionWire` (`zidane/extensions`).

```ts
type SidebarRowActionWire = Api.SidebarRowActionWire
```

Source: [ui/src/extensions/headless/wire.ts:86](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L86)

### `SidebarRowWire`

Type.

A row an extension lists among a space's sessions: zidane's `SidebarRowWire` (`zidane/extensions`).

```ts
type SidebarRowWire = Api.SidebarRowWire
```

Source: [ui/src/extensions/headless/wire.ts:83](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L83)

### `SidebarSortWire`

Type.

A sort an extension offers in the filter menu: zidane's `SidebarSortWire` (`zidane/extensions`).

```ts
type SidebarSortWire = Api.SidebarSortWire
```

Source: [ui/src/extensions/headless/wire.ts:74](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L74)

### `SlotName`

Type.

The places every app knows. An app without the place ignores the item.

```ts
type SlotName = Api.SlotWire['at']
```

Source: [ui/src/extensions/headless/wire.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L16)

### `SlotWire`

Type.

A small item in a slot: a status line, a banner, a composer badge: zidane's `SlotWire` (`zidane/extensions`).

```ts
type SlotWire = Api.SlotWire
```

Source: [ui/src/extensions/headless/wire.ts:38](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L38)

### `SpaceWire`

Type.

A space an extension adds to the switcher, with its base query: zidane's `SpaceWire` (`zidane/extensions`).

```ts
type SpaceWire = Api.SpaceWire
```

Source: [ui/src/extensions/headless/wire.ts:68](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L68)

### `WebviewRpcResult`

Type.

The reply to a request.

```ts
type WebviewRpcResult =
  | { id: string | number; ok: true; output: unknown; type: typeof WEBVIEW_RPC_RESULT }
  | { error: { data?: unknown; message: string; type: string }; id: string | number; ok: false; type: typeof WEBVIEW_RPC_RESULT }
```

Source: [ui/src/extensions/headless/webview-bridge.ts:35](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/webview-bridge.ts#L35)

### `WebviewWire`

Type.

A sandboxed web page in a panel or a screen (a `file` source is relative to the extension's folder): zidane's `WebviewWire` (`zidane/extensions`).

```ts
type WebviewWire = Api.WebviewWire
```

Source: [ui/src/extensions/headless/wire.ts:59](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L59)

### `WireSettings`

Type.

Everything a Settings UI needs to draw settings (values without secrets, locked keys as `extension:key`): zidane's `WireSettings` (`zidane/extensions`).

```ts
type WireSettings = Api.WireSettings
```

Source: [ui/src/extensions/headless/wire.ts:50](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L50)

### `WireSettingsPage`

Type.

One page of an extension's settings in the settings sidebar: zidane's `WireSettingsPage` (`zidane/extensions`).

```ts
type WireSettingsPage = Api.WireSettingsPage
```

Source: [ui/src/extensions/headless/wire.ts:53](https://github.com/Tahul/zidane/blob/main/ui/src/extensions/headless/wire.ts#L53)