@frockbot/plugin-flock 0.3.11 → 0.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-flock",
-  "version": "0.3.11",
+  "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.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",
+    "@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.11",
+    "@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

@@ -2,13 +2,18 @@
 /**
  * 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.
+ * `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 { UiActivityRing } from "@frockbot/client-ui";
 import SheepAvatar from "./SheepAvatar.vue";
 import type { SheepRecipeV1 } from "../shared.js";
 
@@ -26,8 +31,12 @@ withDefaults(
 <template>
   <span class="flock-avatar-slot">
     <SheepAvatar :sheep="sheep" :label="label" :size="size" />
-    <Transition name="flock-avatar-ring">
-      <UiActivityRing v-if="working" :progress="0" />
+    <Transition name="flock-avatar-drift">
+      <span v-if="working" class="flock-avatar-drift" aria-hidden="true">
+        <i />
+        <i />
+        <i />
+      </span>
     </Transition>
   </span>
 </template>
@@ -40,13 +49,86 @@ withDefaults(
   place-items: center;
 }
 
-.flock-avatar-ring-enter-active,
-.flock-avatar-ring-leave-active {
+/*
+ * 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-ring-enter-from,
-.flock-avatar-ring-leave-to {
+.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

@@ -109,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" />
@@ -326,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/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.
+  }
+}

package/src/client/index.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import type { ClientPluginContext } from "@frockbot/client-core";
 import type { FrockBotWebData } from "@frockbot/plugin-shell/shared";
-import { ref, type Ref } from "vue";
+import { nextTick, ref, type Ref } from "vue";
 import { randomSheepRecipeV1 } from "../shared.js";
 import { flockClientPlugin } from "./index.js";
 import { pendingCreateKey, pendingSheepKey } from "./pending-create.js";
@@ -281,7 +281,8 @@ describe("Flock client reconciliation", () => {
 
     await state.value.load();
 
-    expect(state.value.error).toBe("Directory changed");
+    // The sidebar says what failed, not what the deployment called it.
+    expect(state.value.error).toBe("Couldn't load your Bots.");
     expect(storage.has(pendingCreateKey("user-a"))).toBe(false);
   });
 
@@ -481,6 +482,7 @@ describe("Flock client reconciliation", () => {
       return Promise.reject(new Error(`unexpected request: ${path}`));
     });
     const selected: string[] = [];
+    const forgotten: (string | undefined)[] = [];
     state.value.bindShell(
       ref({
         activeBotId: "alpha",
@@ -488,6 +490,11 @@ describe("Flock client reconciliation", () => {
           selected.push(botId);
           return Promise.resolve();
         },
+        transcripts: {
+          rememberViewport: () => undefined,
+          viewportFor: () => undefined,
+          forget: (botId?: string) => forgotten.push(botId),
+        },
       }) as unknown as Ref<FrockBotWebData>,
     );
     state.value.openArchive("alpha");
@@ -496,6 +503,9 @@ describe("Flock client reconciliation", () => {
     expect(state.value.lifecycles.alpha).toBe("archived");
     expect(selected.at(-1)).toBe("beta");
     expect(new URL(location.href).searchParams.get("bot")).toBe("beta");
+    // The archived Bot's held transcript goes with it, so restoring it later
+    // reads from the Bot rather than redrawing what the cache still had.
+    expect(forgotten).toEqual(["alpha"]);
   });
 
   test("reconciles a lost sheep response and clears the exact pending command", async () => {
@@ -532,3 +542,88 @@ describe("Flock client reconciliation", () => {
     expect(storage.has(pendingSheepKey("user-a", "alpha"))).toBe(false);
   });
 });
+
+describe("Flock sidebar rows follow the transcript", () => {
+  test("a settled Turn updates the row without waiting for the poll", async () => {
+    installStorage();
+    const reads: string[] = [];
+    let reply: string | undefined;
+    const state = mount((path) => {
+      if (path !== "/api/bots/unread")
+        return Promise.reject(new Error(`unexpected request: ${path}`));
+      reads.push(path);
+      return Promise.resolve({
+        schemaVersion: 1,
+        unread: [
+          {
+            schemaVersion: 1,
+            botId: "alpha",
+            count: 0,
+            capped: false,
+            unread: false,
+            manuallyUnread: false,
+            ...(reply === undefined
+              ? {}
+              : {
+                  lastMessage: {
+                    schemaVersion: 1,
+                    text: reply,
+                    at: "2026-08-31T00:00:01.000Z",
+                    role: "assistant",
+                  },
+                }),
+          },
+        ],
+      });
+    });
+    const shell = ref({
+      activeBotId: "alpha",
+      activeRunId: "run-1",
+      messages: [
+        {
+          id: "m1",
+          runId: "run-1",
+          role: "user",
+          text: "hello",
+          status: "completed",
+        },
+      ],
+    } as unknown as FrockBotWebData);
+    state.value.bindShell(shell as unknown as Ref<FrockBotWebData>);
+    // Binding a Shell is not itself a beat: nothing has settled, so nothing is
+    // re-read.
+    await nextTick();
+    expect(reads).toHaveLength(0);
+    expect(state.value.unread.alpha).toBeUndefined();
+
+    // The Turn settles: its reply is in the transcript, no run is in flight.
+    reply = "Ollama reply";
+    shell.value = {
+      ...shell.value,
+      activeRunId: undefined,
+      messages: [
+        ...shell.value.messages,
+        {
+          id: "m2",
+          runId: "run-1",
+          role: "assistant",
+          text: reply,
+          status: "completed",
+        },
+      ],
+    } as unknown as FrockBotWebData;
+    await nextTick();
+    // Draining the read the watcher started. A rendered frame does this on its
+    // own; the claim under test is that no 15-second poll was involved.
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(reads).toHaveLength(1);
+    expect(state.value.unread.alpha?.lastMessage).toMatchObject({
+      text: "Ollama reply",
+      at: "2026-08-31T00:00:01.000Z",
+      role: "assistant",
+    });
+  });
+});

package/src/client/state.ts

@@ -24,8 +24,10 @@ export interface FlockWebData {
    * Whether a directory read has ever completed.
    *
    * "No Bots yet." is a fact about the User's account, and it can only be
-   * stated once the account has been read. Before that — the first paint, and
-   * the reload after a Bot is created — the list is unknown, not empty.
+   * stated once the account has been read. Before that — the first paint, the
+   * reload after a Bot is created, and every read that failed — the list is
+   * unknown, not empty, and offering to create a first Bot to someone who
+   * already has several is the worst thing this column can say.
    */
   loaded: boolean;
   error?: string;

package/src/client/styles.css

@@ -357,6 +357,24 @@
   color: var(--frock-danger-text);
 }
 
+/* The way to try the read again, beside the sentence that says it failed. */
+.flock-retry {
+  display: inline-block;
+  margin-top: 6px;
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-control);
+  background: transparent;
+  color: var(--frock-text);
+  padding: 2px 8px;
+  font: inherit;
+  font-size: var(--frock-text-xs);
+  cursor: pointer;
+}
+
+.flock-retry:hover {
+  background: var(--frock-fill-hover);
+}
+
 /* Header identity */
 
 .flock-identity-button {