@perspective-ai/sdk 1.0.0-alpha.2

package/src/utils.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared utilities for the Perspective Embed SDK
+ * SSR-safe - DOM access is guarded
+ */
+
+import { THEME_VALUES, type ThemeValue } from "./constants";
+import { hasDom } from "./config";
+
+/**
+ * Join class names, filtering out falsy values
+ */
+export function cn(...classes: (string | false | null | undefined)[]): string {
+  return classes
+    .map((c) => (c || "").split(" "))
+    .flat()
+    .filter(Boolean)
+    .join(" ");
+}
+
+/**
+ * Get the perspective theme class based on the theme value
+ * Returns "perspective-{theme}-theme" when theme is available, undefined otherwise
+ */
+export function getThemeClass(theme: string | undefined): string | undefined {
+  return theme && theme !== THEME_VALUES.system
+    ? `perspective-${theme}-theme`
+    : undefined;
+}
+
+/**
+ * Resolve whether dark mode should be used.
+ * Priority: 1) explicit theme override, 2) system preference
+ * SSR-safe: defaults to light theme on server
+ */
+export function resolveIsDark(theme?: ThemeValue | string): boolean {
+  if (theme === THEME_VALUES.dark) return true;
+  if (theme === THEME_VALUES.light) return false;
+  // system or undefined → use system preference (or light on server)
+  if (!hasDom()) return false;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+/**
+ * Resolve effective theme based on override and system preference
+ * Returns the theme string ('light' or 'dark')
+ */
+export function resolveTheme(themeOverride?: ThemeValue): "light" | "dark" {
+  return resolveIsDark(themeOverride) ? "dark" : "light";
+}
+
+/**
+ * Normalize and validate hex color. Returns undefined for invalid colors.
+ */
+export function normalizeHex(color: string): string | undefined {
+  const trimmed = color.trim();
+  if (!trimmed) return undefined;
+
+  const normalized = trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+
+  // Validate hex format (#RGB, #RRGGBB, or #RRGGBBAA)
+  if (/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(normalized)) {
+    return normalized;
+  }
+
+  // Try to extract valid hex chars
+  const hexChars = normalized.slice(1).replace(/[^0-9a-fA-F]/g, "");
+  if (hexChars.length >= 6) return `#${hexChars.slice(0, 6)}`;
+  if (hexChars.length >= 3) return `#${hexChars.slice(0, 3)}`;
+
+  return undefined;
+}
+
+/**
+ * Convert hex to rgba for spinner track
+ */
+export function hexToRgba(hex: string, alpha: number): string {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  if (!result || !result[1] || !result[2] || !result[3]) {
+    return `rgba(118, 41, 200, ${alpha})`;
+  }
+
+  const r = parseInt(result[1], 16);
+  const g = parseInt(result[2], 16);
+  const b = parseInt(result[3], 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}

package/src/widget.test.ts

@@ -0,0 +1,375 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createWidget } from "./widget";
+import * as config from "./config";
+import * as iframe from "./iframe";
+
+describe("createWidget", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+    vi.restoreAllMocks();
+  });
+
+  it("creates widget in container", () => {
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(handle.researchId).toBe("test-research-id");
+    expect(handle.type).toBe("widget");
+    expect(handle.container).toBe(container);
+    expect(handle.iframe).toBeInstanceOf(HTMLIFrameElement);
+    expect(container.querySelector("iframe[data-perspective]")).toBeTruthy();
+
+    handle.unmount();
+  });
+
+  it("creates loading indicator", () => {
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    const loading = container.querySelector(".perspective-loading");
+    expect(loading).toBeTruthy();
+
+    handle.unmount();
+  });
+
+  it("returns no-op handle when no DOM", () => {
+    vi.spyOn(config, "hasDom").mockReturnValue(false);
+
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(handle.iframe).toBeNull();
+    expect(handle.container).toBeNull();
+    expect(handle.unmount).toBeInstanceOf(Function);
+    expect(() => handle.unmount()).not.toThrow();
+  });
+
+  it("returns no-op handle when container is null", () => {
+    const handle = createWidget(null, {
+      researchId: "test-research-id",
+    });
+
+    expect(handle.iframe).toBeNull();
+    expect(handle.container).toBeNull();
+  });
+
+  it("is idempotent (React Strict Mode safe)", () => {
+    const handle1 = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    const handle2 = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(handle1.iframe).toBeInstanceOf(HTMLIFrameElement);
+    expect(handle2.iframe).toBeInstanceOf(HTMLIFrameElement);
+    expect(handle2.iframe).toBe(handle1.iframe);
+
+    const iframes = container.querySelectorAll("iframe[data-perspective]");
+    expect(iframes.length).toBe(1);
+
+    handle1.unmount();
+  });
+
+  it("idempotent handle can clean up existing widget", () => {
+    createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(container.querySelector("iframe[data-perspective]")).toBeTruthy();
+
+    const handle2 = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    handle2.unmount();
+
+    expect(container.querySelector("iframe[data-perspective]")).toBeFalsy();
+    expect(container.querySelector(".perspective-embed-root")).toBeFalsy();
+  });
+
+  it("idempotent handle cleans up message listeners and iframe registry", () => {
+    const cleanupSpy = vi.fn();
+    const unregisterSpy = vi.fn();
+
+    vi.spyOn(iframe, "setupMessageListener").mockReturnValue(cleanupSpy);
+    vi.spyOn(iframe, "registerIframe").mockReturnValue(unregisterSpy);
+
+    createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    const handle2 = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(cleanupSpy).not.toHaveBeenCalled();
+    expect(unregisterSpy).not.toHaveBeenCalled();
+
+    handle2.unmount();
+
+    expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    expect(unregisterSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("unmount removes elements", () => {
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(container.querySelector("iframe[data-perspective]")).toBeTruthy();
+
+    handle.unmount();
+
+    expect(container.querySelector("iframe[data-perspective]")).toBeFalsy();
+    expect(container.querySelector(".perspective-embed-root")).toBeFalsy();
+  });
+
+  it("destroy is alias for unmount", () => {
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(container.querySelector("iframe[data-perspective]")).toBeTruthy();
+
+    handle.destroy();
+
+    expect(container.querySelector("iframe[data-perspective]")).toBeFalsy();
+  });
+
+  it("update modifies config", () => {
+    const onSubmit1 = vi.fn();
+    const onSubmit2 = vi.fn();
+
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+      onSubmit: onSubmit1,
+    });
+
+    handle.update({ onSubmit: onSubmit2 });
+
+    // The update should not throw
+    expect(() => handle.update({ onSubmit: onSubmit2 })).not.toThrow();
+
+    handle.unmount();
+  });
+
+  it("applies theme class", () => {
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+      theme: "dark",
+    });
+
+    const wrapper = container.querySelector(".perspective-embed-root");
+    expect(wrapper?.classList.contains("perspective-dark-theme")).toBe(true);
+
+    handle.unmount();
+  });
+
+  it("uses custom host", () => {
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+      host: "https://custom.example.com",
+    });
+
+    const iframe = handle.iframe as HTMLIFrameElement;
+    expect(iframe.src).toContain("https://custom.example.com");
+
+    handle.unmount();
+  });
+
+  it("passes params to iframe", () => {
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+      params: { source: "test", campaign: "demo" },
+    });
+
+    const iframe = handle.iframe as HTMLIFrameElement;
+    const url = new URL(iframe.src);
+    expect(url.searchParams.get("source")).toBe("test");
+    expect(url.searchParams.get("campaign")).toBe("demo");
+
+    handle.unmount();
+  });
+
+  it("unmount is idempotent - calling twice does not throw", () => {
+    const cleanupSpy = vi.fn();
+    const unregisterSpy = vi.fn();
+
+    vi.spyOn(iframe, "setupMessageListener").mockReturnValue(cleanupSpy);
+    vi.spyOn(iframe, "registerIframe").mockReturnValue(unregisterSpy);
+
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(() => {
+      handle.unmount();
+      handle.unmount();
+    }).not.toThrow();
+
+    // Cleanup functions should only be called once
+    expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    expect(unregisterSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("destroy is idempotent - calling twice does not throw", () => {
+    const cleanupSpy = vi.fn();
+    const unregisterSpy = vi.fn();
+
+    vi.spyOn(iframe, "setupMessageListener").mockReturnValue(cleanupSpy);
+    vi.spyOn(iframe, "registerIframe").mockReturnValue(unregisterSpy);
+
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(() => {
+      handle.destroy();
+      handle.destroy();
+    }).not.toThrow();
+
+    // Cleanup functions should only be called once
+    expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    expect(unregisterSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("mixed unmount then destroy does not double-cleanup", () => {
+    const cleanupSpy = vi.fn();
+    const unregisterSpy = vi.fn();
+
+    vi.spyOn(iframe, "setupMessageListener").mockReturnValue(cleanupSpy);
+    vi.spyOn(iframe, "registerIframe").mockReturnValue(unregisterSpy);
+
+    const handle = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(() => {
+      handle.unmount();
+      handle.destroy();
+    }).not.toThrow();
+
+    // Cleanup functions should only be called once
+    expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    expect(unregisterSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("idempotent handle unmount is also idempotent", () => {
+    const cleanupSpy = vi.fn();
+    const unregisterSpy = vi.fn();
+
+    vi.spyOn(iframe, "setupMessageListener").mockReturnValue(cleanupSpy);
+    vi.spyOn(iframe, "registerIframe").mockReturnValue(unregisterSpy);
+
+    // Create first handle
+    createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    // Get idempotent handle
+    const handle2 = createWidget(container, {
+      researchId: "test-research-id",
+    });
+
+    expect(() => {
+      handle2.unmount();
+      handle2.unmount();
+    }).not.toThrow();
+
+    // Cleanup functions should only be called once
+    expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    expect(unregisterSpy).toHaveBeenCalledTimes(1);
+  });
+
+  describe("update() behavior", () => {
+    const host = "https://getperspective.ai";
+    const researchId = "test-research-id";
+
+    const sendMessage = (
+      iframeEl: HTMLIFrameElement,
+      type: string,
+      extra?: Record<string, unknown>
+    ) => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          data: { type, researchId, ...extra },
+          origin: host,
+          source: iframeEl.contentWindow,
+        })
+      );
+    };
+
+    it("update changes which callback is invoked", () => {
+      const onSubmit1 = vi.fn();
+      const onSubmit2 = vi.fn();
+
+      const handle = createWidget(container, {
+        researchId,
+        host,
+        onSubmit: onSubmit1,
+      });
+
+      handle.update({ onSubmit: onSubmit2 });
+
+      sendMessage(handle.iframe!, "perspective:submit");
+
+      expect(onSubmit2).toHaveBeenCalledTimes(1);
+      expect(onSubmit1).not.toHaveBeenCalled();
+
+      handle.unmount();
+    });
+
+    it("sequential updates only use latest callback", () => {
+      const fn1 = vi.fn();
+      const fn2 = vi.fn();
+      const fn3 = vi.fn();
+
+      const handle = createWidget(container, {
+        researchId,
+        host,
+        onSubmit: fn1,
+      });
+
+      handle.update({ onSubmit: fn2 });
+      handle.update({ onSubmit: fn3 });
+
+      sendMessage(handle.iframe!, "perspective:submit");
+
+      expect(fn3).toHaveBeenCalledTimes(1);
+      expect(fn2).not.toHaveBeenCalled();
+      expect(fn1).not.toHaveBeenCalled();
+
+      handle.unmount();
+    });
+
+    it("destroy prevents further callback invocations", () => {
+      const onSubmit = vi.fn();
+
+      const handle = createWidget(container, {
+        researchId,
+        host,
+        onSubmit,
+      });
+
+      const iframeEl = handle.iframe!;
+
+      handle.unmount();
+
+      sendMessage(iframeEl, "perspective:submit");
+
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/widget.ts

@@ -0,0 +1,195 @@
+/**
+ * Inline widget embed - renders directly in a container element
+ * SSR-safe - returns no-op handle on server
+ */
+
+import type { EmbedConfig, EmbedHandle } from "./types";
+import { hasDom, getHost } from "./config";
+import {
+  createIframe,
+  setupMessageListener,
+  registerIframe,
+  ensureGlobalListeners,
+} from "./iframe";
+import { createLoadingIndicator } from "./loading";
+import { injectStyles } from "./styles";
+import { cn, getThemeClass } from "./utils";
+
+type WidgetResources = {
+  cleanup: () => void;
+  unregister: () => void;
+  wrapper: HTMLElement;
+};
+
+const widgetResources = new WeakMap<HTMLIFrameElement, WidgetResources>();
+
+function createNoOpHandle(researchId: string, type: "widget"): EmbedHandle {
+  return {
+    unmount: () => {},
+    update: () => {},
+    destroy: () => {},
+    researchId,
+    type,
+    iframe: null,
+    container: null,
+  };
+}
+
+function createExistingWidgetHandle(
+  container: HTMLElement,
+  researchId: string
+): EmbedHandle {
+  const existingWrapper = container.querySelector<HTMLElement>(
+    ".perspective-embed-root"
+  );
+  const existingIframe = container.querySelector<HTMLIFrameElement>(
+    "iframe[data-perspective]"
+  );
+
+  let destroyed = false;
+
+  const unmount = () => {
+    if (destroyed) return;
+    destroyed = true;
+
+    if (existingIframe) {
+      const resources = widgetResources.get(existingIframe);
+      if (resources) {
+        resources.cleanup();
+        resources.unregister();
+        widgetResources.delete(existingIframe);
+      }
+    }
+    existingWrapper?.remove();
+  };
+
+  return {
+    unmount,
+    update: () => {},
+    destroy: unmount,
+    researchId,
+    type: "widget" as const,
+    iframe: existingIframe,
+    container,
+  };
+}
+
+export function createWidget(
+  container: HTMLElement | null,
+  config: EmbedConfig
+): EmbedHandle {
+  const { researchId } = config;
+
+  // SSR safety: return no-op handle
+  if (!hasDom() || !container) {
+    return createNoOpHandle(researchId, "widget");
+  }
+
+  // Idempotency check for React Strict Mode
+  if (container.querySelector("iframe[data-perspective]")) {
+    return createExistingWidgetHandle(container, researchId);
+  }
+
+  const host = getHost(config.host);
+
+  injectStyles();
+  ensureGlobalListeners();
+
+  // Create wrapper for positioning
+  const wrapper = document.createElement("div");
+  wrapper.className = cn("perspective-embed-root", getThemeClass(config.theme));
+  wrapper.style.cssText =
+    "position:relative;width:100%;height:100%;min-height:500px;";
+
+  // Create loading indicator with theme and brand colors
+  const loading = createLoadingIndicator({
+    theme: config.theme,
+    brand: config.brand,
+  });
+  wrapper.appendChild(loading);
+
+  // Create iframe (hidden initially)
+  const iframe = createIframe(
+    researchId,
+    "widget",
+    host,
+    config.params,
+    config.brand,
+    config.theme
+  );
+  iframe.style.width = "100%";
+  iframe.style.height = "100%";
+  iframe.style.minHeight = "500px";
+  iframe.style.opacity = "0";
+  iframe.style.transition = "opacity 0.3s ease";
+
+  wrapper.appendChild(iframe);
+  container.appendChild(wrapper);
+
+  // Mutable config reference for updates
+  let currentConfig = { ...config };
+
+  // Set up message listener with loading state handling
+  const cleanup = setupMessageListener(
+    researchId,
+    {
+      get onReady() {
+        return () => {
+          // Hide loading, show iframe
+          loading.style.opacity = "0";
+          iframe.style.opacity = "1";
+          setTimeout(() => loading.remove(), 300);
+          currentConfig.onReady?.();
+        };
+      },
+      get onSubmit() {
+        return currentConfig.onSubmit;
+      },
+      get onNavigate() {
+        return currentConfig.onNavigate;
+      },
+      get onClose() {
+        return currentConfig.onClose;
+      },
+      get onError() {
+        return currentConfig.onError;
+      },
+    },
+    iframe,
+    host,
+    { skipResize: true }
+  );
+
+  // Register iframe for theme change notifications
+  const unregisterIframe = registerIframe(iframe, host);
+
+  widgetResources.set(iframe, {
+    cleanup,
+    unregister: unregisterIframe,
+    wrapper,
+  });
+
+  let destroyed = false;
+
+  const unmount = () => {
+    if (destroyed) return;
+    destroyed = true;
+
+    cleanup();
+    unregisterIframe();
+    widgetResources.delete(iframe);
+    wrapper.remove();
+  };
+
+  return {
+    unmount,
+    update: (options) => {
+      currentConfig = { ...currentConfig, ...options };
+    },
+    destroy: unmount,
+    researchId,
+    type: "widget" as const,
+    iframe,
+    container,
+  };
+}