# zidane-ui/palette

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

## Components

### `CommandPalette`

Component.

Renders the command palette: sources, levels and running from `controller`, the surface from `PalettePanel`.

```ts
function CommandPalette(props: CommandPaletteProps): Element
```

**Parameters**

- `props` (`CommandPaletteProps`): [`CommandPaletteProps`](https://zidane.si/docs/reference/ui-palette.md#CommandPaletteProps).

**Returns** `Element`

**Props**

- `busy?` (`boolean`): Turns the header spinner while the app's own search is out.
- `controller` (`PaletteController`): The palette's state, from `usePaletteController`.
- `extraGroups?` (`readonly PaletteSection<PaletteItem>[]`): Groups shown after the ranked ones, never reordering them. Keep the array stable.

Source: [ui/src/palette/CommandPalette.tsx:32](https://github.com/Tahul/zidane/blob/main/ui/src/palette/CommandPalette.tsx#L32)

### `PaletteDialog`

Component.

Renders the palette surface in the modal slot `usePaletteModalSlot` opened. Esc and the backdrop tell the palette;
the palette closing (Cmd+K again, an item ran) closes the slot.

```ts
function PaletteDialog(props: PaletteDialogProps): Element
```

**Parameters**

- `props` (`PaletteDialogProps`): [`PaletteDialogProps`](https://zidane.si/docs/reference/ui-palette.md#PaletteDialogProps).

**Returns** `Element`

**Props**

- `archive?` (`'all' | 'active' | 'archived'`): Which sessions `sessions` was loaded with.
- `className?` (`string`): Classes merged on the surface's root.
- `context` (`PaletteContext`): The snapshot handed to every source. Keep it stable while nothing in it changed.
- `onInsert?` (`(text: string) => void`): Receives an `insert` result's text.
- `onPrompt?` (`(text: string) => void`): Receives a `prompt` result's text.
- `rows?` (`PaletteRows`): The app rows, from `createPaletteRows` (module scope). Absent: the surface's default rows.
- `sessions?` (`readonly PaletteSession[]`): Every loaded session, for the matches inside conversations. Absent: no "In conversations" group.
- `style?` (`CSSProperties`): Inline styles on the surface's root.

Source: [ui/src/palette/PaletteDialog.tsx:62](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteDialog.tsx#L62)

### `PaletteProvider`

Component.

Holds the palette's state (open, sources, recents) for the components below it.

```ts
function PaletteProvider(props: PaletteProviderProps): Element
```

**Parameters**

- `props` (`PaletteProviderProps`): The `host`, optional `labels` and `createRankWorker`, and the `children`.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The app's components.
- `createRankWorker?` (`() => Worker`): Starts a worker running `zidane-ui/palette/rank.worker`, so a big catalog
  (a project's files) is ranked off the main thread. Without one, every
  query ranks in place.
- `host?` (`PaletteHost`): The data the built-in sources read and where recents persist. Read once, at mount.
- `labels?` (`Partial<{ paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }>`): Overrides for the palette area's strings. Keys you leave out keep the default English label.

Source: [ui/src/palette/PaletteProvider.tsx:72](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L72)

## Functions

### `createPaletteRows`

Function.

Builds the palette's app rows over what the app knows about its sessions. Call it once, at module scope: the
hooks it is handed run inside the rows.

```ts
function createPaletteRows(options?: PaletteRowsOptions): PaletteRows
```

**Parameters**

- `options?` (`PaletteRowsOptions`, default `{}`): [`PaletteRowsOptions`](https://zidane.si/docs/reference/ui-palette.md#PaletteRowsOptions).

**Returns** `PaletteRows`

Source: [ui/src/palette/PaletteRows.tsx:117](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteRows.tsx#L117)

### `paletteVerbOf`

Function.

What Enter does to a session, a conversation match or a file; the surface names the rest.

```ts
function paletteVerbOf(
  row: PaletteRowData<PaletteItem>,
  labels: { paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string },
): string | undefined
```

**Parameters**

- `row` (`PaletteRowData<PaletteItem>`): The row under the cursor.
- `labels` (`{ paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }`): The palette labels.

**Returns** `string | undefined`

Source: [ui/src/palette/PaletteRows.tsx:84](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteRows.tsx#L84)

### `useActionsPaletteSource`

Function.

Registers the key command registry's actions as a palette source. Registers again only when the set of bound
actions changes: the rows run the handlers in effect when picked.

```ts
function useActionsPaletteSource(): void
```

Source: [ui/src/palette/app-sources.ts:27](https://github.com/Tahul/zidane/blob/main/ui/src/palette/app-sources.ts#L27)

### `useConversationHit`

Function.

The content hit behind a palette row, if it is one.

```ts
function useConversationHit(itemId: string): PaletteConversationHit | undefined
```

**Parameters**

- `itemId` (`string`): The row's item id.

**Returns** `PaletteConversationHit | undefined`

Source: [ui/src/palette/useConversationSearch.ts:113](https://github.com/Tahul/zidane/blob/main/ui/src/palette/useConversationSearch.ts#L113)

### `useConversationSearch`

Function.

Searches inside conversations as the query settles. Nothing (and no request) when the host leaves
`searchConversations` out.

```ts
function useConversationSearch(
  query: string,
  options: ConversationSearchOptions,
): ConversationSearch
```

**Parameters**

- `query` (`string`): The palette's query as typed.
- `options` (`ConversationSearchOptions`): [`ConversationSearchOptions`](https://zidane.si/docs/reference/ui-palette.md#ConversationSearchOptions).

**Returns** `ConversationSearch`

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

### `usePalette`

Function.

The palette's state and actions. Re-renders on every state change. Throws outside a [`PaletteProvider`](https://zidane.si/docs/reference/ui-palette.md#PaletteProvider).

```ts
function usePalette(): PaletteApi
```

**Returns** `PaletteApi`

Source: [ui/src/palette/PaletteProvider.tsx:101](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L101)

### `usePaletteActions`

Function.

The palette's stable actions. Never re-renders its caller. Throws outside a [`PaletteProvider`](https://zidane.si/docs/reference/ui-palette.md#PaletteProvider).

```ts
function usePaletteActions(): PaletteActions
```

**Returns** `PaletteActions`

Source: [ui/src/palette/PaletteProvider.tsx:108](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L108)

### `usePaletteController`

Function.

The command palette's state: gather, rank, levels and running. Call it inside a `PaletteProvider`.

```ts
function usePaletteController(options: PaletteControllerOptions): PaletteController
```

**Parameters**

- `options` (`PaletteControllerOptions`): The context and where agent-bound results go.

**Returns** `PaletteController`

Source: [ui/src/palette/usePaletteController.ts:115](https://github.com/Tahul/zidane/blob/main/ui/src/palette/usePaletteController.ts#L115)

### `usePaletteHost`

Function.

The [`PaletteHost`](https://zidane.si/docs/reference/ui-palette-headless.md#PaletteHost) given to the nearest [`PaletteProvider`](https://zidane.si/docs/reference/ui-palette.md#PaletteProvider), if any.

```ts
function usePaletteHost(): PaletteHost | undefined
```

**Returns** `PaletteHost | undefined`

Source: [ui/src/palette/PaletteProvider.tsx:115](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L115)

### `usePaletteLabels`

Function.

The palette area's strings, with the provider's overrides.

```ts
function usePaletteLabels(): { paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }
```

**Returns** `{ paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }`

Source: [ui/src/palette/PaletteProvider.tsx:120](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L120)

### `usePaletteModalSlot`

Function.

Opens the palette surface in the modal slot while the palette is open, and closes the palette when another modal
takes the slot. Mount it once, under `ModalProvider` and `PaletteProvider`.

```ts
function usePaletteModalSlot(options: PaletteModalSlotOptions): void
```

**Parameters**

- `options` (`PaletteModalSlotOptions`): [`PaletteModalSlotOptions`](https://zidane.si/docs/reference/ui-palette.md#PaletteModalSlotOptions).

Source: [ui/src/palette/PaletteDialog.tsx:159](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteDialog.tsx#L159)

### `usePaletteSource`

Function.

Registers a source for the component's lifetime. `source` is read through
a ref, so callers can pass a fresh object every render without churning
the registry; it registers again only when its id changes. `null`
registers nothing.

```ts
function usePaletteSource(source: PaletteProvider | null): void
```

**Parameters**

- `source` (`PaletteProvider | null`): The source, or `null`.

Source: [ui/src/palette/PaletteProvider.tsx:132](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L132)

### `useRankedItems`

Function.

Ranks `items` for `query`, off the main thread for a big catalog when the provider has a rank worker.

```ts
function useRankedItems(
  items: readonly PaletteItem[],
  query: string,
  recents: readonly string[],
): RankedItems
```

**Parameters**

- `items` (`readonly PaletteItem[]`): The catalog.
- `query` (`string`): The query.
- `recents` (`readonly string[]`): Recently run ids, for the empty-query order.

**Returns** `RankedItems`

Source: [ui/src/palette/useRankedItems.ts:67](https://github.com/Tahul/zidane/blob/main/ui/src/palette/useRankedItems.ts#L67)

### `useSessionRank`

Function.

A session's palette rank: 0 when it needs the user (attention, a pending approval or question), 1 while it runs,
else 2.

```ts
function useSessionRank(
  peekRunning: (sessionId: string) => boolean,
): (sessionId: string) => SessionRank
```

**Parameters**

- `peekRunning` (`(sessionId: string) => boolean`): Whether the app sees the session running now (read when ranking, not subscribed).

**Returns** `(sessionId: string) => SessionRank`

Source: [ui/src/palette/app-sources.ts:48](https://github.com/Tahul/zidane/blob/main/ui/src/palette/app-sources.ts#L48)

## Constants

### `CONVERSATION_SEARCH_MIN_CHARS`

Constant.

Shorter queries match nearly every conversation: not worth a scan.

```ts
const CONVERSATION_SEARCH_MIN_CHARS = 2
```

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

### `ConversationHitsContext`

Constant.

The hits of the rows on show, for the rows that render them.

```ts
const ConversationHitsContext: Context<ReadonlyMap<string, PaletteConversationHit>>
```

Source: [ui/src/palette/useConversationSearch.ts:106](https://github.com/Tahul/zidane/blob/main/ui/src/palette/useConversationSearch.ts#L106)

### `PALETTE_MODAL_ID`

Constant.

The palette's modal-slot id (`modal.open({ id })`), shared by the slot bridge and the surface.

```ts
const PALETTE_MODAL_ID = 'palette'
```

Source: [ui/src/palette/PaletteDialog.tsx:32](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteDialog.tsx#L32)

## Interfaces

### `ConversationSearch`

Interface.

What [`useConversationSearch`](https://zidane.si/docs/reference/ui-palette.md#useConversationSearch) returns.

```ts
interface ConversationSearch
```

**Properties**

- `hits` (`ReadonlyMap<string, PaletteConversationHit>`): Each row's hit, by item id (match count, age).
- `rows` (`readonly RankedPaletteItem[]`): The "In conversations" rows, in the host's order.
- `searching` (`boolean`): A scan for the current query is on its way.

Source: [ui/src/palette/useConversationSearch.ts:23](https://github.com/Tahul/zidane/blob/main/ui/src/palette/useConversationSearch.ts#L23)

### `ConversationSearchOptions`

Interface.

Options of [`useConversationSearch`](https://zidane.si/docs/reference/ui-palette.md#useConversationSearch).

```ts
interface ConversationSearchOptions
```

**Properties**

- `archive?` (`'all' | 'active' | 'archived'`): Which sessions `sessions` was loaded with.
- `enabled` (`boolean`): False in a nested picker: content search is a root-level thing.
- `listed` (`ReadonlySet<string>`): Session ids the ranked rows already show.
- `sessions` (`readonly PaletteSession[]`): Every loaded session.

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

### `PaletteActions`

Interface.

What never changes: callers that only open the palette or register a source never re-render with it.

```ts
interface PaletteActions
```

**Properties**

- `close` (`() => void`): Closes the palette.
- `open` (`() => void`): Opens the palette.
- `registerSource` (`(source: PaletteProvider) => () => void`): Registers a source for as long as the caller wants it; returns the unregister.
- `toggle` (`() => void`): Opens a closed palette, closes an open one (the Cmd+K entry point).

Source: [ui/src/palette/PaletteProvider.tsx:31](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L31)

### `PaletteApi`

Interface.

The palette's state and actions, from [`usePalette`](https://zidane.si/docs/reference/ui-palette.md#usePalette).

```ts
interface PaletteApi extends PaletteActions, PaletteState
```

**Properties**

- `close` (`() => void`, from `PaletteActions`): Closes the palette.
- `isOpen` (`boolean`, from `PaletteState`): Whether the palette is open.
- `markRecent` (`(id: string) => void`): Puts an item id first in the recents.
- `open` (`() => void`, from `PaletteActions`): Opens the palette.
- `recents` (`readonly string[]`, from `PaletteState`): Recently run item ids, most recent first.
- `registerSource` (`(source: PaletteProvider) => () => void`, from `PaletteActions`): Registers a source for as long as the caller wants it; returns the unregister.
- `sources` (`readonly PaletteProvider[]`, from `PaletteState`): Every registered source, in registration order.
- `toggle` (`() => void`, from `PaletteActions`): Opens a closed palette, closes an open one (the Cmd+K entry point).
- `version` (`number`, from `PaletteState`): Bumps whenever an open palette's source signalled a change through `subscribe`.

Source: [ui/src/palette/PaletteProvider.tsx:43](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L43)

### `PaletteContext`

Interface.

JSON-safe snapshot of the host handed to providers. Never holds functions.

```ts
interface PaletteContext
```

**Properties**

- `busy?` (`boolean`): A run is in flight on the active session.
- `cwd?` (`string`): Working directory of the active session.
- `host` (`PaletteHost`): Which app is asking.
- `sessionId?` (`string`): Id of the active session.

Source: [dist/index-Bq87OcGy.d.ts:28132](https://github.com/Tahul/zidane/blob/main/dist/index-Bq87OcGy.d.ts#L28132)

### `PaletteController`

Interface.

The palette's state and handlers, for [`CommandPalette`](https://zidane.si/docs/reference/ui-palette.md#CommandPalette).

```ts
interface PaletteController
```

**Properties**

- `back` (`() => void`): Leaves the nested level. Stable.
- `clearScope` (`() => void`): Searches every section again. Stable.
- `close` (`() => void`): Closes the palette.
- `cursor` (`number`): The highlighted row's index.
- `cycleScope` (`() => void`): Scopes the root search to the next section; after the last, back to every section. Stable while `scopes` holds.
- `inputRef` (`RefObject<HTMLInputElement | null>`): The query field (focused again when a level opens).
- `loading` (`boolean`): The root items have not landed yet.
- `nested` (`boolean`): Whether a picker's level is shown.
- `notice` (`PaletteNotice | null`): The notice line (a `notify` result or a failed run).
- `placeholder` (`string | undefined`): The query field's placeholder.
- `query` (`string`): The query typed.
- `ranked` (`readonly RankedPaletteItem[]`): The ranked rows of the current level.
- `run` (`(row: PaletteRowData<PaletteItem>) => void`): Runs a row. Stable.
- `running` (`boolean`): A row is running.
- `scope` (`string | null`): The section the root search is scoped to; `null` searches every section.
- `scopes` (`readonly string[]`): The sections a scope can be: the root items' groups in order, then `extraScopes`.
- `sections` (`readonly PaletteGroup[]`): `ranked` grouped into sections.
- `setCursor` (`(index: number) => void`): Moves the highlight.
- `setQuery` (`(query: string) => void`): Sets the query.
- `settled` (`boolean`): The rows are for the query typed.
- `title` (`string | undefined`): The nested level's title.

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

### `PaletteControllerOptions`

Interface.

Options of [`usePaletteController`](https://zidane.si/docs/reference/ui-palette.md#usePaletteController).

```ts
interface PaletteControllerOptions
```

**Properties**

- `context` (`PaletteContext`): The snapshot handed to every source. Keep it stable while nothing in it changed.
- `extraScopes?` (`readonly string[]`): Sections the app lists itself (its own groups), offered as scopes after the root items' groups. Keep it stable.
- `onInsert?` (`(text: string) => void`): Receives an `insert` result's text (the palette closes first).
- `onPrompt?` (`(text: string) => void`): Receives a `prompt` result's text (the palette closes first).
- `recentIdOf?` (`(item: PaletteItem) => string`): The id Recent remembers for a run root item. Default: the item's own id.

Source: [ui/src/palette/usePaletteController.ts:51](https://github.com/Tahul/zidane/blob/main/ui/src/palette/usePaletteController.ts#L51)

### `PaletteDialogProps`

Interface.

Props for [`PaletteDialog`](https://zidane.si/docs/reference/ui-palette.md#PaletteDialog).

```ts
interface PaletteDialogProps
```

**Properties**

- `archive?` (`'all' | 'active' | 'archived'`): Which sessions `sessions` was loaded with.
- `className?` (`string`): Classes merged on the surface's root.
- `context` (`PaletteContext`): The snapshot handed to every source. Keep it stable while nothing in it changed.
- `onInsert?` (`(text: string) => void`): Receives an `insert` result's text.
- `onPrompt?` (`(text: string) => void`): Receives a `prompt` result's text.
- `rows?` (`PaletteRows`): The app rows, from `createPaletteRows` (module scope). Absent: the surface's default rows.
- `sessions?` (`readonly PaletteSession[]`): Every loaded session, for the matches inside conversations. Absent: no "In conversations" group.
- `style?` (`CSSProperties`): Inline styles on the surface's root.

Source: [ui/src/palette/PaletteDialog.tsx:37](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteDialog.tsx#L37)

### `PaletteItem`

Interface.

An entry in the command palette.

```ts
interface PaletteItem
```

**Properties**

- `checked?` (`boolean`): For `toggle` items.
- `description?` (`string`): Secondary text shown beside the title.
- `disabled?` (`string`): Reason the item cannot run right now; it stays listed, muted.
- `group` (`string`): Section header. Hosts order groups by first appearance after `Recent`.
- `icon?` (`PanelIcon`): Icon for each renderer.
- `id` (`string`): Stable, unique across providers: `builtin:openSettings`, `slash:compact`, `<extension>/<id>`.
- `keybinding?` (`string`): Resolved chord spec (`ctrl+shift+k`); the host formats it for display.
- `keywords?` (`readonly string[]`): Extra search terms not shown in the row.
- `kind?` (`PaletteItemKind`): How the item behaves. Treated as `action` when omitted.
- `searchOnly?` (`boolean`): Only appears once the query matches it: bulk catalogs (every file in
  the project) stay out of the empty-query listing but are one keystroke
  away.
- `source` (`string`): Provider that owns `run` for this item. Stamped by the aggregator.
- `title` (`string`): Text shown in the row.

Source: [dist/index-Bq87OcGy.d.ts:28101](https://github.com/Tahul/zidane/blob/main/dist/index-Bq87OcGy.d.ts#L28101)

### `PaletteModalSlotOptions`

Interface.

Options of [`usePaletteModalSlot`](https://zidane.si/docs/reference/ui-palette.md#usePaletteModalSlot).

```ts
interface PaletteModalSlotOptions
```

**Properties**

- `context` (`PaletteContext`): The snapshot the surface opens with (reopening picks up a new one).
- `cwd?` (`string`): The project folder: the extension providers' live updates stay on for it while open.
- `render` (`(context: PaletteContext) => ReactNode`): The surface, usually a `PaletteDialog`.

Source: [ui/src/palette/PaletteDialog.tsx:144](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteDialog.tsx#L144)

### `PaletteProviderProps`

Interface.

Props for [`PaletteProvider`](https://zidane.si/docs/reference/ui-palette.md#PaletteProvider).

```ts
interface PaletteProviderProps
```

**Properties**

- `children` (`ReactNode`): The app's components.
- `createRankWorker?` (`() => Worker`): Starts a worker running `zidane-ui/palette/rank.worker`, so a big catalog
  (a project's files) is ranked off the main thread. Without one, every
  query ranks in place.
- `host?` (`PaletteHost`): The data the built-in sources read and where recents persist. Read once, at mount.
- `labels?` (`Partial<{ paletteActionTitles: Record<string, string>; paletteAppearanceMode: Record<'dark' | 'light' | 'system', string>; paletteAppearanceModeHint: string; paletteAppearanceSettings: string; paletteCloseSidePanel: string; paletteCodeCompletion: string; paletteCommandGone: string; paletteCommandsGroup: string; paletteCompactTranscript: string; paletteCompactTranscriptHint: string; paletteConversationsGroup: string; paletteDiagnostics: Record<'off' | 'lsp' | 'tools', string>; paletteDiagnosticsHint: string; paletteEditFiles: string; paletteEditorGroup: string; paletteEditorSettings: string; paletteFileCount: (count: number) => string; paletteFilesGroup: string; paletteFilesPlaceholder: string; paletteFilesTitle: string; paletteFilesTreeSide: Record<'right' | 'left', string>; paletteFilesTreeSideHint: string; paletteGoToFile: string; paletteHoverDocs: string; paletteImportRepo: string; paletteImportRepoHint: string; paletteMatchCount: (count: number) => string; paletteModelGroup: string; paletteNavigateGroup: string; paletteNeedsLsp: string; paletteNeedsSession: string; paletteOpenAndFind: string; paletteOpenFile: string; paletteOpenSidePanel: string; palettePanelAttention: (count: number, waiting: boolean) => string; palettePanelsGroup: string; palettePanelTitle: (label: string) => string; paletteReducedMotion: string; paletteSearchPlaceholder: string; paletteSessionActionsGroup: string; paletteSessionCurrent: string; paletteSessionsGroup: string; paletteSessionStatus: Record<'error' | 'attention' | 'running' | 'pending', string>; paletteSettingsGroup: string; paletteShowLegacyModels: string; paletteShowLegacyModelsHint: string; paletteSidebarRunDetails: string; paletteSidebarRunDetailsHint: string; paletteSwitchToSession: string; paletteUnavailable: string; paletteUntitledSession: string; paletteViewGroup: string; paletteWordWrap: string }>`): Overrides for the palette area's strings. Keys you leave out keep the default English label.

Source: [ui/src/palette/PaletteProvider.tsx:52](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteProvider.tsx#L52)

### `PaletteRows`

Interface.

The renderers [`createPaletteRows`](https://zidane.si/docs/reference/ui-palette.md#createPaletteRows) returns, for `CommandPalette`.

```ts
interface PaletteRows
```

**Properties**

- `renderIcon` (`(row: PaletteRowData<PaletteItem>) => ReactNode`): A file's type badge, else the item's own glyph.
- `renderKeys` (`PaletteKeys`): Keycaps for binding specs that may list alternatives (`ctrl+w | cmd+w`).
- `renderRow` (`(props: PaletteRowProps<PaletteItem>) => ReactNode`): A session or a conversation match; any other row is the surface's (`undefined`).

Source: [ui/src/palette/PaletteRows.tsx:57](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteRows.tsx#L57)

### `PaletteRowsOptions`

Interface.

What the rows read from the app. Every member is optional.

```ts
interface PaletteRowsOptions
```

**Properties**

- `highlight?` (`(excerpt: string, query: string) => { ranges: readonly PaletteTextRange[]; text: string }`): Cuts a conversation excerpt around its first match and marks the query's terms in it. Absent: plain excerpt.
- `StatusDot?` (`ComponentType<{ sessionId: string }>`): A session's live status dot, in the row's icon slot.
- `useSession?` (`(sessionId: string) => { current: boolean; updatedAt: number } | undefined`): A loaded session's last update and whether it is the one on show (a hook, called once per session row).
- `useSessionStatus?` (`(sessionId: string) => string | undefined`): A session's live status (a hook, called once per session row).

Source: [ui/src/palette/PaletteRows.tsx:45](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteRows.tsx#L45)

### `PaletteSource`

Interface.

Source of palette items and the handler that runs them.

```ts
interface PaletteSource
```

**Properties**

- `id` (`string`): Provider id, stamped on its items as `source`.
- `items` (`(ctx: PaletteContext) => readonly PaletteItem[] | Promise<readonly PaletteItem[]>`): Items for the current context. Called on open, on `subscribe` emits, and on explicit refresh.
- `run` (`(itemId: string, ctx: PaletteContext) => PaletteRunResult | Promise<PaletteRunResult>`): Runs the item with the given id. May return a follow-up result.
- `subscribe?` (`(emit: () => void) => () => void`): Live updates while the palette is open, same contract as panels.

Source: [dist/index-Bq87OcGy.d.ts:28165](https://github.com/Tahul/zidane/blob/main/dist/index-Bq87OcGy.d.ts#L28165)

### `RankedItems`

Interface.

What [`useRankedItems`](https://zidane.si/docs/reference/ui-palette.md#useRankedItems) returns.

```ts
interface RankedItems
```

**Properties**

- `rows` (`readonly RankedPaletteItem[]`): The rows to show.
- `settled` (`boolean`): The rows are for this query (Enter waits for that).

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

## Types

### `CommandPaletteProps`

Type.

Props for [`CommandPalette`](https://zidane.si/docs/reference/ui-palette.md#CommandPalette).

```ts
type CommandPaletteProps = Pick<PalettePanelProps<PaletteItem>, 'verb' | 'renderRow' | 'renderIcon' | 'renderKeys' | 'className' | 'style'> & { busy?: boolean; controller: PaletteController; extraGroups?: readonly PaletteSection<PaletteItem>[] }
```

Source: [ui/src/palette/CommandPalette.tsx:15](https://github.com/Tahul/zidane/blob/main/ui/src/palette/CommandPalette.tsx#L15)

### `PaletteRunResult`

Type.

What a provider's `run` may hand back. `items` opens a nested picker
(branches, environments); the host keeps a stack so Backspace on an
empty query goes back one level. `prompt` sends text to the chat,
`insert` puts it in the composer (a `/` command that takes arguments).

```ts
type PaletteRunResult =
  | void
  | undefined
  | { items: readonly PaletteItem[]; kind: 'items'; placeholder?: string; title?: string }
  | { kind: 'prompt'; text: string }
  | { kind: 'insert'; text: string }
  | { kind: 'notify'; text: string; tone?: 'info' | 'warn' | 'error' }
```

Source: [dist/index-Bq87OcGy.d.ts:28148](https://github.com/Tahul/zidane/blob/main/dist/index-Bq87OcGy.d.ts#L28148)

### `PaletteSessionStatus`

Type.

A session's status as its palette row words it; quiet states say nothing.

```ts
type PaletteSessionStatus = 'running' | 'pending' | 'attention' | 'error'
```

Source: [ui/src/palette/PaletteRows.tsx:42](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteRows.tsx#L42)

### `PaletteTextRange`

Type.

A half-open `[start, end)` range of a text.

```ts
type PaletteTextRange = readonly [start: number, end: number]
```

Source: [ui/src/palette/PaletteRows.tsx:39](https://github.com/Tahul/zidane/blob/main/ui/src/palette/PaletteRows.tsx#L39)