The interface stack — explanation

What is this about?

The draft asks for a desktop application in Go with Wails, "sober and fancy", organised in panels like the Zed editor. Wails draws the interface with web technologies inside a native window, so the question was which web pieces to use. The decision and its measurements are in ADR 0002.

Why Wails v3

Wails v3 became stable on 26 October 2026, after almost four years of alpha and beta. Its model fits Sidekicks closely: the Go side is made of services (agents, channels, terminal), messages to the interface are typed events, several windows are possible, and macOS packaging (signing, DMG, updates) is built in. Starting on v2 would mean migrating within months.

Why Svelte and these components

The interface is updated many times a second while an agent answers. Svelte 5 compiles to direct DOM updates without a virtual DOM, and Wails ships an official template for it. Around it, each need has a well-known component: paneforge for resizable panels, markdown-it and Shiki for Markdown with VS Code-quality code colouring, DOMPurify so that HTML written by a model never runs, Asciidoctor.js (loaded only when an AsciiDoc file is previewed) for AsciiDoc, CodeMirror 6 for the YAML editor, xterm.js and a real PTY for the terminal.

The prototype

What the prototype showed

A prototype assembled all of them in one window. The decisive point was streaming: rendering the Markdown at most once per screen refresh, rather than once per fragment, keeps the interface fluid even at 500 fragments per second, while a code block still being written is already coloured.

Rejected alternatives

Monaco (the VS Code editor) is complete but heavy for editing one YAML file.
highlight.js is lighter than Shiki but its colouring is visibly poorer.
React or Vue would work; nothing in Sidekicks needs their ecosystems.

How it relates to the rest

The interface only talks to one Go package, internal/app (see Architecture). The screens it will show are drawn in the wireframes. One check remains open: running the prototype on macOS, which the development sandbox cannot do.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


# The interface stack — explanation

## What is this about?

The draft asks for a desktop application in Go with [Wails](https://wails.io), "sober and fancy", organised in panels like the Zed editor. Wails draws the interface with web technologies inside a native window, so the question was which web pieces to use. The decision and its measurements are in [ADR 0002](../../adr/0002-ui-stack.md).

## Why Wails v3

Wails v3 became stable on 26 October 2026, after almost four years of alpha and beta. Its model fits Sidekicks closely: the Go side is made of **services** (agents, channels, terminal), messages to the interface are **typed events**, several windows are possible, and macOS packaging (signing, DMG, updates) is built in. Starting on v2 would mean migrating within months.

## Why Svelte and these components

The interface is updated many times a second while an agent answers. Svelte 5 compiles to direct DOM updates without a virtual DOM, and Wails ships an official template for it. Around it, each need has a well-known component: paneforge for resizable panels, markdown-it and Shiki for Markdown with VS Code-quality code colouring, DOMPurify so that HTML written by a model never runs, Asciidoctor.js (loaded only when an AsciiDoc file is previewed) for AsciiDoc, CodeMirror 6 for the YAML editor, xterm.js and a real PTY for the terminal.

![The prototype](../../spikes/ui/prototype-linux.png)

## What the prototype showed

A prototype assembled all of them in one window. The decisive point was streaming: rendering the Markdown at most once per screen refresh, rather than once per fragment, keeps the interface fluid even at 500 fragments per second, while a code block still being written is already coloured.

## Rejected alternatives

- **Monaco** (the VS Code editor) is complete but heavy for editing one YAML file.
- **highlight.js** is lighter than Shiki but its colouring is visibly poorer.
- **React or Vue** would work; nothing in Sidekicks needs their ecosystems.

## How it relates to the rest

The interface only talks to one Go package, `internal/app` (see [Architecture](architecture.md)). The screens it will show are drawn in the [wireframes](../../design/README.md). One check remains open: running the prototype on macOS, which the development sandbox cannot do.