* ui: bring @ggml-org/llama-ui into ui/lib/ui The design system package (tokens, fonts, surfaces, components and Model UI), so far in the temporary ggml-org/llama-ui repository at edaf518, moves to its home in ui/lib/ui, built with @sveltejs/package and published as @ggml-org/llama-ui from here. ui/lib holds the packages, one folder each. Its references to tools/ui now name ui/apps/chat, its package.json points at this repository, and the UI workflow type-checks and packs it. ui/README.md describes the layout. Assisted-by: Claude (Opus 5.5 Medium) * ui: Llama UI design system: tokens, surfaces and brand The design system from allozaur/docs/storybook-overhaul: three tiers of tokens, matte glass surfaces, Llama Sans and Llama Mono, and the base components on the new tokens (Tabs and GlassKey among them). It also restyles the stack's features with it, replacing the plain stand-ins they used until now. DESIGN.md is generated from the tokens. The Storybook that documents it is the next PR. Assisted-by: Claude (Opus 5.5 Medium) * ui: have Llama Chat use @ggml-org/llama-ui for its base components, tokens and fonts Llama Chat kept its own copy of the design system: 29 base components, the three tiers of tokens, the surfaces, the theme and the fonts, next to the 12 components ui/lib/ui held. The copy goes, and the library gets what it lacked. ui/lib/ui - the 17 base components the app had and the library did not (alert, alert-dialog, button-group, checkbox, collapsible, context-menu, dialog, drawer, dropdown-menu, empty, hover-card, radio-group, scroll-area, skeleton, table, tabs, textarea), with vaul-svelte for the drawer - the inset-group and selected-row tokens and surfaces - sources import each other by relative path instead of $lib, which in an app points at the app's own src/lib - theme.css no longer imports tw-animate-css: it is a peer dependency that the consumer imports before the theme, as it does Tailwind - 0.3.0 ui/apps/chat - imports the base components as @ggml-org/llama-ui/ui/<name> and cn/tv as @ggml-org/llama-ui/utils; app.css imports the library's theme.css - compiles the library from source, with no install or build of it: scripts/vite-plugin-llama-ui.ts resolves its entry points and what it imports, and svelte.config.js gives TypeScript the same paths - src/lib/components/ui, styles/tokens, styles/surfaces.css and assets/fonts are removed; components.json moves to the library Builds - CMake stages ui/lib/ui next to the app, keeping the layout of ui/, and rebuilds when a library source changes - the Dockerfiles copy the library's sources; the Nix derivation takes ui/ as its source The built CSS has the same rules in the same order, apart from one zero-specificity rule and the @font-face rules moving, plus ten utilities and two tokens that only the library's own components use. Assisted-by: Claude (Opus 5.5 Medium) * ui: AGENTS.md places Llama UI in ui/lib/ui Llama Chat's AGENTS.md says where each part lives: Llama UI is ui/lib/ui, and Chat imports its tokens, fonts and base components from there. Assisted-by: Claude (Opus 5.5 Medium) * ui: Llama Sans and Llama Mono from llama-brand's latest, and shell commands marked in bash code The fonts in ui/lib/ui come from llama-brand's latest, with optical sizes from 10 to 36. Bash code blocks mark shell commands and flags. Assisted-by: Claude (Opus 5.5 Medium) * ui: open submenus outside the menu they come from A submenu was rendered inside its parent menu, so the menu's scroll box clipped it: the glass menus' backdrop filter, and the filter and transform of the open animation, make the menu the containing block even for the fixed-position submenu. Dropdown and context submenus now render in a portal, like the menus themselves. Assisted-by: Claude (Opus 5.5 Medium) * ui: draw submenus like the menu they open from Submenus had smaller corners than their menus, and context menus had none of the dropdown's glass. Context-menu parts now match the dropdown's, and both submenus take the menu's corners and height cap, with their first row level with the row that opens them, 4px past the menu's edge. Sub-triggers take the items' radius and pointer. The submenus' height cap and zoom origin named the dropdown's CSS variables, which bits-ui does not set on submenus; they now use its --bits-menu-* ones. The chat group submenu takes the actions menu's z-[999999] layer, as it no longer renders inside that menu. Assisted-by: Claude (Opus 5.5 Medium) * ui: keep a late current-node write off a closed or switched conversation updateCurrentNode checked the active conversation, awaited the database write, then wrote currNode to whatever was active after it. When the conversation closed during the write it threw, and the reply ended in a streaming error dialog. When another conversation opened, that one got the wrong node. Assisted-by: Claude (Fable 5.2) * ui: have Llama Chat use the library's Model UI and app components Llama Chat still kept its own copies of what the library holds above the base components. It now takes them from @ggml-org/llama-ui too, and its copies go. ui/lib/ui - ModelId gains what Chat's had: the model's own draft kind, draft sidecars with their quant (ModelDraftSidecars, new), aliases, hideName and a tooltip, in the same badge order - entry points for them, like ui/<name>: @ggml-org/llama-ui/app/<group> (actions, content, forms, misc) and @ggml-org/llama-ui/models ui/apps/chat - ActionIcon, SearchInput, SyntaxHighlightedCode, Logo, ModelCapabilityIcons, ModelDownloadProgressBar and ModelDraftSidecars come from the library; Chat's copies and the two constants only they used are removed - ModelId and ModelOrgAvatar stay as thin wrappers: ModelId parses the raw id and applies the user's display settings, ModelOrgAvatar hides the avatar while Hub metadata is off - the svelte/* TypeScript path falls back to Svelte's types/index.d.ts: svelte/reactivity has no file of its own, so a library source importing it got its types from ui/lib/ui's own install when there was one Assisted-by: Claude (Opus 5.5 Medium) * ui: Llama UI takes the brand's colours and logo from llama-brand @ggml-org/llama-brand is now a dependency of the library, by the same GitHub tarball Llama Chat already installs, which now names it @ggml-org/llama-brand too. - primitives.css drops the 25 tokens it held copies of (the neutral greys, sand, the skies and cinder) and builds on llama-brand's css/colors.css instead; the skies' gradients point at llama-brand's. Apps import that file before theme.css, as they do Tailwind and tw-animate-css: the library's stylesheets import no package, so an app that compiles them from source resolves it from its own node_modules - Logo draws llama-brand's icon, in currentColor, and assets/logo.svg goes - Llama Chat's TypeScript paths resolve llama-brand from its own node_modules, like the library's other dependencies The fonts stay as the library's WOFF2 copies until llama-brand ships WOFF2 builds of them. Assisted-by: Claude (Opus 5.5 Medium) * ui: have Llama Chat take the library's constants, enums and helpers Llama Chat redefined most of what the library exports next to its components. Where the two were the same, Chat now re-exports the library's from the files that held them, so its own imports stay as they are. - the library gets entry points for them: @ggml-org/llama-ui/constants, @ggml-org/llama-ui/enums and @ggml-org/llama-ui/code, and @ggml-org/llama-ui/models carries the model data with the Model UI - from the library now: the shared CSS classes and code-block constants, the byte units, the memory-fit constants and minMemoryTierGb, the bit depth labels, the capability and modality icons, labels and order, ColorMode, TooltipSide, BooleanString, the model enums, ModelModalities, formatParameters, highlightCode and trimCodePadding - the library's modality order follows Chat's: vision, video, audio - Chat keeps its own where they differ: UI_DATA_ATTRS and ModelDownloadProgress are supersets of the library's (the latter extends it now), and formatFileSize counts in 1024s Assisted-by: Claude (Opus 5.5 Medium) * ui: give the chat form's add key and model selector a tighter shadow In light, the two keys inside the chat form, white on its white glass, took the control elevation, whose soft spread blended into the form. They take a new elevation-key instead: a 0.5px hairline all round and a 1px drop. In dark they keep the control elevation. Chosen from the options in Scrapbook › UI › Composer keys. - semantic tokens: --elevation-key (light: the hairline and the drop; dark: the control elevation) - component token: --chat-form-key-shadow, for the add key and every model selector trigger - DESIGN.md names it next to the other elevations Assisted-by: Claude (Opus 5.5 Medium)
llama-ui
A modern, feature-rich web interface for llama-server built with SvelteKit. This UI provides an intuitive chat interface with advanced file handling, conversation management, and comprehensive model interaction capabilities.
Llama UI supports two server operation modes:
- MODEL mode - Single model operation (standard llama-server)
- ROUTER mode - Multi-model operation with dynamic model loading/unloading
Table of Contents
- Features
- Getting Started
- Tech Stack
- Build Pipeline
- Architecture
- Data Flows
- Architectural Patterns
- Testing
Features
Chat Interface
- Streaming responses with real-time updates
- Reasoning content - Support for models with thinking/reasoning blocks
- Dark/light theme with system preference detection
- Responsive design for desktop and mobile
File Attachments
- Images - JPEG, PNG, GIF, WebP, SVG (with PNG conversion)
- Documents - PDF (text extraction or image conversion for vision models)
- Audio - MP3, WAV for audio-capable models
- Text files - Source code, markdown, and other text formats
- Drag-and-drop and paste support with rich previews
Conversation Management
- Branching - Branch messages conversations at any point by editing messages or regenerating responses, navigate between branches
- Regeneration - Regenerate responses with optional model switching (ROUTER mode)
- Import/Export - JSON format for backup and sharing
- Search - Find conversations by title or content
Advanced Rendering
- Syntax highlighting - Code blocks with language detection
- Math formulas - KaTeX rendering for LaTeX expressions
- Markdown - Full GFM support with tables, lists, and more
Multi-Model Support (ROUTER mode)
- Models manager - one table for every model the server can serve, split into loaded, downloading, favorites, local and hidden sections, with search, context/capability/modality filters, sorting, load/unload, delete from disk and hide. It opens from the sidebar, from a model row or from the selector.
- Model selector with Loaded/Available groups
- Automatic loading - Models load on selection
- Modality validation - Prevents sending images to non-vision models
- LRU unloading - Server auto-manages model cache
- Downloads - In-flight downloads stay visible above the selector and can be paused, resumed or cancelled from the manager
- Hub metadata - Avatars, context length and chat template come from the Hugging Face Hub only while the
Use Hugging Face Hub API for models metadatasetting is on. It is off by default, and the UI then shows what the server reports for/v1/models
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
Shift+Ctrl/Cmd+O |
New chat |
Shift+Ctrl/Cmd+E |
Edit conversation |
Shift+Ctrl/Cmd+D |
Delete conversation |
Ctrl/Cmd+K |
Search conversations |
Ctrl/Cmd+B |
Toggle sidebar |
Developer Experience
- Request tracking - Monitor token generation with
/slotsendpoint - Storybook - Component library with visual testing
- Hot reload - Instant updates during development
Getting Started
Prerequisites
- Node.js 18+ (20+ recommended)
- npm 9+
- llama-server running locally (for API access)
1. Install Dependencies
cd ui/apps/chat
npm ci
2. Start llama-server
In a separate terminal, start the backend server:
# Single model (MODEL mode)
./llama-server -m model.gguf
# Multi-model (ROUTER mode)
./llama-server --models-dir /path/to/models
3. Start Development Servers
npm run dev
This starts:
- Vite dev server at
http://localhost:5173- The main UI frontend app - Storybook at
http://localhost:6006- Component documentation
The Vite dev server proxies API requests to SERVER_ORIGIN (with fallback to default llama-server 9931 port):
// vite.config.ts proxy configuration
proxy: {
'/v1': SERVER_ORIGIN,
'/props': SERVER_ORIGIN,
'/models': SERVER_ORIGIN,
'/tools': SERVER_ORIGIN,
'/slots': SERVER_ORIGIN,
'/cors-proxy': SERVER_ORIGIN
},
Development Workflow
- Open
http://localhost:5173in your browser - Make changes to
.svelte,.ts, or.cssfiles - Changes hot-reload instantly
- Use Storybook at
http://localhost:6006for isolated component development
Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| Framework | SvelteKit + Svelte 5 | Reactive UI with runes ($state, $derived, $effect) |
| UI Components | shadcn-svelte + bits-ui | Accessible, customizable component library |
| Drawers | vaul-svelte | Draggable drawer overlays (mobile pickers, model pane) |
| Styling | TailwindCSS 4 | Utility-first CSS with design tokens |
| Database | IndexedDB (Dexie) | Client-side storage for conversations and messages |
| Build | Vite | Fast bundling with static adapter |
| Testing | Playwright + Vitest + Storybook | E2E, unit, and visual testing |
| Markdown | remark + rehype | Markdown processing with KaTeX and syntax highlighting |
Key Dependencies
{
"svelte": "^5.0.0",
"bits-ui": "^2.8.11",
"dexie": "^4.0.11",
"pdfjs-dist": "^5.4.54",
"highlight.js": "^11.11.1",
"rehype-katex": "^7.0.1"
}
Build Pipeline
Development Build
npm run dev
Runs Vite in development mode with:
- Hot Module Replacement (HMR)
- Source maps
- Proxy to llama-server
Production Build
npm run build
The build process:
- Vite Build - Bundles all TypeScript, Svelte, and CSS
- Static Adapter - Outputs to
../../../build/ui/apps/chat/dist(llama-server's static file directory) - Post-Build Script - Cleans up intermediate files
- Custom Plugin - Creates
index.htmlwith:- Inlined favicon as base64
- GZIP compression (level 9)
- Deterministic output (zeroed timestamps)
ui/apps/chat/ → build → build/ui/apps/chat/dist/
├── src/ ├── index.html (served by llama-server)
├── static/ └── (favicon inlined)
└── ...
SvelteKit Configuration
// vite.config.ts - options passed to sveltekit({ ... })
adapter: adapter({
pages: '../../../build/ui/apps/chat/dist', // Output directory
assets: '../../../build/ui/apps/chat/dist', // Static assets
fallback: 'index.html', // SPA fallback
strict: true
}),
output: {
bundleStrategy: 'inline' // Single-file bundle
}
Integration with llama-server
llama-ui is embedded directly into the llama-server binary:
npm run buildoutputsindex.htmltobuild/ui/apps/chat/dist/- llama-server compiles this into the binary at build time
- When accessing
/, llama-server serves the bundled HTML
This results in a single portable binary with the full Llama UI included.
Architecture
Llama UI follows a layered architecture with unidirectional data flow:
Routes → Components → Hooks → Stores → Services → Storage/API
High-Level Architecture
flowchart TB
subgraph Routes["📍 Routes"]
R1["/ (Welcome)"]
R2["/chat/[id]"]
R3["/mcp-servers"]
R4["/search"]
R5["/settings"]
RL["+layout.svelte"]
end
subgraph Components["🧩 Components"]
C_Screen["ChatScreen"]
C_Form["ChatForm"]
C_Messages["ChatMessages"]
C_Sidebar["ChatSidebar"]
C_Models["ModelsSelector"]
C_Settings["ChatSettings"]
C_Mcp["McpServers"]
end
subgraph Hooks["🔌 Hooks"]
H1["use-chat-screen-active-model"]
H2["use-processing-state"]
H3["use-context-gauge"]
H4["use-models-selector"]
H5["use-tools-panel"]
end
subgraph Stores["🗄️ Stores"]
S1["chatStore"]
S2["conversationsStore"]
S3["modelsStore"]
S4["mcpStore"]
S5["agenticStore"]
S6["serverStore"]
S7["settingsStore"]
S8["toolsStore"]
end
subgraph Services["⚙️ Services"]
SV1["ChatService"]
SV2["ModelsService"]
SV3["PropsService"]
SV4["DatabaseService"]
SV5["MCPService"]
SV6["ToolsService"]
SV7["SandboxService"]
end
subgraph Storage["💾 Storage"]
ST1["IndexedDB"]
ST2["LocalStorage"]
end
subgraph APIs["🌐 llama-server"]
API1["/v1/chat/completions"]
API2["/props"]
API3["/models/*"]
API4["/tools"]
end
R1 & R2 --> C_Screen
RL --> C_Sidebar
C_Screen --> C_Form & C_Messages & C_Settings
C_Screen --> H1 & H2 & H3
C_Models --> H4
C_Mcp --> S4
C_Screen --> S1 & S2 & S3
C_Models --> S3
H1 --> S3
S1 --> SV1 & SV4
S2 --> SV4
S3 --> SV2 & SV3
S4 --> SV5
S5 --> SV1 & SV5 & SV6 & SV7
SV4 --> ST1
SV1 --> API1
SV2 --> API3
SV3 --> API2
SV6 --> API4
Layer Breakdown
Routes (src/routes/)
/- Welcome screen, creates new conversation/chat/[id]- Active chat interface/mcp-servers- MCP server management/search- Conversation search/settings- Settings (optional[[section]])+layout.svelte- Sidebar, navigation, global initialization
Components (src/lib/components/)
Application components live in app/. The base components (the shadcn-svelte primitives: button, dialog, tooltip…), the design tokens, the fonts and the surfaces are Llama UI's, in ui/lib/ui: the app imports them as @ggml-org/llama-ui/ui/<name> and compiles them from source as part of its own build, with no install or build of the library (see scripts/llama-ui.js).
Chat Components (app/chat/):
| Component | Responsibility |
|---|---|
ChatScreen/ |
Main chat container, coordinates message list, input form, and attachments |
ChatForm/ |
Message input textarea with file upload, paste handling, keyboard shortcuts |
ChatMessages/ |
Message list with branch navigation, regenerate/continue/edit actions |
ChatAttachments/ |
File attachment previews, drag-and-drop, PDF/image/audio handling |
ChatSettings/ |
Parameter sliders (temperature, top-p, etc.) with server default sync |
ChatSidebar/ |
Conversation list, search, import/export, navigation |
Dialog Components (app/dialogs/):
| Component | Responsibility |
|---|---|
DialogChatSettings |
Full-screen settings configuration |
DialogManageModels |
Models manager: browse, load, download and delete models |
DialogModelInformation |
Model details (context size, modalities, parallel slots) |
DialogChatAttachmentsPreview |
Full preview for images, PDFs (text or page view), code |
DialogConfirmation |
Generic confirmation for destructive actions |
DialogConversationRename |
Edit conversation title |
Server/Model Components (app/servers/, app/models/):
| Component | Responsibility |
|---|---|
ServerErrorSplash |
Error display when server is unreachable |
ModelsSelector/ |
Model dropdown and mobile sheet: favorites, loaded and local sections, rows windowed and folded into families |
ModelsManager/ |
Models manager table and model pane: sections, filters, sorting, quants folded per repo, downloads |
ModelAvatar |
Org avatar of a model, with the quantizer badge; follows the family grouping of the list |
ModelId, ModelBadge |
Model name, aliases, tags, quantization and draft sidecar badges |
ModelContext, ModelCapabilities |
Context window and capability icons, filled from the Hub when it is enabled |
Shared UI Components (app/misc/):
| Component | Responsibility |
|---|---|
MarkdownContent |
Markdown rendering with KaTeX, syntax highlighting, copy buttons |
SyntaxHighlightedCode |
Code blocks with language detection and highlighting |
ActionIcon, DropdownMenuActions |
Reusable action button and action menu |
BadgesModality, BadgeInfo |
Status and capability badges |
CollapsibleSection, CollapsibleRegion |
Section header with a trigger that expands in place |
GroupedList |
Grouped rows with foldable groups, per-group windows and show-more rows |
ScrollCarousel, TruncatedText |
Horizontal scroll strip and single-line truncation with tooltip |
Hooks (src/lib/hooks/)
Hooks are the thin view-layer between components and stores: they own UI concerns (scroll, drag-and-drop, keyboard shortcuts, pickers, selection) and translate store state into view state.
| Hook | Responsibility |
|---|---|
use-chat-screen-active-model |
Active model resolution + modality capability detection |
use-processing-state |
View over chatStore.processing for streaming progress/tokens |
use-context-gauge |
View over contextStatsStore for the context usage gauge |
use-models-selector |
Model selector state: hidden models, family grouping, windowed rows, selection and load on pick |
use-tools-panel |
Tools panel state |
use-reasoning-menu |
Reasoning-effort menu state |
use-attachment-menu |
Attachment menu + modality flags |
use-draft-messages |
Per-chat draft message/files persistence |
use-chat-form-pickers |
Chat form pickers (commands, mentions) |
use-debounced-search |
Shared debounced async search for pickers |
use-picker-navigation |
Picker keyboard navigation |
use-chat-message-edit-context |
Message edit context (content + extras) |
use-chat-screen-drag-and-drop |
Drag-and-drop state machine |
use-chat-screen-file-upload |
File upload queue + capability validation |
use-stick-to-bottom |
Follows new content while the reader sits at the bottom of a scroller |
use-marquee-selection |
Shift+click / marquee range selection |
use-keyboard-shortcuts |
Global keyboard shortcuts |
use-settings-navigation |
Settings section navigation |
use-pwa |
PWA install/update + version mismatch detection |
Stores (src/lib/stores/)
Stores own reactive application state as Svelte 5 runes. Larger stores are split into directories and compose focused sub-stores behind a narrow host interface (see Architectural Patterns).
| Store | Responsibility |
|---|---|
chatStore |
Chat lifecycle, streaming, abort control, error handling; composes processing, activity, streams, flows |
conversationsStore |
Conversation CRUD, message branching, navigation, import/export; composes preferences |
modelsStore |
Model list, selection, loading/unloading (ROUTER), recent picks, favorites, hidden models and list open state; composes props, status |
mcpStore |
MCP host role: multi-server lifecycle, tool routing, server icons; composes health, resources |
agenticStore |
Multi-turn agentic loop orchestration, tool execution; composes gates |
serverStore |
Server connection state, /props, role detection, modalities |
settingsStore |
User preferences, theme, parameter sync with server defaults |
toolsStore |
Tool registry: server + MCP tools, enabled set for the LLM |
permissionsStore |
Persisted tool permission grants |
contextStatsStore |
Context window usage for the active conversation |
draftMessagesStore |
Per-chat draft message/files |
deviceStore |
Browser environment signals (mobile, OS, theme) |
versionStore |
Build version information |
Services (src/lib/services/)
Services are a stateless protocol layer: static methods, pure I/O, no reactive state. Stores consume them for all API and storage access.
| Service | Responsibility |
|---|---|
ChatService |
/v1/chat/completions streaming + SSE parsing, message format conversion |
ModelsService |
/models, /models/load, /models/unload |
PropsService |
/props, /props?model= |
HuggingFaceService |
Hugging Face Hub metadata: model details, avatars, README and file tree, cached per repo and off unless the Hub setting is on |
DatabaseService |
IndexedDB operations via Dexie |
MCPService |
MCP protocol: transports, connect, list/execute tools, prompts, resources |
ToolsService |
Server tool list/execute/stream (/tools) |
SandboxService |
Browser JS execution in a sandboxed worker |
ParameterSyncService |
Syncs settings with server defaults |
ConversationTransferService |
Conversation import/export JSONL + ZIP format |
MigrationService |
Non-destructive localStorage/IndexedDB migrations |
RouterService |
Dynamic route URL construction |
Data Flows
MODEL Mode (Single Model)
sequenceDiagram
participant User
participant UI
participant Stores
participant DB as IndexedDB
participant API as llama-server
Note over User,API: Initialization
UI->>Stores: initStores() (awaited by route loads)
Stores->>Stores: run migrations
Stores->>DB: load conversations (background)
Stores->>API: GET /props
API-->>Stores: server config
Stores->>API: GET /v1/models
API-->>Stores: single model (auto-selected)
Note over User,API: Chat Flow
User->>UI: send message
Stores->>DB: save user message
Stores->>API: POST /v1/chat/completions (stream)
loop streaming
API-->>Stores: SSE chunks
Stores-->>UI: reactive update
end
Stores->>DB: save assistant message
ROUTER Mode (Multi-Model)
sequenceDiagram
participant User
participant UI
participant Stores
participant API as llama-server
Note over User,API: Initialization
Stores->>API: GET /props
API-->>Stores: {role: "router"}
Stores->>API: GET /models
API-->>Stores: models[] with status
Note over User,API: Model Selection
User->>UI: select model
alt model not loaded
Stores->>API: POST /models/load
loop poll status
Stores->>API: GET /models
end
Stores->>API: GET /props?model=X
end
Stores->>Stores: validate modalities
Note over User,API: Chat Flow
Stores->>API: POST /v1/chat/completions {model: X}
loop streaming
API-->>Stores: SSE chunks + model info
end
Architectural Patterns
1. Reactive State with Svelte 5 Runes
All stores use Svelte 5's fine-grained reactivity:
// Store with reactive state
class ChatStore {
#isLoading = $state(false);
#currentResponse = $state('');
// Derived values auto-update
get isStreaming() {
return $derived(this.#isLoading && this.#currentResponse.length > 0);
}
}
// Exported reactive accessors
export const isLoading = () => chatStore.isLoading;
export const currentResponse = () => chatStore.currentResponse;
2. Unidirectional Data Flow
Data flows in one direction, making state predictable:
flowchart LR
subgraph UI["UI Layer"]
A[User Action] --> B[Component]
end
subgraph State["State Layer"]
B --> C[Store Method]
C --> D[State Update]
end
subgraph IO["I/O Layer"]
C --> E[Service]
E --> F[API / IndexedDB]
F -.->|Response| D
end
D -->|Reactive| B
Components dispatch actions to stores, stores coordinate with services for I/O, and state updates reactively propagate back to the UI.
3. Per-Conversation State
Enables concurrent streaming across multiple conversations. Loading is tracked
per conversation by the activity ledger (chatStore.activity), while streaming
state and abort controllers live in per-conversation maps:
class ChatStore {
chatStreamingStates = new SvelteMap<string, { response: string; messageId: string }>();
abortControllers = new SvelteMap<string, AbortController>();
}
4. Message Branching with Tree Structure
Conversations are stored as a tree, not a linear list:
interface DatabaseMessage {
id: string;
parent: string | null; // Points to parent message
children: string[]; // List of child message IDs
// ...
}
interface DatabaseConversation {
currentNode: string; // Currently viewed branch tip
// ...
}
Navigation between branches updates currentNode without losing history.
5. Layered Service Architecture
Stores handle state; services handle I/O:
┌─────────────────┐
│ Stores │ Business logic, state management
├─────────────────┤
│ Services │ API calls, database operations
├─────────────────┤
│ Storage/API │ IndexedDB, LocalStorage, HTTP
└─────────────────┘
6. Server Role Abstraction
Single codebase handles both MODEL and ROUTER modes:
// serverStore.ts
get isRouterMode() {
return this.role === ServerRole.ROUTER;
}
// Components conditionally render based on mode
{#if isRouterMode()}
<ModelsSelector />
{/if}
7. Modality Validation
Prevents sending attachments to incompatible models. The
use-chat-screen-active-model hook derives the active model's capabilities
from modelsStore.props:
// use-chat-screen-active-model hook
const hasVisionModality = $derived.by(() => modelsStore.props.modelSupportsVision(activeModelId));
const hasAudioModality = $derived.by(() => modelsStore.props.modelSupportsAudio(activeModelId));
8. Persistent Storage Strategy
Data is persisted across sessions using two storage mechanisms:
flowchart TB
subgraph Browser["Browser Storage"]
subgraph IDB["IndexedDB (Dexie)"]
C[Conversations]
M[Messages]
end
subgraph LS["LocalStorage"]
S[Settings Config]
O[User Overrides]
T[Theme Preference]
end
end
subgraph Stores["Svelte Stores"]
CS[conversationsStore] --> C
CS --> M
SS[settingsStore] --> S
SS --> O
SS --> T
end
- IndexedDB: Conversations and messages (large, structured data)
- LocalStorage: Settings, user parameter overrides, theme, model favorites, recent picks, hidden models and model list open state (small key-value data)
- Memory only: Server props, model list (fetched fresh on each session), Hugging Face Hub details (cached per repo for the session)
9. Remote Assets Under Cross-Origin Isolation
llama-server serves the UI with Cross-Origin-Embedder-Policy: require-corp and Cross-Origin-Opener-Policy: same-origin, so a cross-origin subresource has to be allowed by the target origin. The UI handles that per asset kind:
- Hub avatars are requested in CORS mode (
crossorigin="anonymous"), which the Hub allows - Hub metadata is fetched with
fetch(), which is a CORS request by default, and only while the Hub setting is on - MCP server icons and web-search result favicons have no CORS guarantee, so they go through the server's
/cors-proxywhen the user started llama-server with--ui-mcp-proxy; without it they fall back to the bundled glyph - Per-row Hub lookups wait until the row is near the viewport (the
nearViewportaction), so a long model list does not fire one request per row on mount
10. Nested Surfaces
The sidebar stacks four surfaces, outermost first:
| Layer | Example | Corners |
|---|---|---|
| Page | the body background | none |
| Panel | the sidebar | rounded-2xl |
| Group | the sidebar's footer, inset in it | inset-group-surface |
| Row | Models, MCP or Settings in a group | rounded-(--surface-row-radius) |
A row keeps its corners concentric with its group's: its radius is the group's less the padding between their edges, so the curves run parallel instead of pinching at the corners. app.css holds the three tokens (--surface-group-radius, which follows the design system's --inset-group-radius, --surface-group-padding and the derived --surface-row-radius); change the group's radius or padding and the rows follow. A group pads its rows with p-(--surface-group-padding). SidebarNavigationActions rounds every row from the token, so the actions at the top of the sidebar (New chat, Search) match the footer's rows; a phone sizes its rows for a thumb instead. A selected row takes selected-row-surface, the group's edge and shade around a tint, where a hovered one is only tinted, so the two never look alike. The group's hairline border is left out of the sum. tests/client/nested-surfaces.svelte.test.ts checks the rule on the rendered footer.
Testing
Test Types
| Type | Tool | Location | Command |
|---|---|---|---|
| Unit | Vitest | tests/unit/ |
npm run test:unit |
| UI/Visual | Storybook + Vitest | tests/stories/ |
npm run test:ui |
| E2E | Playwright | tests/e2e/ |
npm run test:e2e |
| Client | Vitest | tests/client/. |
npm run test:unit |
Running Tests
# All tests
npm run test
# Individual test suites
npm run test:e2e # End-to-end (requires llama-server)
npm run test:client # Client-side unit tests
npm run test:server # Server-side unit tests
npm run test:ui # Storybook visual tests
Locally, the browser tests (e2e, client and Storybook) run in your installed Google Chrome with its sandbox on, since Chrome updates itself and Playwright's bundled Chromium lags behind security fixes. CI (CI set) uses the bundled Chromium from npx playwright install.
Storybook Development
npm run storybook # Start Storybook dev server on :6006
npm run build-storybook # Build static Storybook
Linting and Formatting
npm run lint # Check code style
npm run format # Auto-format with Prettier
npm run check # TypeScript type checking
Project Structure
ui/apps/chat/
├── src/
│ ├── lib/
│ │ ├── components/ # Application components (base ones come from ui/lib/ui)
│ │ ├── hooks/ # Svelte hooks
│ │ ├── stores/ # State management
│ │ ├── services/ # API and database services
│ │ ├── types/ # TypeScript interfaces
│ │ └── utils/ # Utility functions
│ ├── routes/ # SvelteKit routes
│ └── styles/ # Global styles
├── static/ # Static assets
├── tests/ # Test files
└── .storybook/ # Storybook configuration
Related Documentation
- llama.cpp Server README - Full server documentation
- Multimodal Documentation - Image and audio support
- Function Calling - Tool use capabilities