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

Permissions in 0.2.7

  • 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

items.test.ts11.4 KB
// Rows and buttons other plugins put in the sidebar: each publishes a view id
// in the shared app state, under `sidebarItem.<plugin>` for a row of the
// footer, `sidebarButton.<plugin>` for a button left of Options (the update
// button) or `sidebarMenu.<plugin>` for a row of the Options menu, which the
// sidebar draws above Settings (the market's account and Marketplace rows), and
// `sidebarPicture` for the picture in Options' circle.
import assert from "node:assert/strict";
import { test } from "node:test";
import type { AppState } from "divergence";
import type { EffectViewContext } from "divergence/effect";
import type { Sidebar } from "./controller.ts";
import { initialState, listedChats, noteTask } from "./sections.ts";
import { renderSidebar, sidebarItems } from "./views.tsx";

test("published sidebar items are view ids in the order of their keys; cleared ones go", () => {
  assert.deepEqual(sidebarItems(undefined), []);
  assert.deepEqual(
    sidebarItems({
      rightPanel: "files",
      "sidebarItem.zeta": 9,
      "sidebarItem.market": 4,
      "sidebarItem.gone": null,
      "sidebarMenu.market": 5,
      openTab: { nonce: 1 },
    }),
    [4, 9],
  );
  assert.deepEqual(sidebarItems({ "sidebarItem.updates": 4, "sidebarMenu.market": 5 }, "sidebarMenu."), [5]);
});

test("footer items sit above the last row, buttons left of Options, and menu items open from Options above Settings until the route changes", () => {
  const state = initialState();
  state.loaded = true;
  let app: AppState = { route: "chat", shared: { "sidebarItem.other": 8, "sidebarButton.updates": 9, "sidebarMenu.market": 7 } };
  const ctx = {
    get app() {
      return app;
    },
    state: {},
    plugin: "sidebar",
    update() {},
    run() {},
  } as unknown as EffectViewContext<{
    cmd?: boolean;
  }>;
  type Node = { type?: string; id?: string; view?: number; width?: number; open?: boolean; onClick?: () => void; items?: { id: string }[]; children?: Node[] };
  const render = () => renderSidebar(ctx, { state } as unknown as Sidebar["Service"]) as unknown as Node;
  const find = (node: Node | null | undefined, id: string): Node | undefined => {
    if (!node) return undefined;
    if (node.id === id) return node;
    for (const child of node.children ?? []) {
      const found = find(child, id);
      if (found) return found;
    }
    return undefined;
  };
  const order: string[] = [];
  const walk = (node: Node | null | undefined, menu: boolean) => {
    if (!node) return;
    if (node.type === "view") {
      // As tall as its row: a view that fills its place collapses to
      // nothing in the footer.
      assert.equal((node as { fit?: boolean }).fit, true);
      order.push(`${menu ? "menu" : "footer"}:${node.view}`);
    }
    if (node.items?.some((item) => item.id === "sidebar-settings")) order.push(menu ? "menu:settings" : "settings");
    for (const child of node.children ?? []) walk(child, menu || node.id === "sidebar-options");
  };
  walk(render(), false);
  assert.deepEqual(order, ["footer:8", "footer:9", "menu:7", "menu:settings"]);
  // The button stands in a square as big as Options, just before it in the last row.
  const parentOf = (node: Node | null | undefined, id: string): Node | undefined =>
    !node ? undefined : node.children?.some((child) => child.id === id) ? node : (node.children ?? []).map((child) => parentOf(child, id)).find(Boolean);
  const last = parentOf(render(), "sidebar-options")!.children!;
  const options = last.findIndex((child) => child.id === "sidebar-options");
  assert.equal(last[options - 1]?.width, 22);
  assert.equal(last[options - 1]?.children?.[0]?.view, 9);

  assert.equal(find(render(), "sidebar-options")?.open, false);
  find(render(), "sidebar-options-button")!.onClick!();
  assert.equal(find(render(), "sidebar-options")?.open, true);
  // A row of the menu opens its page, and the menu is closed when the chat comes back.
  app = { ...app, route: "market" };
  assert.equal(find(render(), "sidebar-options")?.open, false);
  app = { ...app, route: "chat" };
  assert.equal(find(render(), "sidebar-options")?.open, false);
});

test("Options shows the picture a plugin publishes in place of its person mark, and the mark again once it is cleared", () => {
  const state = initialState();
  state.loaded = true;
  let app: AppState = { route: "chat", shared: { sidebarPicture: 5 } };
  const ctx = {
    get app() {
      return app;
    },
    state: {},
    plugin: "sidebar",
    update() {},
    run() {},
  } as unknown as EffectViewContext<{ cmd?: boolean }>;
  type Node = { type?: string; id?: string; view?: number; name?: string; children?: Node[] };
  const button = () => {
    const find = (node: Node | null | undefined): Node | undefined =>
      !node ? undefined : node.id === "sidebar-options-button" ? node : (node.children ?? []).map(find).find(Boolean);
    return find(renderSidebar(ctx, { state } as unknown as Sidebar["Service"]) as unknown as Node)!;
  };
  const inside = (node: Node, out: Node[] = []): Node[] => {
    for (const child of node.children ?? []) {
      out.push(child);
      inside(child, out);
    }
    return out;
  };
  const marks = () => inside(button()).filter((node) => node.type === "view" || node.type === "icon");
  assert.deepEqual(marks().map((node) => node.view ?? node.name), [5]);
  app = { route: "chat", shared: { sidebarPicture: null } };
  assert.deepEqual(marks().map((node) => node.view ?? node.name), ["user-round", "user-round"]);
});

test("the sidebar steps aside while Settings, which draws its own, is open", () => {
  const state = initialState();
  state.loaded = true;
  const ctx = { app: { route: "settings" }, state: {}, plugin: "sidebar", update() {}, run() {} } as unknown as EffectViewContext<{
    cmd?: boolean;
  }>;
  assert.equal(renderSidebar(ctx, { state } as unknown as Sidebar["Service"]), null);
});

// "Show more" on Complete used to put hundreds of rows in a scrolling
// column that laid out and drew every one of them in each frame of a
// scroll. The chats are one flat list of rows in a scroller that draws
// only the rows on screen, with selection belonging to the selected row.
test("the chats are rows of a list that opens at its start, even after Show more", () => {
  const state = initialState();
  state.loaded = true;
  state.collapsed = {};
  state.chats = Array.from({ length: 300 }, (_, i) => ({
    id: `c${i}`,
    workspaceId: "ws",
    agentId: "agent",
    title: `Chat ${i}`,
    createdAt: "2026-01-01T00:00:00.000Z",
    updatedAt: "2026-01-02T00:00:00.000Z",
    archived: false,
    options: {},
    status: "idle",
  }));
  // Every one checked off: its task's, as the host keeps them.
  for (const chat of state.chats)
    noteTask(state, {
      id: chat.id,
      layout: {
        root: { kind: "pane", id: `pane-${chat.id}`, tabs: [{ kind: "chat", chatId: chat.id }], active: { kind: "chat", chatId: chat.id } },
        focused: `pane-${chat.id}`,
      },
      completedAt: "2026-01-03T00:00:00.000Z",
      createdAt: chat.createdAt,
      updatedAt: chat.updatedAt,
    });
  state.showAll.settled = true;
  const app: AppState = { route: "chat", chatId: "c7" };
  const ctx = { app, state: {}, plugin: "sidebar", update() {}, run() {} } as unknown as EffectViewContext<{
    cmd?: boolean;
  }>;
  type Node = { type?: string; id?: string; name?: string; selected?: boolean; follows?: string; followEnd?: boolean; children?: Node[]; items?: Node[] };
  const find = (node: Node | null | undefined, type: string): Node | undefined => {
    if (!node) return undefined;
    if (node.type === type) return node;
    for (const child of node.children ?? []) {
      const found = find(child, type);
      if (found) return found;
    }
    return undefined;
  };
  const list = find(renderSidebar(ctx, { state } as unknown as Sidebar["Service"]) as unknown as Node, "scroller");
  assert.equal(list?.followEnd, false);
  const items = list?.items ?? [];
  assert.equal(items[0]?.id, "chat-selection", "the open chat's fill leads the rows");
  assert.equal(items[0]?.follows, "row-c7", "under the open chat's row");
  assert.equal(items[1]?.id, "heading-settled");
  assert.equal(items.find((item) => item.id === "row-c7")?.selected, true, "the open chat's label is drawn selected");
  assert.ok(items.filter((item) => item.id?.startsWith("row-")).every((item) => (item as { lift?: boolean }).lift === true), "every chat row is lifted, so the open one is raised");
  assert.equal(items.filter((item) => item.id?.startsWith("row-")).length, 300, "every chat is a row of its own");
  // Shown whole, Complete's rows end the list, nothing stays pinned at its
  // foot, and "Show less" leads the sidebar's last row.
  assert.equal(items.at(-1)?.id, "row-c299");

  noteTask(state, {
    id: "c7",
    layout: {
      root: { kind: "pane", id: "pane-c7", tabs: [{ kind: "chat", chatId: "c7" }, { kind: "chat", chatId: "c8" }], active: { kind: "chat", chatId: "c8" } },
      focused: "pane-c7",
    },
    completedAt: "2026-01-03T00:00:00.000Z",
    createdAt: "2026-01-01T00:00:00.000Z",
    updatedAt: "2026-01-02T00:00:00.000Z",
  });
  const taskCtx = { ...ctx, app: { ...app, chatId: "c8" } } as EffectViewContext<{ cmd?: boolean }>;
  const taskItems = find(renderSidebar(taskCtx, { state } as unknown as Sidebar["Service"]) as unknown as Node, "scroller")?.items ?? [];
  assert.equal(taskItems.find((item) => item.id === "row-c7")?.selected, false);
  assert.equal(taskItems.find((item) => item.id === "child-c8")?.selected, true, "an open task selects its active child");
});

// Holding Cmd shows, in place of each of the first nine rows' agent, the
// number that opens it with Cmd: the same rows, in the same order, that
// Cmd+1 to Cmd+9 open.
test("while Cmd is held the first nine rows show the number Cmd opens them with", () => {
  const state = initialState();
  state.loaded = true;
  state.chats = Array.from({ length: 12 }, (_, i) => ({
    id: `c${i}`,
    workspaceId: "ws",
    agentId: "agent",
    title: `Chat ${i}`,
    sessionId: "s",
    createdAt: "2026-01-01T00:00:00.000Z",
    updatedAt: `2026-01-02T00:00:${String(i).padStart(2, "0")}.000Z`,
    completedAt: i % 3 ? undefined : "2026-01-03T00:00:00.000Z",
    archived: false,
    options: {},
    status: "idle",
  }));
  type Node = { type?: string; id?: string; text?: string; children?: Node[]; items?: Node[] };
  const numbers = (cmd: boolean): Record<string, string> => {
    const ctx = {
      app: { route: "chat" },
      state: { cmd },
      plugin: "sidebar",
      update() {},
      run() {},
    } as unknown as EffectViewContext<{
      cmd?: boolean;
    }>;
    const found: Record<string, string> = {};
    const walk = (node: Node | null | undefined, row?: string) => {
      if (!node) return;
      const id = node.id?.startsWith("row-") ? node.id.slice(4) : row;
      const text = String(node.text ?? node.children?.[0] ?? "");
      if (node.type === "text" && id && /^[1-9]$/.test(text)) found[id] = text;
      for (const child of [...(node.children ?? []), ...(node.items ?? [])]) walk(child, id);
    };
    walk(renderSidebar(ctx, { state, ensurePreview() {} } as unknown as Sidebar["Service"]) as unknown as Node);
    return found;
  };
  assert.deepEqual(numbers(false), {});
  const expected = Object.fromEntries(
    listedChats(state)
      .filter((_, i, chats) => i < 8 || (i === chats.length - 1 && i >= 8))
      .map((chat, i) => [chat.id, String(i + 1)]),
  );
  assert.equal(Object.keys(expected).length, 9);
  assert.deepEqual(numbers(true), expected);
});

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.