@aiworkbench/vibe-bridge 0.0.1

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aiworkbench/vibe-bridge",
+  "version": "0.0.1",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target=browser --external react --external react-dom --external next --external next-auth --external next-auth/react --external next/navigation --external sonner && tsc --emitDeclarationOnly",
+    "dev": "tsc --watch --emitDeclarationOnly",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "files": ["dist", "src"],
+  "dependencies": {
+    "@aiworkbench/vibe-types": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "next": ">=14.0.0",
+    "next-auth": "^4.0.0",
+    "sonner": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "sonner": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "sonner": "^2.0.0"
+  }
+}

package/src/adapters/api.ts

@@ -0,0 +1,24 @@
+import type { ApiBridge } from "@aiworkbench/vibe-types";
+
+export interface ApiAdapterDeps {
+  getToken: () => Promise<string>;
+}
+
+export function createApiAdapter(deps: ApiAdapterDeps): ApiBridge {
+  return {
+    async fetch(endpoint: string, options?: RequestInit): Promise<Response> {
+      const url = endpoint.startsWith("/api/")
+        ? endpoint
+        : `/api/${endpoint.replace(/^\//, "")}`;
+
+      const token = await deps.getToken();
+      const headers = new Headers(options?.headers);
+      headers.set("Authorization", `Bearer ${token}`);
+
+      return globalThis.fetch(url, {
+        ...options,
+        headers,
+      });
+    },
+  };
+}

package/src/adapters/auth.ts

@@ -0,0 +1,28 @@
+import type { AuthBridge, BridgeUser } from "@aiworkbench/vibe-types";
+
+export interface AuthAdapterDeps {
+  session: {
+    user?: { name?: string | null; email?: string | null } | null;
+    idToken?: string;
+  } | null;
+}
+
+export function createAuthAdapter(deps: AuthAdapterDeps): AuthBridge {
+  return {
+    getUser(): BridgeUser {
+      const user = deps.session?.user;
+      return {
+        id: user?.email ?? "unknown",
+        name: user?.name ?? "Unknown User",
+        email: user?.email ?? undefined,
+      };
+    },
+    async getToken(): Promise<string> {
+      const token = deps.session?.idToken;
+      if (!token) {
+        throw new Error("No authentication token available.");
+      }
+      return token;
+    },
+  };
+}

package/src/adapters/events.ts

@@ -0,0 +1,16 @@
+import type { EventsBridge, EventPayload } from "@aiworkbench/vibe-types";
+import { emitEvent, onEvent, onceEvent } from "../core/event-bus";
+
+export function createEventsAdapter(appId: string): EventsBridge {
+  return {
+    emit(event: string, payload?: EventPayload): void {
+      emitEvent(event, payload ?? {}, appId);
+    },
+    on(event: string, handler: (payload: EventPayload) => void): () => void {
+      return onEvent(event, (detail) => handler(detail.payload));
+    },
+    once(event: string, handler: (payload: EventPayload) => void): () => void {
+      return onceEvent(event, (detail) => handler(detail.payload));
+    },
+  };
+}

package/src/adapters/navigation.ts

@@ -0,0 +1,21 @@
+import type { NavigationBridge } from "@aiworkbench/vibe-types";
+
+export interface NavigationAdapterDeps {
+  push: (path: string) => void;
+}
+
+export function createNavigationAdapter(
+  deps: NavigationAdapterDeps,
+): NavigationBridge {
+  return {
+    navigate(path: string): void {
+      // Block external URLs and javascript: protocol
+      if (/^https?:\/\//i.test(path) || /^javascript:/i.test(path)) {
+        throw new Error(
+          `Navigation to external URLs is not allowed: ${path}`,
+        );
+      }
+      deps.push(path);
+    },
+  };
+}

package/src/adapters/storage.ts

@@ -0,0 +1,27 @@
+import type { StorageBridge } from "@aiworkbench/vibe-types";
+
+export function createStorageAdapter(appId: string): StorageBridge {
+  const prefix = `vibe:${appId}:`;
+
+  return {
+    async get(key: string): Promise<string | null> {
+      return localStorage.getItem(`${prefix}${key}`);
+    },
+    async set(key: string, value: string): Promise<void> {
+      localStorage.setItem(`${prefix}${key}`, value);
+    },
+    async remove(key: string): Promise<void> {
+      localStorage.removeItem(`${prefix}${key}`);
+    },
+    async keys(): Promise<string[]> {
+      const result: string[] = [];
+      for (let i = 0; i < localStorage.length; i++) {
+        const k = localStorage.key(i);
+        if (k?.startsWith(prefix)) {
+          result.push(k.slice(prefix.length));
+        }
+      }
+      return result;
+    },
+  };
+}

package/src/adapters/theme.ts

@@ -0,0 +1,24 @@
+import type { ThemeBridge } from "@aiworkbench/vibe-types";
+
+export function createThemeAdapter(): ThemeBridge {
+  return {
+    current(): "light" | "dark" {
+      // Check <html> class for Tailwind dark mode convention
+      const html = document.documentElement;
+      if (html.classList.contains("dark")) return "dark";
+      if (html.classList.contains("light")) return "light";
+
+      // Check data-theme attribute
+      const dataTheme = html.getAttribute("data-theme");
+      if (dataTheme === "dark") return "dark";
+      if (dataTheme === "light") return "light";
+
+      // Fallback to prefers-color-scheme media query
+      if (globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches) {
+        return "dark";
+      }
+
+      return "light";
+    },
+  };
+}

package/src/adapters/toast.ts

@@ -0,0 +1,34 @@
+import type { ToastBridge } from "@aiworkbench/vibe-types";
+
+export interface ToastAdapterDeps {
+  toast: {
+    (message: string): void;
+    success: (message: string) => void;
+    error: (message: string) => void;
+    info: (message: string) => void;
+  };
+}
+
+export function createToastAdapter(deps: ToastAdapterDeps): ToastBridge {
+  return {
+    show(
+      message: string,
+      options?: { type?: "info" | "success" | "error" },
+    ): void {
+      const type = options?.type ?? "info";
+      switch (type) {
+        case "success":
+          deps.toast.success(message);
+          break;
+        case "error":
+          deps.toast.error(message);
+          break;
+        case "info":
+          deps.toast.info(message);
+          break;
+        default:
+          deps.toast(message);
+      }
+    },
+  };
+}

package/src/components/VibeErrorBoundary.tsx

@@ -0,0 +1,36 @@
+import { Component, type ReactNode, type ErrorInfo } from "react";
+
+interface VibeErrorBoundaryProps {
+  fallback: (error: Error) => ReactNode;
+  onError?: (error: Error) => void;
+  children: ReactNode;
+}
+
+interface VibeErrorBoundaryState {
+  error: Error | null;
+}
+
+export class VibeErrorBoundary extends Component<
+  VibeErrorBoundaryProps,
+  VibeErrorBoundaryState
+> {
+  constructor(props: VibeErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): VibeErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, _info: ErrorInfo): void {
+    this.props.onError?.(error);
+  }
+
+  render(): ReactNode {
+    if (this.state.error) {
+      return this.props.fallback(this.state.error);
+    }
+    return this.props.children;
+  }
+}

package/src/components/VibeHost.tsx

@@ -0,0 +1,104 @@
+import { useRef, useEffect, useCallback } from "react";
+import type { Bridge } from "@aiworkbench/vibe-types";
+import { useVibeLoader } from "../hooks/useVibeLoader";
+import { useVibeBridge } from "../hooks/useVibeBridge";
+import { VibeErrorBoundary } from "./VibeErrorBoundary";
+import type { VibeHostProps } from "../core/types";
+
+interface VibeElementInstance extends HTMLElement {
+  bridge: Bridge;
+}
+
+function VibeHostInner({
+  manifest,
+  src,
+  fallback,
+  errorFallback,
+  adapters,
+  onReady,
+  onError,
+  className,
+  style,
+}: VibeHostProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const elementRef = useRef<VibeElementInstance | null>(null);
+  const readyFiredRef = useRef(false);
+
+  const { status, error: loadError } = useVibeLoader(src, manifest.id);
+
+  const bridge = useVibeBridge({
+    appId: manifest.id,
+    permissions: manifest.permissions,
+    overrides: adapters,
+  });
+
+  // Handle load errors
+  useEffect(() => {
+    if (loadError) {
+      onError?.(loadError);
+    }
+  }, [loadError, onError]);
+
+  // Mount the custom element once it's defined
+  useEffect(() => {
+    const container = containerRef.current;
+    if (status !== "ready" || !container) return;
+
+    // Create and mount the custom element
+    const el = document.createElement(manifest.id) as VibeElementInstance;
+    el.bridge = bridge;
+    container.appendChild(el);
+    elementRef.current = el;
+
+    if (!readyFiredRef.current) {
+      readyFiredRef.current = true;
+      onReady?.();
+    }
+
+    return () => {
+      if (container.contains(el)) {
+        container.removeChild(el);
+      }
+      elementRef.current = null;
+    };
+  }, [status, manifest.id]);
+
+  // Re-inject bridge when it changes (session/theme updates)
+  useEffect(() => {
+    if (elementRef.current) {
+      elementRef.current.bridge = bridge;
+    }
+  }, [bridge]);
+
+  if (status === "error" && loadError) {
+    if (errorFallback) {
+      return <>{errorFallback(loadError)}</>;
+    }
+    return null;
+  }
+
+  if (status === "loading") {
+    return <>{fallback ?? null}</>;
+  }
+
+  return <div ref={containerRef} className={className} style={style} />;
+}
+
+export function VibeHost(props: VibeHostProps) {
+  const defaultErrorFallback = useCallback(
+    (error: Error) => {
+      props.onError?.(error);
+      if (props.errorFallback) {
+        return <>{props.errorFallback(error)}</>;
+      }
+      return null;
+    },
+    [props.onError, props.errorFallback],
+  );
+
+  return (
+    <VibeErrorBoundary fallback={defaultErrorFallback} onError={props.onError}>
+      <VibeHostInner {...props} />
+    </VibeErrorBoundary>
+  );
+}

package/src/core/event-bus.ts

@@ -0,0 +1,60 @@
+const VIBE_EVENT_PREFIX = "vibe:";
+
+export interface VibeEventDetail {
+  payload: Record<string, unknown>;
+  sourceAppId: string;
+}
+
+let sharedBus: EventTarget | null = null;
+
+export function getEventBus(): EventTarget {
+  if (!sharedBus) {
+    sharedBus = new EventTarget();
+  }
+  return sharedBus;
+}
+
+export function prefixedEventName(event: string): string {
+  if (event.startsWith(VIBE_EVENT_PREFIX)) {
+    return event;
+  }
+  return `${VIBE_EVENT_PREFIX}${event}`;
+}
+
+export function emitEvent(
+  event: string,
+  payload: Record<string, unknown>,
+  sourceAppId: string,
+): void {
+  const bus = getEventBus();
+  const detail: VibeEventDetail = { payload, sourceAppId };
+  bus.dispatchEvent(
+    new CustomEvent(prefixedEventName(event), { detail }),
+  );
+}
+
+export function onEvent(
+  event: string,
+  handler: (detail: VibeEventDetail) => void,
+): () => void {
+  const bus = getEventBus();
+  const prefixed = prefixedEventName(event);
+  const listener = (e: Event) => {
+    handler((e as CustomEvent<VibeEventDetail>).detail);
+  };
+  bus.addEventListener(prefixed, listener);
+  return () => bus.removeEventListener(prefixed, listener);
+}
+
+export function onceEvent(
+  event: string,
+  handler: (detail: VibeEventDetail) => void,
+): () => void {
+  const bus = getEventBus();
+  const prefixed = prefixedEventName(event);
+  const listener = (e: Event) => {
+    handler((e as CustomEvent<VibeEventDetail>).detail);
+  };
+  bus.addEventListener(prefixed, listener, { once: true });
+  return () => bus.removeEventListener(prefixed, listener);
+}

package/src/core/loader.ts

@@ -0,0 +1,57 @@
+const loadedScripts = new Set<string>();
+
+const ALLOWED_PROTOCOLS = new Set(["https:", "http:"]);
+
+function validateScriptSrc(src: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(src, window.location.href);
+  } catch {
+    return `Invalid vibe app script URL: ${src}`;
+  }
+
+  if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
+    return `Refused to load vibe app script with disallowed protocol "${url.protocol}": ${src}`;
+  }
+
+  return null;
+}
+
+export function loadScript(src: string): Promise<void> {
+  const validationError = validateScriptSrc(src);
+  if (validationError) {
+    return Promise.reject(new Error(validationError));
+  }
+
+  if (loadedScripts.has(src)) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve, reject) => {
+    const existing = document.querySelector(`script[src="${CSS.escape(src)}"]`);
+    if (existing) {
+      loadedScripts.add(src);
+      resolve();
+      return;
+    }
+
+    const script = document.createElement("script");
+    script.type = "module";
+    script.src = src;
+    script.onload = () => {
+      loadedScripts.add(src);
+      resolve();
+    };
+    script.onerror = () => {
+      reject(new Error(`Failed to load vibe app script: ${src}`));
+    };
+    document.head.appendChild(script);
+  });
+}
+
+export function waitForElement(tagName: string): Promise<void> {
+  if (customElements.get(tagName)) {
+    return Promise.resolve();
+  }
+  return customElements.whenDefined(tagName).then(() => undefined);
+}

package/src/core/permissions.ts

@@ -0,0 +1,41 @@
+import type { Bridge, BridgeCapability } from "@aiworkbench/vibe-types";
+
+function createDeniedProxy(capability: string): unknown {
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (typeof prop === "symbol") return undefined;
+        throw new Error(
+          `Access denied: ${capability}.${prop} is not permitted. Add '${capability}' to your manifest.json permissions.`,
+        );
+      },
+    },
+  );
+}
+
+export function filterByPermissions(
+  bridge: Bridge,
+  permissions: BridgeCapability[],
+): Bridge {
+  const allCapabilities: BridgeCapability[] = [
+    "auth",
+    "api",
+    "navigation",
+    "theme",
+    "toast",
+    "storage",
+    "events",
+  ];
+
+  const filtered = {} as Record<string, unknown>;
+  for (const cap of allCapabilities) {
+    if (permissions.includes(cap)) {
+      filtered[cap] = bridge[cap];
+    } else {
+      filtered[cap] = createDeniedProxy(cap);
+    }
+  }
+
+  return filtered as unknown as Bridge;
+}

package/src/core/types.ts

@@ -0,0 +1,54 @@
+import type {
+  Bridge,
+  VibeManifest,
+  AuthBridge,
+  ApiBridge,
+  NavigationBridge,
+  ThemeBridge,
+  ToastBridge,
+  StorageBridge,
+  EventsBridge,
+} from "@aiworkbench/vibe-types";
+import type { ReactNode, CSSProperties } from "react";
+
+export interface VibeHostProps {
+  /** The mini-app manifest describing its id, permissions, etc. */
+  manifest: VibeManifest;
+  /** URL to the built JS bundle for the mini-app. */
+  src: string;
+  /** Shown while the script loads and custom element registers. */
+  fallback?: ReactNode;
+  /** Shown when the script fails to load or the element fails to mount. */
+  errorFallback?: (error: Error) => ReactNode;
+  /** Optional overrides per capability adapter. */
+  adapters?: Partial<AdapterOverrides>;
+  /** Fires when the custom element is mounted and bridge is injected. */
+  onReady?: () => void;
+  /** Fires on load or mount failure. */
+  onError?: (error: Error) => void;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export interface AdapterOverrides {
+  auth: AuthBridge;
+  api: ApiBridge;
+  navigation: NavigationBridge;
+  theme: ThemeBridge;
+  toast: ToastBridge;
+  storage: StorageBridge;
+  events: EventsBridge;
+}
+
+export type LoaderStatus = "loading" | "ready" | "error";
+
+export interface UseVibeLoaderResult {
+  status: LoaderStatus;
+  error: Error | null;
+}
+
+export interface UseVibeBridgeOptions {
+  appId: string;
+  permissions: Bridge extends infer B ? (keyof B)[] : never;
+  overrides?: Partial<AdapterOverrides>;
+}

package/src/hooks/useVibeBridge.ts

@@ -0,0 +1,49 @@
+import { useMemo } from "react";
+import type { Bridge, BridgeCapability } from "@aiworkbench/vibe-types";
+import { useSession } from "next-auth/react";
+import { useRouter } from "next/navigation";
+import { toast } from "sonner";
+import { createAuthAdapter } from "../adapters/auth";
+import { createApiAdapter } from "../adapters/api";
+import { createNavigationAdapter } from "../adapters/navigation";
+import { createThemeAdapter } from "../adapters/theme";
+import { createToastAdapter } from "../adapters/toast";
+import { createStorageAdapter } from "../adapters/storage";
+import { createEventsAdapter } from "../adapters/events";
+import { filterByPermissions } from "../core/permissions";
+import type { AdapterOverrides } from "../core/types";
+
+export interface UseVibeBridgeOptions {
+  appId: string;
+  permissions: BridgeCapability[];
+  overrides?: Partial<AdapterOverrides>;
+}
+
+export function useVibeBridge(options: UseVibeBridgeOptions): Bridge {
+  const { appId, permissions, overrides } = options;
+  const { data: session } = useSession();
+  const router = useRouter();
+
+  return useMemo(() => {
+    const authAdapter =
+      overrides?.auth ?? createAuthAdapter({ session: session ?? null });
+
+    const fullBridge: Bridge = {
+      auth: authAdapter,
+      api:
+        overrides?.api ??
+        createApiAdapter({ getToken: () => authAdapter.getToken() }),
+      navigation:
+        overrides?.navigation ??
+        createNavigationAdapter({ push: (path) => router.push(path) }),
+      theme: overrides?.theme ?? createThemeAdapter(),
+      toast:
+        overrides?.toast ??
+        createToastAdapter({ toast }),
+      storage: overrides?.storage ?? createStorageAdapter(appId),
+      events: overrides?.events ?? createEventsAdapter(appId),
+    };
+
+    return filterByPermissions(fullBridge, permissions);
+  }, [session, router, appId, permissions, overrides]);
+}

package/src/hooks/useVibeEvents.ts

@@ -0,0 +1,13 @@
+import { useEffect } from "react";
+import { onEvent, type VibeEventDetail } from "../core/event-bus";
+
+export function useVibeEvents(
+  event: string,
+  handler: (payload: Record<string, unknown>, sourceAppId: string) => void,
+): void {
+  useEffect(() => {
+    return onEvent(event, (detail: VibeEventDetail) => {
+      handler(detail.payload, detail.sourceAppId);
+    });
+  }, [event, handler]);
+}

package/src/hooks/useVibeLoader.ts

@@ -0,0 +1,42 @@
+import { useState, useEffect } from "react";
+import { loadScript, waitForElement } from "../core/loader";
+import type { LoaderStatus, UseVibeLoaderResult } from "../core/types";
+
+export function useVibeLoader(
+  src: string,
+  tagName: string,
+): UseVibeLoaderResult {
+  const [status, setStatus] = useState<LoaderStatus>("loading");
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    setStatus("loading");
+    setError(null);
+
+    loadScript(src)
+      .then(() => waitForElement(tagName))
+      .then(() => {
+        if (!cancelled) {
+          setStatus("ready");
+        }
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          const e =
+            err instanceof Error
+              ? err
+              : new Error(`Failed to load vibe app: ${tagName}`);
+          setError(e);
+          setStatus("error");
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [src, tagName]);
+
+  return { status, error };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// Components
+export { VibeHost } from "./components/VibeHost";
+export { VibeErrorBoundary } from "./components/VibeErrorBoundary";
+
+// Hooks
+export { useVibeBridge } from "./hooks/useVibeBridge";
+export { useVibeLoader } from "./hooks/useVibeLoader";
+export { useVibeEvents } from "./hooks/useVibeEvents";
+
+// Adapter factories
+export { createAuthAdapter } from "./adapters/auth";
+export { createApiAdapter } from "./adapters/api";
+export { createNavigationAdapter } from "./adapters/navigation";
+export { createThemeAdapter } from "./adapters/theme";
+export { createToastAdapter } from "./adapters/toast";
+export { createStorageAdapter } from "./adapters/storage";
+export { createEventsAdapter } from "./adapters/events";
+
+// Core utilities
+export { filterByPermissions } from "./core/permissions";
+export { getEventBus, emitEvent } from "./core/event-bus";
+
+// Types
+export type {
+  VibeHostProps,
+  AdapterOverrides,
+  LoaderStatus,
+  UseVibeLoaderResult,
+} from "./core/types";
+export type { AuthAdapterDeps } from "./adapters/auth";
+export type { ApiAdapterDeps } from "./adapters/api";
+export type { NavigationAdapterDeps } from "./adapters/navigation";
+export type { ToastAdapterDeps } from "./adapters/toast";