@agent-native/core 0.85.7 → 0.86.1

package/corpus/core/src/client/components/LiveCursorOverlay.tsx

@@ -109,6 +109,9 @@ const CursorLabel = memo(function CursorLabel({
           position: "absolute",
           left: 31,
           top: 31,
+          display: "flex",
+          alignItems: "center",
+          gap: 5,
           backgroundColor: color,
           color: "#fff",
           fontSize: 12,
@@ -118,11 +121,23 @@ const CursorLabel = memo(function CursorLabel({
           borderRadius: 2,
           whiteSpace: "nowrap",
           boxShadow: "0 5px 12px rgba(15, 23, 42, 0.16)",
-          maxWidth: 120,
+          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>

package/corpus/core/src/client/components/PresenceBar.tsx

@@ -120,7 +120,20 @@ function UserAvatar({
             if (e.key === "Enter" || e.key === " ") onClick?.();
           }}
         >
-          {initial}
+          {user.avatarUrl ? (
+            <img
+              src={user.avatarUrl}
+              alt=""
+              style={{
+                width: "100%",
+                height: "100%",
+                borderRadius: "50%",
+                objectFit: "cover",
+              }}
+            />
+          ) : (
+            initial
+          )}
         </div>
       </TooltipTrigger>
       <TooltipContent side="bottom">

package/corpus/core/src/client/components/RecentEditHighlights.tsx

@@ -0,0 +1,219 @@
+/**
+ * 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 } from "react";
+
+import type { AttributedRecentEdit } from "../../collab/recent-edits.js";
+import { RECENT_EDIT_TTL_MS } from "../../collab/recent-edits.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: React.RefObject<HTMLElement | null>;
+  /** Highlight lifetime; should match useRecentEdits ttlMs. Default 6000. */
+  ttlMs?: number;
+  /** Additional CSS class for the overlay div. */
+  className?: string;
+}
+
+interface Highlight {
+  key: string;
+  color: string;
+  label: string;
+  avatarUrl?: string;
+  isAgent: 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.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,
+        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.color,
+          color: "#fff",
+          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,
+  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
+          ? 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,
+        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/corpus/core/src/client/components/RemoteSelectionRings.tsx

@@ -22,6 +22,13 @@ import { useState, useEffect, useRef, useLayoutEffect, memo } from "react";
 
 import type { OtherPresence } from "../../collab/presence.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[];
@@ -48,6 +55,7 @@ interface Ring {
   clientId: number;
   color: string;
   label: string;
+  avatarUrl?: string;
   isAgent: boolean;
   rect: { top: number; left: number; width: number; height: number };
 }
@@ -76,6 +84,9 @@ const RingItem = memo(function RingItem({ ring }: { ring: Ring }) {
           position: "absolute",
           top: -20,
           left: 0,
+          display: "flex",
+          alignItems: "center",
+          gap: 4,
           backgroundColor: ring.color,
           color: "#fff",
           fontSize: 10,
@@ -83,12 +94,24 @@ const RingItem = memo(function RingItem({ ring }: { ring: Ring }) {
           padding: "1px 5px",
           borderRadius: 3,
           whiteSpace: "nowrap",
-          maxWidth: 120,
+          maxWidth: 160,
           overflow: "hidden",
           textOverflow: "ellipsis",
         }}
       >
-        {ring.isAgent ? `AI — ${ring.label}` : ring.label}
+        {ring.avatarUrl ? (
+          <img
+            src={ring.avatarUrl}
+            alt=""
+            style={{
+              width: 12,
+              height: 12,
+              borderRadius: "50%",
+              flexShrink: 0,
+            }}
+          />
+        ) : null}
+        {ring.label}
       </div>
     </div>
   );
@@ -115,10 +138,17 @@ export function RemoteSelectionRings({
     const next: Ring[] = [];
 
     for (const other of others) {
-      const descriptor = other.presence[selectionKey] as string | undefined;
-      if (!descriptor || typeof descriptor !== "string") continue;
+      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(descriptor);
+      const domRect = resolveRect(selector);
       if (!domRect) continue;
 
       // Convert viewport-relative rect to container-relative.
@@ -133,10 +163,14 @@ export function RemoteSelectionRings({
         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: other.isAgent ? "AI" : other.user.name || other.user.email,
+        label: selectionLabel ? `${baseName} — ${selectionLabel}` : baseName,
+        avatarUrl: (other.user as { avatarUrl?: string }).avatarUrl,
         isAgent: other.isAgent,
         rect: { top, left, width: domRect.width, height: domRect.height },
       });

package/corpus/core/src/client/db-admin/DbAdminPage.tsx

@@ -1,11 +1,10 @@
 import { IconDatabase, IconLoader2 } from "@tabler/icons-react";
 /**
- * Code-mode database admin page — the shell that hosts the table browser, the
- * table editor, and the SQL editor.
+ * Database admin page — the shell that hosts the table browser, the table
+ * editor, and the SQL editor.
  *
- * Gated to Code mode: when the app cannot toggle into Code mode
- * (`canToggle` is false) we render a clean notice instead of the tool. The
- * backend also enforces this with a 403, so this is purely a friendlier UX.
+ * By default this is gated to Code mode for the core dev route. Trusted hosts
+ * can opt out and point it at their own admin-gated API path.
  */
 import { useEffect, useMemo, useState } from "react";
 
@@ -16,7 +15,7 @@ import { SqlEditor } from "./SqlEditor.js";
 import { TableBrowser } from "./TableBrowser.js";
 import { TableEditor } from "./TableEditor.js";
 import { useDbAdminAgentSync, useNavigateConsumer } from "./useAgentSync.js";
-import { useOverview } from "./useDbAdmin.js";
+import { useOverview, type DbAdminRequestConfig } from "./useDbAdmin.js";
 
 const DIALECT_LABEL: Record<string, string> = {
   postgres: "Postgres",
@@ -24,9 +23,30 @@ const DIALECT_LABEL: Record<string, string> = {
   d1: "Cloudflare D1",
 };
 
-export function DbAdminPage() {
+export interface DbAdminPageProps {
+  apiBasePath?: string;
+  cacheScope?: string;
+  title?: string;
+  subtitle?: string;
+  codeModeGate?: boolean;
+  syncNavigation?: boolean;
+}
+
+export function DbAdminPage({
+  apiBasePath,
+  cacheScope,
+  title = "Database",
+  subtitle,
+  codeModeGate = true,
+  syncNavigation = true,
+}: DbAdminPageProps = {}) {
   const { canToggle, isLoading: devLoading } = useCodeMode();
-  const { data: overview, isLoading: overviewLoading } = useOverview();
+  const requestConfig = useMemo<DbAdminRequestConfig | undefined>(() => {
+    if (!apiBasePath && !cacheScope) return undefined;
+    return { basePath: apiBasePath, scopeKey: cacheScope };
+  }, [apiBasePath, cacheScope]);
+  const { data: overview, isLoading: overviewLoading } =
+    useOverview(requestConfig);
 
   const [selectedTable, setSelectedTable] = useState<string | null>(null);
   const [mode, setMode] = useState<"table" | "sql">("table");
@@ -45,12 +65,12 @@ export function DbAdminPage() {
   }, [selectedTable, tables]);
 
   // Keep the agent's <current-screen> in sync, and let it drive navigation.
-  useDbAdminAgentSync({ table: selectedTable, mode });
+  useDbAdminAgentSync({ table: selectedTable, mode, enabled: syncNavigation });
   useNavigateConsumer((table) => {
     setSelectedTable(table);
     setMode("table");
     setFkFilters(undefined);
-  });
+  }, syncNavigation);
 
   const tableNames = useMemo(() => tables.map((t) => t.name), [tables]);
   // SqlEditor degrades gracefully without per-table columns; pass an empty map.
@@ -58,7 +78,7 @@ export function DbAdminPage() {
   const columnsByTable = useMemo<Record<string, string[]>>(() => ({}), []);
 
   // ─── Code mode gate ──────────────────────────────────────────────────────
-  if (!devLoading && !canToggle) {
+  if (codeModeGate && !devLoading && !canToggle) {
     return (
       <div className="flex h-full w-full items-center justify-center bg-background p-6">
         <div className="flex max-w-md flex-col items-center rounded-lg border bg-card p-8 text-center shadow-sm">
@@ -79,20 +99,26 @@ export function DbAdminPage() {
     );
   }
 
-  const showInitialLoading = (devLoading || overviewLoading) && !overview;
+  const showInitialLoading =
+    ((codeModeGate && devLoading) || overviewLoading) && !overview;
 
   return (
     <div className="flex h-full w-full flex-col bg-background text-foreground">
       {/* Header */}
       <header className="flex h-12 shrink-0 items-center gap-3 border-b px-4">
         <IconDatabase className="h-5 w-5 text-muted-foreground" stroke={1.75} />
-        <span className="text-sm font-semibold">Database</span>
+        <span className="text-sm font-semibold">{title}</span>
         <span className="inline-flex items-center rounded-full border bg-muted px-2 py-0.5 text-xs font-medium text-muted-foreground">
           {DIALECT_LABEL[dialect] ?? dialect}
         </span>
         <span className="text-xs text-muted-foreground">
           {tables.length} {tables.length === 1 ? "table" : "tables"}
         </span>
+        {subtitle ? (
+          <span className="min-w-0 truncate text-xs text-muted-foreground">
+            {subtitle}
+          </span>
+        ) : null}
       </header>
 
       {/* Body: fixed sidebar + flexible main */}
@@ -122,12 +148,14 @@ export function DbAdminPage() {
               dialect={dialect}
               tableNames={tableNames}
               columnsByTable={columnsByTable}
+              requestConfig={requestConfig}
             />
           ) : selectedTable ? (
             <TableEditor
               key={selectedTable}
               table={selectedTable}
               dialect={dialect}
+              requestConfig={requestConfig}
               initialFilters={fkFilters}
               onNavigateToRow={(t, filters) => {
                 setSelectedTable(t);

package/corpus/core/src/client/db-admin/SqlEditor.tsx

@@ -63,12 +63,13 @@ import {
   deleteSnippet,
   type SqlSnippet,
 } from "./sql-storage.js";
-import { runQuery } from "./useDbAdmin.js";
+import { runQuery, type DbAdminRequestConfig } from "./useDbAdmin.js";
 
 export interface SqlEditorProps {
   dialect: DbAdminDialect;
   tableNames: string[];
   columnsByTable: Record<string, string[]>;
+  requestConfig?: DbAdminRequestConfig;
 }
 
 interface QueryResult {
@@ -266,6 +267,7 @@ export function SqlEditor({
   dialect,
   tableNames,
   columnsByTable,
+  requestConfig,
 }: SqlEditorProps) {
   const isDark = useIsDark();
   const editorRef = useRef<ReactCodeMirrorRef>(null);
@@ -307,7 +309,12 @@ export function SqlEditor({
       setRunning(true);
       setError(null);
       try {
-        const res = await runQuery(trimmed, undefined, confirmDestructive);
+        const res = await runQuery(
+          trimmed,
+          undefined,
+          confirmDestructive,
+          requestConfig,
+        );
         setResult({
           columns: res.columns,
           rows: res.rows,
@@ -334,7 +341,7 @@ export function SqlEditor({
         setRunning(false);
       }
     },
-    [],
+    [requestConfig],
   );
 
   const runActiveStatement = useCallback(() => {

package/corpus/core/src/client/db-admin/TableEditor.tsx

@@ -36,11 +36,17 @@ import { DataGrid, type GridRow, type ActiveCell } from "./DataGrid.js";
 import { FilterBar } from "./FilterBar.js";
 import { RowSidePanel, type RowSidePanelMode } from "./RowSidePanel.js";
 import { loadGridState, saveGridState } from "./storage.js";
-import { useTableSchema, useTableRows, mutateTable } from "./useDbAdmin.js";
+import {
+  useTableSchema,
+  useTableRows,
+  mutateTable,
+  type DbAdminRequestConfig,
+} from "./useDbAdmin.js";
 
 export interface TableEditorProps {
   table: string;
   dialect: DbAdminDialect;
+  requestConfig?: DbAdminRequestConfig;
   initialFilters?: DbAdminFilter[];
   onNavigateToRow: (table: string, filters: DbAdminFilter[]) => void;
 }
@@ -51,6 +57,7 @@ const PAGE_SIZES = [25, 50, 100, 250, 500];
 export function TableEditor({
   table,
   dialect: _dialect,
+  requestConfig,
   initialFilters,
   onNavigateToRow,
 }: TableEditorProps) {
@@ -90,12 +97,12 @@ export function TableEditor({
   }, [table, columnWidths, sort, filters, pageSize]);
 
   // ─── Data ────────────────────────────────────────────────────────────────
-  const schemaState = useTableSchema(table);
+  const schemaState = useTableSchema(table, requestConfig);
   const rowsReq = useMemo(
     () => ({ page, pageSize, sort, filters }),
     [page, pageSize, sort, filters],
   );
-  const rowsState = useTableRows(table, rowsReq);
+  const rowsState = useTableRows(table, rowsReq, requestConfig);
 
   const schema = schemaState.data;
   const changeset = useChangeset(schema);
@@ -201,9 +208,9 @@ export function TableEditor({
       if (!mutation.inserts && !mutation.updates && !mutation.deletes) {
         return null;
       }
-      return mutateTable(table, mutation);
+      return mutateTable(table, mutation, requestConfig);
     },
-    [changeset, originalRows, table],
+    [changeset, originalRows, requestConfig, table],
   );
 
   const handlePreview = useCallback(async () => {

package/corpus/core/src/client/db-admin/useAgentSync.ts

@@ -64,6 +64,7 @@ export interface DbAdminNavigationState {
 export interface UseDbAdminAgentSyncArgs {
   table: string | null;
   mode: "table" | "sql";
+  enabled?: boolean;
 }
 
 /**
@@ -74,8 +75,10 @@ export interface UseDbAdminAgentSyncArgs {
 export function useDbAdminAgentSync({
   table,
   mode,
+  enabled = true,
 }: UseDbAdminAgentSyncArgs): void {
   useEffect(() => {
+    if (!enabled) return;
     const state: DbAdminNavigationState = { view: "database", table, mode };
     fetch(NAVIGATION_PATH, {
       method: "PUT",
@@ -84,7 +87,7 @@ export function useDbAdminAgentSync({
       headers: headers({ "Content-Type": "application/json" }),
       body: JSON.stringify(state),
     }).catch(() => {});
-  }, [table, mode]);
+  }, [enabled, table, mode]);
 }
 
 interface NavigateCommand {
@@ -97,11 +100,15 @@ interface NavigateCommand {
  * a database table, invoke `onNavigate(table)` then clear the key so it does
  * not replay on the next poll.
  */
-export function useNavigateConsumer(onNavigate: (table: string) => void): void {
+export function useNavigateConsumer(
+  onNavigate: (table: string) => void,
+  enabled = true,
+): void {
   const handlerRef = useRef(onNavigate);
   handlerRef.current = onNavigate;
 
   useEffect(() => {
+    if (!enabled) return;
     let active = true;
     let timer: ReturnType<typeof setTimeout> | undefined;
 
@@ -143,5 +150,5 @@ export function useNavigateConsumer(onNavigate: (table: string) => void): void {
       active = false;
       if (timer) clearTimeout(timer);
     };
-  }, []);
+  }, [enabled]);
 }