@runtypelabs/persona 1.41.0 → 1.43.0

package/src/utils/event-stream-controller.test.ts

@@ -0,0 +1,445 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createEventBus } from "./events";
+import type { AgentWidgetControllerEventMap } from "../types";
+
+describe("Event Stream Controller Events", () => {
+  it("should emit eventStream:opened with timestamp", () => {
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+    const handler = vi.fn();
+    eventBus.on("eventStream:opened", handler);
+
+    const now = Date.now();
+    eventBus.emit("eventStream:opened", { timestamp: now });
+
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledWith({ timestamp: now });
+  });
+
+  it("should emit eventStream:closed with timestamp", () => {
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+    const handler = vi.fn();
+    eventBus.on("eventStream:closed", handler);
+
+    const now = Date.now();
+    eventBus.emit("eventStream:closed", { timestamp: now });
+
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledWith({ timestamp: now });
+  });
+
+  it("should allow unsubscription from eventStream events", () => {
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+    const handler = vi.fn();
+    const unsub = eventBus.on("eventStream:opened", handler);
+
+    eventBus.emit("eventStream:opened", { timestamp: Date.now() });
+    expect(handler).toHaveBeenCalledOnce();
+
+    unsub();
+    eventBus.emit("eventStream:opened", { timestamp: Date.now() });
+    expect(handler).toHaveBeenCalledOnce(); // still 1 - not called again
+  });
+
+  it("should not interfere with other controller events", () => {
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+    const openedHandler = vi.fn();
+    const closedHandler = vi.fn();
+    const widgetOpenedHandler = vi.fn();
+
+    eventBus.on("eventStream:opened", openedHandler);
+    eventBus.on("eventStream:closed", closedHandler);
+    eventBus.on("widget:opened", widgetOpenedHandler);
+
+    eventBus.emit("eventStream:opened", { timestamp: Date.now() });
+
+    expect(openedHandler).toHaveBeenCalledOnce();
+    expect(closedHandler).not.toHaveBeenCalled();
+    expect(widgetOpenedHandler).not.toHaveBeenCalled();
+  });
+
+  it("should support multiple listeners for the same event", () => {
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+    const handler1 = vi.fn();
+    const handler2 = vi.fn();
+    eventBus.on("eventStream:opened", handler1);
+    eventBus.on("eventStream:opened", handler2);
+
+    const now = Date.now();
+    eventBus.emit("eventStream:opened", { timestamp: now });
+
+    expect(handler1).toHaveBeenCalledWith({ timestamp: now });
+    expect(handler2).toHaveBeenCalledWith({ timestamp: now });
+  });
+});
+
+/**
+ * Tests for programmatic controller methods (showEventStream/hideEventStream/isEventStreamVisible).
+ * These simulate the controller method logic from ui.ts without requiring full widget DOM setup.
+ */
+describe("Event Stream Controller Methods", () => {
+  it("showEventStream should call toggleEventStreamOn when feature is enabled", () => {
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+    let eventStreamVisible = false;
+    const showEventStreamToggle = true;
+    const eventStreamBuffer = { push: vi.fn(), getAll: () => [] }; // mock buffer
+
+    const toggleEventStreamOn = vi.fn(() => {
+      eventStreamVisible = true;
+      eventBus.emit("eventStream:opened", { timestamp: Date.now() });
+    });
+
+    // Simulates controller.showEventStream() logic
+    const showEventStream = () => {
+      if (!showEventStreamToggle || !eventStreamBuffer) return;
+      toggleEventStreamOn();
+    };
+
+    const handler = vi.fn();
+    eventBus.on("eventStream:opened", handler);
+
+    showEventStream();
+
+    expect(toggleEventStreamOn).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledOnce();
+    expect(eventStreamVisible).toBe(true);
+  });
+
+  it("showEventStream should no-op when feature is disabled", () => {
+    const showEventStreamToggle = false;
+    const eventStreamBuffer = { push: vi.fn(), getAll: () => [] };
+    const toggleEventStreamOn = vi.fn();
+
+    const showEventStream = () => {
+      if (!showEventStreamToggle || !eventStreamBuffer) return;
+      toggleEventStreamOn();
+    };
+
+    showEventStream();
+    expect(toggleEventStreamOn).not.toHaveBeenCalled();
+  });
+
+  it("showEventStream should no-op when buffer is null", () => {
+    const showEventStreamToggle = true;
+    const eventStreamBuffer = null;
+    const toggleEventStreamOn = vi.fn();
+
+    const showEventStream = () => {
+      if (!showEventStreamToggle || !eventStreamBuffer) return;
+      toggleEventStreamOn();
+    };
+
+    showEventStream();
+    expect(toggleEventStreamOn).not.toHaveBeenCalled();
+  });
+
+  it("hideEventStream should call toggleEventStreamOff when visible", () => {
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+    let eventStreamVisible = true;
+
+    const toggleEventStreamOff = vi.fn(() => {
+      eventStreamVisible = false;
+      eventBus.emit("eventStream:closed", { timestamp: Date.now() });
+    });
+
+    const hideEventStream = () => {
+      if (!eventStreamVisible) return;
+      toggleEventStreamOff();
+    };
+
+    const handler = vi.fn();
+    eventBus.on("eventStream:closed", handler);
+
+    hideEventStream();
+
+    expect(toggleEventStreamOff).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledOnce();
+    expect(eventStreamVisible).toBe(false);
+  });
+
+  it("hideEventStream should no-op when already hidden", () => {
+    const eventStreamVisible = false;
+    const toggleEventStreamOff = vi.fn();
+
+    const hideEventStream = () => {
+      if (!eventStreamVisible) return;
+      toggleEventStreamOff();
+    };
+
+    hideEventStream();
+    expect(toggleEventStreamOff).not.toHaveBeenCalled();
+  });
+
+  it("isEventStreamVisible should return current visibility state", () => {
+    let eventStreamVisible = false;
+
+    const isEventStreamVisible = () => eventStreamVisible;
+
+    expect(isEventStreamVisible()).toBe(false);
+
+    eventStreamVisible = true;
+    expect(isEventStreamVisible()).toBe(true);
+
+    eventStreamVisible = false;
+    expect(isEventStreamVisible()).toBe(false);
+  });
+
+  it("show then hide should fire both events in sequence", () => {
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+    let eventStreamVisible = false;
+    const showEventStreamToggle = true;
+    const eventStreamBuffer = { push: vi.fn() };
+    const events: string[] = [];
+
+    const toggleEventStreamOn = () => {
+      eventStreamVisible = true;
+      eventBus.emit("eventStream:opened", { timestamp: Date.now() });
+    };
+    const toggleEventStreamOff = () => {
+      if (!eventStreamVisible) return;
+      eventStreamVisible = false;
+      eventBus.emit("eventStream:closed", { timestamp: Date.now() });
+    };
+
+    const showEventStream = () => {
+      if (!showEventStreamToggle || !eventStreamBuffer) return;
+      toggleEventStreamOn();
+    };
+    const hideEventStream = () => {
+      if (!eventStreamVisible) return;
+      toggleEventStreamOff();
+    };
+
+    eventBus.on("eventStream:opened", () => events.push("opened"));
+    eventBus.on("eventStream:closed", () => events.push("closed"));
+
+    showEventStream();
+    hideEventStream();
+
+    expect(events).toEqual(["opened", "closed"]);
+    expect(eventStreamVisible).toBe(false);
+  });
+});
+
+/** Listener type compatible with EventTarget in Node test env (no DOM globals). */
+type EventListenerLike = ((event: Event) => void) | { handleEvent(event: Event): void };
+
+/**
+ * Minimal EventTarget-based mock for window with CustomEvent support.
+ * Used because the test environment is Node.js (no browser globals).
+ */
+class MockWindow {
+  private target = new EventTarget();
+  addEventListener(type: string, listener: EventListenerLike) {
+    this.target.addEventListener(type, listener);
+  }
+  removeEventListener(type: string, listener: EventListenerLike) {
+    this.target.removeEventListener(type, listener);
+  }
+  dispatchEvent(event: Event): boolean {
+    return this.target.dispatchEvent(event);
+  }
+}
+
+/**
+ * Tests for instance-scoped window events (persona:showEventStream / persona:hideEventStream).
+ * These verify the CustomEvent dispatching and instance ID filtering logic from ui.ts.
+ */
+describe("Event Stream Window Events", () => {
+  let mockWindow: MockWindow;
+  let cleanupFns: (() => void)[];
+
+  beforeEach(() => {
+    mockWindow = new MockWindow();
+    cleanupFns = [];
+  });
+
+  afterEach(() => {
+    cleanupFns.forEach(fn => fn());
+  });
+
+  /**
+   * Creates a mock controller with event stream window event listeners,
+   * mirroring the logic in ui.ts lines 3930-3950.
+   */
+  function createMockWidgetInstance(mountId: string, featureEnabled = true) {
+    let eventStreamVisible = false;
+    const eventBus = createEventBus<AgentWidgetControllerEventMap>();
+
+    const controller = {
+      showEventStream: vi.fn(() => {
+        if (!featureEnabled) return;
+        eventStreamVisible = true;
+        eventBus.emit("eventStream:opened", { timestamp: Date.now() });
+      }),
+      hideEventStream: vi.fn(() => {
+        if (!eventStreamVisible) return;
+        eventStreamVisible = false;
+        eventBus.emit("eventStream:closed", { timestamp: Date.now() });
+      }),
+      isEventStreamVisible: () => eventStreamVisible,
+      on: eventBus.on.bind(eventBus),
+    };
+
+    // Mirror the window event registration logic from ui.ts
+    if (featureEnabled) {
+      const instanceId = mountId || "persona-" + Math.random().toString(36).slice(2, 8);
+      const handleShowEvent = (e: Event) => {
+        const detail = (e as CustomEvent).detail;
+        if (!detail?.instanceId || detail.instanceId === instanceId) {
+          controller.showEventStream();
+        }
+      };
+      const handleHideEvent = (e: Event) => {
+        const detail = (e as CustomEvent).detail;
+        if (!detail?.instanceId || detail.instanceId === instanceId) {
+          controller.hideEventStream();
+        }
+      };
+      mockWindow.addEventListener("persona:showEventStream", handleShowEvent);
+      mockWindow.addEventListener("persona:hideEventStream", handleHideEvent);
+      cleanupFns.push(() => {
+        mockWindow.removeEventListener("persona:showEventStream", handleShowEvent);
+        mockWindow.removeEventListener("persona:hideEventStream", handleHideEvent);
+      });
+    }
+
+    return controller;
+  }
+
+  it("should open event stream via window event without instanceId", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream"));
+
+    expect(ctrl.showEventStream).toHaveBeenCalledOnce();
+    expect(ctrl.isEventStreamVisible()).toBe(true);
+  });
+
+  it("should close event stream via window event without instanceId", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+
+    // First open it
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream"));
+    expect(ctrl.isEventStreamVisible()).toBe(true);
+
+    // Then close it
+    mockWindow.dispatchEvent(new CustomEvent("persona:hideEventStream"));
+    expect(ctrl.hideEventStream).toHaveBeenCalledOnce();
+    expect(ctrl.isEventStreamVisible()).toBe(false);
+  });
+
+  it("should respond to matching instanceId", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream", {
+      detail: { instanceId: "persona-root" }
+    }));
+
+    expect(ctrl.showEventStream).toHaveBeenCalledOnce();
+    expect(ctrl.isEventStreamVisible()).toBe(true);
+  });
+
+  it("should NOT respond to non-matching instanceId", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream", {
+      detail: { instanceId: "wrong-id" }
+    }));
+
+    expect(ctrl.showEventStream).not.toHaveBeenCalled();
+    expect(ctrl.isEventStreamVisible()).toBe(false);
+  });
+
+  it("should scope events to correct instance with multiple widgets", () => {
+    const ctrl1 = createMockWidgetInstance("widget-1");
+    const ctrl2 = createMockWidgetInstance("widget-2");
+
+    // Target only widget-1
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream", {
+      detail: { instanceId: "widget-1" }
+    }));
+
+    expect(ctrl1.showEventStream).toHaveBeenCalledOnce();
+    expect(ctrl2.showEventStream).not.toHaveBeenCalled();
+    expect(ctrl1.isEventStreamVisible()).toBe(true);
+    expect(ctrl2.isEventStreamVisible()).toBe(false);
+  });
+
+  it("should broadcast to all instances when no instanceId is provided", () => {
+    const ctrl1 = createMockWidgetInstance("widget-1");
+    const ctrl2 = createMockWidgetInstance("widget-2");
+
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream"));
+
+    expect(ctrl1.showEventStream).toHaveBeenCalledOnce();
+    expect(ctrl2.showEventStream).toHaveBeenCalledOnce();
+    expect(ctrl1.isEventStreamVisible()).toBe(true);
+    expect(ctrl2.isEventStreamVisible()).toBe(true);
+  });
+
+  it("should not register listeners when feature is disabled", () => {
+    const ctrl = createMockWidgetInstance("persona-root", false);
+
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream"));
+
+    expect(ctrl.showEventStream).not.toHaveBeenCalled();
+    expect(ctrl.isEventStreamVisible()).toBe(false);
+  });
+
+  it("should clean up window listeners on destroy", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+
+    // Verify it works before cleanup
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream"));
+    expect(ctrl.showEventStream).toHaveBeenCalledOnce();
+
+    // Simulate destroy by running cleanup
+    cleanupFns.forEach(fn => fn());
+    cleanupFns = [];
+
+    // Reset mock and dispatch again
+    ctrl.showEventStream.mockClear();
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream"));
+    expect(ctrl.showEventStream).not.toHaveBeenCalled();
+  });
+
+  it("should fire eventStream:opened event via controller.on when opened via window event", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+    const handler = vi.fn();
+    ctrl.on("eventStream:opened", handler);
+
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream"));
+
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledWith(expect.objectContaining({ timestamp: expect.any(Number) }));
+  });
+
+  it("should fire eventStream:closed event via controller.on when closed via window event", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+    const closedHandler = vi.fn();
+    ctrl.on("eventStream:closed", closedHandler);
+
+    // Open first, then close
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream"));
+    mockWindow.dispatchEvent(new CustomEvent("persona:hideEventStream"));
+
+    expect(closedHandler).toHaveBeenCalledOnce();
+    expect(closedHandler).toHaveBeenCalledWith(expect.objectContaining({ timestamp: expect.any(Number) }));
+  });
+
+  it("should handle detail being null gracefully (broadcast)", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream", { detail: null }));
+
+    expect(ctrl.showEventStream).toHaveBeenCalledOnce();
+  });
+
+  it("should handle detail with empty object gracefully (broadcast)", () => {
+    const ctrl = createMockWidgetInstance("persona-root");
+
+    mockWindow.dispatchEvent(new CustomEvent("persona:showEventStream", { detail: {} }));
+
+    expect(ctrl.showEventStream).toHaveBeenCalledOnce();
+  });
+});

package/src/utils/event-stream-store.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import "fake-indexeddb/auto";
+import { EventStreamStore } from "./event-stream-store";
+import type { SSEEventRecord } from "../types";
+
+function makeEvent(type: string, index: number): SSEEventRecord {
+  return {
+    id: `evt-${index}`,
+    type,
+    timestamp: 1000 + index,
+    payload: JSON.stringify({ index })
+  };
+}
+
+describe("EventStreamStore", () => {
+  let store: EventStreamStore;
+
+  beforeEach(async () => {
+    store = new EventStreamStore("test-db-" + Math.random(), "events");
+    await store.open();
+  });
+
+  afterEach(async () => {
+    await store.destroy();
+  });
+
+  it("should open and close without error", () => {
+    expect(store).toBeDefined();
+  });
+
+  it("should store and retrieve events via putBatch + getAll", async () => {
+    const events = [makeEvent("a", 1), makeEvent("b", 2), makeEvent("c", 3)];
+    store.putBatch(events);
+    // Wait for transaction to complete
+    await new Promise((r) => setTimeout(r, 50));
+    const result = await store.getAll();
+    expect(result).toEqual(events);
+  });
+
+  it("should return events ordered by timestamp", async () => {
+    const events = [makeEvent("a", 3), makeEvent("b", 1), makeEvent("c", 2)];
+    store.putBatch(events);
+    await new Promise((r) => setTimeout(r, 50));
+    const result = await store.getAll();
+    expect(result.map((e) => e.timestamp)).toEqual([1001, 1002, 1003]);
+  });
+
+  it("should write events via put with microtask batching", async () => {
+    store.put(makeEvent("a", 1));
+    store.put(makeEvent("b", 2));
+    store.put(makeEvent("c", 3));
+    // Wait for microtask flush + transaction
+    await new Promise((r) => setTimeout(r, 50));
+    const result = await store.getAll();
+    expect(result).toHaveLength(3);
+  });
+
+  it("should return count of stored events", async () => {
+    store.putBatch([makeEvent("a", 1), makeEvent("b", 2)]);
+    await new Promise((r) => setTimeout(r, 50));
+    const count = await store.getCount();
+    expect(count).toBe(2);
+  });
+
+  it("should clear all events", async () => {
+    store.putBatch([makeEvent("a", 1), makeEvent("b", 2)]);
+    await new Promise((r) => setTimeout(r, 50));
+    await store.clear();
+    const result = await store.getAll();
+    expect(result).toEqual([]);
+    const count = await store.getCount();
+    expect(count).toBe(0);
+  });
+
+  it("should return empty array when no events stored", async () => {
+    const result = await store.getAll();
+    expect(result).toEqual([]);
+  });
+
+  it("should return 0 count when no events stored", async () => {
+    const count = await store.getCount();
+    expect(count).toBe(0);
+  });
+
+  it("should destroy the database", async () => {
+    store.putBatch([makeEvent("a", 1)]);
+    await new Promise((r) => setTimeout(r, 50));
+    await store.destroy();
+    // After destroy, getAll should return empty (db is null)
+    const result = await store.getAll();
+    expect(result).toEqual([]);
+  });
+
+  it("should handle put gracefully when db is not open", () => {
+    const closedStore = new EventStreamStore("closed-db", "events");
+    // Should not throw
+    closedStore.put(makeEvent("a", 1));
+  });
+
+  it("should handle putBatch gracefully when db is not open", () => {
+    const closedStore = new EventStreamStore("closed-db", "events");
+    // Should not throw
+    closedStore.putBatch([makeEvent("a", 1)]);
+  });
+
+  it("should clear pending writes on clear", async () => {
+    // Put some events that are still pending
+    store.put(makeEvent("a", 1));
+    // Clear before microtask flushes
+    await store.clear();
+    // Wait for microtask
+    await new Promise((r) => setTimeout(r, 50));
+    const result = await store.getAll();
+    expect(result).toEqual([]);
+  });
+
+  it("should handle putBatch with 100 events", async () => {
+    const events = Array.from({ length: 100 }, (_, i) => makeEvent("bulk", i));
+    store.putBatch(events);
+    await new Promise((r) => setTimeout(r, 50));
+    const result = await store.getAll();
+    expect(result).toHaveLength(100);
+    const count = await store.getCount();
+    expect(count).toBe(100);
+  });
+
+  it("should prevent new writes after destroy via isDestroyed flag", async () => {
+    store.put(makeEvent("a", 1));
+    await new Promise((r) => setTimeout(r, 50));
+    await store.destroy();
+    // After destroy, the store should not accept new writes
+    // Re-create a store with the same db name to verify no new data was written
+    const store2 = new EventStreamStore("verify-destroyed-" + Math.random(), "events");
+    await store2.open();
+    // The original store is destroyed - calling put should be a no-op
+    store.put(makeEvent("b", 2));
+    store.putBatch([makeEvent("c", 3)]);
+    await new Promise((r) => setTimeout(r, 50));
+    await store2.destroy();
+  });
+
+  it("should discard pending writes on destroy", async () => {
+    // Put events that are pending (not yet flushed)
+    store.put(makeEvent("a", 1));
+    store.put(makeEvent("b", 2));
+    // Destroy immediately before microtask flushes
+    await store.destroy();
+    // Pending writes should have been discarded, not flushed
+    // After destroy, db is null so flushWrites will no-op even if microtask runs
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  it("should not throw when put is called after destroy", async () => {
+    await store.destroy();
+    // Should not throw
+    store.put(makeEvent("a", 1));
+    store.putBatch([makeEvent("b", 2)]);
+  });
+
+  it("should handle IndexedDB being unavailable", async () => {
+    const origIndexedDB = globalThis.indexedDB;
+    try {
+      // Simulate IndexedDB being unavailable by deleting it
+      // @ts-expect-error - intentionally removing indexedDB for testing
+      delete globalThis.indexedDB;
+      const unavailableStore = new EventStreamStore("unavailable-db", "events");
+      // open() should reject, but put/putBatch should not throw
+      await expect(unavailableStore.open()).rejects.toBeDefined();
+      // Operations on a store that never opened should be silent no-ops
+      unavailableStore.put(makeEvent("a", 1));
+      unavailableStore.putBatch([makeEvent("b", 2)]);
+      const result = await unavailableStore.getAll();
+      expect(result).toEqual([]);
+      const count = await unavailableStore.getCount();
+      expect(count).toBe(0);
+      await unavailableStore.clear(); // should not throw
+    } finally {
+      globalThis.indexedDB = origIndexedDB;
+    }
+  });
+});