@graph8/sdk 0.362.0 → 0.373.0

package/blocks/visitors/components/snippet-install.tsx

@@ -18,9 +18,12 @@ import { useState } from "react";
 import { Button, Skeleton } from "@graph8/sdk/ui";
 import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import { hasNextOf } from "@/g8/lib/paging";
 import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { ApiError } from "@/g8/components/api-error";
 import { EmptyState } from "@/g8/components/empty-state";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface SnippetInstallProps {
   /** Pre-select a stream id (from listOrgStreams). Default: the org's main stream. */
@@ -71,7 +74,7 @@ function CodeBlock({ label, code }: { label: string; code: string }) {
           {copied ? "Copied" : "Copy"}
         </Button>
       </div>
-      <pre className="overflow-x-auto rounded bg-gray-950 p-3 text-xs text-gray-100">
+      <pre className="overflow-x-auto rounded bg-muted p-3 text-xs text-foreground">
         <code>{code}</code>
       </pre>
     </div>
@@ -98,32 +101,40 @@ function InstallCheck({ writeKey, onInstalled }: { writeKey: string; onInstalled
       </Button>
       {check.error ? <ApiError error={check.error} /> : null}
       {s?.status === "receiving" ? (
-        <p role="status" className="text-sm text-green-700">
+        <p role="status" className="text-sm text-positive-foreground">
           Installed: {s.event_count.toLocaleString()} events received.
         </p>
       ) : null}
       {s?.status === "unknown" ? (
-        <p role="status" className="text-sm text-amber-700">
+        <p role="status" className="text-sm text-warning-foreground">
           Your workspace cannot be probed yet. Open your site once and check the Visitors feed.
         </p>
       ) : null}
       {s?.status === "no_events" && !check.polling ? (
-        <p role="status" className="text-sm text-gray-600">
+        <p role="status" className="text-sm text-muted-foreground">
           No events yet. Load a page that has the snippet, then check again.
         </p>
       ) : null}
       {s?.status === "no_events" && check.polling ? (
-        <p className="text-sm text-gray-600">No events yet. Open a page that has the snippet.</p>
+        <p className="text-sm text-muted-foreground">No events yet. Open a page that has the snippet.</p>
       ) : null}
     </div>
   );
 }
 
+/** Streams per read: every page is read, so the stream picker offers all of them. */
+const STREAM_PAGE = 50;
+
 export function SnippetInstall({ streamId, onInstalled, className }: SnippetInstallProps) {
+  const brand = useBrand();
   const [selected, setSelected] = useState<string | undefined>(streamId);
-  const streams = useG8Query((signal) => g8Get<Stream[]>("/streams", { limit: 50 }, { signal }), []);
+  const streams = useAllPages<Stream>(async (page, signal) => {
+    const env = await g8Get<Stream[]>("/streams", { page, limit: STREAM_PAGE }, { signal });
+    const rows = env.data ?? [];
+    return { rows, hasNext: hasNextOf(env, STREAM_PAGE, rows.length) };
+  }, []);
   const snippet = useG8Query((signal) => g8Get<SnippetPayload>("/snippet", { stream_id: selected }, { signal }), [selected]);
-  const list = streams.data?.data ?? [];
+  const list = streams.items;
 
   if (snippet.error) return <ApiError error={snippet.error} onRetry={() => void snippet.refetch()} className={className} />;
   if (snippet.loading && !snippet.data) return <Skeleton className={`h-40 w-full ${className ?? ""}`} />;
@@ -132,7 +143,7 @@ export function SnippetInstall({ streamId, onInstalled, className }: SnippetInst
     return (
       <EmptyState
         title="No tracking stream yet"
-        description="Create a website stream in graph8 first, then come back for its snippet."
+        description={`Create a website stream in ${brand.linkLabel} first, then come back for its snippet.`}
         className={className}
       />
     );
@@ -143,7 +154,7 @@ export function SnippetInstall({ streamId, onInstalled, className }: SnippetInst
         <label className="flex items-center gap-2 text-sm">
           Website
           <select
-            className="rounded border border-gray-300 px-2 py-1"
+            className="rounded border border-input px-2 py-1"
             value={selected ?? s.stream_id ?? ""}
             onChange={(e) => setSelected(e.target.value || undefined)}
           >
@@ -157,7 +168,7 @@ export function SnippetInstall({ streamId, onInstalled, className }: SnippetInst
         </label>
       ) : null}
       {s.warning ? (
-        <p role="alert" className="rounded border border-amber-200 bg-amber-50 p-2 text-sm text-amber-900">
+        <p role="alert" className="rounded border border-warning-foreground/25 bg-warning p-2 text-sm text-warning-foreground">
           {s.warning}
         </p>
       ) : null}

package/blocks/visitors/components/traffic-chart.tsx

@@ -62,7 +62,7 @@ export function LineChart({ points, metric }: { points: TrendPoint[]; metric: Me
   const y = (v: number) => height - (v / max) * (height - 12) - 6;
   const path = values.map((v, i) => `${i === 0 ? "M" : "L"}${x(i).toFixed(1)},${y(v).toFixed(1)}`).join(" ");
   return (
-    <svg viewBox={`0 0 ${width} ${height}`} role="img" aria-label={`${metric} per day`} className="h-40 w-full text-blue-600">
+    <svg viewBox={`0 0 ${width} ${height}`} role="img" aria-label={`${metric} per day`} className="h-40 w-full text-foreground">
       <path d={path} fill="none" stroke="currentColor" strokeWidth="2" />
       {values.map((v, i) => (
         <circle key={points[i].date} cx={x(i)} cy={y(v)} r="2.5" fill="currentColor">
@@ -113,7 +113,7 @@ export function TrafficChart({ days = 30, writeKey, realtimeSeconds = 10, classN
             </Button>
           ))}
         </div>
-        <p className="text-sm text-gray-600" aria-live="polite">
+        <p className="text-sm text-muted-foreground" aria-live="polite">
           {now != null ? `${now} on the site now` : ""}
         </p>
       </div>
@@ -126,7 +126,7 @@ export function TrafficChart({ days = 30, writeKey, realtimeSeconds = 10, classN
         <EmptyState title="No traffic yet" description="Install the snippet and visits will chart here." />
       ) : (
         <div>
-          <p className="text-sm text-gray-600">
+          <p className="text-sm text-muted-foreground">
             {total.toLocaleString()} {METRICS.find((m) => m.key === metric)?.label.toLowerCase()} in {days} days
           </p>
           <LineChart points={points} metric={metric} />
@@ -136,7 +136,7 @@ export function TrafficChart({ days = 30, writeKey, realtimeSeconds = 10, classN
       {topPages.length > 0 ? (
         <table className="w-full text-sm">
           <thead>
-            <tr className="text-left text-gray-500">
+            <tr className="text-left text-muted-foreground">
               <th className="py-1">Top pages</th>
               <th className="py-1 text-right">Views</th>
             </tr>

package/blocks/visitors/components/visitor-company-card.tsx

@@ -17,10 +17,13 @@ import { useState } from "react";
 import type { ReactNode } from "react";
 import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton } from "@graph8/sdk/ui";
 import { g8Get } from "@/g8/lib/g8-client";
-import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { byPage, hasNextOf } from "@/g8/lib/paging";
+import { LoadMore } from "@/g8/components/paging-notices";
 import { ApiError } from "@/g8/components/api-error";
 import { companyLabel, pageLabel, pageOf, timeAgo } from "../lib/visitors-utils";
 import type { FlowEvent, VisitorGroup } from "../lib/visitors-utils";
+import { plural } from "@/g8/lib/plural";
 
 export interface VisitorCompanyCardProps {
   visit: VisitorGroup;
@@ -31,33 +34,41 @@ export interface VisitorCompanyCardProps {
 }
 
 function PageList({ pages }: { pages: FlowEvent[] }) {
-  if (pages.length === 0) return <p className="text-sm text-gray-500">No page views recorded.</p>;
+  if (pages.length === 0) return <p className="text-sm text-muted-foreground">No page views recorded.</p>;
   return (
     <ol className="space-y-1 text-sm">
       {pages.map((p, i) => (
         <li key={p.message_id ?? `${p.received_at}-${i}`} className="flex justify-between gap-3">
           <span className="truncate">
             {pageLabel(p)}
-            {p.page_referrer ? <span className="ml-2 text-xs text-gray-400">from {p.page_referrer}</span> : null}
+            {p.page_referrer ? <span className="ml-2 text-xs text-muted-foreground">from {p.page_referrer}</span> : null}
           </span>
-          <span className="shrink-0 text-xs text-gray-500">{timeAgo(p.received_at)}</span>
+          <span className="shrink-0 text-xs text-muted-foreground">{timeAgo(p.received_at)}</span>
         </li>
       ))}
     </ol>
   );
 }
 
+/** Page views per read; "Load more" appends the next page of the journey. */
+const JOURNEY_PAGE = 100;
+
 function Journey({ companyId }: { companyId: number }) {
-  const journey = useG8Query(
-    (signal) =>
-      g8Get("/visitors/companies/events", { show_mode: "raw", filter: JSON.stringify({ company_id: companyId }), limit: 100 }, { signal }),
-    [companyId],
-  );
-  if (journey.loading) return <Skeleton className="h-16 w-full" />;
+  const journey = useLoadMoreList(byPage<FlowEvent>(JOURNEY_PAGE, async (page, signal) => {
+    const env = await g8Get("/visitors/companies/events", { show_mode: "raw", filter: JSON.stringify({ company_id: companyId }), page, limit: JOURNEY_PAGE }, { signal });
+    // Raw mode returns one row per page view.
+    const rows = pageOf(env).events as unknown as FlowEvent[];
+    return { rows, hasNext: hasNextOf(env, JOURNEY_PAGE, rows.length) };
+  }), [companyId]);
+  if (journey.loading && !journey.data) return <Skeleton className="h-16 w-full" />;
   if (journey.error) return <ApiError error={journey.error} onRetry={() => void journey.refetch()} />;
-  // Raw mode returns one row per page view.
-  const views = pageOf(journey.data).events as unknown as FlowEvent[];
-  return <PageList pages={views} />;
+  const views = journey.data ?? [];
+  return (
+    <>
+      <PageList pages={views} />
+      <LoadMore shown={views.length} noun="page views" hasMore={journey.hasMore} loading={journey.loadingMore} onLoadMore={journey.loadMore} />
+    </>
+  );
 }
 
 export function VisitorCompanyCard({ visit, previewPages = 5, actions, className }: VisitorCompanyCardProps) {
@@ -68,9 +79,8 @@ export function VisitorCompanyCard({ visit, previewPages = 5, actions, className
       <CardHeader className="flex flex-row items-start justify-between gap-3">
         <div>
           <CardTitle className="text-base">{companyLabel(visit)}</CardTitle>
-          <p className="text-xs text-gray-500">
-            {visit.COMPANY_DOMAIN ? `${visit.COMPANY_DOMAIN} - ` : ""}last seen {timeAgo(visit.received_at)} - {pages.length} page view
-            {pages.length === 1 ? "" : "s"}
+          <p className="text-xs text-muted-foreground">
+            {visit.COMPANY_DOMAIN ? `${visit.COMPANY_DOMAIN} - ` : ""}last seen {timeAgo(visit.received_at)} - {plural(pages.length, "page view")}
           </p>
         </div>
         {actions ? <div className="flex gap-2">{actions}</div> : null}

package/blocks/visitors/components/visitor-detail.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+/**
+ * VisitorDetail: the complete screen for one visitor, a visiting company or an identified person. Shows every field the feed
+ * carries (name, domain, ids, last seen, visit count), every page viewed with its referrer, and, for a company, the full journey of
+ * raw page views. Pass the grouped row from VisitorFeed, or just `kind` and `id` (a deep link): the row is then found in the latest
+ * 100 grouped visits.
+ *
+ * SDK operations, in order (all read tier, nothing billable or external):
+ *   1. listCompanyVisitorEvents  GET /visitors/companies/events  (show_mode=grouped to find the row; show_mode=raw with filter={"company_id": id} for the journey)
+ *   2. listContactVisitorEvents  GET /visitors/contacts/events   (show_mode=grouped to find the row; needs contacts:read too)
+ */
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+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 { SectionCard } from "@/g8/components/screen/section-card";
+import { companyLabel, pageLabel, pageOf, personLabel, timeAgo } from "../lib/visitors-utils";
+import type { FlowEvent, VisitorGroup } from "../lib/visitors-utils";
+import { VisitorCompanyCard } from "./visitor-company-card";
+
+export interface VisitorDetailProps {
+  kind: "company" | "person";
+  /** COMPANY_ID for a company, CONTACT_ID for a person. */
+  id: number;
+  /** The row from the feed; without it the screen looks it up. */
+  visit?: VisitorGroup | null;
+  /** Buttons in the header (for example "Open contact" or "Add to list"). */
+  actions?: React.ReactNode;
+  /** Extra tabs from the screen's `extraDetailTabs` slot, after the built-in ones. */
+  extraTabs?: { id: string; label: string; content: React.ReactNode }[];
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+}
+
+function Pages({ pages }: { pages: FlowEvent[] }) {
+  if (pages.length === 0) return <p className="text-sm text-muted-foreground">No page views recorded.</p>;
+  return (
+    <ol className="space-y-1.5 text-sm">
+      {pages.map((p, i) => (
+        <li key={p.message_id ?? `${p.received_at}-${i}`} className="flex justify-between gap-3">
+          <span className="min-w-0 truncate">
+            {pageLabel(p)}
+            {p.page_path ? <span className="ml-2 text-xs text-muted-foreground">{p.page_path}</span> : null}
+            {p.page_referrer ? <span className="ml-2 text-xs text-muted-foreground">from {p.page_referrer}</span> : null}
+          </span>
+          <span className="shrink-0 text-xs text-muted-foreground">{timeAgo(p.received_at)}</span>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export function VisitorDetail({ kind, id, visit: given, actions, extraTabs, onClose, onExpand, onCollapse }: VisitorDetailProps) {
+  const path = kind === "company" ? "/visitors/companies/events" : "/visitors/contacts/events";
+  const lookup = useG8Query(
+    async (signal) => pageOf(await g8Get(path, { show_mode: "grouped", page: 1, limit: 100 }, { signal })).events,
+    [kind],
+    { enabled: !given },
+  );
+  const visit = given ?? (lookup.data ?? []).find((v) => (kind === "company" ? v.COMPANY_ID : v.CONTACT_ID) === id);
+
+  if (!given && lookup.error) return <ApiError error={lookup.error} title="Could not load the visitor" onRetry={() => void lookup.refetch()} />;
+  if (!visit && lookup.loading) return <Skeleton className="h-40 w-full" />;
+  if (!visit) {
+    if (kind === "company") {
+      return <DetailPanel title={`Company ${id}`} subtitle="Not among the latest visits" onClose={onClose} onExpand={onExpand} onCollapse={onCollapse}
+        tabs={[{ id: "journey", label: "Journey", content: <VisitorCompanyCard visit={{ COMPANY_ID: id }} /> }]} />;
+    }
+    return <EmptyState title="Visitor not found" description="They are not among the latest 100 identified visitors." />;
+  }
+
+  const name = kind === "company" ? companyLabel(visit) : personLabel(visit);
+  const pages = visit.children ?? [];
+  const tabs = [
+    {
+      id: "overview",
+      label: "Overview",
+      content: (
+        <div className="space-y-4">
+          <KeyValueList columns={2} items={[
+            ...(kind === "person" ? [{ label: "Person", value: name }, { label: "Contact id", value: visit.CONTACT_ID ?? "-" }] : []),
+            { label: "Company", value: visit.COMPANY_NAME ?? "-" },
+            { label: "Domain", value: visit.COMPANY_DOMAIN ?? "-" },
+            { label: "Company id", value: visit.COMPANY_ID ?? "-" },
+            { label: "Last seen", value: timeAgo(visit.received_at) },
+            { label: "Page views", value: pages.length },
+          ]} />
+          <SectionCard title="Pages viewed"><Pages pages={pages} /></SectionCard>
+        </div>
+      ),
+    },
+    ...(kind === "company" ? [{ id: "journey", label: "Full journey", content: <VisitorCompanyCard visit={visit} /> }] : []),
+  ];
+  return (
+    <DetailPanel title={name} subtitle={kind === "person" ? visit.COMPANY_NAME ?? visit.COMPANY_DOMAIN ?? undefined : visit.COMPANY_DOMAIN ?? undefined}
+      avatar={<EntityAvatar name={name} kind={kind === "company" ? "company" : "person"} size="lg" />} actions={actions}
+      tabs={extraTabs?.length ? [...tabs, ...extraTabs] : tabs} onClose={onClose} onExpand={onExpand} onCollapse={onCollapse} />
+  );
+}

package/blocks/visitors/components/visitor-feed.tsx

@@ -21,6 +21,7 @@ import { EmptyState } from "@/g8/components/empty-state";
 import { VisitorCompanyCard } from "./visitor-company-card";
 import { pageOf, personLabel, pageLabel, timeAgo } from "../lib/visitors-utils";
 import type { VisitorGroup } from "../lib/visitors-utils";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface VisitorFeedProps {
   pageSize?: number;
@@ -30,6 +31,8 @@ export interface VisitorFeedProps {
   /** Which tab to open on. Default "companies". */
   initialView?: "companies" | "people";
   onSelectPerson?: (visit: VisitorGroup) => void;
+  /** Called when a person opens a visiting company (show a VisitorDetail). Adds an Open button to each company card. */
+  onSelectCompany?: (visit: VisitorGroup) => void;
   className?: string;
 }
 
@@ -42,8 +45,10 @@ export function VisitorFeed({
   includeInternal = false,
   initialView = "companies",
   onSelectPerson,
+  onSelectCompany,
   className,
 }: VisitorFeedProps) {
+  const brand = useBrand();
   const [view, setView] = useState<View>(initialView);
   // The page belongs to one set of inputs: a different tab, page size or bot/internal filter starts at page 1.
   const scope = `${view}|${pageSize}|${includeBots}|${includeInternal}`;
@@ -113,35 +118,39 @@ export function VisitorFeed({
       ) : events.length === 0 ? (
         <EmptyState
           title={view === "companies" ? "No company visits yet" : "No identified people yet"}
-          description="Visits appear once the graph8 snippet is on your site. Check the install in SnippetInstall."
+          description={`Visits appear once the ${brand.linkLabel} snippet is on your site. Check the install in SnippetInstall.`}
         />
       ) : view === "companies" ? (
         <div className="space-y-3">
           {events.map((visit, i) => (
-            <VisitorCompanyCard key={`${visit.COMPANY_ID}-${visit.received_at}-${i}`} visit={visit} />
+            <VisitorCompanyCard
+              key={`${visit.COMPANY_ID}-${visit.received_at}-${i}`}
+              visit={visit}
+              actions={onSelectCompany ? <Button size="sm" variant="outline" onClick={() => onSelectCompany(visit)}>Open</Button> : undefined}
+            />
           ))}
         </div>
       ) : (
-        <ul className="divide-y rounded border border-gray-200">
+        <ul className="divide-y rounded border border-border">
           {events.map((visit, i) => (
             <li key={`${visit.CONTACT_ID}-${visit.received_at}-${i}`}>
               <button
                 type="button"
-                className="flex w-full items-center justify-between px-3 py-2 text-left text-sm hover:bg-gray-50"
+                className="flex w-full items-center justify-between px-3 py-2 text-left text-sm hover:bg-surface-hover"
                 onClick={() => onSelectPerson?.(visit)}
               >
                 <span>
                   <span className="font-medium">{personLabel(visit)}</span>
-                  <span className="ml-2 text-xs text-gray-500">{visit.children?.[0] ? pageLabel(visit.children[0]) : ""}</span>
+                  <span className="ml-2 text-xs text-muted-foreground">{visit.children?.[0] ? pageLabel(visit.children[0]) : ""}</span>
                 </span>
-                <span className="text-xs text-gray-500">{timeAgo(visit.received_at)}</span>
+                <span className="text-xs text-muted-foreground">{timeAgo(visit.received_at)}</span>
               </button>
             </li>
           ))}
         </ul>
       )}
 
-      <div className="flex items-center justify-between text-sm text-gray-600">
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
         <span>{total.toLocaleString()} visits</span>
         <div className="flex gap-2">
           <Button size="sm" variant="outline" disabled={page <= 1 || feed.loading} onClick={() => setPage((p) => p - 1)}>

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

@@ -0,0 +1,166 @@
+"use client";
+
+/**
+ * VisitorsScreen: the finished "website visitors" product page. Three tabs:
+ *   Visitors  companies (default) and identified people visiting your site (VisitorFeed, polled), a stat strip for the last
+ *             7 days, and a complete detail screen for any company or person (VisitorDetail: fields, pages viewed, full journey;
+ *             deep link `?id=c-<company id>` or `?id=p-<contact id>`, full page with `?view=full`).
+ *   Traffic   visitors, sessions and page views per day, top pages, "N on the site now" (TrafficChart).
+ *   Install   the tracking snippet and an install check that polls until events arrive (SnippetInstall).
+ *
+ * User flows: get the snippet, prove it works, watch who visits, switch companies/people, open a person, expand a
+ * company's journey, chart traffic. A site with no events yet opens on a guided "install the snippet" empty state.
+ *
+ * SDK operations: none of its own. Composes VisitorFeed, SnippetInstall, TrafficChart (all read tier, nothing is
+ * billable or external) and one read of getAudienceTrend (7 days) for the stat strip.
+ * Prerequisite: the snippet pasted in the site (a step only a person can do); the People list also needs contacts:read.
+ */
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { Globe } from "lucide-react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { seriesOf } from "../lib/visitors-utils";
+import type { VisitorGroup } from "../lib/visitors-utils";
+import { SnippetInstall } from "./snippet-install";
+import { TrafficChart } from "./traffic-chart";
+import { VisitorDetail } from "./visitor-detail";
+import { VisitorFeed } from "./visitor-feed";
+
+export interface VisitorsScreenProps {
+  /** Buttons in the visitor detail header (for example "Open contact" or "Add to list"). */
+  renderDetailActions?: (visit: VisitorGroup, kind: "company" | "person") => ReactNode;
+  /** Tabs added after the built-in ones on the open visitor (once its row is known). */
+  extraDetailTabs?: { id: string; label: string; render: (visit: VisitorGroup, kind: "company" | "person") => ReactNode }[];
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+interface TrendPoint {
+  date: string;
+  users?: number;
+  sessions?: number;
+  page_views?: number;
+}
+
+type Tab = "visitors" | "traffic" | "install";
+const TABS = ["visitors", "traffic", "install"] as const;
+
+function useWeekStats(): { items: StatItem[] | undefined; loading: boolean } {
+  const q = useG8Query((signal) => g8Get("/analytics/audience/trend", { days: 7 }, { signal }), []);
+  const points = seriesOf<TrendPoint>(q.data);
+  if (q.error || points.length === 0) return { items: undefined, loading: q.loading };
+  // The trend payload is open-shaped in the contract: chart only the metrics the rows really carry.
+  const metrics = [
+    { key: "users", label: "Visitors" },
+    { key: "sessions", label: "Sessions" },
+    { key: "page_views", label: "Page views" },
+  ] as const;
+  const items = metrics
+    .filter((m) => points.some((p) => typeof p[m.key] === "number"))
+    .map((m): StatItem => ({
+      label: m.label,
+      value: points.reduce((s, p) => s + (p[m.key] ?? 0), 0).toLocaleString(),
+      hint: "last 7 days",
+      sparkline: points.map((p) => p[m.key] ?? 0),
+    }));
+  return { loading: q.loading, items: items.length ? items : undefined };
+}
+
+export function VisitorsScreen(props: VisitorsScreenProps) {
+  const [tabValue, setTab] = useUrlState("tab", "visitors");
+  const tab: Tab = (TABS as readonly string[]).includes(tabValue) ? (tabValue as Tab) : "visitors";
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const [open, setOpen] = useState<VisitorGroup | null>(null);
+  const expanded = view === "full" && Boolean(id);
+  const close = () => {
+    setOpen(null);
+    setId("");
+    setView("");
+  };
+  const kind = id.startsWith("p-") ? "person" : "company";
+  // Only `c-<id>` and `p-<id>` open a record: `?id=123` must not be read as company 3.
+  const numeric = /^[cp]-\d+$/.test(id) ? Number(id.slice(2)) : NaN;
+  const stats = useWeekStats();
+  const [bots, setBots] = useState(false);
+  const [internal, setInternal] = useState(false);
+  const [days, setDays] = useState(30);
+
+  return (
+    <ScreenLayout
+      title="Website visitors"
+      description="Who is on your site, which companies they work for, and what they looked at."
+      icon={<Globe className="size-5" />}
+      actions={props.toolbarActions}
+      tabs={[
+        { id: "visitors", label: "Visitors" },
+        { id: "traffic", label: "Traffic" },
+        { id: "install", label: "Install" },
+      ]}
+      activeTab={tab}
+      onTabChange={(next) => {
+        setTab(next);
+        close();
+      }}
+      stats={tab === "visitors" ? stats.items : undefined}
+      className={props.className}
+    >
+      {tab === "visitors" ? (
+        <div className="space-y-3">
+          <Toolbar>
+            <Button size="sm" variant={bots ? "default" : "outline"} aria-pressed={bots} onClick={() => setBots((v) => !v)}>
+              Include bots
+            </Button>
+            <Button size="sm" variant={internal ? "default" : "outline"} aria-pressed={internal} onClick={() => setInternal((v) => !v)}>
+              Include internal traffic
+            </Button>
+          </Toolbar>
+          <SplitView
+            detailOpen={Boolean(id) && Number.isFinite(numeric)}
+            onCloseDetail={close}
+            expanded={expanded}
+            onExpandedChange={(next) => setView(next ? "full" : "")}
+            detailWidth="lg"
+            list={
+              <VisitorFeed
+                key={`${bots}-${internal}`}
+                includeBots={bots}
+                includeInternal={internal}
+                onSelectPerson={(v) => { if (v.CONTACT_ID == null) return; setOpen(v); setId(`p-${v.CONTACT_ID}`); }}
+                onSelectCompany={(v) => { if (v.COMPANY_ID == null) return; setOpen(v); setId(`c-${v.COMPANY_ID}`); }}
+              />
+            }
+            detail={id && Number.isFinite(numeric) ? (
+              <VisitorDetail key={id} kind={kind} id={numeric} visit={open && (kind === "company" ? open.COMPANY_ID : open.CONTACT_ID) === numeric ? open : null}
+                actions={open ? props.renderDetailActions?.(open, kind) : undefined}
+                extraTabs={open ? (props.extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(open, kind) })) : undefined}
+                onClose={close} onExpand={expanded ? undefined : () => setView("full")} onCollapse={expanded ? () => setView("") : undefined} />
+            ) : null}
+          />
+        </div>
+      ) : tab === "traffic" ? (
+        <div className="space-y-3">
+          <Toolbar>
+            <div className="inline-flex gap-1" role="group" aria-label="Traffic window">
+              {[7, 30, 90].map((d) => (
+                <Button key={d} size="sm" variant={days === d ? "default" : "outline"} aria-pressed={days === d} onClick={() => setDays(d)}>
+                  {d} days
+                </Button>
+              ))}
+            </div>
+          </Toolbar>
+          <TrafficChart days={days} />
+        </div>
+      ) : (
+        <SnippetInstall />
+      )}
+    </ScreenLayout>
+  );
+}

package/blocks/webchat/README.md

@@ -4,6 +4,14 @@ Configure the AI chat widget on your website and see who used it. `ChatWidgetCon
 look, starter questions and the embed code; `ConversationList` shows the widget's visitors and the engagement funnel.
 Message threads and replies live in the `inbox` block.
 
+## Screens
+
+`WebchatScreen` (`components/webchat-screen.tsx`) needs no props. **Visitors**: funnel stats, search, identified only,
+paging, visitor detail (`?id=`). **Widget**: pick or create a bot, style it, starter questions (delete is confirmed).
+**Install**: the tracking snippet with copy, and what graph8 must have set up (an answering agent mapped to the bot).
+Slots: `toolbarActions`, `renderRowActions`, `renderDetailActions`, `extraDetailTabs` (use them to link a visitor to the inbox).
+Scopes: `inbox:read`, `inbox:write`, `inbox:delete`, `integrations:read`.
+
 ## Install
 
 ```
@@ -20,6 +28,8 @@ Installs `foundation` and `crm` first if missing. Everything lands under `g8/web
 | graph8 workspace | An **answering agent** mapped to the bot. A bot with none answers nothing. | `GET /api/v1/webchat/agents?chat_bot_id=` lists an active agent. |
 | Your app | `allowedPrefixes` must include `webchat` and `snippet`. | The route file lists both. |
 
+Every detail opens as a full page with `&view=full` (the Open full page button).
+
 ## The flow, in order (IDs passed between steps)
 
 1. `listChatBots` -> **`bot.id`**. This is the `chat_bot_id` of nearly every other call. `createChatBot({ name })` makes one.

package/blocks/webchat/block.json

@@ -14,17 +14,17 @@
     "crm"
   ],
   "operations": [
-    "list_chat_bots_webchat_chat_bots_get",
     "create_chat_bot_webchat_chat_bots_post",
-    "get_webchat_settings_webchat_settings_get",
-    "create_webchat_settings_webchat_settings_post",
-    "update_webchat_settings_webchat_settings_patch",
-    "list_webchat_questions_webchat_questions_get",
     "create_webchat_question_webchat_questions_post",
+    "create_webchat_settings_webchat_settings_post",
     "delete_webchat_question_webchat_questions__question_id__delete",
     "get_org_snippet_snippet_get",
+    "get_webchat_settings_webchat_settings_get",
+    "get_webchat_visitor_funnel_webchat_visitors_funnel_get",
+    "list_chat_bots_webchat_chat_bots_get",
+    "list_webchat_questions_webchat_questions_get",
     "list_webchat_visitors_webchat_visitors_get",
-    "get_webchat_visitor_funnel_webchat_visitors_funnel_get"
+    "update_webchat_settings_webchat_settings_patch"
   ],
   "components": [
     {
@@ -59,6 +59,19 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "WebchatScreen",
+      "file": "components/webchat-screen.tsx",
+      "purpose": "Finished web chat page: visitors with funnel stats and detail, widget styling, and install snippet.",
+      "operations": [
+        "get_org_snippet_snippet_get",
+        "get_webchat_visitor_funnel_webchat_visitors_funnel_get",
+        "list_webchat_visitors_webchat_visitors_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [],
@@ -129,6 +142,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }