@runtypelabs/persona 3.22.0 → 3.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.22.0",
+  "version": "3.23.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -58,6 +58,7 @@
     "zod": "^3.22.4"
   },
   "devDependencies": {
+    "@size-limit/file": "^12.1.0",
     "@types/node": "^20.12.7",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
@@ -66,6 +67,7 @@
     "eslint-config-prettier": "^9.1.0",
     "fake-indexeddb": "^6.2.5",
     "rimraf": "^5.0.5",
+    "size-limit": "^12.1.0",
     "tsup": "^8.0.1",
     "typescript": "^5.4.5",
     "vitest": "^4.0.9"
@@ -98,10 +100,10 @@
   },
   "scripts": {
     "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer && pnpm run build:theme-ref && pnpm run build:theme-editor && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:animations",
-    "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --dts --out-dir dist --no-splitting",
-    "build:testing": "tsup src/testing.ts --format esm,cjs --dts --out-dir dist --no-splitting",
-    "build:smart-dom-reader": "tsup src/smart-dom-reader.ts --format esm,cjs --dts --out-dir dist --no-splitting",
-    "build:animations": "tsup src/animations/glyph-cycle.ts src/animations/wipe.ts --format esm,cjs --dts --out-dir dist/animations --no-splitting",
+    "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:testing": "tsup src/testing.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:smart-dom-reader": "tsup src/smart-dom-reader.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:animations": "tsup src/animations/glyph-cycle.ts src/animations/wipe.ts --format esm,cjs --minify --dts --out-dir dist/animations --no-splitting",
     "build:theme-ref": "tsup src/theme-reference.ts --format esm,cjs --minify --dts",
     "build:styles": "node -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('src/styles/widget.css','dist/widget.css');\"",
     "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" && tsup src/index-global.ts --format iife --global-name AgentWidget --minify --sourcemap --splitting false --out-dir dist --loader \".css=text\" && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
@@ -110,6 +112,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "test:ui": "vitest --ui",
-    "test:run": "vitest run"
+    "test:run": "vitest run",
+    "size": "size-limit"
   }
 }

package/src/components/event-stream-view.ts

@@ -7,6 +7,7 @@ import {
   resolveFollowStateFromWheel
 } from "../utils/auto-follow";
 import type { EventStreamBuffer } from "../utils/event-stream-buffer";
+import type { ThroughputMetric } from "../utils/throughput-tracker";
 import type {
   SSEEventRecord,
   AgentWidgetConfig,
@@ -151,6 +152,36 @@ function formatEventForCopy(event: SSEEventRecord): string {
   );
 }
 
+// ============================================================================
+// Output Throughput Summary
+// ============================================================================
+
+/** Format the headline value, e.g. `23.9 tok/s` or `-- tok/s` when unavailable. */
+function formatThroughputValue(metric: ThroughputMetric): string {
+  if (
+    metric.tokensPerSecond === undefined ||
+    !Number.isFinite(metric.tokensPerSecond)
+  ) {
+    return "-- tok/s";
+  }
+  return `${metric.tokensPerSecond.toFixed(1)} tok/s`;
+}
+
+/** Compact supporting details: output tokens, duration, and usage/estimate source. */
+function formatThroughputMeta(metric: ThroughputMetric): string {
+  const parts: string[] = [];
+  if (metric.outputTokens !== undefined) {
+    parts.push(`${metric.outputTokens.toLocaleString()} tok`);
+  }
+  if (metric.durationMs !== undefined) {
+    parts.push(`${(metric.durationMs / 1000).toFixed(2)}s`);
+  }
+  if (metric.source) {
+    parts.push(metric.source);
+  }
+  return parts.join(" · ");
+}
+
 // ============================================================================
 // Inline Payload Component
 // ============================================================================
@@ -381,6 +412,12 @@ export type EventStreamViewOptions = {
   onClose?: () => void;
   config?: AgentWidgetConfig;
   plugins?: AgentWidgetPlugin[];
+  /**
+   * Optional accessor for the current output-throughput metric, derived from
+   * the same SSE event stream. When provided, a compact "Output throughput"
+   * summary row is rendered and refreshed on each update.
+   */
+  getThroughput?: () => ThroughputMetric;
 };
 
 export function createEventStreamView(
@@ -396,6 +433,7 @@ export function createEventStreamView(
     onClose,
     config,
     plugins = [],
+    getThroughput,
   } = options;
   const scrollToBottomConfig = config?.features?.scrollToBottom;
   const scrollToBottomEnabled = scrollToBottomConfig?.enabled !== false;
@@ -474,11 +512,17 @@ export function createEventStreamView(
     let copyAllBtn!: HTMLButtonElement;
     let searchInput!: HTMLInputElement;
     let searchClearBtn!: HTMLButtonElement;
+    // Inline "Throughput <tok/s>" group, rendered into the header bar next to
+    // the "Events" count when getThroughput is provided. The detailed
+    // breakdown is revealed on hover via the native title tooltip.
+    let throughputValueEl: HTMLElement | null = null;
+    let throughputContainer: HTMLElement | null = null;
+    let throughputTooltipEl: HTMLElement | null = null;
 
     function buildDefaultToolbar(): HTMLElement {
       const toolbarOuter = createElement(
         "div",
-        "persona-flex persona-flex-col persona-flex-shrink-0"
+        "persona-relative persona-flex persona-flex-col persona-flex-shrink-0"
       );
 
       // --- Header bar ---
@@ -502,6 +546,58 @@ export function createEventStreamView(
       );
       countBadge.textContent = "0";
 
+      // Inline throughput group: "Throughput  146.3 tok/s", grouped with the
+      // Events count. Hover reveals tokens · duration · source via a custom
+      // tooltip (shown instantly, unlike the slow native `title` delay).
+      if (getThroughput) {
+        throughputContainer = createElement(
+          "div",
+          "persona-relative persona-flex persona-items-center persona-gap-1.5 persona-whitespace-nowrap persona-ml-1"
+        );
+        throughputContainer.style.cursor = "help";
+        // Label styled to match the "Events" title.
+        const throughputLabel = createElement(
+          "span",
+          "persona-text-sm persona-font-medium persona-text-persona-primary persona-whitespace-nowrap"
+        );
+        throughputLabel.textContent = "Throughput";
+        // Same bounding box + styling as the Events count badge.
+        throughputValueEl = createElement(
+          "span",
+          "persona-text-[11px] persona-font-mono persona-bg-persona-container persona-text-persona-muted persona-px-2 persona-py-0.5 persona-rounded persona-border persona-border-persona-border persona-tabular-nums"
+        );
+        throughputValueEl.textContent = "-- tok/s";
+
+        // Custom hover tooltip — appears instantly (no native title delay).
+        // Appended to the (non-clipping) toolbar wrapper rather than the header
+        // bar, which has overflow-hidden and would clip a dropdown. Position is
+        // measured on hover so it sits just under the throughput group.
+        throughputTooltipEl = createElement(
+          "div",
+          "persona-absolute persona-z-50 persona-whitespace-nowrap persona-rounded persona-border persona-border-persona-border persona-bg-persona-container persona-text-persona-primary persona-text-[11px] persona-font-mono persona-px-2 persona-py-1 persona-shadow"
+        );
+        throughputTooltipEl.style.display = "none";
+        throughputTooltipEl.style.pointerEvents = "none";
+        const group = throughputContainer;
+        const tooltip = throughputTooltipEl;
+        const showTooltip = () => {
+          if (!tooltip.textContent) return;
+          const gRect = group.getBoundingClientRect();
+          const pRect = toolbarOuter.getBoundingClientRect();
+          tooltip.style.left = `${gRect.left - pRect.left}px`;
+          tooltip.style.top = `${gRect.bottom - pRect.top + 4}px`;
+          tooltip.style.display = "block";
+        };
+        const hideTooltip = () => {
+          tooltip.style.display = "none";
+        };
+        throughputContainer.addEventListener("mouseenter", showTooltip);
+        throughputContainer.addEventListener("mouseleave", hideTooltip);
+
+        throughputContainer.appendChild(throughputLabel);
+        throughputContainer.appendChild(throughputValueEl);
+      }
+
       const headerSpacer = createElement("div", "persona-flex-1");
 
       // Filter dropdown
@@ -540,6 +636,7 @@ export function createEventStreamView(
 
       headerBar.appendChild(title);
       headerBar.appendChild(countBadge);
+      if (throughputContainer) headerBar.appendChild(throughputContainer);
       headerBar.appendChild(headerSpacer);
       headerBar.appendChild(filterSelect);
       headerBar.appendChild(copyAllBtn);
@@ -592,6 +689,7 @@ export function createEventStreamView(
 
       toolbarOuter.appendChild(headerBar);
       toolbarOuter.appendChild(searchBar);
+      if (throughputTooltipEl) toolbarOuter.appendChild(throughputTooltipEl);
       return toolbarOuter;
     }
 
@@ -630,6 +728,28 @@ export function createEventStreamView(
     );
     truncationBanner.style.display = "none";
 
+    // Refresh the inline header throughput value + hover tooltip. The elements
+    // live in the header bar (built by buildDefaultToolbar); this is a no-op
+    // when getThroughput is absent or a plugin replaced the toolbar.
+    function updateThroughputSummary(): void {
+      if (!getThroughput || !throughputValueEl || !throughputContainer) return;
+      const metric = getThroughput();
+      throughputValueEl.textContent = formatThroughputValue(metric);
+      // Detailed breakdown is revealed on hover via the custom tooltip; mirror
+      // it into aria-label for assistive tech. When there's nothing to show,
+      // hide the tooltip so an empty box never flashes on hover.
+      const meta = formatThroughputMeta(metric);
+      if (throughputTooltipEl) {
+        throughputTooltipEl.textContent = meta;
+        if (!meta) throughputTooltipEl.style.display = "none";
+      }
+      if (meta) {
+        throughputContainer.setAttribute("aria-label", meta);
+      } else {
+        throughputContainer.removeAttribute("aria-label");
+      }
+    }
+
     // ========================================================================
     // Events List (simple DOM, no virtual scroller)
     // ========================================================================
@@ -804,6 +924,7 @@ export function createEventStreamView(
       lastRenderTime = Date.now();
       pendingUpdate = false;
 
+      updateThroughputSummary();
       updateFilterOptions();
 
       // Truncation banner

package/src/ui.ts

@@ -89,6 +89,7 @@ import { createApprovalBubble } from "./components/approval-bubble";
 import { createSuggestions } from "./components/suggestions";
 import { EventStreamBuffer } from "./utils/event-stream-buffer";
 import { EventStreamStore } from "./utils/event-stream-store";
+import { ThroughputTracker } from "./utils/throughput-tracker";
 import { createEventStreamView } from "./components/event-stream-view";
 import { createArtifactPane, type ArtifactPaneApi } from "./components/artifact-pane";
 import {
@@ -669,6 +670,8 @@ export const createAgentExperience = (
   let eventStreamStore = showEventStreamToggle ? new EventStreamStore(eventStreamDbName) : null;
   const eventStreamMaxEvents = config.features?.eventStream?.maxEvents ?? 2000;
   let eventStreamBuffer = showEventStreamToggle ? new EventStreamBuffer(eventStreamMaxEvents, eventStreamStore) : null;
+  // Passive output-throughput tracker, fed from the same SSE tap as the buffer.
+  let throughputTracker = showEventStreamToggle ? new ThroughputTracker() : null;
   let eventStreamView: ReturnType<typeof createEventStreamView> | null = null;
   let eventStreamVisible = false;
   let eventStreamRAF: number | null = null;
@@ -858,6 +861,8 @@ export const createAgentExperience = (
         onClose: () => toggleEventStreamOff(),
         config,
         plugins,
+        getThroughput: () =>
+          throughputTracker?.getMetric() ?? { status: "idle" },
       });
     }
     if (eventStreamView) {
@@ -4508,6 +4513,7 @@ export const createAgentExperience = (
   if (eventStreamBuffer || config.onSSEEvent) {
     session.setSSEEventCallback((type: string, payload: unknown) => {
       config.onSSEEvent?.(type, payload);
+      throughputTracker?.processEvent(type, payload);
       eventStreamBuffer?.push({
         id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
         type,
@@ -4563,6 +4569,10 @@ export const createAgentExperience = (
     // intact so the user can edit and resend without retyping.
     if (session.isStreaming()) {
       session.cancel();
+      // Cancelling emits no terminal/error SSE frame, so reset the throughput
+      // tracker (as clear-chat does) to avoid a stale `running` row lingering.
+      throughputTracker?.reset();
+      eventStreamView?.update();
       return;
     }
 
@@ -4697,6 +4707,10 @@ export const createAgentExperience = (
     if (!session.isStreaming()) return;
     if (!event.composedPath().includes(container)) return;
     session.cancel();
+    // Cancelling emits no terminal/error SSE frame — reset throughput so the
+    // Events row doesn't keep showing a live rate from the stopped stream.
+    throughputTracker?.reset();
+    eventStreamView?.update();
     resetHistoryNavigation();
     event.preventDefault();
     event.stopImmediatePropagation();
@@ -5562,8 +5576,9 @@ export const createAgentExperience = (
       persistentMetadata = {};
       actionManager.syncFromMetadata();
 
-      // Clear event stream buffer and store
+      // Clear event stream buffer and store, and reset throughput tracking
       eventStreamBuffer?.clear();
+      throughputTracker?.reset();
       eventStreamView?.update();
     });
   };
@@ -5732,10 +5747,12 @@ export const createAgentExperience = (
         if (!eventStreamBuffer) {
           eventStreamStore = new EventStreamStore(eventStreamDbName);
           eventStreamBuffer = new EventStreamBuffer(eventStreamMaxEvents, eventStreamStore);
+          throughputTracker = throughputTracker ?? new ThroughputTracker();
           eventStreamStore.open().then(() => eventStreamBuffer?.restore()).catch(() => {});
-          // Register the SSE event callback (host tap + buffer)
+          // Register the SSE event callback (host tap + buffer + throughput)
           session.setSSEEventCallback((type: string, payload: unknown) => {
             config.onSSEEvent?.(type, payload);
+            throughputTracker?.processEvent(type, payload);
             eventStreamBuffer!.push({
               id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
               type,
@@ -5784,6 +5801,8 @@ export const createAgentExperience = (
         eventStreamStore?.destroy();
         eventStreamBuffer = null;
         eventStreamStore = null;
+        throughputTracker?.reset();
+        throughputTracker = null;
       }
 
       if (config.launcher?.enabled === false && launcherButtonInstance) {
@@ -7024,8 +7043,9 @@ export const createAgentExperience = (
       persistentMetadata = {};
       actionManager.syncFromMetadata();
 
-      // Clear event stream buffer and store
+      // Clear event stream buffer and store, and reset throughput tracking
       eventStreamBuffer?.clear();
+      throughputTracker?.reset();
       eventStreamView?.update();
     },
     setMessage(message: string): boolean {
@@ -7179,6 +7199,7 @@ export const createAgentExperience = (
     /** Push a raw event into the event stream buffer (for testing/debugging) */
     __pushEventStreamEvent(event: { type: string; payload: unknown }): void {
       if (eventStreamBuffer) {
+        throughputTracker?.processEvent(event.type, event.payload);
         eventStreamBuffer.push({
           id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
           type: event.type,