Official

terminal

Built-in integrated terminal (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/terminal@0.2.5

Permissions in 0.2.5

Take care. This plugin asks for permissions that can do anything your account can. The app asks you to hold Enable for two seconds or to type the plugin's name before it turns on.
  • Terminals terminalDangerousCreates and controls terminals, which run a shell.Run shells in the integrated terminal
  • Read chats chats.readMediumReads your transcripts and chat lists.Start shells in the current workspace
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Show the terminal button and its windowSlots: railright

Files

view.ts11.7 KB
// Terminal trees preserve the rail, fly-out, tab menus and session grid from the JavaScript UI.
// Typed factories keep formatting from introducing HTM whitespace nodes; handlers use scoped effects.
import { h } from "divergence";
import * as kit from "divergence";
import type { DivProps, SpacingStep, Terminal } from "divergence";
import * as Effect from "effect/Effect";
import { Views } from "divergence/effect";
import type { EffectViewContext } from "divergence/effect";
import type { Controller } from "./controller.ts";
import { activeTerminal, forWorkspace, terminalInPane } from "./state.ts";

// The shared surface looks from the runtime; an older runtime without them
// gets the same `elevation`, which its kernel already draws.
const FLAT = kit.FLAT ?? { elevation: "none" } satisfies DivProps;

// A tab as a pane's strip draws it (the chat plugin's `views/layout.tsx`): 30px tall and 200px
// wide (more than fit scroll the strip). What is drawn sits 8px from both ends and 8px from the
// next part: the 18px mark box holds a 16px icon with a pixel to spare each side, and the 16px
// close mark box draws its X 3.5px in, so the close box is pulled 2.5px towards the title. The
// selected one is the top of the surface below, reaching 1px over its edge with reverse curves of
// 8px at its foot. The row of tabs starts 18px in from the surface's side.
const TAB_SPACE = 8;
const TAB_HEIGHT = 30;
const TAB_WIDTH = 200;
const TAB_MARK = 18;
const TAB_CLOSE = 16;
const MARK_ROOM = (TAB_MARK - 16) / 2;
const CLOSE_ROOM = 3.5;
const TAB_INSET = TAB_SPACE - MARK_ROOM;
const TAB_GAP = TAB_SPACE - MARK_ROOM;
const TAB_CLOSE_END = TAB_SPACE - CLOSE_ROOM;
const TAB_CLOSE_PULL = TAB_SPACE - CLOSE_ROOM - TAB_GAP;
const TAB_JOIN = 1;
const FLARE = 8;
const STRIP_INSET = 18;
// The room above the tabs; the terminal's surface reaches the fly-out's sides and bottom, with no
// ring of the fly-out's glass around it.
const ROOM = 8;
const EDGED = kit.EDGED ?? { elevation: "edge" };
const column = { display: "flex", flexDirection: "column" } satisfies DivProps;
const row = { display: "flex", flexDirection: "row", alignItems: "center" } satisfies DivProps;
const fill = { flexGrow: 1, flexShrink: 1, flexBasis: "0%", minWidth: 0, minHeight: 0 } satisfies DivProps;
const full = { width: "100%", height: "100%" } satisfies DivProps;
const HOVER = { background: "hover" } satisfies DivProps;
const clickable = { group: "hover" } satisfies DivProps;
// A terminal's tab is dragged as the tabs plugin's terminal item, keyed as that plugin keys it.
const ITEM_DRAG = "divergence/item";
const terminalKey = (terminal: Terminal) => `terminal:${terminal.workspaceId}:${terminal.id}`;
const terminalOfKey = (key: string | undefined) => (key?.startsWith("terminal:") ? key.split(":").slice(2).join(":") : null);
const keep = { flexGrow: 0, flexShrink: 0, flexBasis: "auto" } satisfies DivProps;

function centered(padding: SpacingStep, text: string) {
  return h(
    "div",
    { ...column, ...fill, ...full, marginX: "auto", gap: "small", padding },
    h("text", { style: "muted" }, text),
  );
}

export function renderRail(controller: Controller, ctx: EffectViewContext<object>) {
  if (!controller.state.ready) return null;
  const running = forWorkspace(controller.state.terminals, ctx.app.workspaceId).filter(
    (terminal) => terminal.running,
  ).length;
  return h("button", {
    id: "rail-terminal",
    icon: "square-terminal",
    variant: "ghost",
    active: Boolean(terminalInPane(controller.state.activeTab)),
    badge: running > 1 ? String(running) : undefined,
    tooltip: "Terminal",
    onClick: () => {},
  });
}

/** One terminal's tab in the fly-out's strip, with its menu. */
function renderTab(controller: Controller, ctx: EffectViewContext<object>, terminal: Terminal, active: boolean) {
  const { state, update } = controller;
  if (state.renaming === terminal.id)
    return h(
      "div",
      { ...row, paddingX: TAB_INSET, height: TAB_HEIGHT, background: "muted", borderRadius: "sm", width: TAB_WIDTH, flexShrink: 0 },
      h("input", {
        id: `terminal-rename-${terminal.id}`,
        value: terminal.title,
        ghost: true,
        submitOnEnter: true,
        keys: ["escape"],
        onKey: (event) => {
          if (event.key !== "escape") return;
          state.renaming = null;
          update();
        },
        onSubmit: (event) => ctx.run(controller.rename(terminal, event.value)),
      }),
    );
  const tone = terminal.running ? (active ? "foreground" : "muted") : "danger";
  const close = h(
    "div",
    {
      ...row,
      ...clickable,
      id: `terminal-close-${terminal.id}`,
      justifyContent: "center",
      width: TAB_CLOSE,
      height: TAB_CLOSE,
      flexShrink: 0,
      borderRadius: 4,
      hover: HOVER,
      stopPropagation: true,
      tooltip: "Close terminal",
      onClick: () => ctx.run(controller.close(terminal)),
    },
    h("icon", { name: "x", tone: active ? "foreground" : "muted" }),
  );
  const menu = state.menu?.id === terminal.id ? state.menu : null;
  return h(
      "div",
      {
        ...row,
        ...clickable,
        cursor: "pointer",
        id: `terminal-tab-${terminal.id}`,
        position: "relative",
        gap: TAB_GAP,
        paddingLeft: TAB_INSET,
        paddingRight: TAB_CLOSE_END,
        height: active ? TAB_HEIGHT + TAB_JOIN : TAB_HEIGHT,
        paddingBottom: active ? TAB_JOIN : 0,
        width: TAB_WIDTH,
        flexShrink: 0,
        borderRadius: "sm",
        hover: active ? undefined : HOVER,
        ...FLAT,
        // Dragged as a tab: onto the panes it opens there, or splits one at an edge, as a
        // chat's tab does; along this strip it moves among the terminals.
        drag: { type: ITEM_DRAG, data: { kind: "tabs.terminal", key: terminalKey(terminal) }, label: terminal.title },
        drop: {
          types: [ITEM_DRAG],
          reorder: "horizontal",
          onDrop: (event) => {
            const id = "data" in event ? terminalOfKey((event.data as { key?: string } | null)?.key) : null;
            if (id) ctx.run(controller.move(id, terminal.id, event.zone));
          },
        },
        onClick: () => {
          state.activeByWorkspace[String(terminal.workspaceId)] = terminal.id;
          // A click on another tab leaves a rename unfinished, as Escape does.
          state.renaming = null;
          update();
        },
        // The menu opens where the tab was right-clicked, as a press on the list's trigger does.
        onSecondaryClick: (event) => {
          state.menu = { id: terminal.id, at: { x: event.x, y: event.y } };
          update();
          ctx.run(Effect.flatMap(Views, (views) => views.focus("terminal-menu")));
        },
      },
      h("div", { ...row, justifyContent: "center", width: TAB_MARK, height: TAB_MARK, flexShrink: 0 }, h("icon", { name: "square-terminal", tone })),
      h("div", { ...row, flexGrow: 1, minWidth: 0 }, h("text", { style: "body", size: "sm", weight: 500, tone, truncate: true }, terminal.title)),
      h("div", { ...row, marginLeft: TAB_CLOSE_PULL, ...(active ? null : { visibility: "hidden", groupHover: { group: "hover", visibility: "visible" } }) }, close),
      menu ? tabMenu(controller, ctx, terminal, menu.at) : null,
  );
}

// The tab's menu: the kernel's list with icons, as in the + menu of the chat's tabs, opened
// where the tab was right-clicked from a trigger with no height, which the list's corner sits on.
const MENU = [
  { value: "rename", icon: "pencil", label: "Rename Terminal" },
  { value: "popout", icon: "maximize", label: "Open in a Tab" },
  { value: "close", icon: "x", label: "Close Terminal" },
] as const;
function tabMenu(controller: Controller, ctx: EffectViewContext<object>, terminal: Terminal, at: { x: number; y: number }) {
  const run = { rename: controller.startRename, popout: controller.popOut, close: controller.close } as const;
  return h(
    "div",
    { position: "absolute", left: at.x, top: at.y },
    h(
      "combobox",
      {
        id: "terminal-menu",
        value: "",
        width: 240,
        options: MENU.map((entry) => ({ ...entry })),
        onChange: (event: { value?: string }) => {
          controller.state.menu = null;
          const action = run[event.value as keyof typeof run];
          if (action) ctx.run(action(terminal));
        },
      },
      h("div", { width: 1, height: 0 }),
    ),
  );
}
export function renderFlyOut(controller: Controller, ctx: EffectViewContext<object>) {
  const { state, update } = controller;
  if (!state.ready || ctx.app.shared?.rightPanelPreview !== "terminal") return null;
  const workspaceId = ctx.app.workspaceId;
  if (!workspaceId) return centered("medium", "Open a workspace to use the terminal.");
  const mine = forWorkspace(state.terminals, workspaceId);
  const active = activeTerminal(state, workspaceId);
  const failed = state.failed[workspaceId];
  if (!active && failed !== undefined)
    return h(
      "div",
      { ...column, ...fill, ...full, marginX: "auto", gap: "small", padding: "medium" },
      h("text", { style: "muted" }, `Cannot open a terminal: ${failed}`),
      h("div", { ...row }, h("button", { id: "terminal-retry", label: "Try again", onClick: () => ctx.run(controller.create(workspaceId)) })),
    );
  if (!active) return centered("medium", "Starting…");

  // The terminal's surface, with the strip above it: laid out above but painted after it, so the
  // selected tab covers the surface's edge where they meet, as a pane's does.
  const surface =
    terminalInPane(state.activeTab) === active.id
      ? h("div", { ...column, ...fill, ...full, background: "background", ...EDGED, borderRadius: "md" }, centered("large", "This terminal is open in a tab."))
      : h(
          "div",
          { ...column, ...fill, ...full, padding: "small", background: "background", ...EDGED, borderRadius: "md" },
          h("terminal", { terminal: active.id }),
        );
  const strip = h(
    "div",
    { ...row, alignItems: "start", gap: 4, height: TAB_HEIGHT, flexShrink: 0, paddingLeft: STRIP_INSET, paddingRight: 4 },
    h(
      "div",
      {
        ...row,
        ...fill,
        id: "terminal-tabs",
        alignItems: "start",
        height: TAB_HEIGHT + TAB_JOIN,
        marginBottom: -TAB_JOIN,
        paddingLeft: FLARE,
        gap: "small",
        overflowX: "scroll",
        reveal: Math.max(
          0,
          mine.findIndex((terminal) => terminal.id === active.id),
        ),
      },
      // The selected tab's surface: one, under the tabs, moving at once to the tab the user picks.
      h("div", {
        id: "terminal-tab-surface",
        follows: `terminal-tab-${active.id}`,
        width: "100%",
        height: "100%",
        tabShape: { radius: 8, flare: FLARE, join: TAB_JOIN },
      }),
      mine.map((terminal) => h("div", { key: terminal.id, ...row, minWidth: 0, flexShrink: 1 }, renderTab(controller, ctx, terminal, terminal.id === active.id))),
      h(
        "div",
        { key: "new", ...row, height: TAB_HEIGHT, ...keep },
        h("button", {
          id: "terminal-new",
          icon: "plus-large",
          variant: "ghost",
          tooltip: "New terminal (⌘J)",
          onClick: () => ctx.run(controller.create(active.workspaceId)),
        }),
      ),
    ),
    h(
      "div",
      { ...row, height: TAB_HEIGHT, gap: 4, ...keep },
      !active.running ? h("text", { style: "body", size: "xs", tone: "muted" }, active.exitCode === null ? "exited" : `exited ${active.exitCode}`) : null,
      h("button", {
        id: "terminal-popout",
        icon: "maximize",
        variant: "ghost",
        tooltip: "Open in a tab",
        onClick: () => ctx.run(controller.popOut(active)),
      }),
    ),
  );
  return h("div", { ...column, ...fill, ...full, paddingTop: ROOM, flexDirection: "column-reverse" }, surface, strip);
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=5 <612.9 KB3 permissionsListed
0.2.4Nov 16, 2026>=5 <612.6 KB3 permissionsListed
0.2.3Nov 11, 2026>=5 <612.4 KB3 permissionsListed
0.2.2Nov 9, 2026>=5 <611.5 KB3 permissionsListed
0.2.1Oct 27, 2026>=2 <49.5 KB3 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.