Files
llama.cpp/tools/ui/demo
Aleksander Grygier 7592b61d3b ui: move Models, MCP and Settings to a sidebar footer (#32022)
* ui : move Models, MCP and Settings to a sidebar footer

The sidebar's actions split in two: New chat, Search and Projects stay at
its top, and Models, MCP and Settings move to a footer at its bottom, under
a thin rule, in the expanded sidebar and its collapsed strip alike. On a
phone the footer keeps clear of the home indicator, and Models stays
desktop-only as before. The search dialog still lists every action.

Assisted-by: Claude (Opus 5.5 Medium)

* ui : group the sidebar footer in an inset surface

The design system gains inset-group-surface, for rows grouped inside a glass
panel: white on the light glass and a faint tint of the text colour on the
dark one, with the sidebar's own ambient edge, no inner highlight, a faint
wide shade under it and the card radius. It is matte-glass pointed at its
own component tokens, like the sidebar and chat form surfaces, and reads as
part of the panel: no tight contact shadow or solid border like a button,
no inset shade like a field.

The sidebar footer uses it in place of the rule above Models, MCP and
Settings. DESIGN.md and the Surfaces page document it.

Assisted-by: Claude (Opus 5.5 Medium)

* ui : give the sidebar's logo button the add button's key look

Whenever the sidebar shows, open or peeking, its logo button takes the same
key as the chat form's add button (matte-key, white in light mode, a light
tint in dark), in place of its own muted fill. While the sidebar is hidden
the logo has no fill and no shadow, and hover and focus never change the
fill. It keeps its round shape and its own size.

Assisted-by: Claude (Opus 5.5 Medium)

* ui : put search in a round key at the top of the phone sidebar

On a phone the sidebar's Search row moves to a round key at the right end
of its top row, across from the logo, with the same key look as the logo
and the chat form's add button. It opens search as the row did. Desktop
keeps the Search row.

Assisted-by: Claude (Opus 5.5 Medium)

* ui : size the phone sidebar for a thumb and list its footer with the actions

On a phone the sidebar's actions and rows are 48px tall at 17px, flush one under
the other with 16px corners, its section headings 15px and grey, and its groups
28px apart. MCP and Settings join the top actions there: the footer is a desktop
pattern.

Assisted-by: Claude (Opus 5.5 Medium)

* ui : mark the selected sidebar row with a tinted inset surface

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep the phone sidebar's round keys white on the grey page

Assisted-by: Claude (Opus 5.5 Medium)

* ui : open Settings and MCP as pages on a phone, dialogs elsewhere

On a phone the sidebar opens them at #/settings and #/mcp-servers, with the menu key and a
title like any phone page. Pinned under the status bar, Settings' section tabs fill the
screen above them in the page's colour.

Assisted-by: Claude (Opus 5.5 Medium)

* ui : open a phone sidebar's pages behind it, settled before they slide back

A tap in the phone sidebar now opens its page while the current one is still aside and slides
back once it has rendered, instead of swapping pages mid-slide. The slid page's fixed bars are
pinned again as the page under them changes, the lock ends with the slide itself, and a
phone's new chat shows its form and greeting at once, without the move and entry they have
on a desktop.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: style the sidebar footer group and the selected row with master's classes until the design system lands

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add GlassKey with master's styles for the phone sidebar's round keys

Assisted-by: Claude (Opus 5.5 Medium)

* ui: center the top edge of a new chat's form on the screen

The form rested 42px below the middle up to 2xl and 6px above it past
that; one drop, from the resting card's height, now puts its top edge on
the middle at every width from md up.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: round the sidebar's action rows concentric with the footer group

The sidebar stacks four surfaces: the page, the sidebar, the footer group
inset in it and a row in the group. app.css now names the group's radius
and padding, and derives the row radius from them (16px less 4px), so the
footer's rows run parallel to its corners; the actions at the top of the
sidebar share that radius. The footer moves to its own component, the
README documents the pattern, and a client test holds the rule on the
rendered footer.

A selected action row was bg-accent, the same grey as a hovered row in
light and darker than the footer's fill in dark, so it read as hovered or
not at all; it is now raised and edged, while a hover only tints.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: import demo chats through the Settings page on a phone

A phone opens Settings as a page now, not a dialog, so the demo harness
waited for a dialog that never came and every phone demo with traces
failed; it now imports through whichever of the two opens.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: count the sidebar's rows from their items in the surface test

The test expected three footer rows and two top actions, which the
stacked PRs change as they add Projects, Library and Servers; it now
expects as many rows as the sidebar has items.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add a line on Meta+Enter off macOS too

The chat form takes Meta+Enter as Ctrl+Enter and leaves the newline to
the editor, but the editor bound only Mod-Enter, which is Ctrl off
macOS, so on Linux Meta+Enter neither sent nor added a line. This failed
the client test on CI's Linux runners, on master too.

Assisted-by: Claude (Opus 5.5 Medium)
2026-11-10 18:58:57 +01:00
..

Demo videos

Scripted Playwright walkthroughs of the UI, exported as mp4 with an animated GIF preview, for pull requests and documentation. The harness lives here; the demo scripts don't:

  • PR demos live in the PR description, as a ts demo code block.
  • Docs demos live in the storage target, under scripts/docs/.
demo/
├── cli.ts      demo:pr, demo:docs and demo:traces
├── storage.ts  storage targets (hf://, file://)
├── helpers.ts  `test` with a `demo` fixture: cursor, captions, human-like timing
├── recorder.ts screencast recording and mp4 export
├── fixtures/   fixture MCP servers, seeded settings and demo conversations
└── videos/     output (git-ignored)

Setup

Tools

Tool Used for
Node 22.18+ runs demo/cli.ts directly (TypeScript type stripping)
npx playwright install chromium the browser demos record in, with its sandbox on
ffmpeg mp4 encoding and the GIF preview
gh, logged in reads the PR description and writes the ## Demo section, so you need edit rights on the PR
hf, logged in with a write token (hf auth login) uploads to the bucket and the traces dataset
llama-server build/bin/llama-server, or one already running at DEMO_SERVER_ORIGIN (default :9931). It runs in router mode, so demos can pick any model in the local cache; scripts that send messages need at least one.

gh is only needed for demo:pr, and hf only with the bucket or dataset below. Without them, the video stays in demo/videos/.

Videos are recorded through Chromium's screencast at DEMO_SCALE (2x by default, so 2880x1800) and 60 fps, starting once the page has settled.

Hugging Face bucket (videos, previews, scripts)

The bucket must be public, since GitHub loads the preview from it:

hf buckets create <owner>/llama-ui-demos

Then set it in tools/ui/.env (see .env.example):

DEMO_STORAGE='hf://buckets/<owner>/llama-ui-demos'
DEMO_STORAGE_PUBLIC_URL='https://huggingface.co/buckets/<owner>/llama-ui-demos/resolve'

Layout: videos/pr/<number>/<sha>.{mp4,gif,demo.ts}, videos/docs/<name>.{mp4,gif} and scripts/docs/*.demo.ts (the docs scripts). Without DEMO_STORAGE_PUBLIC_URL, videos are uploaded but not linked in the PR. DEMO_STORAGE='file:///some/dir' stores them in a local folder instead.

Hugging Face dataset (conversations, optional)

Only needed for demos that import conversations other than the built-in ones, or to publish the built-in ones with npm run demo:traces. It can be private: it is read with your hf login.

hf repos create <owner>/llama-ui-demo-traces --repo-type dataset --private
DEMO_TRACES_DATASET='<owner>/llama-ui-demo-traces'

Other storage

Only Hugging Face buckets and file:// folders are supported for now. S3, R2 or similar would be one more class in storage.ts (upload and downloadDir) plus the matching DEMO_STORAGE_PUBLIC_URL.

Recording a pull request

Add the script to the PR description:

<details>
<summary>Demo script</summary>

```ts demo
test('demo', async ({ demo, page }) => {
	await demo.click(page.getByRole('button', { exact: true, name: 'Settings' }));
	await demo.caption('What this shows');
});
```

</details>

Then run:

npm run demo:pr -- 31303

A PR by someone else runs its code and demo script on your machine, with your gh and hf logins, so demo:pr refuses it until you've read its diff and demo block and pass the head commit you read: npm run demo:pr -- 31303 --trust <sha>. If the PR gets new commits, it refuses again.

It checks out the PR head in a temporary worktree, records the script against it, uploads videos/pr/<number>/<sha>.{mp4,gif,demo.ts} and adds or updates a ## Demo section in the PR description with the preview linking to the video.

A large PR can show its changes in several shorter videos: each test() in the block is recorded as its own video (<sha>-1.mp4, <sha>-2.mp4, ...), and the ## Demo section shows their previews in a table, each headed by its test's title: up to four portrait (phone) videos to a row, or two landscape ones. Helpers and test.use at the top of the block are shared by all of them.

test('Header and safe areas', async ({ demo, page }) => {
	// ...
});

test('Sidebar gestures', async ({ demo, page }) => {
	// ...
});
``` GitHub has no API for attachments, so for an inline player drag `demo/videos/pr-<number>.mp4` into the description instead.

## Recording docs

```bash
npm run demo:docs

Records every scripts/docs/*.demo.ts from the storage target and uploads videos/docs/<name>.{mp4,gif}.

Writing a demo

Scripts get test and expect from helpers.ts without importing them. demo.click, demo.hover and demo.type glide a visible cursor to the target before acting, with timing varied like a person's (seeded per demo, so re-takes match); demo.scroll turns the mouse wheel over a target; demo.zoom pinches in on a control or a point to show a detail too small to read in the frame, holds, and pinches back out (with the fingertips drawn on a touch device); demo.caption shows a caption at the top of the frame. Use test.use({ settings, startPath }) to seed other settings or start on another route.

Conversations

Demos that need existing chats import them with test.use({ traces: ['long-chat'] }), through Settings > Import/Export before the video starts. Traces use the export format (llama.app JSONL), so the Hub shows them as Llama traces:

  • fixtures/traces.ts generates the built-in ones: long-chat (36 tall exchanges) and agentic-debugging (long reasoning, shell output and code blocks).
  • Any other name is downloaded as <name>.jsonl from DEMO_TRACES_DATASET, e.g. an exported conversation uploaded there.

npm run demo:traces writes the built-in traces to demo/traces/ and pushes them to DEMO_TRACES_DATASET.

Trying a script locally

To try a script locally, put it in demo/ as <name>.demo.ts, importing from ./helpers.ts, and run npm run demo:record -- demo/<name>. npm run demo:codegen opens Playwright codegen against :5180 for a first draft.

The config starts, or reuses when already running, the fixture MCP servers on :8765, llama-server on :9931 (router mode, --tools all) and the UI's vite dev server.