Extension placements

A placement is a place in the apps where an extension's UI shows. Items added with ctx.add stay in their place until you dispose them (UI model). Dialogs, toasts and layout calls on ctx.ui act once and return. This page lists every place, with where it shows in each app.

The three apps share the names. When an app has no such place, it ignores the item, and an await on a layout call answers false. Code that runs in every app needs no checks: it shows what each app can show.

A minimal example#

import { Panel, Slot } from 'zidane'

ctx.add(Slot, { at: 'app.statusbar', text: 'deploys: 2', panel: 'deploys' })

ctx.add(Panel, {
  id: 'deploys',
  label: 'Deploys',
  icon: { gui: 'i-ph-rocket-launch', tui: '^' },
  load: () => ({ sections: [{ id: 'list', items: [{ kind: 'row', title: 'main', subtitle: 'running' }] }] }),
})

ctx.commands.register({
  id: 'confirm-deploy',
  title: 'Deploy main',
  run: async ({ sessionId }) => {
    if (await ctx.ui.confirm({ title: 'Deploy main?', danger: true, ...(sessionId ? { sessionId } : {}) }))
      await ctx.ui.toast({ text: 'Deploying main', tone: 'info' })
  },
})

A click on the status item opens the panel. The command asks first, then shows a toast.

Slots#

A slot is a small item in one of twelve named places: a status line, a badge in the title bar, a banner, a row pinned in the sidebar. ctx.add(Slot, item) returns a handle.

panel and command take a bare id: the apps look for your own panel or command first.

Where each slot shows#

app.titlebar and composer.badges draw badges: at most 8 per extension (app.titlebar across every session, composer.badges per session), with text cut at 40 characters. Keep a title bar badge to a word or a count.

sidebar.top and sidebar.bottom are blocks: each item is a full-width row of its own, pinned outside the session list, so it stays put while the list scrolls. sidebar.footer items are small chips that share the footer strip with the app's status. In the desktop and web apps each block takes at most 30% of the sidebar's height and scrolls on its own past that; the terminal app clips a block at 30% of the screen. An empty block takes no room. See the sidebar's top and bottom.

The apps do not draw every field the same way:

composer.badges#

A composer badge belongs to one session, so sessionId is required. An extension shows up to 8 per session: the ninth ctx.add throws a RangeError. The badge label is text; with no text, the extension id.

In the desktop and web apps, a badge with a command runs it. A badge with a panel toggles that panel. In the desktop app the user can drag badges into their own order, kept per project. The terminal app draws badges as plain labels: no click, no reordering.

The kitchen sink adds one badge per session and lights it up while the session waits on the user (ui-items.ts):

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

const badges = new Map<string, Handle<SlotItem>>()
function badge(sessionId: string): Handle<SlotItem> {
  let handle = badges.get(sessionId)
  if (!handle) {
    handle = ctx.add(Slot, { at: 'composer.badges', sessionId, text: 'kitchen', panel: 'board', icon: { gui: 'i-ph-cooking-pot', tui: '◍' } })
    badges.set(sessionId, handle)
  }
  return handle
}
ctx.hooks.on('run:settled', event => badge(event.sessionId).update({ highlight: false, loader: false }))
ctx.hooks.on('session:event', event => badge(event.sessionId).update({ highlight: event.kind === 'needs-attention' }))

transcript.turn-end#

With sessionId and turnId, the item draws right after that turn, in every app. If the transcript holds no turn with that id, the item does not draw.

Without turnId, the item draws once, at the end of the transcript. The desktop and web apps show it only when no run is streaming and the transcript is not empty. The terminal app shows it all the time, under the transcript, during a run too.

Panels#

A panel is a side panel tab, a block on the project home, or both. Its content is data: load returns sections of rows, markdown, stats, charts and custom blocks, plus actions, header controls, a search field and pages. The apps call load when the panel shows, and again when it changes or the user filters, searches or asks for more.

import { Panel, panelViewValue } from 'zidane'

ctx.add(Panel, {
  id: 'board',
  label: 'Kitchen',
  icon: { gui: 'i-ph-cooking-pot', tui: '◍' },
  scope: 'both',
  surfaces: ['side', 'home'],
  home: { order: 10, width: 'half' },
  load: (lc) => {
    const range = panelViewValue(lc.view, 'range', 'all')
    return {
      controls: [{ id: 'range', label: 'Range', value: range, options: [{ id: 'all', label: 'All' }, { id: 'today', label: 'Today' }] }],
      sections: [
        { id: 'rows', title: 'Actions', items: [{ kind: 'row', title: 'Bump', actionId: 'bump' }, { kind: 'markdown', text: `Viewing **${range}** from ${lc.surface}.` }] },
        { id: 'card', items: [{ kind: 'custom', renderer: 'kitchen-card', data: { count: 3 }, fallback: 'Counter: 3' }] },
      ],
      actions: [{ id: 'reset', label: 'Reset', tone: 'danger' }],
    }
  },
  onAction: async (actionId) => {
    if (actionId === 'bump')
      await ctx.commands.run('kitchen-sink.bump')
  },
})

PanelContent and its item kinds are in the extensions reference. The apps reload a panel only while it shows. An update on the panel's handle also counts as a change.

A custom item in a panel draws through a renderer for its renderer id, and shows its fallback markdown where none matches.

Search, filters and Show more#

A home block can be browsed. The app keeps what the user picks and loads the panel again with it:

• controls with kind: 'select' (one option from a menu) or kind: 'multi' (several; view[id] is a list). Read them with panelViewValue and panelViewValues. Plain controls stay side by side.
• search: { placeholder } adds a search field. load gets its text as lc.search once typing rests.
• more: { cursor } adds Show more. load gets lc.cursor; the rows it returns are appended to the sections of the same id.

import { Panel, panelViewValue, panelViewValues } from 'zidane'

// Your own service.
declare const ordersApi: {
  list: (q: { status: readonly string[], sort: string, query?: string, cursor?: string }) => Promise<{ items: { id: string, title: string }[], next?: string }>
}

ctx.add(Panel, {
  id: 'orders',
  label: 'Orders',
  surfaces: ['home'],
  load: async (lc) => {
    const status = panelViewValues(lc.view, 'status', ['open'])
    const sort = panelViewValue(lc.view, 'sort', 'new')
    const page = await ordersApi.list({ status, sort, query: lc.search, cursor: lc.cursor })
    return {
      search: { placeholder: 'Search orders' },
      controls: [
        { id: 'sort', label: 'Sort', value: sort, options: [{ id: 'new', label: 'Newest' }, { id: 'big', label: 'Largest' }] },
        { id: 'status', label: 'Status', kind: 'multi', value: 'open', values: status, options: [{ id: 'open', label: 'Open' }, { id: 'shipped', label: 'Shipped' }] },
      ],
      sections: [{ id: 'orders', items: page.items.map(o => ({ kind: 'row', id: o.id, title: o.title })) }],
      ...(page.next ? { more: { cursor: page.next } } : {}),
    }
  },
})

Starting a chat from a row#

A row's actions are buttons shown on hover and in its right-click menu. One with start opens a new chat draft for the folder, never sent: where: 'worktree' runs it in a git worktree on branch (a pull request's head with pullRequest), where: 'here' in the folder (switched to pullRequest or branch when given). prompt is the draft's text.

import type { PanelRowItem } from 'zidane'

declare const t: { id: string, title: string, branch: string }

const row: PanelRowItem = {
  kind: 'row',
  id: t.id,
  title: t.title,
  actions: [
    { id: 'worktree', label: 'Worktree', icon: { gui: 'i-ph-git-fork' }, start: { where: 'worktree', branch: t.branch, prompt: `${t.id}: ${t.title}` } },
    { id: 'here', label: 'Here', icon: { gui: 'i-ph-folder-simple' }, start: { where: 'here', prompt: `${t.id}: ${t.title}` } },
  ],
}

The desktop app's project home runs these. Elsewhere a button with start is not shown; the others call onAction.

Screens and modals#

A screen is a full-screen view, or a modal with presentation: 'modal'. It needs a component. ctx.ui.navigate({ screen: id }) opens it: nothing else does, so pair it with a command.

import { Screen } from 'zidane'

ctx.add(Screen, { id: 'kitchen', title: 'Kitchen', component: { component: 'KitchenScreen' }, fallback: '# Kitchen\nThis app draws no kitchen screen.' })
ctx.add(Screen, { id: 'about', title: 'About the kitchen sink', presentation: 'modal', component: { component: 'KitchenAbout' } })

ctx.commands.register({ id: 'open-kitchen', title: 'Open the kitchen', slash: { name: 'kitchen' }, run: () => void ctx.ui.navigate({ screen: 'kitchen' }) })

Renderers#

A renderer draws one kind of content with your component: a custom block, a fenced code-block language, a tool's result, or an artifact kind's detail.

import { Renderer } from 'zidane'

ctx.add(Renderer, { for: { block: 'kitchen-card' }, component: { component: 'KitchenCard' } })
ctx.add(Renderer, { for: { language: 'kitchen' }, component: { component: 'KitchenCode' } })
ctx.add(Renderer, { for: { tool: 'kitchen_count' }, component: { component: 'KitchenToolResult' }, fallthrough: true })
ctx.add(Renderer, { for: { artifact: 'kitchen-sink.counter' }, component: { component: 'KitchenArtifact' } })

The props each component gets, besides its own component.props (the app's props win a clash):

The first renderer that matches draws, in load order. With fallthrough: true, a component that returns null hands over to the next one; past the last, the app draws its default view. A component that is missing or throws also gives way to the default view.

In the terminal app, fallthrough works for a plain function component only: one wrapped in memo or forwardRef, or a class, cannot hand over. The terminal app draws a fenced block once its closing fence arrives, and keeps an open one as markdown while it streams.

Settings pages#

A settings page is a page under the extension in Settings: rows from a schema, or a component.

import { SettingsPage } from 'zidane'

ctx.add(SettingsPage, { id: 'quick', title: 'Quick settings', schema: { items: { step: { type: 'number', label: 'Bump step', min: 1, max: 10 } } } })
ctx.add(SettingsPage, { id: 'stats', title: 'Statistics', component: { component: 'KitchenSettings' } })

A page sits with the extension's other pages in the settings sidebar: under the extension's entry in the Extensions group, or under its category. Settings search finds the rows of its schema. An extension with only SettingsPage items, and no settings of its own, still gets an entry. Every app draws them, the terminal app included (as a tab of its Settings), and a component page draws its component where the app has it.

Menus#

A menu item is a native menu entry in the desktop app. It runs a command.

import { Menu } from 'zidane'

ctx.add(Menu, { menu: 'app', label: 'Bump the kitchen counter', command: 'kitchen-sink.bump', accelerator: 'CmdOrCtrl+Shift+Y' })
ctx.add(Menu, { menu: 'session', label: 'Kitchen: about this session', command: 'kitchen-sink.session-info' })

The terminal and web apps have no native menus and ignore menu items. Register the same action as a command so it is reachable everywhere.

Links#

A LinkHandler opens links the extension understands before the app does: a ticket URL in a panel of the extension's own, a vscode:// link in a terminal. Every link the apps open goes to the handlers first. A link no handler takes opens the app's way.

import { LinkHandler } from 'zidane'

ctx.add(LinkHandler, {
  id: 'tickets',
  match: /^https:\/\/linear\.app\/[\w-]+\/issue\//,
  open: async (url, { sessionId }) => {
    const shown = await ctx.ui.panel.open('tickets', { sessionId })
    if (!shown)
      return false
    ctx.logger.info(`opened ${url} in the tickets panel`)
  },
})

source says where the link was clicked: transcript, chip, panel, badge, terminal or other. File and path links pass the absolute path as url. match and open run where the extension runs, so a link clicked in a window goes to the daemon or the server and back. A handler that returns false, throws or passes the 8 second callback timeout passes the link to the next one; a match that throws counts as no match. Both count against the extension's error budget.

To call the handlers yourself, as an app does: extensions.links.open on the protocol (a chat token is enough) answers { handled }.

The desktop and web apps route links only while at least one extension has a LinkHandler. Terminal links in those apps reach the handlers without a sessionId.

Sidebar#

Six tokens add to the session list: spaces, filters, sorts, groupings, row decorations and rows of the extension's own. Each one takes a session query that says which sessions it applies to. Sidebar has their fields and a full example.

import { SidebarDecoration, Space } from 'zidane'

ctx.add(Space, { id: 'failed', name: 'Failed', query: { field: 'status', eq: 'error' }, sortBy: [{ field: 'updatedAt', dir: 'desc' }] })
ctx.add(SidebarDecoration, { id: 'model', where: { field: 'modelId', exists: true }, chips: [{ template: '{modelId}' }] })

Dialogs#

A dialog asks the user and resolves with the answer. Call it from anywhere: a command, a hook, a panel action, a timer.

import { NoUiError } from 'zidane'

try {
  const name = await ctx.ui.prompt({ title: 'Your name?', placeholder: 'Ada' })
  const dish = await ctx.ui.select({
    title: 'Pick a dish',
    options: [{ id: 'soup', label: 'Soup' }, { id: 'pie', label: 'Pie', description: 'Takes longer' }],
    actions: [{ id: 'random', label: 'Surprise me' }],
  })
  const portions = await ctx.ui.form({
    title: 'Portions',
    schema: { items: { people: { type: 'number', label: 'People', default: 2, min: 1, max: 12 } } },
  })
  ctx.logger.info(`${name ?? 'someone'} picked ${dish?.action ?? dish?.ids.join(', ')} for ${String(portions?.people)}`)
}
catch (error) {
  if (!(error instanceof NoUiError))
    throw error
}

Every dialog also takes these options:

With no window that can show it, a dialog rejects at once with NoUiError: a command run from a keybinding on a headless server, or a hook while no window is attached. Catch it where that can happen.

In the desktop app, a form answer that fails the schema makes ctx.ui.form throw a TypeError. Check the values your schema allows, or catch it.

Toasts and notifications#

ctx.ui.toast shows a short message, with optional buttons. It resolves with the id of the button the user clicked, or undefined.

const action = await ctx.ui.toast({
  text: 'Counter reset.',
  tone: 'success',
  actions: [{ id: 'undo', label: 'Undo' }],
  timeoutMs: 10_000,
})
if (action === 'undo')
  ctx.logger.info('undo')

ctx.ui.notify({ title, body?, sound?, sessionId? }) shows an OS notification. It returns nothing.

Toasts and notifications do not fail when no window is open. They wait: up to 20 of them, each for 60 s, delivered in order to the first window that attaches. A toast dropped before any window shows it resolves undefined.

Panel and navigation control#

ctx.ui.panel drives the side panel. ctx.ui.navigate shows a screen, a session or a new session. Each call goes to the window that views sessionId, else the last active window, and resolves false when no window takes it.

ctx.commands.register({
  id: 'toggle-board',
  title: 'Toggle the kitchen panel',
  bind: 'mod+alt+k',
  run: async ({ sessionId }) => void await ctx.ui.panel.toggle('board', sessionId ? { sessionId } : {}),
})

id is your panel's id, <extension>/<id>, or a built-in tab.

Composer control#

ctx.composer edits the draft of a session's composer. Each call resolves false when no window took it.

ctx.commands.register({
  id: 'fill',
  title: 'Fill the composer',
  when: 'session',
  run: async ({ sessionId }) => {
    if (!sessionId)
      return
    await ctx.composer.setText('Tell me about the counter.', { sessionId })
    await ctx.composer.attach([{ name: 'counter.json', mimeType: 'application/json', data: new TextEncoder().encode('{"count":3}') }], { sessionId })
  },
})

Without sessionId, the call goes to the focused composer.

Composer providers#

Two providers feed the composer while the user types:

• ctx.composer.completions.register(provider) adds a menu on a trigger character, like @ for files. provider has id, trigger (one character), label, suggest(query, ctx, signal) returning items, and parseReferences(text, ctx) returning the references it finds in the draft.
• ctx.composer.autocomplete.register(provider) adds ghost text. provider has id, suggest({ text, cursor, cwd, signal }) returning the text to append (or a list to cycle through, or null), and deadlineMs when the source is slow.

ctx.composer.completions.register({
  id: 'kitchen-sink.recipes',
  trigger: '%',
  label: 'Kitchen',
  suggest: query => ['toast', 'tea', 'soup'].filter(r => r.startsWith(query)).map(r => ({ id: r, label: r, insertText: `%${r} `, data: r })),
  parseReferences: () => [],
})
ctx.composer.autocomplete.register({
  id: 'kitchen-sink.counter',
  suggest: ({ text, cursor }) => (text.slice(0, cursor).endsWith('kitchen count ') ? '3' : null),
})

Both return a Disposable. An autocomplete provider runs on each keystroke with a short deadline (150 ms unless deadlineMs says more). A slow one only delays the providers after it, never the typing.

ctx.desktop#

ctx.desktop exists only in the desktop app's main process. It is undefined everywhere else: in the terminal app, the daemon, the server, and in the desktop app when the daemon runs its sessions. Check it before each use (examples/extension-kitchen-sink/desktop.ts):

interface ElectronSubset { app: { getVersion: () => string } }

const desktop = ctx.desktop
if (desktop) {
  const { app } = desktop.electron<ElectronSubset>()
  ctx.logger.info(`desktop ${app.getVersion()}`)
  desktop.windows.on('focus', window => ctx.logger.debug(`window ${window.id} focused (${desktop.windows.list().length} open)`))
}

For menus, use menu items: they work whichever process runs the extension.

Pitfalls#

• A screen opens only through ctx.ui.navigate. Register a command for it, or the user cannot reach it.
• A LinkHandler with a wide match takes links the user expected in the browser. Match narrowly, and return false for a link you cannot open.
• composer.badges without sessionId throws. A badge for "every session" is one ctx.add per session, added when the session first runs.
• Icons and hover text do not show in the terminal app. Put what matters in text.
• The terminal app blocks on a toast with actions until the user answers. Keep action toasts for things the user must decide.
• ctx.ui.notify is skipped while the app has focus in the desktop and web apps. Use a toast for something the user must see now.
• ctx.composer.attach with a path fails in the desktop app. Read the file and pass bytes.
• A dialog from a hook can land in another window than the one the user looks at. Pass the sessionId the hook gives you.
• ctx.desktop is absent when the daemon runs the extension, even inside the desktop app. Code that needs it must also work without it.