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.6

Permissions in 0.2.6

  • Manage plugins plugins.manageOfficial onlyReloads and enables plugins. Only official plugins can have it.List, enable, disable and reload plugins, install updates, and quit to finish an update
  • Change app settings settings.writeHighChanges the app settings.Change the settings and the theme
  • Manage agents agents.manageHighEnables, disables and signs in agents, and changes their settings.Turn agents on and off, sign in to them and update them
  • Control chats chats.controlHighCreates chats, sends prompts and cancels runs.Add project folders, and open the first chat and the changes saved in the first-run guide
  • Read chats chats.readMediumReads your transcripts and chat lists.Hold an agent's update until its chats stop running
  • Read app settings settings.readLowReads the app settings.Show the settings, and the tools and rules of every plugin
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Draw settings, its list of sections in the sidebar's place, and the first-run guideSlots: centerleft

Files

views/onboarding.tsx19.6 KB
// The first-run guide: the step on the left, the window it changes on the
// right. Each step asks one question, and its explanation sits beside the
// control it explains; nothing here is a page of reading.
// 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 { EffectViewContext } from "divergence/effect";
import { LAST_STEP, OPTIONAL_PLUGINS, STEPS, THEMES, VISUALS } from "../onboarding.ts";
import type { Onboarding, Visual } from "../onboarding.ts";
import type { AgentEntry } from "../controller.ts";
import { fromRegistry } from "./agents.tsx";
import { column, fill, full, row, segmented } from "./layout.tsx";
import { THEME_SWATCHES, VISUAL_EXAMPLES, renderPreview } from "./onboarding-preview.tsx";

type Actions = Onboarding["Service"];
type Ctx = EffectViewContext<object>;
// The shared surface looks from the runtime; an older runtime without them
// gets the same `elevation`, which its kernel already draws.
const RAISED = kit.RAISED ?? { elevation: "raised" };
const FLAT = kit.FLAT ?? { elevation: "none" };

const TITLES = [
  "One window for every coding agent",
  "Choose your agents",
  "Add the folders you work in",
  "Make it yours",
  "Answers can be charts and diagrams",
  "You’re ready",
];
const BODIES = [
  "Divergence runs the coding agents already on this Mac side by side, on your own folders. The window itself is made of plugins, so any part of it can be switched off, swapped, or changed by asking an agent.",
  "Divergence has no model of its own. It drives the agents already on this Mac, each signed in with its own account. Turn on the ones you want in the picker.",
  "Each folder you add is a workspace: its chats, files, Git and terminal stay together. Pick the one your first chat opens in.",
  "Everything in the window is a plugin. Switch one off and it leaves at once, or describe a change and an agent will make it.",
  "Agents can draw what they find right in their reply: a chart from numbers, a diagram of how things connect, a table to compare. Ask for one in plain words.",
];

// A block that rises a little and fades in, `order` steps after the first.
function rise(key: string, order: number, child: Element | null) {
  if (!child) return null;
  return <div key={key} {...column} position="relative" top={10} opacity={0} motion={{ to: { top: 0, opacity: 1 }, duration: 520, delay: order * 70, easing: "spring" }}>{child}</div>;
}

const note = (icon: IconName, text: string) =>
  (
    <div {...row} gap="medium" alignItems="start" paddingX={9}>
      <div paddingTop={2} flexShrink={0}><icon name={icon} small tone="muted" /></div>
      <div {...fill}><text style="body" size="sm" tone="muted">{text}</text></div>
    </div>
  );

const label = (text: string) => <div paddingX={9} paddingBottom={4}><text style="body" size="xs" tone="muted">{text}</text></div>;

// One row of a list of choices: the chosen one is the selected surface, raised.
function choice(id: string, selected: boolean, onClick: (() => void) | undefined, children: Element | readonly (Element | null)[]) {
  return <div id={id} {...row} gap={9} minHeight={36} paddingX={9} paddingY={5} borderRadius="sm" background={selected ? "accent" : undefined} {...selected ? RAISED : FLAT} hover={onClick && !selected ? { background: "hover" } : undefined} onClick={onClick}>{children}</div>;
}

const textPair = (title: string, detail: string | null) =>
  (
    <div {...column} {...fill} gap={1}>
      <text style="body" size="sm" weight={500}>{title}</text>
      {detail ? <text style="body" size="xs" tone="muted">{detail}</text> : null}
    </div>
  );

function welcome() {
  return (
    <div {...column} gap="large">
      {note("puzzle", "Every label on the right is a plugin: a folder of code that draws one part of the window.")}
      {note("shield-check", "Plugins and agents only reach what you allow, and you can see and change all of it.")}
    </div>
  );
}

function agentStatus(ctx: Ctx, actions: Actions, a: AgentEntry) {
  const busy = Boolean(actions.state.pending);
  const status = a.status?.state;
  if (!a.enabled) return null;
  if (status === "ready") {
    const first = actions.state.firstAgent === a.id;
    return (
      <div {...row} gap="small">
        {first
                ? <badge>First chat</badge>
                : <button id={`onboarding-first-${a.id}`} label="Use first" small variant="ghost" onClick={() => ctx.run(actions.set("firstAgent", a.id))} />}
        <text style="body" size="xs" tone="success">Ready</text>
      </div>
    );
  }
  if (status === "starting") return <text style="body" size="xs" tone="muted">Checking…</text>;
  const methods = a.authMethods ?? [];
  if (status === "auth_required" && methods.length)
    return (
      <div {...row} gap="small">
        {methods.map((m) => <button id={`auth-${a.id}-${m.id}`} label={m.name} small disabled={busy} loading={actions.state.pending === `auth:${a.id}`} onClick={() => ctx.run(actions.signIn(a, m))} />)}
      </div>
    );
  return <text style="body" size="xs" tone="faint">Unavailable</text>;
}

function agentRow(ctx: Ctx, actions: Actions, a: AgentEntry) {
  const status = a.status?.state;
  const why = a.enabled && status !== "ready" && a.status && "message" in a.status ? a.status.message : null;
  return (
    <div key={a.id} {...column}>
      {choice(`onboarding-agent-row-${a.id}`, false, undefined, [
            <switch id={`agent-${a.id}`} label="" checked={a.enabled} disabled={Boolean(actions.state.pending)} onChange={(e: { value: boolean }) => ctx.run(actions.setAgentEnabled(a, e.value))} />,
            <icon name="bot" small tone="muted" svg={a.icon} />,
            textPair(a.name, null),
            agentStatus(ctx, actions, a),
          ])}
      {why ? <div paddingLeft={62} paddingRight={9} paddingBottom={6}><text style="body" size="xs" tone="muted">{why}</text></div> : null}
    </div>
  );
}

function agents(ctx: Ctx, actions: Actions) {
  const state = actions.state;
  const direct = state.agents.filter((a) => !fromRegistry(a));
  const registry = state.agents.filter(fromRegistry);
  const shown = state.showRegistry ? registry : registry.filter((a) => a.enabled);
  return (
    <div {...column} gap="large">
      <div {...column} gap={2}>{[...direct, ...shown].map((a) => agentRow(ctx, actions, a))}</div>
      {registry.length
            ? (
              <div {...row}>
                <button id="registry-agents" small variant="ghost" icon={state.showRegistry ? "chevron-down" : "chevron-right"} label={state.showRegistry ? "Show fewer agents" : `${registry.length} more through the agent registry`} onClick={() => ctx.run(actions.set("showRegistry", !state.showRegistry))} />
              </div>
            )
            : null}
      {note("puzzle", "Each agent is connected by a plugin, so new agents arrive the same way everything else does.")}
    </div>
  );
}

// Every workspace in one list, the Divergence one last; the chosen row is
// where the first chat opens.
function projects(ctx: Ctx, actions: Actions) {
  const state = actions.state;
  const busy = Boolean(state.pending);
  const own = actions.pluginsWorkspace();
  const chosen = state.workspaceId ?? own?.id;
  const rows = [...actions.projects(), ...(own ? [own] : [])];
  return (
    <div {...column} gap="large">
      <div {...column} gap={2}>
          {rows.map((w) =>
                  choice(`onboarding-project-${w.id}`, w.id === chosen, busy ? undefined : () => ctx.run(actions.chooseWorkspace(w.id)), [
                    w.mark ? <icon name="divergence" small /> : <icon name="folder" small tone="muted" />,
                    textPair(w.name, w.mark ? "Divergence’s own plugins: chats here change the app" : w.path),
                    w.id === chosen ? <text style="body" size="xs" tone="muted">First chat</text> : null,
                    w.mark
                      ? null
                      : <button id={`onboarding-remove-${w.id}`} icon="x" small variant="ghost" tooltip="Remove from Divergence" disabled={busy} onClick={() => ctx.run(actions.removeWorkspace(w.id))} />,
                  ]))}
          <div {...row} paddingTop={4} marginLeft={1}>
              <button id="onboarding-folder" icon="folder-plus" label="Add a folder…" variant="ghost" loading={state.pending === "folder"} disabled={busy} onClick={() => ctx.run(actions.addWorkspace())} />
            </div>
        </div>
    </div>
  );
}

function pluginSwitches(ctx: Ctx, actions: Actions) {
  const busy = Boolean(actions.state.pending);
  const present = OPTIONAL_PLUGINS.flatMap((o) => {
    const p = actions.state.plugins.find((plugin) => plugin.name === o.name);
    return p ? [{ ...o, enabled: p.enabled }] : [];
  });
  return (
    <div {...column} gap={2}>
      {label("Plugins")}
      {present.map((p) => choice(`onboarding-plugin-row-${p.name}`, false, undefined, [
            textPair(p.title, p.detail),
            <switch id={`onboarding-plugin-${p.name}`} label="" checked={p.enabled} disabled={busy} onChange={(e: { value: boolean }) => ctx.run(actions.setPluginEnabled(p.name, e.value))} />,
          ]))}
    </div>
  );
}

function looks(ctx: Ctx, actions: Actions) {
  const state = actions.state;
  return (
    <div {...column} gap={6}>
      {label("Look")}
      <div display="grid" gridTemplateColumns={4} gap={8} paddingX={9}>
          {THEMES.map((t) => {
                  const s = THEME_SWATCHES[t.id];
                  const on = state.theme === t.id;
                  return (
                    <div key={t.id} id={`onboarding-theme-${t.id}`} {...column} gap={6} onClick={() => ctx.run(actions.setTheme(t.id))}>
                      <div height={34} borderRadius="sm" background={s.bg} overflow="hidden" position="relative" border={{ width: on ? 2 : 0.75, color: on ? "info" : "border" }}>
                                <div position="absolute" left={0} top={0} bottom={0} width={18} background={s.ground} />
                                <div position="absolute" left={26} right={8} top={10} height={6} borderRadius="full" background={s.line} />
                                <div position="absolute" left={26} right={24} top={20} height={4} borderRadius="full" background={s.text} opacity={0.55} />
                              </div>
                      <text style="body" size="xs" tone={on ? undefined : "muted"}>{t.name}</text>
                    </div>
                  );
                })}
        </div>
      <div {...row} paddingX={9} paddingTop={4}>
          {segmented("onboarding-appearance", state.settings?.appearance ?? "system", [
                { value: "system", label: "System" }, { value: "light", label: "Light" }, { value: "dark", label: "Dark" },
              ], (value) => ctx.run(actions.changeAppearance(value)))}
        </div>
    </div>
  );
}

function changes(ctx: Ctx, actions: Actions) {
  const state = actions.state;
  return (
    <div {...column} gap={6}>
      {label("Change it by asking")}
      <div {...row} gap="small" paddingX={9}>
          <div {...fill}>
              <input id="onboarding-change" value={state.change} placeholder="Describe a change, like a word count under the prompt" onChange={(e: { value: string }) => ctx.run(actions.set("change", e.value))} onSubmit={() => ctx.run(actions.saveChange())} />
            </div>
          <button id="onboarding-save-change" label="Save for later" disabled={!state.change.trim()} onClick={() => ctx.run(actions.saveChange())} />
        </div>
      {state.saved.map((text, i) => choice(`onboarding-saved-${i}`, false, undefined, [
            <icon name="play" small tone="muted" />,
            textPair(text, `Waiting in ${actions.pluginsWorkspace()?.name ?? "Divergence"} for you to send it`),
            <button id={`onboarding-unsave-${i}`} icon="x" small variant="ghost" tooltip="Remove" onClick={() => ctx.run(actions.removeChange(text))} />,
          ]))}
    </div>
  );
}

function yourApp(ctx: Ctx, actions: Actions) {
  return <div {...column} gap="large">{pluginSwitches(ctx, actions)}{looks(ctx, actions)}{changes(ctx, actions)}</div>;
}

function visuals(ctx: Ctx, actions: Actions) {
  const state = actions.state;
  const plugin = state.plugins.find((p) => p.name === "visuals");
  return (
    <div {...column} gap="large">
      <div {...column} gap={2}>
          {VISUALS.map((kind: Visual) =>
                choice(`onboarding-visual-${kind}`, state.visual === kind, () => ctx.run(actions.set("visual", kind)),
                  textPair(VISUAL_EXAMPLES[kind].title, `“${VISUAL_EXAMPLES[kind].prompt}”`)))}
        </div>
      {plugin
            ? choice("onboarding-plugin-row-visuals", false, undefined, [
                textPair("Charts and diagrams in replies", "The visuals plugin draws them, and gives agents a tool to build whole pages"),
                <switch id="onboarding-plugin-visuals" label="" checked={plugin.enabled} disabled={Boolean(state.pending)} onChange={(e: { value: boolean }) => ctx.run(actions.setPluginEnabled("visuals", e.value))} />,
              ])
            : null}
    </div>
  );
}

function summary(ctx: Ctx, actions: Actions) {
  const state = actions.state;
  const ready = actions.readyAgents();
  const off = OPTIONAL_PLUGINS.filter((o) => state.plugins.some((p) => p.name === o.name && !p.enabled)).map((o) => o.title);
  const theme = THEMES.find((t) => t.id === state.theme)?.name ?? "Divergence";
  const own = actions.pluginsWorkspace()?.name ?? "Divergence";
  const changes = `${state.saved.length} ${state.saved.length === 1 ? "change" : "changes"}`;
  const extras = !state.saved.length
    ? null
    : ready.length
      ? `${changes} waiting in ${own}`
      : `${changes} kept until an agent is ready`;
  const line = (key: string, title: string, value: string, detail: string | null, step: number) =>
    (
      <div key={key} {...row} alignItems="start" gap="large" paddingX={9} paddingY={9}>
        <div width={90} flexShrink={0}><text style="body" size="sm" tone="muted">{title}</text></div>
        {textPair(value, detail)}
        <button id={`onboarding-change-${key}`} label="Change" small variant="ghost" onClick={() => ctx.run(actions.move(step))} />
      </div>
    );
  return (
    <card divided>
      {line("agents", "Agents", ready.length ? ready.map((a) => a.name).join(", ") : "None ready yet",
            ready.length ? `${ready.find((a) => a.id === state.firstAgent)?.name ?? ready[0]?.name} starts the first chat` : "Finish one under Agents, or later in Settings", 1)}
      {line("projects", "Workspaces", [...actions.projects().map((w) => w.name), own].join(", "),
            "Earlier chats come in as they are found", 2)}
      {line("app", "Your app", `${theme}${off.length ? `, without ${off.join(", ")}` : ", every plugin on"}`, extras, 3)}
    </card>
  );
}

function stepBody(ctx: Ctx, actions: Actions) {
  const step = actions.state.step;
  if (!actions.state.ready) return <text style="body" tone="muted">Loading your setup…</text>;
  if (step === 0) return welcome();
  if (step === 1) return agents(ctx, actions);
  if (step === 2) return projects(ctx, actions);
  if (step === 3) return yourApp(ctx, actions);
  if (step === 4) return visuals(ctx, actions);
  return summary(ctx, actions);
}

function firstChatLine(actions: Actions) {
  const state = actions.state;
  const agent = actions.readyAgents().find((a) => a.id === state.firstAgent);
  const workspace = state.workspaces.find((w) => w.id === state.workspaceId) ?? actions.pluginsWorkspace();
  if (!agent || !workspace) return "Get an agent ready under Agents to start chatting. You can also do it later in Settings.";
  return `Your first chat opens in ${workspace.name} with ${agent.name}.`;
}

function nextLabel(actions: Actions) {
  const step = actions.state.step;
  if (step === 0) return "Set up Divergence";
  if (step === 1 && !actions.readyAgents().length) return "Continue without an agent";
  if (step < LAST_STEP) return "Continue";
  const workspace = actions.state.workspaces.find((w) => w.id === actions.state.workspaceId) ?? actions.pluginsWorkspace();
  if (!actions.readyAgents().length || !workspace) return "Open Divergence";
  return `Start in ${workspace.name}`;
}

function stepBar(ctx: Ctx, actions: Actions) {
  const step = actions.state.step;
  const busy = Boolean(actions.state.pending);
  return (
    <div {...row} gap={0} marginLeft={-7}>
      {STEPS.map((name, i) => {
            const now = i === step;
            const reachable = !busy && i < step;
            return (
              <div key={`step-${i}`} id={`onboarding-step-${i}`} {...row} height={26} paddingX={7} borderRadius="sm" background={now ? "accent" : undefined} {...now ? RAISED : FLAT} hover={reachable ? { background: "hover" } : undefined} onClick={reachable ? () => ctx.run(actions.move(i)) : undefined}>
                <text style="body" size="sm" tone={now ? undefined : i < step ? "muted" : "faint"}>{name}</text>
              </div>
            );
          })}
    </div>
  );
}

function footer(ctx: Ctx, actions: Actions) {
  const state = actions.state;
  const step = state.step;
  const busy = Boolean(state.pending);
  return (
    <div {...row} gap="medium" paddingTop="large">
      {step > 0 ? <button id="onboarding-back" label="Back" icon="arrow-left" variant="ghost" disabled={busy} onClick={() => ctx.run(actions.move(step - 1))} /> : null}
      {step === 0 ? <button id="onboarding-skip" label="Skip and use the defaults" variant="ghost" disabled={busy || !state.ready} onClick={() => ctx.run(actions.finish())} /> : null}
      <spacer />
      <button id="onboarding-next" label={nextLabel(actions)} icon={step === LAST_STEP ? undefined : "arrow-right"} variant="primary" loading={state.pending === "finish"} disabled={busy || !state.ready} onClick={() => ctx.run(step === LAST_STEP ? actions.finish() : actions.move(step + 1))} />
    </div>
  );
}

export function renderOnboarding(ctx: Ctx, actions: Actions): Element | null {
  const state = actions.state;
  if (ctx.app.route !== "onboarding") {
    state.active = false;
    return null;
  }
  if (!state.active) ctx.run(actions.enter());
  const step = state.step;
  const body = step === LAST_STEP ? firstChatLine(actions) : BODIES[step];
  const page = (
    <div {...row} {...full} alignItems="stretch">
      <div {...column} width={500} flexShrink={0} paddingX={44} paddingTop={28} paddingBottom={24}>
          {stepBar(ctx, actions)}
          <div {...column} {...fill} overflowY="scroll" paddingTop={30} gap={20}>
              <div key={`step-${step}`} {...column} gap={20}>
                  {rise("head", 0, (
                              <div {...column} gap="medium">
                                <div fontFamily="Bricolage Grotesque" fontSize={27} lineHeight={34} fontWeight={500}><text>{TITLES[step]}</text></div>
                                <text style="body" tone="muted">{body}</text>
                              </div>
                            ))}
                  {rise("error", 1, state.error ? (
                              <callout tone="danger" title="Something needs attention" text={state.error}>
                                <button id="onboarding-retry" label={state.ready ? "Refresh status" : "Try again"} disabled={Boolean(state.pending)} onClick={() => ctx.run(actions.retry())} />
                              </callout>
                            ) : null)}
                  {rise(state.ready ? "body" : "loading", 2, stepBody(ctx, actions))}
                </div>
            </div>
          {footer(ctx, actions)}
        </div>
      <div {...column} {...fill} padding={18} paddingLeft={0}>{renderPreview(actions)}</div>
    </div>
  );
  // `width` and `top` only shape the card an older kernel draws without `cover`.
  return <overlay id="onboarding" open cover width={880} top={0.06}>{page}</overlay>;
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.8latestNov 21, 2026>=5 <668.5 KB7 permissionsListed
0.2.7Nov 18, 2026>=5 <668 KB7 permissionsListed
0.2.6Nov 16, 2026>=5 <666.3 KB7 permissionsListed
0.2.5Nov 11, 2026>=5 <663.6 KB7 permissionsListed
0.2.4Nov 9, 2026>=5 <661.6 KB7 permissionsListed
0.2.3Oct 27, 2026>=2 <446.8 KB7 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.