@graph8/sdk 0.358.0 → 0.362.0

package/blocks/deals/hooks/use-default-owner.ts

@@ -0,0 +1,60 @@
+"use client";
+
+/**
+ * useDefaultOwner: who owns a deal created in the UI when nobody picked an owner.
+ *
+ * graph8 requires an owner on every deal. The rule (documented in the README defaults, so no agent has to ask):
+ *   1. the API key's own user: GET /team-members/me (roster record of the person who minted a PERSONAL key);
+ *   2. otherwise the first active team member of GET /team-members (an organisation key has no person, and
+ *      /team-members/me answers 403 for it), which the screen shows in an owner picker the person can change.
+ *
+ * SDK operations, in order:
+ *   1. GET /team-members/me   (teamMembers.getMyTeamMember)  read  - may be refused for an organisation key
+ *   2. GET /team-members      (teamMembers.listTeamMembers)  read  - the picker options
+ *
+ * `owner_id` accepts a user id or an email; this hook prefers the identity-provider user id and falls back to the email.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { dataOf } from "../lib/deals-types";
+
+interface TeamMember {
+  id?: string;
+  name?: string | null;
+  email?: string | null;
+  propelauth_user_id?: string | null;
+  status?: string | null;
+}
+
+export interface OwnerOption {
+  /** The value to send as `owner_id`. */
+  id: string;
+  name: string;
+  email?: string | null;
+}
+
+export type OwnerSource = "key" | "first-member" | "none";
+
+function toOption(m: TeamMember | null | undefined): OwnerOption | null {
+  const id = m?.propelauth_user_id || m?.email || null;
+  return m && id ? { id, name: m.name || m.email || id, email: m.email } : null;
+}
+
+function membersOf(env: unknown): TeamMember[] {
+  const inner = dataOf<unknown>(env);
+  if (Array.isArray(inner)) return inner as TeamMember[];
+  const o = inner as { items?: unknown; team_members?: unknown } | null;
+  const list = o?.items ?? o?.team_members;
+  return Array.isArray(list) ? (list as TeamMember[]) : [];
+}
+
+export function useDefaultOwner() {
+  const me = useG8Query(async (signal) => toOption(dataOf<TeamMember>(await g8Get("/team-members/me", undefined, { signal }))), []);
+  const team = useG8Query(async (signal) => membersOf(await g8Get("/team-members", { limit: 200 }, { signal })).filter((m) => !m.status || m.status === "active").map(toOption).filter((o): o is OwnerOption => o !== null), []);
+  const mine = me.data ?? null; // a refused /team-members/me (organisation key) is expected, not an error to show
+  const owners = team.data ?? [];
+  const all = mine && !owners.some((o) => o.id === mine.id) ? [mine, ...owners] : owners;
+  const defaultOwner = mine ?? all[0] ?? null;
+  const source: OwnerSource = mine ? "key" : defaultOwner ? "first-member" : "none";
+  return { owners: all, defaultOwner, source, loading: me.loading || (team.loading && !defaultOwner), error: all.length === 0 ? team.error : undefined, reload: team.refetch };
+}

package/blocks/deals/lib/deals-types.ts

@@ -80,6 +80,20 @@ export function sumAmounts(deals: ReadonlyArray<Pick<Deal, "amount">>): number {
   return deals.reduce((total, d) => total + (d.amount ?? 0), 0);
 }
 
+/**
+ * Money for a group of deals that may span currencies: one formatted total per currency, joined with " + "
+ * ("$1,200 + €300"). A single currency formats exactly like formatMoney. `valueOf` defaults to the amount sum.
+ */
+export function sumMoney(deals: ReadonlyArray<Deal>, valueOf: (group: ReadonlyArray<Deal>) => number = sumAmounts, fallbackCurrency?: string | null): string {
+  const groups = new Map<string, Deal[]>();
+  for (const d of deals) {
+    const key = d.currency || "USD";
+    groups.set(key, [...(groups.get(key) ?? []), d]);
+  }
+  if (groups.size <= 1) return formatMoney(valueOf(deals), deals[0]?.currency ?? fallbackCurrency);
+  return [...groups].map(([currency, group]) => formatMoney(valueOf(group), currency)).join(" + ");
+}
+
 /**
  * Probability-weighted value of open deals. This is an ESTIMATE computed here: the analytics endpoint refuses to
  * return a weighted total because a stage's probability defaults to 0 when nobody configured it, which would

package/blocks/forms/README.md

@@ -5,6 +5,17 @@ snippet, lists them, and routes every submission to a list with a field mapping.
 that: install the code (`FormEmbed`), set where leads go and how fields map (`FormBuilder`), see what arrived and
 retry failures (`SubmissionsTable`), and find forms that are not captured (`SiteAuditPanel`).
 
+## Screens
+
+`FormsScreen` (`components/forms-screen.tsx`) is the finished page: install code, captured forms, routing and submissions in one place.
+
+```tsx
+import { FormsScreen } from "@/g8/forms/components/forms-screen";
+export default function Page() { return <FormsScreen />; }
+```
+
+Flows: copy the snippet and ready-made lead form (Install tab, `?tab=install`), see every captured form with health and counts (search is debounced; the first 100 are listed), open one (deep link `?id=<source_id>/<form_key>`; a submission opens in a sheet at `&submission=<id>` with every field, its delivery and trace) to rename it, pause or resume delivery (confirmed), choose the destination list and map fields (suggest, preview, save, test), read submissions, trace a lead and retry a failed delivery (confirmed), and find forms that are not captured (Site audit tab, `?tab=audit`). A `&submission=` link opened cold (reload, shared link) is looked up in the form's latest 100 submissions; an older one shows its trace and points to the Submissions tab. Optional props: `renderRowActions`, `renderDetailActions`, `extraDetailTabs`, `toolbarActions`.
+
 ## Install
 
 ```
@@ -78,6 +89,7 @@ export default function FormsPage() {
 
 | Component | File | What it is |
 |---|---|---|
+| `FormsScreen` | `components/forms-screen.tsx` | The finished page: install code, captured forms, routing, submissions and site audit. |
 | `FormBuilder` | `components/form-builder.tsx` | Forms workspace: list captured forms, rename, pause/resume delivery, set destination and mapping, view submissions. |
 | `FormMappingEditor` | `components/form-mapping-editor.tsx` | Pick the destination list and map submitted fields to contact fields, with suggest, preview, save and test. |
 | `FormEmbed` | `components/form-embed.tsx` | Copyable tracking snippet (script tag, React) and a ready-made lead-capture form with live preview. |

package/blocks/forms/block.json

@@ -37,6 +37,13 @@
     "update_site_audit_finding_forms_site_audit_findings__finding_id__patch"
   ],
   "components": [
+    {
+      "name": "FormsScreen",
+      "file": "components/forms-screen.tsx",
+      "purpose": "Finished forms workspace: captured forms with health, detail (overview, destination and fields, submissions), install code and site audit tabs.",
+      "operations": [],
+      "tiers": []
+    },
     {
       "name": "FormBuilder",
       "file": "components/form-builder.tsx",
@@ -195,6 +202,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }

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

@@ -0,0 +1,350 @@
+"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";
+
+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 [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 graph8 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()} {(f.total_submissions ?? 0) === 1 ? "submission" : "submissions"}{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

@@ -29,6 +29,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,7 +63,7 @@ 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 [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;
@@ -75,10 +79,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 +127,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/lifecycle/README.md

@@ -13,6 +13,22 @@ These five are ONE parametrised view keyed by stage, not five features: the stag
 | `ChurnList` | Churned companies, last MRR, on-demand activity check, win-back to Leads. |
 | `useLifecycleStages` (hook) | Stages and their counts. |
 
+## Screens
+
+`LifecycleScreen` (`components/lifecycle-screen.tsx`): `<LifecycleScreen />`.
+
+- A count per stage as headline numbers, then a Board tab and one tab per stage (custom stages included).
+- Board: columns of companies with Move (a dry run shows refusals first, for example Customers without an active
+  subscription). Customers tab: the book of business with MRR, headline counts and the account brief (rewriting it
+  uses credits, confirmed). Churned tab: lost revenue, an activity check and a win-back to Leads. Every other stage is
+  a contact queue with search; locked emails are unlocked with credits (confirmed) and contacts can be moved.
+- Open a company or contact (deep link `?rec=company:<id>` or `?rec=contact:<id>`) to get the crm block's full record
+  (activity, notes, tasks, edit) with a **Move stage** action.
+- Slots, all optional: `renderDetailActions(record)`, `extraDetailTabs`, `toolbarActions`.
+
+Proxy `allowedPrefixes` must also include the crm block's prefixes for the record panel.
+
+
 ## Flow, in order (and the ids passed between steps)
 
 1. `GET /lifecycle-stages` -> each stage has `id` (entry id) and `slug` (`suspects`, `leads`, `trials`, `customers`, `churned`).

package/blocks/lifecycle/block.json

@@ -98,6 +98,27 @@
         "read",
         "write"
       ]
+    },
+    {
+      "name": "LifecycleScreen",
+      "file": "components/lifecycle-screen.tsx",
+      "purpose": "Finished lifecycle product: board, one tab per stage (contact queue, customers, churned) and a CRM record panel with Move stage.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "AccountBriefTab",
+      "file": "components/account-related.tsx",
+      "purpose": "Account views for the record panel: the customer-success brief (rewrite is billable and confirmed) and AccountSignalsTab, recent intent signals.",
+      "operations": [
+        "get_brief_customer_success_companies__company_id__brief_get",
+        "synthesize_brief_customer_success_companies__company_id__brief_synthesize_post",
+        "get_account_intent_signals_accounts__account_id__intent_signals_get"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
     }
   ],
   "hooks": [
@@ -193,6 +214,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }