@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/collab-ui/RecentEditHighlights.tsx

@@ -0,0 +1,239 @@
+/**
+ * RecentEditHighlights — lingering, fading highlights over regions another
+ * participant (human or agent) just edited, with their name/avatar flag.
+ *
+ * The Google-Docs/Figma feel: when a collaborator or the AI edits something,
+ * the changed region glows in their color and the flag identifies them; the
+ * highlight fades out over the last portion of its lifetime instead of
+ * vanishing.
+ *
+ * Feed it `useRecentEdits(others)` (which reads participants' `recentEdits`
+ * awareness rings) and a `resolveRect` that maps an edit descriptor to a
+ * viewport DOMRect for your surface:
+ *
+ *   const others = usePresence(awareness, ydoc?.clientID).others;
+ *   const edits = useRecentEdits(others);
+ *   <RecentEditHighlights
+ *     edits={edits}
+ *     resolveRect={(edit) =>
+ *       edit.descriptor.kind === "selector"
+ *         ? container.querySelector(edit.descriptor.selector)?.getBoundingClientRect() ?? null
+ *         : null
+ *     }
+ *     containerRef={containerRef}
+ *   />
+ */
+
+import {
+  memo,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
+
+import { RECENT_EDIT_TTL_MS, type AttributedRecentEdit } from "./types.js";
+
+export interface RecentEditHighlightsProps {
+  /** Attributed recent edits (from `useRecentEdits`). */
+  edits: AttributedRecentEdit[];
+  /**
+   * Resolver: maps an edit to a viewport-relative DOMRect, or null when the
+   * region can't be located (the edit is skipped).
+   */
+  resolveRect: (edit: AttributedRecentEdit) => DOMRect | null;
+  /** Container the highlights are positioned within (position: relative). */
+  containerRef: RefObject<HTMLElement | null>;
+  /** Highlight lifetime; should match useRecentEdits ttlMs. Default 6000. */
+  ttlMs?: number;
+  /** Render the compact outline treatment used by the Slides editor. */
+  outlineOnly?: boolean;
+  /** Additional CSS class for the overlay div. */
+  className?: string;
+}
+
+interface Highlight {
+  key: string;
+  color: string;
+  label: string;
+  avatarUrl?: string;
+  isAgent: boolean;
+  outlineOnly: boolean;
+  opacity: number;
+  rect: { top: number; left: number; width: number; height: number };
+}
+
+const HighlightItem = memo(function HighlightItem({ h }: { h: Highlight }) {
+  return (
+    <div
+      aria-label={
+        h.isAgent && h.outlineOnly ? h.label : `${h.label} edited this`
+      }
+      style={{
+        position: "absolute",
+        top: h.rect.top,
+        left: h.rect.left,
+        width: h.rect.width,
+        height: h.rect.height,
+        borderRadius: 4,
+        pointerEvents: "none",
+        zIndex: 9997,
+        opacity: h.opacity,
+        transition: "opacity 400ms ease-out",
+        outline: `2px solid ${h.color}`,
+        outlineOffset: 2,
+        ...(h.outlineOnly
+          ? {}
+          : {
+              backgroundColor: `${h.color}1A`,
+              boxShadow: `0 0 0 1px ${h.color}33, 0 0 12px ${h.color}40`,
+            }),
+      }}
+    >
+      <div
+        style={{
+          position: "absolute",
+          top: -22,
+          left: 0,
+          display: "flex",
+          alignItems: "center",
+          gap: 4,
+          backgroundColor: h.outlineOnly ? "transparent" : h.color,
+          border: h.outlineOnly ? `1px solid ${h.color}` : undefined,
+          color: h.outlineOnly ? h.color : "hsl(var(--background))",
+          fontSize: 10,
+          fontWeight: 600,
+          padding: "2px 6px",
+          borderRadius: 3,
+          whiteSpace: "nowrap",
+          maxWidth: 180,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        }}
+      >
+        {h.avatarUrl ? (
+          <img
+            src={h.avatarUrl}
+            alt=""
+            style={{
+              width: 12,
+              height: 12,
+              borderRadius: "50%",
+              flexShrink: 0,
+            }}
+          />
+        ) : null}
+        {h.label}
+      </div>
+    </div>
+  );
+});
+
+export function RecentEditHighlights({
+  edits,
+  resolveRect,
+  containerRef,
+  ttlMs = RECENT_EDIT_TTL_MS,
+  outlineOnly = false,
+  className,
+}: RecentEditHighlightsProps) {
+  const [highlights, setHighlights] = useState<Highlight[]>([]);
+  const editsRef = useRef(edits);
+  editsRef.current = edits;
+  const resolveRef = useRef(resolveRect);
+  resolveRef.current = resolveRect;
+
+  const recompute = () => {
+    const container = containerRef.current;
+    if (!container) {
+      setHighlights([]);
+      return;
+    }
+    const containerRect = container.getBoundingClientRect();
+    const now = Date.now();
+    const next: Highlight[] = [];
+
+    for (const edit of editsRef.current) {
+      const domRect = resolveRef.current(edit);
+      if (!domRect) continue;
+
+      const top = domRect.top - containerRect.top;
+      const left = domRect.left - containerRect.left;
+      if (
+        left + domRect.width < 0 ||
+        top + domRect.height < 0 ||
+        left > containerRect.width ||
+        top > containerRect.height
+      ) {
+        continue;
+      }
+
+      // Fade over the final 40% of the lifetime.
+      const age = now - edit.at;
+      const fadeStart = ttlMs * 0.6;
+      const opacity =
+        age <= fadeStart
+          ? 1
+          : Math.max(0, 1 - (age - fadeStart) / (ttlMs - fadeStart));
+
+      next.push({
+        key: `${edit.clientId}:${edit.at}`,
+        color: edit.user.color || "#94a3b8",
+        label: edit.isAgent
+          ? outlineOnly
+            ? "AI editing"
+            : edit.label
+              ? `AI — ${edit.label}`
+              : "AI edited"
+          : edit.label
+            ? `${edit.user.name} — ${edit.label}`
+            : edit.user.name,
+        avatarUrl: (edit.user as { avatarUrl?: string }).avatarUrl,
+        isAgent: edit.isAgent,
+        outlineOnly,
+        opacity,
+        rect: { top, left, width: domRect.width, height: domRect.height },
+      });
+    }
+
+    setHighlights(next);
+  };
+
+  useLayoutEffect(() => {
+    recompute();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [edits, ttlMs]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const observer = new ResizeObserver(() => recompute());
+    observer.observe(container);
+    container.addEventListener("scroll", recompute, { passive: true });
+    window.addEventListener("scroll", recompute, { passive: true });
+    return () => {
+      observer.disconnect();
+      container.removeEventListener("scroll", recompute);
+      window.removeEventListener("scroll", recompute);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [containerRef]);
+
+  return (
+    <div
+      aria-hidden
+      style={{
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "hidden",
+      }}
+      className={className}
+    >
+      {highlights.map((h) => (
+        <HighlightItem key={h.key} h={h} />
+      ))}
+    </div>
+  );
+}

package/src/collab-ui/RemoteSelectionRings.tsx

@@ -0,0 +1,227 @@
+/**
+ * RemoteSelectionRings — renders colored outline rings + name tags over
+ * elements selected by remote participants.
+ *
+ * Each participant's presence payload may contain a `selection` key with an
+ * opaque descriptor (e.g. a CSS selector). The `resolveRect` callback maps
+ * a descriptor to a DOMRect (or null when the element isn't found). Rings
+ * are rendered as absolutely-positioned outlines anchored to the container.
+ *
+ * Usage:
+ *   <div style={{ position: "relative" }}>
+ *     {content}
+ *     <RemoteSelectionRings
+ *       others={others}
+ *       resolveRect={(selector) => document.querySelector(selector)?.getBoundingClientRect() ?? null}
+ *       containerRef={containerRef}
+ *     />
+ *   </div>
+ */
+
+import {
+  useState,
+  useEffect,
+  useRef,
+  useLayoutEffect,
+  memo,
+  type RefObject,
+} from "react";
+
+import type { OtherPresence } from "./types.js";
+
+/**
+ * Selection descriptors may be a plain string (treated as the resolver
+ * input) or an object carrying a resolver input plus a human label
+ * ("Editing hero section").
+ */
+export type SelectionDescriptor = string | { selector: string; label?: string };
+
+export interface RemoteSelectionRingsProps {
+  /** Remote participants. */
+  others: OtherPresence[];
+  /**
+   * Key inside presence payload that carries the selection descriptor.
+   * Default: "selection"
+   */
+  selectionKey?: string;
+  /**
+   * Resolver: maps a selection descriptor to a DOMRect relative to the
+   * viewport. Return null when the element is not found.
+   */
+  resolveRect: (descriptor: string) => DOMRect | null;
+  /**
+   * Container element ref. Rings are positioned relative to this element's
+   * bounding box.
+   */
+  containerRef: RefObject<HTMLElement | null>;
+  /** Additional CSS class for the overlay div. */
+  className?: string;
+}
+
+interface Ring {
+  clientId: number;
+  color: string;
+  label: string;
+  avatarUrl?: string;
+  isAgent: boolean;
+  rect: { top: number; left: number; width: number; height: number };
+}
+
+const RingItem = memo(function RingItem({ ring }: { ring: Ring }) {
+  return (
+    <div
+      aria-label={`${ring.label} selection`}
+      style={{
+        position: "absolute",
+        top: ring.rect.top,
+        left: ring.rect.left,
+        width: ring.rect.width,
+        height: ring.rect.height,
+        outline: `2px solid ${ring.color}`,
+        outlineOffset: 2,
+        borderRadius: 3,
+        pointerEvents: "none",
+        boxShadow: `0 0 0 1px ${ring.color}40`,
+        zIndex: 9998,
+      }}
+    >
+      {/* Name tag in top-left corner of the ring */}
+      <div
+        style={{
+          position: "absolute",
+          top: -20,
+          left: 0,
+          display: "flex",
+          alignItems: "center",
+          gap: 4,
+          backgroundColor: ring.color,
+          color: "#fff",
+          fontSize: 10,
+          fontWeight: 600,
+          padding: "1px 5px",
+          borderRadius: 3,
+          whiteSpace: "nowrap",
+          maxWidth: 160,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        }}
+      >
+        {ring.avatarUrl ? (
+          <img
+            src={ring.avatarUrl}
+            alt=""
+            style={{
+              width: 12,
+              height: 12,
+              borderRadius: "50%",
+              flexShrink: 0,
+            }}
+          />
+        ) : null}
+        {ring.label}
+      </div>
+    </div>
+  );
+});
+
+export function RemoteSelectionRings({
+  others,
+  selectionKey = "selection",
+  resolveRect,
+  containerRef,
+  className,
+}: RemoteSelectionRingsProps) {
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const [rings, setRings] = useState<Ring[]>([]);
+
+  // Recompute rings whenever others change or on animation frame.
+  const recompute = () => {
+    const container = containerRef.current;
+    if (!container) {
+      setRings([]);
+      return;
+    }
+    const containerRect = container.getBoundingClientRect();
+    const next: Ring[] = [];
+
+    for (const other of others) {
+      const raw = other.presence[selectionKey] as
+        | SelectionDescriptor
+        | null
+        | undefined;
+      const selector =
+        typeof raw === "string" ? raw : raw ? raw.selector : undefined;
+      if (!selector || typeof selector !== "string") continue;
+      const selectionLabel =
+        raw && typeof raw === "object" ? raw.label : undefined;
+
+      const domRect = resolveRect(selector);
+      if (!domRect) continue;
+
+      // Convert viewport-relative rect to container-relative.
+      const top = domRect.top - containerRect.top;
+      const left = domRect.left - containerRect.left;
+      if (
+        left + domRect.width < 0 ||
+        top + domRect.height < 0 ||
+        left > containerRect.width ||
+        top > containerRect.height
+      ) {
+        continue; // Out of container bounds — skip.
+      }
+
+      const baseName = other.isAgent
+        ? "AI"
+        : other.user.name || other.user.email;
+      next.push({
+        clientId: other.clientId,
+        color: other.user.color || "#94a3b8",
+        label: selectionLabel ? `${baseName} — ${selectionLabel}` : baseName,
+        avatarUrl: (other.user as { avatarUrl?: string }).avatarUrl,
+        isAgent: other.isAgent,
+        rect: { top, left, width: domRect.width, height: domRect.height },
+      });
+    }
+
+    setRings(next);
+  };
+
+  // Recompute on scroll/resize of the container to keep rings in sync.
+  useLayoutEffect(() => {
+    recompute();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [others, selectionKey]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const observer = new ResizeObserver(() => recompute());
+    observer.observe(container);
+    container.addEventListener("scroll", recompute, { passive: true });
+    window.addEventListener("scroll", recompute, { passive: true });
+    return () => {
+      observer.disconnect();
+      container.removeEventListener("scroll", recompute);
+      window.removeEventListener("scroll", recompute);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [containerRef]);
+
+  return (
+    <div
+      ref={overlayRef}
+      aria-hidden
+      style={{
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "hidden",
+      }}
+      className={className}
+    >
+      {rings.map((ring) => (
+        <RingItem key={ring.clientId} ring={ring} />
+      ))}
+    </div>
+  );
+}

package/src/collab-ui/agent-identity.ts

@@ -0,0 +1,16 @@
+// Reserve the maximum signed 32-bit id so the agent never wins client leader election.
+export const AGENT_CLIENT_ID = 2147483647;
+
+export interface AgentIdentity {
+  clientId: number;
+  name: string;
+  email: string;
+  color: string;
+}
+
+export const DEFAULT_AGENT_IDENTITY: AgentIdentity = {
+  clientId: AGENT_CLIENT_ID,
+  name: "AI Assistant",
+  email: "agent@system",
+  color: "#00B5FF",
+};

package/src/collab-ui/index.ts

@@ -0,0 +1,39 @@
+export {
+  AgentPresenceChip,
+  type AgentPresenceChipProps,
+} from "./AgentPresenceChip.js";
+export {
+  AGENT_CLIENT_ID,
+  DEFAULT_AGENT_IDENTITY,
+  type AgentIdentity,
+} from "./agent-identity.js";
+export {
+  LiveCursorOverlay,
+  type CursorMapFn,
+  type LiveCursorOverlayProps,
+} from "./LiveCursorOverlay.js";
+export { PresenceBar, type PresenceBarProps } from "./PresenceBar.js";
+export { isReconcileLeadClient } from "./lead-client.js";
+export {
+  RecentEditHighlights,
+  type RecentEditHighlightsProps,
+} from "./RecentEditHighlights.js";
+export {
+  RemoteSelectionRings,
+  type RemoteSelectionRingsProps,
+  type SelectionDescriptor,
+} from "./RemoteSelectionRings.js";
+export {
+  RECENT_EDITS_MAX,
+  RECENT_EDIT_TTL_MS,
+  dedupeCollabUsersByEmail,
+  emailToColor,
+  emailToName,
+  type AttributedRecentEdit,
+  type CollabUser,
+  type NormalizedPoint,
+  type OtherPresence,
+  type PresencePayload,
+  type RecentEdit,
+  type RecentEditDescriptor,
+} from "./types.js";

package/src/collab-ui/lead-client.ts

@@ -0,0 +1,32 @@
+import type { Awareness } from "y-protocols/awareness";
+
+import { AGENT_CLIENT_ID } from "./agent-identity.js";
+
+// Exactly one visible non-agent client may apply an external snapshot; allowing
+// every client to reconcile it duplicates concurrent CRDT inserts.
+export function isReconcileLeadClient(
+  awareness: Awareness | null | undefined,
+  localClientId: number | null | undefined,
+): boolean {
+  if (localClientId == null) return false;
+  if (!awareness) return true;
+
+  let hasPeer = false;
+  let minVisible = localClientId;
+  awareness.getStates().forEach((state, clientId) => {
+    if (clientId === AGENT_CLIENT_ID || clientId === localClientId) return;
+    const candidate = state as { user?: unknown; visible?: boolean };
+    if (!candidate?.user) return;
+    hasPeer = true;
+    if (candidate.visible !== false && clientId < minVisible) {
+      minVisible = clientId;
+    }
+  });
+
+  if (!hasPeer) return true;
+
+  const localHidden =
+    typeof document !== "undefined" && document.visibilityState === "hidden";
+  if (localHidden) return false;
+  return localClientId <= minVisible;
+}

package/src/collab-ui/types.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+
+import { dedupeCollabUsersByEmail } from "./types.js";
+
+describe("dedupeCollabUsersByEmail", () => {
+  it("ignores malformed awareness user payloads", () => {
+    expect(
+      dedupeCollabUsersByEmail([
+        {
+          name: "Broken",
+          email: undefined as unknown as string,
+          color: "#fff",
+        },
+        { name: "Real", email: "real@example.com", color: "#000" },
+      ]),
+    ).toEqual([{ name: "Real", email: "real@example.com", color: "#000" }]);
+  });
+});

package/src/collab-ui/types.ts

@@ -0,0 +1,96 @@
+export interface CollabUser {
+  name: string;
+  email: string;
+  color: string;
+  avatarUrl?: string;
+}
+
+export type PresencePayload = Record<string, unknown>;
+
+export interface OtherPresence {
+  clientId: number;
+  user: CollabUser;
+  presence: PresencePayload;
+  isAgent: boolean;
+}
+
+export interface NormalizedPoint {
+  x: number;
+  y: number;
+}
+
+export type RecentEditDescriptor =
+  | { kind: "text"; quote: string }
+  | { kind: "selector"; selector: string }
+  | { kind: "paths"; paths: string[] }
+  | { kind: "doc" }
+  | { kind: string; [key: string]: unknown };
+
+export interface RecentEdit {
+  descriptor: RecentEditDescriptor;
+  label?: string;
+  at: number;
+}
+
+export interface AttributedRecentEdit extends RecentEdit {
+  clientId: number;
+  user: OtherPresence["user"];
+  isAgent: boolean;
+}
+
+export const RECENT_EDITS_MAX = 5;
+export const RECENT_EDIT_TTL_MS = 10_000;
+
+const CURSOR_COLORS = [
+  "#f87171",
+  "#fb923c",
+  "#fbbf24",
+  "#a3e635",
+  "#34d399",
+  "#22d3ee",
+  "#60a5fa",
+  "#14b8a6",
+  "#f472b6",
+  "#e879f9",
+];
+
+export function emailToColor(email: string): string {
+  let hash = 0;
+  for (let i = 0; i < email.length; i++) {
+    hash = ((hash << 5) - hash + email.charCodeAt(i)) | 0;
+  }
+  return CURSOR_COLORS[Math.abs(hash) % CURSOR_COLORS.length];
+}
+
+export function emailToName(email: string): string {
+  const local = email.split("@")[0] || email;
+  return local.charAt(0).toUpperCase() + local.slice(1);
+}
+
+function normalizeCollabEmail(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+export function dedupeCollabUsersByEmail(users: CollabUser[]): CollabUser[] {
+  const byEmail = new Map<string, CollabUser>();
+  for (const user of users) {
+    // Awareness is a network boundary. Older clients or partially-written
+    // states can contain a malformed user payload; ignore it instead of
+    // letting a missing email reach normalizeCollabEmail().
+    if (!user || typeof user.email !== "string") continue;
+    const email = normalizeCollabEmail(user.email);
+    if (!email || byEmail.has(email)) continue;
+    byEmail.set(email, {
+      name:
+        typeof user.name === "string" && user.name.trim()
+          ? user.name
+          : emailToName(email),
+      email,
+      color:
+        typeof user.color === "string" && user.color.trim()
+          ? user.color
+          : emailToColor(email),
+    });
+  }
+  return Array.from(byEmail.values());
+}