@graph8/sdk 0.361.0 → 0.370.0

package/blocks/webchat/components/webchat-screen.tsx

@@ -0,0 +1,245 @@
+"use client";
+
+/**
+ * WebchatScreen: the finished web chat page with three tabs.
+ *   Visitors: the people who used the widget (search, identified-only, paging), engagement funnel as stats, and a detail
+ *             panel for the selected visitor (deep link `?id=`). Message threads live in the inbox block: pass
+ *             `renderDetailActions` to link a visitor to their conversation.
+ *   Widget:   ChatWidgetConfig (pick or create a chat bot, style the widget, starter questions, delete a question with confirm).
+ *   Install:  the tracking snippet to paste on your pages, plus what must be set up in graph8 first.
+ *
+ * SDK operations (all through the composed parts): listWebchatVisitors, getWebchatVisitorFunnel, getOrgSnippet (read);
+ * ChatWidgetConfig's bot, settings and question calls (write); deleteWebchatQuestion (destructive, ConfirmSpendDialog).
+ * Saves in the Widget tab are live for the next visitor. Mapping an answering agent to a bot is done in the graph8 app.
+ */
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+import { Copy, MessageSquare } from "lucide-react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { pickItems, visitorCompany, visitorEmail, visitorLastSeen, visitorName } from "../lib/webchat-types";
+import type { Visitor } from "../lib/webchat-types";
+import { ChatWidgetConfig } from "./chat-widget-config";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface WebchatScreenProps {
+  /** Limit the funnel and open the Widget tab on this bot. */
+  botId?: string;
+  pageSize?: number;
+  /** Extra buttons in the header. */
+  toolbarActions?: ReactNode;
+  /** Buttons in the visitor detail header (for example "Open in inbox"). */
+  renderDetailActions?: (visitor: Visitor) => ReactNode;
+  /** Extra tabs in the visitor detail panel. */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (visitor: Visitor) => ReactNode }>;
+  renderRowActions?: (visitor: Visitor) => ReactNode;
+  className?: string;
+}
+
+const TABS = [
+  { id: "visitors", label: "Visitors" },
+  { id: "widget", label: "Widget" },
+  { id: "install", label: "Install" },
+];
+
+function useDebounced<T>(value: T, ms = 300): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
+/** A stable, deep-linkable key: the visitor id, else the email. A row with neither is selectable but not linkable (never the row index, which points at different people per page). */
+const idOf = (v: Visitor): string | null => {
+  if (v.id != null && String(v.id) !== "") return String(v.id);
+  const email = visitorEmail(v);
+  return email ? `email:${email}` : null;
+};
+
+function flatFields(v: Visitor): Array<{ label: string; value: ReactNode }> {
+  return Object.entries(v)
+    .filter(([, x]) => ["string", "number", "boolean"].includes(typeof x) && String(x) !== "")
+    .map(([k, x]) => ({ label: k.replace(/_/g, " "), value: String(x) }));
+}
+
+function VisitorDetail({ visitor, onClose, onExpand, onCollapse, props }: { visitor: Visitor; onClose: () => void; onExpand?: () => void; onCollapse?: () => void; props: WebchatScreenProps }) {
+  const name = visitorName(visitor);
+  const identified = Boolean(visitorEmail(visitor));
+  return (
+    <DetailPanel
+      title={name}
+      subtitle={[visitorEmail(visitor), visitorCompany(visitor)].filter(Boolean).join(" at ") || "Anonymous visitor"}
+      avatar={<EntityAvatar name={name} kind="person" />}
+      badges={<StatusPill tone={identified ? "positive" : "neutral"}>{identified ? "Identified" : "Anonymous"}</StatusPill>}
+      actions={props.renderDetailActions?.(visitor)}
+      onClose={onClose}
+      onExpand={onExpand}
+      onCollapse={onCollapse}
+      tabs={[
+        { id: "overview", label: "Overview", content: <KeyValueList columns={1} items={[{ label: "Last seen", value: visitorLastSeen(visitor) || "Not known" }, ...flatFields(visitor)]} /> },
+        ...(props.extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(visitor) })),
+      ]}
+    />
+  );
+}
+
+function VisitorsTab({ props }: { props: WebchatScreenProps }) {
+  const pageSize = props.pageSize ?? 25;
+  const [page, setPage] = useState(1);
+  const [identifiedOnly, setIdentifiedOnly] = useState(false);
+  const [text, setText] = useState("");
+  const search = useDebounced(text.trim());
+  const [openId, setOpenId] = useUrlState("id");
+  const [view, setView] = useUrlState("view");
+  const [localSel, setLocalSel] = useState<Visitor | null>(null);
+  const visitors = useG8Query(
+    (signal) =>
+      g8Get<unknown>("/webchat/visitors", { page, page_size: pageSize, identified_only: identifiedOnly || undefined, search: search || undefined }, { signal }).then((r) => ({
+        items: pickItems<Visitor>(r.data),
+        total: (r.data as { total?: number } | undefined)?.total,
+      })),
+    [page, pageSize, identifiedOnly, search],
+  );
+  const items = visitors.data?.items ?? [];
+  const selected = (openId ? items.find((v) => idOf(v) === openId) : undefined) ?? (localSel && items.includes(localSel) ? localSel : undefined);
+  const reset = () => { setPage(1); setOpenId(null); setView(null); setLocalSel(null); };
+  const pick = (v: Visitor) => { const id = idOf(v); setLocalSel(id ? null : v); setOpenId(id); };
+  const expanded = view === "full" && Boolean(selected);
+
+  const list = (
+    <div className="space-y-3">
+      <Toolbar
+        search={{ value: text, onChange: (v) => { setText(v); reset(); }, placeholder: "Search by name or email" }}
+        filters={<label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={identifiedOnly} onChange={(e) => { setIdentifiedOnly(e.target.checked); reset(); }} />Identified only</label>}
+      />
+      {visitors.error ? (
+        <ApiError error={visitors.error} title="Could not load visitors" onRetry={() => void visitors.refetch()} />
+      ) : visitors.loading && !visitors.data ? (
+        <div aria-busy="true" className="grid gap-2">{Array.from({ length: 4 }, (_, i) => <Skeleton key={i} className="h-9 w-full" />)}</div>
+      ) : items.length === 0 ? (
+        search || identifiedOnly ? (
+          <EmptyState title="No visitors match" description="Try a different search, or include anonymous visitors." action={<Button size="sm" variant="outline" onClick={() => { setText(""); setIdentifiedOnly(false); reset(); }}>Clear filters</Button>} />
+        ) : (
+          <EmptyState icon={<MessageSquare className="size-6" />} title="No chat visitors yet" description="People appear here after they use the widget on your site. Install the snippet first." action={<span className="text-sm text-muted-foreground">See the Install tab.</span>} />
+        )
+      ) : (
+        <Table>
+          <TableHeader><TableRow><TableHead>Visitor</TableHead><TableHead>Email</TableHead><TableHead>Company</TableHead><TableHead>Last seen</TableHead>{props.renderRowActions ? <TableHead /> : null}</TableRow></TableHeader>
+          <TableBody>
+            {items.map((v, i) => (
+              <TableRow key={idOf(v) ?? `row-${i}`} data-state={selected === v ? "selected" : undefined} className="cursor-pointer" {...rowActivationProps(() => pick(v))}>
+                <TableCell><span className="flex items-center gap-2"><EntityAvatar name={visitorName(v)} kind="person" size="sm" />{idOf(v) ? <RecordLink param="id" id={idOf(v) as string} onOpen={() => pick(v)}>{visitorName(v)}</RecordLink> : visitorName(v)}</span></TableCell>
+                <TableCell>{visitorEmail(v)}</TableCell>
+                <TableCell>{visitorCompany(v)}</TableCell>
+                <TableCell>{visitorLastSeen(v)}</TableCell>
+                {props.renderRowActions ? <TableCell onClick={(e) => e.stopPropagation()}>{props.renderRowActions(v)}</TableCell> : null}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <span>{visitors.data?.total != null ? `${visitors.data.total.toLocaleString()} visitors` : `Page ${page}`}</span>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" disabled={page <= 1} onClick={() => { setPage(page - 1); setOpenId(null); setLocalSel(null); }}>Previous</Button>
+          <Button size="sm" variant="outline" disabled={items.length < pageSize} onClick={() => { setPage(page + 1); setOpenId(null); setLocalSel(null); }}>Next</Button>
+        </div>
+      </div>
+    </div>
+  );
+  const close = () => { setOpenId(null); setView(null); setLocalSel(null); };
+  return (
+    <SplitView
+      list={list}
+      detailOpen={Boolean(selected)}
+      onCloseDetail={close}
+      expanded={expanded}
+      onExpandedChange={(next) => setView(next ? "full" : null)}
+      detail={selected ? <VisitorDetail visitor={selected} onClose={close} onExpand={expanded ? undefined : () => setView("full")} onCollapse={expanded ? () => setView(null) : undefined} props={props} /> : null}
+    />
+  );
+}
+
+function InstallTab() {
+  const brand = useBrand();
+  const snippet = useG8Query((signal) => g8Get<{ script_tag?: string }>("/snippet", {}, { signal }).then((r) => r.data), []);
+  const [copied, setCopied] = useState(false);
+  const [copyFailed, setCopyFailed] = useState(false);
+  const tag = snippet.data?.script_tag;
+  const copy = () => {
+    setCopyFailed(false);
+    const write = navigator.clipboard?.writeText(tag ?? "");
+    if (!write) { setCopyFailed(true); return; }
+    write.then(() => setCopied(true)).catch(() => { setCopied(false); setCopyFailed(true); });
+  };
+  return (
+    <div className="grid gap-4">
+      <SectionCard title="Embed code" description={`The widget loads through the ${brand.linkLabel} tracking snippet. Add it to every page that should show the chat.`}>
+        {snippet.error ? (
+          <ApiError error={snippet.error} title="Could not load the snippet" onRetry={() => void snippet.refetch()} />
+        ) : tag ? (
+          <div className="space-y-2">
+            <pre aria-label="Snippet" className="overflow-auto rounded-md bg-muted p-3 text-xs">{tag}</pre>
+            <Button size="sm" variant="outline" onClick={copy}><Copy className="mr-1 size-4" />{copied ? "Copied" : "Copy snippet"}</Button>
+            {copyFailed ? <p role="alert" className="text-sm text-error-foreground">Copy failed. Select the code above and copy it.</p> : null}
+          </div>
+        ) : (
+          <Skeleton className="h-12 w-full" />
+        )}
+      </SectionCard>
+      <SectionCard title="Before it works">
+        <ul className="list-disc space-y-1 pl-5 text-sm">
+          <li>The snippet is on the pages that should show the chat.</li>
+          <li>An answering agent is mapped to the bot. A bot with none answers nothing. Set it up in {brand.linkLabel}.</li>
+          <li>Style the widget in the Widget tab. Saves are live for the next visitor.</li>
+        </ul>
+        <a className="mt-2 inline-block text-sm underline" href={brand.appUrl} target="_blank" rel="noreferrer">Open {brand.linkLabel}</a>
+      </SectionCard>
+    </div>
+  );
+}
+
+export function WebchatScreen(props: WebchatScreenProps) {
+  const { botId, toolbarActions, className } = props;
+  const [tab, setTab] = useUrlState("tab", "visitors");
+  const funnel = useG8Query((signal) => g8Get<Record<string, unknown>>("/webchat/visitors/funnel", { bot_id: botId }, { signal }).then((r) => r.data), [botId]);
+  const stats = useMemo(() => {
+    const counts = Object.entries((funnel.data?.counts ?? funnel.data?.events ?? {}) as Record<string, unknown>).filter(([, v]) => typeof v === "number") as Array<[string, number]>;
+    return counts.slice(0, 4).map(([k, v]) => ({ label: k.replace(/_/g, " "), value: v.toLocaleString() }));
+  }, [funnel.data]);
+  const active = TABS.some((t) => t.id === tab) ? tab : "visitors";
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Web chat"
+      description="Who talks to your site's AI chat, how it looks, and how to put it on your pages."
+      icon={<MessageSquare className="size-5" />}
+      actions={toolbarActions}
+      tabs={TABS}
+      activeTab={active}
+      onTabChange={(id) => setTab(id)}
+      stats={stats.length > 0 ? stats : undefined}
+    >
+      {funnel.error ? <p role="alert" className="mb-3 text-sm text-muted-foreground">Could not load the engagement numbers. <button type="button" className="underline" onClick={() => void funnel.refetch()}>Retry</button></p> : null}
+      {active === "visitors" ? <VisitorsTab props={props} /> : null}
+      {active === "widget" ? <ChatWidgetConfig initialBotId={botId} /> : null}
+      {active === "install" ? <InstallTab /> : null}
+    </ScreenLayout>
+  );
+}

package/blocks/workbench/README.md

@@ -7,6 +7,17 @@ price, run it, and watch it finish. Finished rows go to a list. Builds on `enric
 
 Install: `npx @graph8/sdk add workbench` (installs `foundation`, `crm`, `enrichment` and `lists` first).
 
+## Screens
+
+`WorkbenchScreen` is the finished Workbench page; mount it with no props. The list view shows every workbench with row and
+column counts, search, **New workbench** (People or Companies) and a confirmed delete. `?id=<table>` opens a table: a
+header with row, column and recipe-column counts and the full `WorkbenchGrid` (edit cells, paste or add rows, add AI,
+waterfall and formula columns, quote then run, progress, unlock locked rows, send rows to a list, delete rows).
+**Import people** (free preview and match count, then a confirmed import; rows land locked) and **Scrape the web** (credit estimate and balance, confirmed run, polled progress) are in the table header (`SearchImportPanel`, `ScraperPanel`). Open any row (`?row=`) for `WorkbenchRowDetail`: every cell, per-cell edit, unlock, send to a list, delete. `?view=full` opens a row full-page.
+Slots: `toolbarActions`, `renderRowActions(table)`, `renderDetailActions(table)`.
+
+Prerequisites: `enrichment` and `lists` installed, proxy allowlist `workbench`, `enrichment`, `lists`; provider keys and credits as below.
+
 ## What you get
 
 | Component | Use it for | Props |

package/blocks/workbench/block.json

@@ -8,7 +8,8 @@
     "add rows by typing or pasting a spreadsheet; locked rows from a search import show masked cells",
     "column recipes: AI prompt with {{column}} placeholders, enrichment waterfall presets, formulas, plain columns, target-field mapping",
     "runs are quoted for free, confirmed with the exact credits, started with the quote as the cap and followed to a final receipt",
-    "unlock locked rows (1 credit each), send rows to a list, delete rows"
+    "unlock locked rows (1 credit each), send rows to a list, delete rows",
+    "finished WorkbenchScreen page"
   ],
   "dependsOn": [
     "enrichment",
@@ -25,6 +26,7 @@
     "export_workbench_table_workbench_tables__table_id__export_post",
     "get_workbench_analytics_workbench_tables__table_id__analytics_get",
     "get_workbench_history_workbench_tables__table_id__history_get",
+    "get_workbench_row_workbench_tables__table_id__rows__row_id__get",
     "get_workbench_scraper_run_workbench_tables__table_id__scraper_runs__run_id__get",
     "get_workbench_table_workbench_tables__table_id__get",
     "import_workbench_from_search_workbench_tables__table_id__import_search_post",
@@ -143,6 +145,50 @@
         "billable",
         "destructive"
       ]
+    },
+    {
+      "name": "WorkbenchScreen",
+      "file": "components/workbench-screen.tsx",
+      "purpose": "Finished Workbench page: workbench list with create/delete and the full table (WorkbenchGrid) with a stats header.",
+      "operations": [
+        "create_workbench_table_workbench_tables_post",
+        "delete_workbench_table_workbench_tables__table_id__delete",
+        "list_workbench_tables_workbench_tables_get"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SearchImportPanel",
+      "file": "components/workbench-sources.tsx",
+      "purpose": "Import people from a search into a table: free preview and match count, then a confirmed billable import (rows land locked). The same file exports ScraperPanel: web scraper with credit estimate, confirmed billable run and polled progress.",
+      "operations": [
+        "estimate_workbench_scraper_credits_workbench_scraper_credit_estimate_get",
+        "get_workbench_scraper_run_workbench_tables__table_id__scraper_runs__run_id__get",
+        "import_workbench_from_search_workbench_tables__table_id__import_search_post",
+        "preview_workbench_search_import_workbench_tables__table_id__import_search_preview_post",
+        "run_workbench_scraper_workbench_tables__table_id__scraper_runs_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "WorkbenchRowDetail",
+      "file": "components/workbench-row-detail.tsx",
+      "purpose": "One workbench row in full: every cell, status, per-cell edit, unlock, send to a list and delete.",
+      "operations": [
+        "get_workbench_row_workbench_tables__table_id__rows__row_id__get",
+        "update_workbench_row_workbench_tables__table_id__rows__row_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
     }
   ],
   "hooks": [
@@ -254,6 +300,7 @@
     }
   ],
   "peerDependencies": {
+    "lucide-react": ">=0.400.0",
     "react": ">=18"
   }
 }

package/blocks/workbench/components/column-recipe-editor.tsx

@@ -30,6 +30,7 @@ import { useProviders } from "@/g8/enrichment/hooks/use-providers";
 import { WATERFALL_PRESETS, buildWaterfallConfig, requiredTargets } from "../lib/waterfall-presets";
 import { pageItems, toMachineName } from "../lib/workbench-types";
 import type { WorkbenchColumn } from "../lib/workbench-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface ColumnRecipeEditorProps {
   tableId: string;
@@ -52,6 +53,7 @@ const TABS: Array<{ id: Tab; label: string }> = [
 const newId = () => globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`;
 
 export function ColumnRecipeEditor({ tableId, columns, entityType = "contact", onSaved, className }: ColumnRecipeEditorProps) {
+  const brand = useBrand();
   const [tab, setTab] = useState<Tab>("ai");
   const [name, setName] = useState("");
   const [prompt, setPrompt] = useState("");
@@ -132,7 +134,7 @@ export function ColumnRecipeEditor({ tableId, columns, entityType = "contact", o
                 <label key={s.provider} className="flex items-center gap-2 text-sm">
                   <input type="checkbox" aria-label={`Use ${s.provider}`} checked={!skipped.includes(s.provider)} onChange={() => setSkipped(skipped.includes(s.provider) ? skipped.filter((x) => x !== s.provider) : [...skipped, s.provider])} />
                   <span className="w-6 text-muted-foreground">{i + 1}.</span><span className="font-medium">{s.provider}</span>
-                  <span className="text-xs text-muted-foreground">{info?.byok_configured ? "your key" : info?.system_funded ? "graph8 key, uses credits when run" : "needs your key"}</span>
+                  <span className="text-xs text-muted-foreground">{info?.byok_configured ? "your key" : info?.system_funded ? `${brand.linkLabel} key, uses credits when run` : "needs your key"}</span>
                 </label>
               );
             })}
@@ -163,7 +165,7 @@ export function ColumnRecipeEditor({ tableId, columns, entityType = "contact", o
 
       {tab === "map" ? (
         <div className="flex flex-col gap-2">
-          <p className="text-sm text-muted-foreground">Tell graph8 what each of your columns holds, so enrichment steps know where the first name, last name and website are.</p>
+          <p className="text-sm text-muted-foreground">Tell {brand.linkLabel} what each of your columns holds, so enrichment steps know where the first name, last name and website are.</p>
           {targets.error ? <ApiError error={targets.error} title="Could not load the fields" onRetry={() => void targets.refetch()} /> : null}
           {map.error ? <ApiError error={map.error} title="Could not save the mapping" /> : null}
           {columns.filter((c) => (c.column_type ?? "data") === "data" && !c.enrichment_type).map((c) => (

package/blocks/workbench/components/workbench-grid.tsx

@@ -39,6 +39,10 @@ export interface WorkbenchGridProps {
   tableId: string;
   /** Rows per window. Default 100. */
   pageSize?: number;
+  /** Adds an "Open" button on every row (a row detail screen). Omit it and the grid is unchanged. */
+  onOpenRow?: (row: WorkbenchRow) => void;
+  /** Highlights the open row. */
+  activeRowId?: number | null;
   className?: string;
 }
 
@@ -50,7 +54,7 @@ function runTarget(column: WorkbenchColumn): RunTarget | null {
   return null;
 }
 
-export function WorkbenchGrid({ tableId, pageSize = 100, className }: WorkbenchGridProps) {
+export function WorkbenchGrid({ tableId, pageSize = 100, onOpenRow, activeRowId, className }: WorkbenchGridProps) {
   const [end, setEnd] = useState(pageSize);
   const [panel, setPanel] = useState<Panel>(null);
   const [selected, setSelected] = useState<number[]>([]);
@@ -114,6 +118,7 @@ export function WorkbenchGrid({ tableId, pageSize = 100, className }: WorkbenchG
             <TableHeader>
               <TableRow>
                 <TableHead className="w-8"><input type="checkbox" aria-label="Select all rows" checked={allOn} onChange={() => setSelected(allOn ? [] : items.map((r) => r.id))} /></TableHead>
+                {onOpenRow ? <TableHead className="w-14"><span className="sr-only">Open</span></TableHead> : null}
                 {columns.map((c) => {
                   const target = runTarget(c);
                   return (
@@ -130,8 +135,9 @@ export function WorkbenchGrid({ tableId, pageSize = 100, className }: WorkbenchG
             </TableHeader>
             <TableBody>
               {items.map((row) => (
-                <TableRow key={row.id} data-state={selected.includes(row.id) ? "selected" : undefined}>
+                <TableRow key={row.id} data-state={selected.includes(row.id) || activeRowId === row.id ? "selected" : undefined}>
                   <TableCell><input type="checkbox" aria-label={`Select row ${row.id}`} checked={selected.includes(row.id)} onChange={() => toggle(row.id)} /></TableCell>
+                  {onOpenRow ? <TableCell><Button size="sm" variant="ghost" aria-label={`Open row ${row.id}`} onClick={() => onOpenRow(row)}>Open</Button></TableCell> : null}
                   {columns.map((c) => {
                     const value = cellValue(row, c);
                     const isEdit = editing?.rowId === row.id && editing.column === c.name;
@@ -140,7 +146,7 @@ export function WorkbenchGrid({ tableId, pageSize = 100, className }: WorkbenchG
                       <TableCell key={c.id} onDoubleClick={() => editable && setEditing({ rowId: row.id, column: c.name, value: formatCell(value) })}>
                         {isEdit && editing ? (
                           <Input autoFocus aria-label={`Edit ${c.name}`} value={editing.value} onChange={(e) => setEditing({ ...editing, value: e.target.value })}
-                            onKeyDown={(e) => { if (e.key === "Enter" && !save.loading) void save.mutate(editing); if (e.key === "Escape") setEditing(null); }} />
+                            onKeyDown={(e) => { if (e.key === "Enter" && !save.loading) { if (editing.value === formatCell(value)) setEditing(null); else void save.mutate(editing); } if (e.key === "Escape") setEditing(null); }} />
                         ) : (
                           <span className={isMasked(value) || (isLocked(row) && value == null) ? "text-muted-foreground" : ""} title={isLocked(row) ? "Locked: unlock the row to see this" : undefined}>{formatCell(value) || (isLocked(row) ? "locked" : "")}</span>
                         )}

package/blocks/workbench/components/workbench-row-detail.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+/**
+ * WorkbenchRowDetail: one workbench row in full. Every column with its value (a recipe's `extracted_data` before the
+ * imported `raw_data`), the row's status, error and enrichment time, an edit field per plain data column, and the row
+ * actions (unlock, send to a list, delete) for this one row.
+ *
+ * SDK operations, in order:
+ *   1. getWorkbenchRow         GET   /workbench/tables/{table_id}/rows/{row_id}                  (read)
+ *   2. updateWorkbenchRow      PATCH /workbench/tables/{table_id}/rows/{row_id} { field, value } (write; one field per call)
+ *   3. via WorkbenchRowActions: quoteWorkbenchUnlock, unlockWorkbenchRows (billable, confirmed), exportWorkbenchTable,
+ *      bulkDeleteWorkbenchRows (destructive, confirmed)
+ * A locked row (credit_charged false) shows masked cells and cannot be edited until it is unlocked (1 credit per row).
+ */
+
+import { useState } from "react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill, humanizeStatus, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Patch } from "@/g8/lib/g8-client";
+import { cellValue, formatCell, isLocked, isMasked } from "../lib/workbench-types";
+import type { WorkbenchColumn, WorkbenchRow } from "../lib/workbench-types";
+import { WorkbenchRowActions } from "./workbench-row-actions";
+
+export interface WorkbenchRowDetailProps {
+  tableId: string;
+  rowId: number;
+  columns: WorkbenchColumn[];
+  entityType?: "contact" | "company";
+  /** Called after an edit, unlock or export so the grid can reload; `deleted` also means this row is gone. */
+  onChanged?: (what: "edited" | "unlocked" | "exported" | "deleted") => void;
+  className?: string;
+}
+
+/** The endpoint answers the row itself; tolerate a `{ row }` wrapper too. */
+function asRow(data: unknown): WorkbenchRow | null {
+  const d = data as (WorkbenchRow & { row?: WorkbenchRow }) | null | undefined;
+  return d?.row ?? (d && typeof d.id === "number" ? d : null);
+}
+
+export function WorkbenchRowDetail({ tableId, rowId, columns, entityType = "contact", onChanged, className }: WorkbenchRowDetailProps) {
+  const [draft, setDraft] = useState<{ column: string; value: string } | null>(null);
+  const row = useG8Query(async (signal) => asRow((await g8Get(`/workbench/tables/${tableId}/rows/${rowId}`, undefined, { signal })).data), [tableId, rowId]);
+  const save = useG8Mutation((v: { column: string; value: string }) => g8Patch(`/workbench/tables/${tableId}/rows/${rowId}`, { field: v.column, value: v.value }), {
+    onSuccess: () => { setDraft(null); void row.refetch(); onChanged?.("edited"); },
+  });
+
+  if (row.error) return <ApiError error={row.error} title="Could not load the row" onRetry={() => void row.refetch()} />;
+  const r = row.data;
+  if (!r) return <Skeleton className="h-32 w-full" />;
+  const locked = isLocked(r);
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center gap-2">
+        {locked ? <StatusPill tone="warning" dot>Locked</StatusPill> : <StatusPill tone="positive" dot>Unlocked</StatusPill>}
+        {r.status ? <StatusPill tone={toneForStatus(r.status)} dot>{humanizeStatus(r.status)}</StatusPill> : null}
+      </div>
+      {r.error_message ? <p role="alert" className="text-sm text-destructive">{r.error_message}</p> : null}
+      {save.error ? <ApiError error={save.error} title="Could not save the cell" /> : null}
+      <SectionCard title="Fields" description={locked ? "Unlock this row to see and edit real values." : "Edit a plain data field and save it."}>
+        <ul className="flex flex-col gap-3">
+          {columns.map((c) => {
+            const value = cellValue(r, c);
+            const editable = !locked && (c.column_type ?? "data") === "data" && !c.enrichment_type;
+            const open = draft?.column === c.name;
+            return (
+              <li key={c.id} className="flex flex-col gap-1">
+                <span className="text-xs text-muted-foreground">{c.display_name || c.name}{c.enrichment_type ? ` (${c.enrichment_type})` : ""}</span>
+                {open ? (
+                  <div className="flex gap-2">
+                    <Input aria-label={`Edit ${c.name}`} value={draft.value} onChange={(e) => setDraft({ column: c.name, value: e.target.value })} />
+                    <Button size="sm" loading={save.loading} onClick={() => void save.mutate(draft)}>Save</Button>
+                    <Button size="sm" variant="ghost" onClick={() => setDraft(null)}>Cancel</Button>
+                  </div>
+                ) : (
+                  <div className="flex items-center justify-between gap-2">
+                    <span className={`min-w-0 break-words text-sm ${isMasked(value) ? "text-muted-foreground" : ""}`}>{isMasked(value) ? "Locked" : formatCell(value) || <span className="text-muted-foreground">-</span>}</span>
+                    {editable ? <Button size="sm" variant="ghost" aria-label={`Edit ${c.name} value`} onClick={() => setDraft({ column: c.name, value: formatCell(value) })}>Edit</Button> : null}
+                  </div>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      </SectionCard>
+      <SectionCard title="About this row">
+        <KeyValueList columns={2} items={[
+          { label: "Row id", value: String(r.id), mono: true },
+          { label: "Source", value: r.source_type ? humanizeStatus(r.source_type) : "" },
+          { label: "Enriched", value: r.enriched_at ? new Date(r.enriched_at).toLocaleString() : "" },
+          { label: "Credit charged", value: r.credit_charged == null ? "" : r.credit_charged ? "Yes" : "No, locked" },
+        ]} />
+      </SectionCard>
+      <SectionCard title="Actions" description="Unlock real emails and phones, send this row to a list, or delete it.">
+        <WorkbenchRowActions tableId={tableId} rowIds={[rowId]} entityType={entityType} onChanged={(what) => { void row.refetch(); onChanged?.(what); }} />
+      </SectionCard>
+    </div>
+  );
+}