@frockbot/plugin-flock 0.3.10 → 0.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-flock",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "private": false,
   "type": "module",
   "exports": {
@@ -27,20 +27,20 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/client-core": "0.3.10",
-    "@frockbot/client-ui": "0.3.10",
-    "@frockbot/configuration-core": "0.3.10",
-    "@frockbot/kernel-contracts": "0.3.10",
-    "@frockbot/plugin-shell": "0.3.10",
+    "@frockbot/client-core": "0.3.12",
+    "@frockbot/client-ui": "0.3.12",
+    "@frockbot/configuration-core": "0.3.12",
+    "@frockbot/kernel-contracts": "0.3.12",
+    "@frockbot/plugin-shell": "0.3.12",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
-    "@frockbot/plugin-testkit": "0.3.10",
+    "@frockbot/plugin-testkit": "0.3.12",
     "@types/bun": "1.4.0",
     "@vitejs/plugin-vue": "6.0.8",
     "css-tree": "2.3.1",
-    "typescript": "5.9.3",
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
     "vite": "8.2.2",
     "vue-tsc": "3.3.10"
   },

package/src/client/BotAvatar.vue

@@ -1,20 +1,134 @@
 <script setup lang="ts">
 /**
  * What a Bot looks like. The Flock's generated sheep recipe is the avatar.
+ *
+ * `working` draws the same language the thread uses for the Bot it is talking
+ * to — particles drifting off the avatar's right — so a person reading one
+ * conversation can see another Bot still going, on a list row and on a pinned
+ * tile alike.
+ *
+ * It is three CSS dots rather than the thread's canvas. A sidebar can hold
+ * twenty rows, and twenty `requestAnimationFrame` loops running full particle
+ * fields to say one bit each — "this Bot is busy" — is a cost the list should
+ * not pay. Out here that is genuinely all there is to say: the sidebar knows a
+ * Turn is running and nothing about its pace, which is the open
+ * conversation's to show.
  */
 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-drift">
+      <span v-if="working" class="flock-avatar-drift" aria-hidden="true">
+        <i />
+        <i />
+        <i />
+      </span>
+    </Transition>
+  </span>
 </template>
+
+<style scoped>
+.flock-avatar-slot {
+  position: relative;
+  display: inline-grid;
+  flex: 0 0 auto;
+  place-items: center;
+}
+
+/*
+ * Clear of the avatar rather than over it, in the strip of row to its right.
+ * `pointer-events` keeps the whole thing out of the way of the row's click,
+ * and it lives inside the gap the row already leaves between the avatar and the
+ * name, so it never runs under the text.
+ */
+.flock-avatar-drift {
+  position: absolute;
+  z-index: 1;
+  top: 50%;
+  left: 100%;
+  width: 12px;
+  height: 6px;
+  margin-left: 2px;
+  pointer-events: none;
+  transform: translateY(-50%);
+}
+
+.flock-avatar-drift i {
+  position: absolute;
+  top: 2px;
+  width: 2px;
+  height: 2px;
+  border-radius: 50%;
+  background: var(--frock-action-primary);
+  animation: frock-drift 2400ms linear infinite;
+}
+
+.flock-avatar-drift i:nth-child(2) {
+  animation-delay: 800ms;
+}
+
+.flock-avatar-drift i:nth-child(3) {
+  animation-delay: 1600ms;
+}
+
+/*
+ * The same journey the thread's particles make — born at the avatar's edge,
+ * out to the right, fading as they go — at a size a list can afford.
+ */
+@keyframes frock-drift {
+  0% {
+    opacity: 0;
+    transform: translate(0, 0);
+  }
+
+  20% {
+    opacity: 0.9;
+  }
+
+  100% {
+    opacity: 0;
+    transform: translate(10px, -2px);
+  }
+}
+
+.flock-avatar-drift-enter-active,
+.flock-avatar-drift-leave-active {
+  transition: opacity 420ms ease-out;
+}
+
+.flock-avatar-drift-enter-from,
+.flock-avatar-drift-leave-to {
+  opacity: 0;
+}
+
+/*
+ * Reduced motion keeps the fact and drops the movement: one still dot beside
+ * the avatar, which is the whole of what this was saying.
+ */
+@media (prefers-reduced-motion: reduce) {
+  .flock-avatar-drift i {
+    animation: none;
+    opacity: 0.9;
+    transform: translate(4px, 0);
+  }
+
+  .flock-avatar-drift i:nth-child(2),
+  .flock-avatar-drift i:nth-child(3) {
+    display: none;
+  }
+}
+</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;
@@ -85,17 +109,39 @@ onMounted(() => void flock.value.load());
 
 <template>
   <div class="flock-list-actions">
-    <button type="button" class="flock-manage" @click="flock.toggleArchived">
-      {{ flock.showArchived ? "Hide archived" : "Manage" }}
+    <button
+      type="button"
+      class="flock-manage"
+      :aria-pressed="flock.showArchived"
+      @click="flock.toggleArchived"
+    >
+      {{ flock.showArchived ? "Done" : "Manage" }}
     </button>
   </div>
+  <!--
+    An unreadable list is not an empty one, and it is not a loading one either.
+    Offering to add a first Bot to a User whose Bots simply did not load is the
+    worst thing this column can say; leaving the skeleton up forever is the
+    second worst, because it says the read is still coming when it has already
+    failed. So the failure takes the slot first, and offers the read again.
+  -->
+  <p
+    v-if="flock.error && !flock.directory.bots.length"
+    class="flock-error"
+    role="alert"
+  >
+    {{ flock.error }}
+    <button type="button" class="flock-retry" @click="flock.load()">
+      Retry
+    </button>
+  </p>
   <!--
     The skeleton is for a list nobody has yet, not for every request: the first
     paint happens before `load()` is even called, and a reload after creating a
     Bot must keep the list already on screen rather than blanking it. "No Bots
     yet." is a fact about the account, so it waits for an answer.
   -->
-  <div v-if="!flock.loaded" class="flock-skeleton" aria-busy="true">
+  <div v-else-if="!flock.loaded" class="flock-skeleton" aria-busy="true">
     <span class="flock-skeleton-label">Loading your flock…</span>
     <div v-for="row in 3" :key="row" class="flock-skeleton-row">
       <UiSkeleton shape="circle" />
@@ -109,6 +155,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 +230,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 +329,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">
@@ -256,5 +348,13 @@ onMounted(() => void flock.value.load());
       </TransitionGroup>
     </div>
   </template>
-  <p v-if="flock.error" class="flock-error" role="alert">{{ flock.error }}</p>
+  <!-- The same failure over a list that still has rows: a banner, not a
+       replacement, because what is on screen is still the last thing known. -->
+  <p
+    v-if="flock.error && flock.directory.bots.length"
+    class="flock-error"
+    role="alert"
+  >
+    {{ flock.error }}
+  </p>
 </template>

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/delivered-notifications.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import {
+  claimNotificationDeliveryV1,
+  deliveredNotificationKeyV1,
+  DELIVERED_NOTIFICATIONS_KEY,
+  DELIVERED_NOTIFICATIONS_LIMIT,
+  releaseNotificationDeliveryV1,
+} from "./delivered-notifications.js";
+
+/** The half of `localStorage` the ledger uses, shared as a browser shares it. */
+function storage(initial?: string): Pick<Storage, "getItem" | "setItem"> {
+  const values = new Map<string, string>(
+    initial === undefined ? [] : [[DELIVERED_NOTIFICATIONS_KEY, initial]],
+  );
+  return {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => {
+      values.set(key, value);
+    },
+  };
+}
+
+describe("the delivered-notification ledger", () => {
+  test("the first claim wins and every later one loses", () => {
+    const shared = storage();
+    const key = deliveredNotificationKeyV1("beta", "run-1");
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(true);
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(false);
+    // A second tab reads the same storage, so it loses too — which is the
+    // whole point: one notification per message, not one per tab.
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(false);
+    // A different message is still news.
+    expect(
+      claimNotificationDeliveryV1(
+        deliveredNotificationKeyV1("beta", "run-2"),
+        shared,
+      ),
+    ).toBe(true);
+  });
+
+  test("a claim survives the reload that empties the page's own set", () => {
+    const values = new Map<string, string>();
+    const persistent = (): Pick<Storage, "getItem" | "setItem"> => ({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+    });
+    const key = deliveredNotificationKeyV1("beta", "run-1");
+    expect(claimNotificationDeliveryV1(key, persistent())).toBe(true);
+    // A brand-new page, the same browser.
+    expect(claimNotificationDeliveryV1(key, persistent())).toBe(false);
+  });
+
+  test("a notification that could not be shown gives its claim back", () => {
+    const shared = storage();
+    const key = deliveredNotificationKeyV1("beta", "run-1");
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(true);
+    releaseNotificationDeliveryV1(key, shared);
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(true);
+  });
+
+  test("the ledger is bounded, oldest first", () => {
+    const shared = storage();
+    for (let index = 0; index <= DELIVERED_NOTIFICATIONS_LIMIT; index += 1) {
+      claimNotificationDeliveryV1(
+        deliveredNotificationKeyV1("beta", `run-${index}`),
+        shared,
+      );
+    }
+    // The oldest fell off; the newest is still remembered.
+    expect(
+      claimNotificationDeliveryV1(
+        deliveredNotificationKeyV1("beta", "run-0"),
+        shared,
+      ),
+    ).toBe(true);
+    expect(
+      claimNotificationDeliveryV1(
+        deliveredNotificationKeyV1(
+          "beta",
+          `run-${DELIVERED_NOTIFICATIONS_LIMIT}`,
+        ),
+        shared,
+      ),
+    ).toBe(false);
+  });
+
+  test("junk in storage is not a reason to go silent", () => {
+    for (const junk of ["", "{", "null", '{"not":"an array"}', "[1,2,3]"]) {
+      const key = deliveredNotificationKeyV1("beta", "run-1");
+      const shared = storage(junk);
+      expect(claimNotificationDeliveryV1(key, shared)).toBe(true);
+      expect(claimNotificationDeliveryV1(key, shared)).toBe(false);
+    }
+  });
+
+  test("no storage at all still shows the notification", () => {
+    const key = deliveredNotificationKeyV1("beta", "run-1");
+    expect(claimNotificationDeliveryV1(key, undefined)).toBe(true);
+    expect(claimNotificationDeliveryV1(key, undefined)).toBe(true);
+  });
+});

package/src/client/delivered-notifications.ts

@@ -0,0 +1,100 @@
+/**
+ * Which notification intents this browser has already shown.
+ *
+ * "One notification per message" is a promise about the *person*, not about
+ * the page. The durable acknowledgement the Bot records is what closes an
+ * intent, but it lands after the notification is shown, and in that window a
+ * second tab polling the same fan-out — or the same tab after a reload —
+ * showed the identical intent again. A set on the page could not see either.
+ *
+ * `localStorage` can, because both tabs of one browser share it. It is a
+ * ledger of ids, never of content: an id already here is one this browser has
+ * spoken. It is bounded and oldest-first, so a long-lived session cannot grow
+ * it without limit; an id that falls off the end is one whose acknowledgement
+ * settled long ago.
+ */
+
+export const DELIVERED_NOTIFICATIONS_KEY =
+  "frockbot.flock.delivered-notifications.v1";
+
+/** How many ids one browser remembers. Comfortably past any in-flight burst. */
+export const DELIVERED_NOTIFICATIONS_LIMIT = 200;
+
+type WritableStorage = Pick<Storage, "getItem" | "setItem">;
+
+function browserStorage(): Storage | undefined {
+  try {
+    return typeof localStorage === "undefined" ? undefined : localStorage;
+  } catch {
+    // A browser with storage denied still shows notifications; it only loses
+    // the cross-tab half of the promise.
+    return undefined;
+  }
+}
+
+/** The key one intent is remembered under. */
+export function deliveredNotificationKeyV1(
+  botId: string,
+  notificationId: string,
+): string {
+  return `${botId}:${notificationId}`;
+}
+
+function parse(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const value: unknown = JSON.parse(raw);
+    return Array.isArray(value)
+      ? value.filter((entry): entry is string => typeof entry === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Claims the right to show the intent behind `key`, returning `false` when
+ * some other tab — or this one, before a reload — already has it.
+ *
+ * Check-and-write in one call, and the write happens *before* the notification
+ * is shown, because the gap between showing and recording is exactly where the
+ * duplicate got in.
+ */
+export function claimNotificationDeliveryV1(
+  key: string,
+  storage: WritableStorage | undefined = browserStorage(),
+): boolean {
+  if (!storage) return true;
+  try {
+    const existing = parse(storage.getItem(DELIVERED_NOTIFICATIONS_KEY));
+    if (existing.includes(key)) return false;
+    const next = [...existing, key].slice(-DELIVERED_NOTIFICATIONS_LIMIT);
+    storage.setItem(DELIVERED_NOTIFICATIONS_KEY, JSON.stringify(next));
+    return true;
+  } catch {
+    // Storage that will not take the ledger must not silence the notification.
+    return true;
+  }
+}
+
+/**
+ * Gives a claim back, for the one case where the notification was never
+ * actually shown: no permission yet. Without this the intent would be
+ * remembered as spoken and stay silent after the User granted it.
+ */
+export function releaseNotificationDeliveryV1(
+  key: string,
+  storage: WritableStorage | undefined = browserStorage(),
+): void {
+  if (!storage) return;
+  try {
+    const existing = parse(storage.getItem(DELIVERED_NOTIFICATIONS_KEY));
+    if (!existing.includes(key)) return;
+    storage.setItem(
+      DELIVERED_NOTIFICATIONS_KEY,
+      JSON.stringify(existing.filter((entry) => entry !== key)),
+    );
+  } catch {
+    // Nothing to undo that anybody can see.
+  }
+}