@frockbot/plugin-flock 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-flock",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "private": false,
   "type": "module",
   "exports": {
@@ -27,16 +27,16 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/client-core": "0.3.9",
-    "@frockbot/client-ui": "0.3.9",
-    "@frockbot/configuration-core": "0.3.9",
-    "@frockbot/kernel-contracts": "0.3.9",
-    "@frockbot/plugin-shell": "0.3.9",
+    "@frockbot/client-core": "0.3.11",
+    "@frockbot/client-ui": "0.3.11",
+    "@frockbot/configuration-core": "0.3.11",
+    "@frockbot/kernel-contracts": "0.3.11",
+    "@frockbot/plugin-shell": "0.3.11",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
-    "@frockbot/plugin-testkit": "0.3.9",
+    "@frockbot/plugin-testkit": "0.3.11",
     "@types/bun": "1.4.0",
     "@vitejs/plugin-vue": "6.0.8",
     "css-tree": "2.3.1",

package/src/client/BotAvatar.vue

@@ -1,20 +1,52 @@
 <script setup lang="ts">
 /**
  * What a Bot looks like. The Flock's generated sheep recipe is the avatar.
+ *
+ * `working` draws the same activity ring the thread puts on the Bot it is
+ * talking to, so a person reading one conversation can see another Bot still
+ * going — on a list row and on a pinned tile alike. The sidebar knows only that
+ * a Turn is running; the step count is the open conversation's to show, so a
+ * ring out here pulses and does not tick.
  */
+import { UiActivityRing } from "@frockbot/client-ui";
 import SheepAvatar from "./SheepAvatar.vue";
 import type { SheepRecipeV1 } from "../shared.js";
 
-const props = withDefaults(
+withDefaults(
   defineProps<{
     botId: string;
     sheep: SheepRecipeV1;
     label?: string;
-    size?: "mini" | "small" | "large";
+    size?: "mini" | "small" | "tile" | "large";
+    working?: boolean;
   }>(),
-  { label: "Bot avatar", size: "small" },
+  { label: "Bot avatar", size: "small", working: false },
 );
 </script>
 <template>
-  <SheepAvatar :sheep="sheep" :label="label" :size="size" />
+  <span class="flock-avatar-slot">
+    <SheepAvatar :sheep="sheep" :label="label" :size="size" />
+    <Transition name="flock-avatar-ring">
+      <UiActivityRing v-if="working" :progress="0" />
+    </Transition>
+  </span>
 </template>
+
+<style scoped>
+.flock-avatar-slot {
+  position: relative;
+  display: inline-grid;
+  flex: 0 0 auto;
+  place-items: center;
+}
+
+.flock-avatar-ring-enter-active,
+.flock-avatar-ring-leave-active {
+  transition: opacity 420ms ease-out;
+}
+
+.flock-avatar-ring-enter-from,
+.flock-avatar-ring-leave-to {
+  opacity: 0;
+}
+</style>

package/src/client/FlockSidebar.vue

@@ -3,7 +3,11 @@ import { UiSkeleton } from "@frockbot/client-ui";
 import { computed, inject, onMounted } from "vue";
 import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
 import { flockWebDataKey } from "./state.js";
-import { formatSidebarMessageTimeV1, groupSidebarBotsV1 } from "./sidebar.js";
+import {
+  formatSidebarMessageTimeV1,
+  groupSidebarBotsV1,
+  partitionPinnedSidebarBotsV1,
+} from "./sidebar.js";
 import BotAvatar from "./BotAvatar.vue";
 
 const injectedFlock = inject(flockWebDataKey);
@@ -33,8 +37,16 @@ const listedBots = computed(() =>
 const visibleBots = computed(() =>
   listedBots.value.filter((bot) => !isHidden(bot.botId)),
 );
+/*
+ * A pinned Bot is a tile above the list instead of a row inside it, never
+ * both: the tile is the row, moved, so grouping runs over what is left.
+ */
+const partitionedBots = computed(() =>
+  partitionPinnedSidebarBotsV1(visibleBots.value, flock.value.profiles),
+);
+const pinnedBots = computed(() => partitionedBots.value.pinned);
 const groupedVisibleBots = computed(() =>
-  groupSidebarBotsV1(visibleBots.value, flock.value.profiles),
+  groupSidebarBotsV1(partitionedBots.value.rest, flock.value.profiles),
 );
 const hiddenBots = computed(() =>
   listedBots.value.filter((bot) => isHidden(bot.botId)),
@@ -65,6 +77,18 @@ function previewTime(botId: string): string {
 function isUnread(botId: string): boolean {
   return flock.value.unread[botId]?.unread === true;
 }
+/**
+ * Whether the row draws an activity ring.
+ *
+ * The open Bot's own Turn is the Shell's — it is projecting the run into the
+ * conversation and knows about it a poll sooner — so that row reads the Shell.
+ * Every other row reads the unread fan-out, which is the only thing that knows
+ * a Bot in another conversation is working.
+ */
+function isWorking(botId: string): boolean {
+  if (botId === active.value) return shell.value.activeRunId !== undefined;
+  return flock.value.unread[botId]?.working === true;
+}
 function unreadLabel(botId: string): string | undefined {
   const view = flock.value.unread[botId];
   if (!view?.unread || view.count === 0) return undefined;
@@ -109,6 +133,50 @@ onMounted(() => void flock.value.load());
     No Bots yet. Add your first sheep.
   </p>
   <template v-else>
+    <!--
+      Pinned Bots: large tiles above the labelled groups, in pin order. The
+      tile is the row moved, so clicking it selects exactly as a row does.
+    -->
+    <TransitionGroup
+      v-if="pinnedBots.length"
+      name="flock-row"
+      tag="div"
+      class="flock-pinned"
+    >
+      <button
+        v-for="bot in pinnedBots"
+        :key="bot.botId"
+        type="button"
+        class="flock-pinned-tile"
+        :class="{
+          active: active === bot.botId,
+          archived: flock.lifecycles[bot.botId] === 'archived',
+          unread: isUnread(bot.botId),
+        }"
+        :disabled="flock.lifecycles[bot.botId] === 'archived'"
+        :aria-current="active === bot.botId ? 'true' : undefined"
+        @click="flock.select(bot.botId)"
+      >
+        <span class="flock-pinned-art">
+          <BotAvatar
+            :bot-id="bot.botId"
+            :sheep="flock.identities[bot.botId]?.sheep ?? bot.sheep"
+            size="tile"
+            :label="`${botName(bot.botId, bot.initialName)} avatar`"
+            :working="isWorking(bot.botId)"
+          />
+          <i
+            v-if="isUnread(bot.botId)"
+            class="flock-pinned-dot"
+            role="img"
+            :aria-label="`${botName(bot.botId, bot.initialName)} has unread`"
+          />
+        </span>
+        <span class="flock-pinned-name">{{
+          botName(bot.botId, bot.initialName)
+        }}</span>
+      </button>
+    </TransitionGroup>
     <div class="flock-groups">
       <section
         v-for="group in groupedVisibleBots.groups"
@@ -140,6 +208,7 @@ onMounted(() => void flock.value.load());
                 :bot-id="bot.botId"
                 :sheep="flock.identities[bot.botId]?.sheep ?? bot.sheep"
                 :label="`${botName(bot.botId, bot.initialName)} avatar`"
+                :working="isWorking(bot.botId)"
               />
               <span class="flock-bot-copy">
                 <span class="flock-bot-primary">
@@ -238,6 +307,7 @@ onMounted(() => void flock.value.load());
               :bot-id="bot.botId"
               :sheep="flock.identities[bot.botId]?.sheep ?? bot.sheep"
               :label="`${botName(bot.botId, bot.initialName)} avatar`"
+              :working="isWorking(bot.botId)"
             />
             <span class="flock-bot-copy">
               <span class="flock-bot-primary">

package/src/client/SheepAvatar.vue

@@ -5,7 +5,7 @@ const props = withDefaults(
   defineProps<{
     sheep: SheepRecipeV1;
     label?: string;
-    size?: "mini" | "small" | "large";
+    size?: "mini" | "small" | "tile" | "large";
   }>(),
   { label: "Bot sheep", size: "small" },
 );

package/src/client/sidebar.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { formatSidebarMessageTimeV1, groupSidebarBotsV1 } from "./sidebar.js";
+import {
+  formatSidebarMessageTimeV1,
+  groupSidebarBotsV1,
+  partitionPinnedSidebarBotsV1,
+} from "./sidebar.js";
 
 const bots = [
   { botId: "alpha" },
@@ -8,6 +12,48 @@ const bots = [
   { botId: "delta" },
 ];
 
+describe("pinned sidebar Bots", () => {
+  test("orders pinned Bots by pin time and leaves the rest in list order", () => {
+    expect(
+      partitionPinnedSidebarBotsV1(bots, {
+        alpha: { pinnedAt: "2026-09-02T09:00:00.000Z" },
+        beta: {},
+        gamma: { pinnedAt: "2026-08-30T09:00:00.000Z" },
+      }),
+    ).toEqual({
+      pinned: [{ botId: "gamma" }, { botId: "alpha" }],
+      rest: [{ botId: "beta" }, { botId: "delta" }],
+    });
+  });
+
+  test("a pinned Bot leaves the labelled groups entirely", () => {
+    const profiles: Record<string, { label?: string; pinnedAt?: string }> = {
+      alpha: { label: "Work", pinnedAt: "2026-09-02T09:00:00.000Z" },
+      beta: { label: "Work" },
+    };
+    const { pinned, rest } = partitionPinnedSidebarBotsV1(
+      bots.slice(0, 2),
+      profiles,
+    );
+    expect(pinned.map((bot) => bot.botId)).toEqual(["alpha"]);
+    expect(
+      groupSidebarBotsV1(rest, profiles).groups.map((group) => ({
+        label: group.label,
+        bots: group.bots.map((bot) => bot.botId),
+      })),
+    ).toEqual([{ label: "Work", bots: ["beta"] }]);
+  });
+
+  test("treats a blank pin instant as unpinned", () => {
+    expect(
+      partitionPinnedSidebarBotsV1(bots.slice(0, 2), {
+        alpha: { pinnedAt: "  " },
+        beta: {},
+      }).pinned,
+    ).toEqual([]);
+  });
+});
+
 describe("sidebar Bot groups", () => {
   test("renders one plain list until a visible Bot has a label", () => {
     expect(groupSidebarBotsV1(bots.slice(0, 2), {})).toEqual({

package/src/client/sidebar.ts

@@ -1,3 +1,40 @@
+export interface PinnedSidebarBotsV1<T> {
+  /** Pinned Bots, earliest pin first. Rendered as tiles above the list. */
+  pinned: T[];
+  /** Everything else, in the order it arrived. */
+  rest: T[];
+}
+
+/**
+ * Splits the pinned Bots out of the sidebar list. A pinned Bot is a tile at
+ * the top instead of a row below, never both, so the list this returns is what
+ * {@link groupSidebarBotsV1} then groups by label.
+ *
+ * Order is by pin time — earliest first — because the tile row is a place a
+ * User builds up over time and a Bot pinned today must not displace the one
+ * they pinned last month. Ties and unparseable instants keep list order.
+ */
+export function partitionPinnedSidebarBotsV1<T extends { botId: string }>(
+  bots: readonly T[],
+  profiles: Readonly<Record<string, { pinnedAt?: string } | undefined>>,
+): PinnedSidebarBotsV1<T> {
+  const pinned: Array<{ bot: T; at: number; index: number }> = [];
+  const rest: T[] = [];
+  for (const [index, bot] of bots.entries()) {
+    const pinnedAt = profiles[bot.botId]?.pinnedAt?.trim();
+    if (!pinnedAt) {
+      rest.push(bot);
+      continue;
+    }
+    const at = Date.parse(pinnedAt);
+    pinned.push({ bot, at: Number.isFinite(at) ? at : 0, index });
+  }
+  pinned.sort((left, right) =>
+    left.at === right.at ? left.index - right.index : left.at - right.at,
+  );
+  return { pinned: pinned.map((entry) => entry.bot), rest };
+}
+
 export interface SidebarBotGroupV1<T> {
   key: string;
   label: string;

package/src/client/styles.css

@@ -16,6 +16,13 @@
   border-radius: 9px;
 }
 
+/* The pinned sidebar tile: round, so a pin reads as a destination not a row. */
+.flock-avatar--tile {
+  width: var(--frock-avatar-lg);
+  height: var(--frock-avatar-lg);
+  border-radius: 50%;
+}
+
 .flock-avatar--large {
   width: 188px;
   height: 188px;
@@ -63,6 +70,88 @@
   color: var(--frock-text);
 }
 
+/*
+ * Pinned Bots. A wrapping row of large round tiles above the labelled groups,
+ * each one a whole Bot rather than a line of text about it.
+ */
+.flock-pinned {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 4px 6px 10px;
+  border-bottom: 1px solid var(--frock-border);
+  margin-bottom: 8px;
+}
+
+.flock-pinned-tile {
+  display: flex;
+  width: 72px;
+  flex: 0 0 auto;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 2px;
+  border: 0;
+  border-radius: var(--frock-radius-card);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+  transition: background-color var(--frock-motion-fast);
+}
+
+.flock-pinned-tile:hover:not(:disabled) {
+  background: var(--frock-fill-hover);
+}
+
+.flock-pinned-tile.active {
+  background: var(--frock-fill-pressed);
+}
+
+.flock-pinned-tile.archived {
+  opacity: 0.72;
+  cursor: default;
+}
+
+.flock-pinned-tile:focus-visible {
+  outline: 2px solid var(--frock-focus-ring);
+  outline-offset: 2px;
+}
+
+.flock-pinned-art {
+  position: relative;
+  display: inline-flex;
+}
+
+/* The tile has no preview line, so unread is a dot rather than bold text. */
+.flock-pinned-dot {
+  position: absolute;
+  right: 0;
+  bottom: 2px;
+  width: 10px;
+  height: 10px;
+  border-radius: 999px;
+  background: var(--frock-action-primary);
+  box-shadow: 0 0 0 2px var(--frock-surface);
+}
+
+.flock-pinned-name {
+  max-width: 100%;
+  overflow: hidden;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-xs);
+  line-height: var(--frock-leading-tight);
+  text-align: center;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.flock-pinned-tile.active .flock-pinned-name,
+.flock-pinned-tile.unread .flock-pinned-name {
+  color: var(--frock-text);
+  font-weight: 600;
+}
+
 .flock-groups,
 .flock-group,
 .flock-rows {

package/src/shared.test.ts

@@ -184,6 +184,28 @@ describe("Flock v1 contracts", () => {
       }),
     ).toThrow("duplicate IDs");
   });
+
+  test("carries the pin instant, and refuses one that is not an instant", () => {
+    const identity = {
+      schemaVersion: 1 as const,
+      botId: "alpha",
+      name: "Atlas",
+      namedBy: "user" as const,
+      hiddenFromSidebar: false,
+      pinnedAt: "2026-09-03T10:15:00.000Z",
+    };
+    expect(decodeBotIdentityViewV1(structuredClone(identity))).toEqual(
+      identity,
+    );
+    // Absent stays absent: every identity written before pinning existed.
+    const { pinnedAt: _pinnedAt, ...unpinned } = identity;
+    expect(decodeBotIdentityViewV1(structuredClone(unpinned))).toEqual(
+      unpinned,
+    );
+    expect(() =>
+      decodeBotIdentityViewV1({ ...identity, pinnedAt: "someday" }),
+    ).toThrow("pinnedAt is invalid");
+  });
 });
 
 describe("stored Bot directory migration", () => {

package/src/shared.ts

@@ -137,6 +137,12 @@ export interface BotIdentityViewV1 {
   /** Purely organisational sidebar group; never part of Bot instructions. */
   label?: string;
   title?: string;
+  /**
+   * When the User pinned this Bot, as an ISO 8601 instant. A pinned Bot is
+   * shown as a tile above the list instead of a row inside it, earliest pin
+   * first. Absent means not pinned.
+   */
+  pinnedAt?: string;
 }
 
 export interface BotIdentityDirectoryViewV1 {
@@ -600,7 +606,7 @@ export function decodeBotIdentityViewV1(input: unknown): BotIdentityViewV1 {
   exact(
     value,
     ["schemaVersion", "botId", "name", "namedBy", "hiddenFromSidebar"],
-    ["label", "title"],
+    ["label", "title", "pinnedAt"],
   );
   if (value.schemaVersion !== 1 || typeof value.hiddenFromSidebar !== "boolean")
     throw new FlockDecodeError("Bot identity is invalid");
@@ -616,9 +622,20 @@ export function decodeBotIdentityViewV1(input: unknown): BotIdentityViewV1 {
     ...(value.title === undefined
       ? {}
       : { title: boundedText(value.title, "title", 120) }),
+    ...(value.pinnedAt === undefined
+      ? {}
+      : { pinnedAt: timestampText(value.pinnedAt, "pinnedAt") }),
   };
 }
 
+/** An ISO 8601 instant. The sidebar orders pinned Bots by it. */
+function timestampText(value: unknown, label: string): string {
+  const candidate = boundedText(value, label, 64);
+  if (!Number.isFinite(Date.parse(candidate)))
+    throw new FlockDecodeError(`${label} is invalid`);
+  return candidate;
+}
+
 export function decodeBotIdentityDirectoryViewV1(
   input: unknown,
 ): BotIdentityDirectoryViewV1 {