gloomberb 0.13.2 → 0.14.0

package/src/plugins/builtin/cloud/team/command.ts

@@ -0,0 +1,313 @@
+import { apiClient } from "../../../../api-client";
+import type { CommandResultDef, GloomPluginContext } from "../../../../types/plugin";
+import { requestAuthDialog } from "../auth-dialog";
+import {
+  canInviteToTeam,
+  canManageTeam,
+  describeTeam,
+  findTeam,
+  teamChannelId,
+  teamLabel,
+  userHandle,
+} from "./model";
+import { openTeamPane, type TeamPaneSection } from "./pane-request";
+import { teamStore } from "./store";
+
+const TEAM_SUBCOMMAND = /^(invite|new|settings|members|channels|leave|focus|chat)\b\s*(.*)$/i;
+
+function requireSignIn(ctx: GloomPluginContext): boolean {
+  if (apiClient.isVerified()) return true;
+  const opened = requestAuthDialog({ mode: apiClient.isSignedIn() ? "login" : "signup" });
+  if (!opened) ctx.notify({ body: "Sign in to use teams.", type: "info" });
+  return false;
+}
+
+function open(ctx: GloomPluginContext, view: { teamId?: string | null; section?: TeamPaneSection; mode?: "team" | "create" }) {
+  openTeamPane(ctx.createPaneFromTemplate, view);
+}
+
+function openTeamChannel(ctx: GloomPluginContext, teamId: string) {
+  ctx.createPaneFromTemplate("new-chat-pane", { arg: teamChannelId(teamId) });
+}
+
+function errorText(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message ? error.message : fallback;
+}
+
+/** `TEAM invite @user` sends straight away; `TEAM invite link` copies a fresh link. */
+async function inviteFromCommand(ctx: GloomPluginContext, teamId: string, target: string | null) {
+  const team = teamStore.getTeam(teamId);
+  if (!team) return;
+  if (target === "link") {
+    try {
+      const link = await apiClient.createTeamInviteLink(team.id);
+      ctx.notify({ body: `Invite link for ${team.name}: ${link.url}`, type: "success" });
+    } catch (error) {
+      ctx.notify({ body: errorText(error, "Could not create an invite link."), type: "error" });
+    }
+    return;
+  }
+  if (target) {
+    try {
+      const invitation = await apiClient.inviteTeamMemberByUsername(team.id, target.replace(/^@/, ""));
+      ctx.notify({ body: `Invited ${userHandle(invitation.invitee)} to ${team.name}.`, type: "success" });
+    } catch (error) {
+      ctx.notify({ body: errorText(error, "Could not send the invitation."), type: "error" });
+    }
+    return;
+  }
+  open(ctx, { teamId: team.id, section: "invites" });
+}
+
+export function buildTeamCommandResults(ctx: GloomPluginContext, arg: string): CommandResultDef[] {
+  const snapshot = teamStore.getSnapshot();
+  const trimmed = arg.trim();
+  const sub = TEAM_SUBCOMMAND.exec(trimmed);
+  const category = "Teams";
+
+  if (!apiClient.isVerified()) {
+    return [{
+      id: "sign-in",
+      label: "Sign in to use teams",
+      detail: "Teams share layouts, notes, watchlists, and chat channels.",
+      category,
+      right: "TEAM",
+      execute: () => {
+        requireSignIn(ctx);
+      },
+    }];
+  }
+
+  const focused = teamStore.getTeam(teamStore.getDefaultTeamId()) ?? snapshot.teams[0] ?? null;
+
+  if (sub) {
+    const verb = sub[1]!.toLowerCase();
+    const rest = sub[2]?.trim() ?? "";
+    if (verb === "new") {
+      return [{
+        id: "new",
+        label: "New team",
+        detail: "Name, short name, accent color. Needs Pro; joining is free.",
+        category,
+        right: "TEAM",
+        execute: () => open(ctx, { mode: "create" }),
+      }];
+    }
+    if (verb === "invite") {
+      const teams = snapshot.teams.filter(canInviteToTeam);
+      if (teams.length === 0) {
+        return [{
+          id: "invite:none",
+          label: "No team to invite to",
+          detail: "Create one with TEAM new.",
+          category,
+          right: "TEAM",
+          disabled: true,
+          execute: () => {},
+        }];
+      }
+      const linkOnly = rest.toLowerCase() === "link";
+      const username = !linkOnly && rest.startsWith("@") ? rest : null;
+      return teams.map((team) => ({
+        id: `invite:${team.id}`,
+        label: linkOnly
+          ? `Copy an invite link for ${team.name}`
+          : username
+            ? `Invite ${username} to ${team.name}`
+            : `Invite people to ${team.name}`,
+        detail: linkOnly ? "Anyone with the link joins as a member." : describeTeam(team),
+        category,
+        right: team.shortName,
+        current: focused?.id === team.id,
+        execute: () => inviteFromCommand(ctx, team.id, linkOnly ? "link" : username),
+      }));
+    }
+    if (verb === "settings" || verb === "members" || verb === "channels" || verb === "leave" || verb === "chat") {
+      const section: TeamPaneSection = verb === "leave" ? "settings" : verb === "chat" ? "channels" : verb;
+      const teams = verb === "settings"
+        ? snapshot.teams.filter((team) => canManageTeam(team.role))
+        : snapshot.teams;
+      const named = rest ? findTeam(teams, rest) : null;
+      return (named ? [named] : teams).map((team) => ({
+        id: `${verb}:${team.id}`,
+        label: verb === "leave"
+          ? `Leave ${team.name}`
+          : verb === "chat"
+            ? `Open ${team.name} chat`
+            : `${team.name}: ${section}`,
+        detail: describeTeam(team),
+        category,
+        right: team.shortName,
+        current: focused?.id === team.id,
+        execute: () => {
+          if (verb === "chat") openTeamChannel(ctx, team.id);
+          else open(ctx, { teamId: team.id, section });
+        },
+      }));
+    }
+    if (verb === "focus") {
+      return buildFocusResults(ctx, rest);
+    }
+  }
+
+  const results: CommandResultDef[] = [];
+  for (const invitation of snapshot.invitations) {
+    results.push({
+      id: `invitation:${invitation.id}`,
+      label: `Invitation to ${invitation.team.name}`,
+      detail: `From ${userHandle(invitation.inviter)}. Accept or decline in the team pane.`,
+      category: "Invitations",
+      right: "NEW",
+      execute: () => open(ctx, {}),
+    });
+  }
+
+  const matched = trimmed ? findTeam(snapshot.teams, trimmed) : null;
+  const teams = trimmed
+    ? snapshot.teams.filter((team) =>
+        matched ? team.id === matched.id : teamLabel(team).toLowerCase().includes(trimmed.toLowerCase()),
+      )
+    : snapshot.teams;
+  for (const team of teams) {
+    results.push({
+      id: `team:${team.id}`,
+      label: teamLabel(team),
+      detail: `${describeTeam(team)} · members, invites, channels, settings`,
+      category,
+      right: team.shortName,
+      keywords: [team.name, team.shortName, team.slug],
+      current: teamStore.getDefaultTeamId() === team.id,
+      execute: () => open(ctx, { teamId: team.id }),
+    });
+  }
+
+  if (!trimmed) {
+    results.push({
+      id: "new",
+      label: snapshot.teams.length === 0 ? "Create a team" : "New team",
+      detail: snapshot.teams.length === 0
+        ? "Share layouts, notes, watchlists, and chat channels. Needs Pro; joining is free."
+        : "TEAM new",
+      category,
+      right: "TEAM",
+      execute: () => open(ctx, { mode: "create" }),
+    });
+  }
+
+  if (results.length === 0) {
+    results.push({
+      id: "none",
+      label: `No team matches "${trimmed}"`,
+      detail: "TEAM lists your teams. TEAM new creates one.",
+      category,
+      right: "TEAM",
+      disabled: true,
+      execute: () => {},
+    });
+  }
+  return results;
+}
+
+/** FOCUS lens: collapse other groups' tabs and mute their channels. */
+export function buildFocusResults(ctx: GloomPluginContext, arg: string): CommandResultDef[] {
+  const snapshot = teamStore.getSnapshot();
+  const current = snapshot.focus;
+  const trimmed = arg.trim().toLowerCase();
+  const results: CommandResultDef[] = [
+    {
+      id: "focus:all",
+      label: "All",
+      detail: "Every tab and channel.",
+      category: "Focus",
+      right: "FOCUS",
+      current: current === "all",
+      execute: () => {
+        teamStore.setFocus("all");
+        ctx.notify({ body: "Focus: everything.", type: "info" });
+      },
+    },
+    {
+      id: "focus:personal",
+      label: "Personal",
+      detail: "Team tabs collapse and team channels go quiet.",
+      category: "Focus",
+      right: "FOCUS",
+      current: current === "personal",
+      execute: () => {
+        teamStore.setFocus("personal");
+        ctx.notify({ body: "Focus: personal.", type: "info" });
+      },
+    },
+    ...snapshot.teams.map((team) => ({
+      id: `focus:${team.id}`,
+      label: teamLabel(team),
+      detail: "Only this team's tabs and channels, and its content by default in owner pickers.",
+      category: "Focus",
+      right: team.shortName,
+      current: typeof current === "object" && current.teamId === team.id,
+      keywords: [team.name, team.shortName],
+      execute: () => {
+        teamStore.setFocus({ teamId: team.id });
+        ctx.notify({ body: `Focus: ${team.name}.`, type: "info" });
+      },
+    })),
+  ];
+  if (!trimmed) return results;
+  const matched = findTeam(snapshot.teams, trimmed);
+  return results.filter((result) =>
+    matched ? result.id === `focus:${matched.id}` : result.label.toLowerCase().includes(trimmed),
+  );
+}
+
+export function registerTeamCommands(ctx: GloomPluginContext): void {
+  ctx.registerCommand({
+    id: "team",
+    label: "Team",
+    description: "Your teams: members, invites, channels, settings",
+    keywords: ["team", "teams", "invite", "members", "channels", "collaborate", "share"],
+    category: "navigation",
+    shortcut: "TEAM",
+    shortcutArg: {
+      placeholder: "[team | new | invite [@user|link] | members | channels | settings | leave | focus]",
+      kind: "text",
+      parse: (arg) => ({ query: arg.trim() }),
+    },
+    buildResults: (arg) => buildTeamCommandResults(ctx, arg),
+    execute: async (values) => {
+      const query = values?.query ?? values?.shortcut ?? "";
+      if (!requireSignIn(ctx)) return;
+      if (!query.trim()) {
+        // Plain TEAM opens the pane: the current team, or the form when there is none.
+        open(ctx, {});
+        return;
+      }
+      const results = buildTeamCommandResults(ctx, query);
+      const first = results.find((result) => !result.disabled);
+      if (!first) return;
+      await first.execute();
+    },
+  });
+
+  ctx.registerCommand({
+    id: "team-focus",
+    label: "Focus",
+    description: "Show one team, personal only, or everything",
+    keywords: ["focus", "team", "personal", "lens", "collapse", "mute"],
+    category: "navigation",
+    shortcut: "FOCUS",
+    shortcutArg: {
+      placeholder: "[all | personal | team]",
+      kind: "text",
+      parse: (arg) => ({ query: arg.trim() }),
+    },
+    hidden: () => !apiClient.isVerified() || teamStore.getSnapshot().teams.length === 0,
+    buildResults: (arg) => buildFocusResults(ctx, arg),
+    execute: async (values) => {
+      const query = values?.query ?? values?.shortcut ?? "";
+      const results = buildFocusResults(ctx, query);
+      const target = query.trim() ? results[0] : results.find((result) => result.current) ?? results[0];
+      await target?.execute();
+    },
+  });
+
+}

package/src/plugins/builtin/cloud/team/model.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import type { TeamNotification, TeamSummary } from "../../../../api-client";
+import {
+  canInviteToTeam,
+  canManageTeam,
+  countTeamUpdates,
+  deriveTeamShortName,
+  describeExpiry,
+  describeTeamNotification,
+  findTeam,
+  isTeamChannelId,
+  normalizeTeamChannelName,
+  normalizeTeamShortName,
+  sortTeamChannels,
+  teamChannelId,
+  teamIdFromChannelId,
+  teamLabel,
+  teamPrefix,
+} from "./model";
+
+function team(overrides: Partial<TeamSummary>): TeamSummary {
+  return {
+    id: "org-1",
+    name: "Macro Desk",
+    slug: "macro-desk-abc123",
+    accentColor: "magenta",
+    shortName: "MD",
+    allowMemberInvites: false,
+    channelId: "team:org-1",
+    createdAt: "2026-09-14T12:00:00.000Z",
+    role: "member",
+    memberCount: 3,
+    ...overrides,
+  };
+}
+
+describe("team markers", () => {
+  test("prefix and label use the short name", () => {
+    expect(teamPrefix(team({}))).toBe("MD·");
+    expect(teamLabel(team({}))).toBe("MD· Macro Desk");
+  });
+
+  test("channel ids round-trip", () => {
+    expect(teamChannelId("org-1")).toBe("team:org-1");
+    expect(teamIdFromChannelId("team:org-1")).toBe("org-1");
+    expect(teamIdFromChannelId("everyone")).toBeNull();
+    expect(teamIdFromChannelId("team:")).toBeNull();
+  });
+});
+
+describe("roles", () => {
+  test("owners and admins manage; members invite only when allowed", () => {
+    expect(canManageTeam("owner")).toBe(true);
+    expect(canManageTeam("admin")).toBe(true);
+    expect(canManageTeam("member")).toBe(false);
+    expect(canInviteToTeam(team({ role: "member" }))).toBe(false);
+    expect(canInviteToTeam(team({ role: "member", allowMemberInvites: true }))).toBe(true);
+    expect(canInviteToTeam(team({ role: "admin" }))).toBe(true);
+  });
+});
+
+describe("findTeam", () => {
+  const teams = [
+    team({ id: "a", name: "Macro Desk", shortName: "MD", slug: "macro-desk-1" }),
+    team({ id: "b", name: "Rates", shortName: "RT", slug: "rates-2" }),
+    team({ id: "c", name: "Rates Desk", shortName: "RD", slug: "rates-desk-3" }),
+  ];
+
+  test("matches id, short name, slug, and name exactly, ignoring case and markers", () => {
+    expect(findTeam(teams, "a")?.id).toBe("a");
+    expect(findTeam(teams, "md")?.id).toBe("a");
+    expect(findTeam(teams, "MD·")?.id).toBe("a");
+    expect(findTeam(teams, "#rates-2")?.id).toBe("b");
+    expect(findTeam(teams, "rates desk")?.id).toBe("c");
+  });
+
+  test("exact wins over prefix and ambiguous prefixes return nothing", () => {
+    expect(findTeam(teams, "rates")?.id).toBe("b");
+    expect(findTeam(teams, "rat")).toBeNull();
+    expect(findTeam(teams, "mac")?.id).toBe("a");
+    expect(findTeam(teams, "")).toBeNull();
+    expect(findTeam(teams, "nothing")).toBeNull();
+  });
+});
+
+describe("notifications", () => {
+  const base = { id: "n1", channelId: "team:org-1", createdAt: "2026-09-14T12:00:00.000Z" };
+  const teamCard = { id: "org-1", name: "Macro Desk", accentColor: "magenta" as const, shortName: "MD" };
+
+  test("describes each kind for a toast", () => {
+    const invite: TeamNotification = {
+      ...base,
+      type: "team-invite",
+      data: {
+        kind: "team-invite",
+        team: teamCard,
+        invitationId: "inv-1",
+        expiresAt: "2026-09-21T12:00:00.000Z",
+        inviter: { id: "u1", username: "vince", displayName: "Vince" },
+      },
+    };
+    expect(describeTeamNotification(invite)).toEqual({
+      title: "MD· Macro Desk",
+      body: "@vince invited you to Macro Desk. Run TEAM to accept.",
+    });
+
+    const joined: TeamNotification = {
+      ...base,
+      id: "n2",
+      type: "team-joined",
+      data: { kind: "team-joined", team: teamCard, member: { id: "u2", username: null, displayName: "Bob Jones" } },
+    };
+    expect(describeTeamNotification(joined).body).toBe("Bob Jones joined Macro Desk.");
+
+    const layout: TeamNotification = {
+      ...base,
+      id: "n3",
+      type: "layout-updated",
+      data: {
+        kind: "layout-updated",
+        team: teamCard,
+        layoutId: "l1",
+        layoutName: "Morning",
+        revision: 4,
+        author: { id: "u1", username: "vince", displayName: "Vince" },
+      },
+    };
+    expect(describeTeamNotification(layout).body).toBe("@vince published Morning r4.");
+    expect(countTeamUpdates([invite, joined, layout])).toEqual(new Map([["org-1", 3]]));
+  });
+});
+
+describe("team channels and names", () => {
+  test("channel ids carry the team id, with or without a channel name", () => {
+    expect(teamChannelId("org-1")).toBe("team:org-1");
+    expect(teamChannelId("org-1", "general")).toBe("team:org-1");
+    expect(teamChannelId("org-1", "trades")).toBe("team:org-1:trades");
+    expect(teamIdFromChannelId("team:org-1:trades")).toBe("org-1");
+    expect(teamIdFromChannelId("team:org-1")).toBe("org-1");
+    expect(teamIdFromChannelId("everyone")).toBeNull();
+    expect(isTeamChannelId("team:x")).toBe(true);
+  });
+
+  test("#general leads, the rest sort by name", () => {
+    const sorted = sortTeamChannels([
+      { id: "team:o:zeta", name: "zeta" },
+      { id: "team:o:alpha", name: "alpha" },
+      { id: "team:o", name: "general" },
+    ]);
+    expect(sorted.map((channel) => channel.name)).toEqual(["general", "alpha", "zeta"]);
+  });
+
+  test("channel names normalize the way the server keeps them", () => {
+    expect(normalizeTeamChannelName("Earnings Season")).toBe("earnings-season");
+    expect(normalizeTeamChannelName("#Trades")).toBe("trades");
+    expect(normalizeTeamChannelName("!!!")).toBe("");
+  });
+
+  test("short names derive like the server: initials or the first three letters", () => {
+    expect(deriveTeamShortName("Macro Desk")).toBe("MD");
+    expect(deriveTeamShortName("Options")).toBe("OPT");
+    expect(deriveTeamShortName("a b c d e")).toBe("ABCD");
+    expect(deriveTeamShortName("!!!")).toBe("TM");
+    expect(normalizeTeamShortName("m-d x1")).toBe("MDX1");
+  });
+
+  test("expiry reads as a short relative time", () => {
+    const now = Date.parse("2026-09-15T12:00:00.000Z");
+    expect(describeExpiry("2026-09-21T12:00:00.000Z", now)).toBe("in 6d");
+    expect(describeExpiry("2026-09-15T20:00:00.000Z", now)).toBe("in 8h");
+    expect(describeExpiry("2026-09-15T12:10:00.000Z", now)).toBe("in minutes");
+    expect(describeExpiry("2026-09-14T12:00:00.000Z", now)).toBe("expired");
+  });
+});

package/src/plugins/builtin/cloud/team/model.ts

@@ -0,0 +1,209 @@
+import type {
+  TeamAccentColor,
+  TeamNotification,
+  TeamRole,
+  TeamSummary,
+  TeamUser,
+} from "../../../../api-client";
+import { blendHex, colors } from "../../../../theme/colors";
+
+export const TEAM_CHANNEL_PREFIX = "team:";
+
+/** The text marker for team content on terminals without color: `MD·`. */
+export function teamPrefix(team: Pick<TeamSummary, "shortName">): string {
+  return `${team.shortName}·`;
+}
+
+export const TEAM_ACCENT_COLORS: readonly TeamAccentColor[] = [
+  "amber", "blue", "cyan", "green", "magenta", "orange", "red", "violet",
+];
+
+/** `team:<teamId>` is #general; other channels append their name. */
+export function teamChannelId(teamId: string, channelName?: string): string {
+  return channelName && channelName !== "general"
+    ? `${TEAM_CHANNEL_PREFIX}${teamId}:${channelName}`
+    : `${TEAM_CHANNEL_PREFIX}${teamId}`;
+}
+
+export function teamIdFromChannelId(channelId: string): string | null {
+  if (!channelId.startsWith(TEAM_CHANNEL_PREFIX)) return null;
+  const rest = channelId.slice(TEAM_CHANNEL_PREFIX.length);
+  const teamId = rest.split(":")[0];
+  return teamId || null;
+}
+
+/** #general first, then the rest by name, whatever order the server used. */
+export function sortTeamChannels<T extends { id: string; name: string }>(channels: readonly T[]): T[] {
+  return [...channels].sort((a, b) => {
+    const aGeneral = a.id.split(":").length === 2;
+    const bGeneral = b.id.split(":").length === 2;
+    if (aGeneral !== bGeneral) return aGeneral ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+export function isTeamChannelId(channelId: string): boolean {
+  return channelId.startsWith(TEAM_CHANNEL_PREFIX);
+}
+
+/** What a person types for a channel name, as the server will keep it. */
+export function normalizeTeamChannelName(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/^#+/, "")
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 24);
+}
+
+/** Initials for multi-word names, otherwise the first three letters; mirrors the server. */
+export function deriveTeamShortName(name: string): string {
+  const words = name
+    .split(/[\s\-_/]+/)
+    .map((word) => word.replace(/[^A-Za-z0-9]/g, ""))
+    .filter(Boolean);
+  const candidate = words.length >= 2
+    ? words.slice(0, 4).map((word) => word[0] ?? "").join("")
+    : (words[0] ?? "").slice(0, 3);
+  return normalizeTeamShortName(candidate) || "TM";
+}
+
+export function normalizeTeamShortName(value: string): string {
+  return value.replace(/[^A-Za-z0-9]/g, "").toUpperCase().slice(0, 4);
+}
+
+export function userHandle(user: TeamUser): string {
+  return user.username ? `@${user.username}` : user.displayName;
+}
+
+/** "in 6d", "in 3h", or "expired", for invites and links. */
+export function describeExpiry(iso: string, now = Date.now()): string {
+  const remaining = new Date(iso).getTime() - now;
+  if (!Number.isFinite(remaining) || remaining <= 0) return "expired";
+  const hours = Math.round(remaining / 3_600_000);
+  if (hours < 1) return "in minutes";
+  if (hours < 48) return `in ${hours}h`;
+  return `in ${Math.round(hours / 24)}d`;
+}
+
+/**
+ * Accent tokens map onto the active theme rather than fixed hexes so a team
+ * marker still reads as one of the theme's colors. Positive and negative are
+ * avoided as bases for the greens and reds so a team never looks like P&L.
+ */
+export function teamAccentHex(accent: TeamAccentColor): string {
+  switch (accent) {
+    case "amber":
+      return colors.warning;
+    case "blue":
+      return colors.borderFocused;
+    case "cyan":
+      return blendHex(colors.borderFocused, colors.positive, 0.5);
+    case "green":
+      return blendHex(colors.positive, colors.textBright, 0.3);
+    case "magenta":
+      return blendHex(colors.negative, colors.borderFocused, 0.45);
+    case "orange":
+      return blendHex(colors.warning, colors.negative, 0.4);
+    case "red":
+      return blendHex(colors.negative, colors.textBright, 0.25);
+    case "violet":
+      return blendHex(colors.borderFocused, colors.negative, 0.35);
+    default:
+      return colors.text;
+  }
+}
+
+export function roleLabel(role: TeamRole): string {
+  return role === "owner" ? "Owner" : role === "admin" ? "Admin" : "Member";
+}
+
+export function canManageTeam(role: TeamRole | null | undefined): boolean {
+  return role === "owner" || role === "admin";
+}
+
+export function canInviteToTeam(team: Pick<TeamSummary, "role" | "allowMemberInvites">): boolean {
+  return canManageTeam(team.role) || team.allowMemberInvites;
+}
+
+function normalizeQuery(value: string): string {
+  return value.trim().replace(/^[#@]+/, "").replace(/·$/, "").toLowerCase();
+}
+
+/**
+ * Resolves what someone typed after `TEAM` or `CHAT` to a team: the id, the
+ * short name (`MD`), the slug, or the name. Exact matches win over prefixes so
+ * `rat` finds "Rates" without ambiguity when "Rates Desk" also exists.
+ */
+export function findTeam(
+  teams: readonly TeamSummary[],
+  query: string,
+): TeamSummary | null {
+  const needle = normalizeQuery(query);
+  if (!needle) return null;
+  const exact = teams.find((team) =>
+    team.id === query.trim() ||
+    team.shortName.toLowerCase() === needle ||
+    team.slug.toLowerCase() === needle ||
+    team.name.toLowerCase() === needle,
+  );
+  if (exact) return exact;
+  const prefixed = teams.filter((team) =>
+    team.name.toLowerCase().startsWith(needle) ||
+    team.shortName.toLowerCase().startsWith(needle),
+  );
+  return prefixed.length === 1 ? prefixed[0]! : null;
+}
+
+export function teamLabel(team: Pick<TeamSummary, "name" | "shortName">): string {
+  return `${teamPrefix(team)} ${team.name}`;
+}
+
+export function describeTeam(team: TeamSummary): string {
+  const members = team.memberCount === 1 ? "1 member" : `${team.memberCount} members`;
+  return `${roleLabel(team.role)} · ${members}`;
+}
+
+/** Toast text for the team frames the server sends. */
+export function describeTeamNotification(notification: TeamNotification): {
+  title: string;
+  body: string;
+} {
+  const data = notification.data;
+  const who = (actor: { username: string | null; displayName: string }) =>
+    actor.username ? `@${actor.username}` : actor.displayName;
+  switch (data.kind) {
+    case "team-invite":
+      return {
+        title: teamLabel(data.team),
+        body: `${who(data.inviter)} invited you to ${data.team.name}. Run TEAM to accept.`,
+      };
+    case "team-joined":
+      return {
+        title: teamLabel(data.team),
+        body: `${who(data.member)} joined ${data.team.name}.`,
+      };
+    case "layout-updated":
+      return {
+        title: teamLabel(data.team),
+        body: `${who(data.author)} published ${data.layoutName} r${data.revision}.`,
+      };
+    default:
+      return { title: "Team", body: "Team update." };
+  }
+}
+
+/** Unread counts per team for the status bar: pending invites and layout updates. */
+export function countTeamUpdates(
+  notifications: readonly TeamNotification[],
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const notification of notifications) {
+    const teamId = notification.data.team.id;
+    counts.set(teamId, (counts.get(teamId) ?? 0) + 1);
+  }
+  return counts;
+}