Extension UI

An extension adds UI as data. ctx.add(Token, item) hands an item to every app, and each app draws it with its own widgets: the terminal app with text, the desktop and web apps with the zidane-ui kit. The call returns a handle that updates or withdraws the item. A field can follow a store, so the item changes on its own.

Use data items for most UI: a status line, a badge, a panel, a renderer for a code block. They work in every app with no extra code. When the data is not enough, an item names a component from the extension's ui.tsx (desktop and web) and tui.tsx (terminal) (components). For a whole page with its own HTML, use a webview.

A first item#

The kitchen-sink example shows its counter in the statusbar (examples/extension-kitchen-sink/ui-items.ts). The text follows a store, and a click runs a command:

import { defineExtension, Slot } from 'zidane'
import { z } from 'zod'

export default defineExtension({
  apiVersion: 1,
  id: 'counter',
  setup(ctx) {
    const counter = ctx.storage.store('counter', z.object({ count: z.number() }), { count: 0 }, { scope: 'project' })

    ctx.commands.register({
      id: 'bump',
      title: 'Bump the counter',
      run: () => counter.set(c => ({ count: c.count + 1 })),
    })

    ctx.add(Slot, {
      at: 'app.statusbar',
      text: counter.select(c => `count ${c.count}`),
      title: 'Click to bump',
      command: 'counter.bump',
    })
  },
})

Each counter.set changes the store, the bound text reads it again, and every app redraws the item. No code calls update.

ctx.add and handles#

ctx.add takes a token and an item, and returns a Handle:

import type { Handle, SlotItem } from 'zidane'
import { Slot } from 'zidane'

let line: Handle<SlotItem> | undefined

function progress(text: string | null): void {
  if (text === null) {
    line?.dispose()
    line = undefined
    return
  }
  if (line)
    line.update({ text })
  else
    line = ctx.add(Slot, { at: 'app.statusbar', text, loader: true })
}

This is the pattern of the in-repo ai-autocomplete and goal extensions: one handle per line, updated in place, disposed when the work ends.

An item lives as long as the owner it was added through. When the extension unloads, or a scope is disposed, its items go. ctx.add through a disposed owner throws DisposedError.

The rules the registry checks when you add or update an item:

Slot, Renderer and Menu items have no id: add as many as you need. For Reference, BadgeAction and ThemeToken, ids are shared by every extension and the first one loaded wins. Prefix them with your extension id (kitchen-sink.ticket).

Bound fields#

A field typed Bindable<T> takes a value or a Readable<T>: an object with get() and subscribe(listener). The registry reads each bound field when it sends the item, and subscribes to it. A change sends the item again.

A store is a Readable, and store.select(pick) gives a Readable over part of it. Both fit any bindable field:

import { Menu, Slot } from 'zidane'
import { z } from 'zod'

const counter = ctx.storage.store('counter', z.object({ count: z.number() }), { count: 0 }, { scope: 'project' })
const count = counter.select(c => c.count)

ctx.add(Slot, { at: 'composer.below', text: counter.select(c => `counter ${c.count}`) })
ctx.add(Menu, { menu: 'tray', label: counter.select(c => `Counter: ${c.count}`), command: 'counter.bump' })
ctx.add(Slot, { at: 'composer.badges', sessionId: 'session-1', text: 'counter', count })

Any object with get and subscribe works. A value that comes from outside a store:

import type { Readable } from 'zidane'
import { Slot } from 'zidane'

function clock(): Readable<string> {
  const listeners = new Set<(value: string) => void>()
  const now = () => new Date().toLocaleTimeString()
  const timer = setInterval(() => listeners.forEach(l => l(now())), 1000)
  ctx.onCleanup(() => clearInterval(timer))
  return {
    get: now,
    subscribe: (listener) => {
      listeners.add(listener)
      return () => listeners.delete(listener)
    },
  }
}

ctx.add(Slot, { at: 'app.statusbar', text: clock() })

The fields you can bind:

Only top-level fields bind. A Readable nested in an object (inside component.props, inside a panel's content) is not read. A panel follows changes through its own subscribe instead (panels).

Tokens#

Every UI token comes from zidane. Each one names one kind of item:

Slots, panels, screens, renderers, settings pages, webviews, menus and link handlers have their own pages, and the six sidebar tokens share one. The four below have no place of their own: the apps fold them into what they already draw.

Themes#

ctx.add(ThemeToken, theme) adds a theme to the theme picker of every app. A Theme spells every color: id, label, colors, select, surfaces and syntax. The kitchen sink's full theme is in examples/extension-kitchen-sink/theme.ts. Type it from the token, since no built-in theme is exported to extend:

import type { ThemeToken } from 'zidane'

type Theme = NonNullable<typeof ThemeToken.__type>

Built-in themes win an id clash. Prefix the id with your extension id.

References#

A reference provider finds ids in text (prompts, replies, session titles) and turns each one into a chip. The apps match patterns, then call resolve for each key. A key that resolves to nothing stays plain text, so a loose pattern does no harm:

import { Reference } from 'zidane'

ctx.add(Reference, {
  id: 'kitchen-sink.ticket',
  patterns: [{ regex: '\\bKS-(\\d+)\\b', key: '$1' }],
  surfaces: ['prompt', 'assistant'],
  resolve: async key => ({ label: `KS-${key}`, status: 'queued', tone: 'accent', prompt: `kitchen ticket ${key}` }),
})

The apps cache each resolved key. When matches overlap, the earliest wins, then the longest. The desktop and web apps draw reference chips. The terminal app does not.

Badge actions#

A badge action adds entries to the right-click menu of badges: links, files, commits, references, artifacts.

import { BadgeAction } from 'zidane'

ctx.add(BadgeAction, {
  id: 'kitchen-sink.ticket-actions',
  match: { references: ['kitchen-sink.ticket'] },
  actions: () => [{ id: 'serve', label: 'Serve this ticket', group: 'more' }],
  run: async (_actionId, target) => ({ notice: `Served ${target.text}` }),
})

Context sections#

A context section adds rows to the context breakdown (placement: 'breakdown') or a section to the context panel (placement: 'panel'):

import { ContextSection } from 'zidane'

ctx.add(ContextSection, {
  placement: 'breakdown',
  contributor: () => ({ id: 'kitchen', label: 'Kitchen sink', rows: [{ label: 'Counter', value: '3' }] }),
})
ctx.add(ContextSection, {
  placement: 'panel',
  section: { id: 'kitchen', title: 'Kitchen sink', rows: ({ turns }) => [{ label: 'Turns seen', value: String(turns.length) }] },
})

A breakdown contributor gets the session's turns and returns a section, a list of sections, or nothing. A panel section has an id (unique per extension), a title, an optional accentColor, and rows, load or both.

Dialogs, panels and the composer#

UI that answers a call, rather than an item that stays, lives on ctx.ui and ctx.composer:

Components#

Every item that has a component field can name an export of the extension's UI entries: { component: 'KitchenBoard', props: { compact: true } }. A Screen requires one. The desktop and web apps look the name up in ui.tsx, the terminal app in tui.tsx, so both files export the same names. An app without the component, or with one that throws, draws the item's data instead (components).

In each app#

The three apps draw the same items in their own places. Some are not drawn everywhere:

Placements has where each item shows in each app.

Pitfalls#

• An app that lacks a place ignores the item. Do not rely on one item to tell the user something important: pair a slot with a toast, or with a command they can run.
• update cannot move an item. To show a badge in another session or another slot, dispose it and add a new one.
• A bound value that makes the item invalid (a color that is not #rgb) is refused, and the item keeps its last valid form. The extension's log says why.
• Reference, BadgeAction and ThemeToken ids are global. Two extensions with the same id: the second one silently loses.
• Items belong to the owner that added them. Add short-lived items through ctx.scope() and dispose the scope, instead of keeping every handle.