Official
settings
Built-in settings UI (JavaScript UI plugin).
The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/settings@0.2.7
Permissions in 0.2.7
Files
views/onboarding-preview.tsx23.9 KB
// The window beside the guide: Divergence itself at its real sizes, the
// new chat page with its living background, filling the guide's right
// side. It follows the guide's choices (the agents in the picker, the
// folders, the plugins that are on, the reviews and saved changes waiting
// in the sidebar). On Welcome it builds itself part by part and names the
// plugin behind each part; on Visuals it is a reply drawn by the real
// markdown renderer.
// HTM whitespace is significant; keep these templates out of Prettier's HTML formatter.
import * as kit from "divergence";
import type { Element, IconName } from "divergence";
import type { Onboarding, THEMES, Visual } from "../onboarding.ts";
import type { AgentEntry } from "../controller.ts";
import { column, fill, row } from "./layout.tsx";
import { CHECK, CIRCLE_CHECK, PENCIL } from "../../sdk/ui/icons.ts";
type Actions = Onboarding["Service"];
const RAISED = kit.RAISED ?? { elevation: "raised" };
const FLAT = kit.FLAT ?? { elevation: "none" };
// A theme family's colours, for its swatch in the guide. They are the dark
// presets' own values: a swatch shows a theme that is not the one in force,
// so it cannot use the current theme's tokens.
export const THEME_SWATCHES: Record<(typeof THEMES)[number]["id"], { bg: string; ground: string; line: string; text: string }> = {
divergence: { bg: "#0a1224", ground: "#151b24", line: "#25466f", text: "#9aa4b5" },
vscode: { bg: "#1f1f1f", ground: "#181818", line: "#0078d4", text: "#9d9d9d" },
"high-contrast": { bg: "#000000", ground: "#000000", line: "#6fc3df", text: "#ffffff" },
compact: { bg: "#0a1224", ground: "#151b24", line: "#25466f", text: "#9aa4b5" },
};
// The Visuals step's examples: a prompt and the reply that answers it, with
// the fence the visuals plugin draws. The figures are made up for the example.
export const VISUAL_EXAMPLES: Record<Visual, { title: string; prompt: string; reply: string }> = {
chart: {
title: "A chart",
prompt: "How long did our builds take this month?",
reply: `Builds got faster after the cache change on the 12th.
\`\`\`chart
{"version":1,"kind":"bar","title":"Average build (minutes)","labels":["Oct 5","Oct 12","Oct 19","Oct 26"],"series":[{"name":"Minutes","values":[14.2,9.8,8.9,8.1]}]}
\`\`\`
An example reply; the numbers are made up.`,
},
diagram: {
title: "A diagram",
prompt: "How does a request reach the database?",
reply: `Every request goes through the cache first, and only a miss reaches the database.
\`\`\`mermaid
flowchart LR
Browser --> API
API --> Cache
Cache -->|miss| Database
Cache -->|hit| API
\`\`\`
An example reply.`,
},
table: {
title: "A table",
prompt: "What can the Files, Git and Terminal plugins do?",
reply: `Each asks only for what it uses:
| Plugin | Draws | Allowed to |
| --- | --- | --- |
| files | The file tree | Read files in your folders |
| git | Changes and commits | Read and commit Git changes |
| terminal | A shell | Run a shell in your folders |`,
},
};
// The Welcome step builds the window in this order, then names its plugins.
const BUILD = { strip: 0, sidebar: 140, pane: 280, composer: 420, rail: 560, tags: 900 } as const;
const TAG_STEP = 110;
// Rises a little and fades in after `delay` ms; without a delay, it is just there.
function appear(key: string, delay: number | null, child: Element, layout: Record<string, unknown> = {}) {
if (delay === null) return <div key={key} {...layout}>{child}</div>;
return <div key={key} {...layout} position="relative" top={8} opacity={0} motion={{ to: { top: 0, opacity: 1 }, duration: 480, delay, easing: "spring" }}>{child}</div>;
}
// A plugin's name, beside the part of the window it draws.
function tag(name: string, order: number | null, off = false) {
const pill = (
<div {...row} height={20} paddingX={7} borderRadius="sm" background={off ? "muted" : "info"}>
<div fontSize="xs" fontWeight={600} lineHeight={14} whiteSpace="nowrap" color={off ? "mutedForeground" : "background"}>{off ? `${name} is off` : name}</div>
</div>
);
return appear(`tag-${name}`, order === null ? null : BUILD.tags + order * TAG_STEP, pill, { flexShrink: 0 });
}
// An agent as the composer and the sidebar show it.
interface AgentMark {
readonly id: string;
readonly name: string;
readonly icon?: string | undefined;
}
interface Folder {
readonly name: string;
readonly plugins: boolean;
}
type Section = "Drafts" | "Running" | "Finished";
interface SideRow {
readonly title: string;
readonly section: Section;
readonly live?: string;
readonly folder: Folder;
readonly selected?: boolean;
}
interface Look {
readonly animate: boolean;
readonly tags: boolean;
readonly plugins: { readonly files: boolean; readonly git: boolean; readonly terminal: boolean; readonly market: boolean };
}
// Ids inside the preview start with this, apart from the app's own.
const ID = "onboarding-preview";
const folderIcon = (folder: Folder, small = true, tone = "muted") =>
folder.plugins ? <icon name="divergence" small={small} tone={tone} /> : <icon name="folder" small={small} tone={tone} />;
// The marks the sidebar gives these sections' headings.
const SECTION_MARK = { Drafts: PENCIL, Running: null, Finished: CHECK } as const;
// The sidebar as the sidebar plugin draws it: chats by section and the
// folded Complete heading beside Options.
function sidebar(rows: readonly SideRow[], look: Look) {
const t = (name: string, order: number) => (look.tags ? tag(name, look.animate ? order : null) : null);
const sections = (["Drafts", "Finished", "Running"] as const).filter((section) => rows.some((r) => r.section === section));
const glyph = (r: SideRow, i: number) =>
r.section === "Drafts"
? <button id={`${ID}-play-${i}`} icon="play" variant="ghost" small />
: (
<div {...row} justifyContent="center" width={17} height={17} flexShrink={0}>
{r.section === "Running" ? <spinner activity /> : folderIcon(r.folder, true, "faint")}
</div>
);
const chat = (r: SideRow, i: number) => (
<item key={`row-${i}`} id={`${ID}-row-${i}`} label={r.title} selected={!!r.selected} {...FLAT} background={r.selected ? "transparent" : undefined} sublabel={r.live} sublabelTone="muted" stacked>
<slot name="leading">{glyph(r, i)}</slot>
{r.section === "Running" || r.section === "Drafts" ? folderIcon(r.folder, true, "faint") : null}
</item>
);
const selected = rows.findIndex((r) => r.selected);
return (
<div {...column} width={268} flexShrink={0} padding="small" paddingX="small" paddingTop={0}>
<div {...column} {...fill} paddingX="small" paddingY="medium" position="relative">
{selected >= 0 ? <div follows={`${ID}-row-${selected}`} width="100%" height="100%" background="accent" borderRadius="sm" {...RAISED} /> : null}
{sections.map((section, index) => {
const inSection = rows.filter((r) => r.section === section);
return [
section === "Running" ? <spacer key="dock-space" /> : null,
(
<div key={`heading-${section}`} {...column} paddingTop={index ? "0.75rem" : 0}>
<item heading id={`${ID}-section-${section}`} iconSvg={SECTION_MARK[section]} busy={!SECTION_MARK[section]} iconTone="foreground" label={section} tone="foreground" opacity={0.8}>
<text style="body" size={10.72} weight={600} tone="foreground">{String(inSection.length)}</text>
</item>
</div>
),
...inSection.map((r) => chat(r, rows.indexOf(r))),
];
})}
{look.tags ? <div {...row} paddingX="small" paddingTop={10}>{t("sidebar", 0)}</div> : null}
</div>
{look.tags ? <div {...row} justifyContent="end" gap="small" paddingX="small">{look.plugins.market ? t("market", 6) : null}{t("settings", 7)}</div> : null}
<div {...row} padding="small" paddingBottom={4} gap={4}>
<div {...column} {...fill} alignItems="flex-start">
<item heading id={`${ID}-section-Complete`} iconSvg={CIRCLE_CHECK} iconTone="foreground" label="Complete" tone="foreground" opacity={0.8}>
<text style="body" size={10.72} weight={600} tone="foreground">0</text>
</item>
</div>
<div id={`${ID}-options`} {...row} justifyContent="center" width={22} height={22} borderRadius="full" background="muted"><icon name="user-round" small tone="muted" /></div>
</div>
</div>
);
}
function rail(look: Look) {
const button = (name: IconName, on: boolean) =>
on ? <div {...row} justifyContent="center" width={30} height={30}><icon name={name} tone="muted" /></div> : null;
return (
<div {...column} width={49} flexShrink={0} alignItems="center" gap={5} paddingBottom={6}>
{button("files", look.plugins.files)}
{button("git-branch", look.plugins.git)}
{button("activity", true)}
<spacer />
{button("square-terminal", look.plugins.terminal)}
</div>
);
}
// The tags of the rail's plugins, in the pane's edge beside their icons.
function railTags(look: Look, offs: boolean) {
if (!look.tags) return null;
const order = (n: number) => (look.animate ? n : null);
const one = (name: "files" | "git" | "terminal", n: number) =>
look.plugins[name] ? tag(name, order(n)) : offs ? tag(name, null, true) : null;
return <div position="absolute" top={4} bottom={12} right={57} {...column} alignItems="end" gap={15} zIndex={3}>{one("files", 3)}{one("git", 4)}<spacer />{one("terminal", 5)}</div>;
}
// What the composer's pills show: the agent, its model with the reasoning
// beside it, and its approval mode.
export interface AgentLook {
readonly agent: AgentMark;
readonly model: string | null;
readonly effort: string | null;
readonly mode: string | null;
}
// The new chat page's headline, as the chat plugin sets it.
const HEADLINE = { fontSize: "1.875rem", bold: false, weight: 500, fontFamily: "Bricolage Grotesque" } as const;
// What opens over the page: the agent picker under its pill, or the
// workspace picker under the chip.
interface Opened {
readonly at: "agent" | "workspace";
readonly menu: Element;
}
// Drawn last in the page, so it lies over the prompt box like the real menu.
const over = (menu: Element, top: number) => <div position="absolute" top={top} left={14} zIndex={5}>{menu}</div>;
function composer(first: AgentLook | null) {
const compact = (child: Element, maxWidth = 220) =>
<div {...row} gap="small" padding="small" maxWidth={maxWidth} minWidth={0} flexShrink={1}>{child}</div>;
const pills = first
? [
compact(<select id={`${ID}-agent`} value="agent" small ghost options={[{ value: "agent", label: first.agent.name, svg: first.agent.icon }]} />),
first.model ? compact(<combobox id={`${ID}-model`} look="toolbar" label={first.model} detail={first.effort ?? undefined} options={[]} />, 340) : null,
first.mode ? compact(<select id={`${ID}-mode`} value="mode" small ghost options={[{ value: "mode", label: first.mode }]} />) : null,
]
: [<div {...row} padding="small"><text style="body" size="xs" tone="faint">No agent yet</text></div>];
const ring = [{ op: "roundRect" as const, x: 1, y: 1, width: 12, height: 12, radius: 6, stroke: "mutedForeground/25", lineWidth: 2 }];
return (
<div {...column} gap="small" padding="small" position="relative">
<div {...column} background="card/40" backdrop={{ blur: 6 }} borderRadius="xl" {...RAISED}>
<div {...row}>
<div {...column} {...fill} gap="small" padding="small" paddingY={0}>
<input id={`${ID}-prompt`} value="" multiline ghost placeholder="@ files, / commands, $ skills" />
</div>
<div {...row} gap="small" padding="medium" alignSelf="end">
<button id={`${ID}-attach`} icon="paperclip" variant="ghost" small />
<button id={`${ID}-queue`} icon="list-plus" variant="ghost" small />
<button id={`${ID}-send`} icon="corner-down-left" variant="primary" small />
</div>
</div>
</div>
<div {...row} gap="small" paddingY="small">
<div {...row} {...fill} gap="small" minWidth={0} overflow="hidden">{pills}</div>
<div {...row} gap="small" padding="small" paddingX={6} paddingY={2} height={22} borderRadius={6}>
<canvas width={14} height={14} commands={ring} />
<text style="body" size="xs" tone="faint">{"—"}</text>
</div>
</div>
</div>
);
}
// The new chat page, as the chat plugin draws it.
function newChat(folder: Folder, first: AgentLook | null, opened: Opened | null, look: Look) {
const delay = (n: number) => (look.animate ? n : null);
const headline = (
<div {...row} gap={0} padding="small" justifyContent="center">
<text style="body" {...HEADLINE}>What should we do in</text>
<div {...row} gap={6} padding="small" paddingX={6} paddingLeft={5} paddingY={2} borderRadius="md">
{folderIcon(folder, false)}
<text style="body" {...HEADLINE}>{folder.name}</text>
<icon name="chevron-down" small tone="muted" />
</div>
<text style="body" {...HEADLINE}>{"?"}</text>
</div>
);
const chip = (
<div {...row} alignSelf="stretch" gap="small" padding="small">
<div {...row} gap={5} padding="small" paddingX={8} paddingY={2} maxWidth={220} background="subtle" borderRadius={11}>
{folderIcon(folder)}
<text style="body" size="xs" tone="muted" truncate>{folder.name}</text>
<icon name="chevron-down" small tone="faint" />
</div>
</div>
);
// The agent's plugin, named by the agent's id; the example's agent may not be installed.
const agentTag = look.tags && first?.agent.id ? <div {...row} paddingX="small">{tag(first.agent.id.split(":")[0] ?? first.agent.id, look.animate ? 2 : null)}</div> : null;
// The workspace menu opens under the chip, the agent's under the pills.
const stack = (
<div {...column} width="100%" marginX="auto" gap="small" padding="small" maxWidth={768} position="relative">
{chip}
{composer(first)}
{opened ? over(opened.menu, opened.at === "workspace" ? 40 : 128) : agentTag}
</div>
);
return (
<div {...column} {...fill} gap="large" padding="large" alignItems="center" justifyContent="center">
{appear("headline", delay(BUILD.composer - 60), headline)}
{appear("composer", delay(BUILD.composer), stack, { display: "flex", justifyContent: "center", width: "100%" })}
</div>
);
}
// A list that opens over the page, like the kernel's select and combobox menus.
const menu = (rows: readonly { key: string; mark: Element; title: string; detail?: string; on?: boolean }[], action?: string) =>
(
<div {...column} gap={2} padding={4} borderRadius="md" background="popover" {...RAISED} width={320}>
{rows.map((r) => (
<div key={r.key} {...row} gap={8} minHeight={28} paddingX={8} paddingY={4} borderRadius="sm" background={r.on ? "accent" : undefined}>
{r.mark}
<div {...column} {...fill}>
<text style="body" size="sm" truncate>{r.title}</text>
{r.detail ? <text style="body" size="xs" tone="muted" truncate>{r.detail}</text> : null}
</div>
{r.on ? <icon name="check" small tone="muted" /> : null}
</div>
))}
{action ? (
<div {...row} gap={8} height={28} paddingX={8} borderRadius="sm">
<icon name="folder-plus" small tone="muted" />
<text style="body" size="sm" tone="muted">{action}</text>
</div>
) : null}
</div>
);
function windowOf(rows: readonly SideRow[] | null, folder: Folder, pane: Element, look: Look, offs = false) {
const delay = (n: number) => (look.animate ? n : null);
const strip = (
<div {...row} height={40} paddingLeft={11} paddingRight={12} gap={10}>
<div {...row} gap={11} marginRight={14}>
{["#ff5f57", "#febc2e", "#28c840"].map((c) => <div key={c} width={12} height={12} borderRadius="full" background={c} />)}
</div>
<icon name="panel-left" tone="muted" />
{rows ? <div {...row} gap={4}>
<button id={`${ID}-new-chat`} icon="plus-large" variant="ghost" muted />
<button id={`${ID}-filter`} icon="folders" variant="ghost" muted />
<button id={`${ID}-search`} icon="search" variant="ghost" muted />
</div> : null}
<text style="body" weight={600}>New Chat</text>
<spacer />
{look.tags ? tag("themes", look.animate ? 1 : null) : null}
<spacer />
<div {...row} gap={5} padding="small" paddingX={8} paddingY={2} maxWidth={220} background="subtle" borderRadius={11}>
{folderIcon(folder, false)}
<text style="body" size="xs" tone="muted" truncate>{folder.name}</text>
<icon name="chevron-down" tone="faint" />
</div>
<div paddingLeft={8}><icon name="refresh-cw" small tone="muted" /></div>
</div>
);
const stage = (
<div id={`${ID}-stage`} {...column} {...fill} position="relative" borderRadius={17} background="stage" ambient="caustics" overflow="hidden" {...RAISED} marginLeft={rows ? 0 : 6} marginBottom={6}>
{look.tags ? <div position="absolute" left={14} top={14} zIndex={3}>{tag("chat", look.animate ? 0 : null)}</div> : null}
{pane}
</div>
);
return (
<div {...column} {...fill} minWidth={0} borderRadius={17} background="sidebar" overflow="hidden" {...RAISED}>
{appear("strip", delay(BUILD.strip), strip)}
<div {...row} {...fill} alignItems="stretch" position="relative">
{rows ? appear("sidebar", delay(BUILD.sidebar), sidebar(rows, look), { display: "flex" }) : null}
{appear("pane", delay(BUILD.pane), stage, { display: "flex", flexGrow: 1, flexShrink: 1, flexBasis: "0%", minWidth: 0 })}
{appear("rail", delay(BUILD.rail), rail(look), { display: "flex" })}
{railTags(look, offs)}
</div>
</div>
);
}
function pluginOn(actions: Actions, name: string) {
return actions.state.plugins.find((p) => p.name === name)?.enabled ?? true;
}
// The Plugins workspace as the app names it ("Divergence"), with its mark.
function ownFolder(actions: Actions): Folder {
return { name: actions.pluginsWorkspace()?.name ?? "Divergence", plugins: true };
}
// The changes saved for an agent, waiting as drafts in the Plugins workspace.
function waiting(actions: Actions): SideRow[] {
return actions.state.saved.map((title) => ({ title, section: "Drafts" as const, folder: ownFolder(actions) }));
}
function caption(text: string) {
return <div {...row} justifyContent="center" paddingTop={10}><text style="body" size="xs" tone="muted">{text}</text></div>;
}
// The folder the first chat opens in, named as the app names it.
function firstFolder(actions: Actions): Folder {
const workspace = actions.state.workspaces.find((w) => w.id === actions.state.workspaceId) ?? actions.pluginsWorkspace();
return workspace ? { name: workspace.name, plugins: Boolean(workspace.mark) } : ownFolder(actions);
}
// An agent as its composer shows it, with its own model and mode once read.
function lookOf(actions: Actions, agent: AgentEntry | null): AgentLook | null {
if (!agent) return null;
const known = actions.state.firstLook?.agentId === agent.id ? actions.state.firstLook : null;
return { agent, model: known?.model ?? null, effort: null, mode: known?.mode ?? null };
}
// The Welcome example: one agent, model, effort and mode, whatever is set
// up here, with no model version so it does not date. The mark is the
// agent's own when it is installed.
const EXAMPLE = { name: "Agent", model: "Opus", effort: "High", mode: "Auto" } as const;
function welcome(actions: Actions): [Element, Element] {
const installed = actions.state.agents[0];
const agent: AgentMark = { id: installed?.id ?? "", name: installed?.name ?? EXAMPLE.name, icon: installed?.icon };
const folder = firstFolder(actions);
const rows: SideRow[] = [
{ title: "New Chat", section: "Drafts", folder, selected: true },
{ title: "Add CSV export to reports", section: "Running", live: "Writing the export test", folder },
{ title: "Fix the failing date test", section: "Finished", live: "All 214 tests pass", folder },
{ title: "Show a word count under the prompt", section: "Finished", live: "The count shows under the prompt", folder: ownFolder(actions) },
];
const look: Look = { animate: true, tags: true, plugins: { files: true, git: true, terminal: true, market: true } };
const first: AgentLook = { agent, model: EXAMPLE.model, effort: EXAMPLE.effort, mode: EXAMPLE.mode };
return [windowOf(rows, folder, newChat(folder, first, null, look), look), caption("Each label is a plugin. The chats are an example.")];
}
function stepWindow(actions: Actions): [Element, Element] {
const state = actions.state;
const step = state.step;
const folder = firstFolder(actions);
const firstAgent = actions.readyAgents().find((a) => a.id === state.firstAgent) ?? null;
const first = lookOf(actions, firstAgent);
const plugins = { files: pluginOn(actions, "files"), git: pluginOn(actions, "git"), terminal: pluginOn(actions, "terminal"), market: pluginOn(actions, "market") };
const rows = waiting(actions);
const side = rows.length ? rows : null;
const look: Look = { animate: false, tags: step === 3, plugins };
if (step === 1) {
const ready = actions.readyAgents();
const opened = ready.length
? { at: "agent" as const, menu: menu(ready.map((a) => ({ key: a.id, mark: <icon name="bot" small tone="muted" svg={a.icon} />, title: a.name, on: a.id === firstAgent?.id }))) }
: null;
return [windowOf(side, folder, newChat(folder, first, opened, look), look), caption(ready.length ? "Your agents, in the picker under every prompt." : "No agent is ready yet.")];
}
if (step === 2) {
const own = actions.pluginsWorkspace();
const chosen = state.workspaceId ?? own?.id;
const list = [...actions.projects(), ...(own ? [own] : [])];
const opened = {
at: "workspace" as const,
menu: menu(
list.map((w) => ({ key: w.id, mark: folderIcon({ name: w.name, plugins: Boolean(w.mark) }), title: w.name, detail: w.path, on: w.id === chosen })),
"Add workspace folder…",
),
};
return [windowOf(side, folder, newChat(folder, first, opened, look), look), caption("Every new chat asks where to work. Your first one opens here.")];
}
if (step === 3)
return [windowOf(side, folder, newChat(folder, first, null, look), look, true), caption(side ? "Saved changes wait in the sidebar as drafts." : "Switch a plugin off and it leaves the window.")];
return [windowOf(side, folder, newChat(folder, first, null, look), look), caption("This is where you’ll start.")];
}
// The Visuals step: the example's prompt and its reply, drawn as a chat draws it.
function visualReply(actions: Actions) {
const kind = actions.state.visual;
const sample = VISUAL_EXAMPLES[kind];
const on = pluginOn(actions, "visuals");
return (
<div {...column} width="100%" maxWidth={600} gap="large" padding="large">
<div alignSelf="end" maxWidth={420} paddingX={11} paddingY={7} borderRadius="xl" background="bubble" {...RAISED}><text style="body">{sample.prompt}</text></div>
<markdown key={`visual-${kind}`} id={`onboarding-visual-${kind}`} text={sample.reply} />
{on ? null : (
<text style="body" size="xs" tone="muted">
Charts and diagrams are off, so the reply shows their source. Turn them on to see them drawn.
</text>
)}
</div>
);
}
export function renderPreview(actions: Actions): Element {
if (actions.state.step === 4)
return <div {...column} {...fill} borderRadius={17} background="background" {...RAISED} overflow="hidden" alignItems="center" overflowY="scroll" paddingTop={24}>{visualReply(actions)}</div>;
const [drawing, text] = actions.state.step === 0 ? welcome(actions) : stepWindow(actions);
return <div {...column} {...fill} minWidth={0}>{drawing}{text}</div>;
}Versions
| Version | Published | Plugin API | Size | Permissions | Status |
|---|---|---|---|---|---|
| 0.2.8latest | Nov 21, 2026 | >=5 <6 | 68.5 KB | 7 permissions | Listed |
| 0.2.7 | Nov 18, 2026 | >=5 <6 | 68 KB | 7 permissions | Listed |
| 0.2.6 | Nov 16, 2026 | >=5 <6 | 66.3 KB | 7 permissions | Listed |
| 0.2.5 | Nov 11, 2026 | >=5 <6 | 63.6 KB | 7 permissions | Listed |
| 0.2.4 | Nov 9, 2026 | >=5 <6 | 61.6 KB | 7 permissions | Listed |
| 0.2.3 | Oct 27, 2026 | >=2 <4 | 46.8 KB | 7 permissions | Listed |
No comments yet.