@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/collab-ui/LiveCursorOverlay.tsx

@@ -0,0 +1,241 @@
+/**
+ * LiveCursorOverlay — renders remote users' cursors over an absolutely-
+ * positioned container.
+ *
+ * Cursor positions are expected as normalized coordinates (0–1 relative to
+ * the container's content size) so different zoom/scroll positions map
+ * correctly. Pass a `mapCoords` prop to handle non-identity transforms
+ * (e.g. a zoomed canvas).
+ *
+ * The agent uses the same pointer shape with an "AI" label.
+ *
+ * Cursors fade out after 10 seconds of no movement.
+ */
+
+import { useState, useEffect, useRef, memo, type RefObject } from "react";
+
+import type { OtherPresence, NormalizedPoint } from "./types.js";
+
+export interface CursorMapFn {
+  /** Convert normalized coords to pixel offsets within the overlay container. */
+  (norm: NormalizedPoint): { x: number; y: number };
+}
+
+export interface LiveCursorOverlayProps {
+  /** Remote participants with presence payload. */
+  others: OtherPresence[];
+  /**
+   * Key inside presence payload that carries the cursor position.
+   * Default: "cursor"
+   * Expected shape: { x: number; y: number } (normalized 0–1).
+   */
+  cursorKey?: string;
+  /**
+   * Override coordinate mapping. Default: scale by container clientWidth/Height.
+   * Pass this when the container uses transform: scale() or has virtual scroll.
+   */
+  mapCoords?: CursorMapFn;
+  /**
+   * Container element ref. Required when mapCoords is not provided —
+   * used to compute pixel positions from normalized coords.
+   */
+  containerRef?: RefObject<HTMLElement | null>;
+  /** Additional CSS class for the overlay div. */
+  className?: string;
+}
+
+const STALE_MS = 10_000; // Fade out cursors older than 10s
+
+function CursorPointer({ color }: { color: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="25"
+      height="29"
+      viewBox="0 0 25 29"
+      fill="none"
+      aria-hidden
+      style={{
+        display: "block",
+        filter: "drop-shadow(0 2px 3px rgba(15, 23, 42, 0.3))",
+      }}
+    >
+      <path
+        d="M2.5 2.5L21.5 11L12.6 14.1L8.3 24.5L2.5 2.5Z"
+        fill={color}
+        stroke="white"
+        strokeLinejoin="round"
+        strokeWidth="3"
+      />
+    </svg>
+  );
+}
+
+interface CursorEntry {
+  other: OtherPresence;
+  x: number;
+  y: number;
+  lastSeen: number;
+}
+
+const CursorLabel = memo(function CursorLabel({
+  entry,
+}: {
+  entry: CursorEntry;
+}) {
+  const { other, x, y } = entry;
+  const color = other.user.color || "#94a3b8";
+  const label = other.isAgent ? "AI" : other.user.name || other.user.email;
+
+  return (
+    <div
+      aria-label={`${label} cursor`}
+      style={{
+        position: "absolute",
+        left: 0,
+        top: 0,
+        pointerEvents: "none",
+        userSelect: "none",
+        transform: `translate3d(${x - 2}px, ${y - 2}px, 0)`,
+        zIndex: 9999,
+        transition: "transform 80ms linear",
+        willChange: "transform",
+        width: 0,
+        height: 0,
+      }}
+    >
+      <CursorPointer color={color} />
+      <div
+        style={{
+          position: "absolute",
+          left: 31,
+          top: 31,
+          display: "flex",
+          alignItems: "center",
+          gap: 5,
+          backgroundColor: color,
+          color: "#fff",
+          fontSize: 12,
+          fontWeight: 500,
+          lineHeight: "16px",
+          padding: "2px 7px",
+          borderRadius: 2,
+          whiteSpace: "nowrap",
+          boxShadow: "0 5px 12px rgba(15, 23, 42, 0.16)",
+          maxWidth: 150,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        }}
+      >
+        {(other.user as { avatarUrl?: string }).avatarUrl ? (
+          <img
+            src={(other.user as { avatarUrl?: string }).avatarUrl}
+            alt=""
+            style={{
+              width: 14,
+              height: 14,
+              borderRadius: "50%",
+              flexShrink: 0,
+            }}
+          />
+        ) : null}
+        {label}
+      </div>
+    </div>
+  );
+});
+
+export function LiveCursorOverlay({
+  others,
+  cursorKey = "cursor",
+  mapCoords,
+  containerRef,
+  className,
+}: LiveCursorOverlayProps) {
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const [, tick] = useState(0); // Force re-render to prune stale cursors
+  const entriesRef = useRef<Map<number, CursorEntry>>(new Map());
+
+  // Tick every 5s to prune stale cursors (no re-render storm).
+  useEffect(() => {
+    const id = setInterval(() => tick((n) => n + 1), 5_000);
+    return () => clearInterval(id);
+  }, []);
+
+  // Build entries from others, computing pixel positions.
+  const now = Date.now();
+  const visible: CursorEntry[] = [];
+
+  for (const other of others) {
+    const pos = other.presence[cursorKey] as NormalizedPoint | undefined;
+    if (!pos || typeof pos.x !== "number" || typeof pos.y !== "number")
+      continue;
+
+    // Compute pixel position.
+    let px: number;
+    let py: number;
+    if (mapCoords) {
+      const mapped = mapCoords(pos);
+      px = mapped.x;
+      py = mapped.y;
+    } else {
+      const container =
+        containerRef?.current ?? overlayRef.current?.parentElement;
+      const w = container ? container.clientWidth : 0;
+      const h = container ? container.clientHeight : 0;
+      px = pos.x * w;
+      py = pos.y * h;
+    }
+
+    const prev = entriesRef.current.get(other.clientId);
+    const lastSeen =
+      prev && prev.x === px && prev.y === py ? prev.lastSeen : now;
+    const entry: CursorEntry = { other, x: px, y: py, lastSeen };
+    entriesRef.current.set(other.clientId, entry);
+
+    if (now - lastSeen < STALE_MS) {
+      visible.push(entry);
+    }
+  }
+
+  // Remove entries for participants who left.
+  for (const clientId of entriesRef.current.keys()) {
+    if (!others.find((o) => o.clientId === clientId)) {
+      entriesRef.current.delete(clientId);
+    }
+  }
+
+  if (visible.length === 0) {
+    return (
+      <div
+        ref={overlayRef}
+        aria-hidden
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+          overflow: "hidden",
+        }}
+        className={className}
+      />
+    );
+  }
+
+  return (
+    <div
+      ref={overlayRef}
+      aria-hidden
+      style={{
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "hidden",
+      }}
+      className={className}
+    >
+      {visible.map((entry) => (
+        <CursorLabel key={entry.other.clientId} entry={entry} />
+      ))}
+    </div>
+  );
+}

package/src/collab-ui/PresenceBar.spec.tsx

@@ -0,0 +1,44 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { PresenceBar } from "./PresenceBar.js";
+
+describe("PresenceBar", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("gives the integrated AI editing label space after the avatar", () => {
+    act(() => {
+      root.render(
+        <PresenceBar
+          activeUsers={[]}
+          agentPresent
+          agentActive
+          showAgentEditingDot={false}
+        />,
+      );
+    });
+
+    const label = Array.from(container.querySelectorAll("span")).find(
+      (element) => element.textContent === "AI editing",
+    );
+    expect(label?.style.padding).toBe("0px 0px 0px 2px");
+  });
+});

package/src/collab-ui/PresenceBar.tsx

@@ -0,0 +1,373 @@
+import { useMemo, type CSSProperties } from "react";
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "../ui/tooltip.js";
+import {
+  type CollabUser,
+  dedupeCollabUsersByEmail,
+  emailToColor,
+  emailToName,
+} from "./types.js";
+
+export interface PresenceBarProps {
+  /** Active collaborators on this document. */
+  activeUsers: CollabUser[];
+  /** Whether the agent has a durable presence entry. */
+  agentPresent?: boolean;
+  /** Whether the agent is actively making edits right now. */
+  agentActive?: boolean;
+  /** Whether to show the status dot beside the active agent label. When false,
+   *  the label is integrated with the avatar pill. */
+  showAgentEditingDot?: boolean;
+  /** Current user's email (to exclude from the list). */
+  currentUserEmail?: string;
+  /** Max visible avatars before "+N" overflow. Default: 5 */
+  maxVisible?: number;
+  /** Additional CSS classes. */
+  className?: string;
+  /**
+   * Called when an avatar is clicked. Receives the user being clicked
+   * (or null for the agent avatar). Use this to start/stop follow mode.
+   */
+  onAvatarClick?: (user: CollabUser | null) => void;
+  /**
+   * The email of the user currently being followed. Highlighted with a
+   * blue ring to indicate active follow mode.
+   */
+  followingEmail?: string | null;
+}
+
+const AVATAR_SIZE = 28;
+const OVERLAP = -8;
+const BORDER_WIDTH = 2;
+const FONT_SIZE = 12;
+const AGENT_COLOR = "#00B5FF";
+
+const baseAvatarStyle: CSSProperties = {
+  width: AVATAR_SIZE,
+  height: AVATAR_SIZE,
+  borderRadius: "50%",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  fontSize: FONT_SIZE,
+  fontWeight: 700,
+  color: "#fff",
+  border: `${BORDER_WIDTH}px solid #fff`,
+  flexShrink: 0,
+  position: "relative",
+  cursor: "default",
+  boxSizing: "border-box",
+};
+
+const containerStyle: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  flexDirection: "row",
+};
+
+const pulseKeyframes = `
+@keyframes _anPresencePulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.6; }
+}
+`;
+
+let styleInjected = false;
+
+function injectStyles() {
+  if (styleInjected || typeof document === "undefined") return;
+  const style = document.createElement("style");
+  style.textContent = pulseKeyframes;
+  document.head.appendChild(style);
+  styleInjected = true;
+}
+
+function UserAvatar({
+  user,
+  isFirst,
+  onClick,
+  isFollowing,
+}: {
+  user: CollabUser;
+  isFirst: boolean;
+  onClick?: () => void;
+  isFollowing?: boolean;
+}) {
+  const color = user.color || emailToColor(user.email);
+  const name = user.name || emailToName(user.email);
+  const initial = name.charAt(0).toUpperCase();
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <div
+          style={{
+            ...baseAvatarStyle,
+            backgroundColor: color,
+            marginLeft: isFirst ? 0 : OVERLAP,
+            cursor: onClick ? "pointer" : "default",
+            boxShadow: isFollowing
+              ? `0 0 0 2px #3b82f6, 0 0 0 4px #fff`
+              : `0 0 0 2px #fff`,
+          }}
+          aria-label={`${name} (${user.email})${isFollowing ? " — following" : ""}`}
+          tabIndex={onClick ? 0 : undefined}
+          role={onClick ? "button" : undefined}
+          onClick={onClick}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" || e.key === " ") onClick?.();
+          }}
+        >
+          {user.avatarUrl ? (
+            <img
+              src={user.avatarUrl}
+              alt=""
+              style={{
+                width: "100%",
+                height: "100%",
+                borderRadius: "50%",
+                objectFit: "cover",
+              }}
+            />
+          ) : (
+            initial
+          )}
+        </div>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">
+        {isFollowing
+          ? `Following ${name} — click to stop`
+          : onClick
+            ? `${name} — click to follow`
+            : user.email}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function AgentAvatar({
+  active,
+  onClick,
+  isFollowing,
+  showAgentEditingDot,
+}: {
+  active: boolean;
+  onClick?: () => void;
+  isFollowing?: boolean;
+  showAgentEditingDot: boolean;
+}) {
+  injectStyles();
+  const integratedEditingBadge = active && !isFollowing && !showAgentEditingDot;
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: 4,
+        ...(integratedEditingBadge && {
+          height: AVATAR_SIZE,
+          paddingRight: 8,
+          borderRadius: 9999,
+          backgroundColor: `${AGENT_COLOR}20`,
+        }),
+      }}
+    >
+      <div
+        style={{
+          ...baseAvatarStyle,
+          backgroundColor: AGENT_COLOR,
+          marginLeft: 0,
+          animation: active ? "_anPresencePulse 2s infinite" : undefined,
+          cursor: onClick ? "pointer" : "default",
+          boxShadow: isFollowing
+            ? `0 0 0 2px #3b82f6, 0 0 0 4px #fff`
+            : undefined,
+        }}
+        title={
+          isFollowing
+            ? "Following AI — click to stop"
+            : active
+              ? "AI is editing"
+              : "AI agent"
+        }
+        onClick={onClick}
+        tabIndex={onClick ? 0 : undefined}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") onClick?.();
+        }}
+        role={onClick ? "button" : undefined}
+      >
+        A
+      </div>
+      {active && !isFollowing && (
+        <AgentEditingChip
+          showDot={showAgentEditingDot}
+          integrated={integratedEditingBadge}
+        />
+      )}
+      {isFollowing && (
+        <span
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            height: 20,
+            padding: "0 8px",
+            borderRadius: 9999,
+            backgroundColor: `#3b82f620`,
+            color: "#3b82f6",
+            fontSize: 11,
+            fontWeight: 600,
+            whiteSpace: "nowrap",
+          }}
+        >
+          Following AI
+        </span>
+      )}
+    </div>
+  );
+}
+
+function AgentEditingChip({
+  showDot,
+  integrated,
+}: {
+  showDot: boolean;
+  integrated: boolean;
+}) {
+  return (
+    <span
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: showDot ? 4 : 0,
+        height: integrated ? "auto" : 20,
+        padding: integrated ? "0 0 0 2px" : "0 8px",
+        borderRadius: integrated ? 0 : 9999,
+        backgroundColor: integrated ? "transparent" : `${AGENT_COLOR}20`,
+        color: AGENT_COLOR,
+        fontSize: 11,
+        fontWeight: 600,
+        whiteSpace: "nowrap",
+      }}
+    >
+      {showDot && (
+        <span
+          style={{
+            width: 6,
+            height: 6,
+            borderRadius: "50%",
+            backgroundColor: AGENT_COLOR,
+            animation: "_anPresencePulse 2s infinite",
+            flexShrink: 0,
+          }}
+        />
+      )}
+      AI editing
+    </span>
+  );
+}
+
+function OverflowBadge({
+  count,
+  isFirst,
+}: {
+  count: number;
+  isFirst: boolean;
+}) {
+  return (
+    <div
+      style={{
+        ...baseAvatarStyle,
+        backgroundColor: "rgba(255,255,255,0.1)",
+        color: "rgba(255,255,255,0.5)",
+        marginLeft: isFirst ? 0 : OVERLAP,
+        fontSize: 10,
+      }}
+      title={`${count} more collaborator${count === 1 ? "" : "s"}`}
+    >
+      +{count}
+    </div>
+  );
+}
+
+export function PresenceBar({
+  activeUsers,
+  agentPresent,
+  agentActive,
+  showAgentEditingDot = true,
+  currentUserEmail,
+  maxVisible = 5,
+  className,
+  onAvatarClick,
+  followingEmail,
+}: PresenceBarProps) {
+  const { humanUsers, showAgent } = useMemo(() => {
+    const currentEmail = currentUserEmail?.trim().toLowerCase();
+    const uniqueUsers = dedupeCollabUsersByEmail(activeUsers);
+    const humans = uniqueUsers.filter((u) => {
+      const email = u.email.trim().toLowerCase();
+      return email !== currentEmail && email !== "agent@system";
+    });
+    const hasAgentUser = uniqueUsers.some(
+      (u) => u.email.trim().toLowerCase() === "agent@system",
+    );
+    return {
+      humanUsers: humans,
+      showAgent: agentPresent || agentActive || hasAgentUser,
+    };
+  }, [activeUsers, currentUserEmail, agentPresent, agentActive]);
+
+  const visibleUsers = humanUsers.slice(0, maxVisible);
+  const overflowCount = humanUsers.length - visibleUsers.length;
+
+  if (!showAgent && humanUsers.length === 0) return null;
+
+  const followingLower = followingEmail?.trim().toLowerCase() ?? null;
+  const isFollowingAgent = followingLower === "agent@system";
+
+  return (
+    <TooltipProvider delayDuration={150}>
+      <div style={containerStyle} className={className}>
+        {showAgent && (
+          <AgentAvatar
+            active={!!agentActive}
+            onClick={onAvatarClick ? () => onAvatarClick(null) : undefined}
+            isFollowing={isFollowingAgent}
+            showAgentEditingDot={showAgentEditingDot}
+          />
+        )}
+        {visibleUsers.length > 0 && (
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              marginLeft: showAgent ? 6 : 0,
+            }}
+          >
+            {visibleUsers.map((u, i) => (
+              <UserAvatar
+                key={u.email}
+                user={u}
+                isFirst={i === 0}
+                onClick={onAvatarClick ? () => onAvatarClick(u) : undefined}
+                isFollowing={
+                  followingLower != null &&
+                  u.email.trim().toLowerCase() === followingLower
+                }
+              />
+            ))}
+            {overflowCount > 0 && (
+              <OverflowBadge count={overflowCount} isFirst={false} />
+            )}
+          </div>
+        )}
+      </div>
+    </TooltipProvider>
+  );
+}