@agent-native/toolkit 0.5.1 → 0.7.0

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());
+}

package/src/composer/AgentComposerFrame.tsx

@@ -0,0 +1,59 @@
+import { ComposerPrimitive } from "@assistant-ui/react";
+import type React from "react";
+
+import { cn } from "../utils.js";
+import type { AgentComposerLayoutVariant } from "./types.js";
+
+export interface AgentComposerFrameProps {
+  children: React.ReactNode;
+  className?: string;
+  rootClassName?: string;
+  style?: React.CSSProperties;
+  rootStyle?: React.CSSProperties;
+  layoutVariant?: AgentComposerLayoutVariant;
+  onClick?: React.MouseEventHandler<HTMLDivElement>;
+}
+
+/**
+ * The single visual shell for agent chat composition.
+ *
+ * AssistantChat, PromptComposer, and host surfaces such as Agent-Native Code
+ * all render this same frame so the composer does not drift across products.
+ */
+export function AgentComposerFrame({
+  children,
+  className,
+  rootClassName,
+  style,
+  rootStyle,
+  layoutVariant = "default",
+  onClick,
+}: AgentComposerFrameProps) {
+  return (
+    <div
+      data-agent-composer-variant={layoutVariant}
+      data-agent-composer-slot="area"
+      className={cn(
+        "agent-composer-area shrink-0 px-3 py-2",
+        layoutVariant !== "default" && `agent-composer-area--${layoutVariant}`,
+        className,
+      )}
+      style={style}
+      onClick={onClick}
+    >
+      <ComposerPrimitive.Root
+        data-agent-composer-variant={layoutVariant}
+        data-agent-composer-slot="root"
+        className={cn(
+          "agent-composer-root flex flex-col rounded-lg border border-input bg-muted/45 transition-colors focus-within:border-ring",
+          layoutVariant !== "default" &&
+            `agent-composer-root--${layoutVariant}`,
+          rootClassName,
+        )}
+        style={rootStyle}
+      >
+        {children}
+      </ComposerPrimitive.Root>
+    </div>
+  );
+}