Official

sidebar

Built-in sidebar 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/sidebar@0.2.6

Permissions in 0.2.6

  • Control chats chats.controlHighCreates chats, sends prompts and cancels runs.Add and remove workspaces, and create, rename, check off and archive chats
  • Run other plugins' commands commands.runHighRuns commands of other plugins.Open the chat search from the search button, and close the tab on screen with Cmd+W when its chat is part of a task
  • Read chats chats.readMediumReads your transcripts and chat lists.List workspaces and chats, and follow them as agents work
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Draw the sidebar, and its top controls in the title strip after the sidebar toggleSlots: lefttitle

Files

complete-footer.test.ts12.1 KB
// Complete is pinned at the foot of the chat list: its heading and its most
// recently completed chats, in a box that scrolls past five rows, float over
// the list's bottom in the scroller's footer, with Running's chats pinned
// above it. Past fifty chats it says "Show more"; shown whole, Complete's
// chats end the list and scroll with it, Running's above them.
// Its "Show more" or "Show less", or its heading while it is folded, leads the
// sidebar's last row, with Options at that row's end. A completed chat's row shows no workspace or agent mark.
import assert from "node:assert/strict";
import { test } from "node:test";
import type { AppState, Chat, Workspace as AppStateWorkspace } from "divergence";
import type { EffectViewContext } from "divergence/effect";
import type { Sidebar } from "./controller.ts";
import { initialState, noteTask } from "./sections.ts";
import { renderSidebar } from "./views.tsx";

type Node = { type?: string; id?: string; name?: string; background?: string; backdrop?: unknown; onClick?: () => void; children?: Node[]; items?: Node[] };

const findId = (node: Node | null | undefined, id: string): Node | undefined => {
  if (!node) return undefined;
  if (node.id === id) return node;
  for (const child of [...(node.children ?? []), ...(node.items ?? [])]) {
    const found = findId(child, id);
    if (found) return found;
  }
  return undefined;
};

const chat = (id: string, minute: number): Chat => ({
  id,
  workspaceId: "ws",
  agentId: "agent",
  title: id,
  sessionId: "s",
  createdAt: "2026-01-01T00:00:00.000Z",
  updatedAt: `2026-01-02T00:${String(minute).padStart(2, "0")}:00.000Z`,
  archived: false,
  options: {},
  status: "idle",
});

function setup(count = 5) {
  const state = initialState();
  state.loaded = true;
  // Complete unfolded; it starts folded (the test of the default is in dock.test.ts).
  state.collapsed = {};
  const done = Array.from({ length: count }, (_, i) => chat(`done-${i}`, i));
  state.chats = [chat("open-a", 30), chat("open-b", 31), ...done];
  // Completed one minute apart, done-4 last.
  done.forEach((c, i) =>
    noteTask(state, {
      id: c.id,
      layout: { root: { kind: "pane", id: `pane-${c.id}`, tabs: [{ kind: "chat", chatId: c.id }], active: { kind: "chat", chatId: c.id } }, focused: `pane-${c.id}` },
      completedAt: new Date(Date.parse("2026-01-03T00:00:00.000Z") + i * 60_000).toISOString(),
      createdAt: c.createdAt,
      updatedAt: c.updatedAt,
    }),
  );
  const app: AppState = { route: "chat", chatId: "open-a" };
  const ctx = { app, state: {}, plugin: "sidebar", update() {}, run() {} } as unknown as EffectViewContext<{ cmd?: boolean }>;
  const render = () => renderSidebar(ctx, { state, ensurePreview() {} } as unknown as Sidebar["Service"]) as unknown as Node;
  // The sidebar's last row: Complete's Show more or Show less, then Options.
  const lastRow = () => {
    const tree = render();
    const options = findId(tree, "sidebar-options")!;
    const find = (node: Node | null | undefined): Node | undefined => {
      if (!node) return undefined;
      if (node.children?.includes(options)) return node;
      for (const child of node.children ?? []) {
        const found = find(child);
        if (found) return found;
      }
      return undefined;
    };
    const row = find(tree)!;
    return { toggle: row.children![0]!.children?.[0], options: row.children!.at(-1) };
  };
  const list = () => {
    const find = (node: Node | null | undefined): Node | undefined => {
      if (!node) return undefined;
      if (node.type === "scroller") return node;
      for (const child of node.children ?? []) {
        const found = find(child);
        if (found) return found;
      }
      return undefined;
    };
    const scroller = find(render())!;
    const items = scroller.items ?? [];
    const last = items.at(-1);
    const footer = last?.type === "slot" && last.name === "footer" ? last : undefined;
    // The footer holds the room above the pinned rows, then the pinned rows.
    const [lead, pinned] = footer?.children?.[0]?.children ?? [];
    return { items: footer ? items.slice(0, -1) : items, lead, pinned };
  };
  return { state, list, lastRow, render };
}

const ids = (nodes: readonly Node[]) => nodes.map((node) => node.id);
// The pinned headings and rows, with the rows a docked section scrolls in its box in their place.
const pinnedIds = (nodes: readonly Node[]): (string | undefined)[] =>
  nodes.flatMap((node) => (node.id?.startsWith("dock-rows-") || !node.id ? pinnedIds(node.children ?? []) : [node.id]));

// The footer: the column whose last child is the row that holds Options.
function footerOf(tree: Node): Node & { paddingTop?: unknown } {
  const parentOf = (node: Node | undefined, target: Node): Node | undefined =>
    !node ? undefined : node.children?.includes(target) ? node : (node.children ?? []).map((child) => parentOf(child, target)).find(Boolean);
  const row = parentOf(tree, findId(tree, "sidebar-options")!)!;
  return parentOf(tree, row) as Node & { paddingTop?: unknown };
}

test("Complete's heading and its chats, newest first, are pinned at the foot of the list in a box of their own, with Options alone in the last row", () => {
  const { list, lastRow } = setup();
  const { items, lead, pinned } = list();
  assert.ok(pinned, "the scroller has a footer");
  assert.equal(pinned.background, undefined, "no fill, so no box shows over the bare ground");
  assert.deepEqual(pinned.backdrop, { blur: 20, ground: [1, 1] }, "under the pinned rows the rows passing under them are gone into the ground");
  assert.deepEqual(lead?.backdrop, { blur: [0, 8], ground: [0, 1] }, "above the pinned rows they blur and fade into the ground from nothing, so the list meets no hard edge");
  assert.equal(lead?.background, undefined);
  assert.deepEqual(ids(pinned.children!.filter((node) => node.type !== "canvas")), ["heading-settled", "dock-rows-settled"]);
  assert.deepEqual(pinnedIds(pinned.children!), ["heading-settled", "row-done-4", "row-done-3", "row-done-2", "row-done-1", "row-done-0"]);
  const { toggle, options } = lastRow();
  assert.equal(toggle, undefined, "five chats need no Show more");
  assert.equal(options?.id, "sidebar-options");
  assert.ok(!ids(items).some((id) => id === "heading-settled" || id?.startsWith("row-done-")), "Complete is not among the list's items");
  assert.deepEqual(ids(items).filter((id) => id?.startsWith("row-")), ["row-open-b", "row-open-a"]);
});

test("past fifty chats Show more leads the last row; it puts every Complete chat at the end of the list, with Show less in its place, and Show less brings the page back", () => {
  const { state, list, lastRow, render } = setup(52);
  assert.equal(pinnedIds(list().pinned!.children!).length, 51, "the heading and fifty rows");
  const more = lastRow().toggle!;
  assert.equal(more.id, "more-settled");
  assert.equal(footerOf(render()).paddingTop, 0, "Show more follows the rows above as a row follows a row");
  assert.equal((more as { badge?: string }).badge, undefined, "Show more says no count");
  more.onClick!();
  assert.equal(state.showAll.settled, true);
  const { items, pinned } = list();
  assert.deepEqual(ids(items).slice(-53, -50), ["heading-settled", "row-done-51", "row-done-50"]);
  assert.equal(pinned, undefined, "nothing stays pinned over the list");
  const less = lastRow().toggle!;
  assert.equal(less.id, "less-settled");
  assert.equal(footerOf(render()).paddingTop, 0, "and so does Show less");
  less.onClick!();
  assert.equal(state.showAll.settled, false);
  assert.equal(lastRow().toggle?.id, "more-settled");
});

test("a folded Complete's heading takes the last row beside Options, below Running pinned alone, and without completed chats there is no footer and Options stands alone", () => {
  const { state, list, lastRow } = setup();
  state.collapsed.settled = true;
  assert.equal(list().pinned, undefined, "nothing else is docked, so nothing is pinned over the list");
  const heading = lastRow().toggle as Node & { paddingTop?: unknown; alignSelf?: string };
  assert.equal(heading.id, "heading-settled");
  assert.equal(heading.paddingTop, 0, "level with Options, with no room above it");
  assert.equal(heading.alignSelf, undefined, "as wide as its label, count and chevron, like Show more");
  assert.ok(!ids(list().items).includes("heading-settled"));
  state.chats = [{ ...chat("busy", 40), status: "running" }, ...state.chats];
  assert.deepEqual(pinnedIds(list().pinned!.children!), ["heading-running", "row-busy"]);
  assert.equal(lastRow().toggle?.id, "heading-settled");
  state.chats = state.chats.filter((c) => c.id !== "busy");
  state.collapsed.settled = false;
  state.chats = state.chats.filter((c) => c.id.startsWith("open-"));
  assert.equal(list().pinned, undefined);
  assert.equal(lastRow().toggle, undefined);
  assert.equal(lastRow().options?.id, "sidebar-options");
});

test("Running is pinned at the foot of the list above Complete, ends the list above Complete shown whole, and is pinned alone without completed chats", () => {
  const { state, list, lastRow } = setup(52);
  state.chats = [{ ...chat("busy", 59), status: "running" }, ...state.chats];
  assert.deepEqual(pinnedIds(list().pinned!.children!).slice(0, 5), ["heading-running", "row-busy", "heading-settled", "row-done-51", "row-done-50"]);
  assert.ok(!ids(list().items).includes("row-busy"), "Running is not among the list's items");
  lastRow().toggle!.onClick!();
  const { items, pinned } = list();
  assert.equal(pinned, undefined);
  assert.deepEqual(ids(items).filter((id) => !id?.startsWith("gap-")).slice(-55, -50), ["heading-running", "row-busy", "heading-settled", "row-done-51", "row-done-50"]);
  state.chats = state.chats.filter((c) => !c.id.startsWith("done-"));
  assert.deepEqual(pinnedIds(list().pinned!.children!), ["heading-running", "row-busy"]);
  assert.equal(lastRow().toggle, undefined);
});

test("a completed chat's row shows no workspace mark and no hover actions, so its title runs to the row's end; an open one leads with its workspace's mark and shows no agent mark", () => {
  const { state, render } = setup();
  state.workspaces = [{ id: "ws", name: "ws", path: "/ws" } as AppStateWorkspace];
  const marks = (id: string) => {
    const found: string[] = [];
    const walk = (node: Node | null | undefined) => {
      if (!node) return;
      if (node.type === "icon" && node.name !== "circle" && node.name !== "circle-check") found.push(node.name!);
      for (const child of node.children ?? []) walk(child);
    };
    walk(findId(render(), id));
    return found;
  };
  assert.deepEqual(marks("row-done-4"), []);
  assert.equal((findId(render(), "row-done-4") as { actions?: unknown }).actions, undefined, "no actions to keep room for");
  const open = findId(render(), "row-open-a")!;
  assert.ok(((open as { actions?: unknown[] }).actions ?? []).length > 0);
  assert.deepEqual(marks("row-open-a"), ["folder"], "an open chat shows its workspace and not its agent");
  const leading = (open.children ?? []).find((child) => child.type === "slot" && child.name === "leading");
  const glyph = findId(leading, "glyph-open-a");
  assert.ok(glyph, "the workspace's mark is the row's mark, which turns into the check");
  const shown = (node: Node | undefined, name: string): Node | undefined =>
    !node ? undefined : node.type === "icon" && node.name === name ? node : (node.children ?? []).map((child) => shown(child, name)).find(Boolean);
  const circle = (glyph!.children ?? []).find((layer) => shown(layer, "circle"));
  assert.equal((circle?.children?.[0]?.children?.[0] as { groupHover?: { group?: string } } | undefined)?.groupHover?.group, "item", "the status circle takes its place while the pointer is on the row");
  assert.deepEqual((open.children ?? []).filter((child) => child.type !== "slot"), [], "nothing ends the title's line or the live line");
});

test("a folded Complete in the last row keeps the room every section's heading has above it, under a folded Running and under Running's rows alike", () => {
  const { state, render } = setup();
  state.collapsed = { settled: true, running: true };
  state.chats = [{ ...chat("busy", 40), status: "running" }, ...state.chats];
  const footer = () => footerOf(render());
  assert.equal(footer().paddingTop, "0.75rem");
  state.collapsed.running = false;
  assert.equal(footer().paddingTop, "0.75rem");
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.7latestNov 21, 2026>=5 <6100.9 KB4 permissionsListed
0.2.6Nov 16, 2026>=5 <6100.6 KB4 permissionsListed
0.2.5Nov 11, 2026>=5 <665.1 KB4 permissionsListed
0.2.4Nov 9, 2026>=5 <660.4 KB4 permissionsListed
0.2.3Oct 27, 2026>=2 <426.1 KB3 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.