@graph8/sdk 0.361.0 → 0.370.0

package/blocks/forms/components/form-builder.tsx

@@ -28,6 +28,7 @@ import { STATUS_LABEL, formLabel, formStatus, pageUrlText, pickItems } from "../
 import type { FormListItem, FormOverview, FormRef } from "../lib/form-types";
 import { FormMappingEditor } from "./form-mapping-editor";
 import { SubmissionsTable } from "./submissions-table";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface FormBuilderProps {
   /** Form to open first. */
@@ -83,6 +84,7 @@ function FormHeader({ form, onChanged }: { form: FormListItem; onChanged: () =>
 }
 
 export function FormBuilder({ initialForm, onSelectForm }: FormBuilderProps) {
+  const brand = useBrand();
   const [page, setPage] = useState(1);
   const [searchText, setSearchText] = useState("");
   const [search, setSearch] = useState("");
@@ -109,7 +111,7 @@ export function FormBuilder({ initialForm, onSelectForm }: FormBuilderProps) {
             <Button type="submit" size="sm" variant="outline">Search</Button>
           </form>
           {forms.loading && !forms.data ? <div className="grid gap-2" aria-busy="true"><Skeleton className="h-12 w-full" /><Skeleton className="h-12 w-full" /></div> : items.length === 0 ? (
-            <EmptyState title={search ? "No forms match" : "No forms captured yet"} description={search ? "Try another name." : "Install the graph8 snippet on your site (see FormEmbed). Forms appear here after their first submission."} />
+            <EmptyState title={search ? "No forms match" : "No forms captured yet"} description={search ? "Try another name." : `Install the ${brand.linkLabel} snippet on your site (see FormEmbed). Forms appear here after their first submission.`} />
           ) : (
             <ul className="grid gap-1">
               {items.map((f) => {

package/blocks/forms/components/form-embed.tsx

@@ -15,6 +15,7 @@ import { Button, Card, CardContent, CardHeader, CardTitle, Label, Skeleton } fro
 import { ApiError } from "@/g8/components/api-error";
 import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface FormEmbedProps {
   /** Stream (site) to read the snippet for. Omit for the organization's main stream. */
@@ -55,6 +56,7 @@ function CodeBlock({ label, code }: { label: string; code: string }) {
 }
 
 export function FormEmbed({ streamId }: FormEmbedProps) {
+  const brand = useBrand();
   const [stream, setStream] = useState<string | undefined>(streamId);
   const snippet = useG8Query((signal) => g8Get<Snippet>("/snippet", { stream_id: stream }, { signal }).then((r) => r.data), [stream]);
   const template = useG8Query((signal) => g8Get<{ html?: string }>("/snippet/form", { stream_id: stream }, { signal }).then((r) => r.data), [stream]);
@@ -80,7 +82,7 @@ export function FormEmbed({ streamId }: FormEmbedProps) {
       <Card>
         <CardHeader><CardTitle>1. Install the tracking snippet</CardTitle></CardHeader>
         <CardContent className="grid gap-3">
-          <p className="text-muted-foreground text-sm">Put this on every page that has a form. graph8 then detects the forms and records submissions. Allowed domains: {s?.domains?.join(", ") || "any"}.</p>
+          <p className="text-muted-foreground text-sm">Put this on every page that has a form. {brand.linkLabel} then detects the forms and records submissions. Allowed domains: {s?.domains?.join(", ") || "any"}.</p>
           {s?.script_tag ? <CodeBlock label="Script tag" code={s.script_tag} /> : null}
           {s?.react_snippet ? <CodeBlock label="React component" code={s.react_snippet} /> : null}
           <p className="text-muted-foreground text-xs">Write key: <code>{s?.write_key}</code> (public, safe in page source).</p>

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

@@ -0,0 +1,353 @@
+"use client";
+
+/**
+ * FormsScreen: the finished forms workspace. No props needed.
+ *
+ * graph8 captures the lead forms already on your site (it does not host a form designer), so this screen is
+ * about getting the code on the site, routing every captured form to a list, and watching what arrives.
+ *
+ * Composes: ScreenLayout (title, tabs, stats), Toolbar (debounced search, health filter), SplitView +
+ * DetailPanel (selected form, deep link `?id=<source_id>/<form_key>`, one submission `&submission=<id>`), FormEmbed
+ * (Install tab, `?tab=install`), SiteAuditPanel (Site audit tab, `?tab=audit`), FormMappingEditor (Setup tab),
+ * SubmissionsTable (Submissions tab).
+ *
+ * User flows: install the snippet and copy the ready-made lead form, see every captured form with its health and
+ * counts, search and filter, open one to read capture and delivery numbers, rename it, pause or resume delivery
+ * (confirmed), pick the destination list and map fields (suggest, preview, save, test), read submissions, trace
+ * where a lead went and retry a failed delivery (confirmed), and find forms graph8 is not capturing.
+ *
+ * SDK operations: listForms, getFormOverview, updateFormRegistry, pauseFormDelivery / resumeFormDelivery
+ * (external, confirmed), searchFormSubmissions (read, to resolve a `&submission=` deep link that was not clicked
+ * in this session); the rest live in the composed parts.
+ */
+
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import { ClipboardList, Pause, Play } from "lucide-react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import type { Tone } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { STATUS_LABEL, cellText, formLabel, formStatus, pageUrlText, pickItems, submissionFailed, submissionState } from "../lib/form-types";
+import type { FormListItem, FormOverview, FormRef, FormSubmission } from "../lib/form-types";
+import { FormEmbed } from "./form-embed";
+import { FormMappingEditor } from "./form-mapping-editor";
+import { SiteAuditPanel } from "./site-audit-panel";
+import { SubmissionsTable } from "./submissions-table";
+import { pluralWord } from "@/g8/lib/plural";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface FormsScreenProps {
+  renderRowActions?: (form: FormListItem) => ReactNode;
+  renderDetailActions?: (form: FormListItem) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (form: FormListItem) => ReactNode }[];
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+type Tab = "forms" | "install" | "audit";
+const LIMIT = 100;
+/** How many of a form's latest submissions a deep link is looked up in. */
+const SUBMISSION_LOOKUP = 100;
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+const TONE: Record<ReturnType<typeof formStatus>, Tone> = { failing: "negative", paused: "warning", live: "positive", needs_setup: "info", no_data: "neutral" };
+
+const refKey = (f: FormRef): string => `${encodeURIComponent(f.source_id)}/${encodeURIComponent(f.form_key)}`;
+
+function parseRef(value: string): FormRef | undefined {
+  const [source, key] = value.split("/");
+  return source && key ? { source_id: decodeURIComponent(source), form_key: decodeURIComponent(key) } : undefined;
+}
+
+function FormOverviewTab({ form, onChanged }: { form: FormListItem; onChanged: () => void }) {
+  const base = `/forms/${encodeURIComponent(form.form_key)}`;
+  const overview = useG8Query((signal) => g8Get<FormOverview>(`${base}/overview`, { source_id: form.source_id }, { signal }).then((r) => r.data), [base, form.source_id]);
+  const [name, setName] = useState(form.display_name ?? "");
+  const [confirm, setConfirm] = useState<"pause" | "resume" | null>(null);
+  const rename = useG8Mutation(() => g8Patch(base, { source_id: form.source_id, display_name: name.trim() }), { onSuccess: onChanged });
+  const toggle = useG8Mutation((action: "pause" | "resume") => g8Post(`${base}/delivery/${action}`, { source_id: form.source_id }), {
+    onSuccess: () => { setConfirm(null); void overview.refetch(); onChanged(); },
+  });
+  if (overview.error) return <ApiError error={overview.error} title="Could not load the form overview" onRetry={() => void overview.refetch()} />;
+  if (overview.loading && !overview.data) return <Skeleton className="h-32 w-full" aria-busy="true" />;
+  const o = overview.data;
+  const paused = o?.delivery_health === "paused";
+  const m = o?.metrics;
+  return (
+    <div className="grid gap-4">
+      <form className="flex items-end gap-2" onSubmit={(e) => { e.preventDefault(); if (name.trim()) void rename.mutate(undefined); }}>
+        <div className="max-w-sm flex-1">
+          <label htmlFor="g8-forms-name" className="text-muted-foreground text-xs">Form name</label>
+          <Input id="g8-forms-name" value={name} placeholder={form.form_key} onChange={(e) => setName(e.target.value)} />
+        </div>
+        <Button type="submit" size="sm" variant="outline" loading={rename.loading} disabled={!name.trim() || name.trim() === form.display_name}>Rename</Button>
+        <Button type="button" size="sm" variant="outline" disabled={!o} onClick={() => setConfirm(paused ? "resume" : "pause")}>
+          {paused ? <Play className="size-4" /> : <Pause className="size-4" />}{paused ? "Resume delivery" : "Pause delivery"}
+        </Button>
+      </form>
+      {rename.error ? <ApiError error={rename.error} title="Could not rename the form" /> : null}
+      {o?.delivery_warning ? <p role="alert" className="flex items-center gap-2 text-sm"><StatusPill tone="warning">Check delivery</StatusPill>{o.delivery_warning}</p> : null}
+      <KeyValueList
+        columns={2}
+        items={[
+          { label: "Captured", value: (m?.captured ?? 0).toLocaleString() },
+          { label: "Processed", value: (m?.processed ?? 0).toLocaleString() },
+          { label: "In destination", value: (m?.destination_verified ?? 0).toLocaleString() },
+          { label: "Failed", value: (m?.failed ?? 0).toLocaleString() },
+          { label: "Destination list", value: o?.destination?.list_name ?? "None yet" },
+          { label: "Capture health", value: o?.capture_health ?? "-" },
+          { label: "Page", value: pageUrlText(form.page_url) || "-" },
+          { label: "Next step", value: o?.recommended_action ?? "-" },
+        ]}
+      />
+      <ConfirmSpendDialog
+        open={confirm !== null}
+        tier="external"
+        title={confirm === "pause" ? "Pause delivery for this form?" : "Resume delivery for this form?"}
+        confirmLabel={confirm === "pause" ? "Pause" : "Resume"}
+        description={<><p>{confirm === "pause" ? "New submissions are still captured but queue instead of reaching your list." : "Queued and new submissions are delivered to the destination list, creating or updating contacts."}</p>{toggle.error ? <ApiError error={toggle.error} title="Could not change delivery" /> : null}</>}
+        confirming={toggle.loading}
+        onCancel={() => setConfirm(null)}
+        onConfirm={() => { if (confirm) void toggle.mutate(confirm); }}
+      />
+    </div>
+  );
+}
+
+/** A linked submission that is not among the form's latest ones: say so, and still show its real trace. */
+function SubmissionNotFound({ form, submissionId }: { form: FormRef; submissionId: string }) {
+  const trace = useG8Query(
+    (signal) => g8Get<{ capture_state?: string; receipts?: unknown[] }>(`/forms/${encodeURIComponent(form.form_key)}/submissions/${encodeURIComponent(submissionId)}/trace`, { source_id: form.source_id }, { signal }).then((r) => r.data),
+    [form.form_key, form.source_id, submissionId],
+  );
+  const receipts = pickItems<Record<string, unknown>>(trace.data, "receipts");
+  return (
+    <div className="grid gap-4">
+      <EmptyState
+        title="This submission is not in the latest 100"
+        description={`Submission ${submissionId} is older than the form's latest ${SUBMISSION_LOOKUP} submissions, so its fields and delivery are not shown here. Open it from the Submissions tab to see them and to retry a failed delivery.`}
+      />
+      <SectionCard title="Where did this lead go?" description={trace.data?.capture_state ? `Capture: ${trace.data.capture_state}` : undefined}>
+        {trace.error ? <ApiError error={trace.error} title="No trace for this submission" /> : trace.loading ? <Skeleton className="h-16 w-full" /> : receipts.length === 0 ? <p className="text-muted-foreground text-sm">No delivery steps recorded yet.</p> : (
+          receipts.map((r, i) => <pre key={i} className="overflow-x-auto rounded border p-2 text-xs">{JSON.stringify(r, null, 2)}</pre>)
+        )}
+      </SectionCard>
+    </div>
+  );
+}
+
+/** One submission in full: every submitted field, where it came from, its delivery, and the trace. */
+function SubmissionDetail({ form, submission, onChanged }: { form: FormRef; submission: FormSubmission; onChanged: () => void }) {
+  const [retrying, setRetrying] = useState(false);
+  const trace = useG8Query(
+    (signal) => g8Get<{ capture_state?: string; receipts?: unknown[] }>(`/forms/${encodeURIComponent(form.form_key)}/submissions/${encodeURIComponent(submission.id)}/trace`, { source_id: form.source_id }, { signal }).then((r) => r.data),
+    [form.form_key, form.source_id, submission.id],
+  );
+  const retry = useG8Mutation(() => g8Post(`/forms/deliveries/${encodeURIComponent(submission.delivery?.receipt_id ?? "")}/retry`), { onSuccess: () => { setRetrying(false); void trace.refetch(); onChanged(); } });
+  const fields = Object.entries(submission.form_data ?? {});
+  const receipts = pickItems<Record<string, unknown>>(trace.data, "receipts");
+  const failed = submissionFailed(submission);
+  return (
+    <div className="grid gap-4">
+      <div className="flex items-center gap-2">
+        <StatusPill tone={failed ? "negative" : submissionState(submission) === "delivered" ? "positive" : "neutral"}>{submissionState(submission)}</StatusPill>
+        {submission.is_test ? <StatusPill tone="info">Test</StatusPill> : null}
+        {failed && submission.delivery?.receipt_id ? <Button size="sm" variant="outline" onClick={() => { retry.reset(); setRetrying(true); }}>Retry delivery</Button> : null}
+      </div>
+      <SectionCard title="Submitted fields">
+        {fields.length === 0 ? <p className="text-muted-foreground text-sm">No fields were captured. Identifying fields may be redacted for your key.</p> : (
+          <KeyValueList columns={1} items={fields.map(([k, v]) => ({ label: k, value: cellText(v) || "Empty" }))} />
+        )}
+      </SectionCard>
+      <SectionCard title="Where it came from">
+        <KeyValueList
+          columns={2}
+          items={[
+            { label: "Received", value: submission.received_at ? new Date(submission.received_at).toLocaleString() : "Not set" },
+            { label: "Page", value: submission.page?.url ?? submission.page?.path ?? "Not set" },
+            { label: "Delivery", value: submissionState(submission) },
+            { label: "Reason", value: submission.delivery?.reason ?? "None" },
+            { label: "Receipt", value: submission.delivery?.receipt_id ?? "None" },
+            { label: "Submission id", value: submission.id },
+          ]}
+        />
+      </SectionCard>
+      <SectionCard title="Where did this lead go?" description={trace.data?.capture_state ? `Capture: ${trace.data.capture_state}` : undefined}>
+        {trace.error ? <ApiError error={trace.error} title="No trace for this submission" /> : trace.loading ? <Skeleton className="h-16 w-full" /> : receipts.length === 0 ? <p className="text-muted-foreground text-sm">No delivery steps recorded yet.</p> : (
+          receipts.map((r, i) => <pre key={i} className="overflow-x-auto rounded border p-2 text-xs">{JSON.stringify(r, null, 2)}</pre>)
+        )}
+      </SectionCard>
+      <ConfirmSpendDialog
+        open={retrying}
+        tier="external"
+        title="Retry delivering this lead?"
+        description={<><p>The lead is sent to the form's destination again, creating or updating a contact.</p>{retry.error ? <ApiError error={retry.error} title="Could not retry" /> : null}</>}
+        confirmLabel="Retry delivery"
+        confirming={retry.loading}
+        onCancel={() => { retry.reset(); setRetrying(false); }}
+        onConfirm={() => void retry.mutate(undefined)}
+      />
+    </div>
+  );
+}
+
+export function FormsScreen({ renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, className }: FormsScreenProps) {
+  const brand = useBrand();
+  const [tabParam, setTabParam] = useUrlState("tab", "forms");
+  const tab: Tab = tabParam === "install" || tabParam === "audit" ? tabParam : "forms";
+  const setTab = (next: Tab): void => setTabParam(next === "forms" ? null : next);
+  const [selectedKey, setSelectedKey] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const expandProps = { onExpand: () => setView("full"), onCollapse: view === "full" ? () => setView(null) : undefined };
+  const [text, setText] = useState("");
+  const [search, setSearch] = useState("");
+  const [health, setHealth] = useState("");
+  const [submissionId, setSubmissionId] = useUrlState("submission", "");
+  const [openedSubmission, setOpenedSubmission] = useState<FormSubmission | null>(null);
+  const [subsRefresh, setSubsRefresh] = useState(0);
+
+  // Debounce the search so each keystroke is not a request.
+  useEffect(() => {
+    const t = setTimeout(() => setSearch(text.trim()), 300);
+    return () => clearTimeout(t);
+  }, [text]);
+
+  const closeForm = (): void => { setView(null); setSelectedKey(null); setSubmissionId(null); setOpenedSubmission(null); };
+  const forms = useG8Query(
+    (signal) => g8Get<{ items?: FormListItem[]; total?: number }>("/forms", { page: 1, per_page: LIMIT, search: search || undefined }, { signal }).then((r) => ({ items: pickItems<FormListItem>(r.data, "items"), total: (r.data as { total?: number } | undefined)?.total ?? 0 })),
+    [search],
+  );
+  const items = forms.data?.items ?? [];
+  const total = forms.data?.total ?? items.length;
+  const shown = items.filter((f) => !health || formStatus(f) === health);
+  const ref = parseRef(selectedKey);
+  const selected: FormListItem | undefined = ref ? (items.find((f) => f.form_key === ref.form_key && f.source_id === ref.source_id) ?? { id: `${ref.source_id}:${ref.form_key}`, ...ref }) : undefined;
+  const sum = (pick: (f: FormListItem) => number | null | undefined): number => items.reduce((a, f) => a + (pick(f) ?? 0), 0);
+  // A `&submission=` link that was not clicked in this session (reload, shared link): find the real record in the
+  // form's latest submissions instead of rendering an empty stub as if it were data.
+  const needsLookup = Boolean(ref && submissionId) && openedSubmission?.id !== submissionId;
+  const lookup = useG8Query(
+    (signal) => g8Post<unknown>(`/forms/${encodeURIComponent(ref?.form_key ?? "")}/submissions`, { page: 1, per_page: SUBMISSION_LOOKUP, source_id: ref?.source_id }, { signal }).then((r) => {
+      const data = r.data as { submissions?: { items?: FormSubmission[] }; items?: FormSubmission[] } | undefined;
+      return (data?.submissions ?? data)?.items ?? [];
+    }),
+    [ref?.form_key, ref?.source_id, submissionId],
+    { enabled: needsLookup },
+  );
+  const linkedSubmission: FormSubmission | null = !submissionId ? null : openedSubmission?.id === submissionId ? openedSubmission : ((lookup.data ?? []).find((x) => x.id === submissionId) ?? null);
+
+  const rows = forms.error ? <ApiError error={forms.error} title="Could not load forms" onRetry={() => void forms.refetch()} /> : forms.loading && !forms.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState
+      icon={<ClipboardList className="size-8" />}
+      title={search || health ? "No forms match" : "No forms captured yet"}
+      description={search || health ? "Try another name or health." : `Install the ${brand.linkLabel} snippet on your site. Forms appear here after their first submission.`}
+      action={!search && !health ? <Button onClick={() => setTab("install")}>Get the install code</Button> : undefined}
+    />
+  ) : (
+    <ul className="grid gap-2">
+      {shown.map((f) => {
+        const status = formStatus(f);
+        const key = refKey(f);
+        return (
+          <li key={key} className={`flex items-center justify-between gap-3 rounded-md border p-3 ${key === selectedKey ? "bg-muted" : ""}`}>
+            <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setSelectedKey(key)}>
+              <span className="block truncate font-medium">{formLabel(f)}</span>
+              <span className="text-muted-foreground block truncate text-xs">{pageUrlText(f.page_url) || f.form_key}</span>
+              <span className="text-muted-foreground block text-xs">
+                {(f.total_submissions ?? 0).toLocaleString()} {pluralWord(f.total_submissions ?? 0, "submission")}{f.failed_submissions ? ` · ${f.failed_submissions} failed` : ""}{f.target_list_name ? ` · to ${f.target_list_name}` : ""}
+              </span>
+            </button>
+            <StatusPill tone={TONE[status]}>{STATUS_LABEL[status]}</StatusPill>
+            {renderRowActions?.(f)}
+          </li>
+        );
+      })}
+      {total > items.length ? <li className="text-muted-foreground text-xs">Showing the first {items.length} of {total.toLocaleString()} forms. Search to narrow down.</li> : null}
+    </ul>
+  );
+
+  const detail = selected ? (
+    <DetailPanel
+      title={formLabel(selected)}
+      subtitle={pageUrlText(selected.page_url) || selected.form_key}
+      badges={<StatusPill tone={TONE[formStatus(selected)]}>{STATUS_LABEL[formStatus(selected)]}</StatusPill>}
+      actions={renderDetailActions?.(selected)}
+      onClose={() => closeForm()}
+      {...expandProps}
+      tabs={[
+        { id: "overview", label: "Overview", content: <FormOverviewTab key={refKey(selected)} form={selected} onChanged={() => void forms.refetch()} /> },
+        { id: "setup", label: "Destination and fields", content: <FormMappingEditor key={refKey(selected)} form={selected} onSaved={() => void forms.refetch()} /> },
+        { id: "submissions", label: "Submissions", content: <SubmissionsTable key={`${refKey(selected)}:${subsRefresh}`} form={selected} selectedId={submissionId || undefined} onOpen={(sub) => { setOpenedSubmission(sub); setSubmissionId(sub.id); }} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })),
+      ]}
+    />
+  ) : null;
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Forms"
+      description="Capture the forms already on your site, route every lead to a list, and watch what arrives."
+      icon={<ClipboardList className="size-5" />}
+      tabs={[{ id: "forms", label: "Forms", count: total }, { id: "install", label: "Install" }, { id: "audit", label: "Site audit" }]}
+      activeTab={tab}
+      onTabChange={(id) => { setTab(id as Tab); closeForm(); }}
+      stats={tab === "forms" ? [
+        { label: "Forms", value: total.toLocaleString() },
+        { label: "Submissions", value: sum((f) => f.total_submissions).toLocaleString() },
+        { label: "Failed", value: sum((f) => f.failed_submissions).toLocaleString(), tone: sum((f) => f.failed_submissions) > 0 ? "negative" : "neutral" },
+        { label: "Need setup", value: items.filter((f) => formStatus(f) === "needs_setup").length.toLocaleString(), tone: "info" },
+      ] : undefined}
+      toolbar={tab === "forms" ? (
+        <Toolbar
+          search={{ value: text, onChange: setText, placeholder: "Search forms" }}
+          filters={(
+            <select aria-label="Form health" className={SELECT} value={health} onChange={(e) => setHealth(e.target.value)}>
+              <option value="">All health</option>
+              {Object.entries(STATUS_LABEL).map(([value, label]) => <option key={value} value={value}>{label}</option>)}
+            </select>
+          )}
+          actions={toolbarActions}
+        />
+      ) : undefined}
+    >
+      <FormSheet
+        open={Boolean(submissionId) && Boolean(selected)}
+        onOpenChange={(o) => { if (!o) { setSubmissionId(null); setOpenedSubmission(null); } }}
+        title="Submission"
+        description={selected ? formLabel(selected) : undefined}
+      >
+        {selected && submissionId ? (
+          linkedSubmission ? (
+            <SubmissionDetail key={submissionId} form={selected} submission={linkedSubmission} onChanged={() => setSubsRefresh((n) => n + 1)} />
+          ) : lookup.error ? (
+            <ApiError error={lookup.error} title="Could not load this submission" onRetry={() => void lookup.refetch()} />
+          ) : lookup.loading || !lookup.data ? (
+            <div aria-busy="true" className="grid gap-2"><Skeleton className="h-8 w-40" /><Skeleton className="h-32 w-full" /></div>
+          ) : (
+            <SubmissionNotFound form={selected} submissionId={submissionId} />
+          )
+        ) : null}
+      </FormSheet>
+      {tab === "install" ? <FormEmbed /> : tab === "audit" ? <SiteAuditPanel /> : (
+        <SplitView list={rows} detail={detail} detailOpen={Boolean(selected)} onCloseDetail={() => closeForm()} expanded={view === "full"} onExpandedChange={(e) => setView(e ? "full" : null)} detailWidth="xl" />
+      )}
+    </ScreenLayout>
+  );
+}

package/blocks/forms/components/submissions-table.tsx

@@ -21,6 +21,7 @@ import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { cellText, pickItems, submissionFailed, submissionState } from "../lib/form-types";
 import type { FormRef, FormSubmission } from "../lib/form-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface SubmissionsTableProps {
   /** The form to show. Omit it (for example as a stack nav page) and a form picker is shown instead. */
@@ -29,6 +30,10 @@ export interface SubmissionsTableProps {
   pageSize?: number;
   /** Max submitted-field columns. Default 4. */
   maxFieldColumns?: number;
+  /** When set, the received time of a row is a button that opens the full record (see FormsScreen). */
+  onOpen?: (submission: FormSubmission) => void;
+  /** The submission whose full record is open; its row is highlighted. */
+  selectedId?: string;
 }
 
 interface Page { items: FormSubmission[]; total: number }
@@ -59,14 +64,15 @@ function SubmissionTrace({ form, submission, onClose }: { form: FormRef; submiss
   );
 }
 
-export function SubmissionsTable({ form: given, pageSize = 20, maxFieldColumns = 4 }: SubmissionsTableProps) {
+export function SubmissionsTable({ form: given, pageSize = 20, maxFieldColumns = 4, onOpen, selectedId }: SubmissionsTableProps) {
+  const brand = useBrand();
   const [picked, setPicked] = useState<FormRef | undefined>(undefined);
   const forms = useG8Query((signal) => g8Get<unknown>("/forms", { per_page: 100 }, { signal }).then((r) => pickItems<FormRef & { display_name?: string | null }>(r.data, "items")), [], { enabled: !given });
   const form = given ?? picked;
   if (!form) {
     if (forms.error) return <ApiError error={forms.error} title="Could not load forms" onRetry={() => void forms.refetch()} />;
     if (forms.loading && !forms.data) return <Skeleton className="h-9 w-64" aria-busy="true" />;
-    if ((forms.data ?? []).length === 0) return <EmptyState title="No forms captured yet" description="Install the graph8 snippet on your site; forms appear after their first submission." />;
+    if ((forms.data ?? []).length === 0) return <EmptyState title="No forms captured yet" description={`Install the ${brand.linkLabel} snippet on your site; forms appear after their first submission.`} />;
     return (
       <select aria-label="Choose a form" className="border-input bg-background h-9 max-w-sm rounded-md border px-2 text-sm" defaultValue="" onChange={(e) => { const f = forms.data?.[Number(e.target.value)]; if (f) setPicked({ form_key: f.form_key, source_id: f.source_id }); }}>
         <option value="" disabled>Choose a form</option>
@@ -75,10 +81,10 @@ export function SubmissionsTable({ form: given, pageSize = 20, maxFieldColumns =
     );
   }
   // Keyed on the form: page, trace and retry state belong to one form.
-  return <SubmissionsFor key={`${form.source_id}:${form.form_key}`} form={form} pageSize={pageSize} maxFieldColumns={maxFieldColumns} />;
+  return <SubmissionsFor key={`${form.source_id}:${form.form_key}`} form={form} pageSize={pageSize} maxFieldColumns={maxFieldColumns} onOpen={onOpen} selectedId={selectedId} />;
 }
 
-function SubmissionsFor({ form, pageSize, maxFieldColumns }: { form: FormRef; pageSize: number; maxFieldColumns: number }) {
+function SubmissionsFor({ form, pageSize, maxFieldColumns, onOpen, selectedId }: { form: FormRef; pageSize: number; maxFieldColumns: number; onOpen?: (s: FormSubmission) => void; selectedId?: string }) {
   const [page, setPage] = useState(1);
   const [traceOf, setTraceOf] = useState<FormSubmission | null>(null);
   const [retrying, setRetrying] = useState<FormSubmission | null>(null);
@@ -123,8 +129,12 @@ function SubmissionsFor({ form, pageSize, maxFieldColumns }: { form: FormRef; pa
         </TableHeader>
         <TableBody>
           {items.map((s) => (
-            <TableRow key={s.id}>
-              <TableCell>{s.received_at ? new Date(s.received_at).toLocaleString() : ""}{s.is_test ? " (test)" : ""}</TableCell>
+            <TableRow key={s.id} data-state={selectedId === s.id ? "selected" : undefined}>
+              <TableCell>
+                {onOpen ? (
+                  <button type="button" className="text-left hover:underline" aria-label={`Open submission ${s.id}`} onClick={() => onOpen(s)}>{s.received_at ? new Date(s.received_at).toLocaleString() : s.id}{s.is_test ? " (test)" : ""}</button>
+                ) : <>{s.received_at ? new Date(s.received_at).toLocaleString() : ""}{s.is_test ? " (test)" : ""}</>}
+              </TableCell>
               {columns.map((c) => <TableCell key={c}>{cellText(s.form_data?.[c])}</TableCell>)}
               <TableCell className={submissionFailed(s) ? "text-red-700" : undefined}>{submissionState(s)}</TableCell>
               <TableCell className="text-right">

package/blocks/inbox/README.md

@@ -7,6 +7,23 @@ copy `InboxScreen`, the finished two-pane page.
 Depends on: `crm` (the contact on each thread), `mailboxes` (the connected sending mailboxes). Install with
 `npx @graph8/sdk add inbox`.
 
+## Screens
+
+`InboxScreen` (`components/inbox-screen.tsx`) is the finished page; it needs no props. Stat strip, channel / status /
+tag filters, search of the loaded page, paged list, and the open conversation (reply composer with confirmed AI draft
+and send, tag and assign). Open conversations deep-link as `?id=<channel>:<thread id>`. Optional slots:
+`toolbarActions`, `renderRowActions(thread)`, `renderDetailActions(thread)`, `extraDetailTabs`, `pageSize`.
+Needs scopes `inbox:read`, `inbox:write`, `inbox:run` (plus `campaigns:read` for the SMS sender picker) and a mailbox
+connected in the graph8 app (a link-out card says so).
+
+**Behaviour change.** Compared with the original two-pane `InboxScreen`, the finished page now writes `?id=` and
+`?view=` to the host page URL and renders its own header (an "Inbox" h1, description and stats). If your page
+already has a title or owns those query keys, pass `urlState={false}` (the open conversation lives in component
+state, the URL is untouched) and/or `hideHeader` (no title or stats, just search, filters, Refresh and the two panes).
+Defaults are unchanged from this release: both are on.
+
+Every detail opens as a full page with `&view=full` (the Open full page button).
+
 ## The flow, in order
 
 1. **List** `GET /inbox?channel=&status=&page=&page_size=` (`InboxList`). Each row has `id` and `channel`.
@@ -18,8 +35,12 @@ Depends on: `crm` (the contact on each thread), `mailboxes` (the connected sendi
    `shorten` / `expand` / `fix_grammar_spelling` rework the text you pass in `message_html`. The response
    `data.content` is HTML and `data.plain_content` is text. It sends nothing.
 4. **Send** `POST /inbox/{reply_id}/send` (`ReplyComposer`, **external**, confirm first) with
-   `{ channel, body, subject?, to? }`. The composer sends an `Idempotency-Key` so a double click cannot
-   send twice.
+   `{ channel, body, subject?, to, from_address }`. `from_address` is the thread's own sender: `thread.mailbox`
+   (email), `thread.from_number` (SMS) or `thread.linkedin_account_id` (LinkedIn); `to` is the thread's contact
+   (`contact.email`, or `thread.to_number` for SMS). If an SMS or LinkedIn thread names no sender, the composer
+   shows a picker filled from `GET /sms/phone-numbers` or `GET /inbox/linkedin/accounts`. The API fills both
+   from the thread when omitted (older API versions refused the send with 400). The composer sends an
+   `Idempotency-Key` so a double click cannot send twice.
 5. **Route** (`TagAndAssign`): `POST /inbox/tags` creates a tag (write), `POST /inbox/{id}/tag?channel=`
    applies tag ids and `POST /inbox/{id}/assign?channel=` hands the thread to a teammate by email. Both of
    those are **external** (confirm first) because they can fire automations and notify people.
@@ -31,13 +52,14 @@ IDs passed between steps: `thread.id` + `thread.channel` (list -> view -> draft/
 
 - Connect a mailbox in the graph8 app (Google / Microsoft OAuth exists only there; see the `mailboxes` block).
   Until then the inbox has no email threads. `where: "app"`.
-- Give the proxy's API key `inbox:read`, `inbox:write` and `inbox:run`.
+- Give the proxy's API key `inbox:read`, `inbox:write` and `inbox:run` (and `campaigns:read` for the SMS sender picker).
 - Credits for AI drafts (402 when none; there is no balance read, so the confirm dialog shows no estimate).
 
 ## Defaults (the agent does not need to ask)
 
 - AI drafts are only ever written into the reply box. Sending is always a separate, confirmed click.
 - Tone `professional`, goal `follow_up`.
+- A reply leaves from the thread's own mailbox, number or LinkedIn account and goes to the thread's contact.
 - No assignee filter: the API cannot filter by an arbitrary assignee email (an org key owns no threads), so
   filter `thread.assignees` client-side if you need it.
 - Ask the human only about **tags**: there is no list-tags operation. Pass `availableTags` from your own
@@ -60,6 +82,8 @@ IDs passed between steps: `thread.id` + `thread.channel` (list -> view -> draft/
 | `inbox.getReply` | GET /inbox/{reply_id} | read | ThreadView, useInboxThread |
 | `aiInbox.generateInboxDraft` | POST /inbox/drafts/generate | billable | ReplyComposer |
 | `inbox.sendReply` | POST /inbox/{reply_id}/send | external | ReplyComposer |
+| `channels.listSmsPhoneNumbers` | GET /sms/phone-numbers | read | ReplyComposer (SMS sender picker) |
+| `aiInbox.listInboxLinkedinAccounts` | GET /inbox/linkedin/accounts | read | ReplyComposer (LinkedIn sender picker) |
 | `aiInbox.listInboxUsers` | GET /inbox/users | read | TagAndAssign |
 | `aiInbox.createInboxTag` | POST /inbox/tags | write | TagAndAssign |
 | `inbox.tagReply` | POST /inbox/{reply_id}/tag | external | TagAndAssign |

package/blocks/inbox/block.json

@@ -20,7 +20,9 @@
     "generate_inbox_draft_inbox_drafts_generate_post",
     "get_reply_inbox__reply_id__get",
     "list_inbox_inbox_get",
+    "list_inbox_linkedin_accounts_inbox_linkedin_accounts_get",
     "list_inbox_users_inbox_users_get",
+    "list_sms_phone_numbers_sms_phone_numbers_get",
     "send_reply_inbox__reply_id__send_post",
     "tag_reply_inbox__reply_id__tag_post"
   ],
@@ -50,12 +52,15 @@
     {
       "name": "ReplyComposer",
       "file": "components/reply-composer.tsx",
-      "purpose": "Write a reply, draft or reshape it with AI (confirm, billable) and send it on the thread's channel (confirm, external).",
+      "purpose": "Write a reply, draft or reshape it with AI (confirm, billable) and send it from the thread's own mailbox, number or LinkedIn account to its contact (confirm, external); picks a sender when an SMS or LinkedIn thread names none.",
       "operations": [
         "generate_inbox_draft_inbox_drafts_generate_post",
+        "list_inbox_linkedin_accounts_inbox_linkedin_accounts_get",
+        "list_sms_phone_numbers_sms_phone_numbers_get",
         "send_reply_inbox__reply_id__send_post"
       ],
       "tiers": [
+        "read",
         "billable",
         "external"
       ]
@@ -157,6 +162,7 @@
     }
   ],
   "scopes": [
+    "campaigns:read",
     "inbox:read",
     "inbox:run",
     "inbox:write"
@@ -186,9 +192,15 @@
       "decision": "Filter by assignee",
       "default": "Not offered: the API cannot filter by an arbitrary assignee email (an org key owns no threads). Filter thread.assignees client-side",
       "askHuman": false
+    },
+    {
+      "decision": "Which mailbox, number or LinkedIn account a reply is sent from",
+      "default": "The thread's own (mailbox / from_number / linkedin_account_id on the thread); an SMS or LinkedIn thread without one shows a sender picker",
+      "askHuman": false
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }

package/blocks/inbox/components/inbox-list.tsx

@@ -25,8 +25,12 @@ import {
   type InboxChannel,
   type InboxThread,
 } from "../lib/inbox-types";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
 
 export interface InboxListProps {
+  /** URL param the host screen reads for this record type. With it the name is a real link (Cmd-click opens it in a new tab); without it a plain button. */
+  linkParam?: string;
   onSelect?: (thread: InboxThread) => void;
   selectedId?: string | null;
   /** Start with these filters (for example a tag id from the URL). */
@@ -62,7 +66,7 @@ function LoadingRows() {
   );
 }
 
-export function InboxList({ onSelect, selectedId, initialFilters, pageSize = 25, onFiltersChange, className }: InboxListProps) {
+export function InboxList({ linkParam, onSelect, selectedId, initialFilters, pageSize = 25, onFiltersChange, className }: InboxListProps) {
   const [filters, setFilters] = useState<InboxFilters>(initialFilters ?? {});
   const [page, setPage] = useState(1);
   const { threads, loading, error, hasNext, total, refetch } = useInboxThreads(filters, page, pageSize);
@@ -123,9 +127,9 @@ export function InboxList({ onSelect, selectedId, initialFilters, pageSize = 25,
                 key={`${thread.channel}:${thread.id}`}
                 data-state={selectedId === thread.id ? "selected" : undefined}
                 className="cursor-pointer"
-                onClick={() => onSelect?.(thread)}
+                {...rowActivationProps(() => onSelect?.(thread))}
               >
-                <TableCell className="max-w-48 truncate font-medium">{contactLabel(thread)}</TableCell>
+                <TableCell className="max-w-48 truncate font-medium">{onSelect ? <RecordLink param={linkParam} id={thread.id} onOpen={() => onSelect(thread)}>{contactLabel(thread)}</RecordLink> : contactLabel(thread)}</TableCell>
                 <TableCell className="max-w-80 truncate text-muted-foreground">
                   {thread.subject ? <span className="text-foreground">{thread.subject} </span> : null}
                   {previewText(thread)}