@graph8/sdk 0.373.0 → 0.374.0

package/blocks/web-analytics/components/pages-tab.tsx

@@ -0,0 +1,148 @@
+"use client";
+
+/**
+ * PagesTab: how pages perform, and the detail of any one page.
+ *   Top pages      views, unique visitors, average time on page and bounce rate (re-sortable)
+ *   Landing pages  where sessions start
+ *   Exit pages     where sessions end
+ *   Events         custom tracked events (name, how often, how many people, last seen)
+ *   Page detail    a side panel for the page you click: views, unique visitors, form submissions and bookings
+ *
+ * The page you open is `?page=/path` in the URL. A path the API would refuse (it must start with / and use plain
+ * URL characters) is shown but not opened. When the app passes `resolveLandingPage`, a page whose address exactly
+ * matches one landing page gets an "Open landing page" button (by landing page id only, never by title).
+ *
+ * SDK operations, in order (all read, free). RankedTable renders a FirstNotice ("Showing the first N") when a read came back full:
+ *   1. getTopPages      GET /analytics/behavior/pages          (limit 200)
+ *   2. getLandingPages  GET /analytics/behavior/landing-pages  (limit 200)
+ *   3. getExitPages     GET /analytics/behavior/exit-pages     (limit 200)
+ *   4. getEvents        GET /analytics/behavior/events         (limit 200)
+ *   5. getPageMetrics   GET /analytics/behavior/page-metrics?path=   (the open page)
+ */
+import type { ReactNode } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useReport } from "../hooks/use-report";
+import { LIMITS, windowedQuery } from "../lib/analytics-scope";
+import type { ScopeState } from "../lib/analytics-scope";
+import { isReportablePath } from "../lib/page-path";
+import { fmtDateTime, fmtInt, fmtPct, fmtSeconds, num, readRow, readRows, str } from "../lib/web-analytics-types";
+import type { EventRow, ExitRow, LandingRow, PageMetrics, PageRow } from "../lib/web-analytics-types";
+import { RankedTable } from "./ranked-table";
+import { ReportCard } from "./report-card";
+
+export interface PagesTabProps {
+  scope: ScopeState;
+  /** The id of the landing page whose address is exactly this path, if there is exactly one. */
+  resolveLandingPage?: (path: string) => string | undefined;
+  onOpenLandingPage?: (id: string) => void;
+}
+
+function PathCell({ path, onOpen, landing }: { path: string; onOpen: (p: string) => void; landing?: ReactNode }) {
+  if (!path) return <span className="text-text-color-muted">Unknown</span>;
+  return (
+    <span className="flex min-w-0 items-center gap-2">
+      {isReportablePath(path) ? (
+        <button type="button" className="min-w-0 truncate text-left hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring" title={path} aria-label={`Open page ${path}`} onClick={() => onOpen(path)}>{path}</button>
+      ) : (
+        <span className="min-w-0 truncate" title={path}>{path}</span>
+      )}
+      {landing}
+    </span>
+  );
+}
+
+function PageDetail({ scope, path, onClose, landingId, onOpenLandingPage }: { scope: ScopeState; path: string; onClose: () => void; landingId?: string; onOpenLandingPage?: (id: string) => void }) {
+  const q = windowedQuery(scope);
+  const ok = isReportablePath(path);
+  const report = useReport(async (signal) => readRow<PageMetrics>(await g8Get("/analytics/behavior/page-metrics", { ...q, path }, { signal })), `${scope.key}|${path}`, { enabled: ok });
+  const open = landingId && onOpenLandingPage ? <Button type="button" size="sm" variant="outline" onClick={() => onOpenLandingPage(landingId)}>Open landing page</Button> : null;
+  return (
+    <DetailPanel title={path} subtitle="Page detail" onClose={onClose} actions={open}>
+      {ok ? (
+        <ReportCard title="This window" report={report} isEmpty={(d) => d === null} emptyTitle="No activity on this page">
+          {(d) => (
+            <StatStrip columns={2} items={[
+              { label: "Views", value: fmtInt(d!.views) },
+              { label: "Unique visitors", value: fmtInt(d!.unique_visitors) },
+              { label: "Form submissions", value: fmtInt(d!.form_submissions) },
+              { label: "Meetings booked", value: fmtInt(d!.bookings) },
+            ]} />
+          )}
+        </ReportCard>
+      ) : (
+        <p role="status" className="text-sm text-text-color-muted">This path has characters the report cannot look up, so its detail is not available.</p>
+      )}
+    </DetailPanel>
+  );
+}
+
+export function PagesTab({ scope, resolveLandingPage, onOpenLandingPage }: PagesTabProps) {
+  const q = windowedQuery(scope);
+  const [page, setPage] = useUrlState("page", "");
+  const top = useReport(async (signal) => readRows<PageRow>(await g8Get("/analytics/behavior/pages", { ...q, limit: LIMITS.topPages }, { signal })), scope.key);
+  const landing = useReport(async (signal) => readRows<LandingRow>(await g8Get("/analytics/behavior/landing-pages", { ...q, limit: LIMITS.landing }, { signal })), scope.key);
+  const exits = useReport(async (signal) => readRows<ExitRow>(await g8Get("/analytics/behavior/exit-pages", { ...q, limit: LIMITS.exit }, { signal })), scope.key);
+  const events = useReport(async (signal) => readRows<EventRow>(await g8Get("/analytics/behavior/events", { ...q, limit: LIMITS.events }, { signal })), scope.key);
+  const none = (rows: unknown[]) => rows.length === 0;
+  const landingBtn = (path: string) => {
+    const id = resolveLandingPage?.(path);
+    return id && onOpenLandingPage ? <button type="button" className="shrink-0 text-xs text-text-color-muted underline hover:text-foreground" aria-label={`Open landing page for ${path}`} onClick={() => onOpenLandingPage(id)}>Landing page</button> : null;
+  };
+  const list = (
+    <div className="space-y-4">
+      <ReportCard title="Top pages" report={top} isEmpty={none}>
+        {(rows) => (
+          <RankedTable rows={rows} noun="pages" limit={LIMITS.topPages} defaultSort="views" rowKey={(r, i) => `${str(r.page_path)}|${i}`} columns={[
+            { key: "path", label: "Page", render: (r) => <PathCell path={str(r.page_path)} onOpen={setPage} landing={landingBtn(str(r.page_path))} />, sortBy: (r) => str(r.page_path) },
+            { key: "views", label: "Views", numeric: true, render: (r) => fmtInt(r.views), sortBy: (r) => num(r.views) },
+            { key: "visitors", label: "Visitors", numeric: true, render: (r) => fmtInt(r.unique_visitors), sortBy: (r) => num(r.unique_visitors) },
+            { key: "time", label: "Avg time", numeric: true, render: (r) => fmtSeconds(r.avg_time_on_page), sortBy: (r) => num(r.avg_time_on_page) },
+            { key: "bounce", label: "Bounce rate", numeric: true, render: (r) => fmtPct(r.bounce_rate), sortBy: (r) => num(r.bounce_rate) },
+          ]} />
+        )}
+      </ReportCard>
+      <ReportCard title="Landing pages" description="Where sessions start" report={landing} isEmpty={none}>
+        {(rows) => (
+          <RankedTable rows={rows} noun="landing pages" limit={LIMITS.landing} defaultSort="sessions" rowKey={(r, i) => `${str(r.landing_page)}|${i}`} columns={[
+            { key: "path", label: "Page", render: (r) => <PathCell path={str(r.landing_page)} onOpen={setPage} landing={landingBtn(str(r.landing_page))} />, sortBy: (r) => str(r.landing_page) },
+            { key: "sessions", label: "Sessions", numeric: true, render: (r) => fmtInt(r.sessions), sortBy: (r) => num(r.sessions) },
+            { key: "users", label: "Visitors", numeric: true, render: (r) => fmtInt(r.users), sortBy: (r) => num(r.users) },
+          ]} />
+        )}
+      </ReportCard>
+      <ReportCard title="Exit pages" description="Where sessions end" report={exits} isEmpty={none}>
+        {(rows) => (
+          <RankedTable rows={rows} noun="exit pages" limit={LIMITS.exit} defaultSort="exits" rowKey={(r, i) => `${str(r.exit_page)}|${i}`} columns={[
+            { key: "path", label: "Page", render: (r) => <PathCell path={str(r.exit_page)} onOpen={setPage} />, sortBy: (r) => str(r.exit_page) },
+            { key: "exits", label: "Exits", numeric: true, render: (r) => fmtInt(r.exits), sortBy: (r) => num(r.exits) },
+            { key: "users", label: "Visitors", numeric: true, render: (r) => fmtInt(r.users), sortBy: (r) => num(r.users) },
+          ]} />
+        )}
+      </ReportCard>
+      <ReportCard title="Events" description="Custom events your site sends" report={events} isEmpty={none} emptyTitle="No custom events in this window">
+        {(rows) => (
+          <RankedTable rows={rows} noun="events" limit={LIMITS.events} defaultSort="total" rowKey={(r, i) => `${str(r.event_name)}|${i}`} columns={[
+            { key: "name", label: "Event", render: (r) => str(r.event_name) || "Unknown", sortBy: (r) => str(r.event_name) },
+            { key: "total", label: "Count", numeric: true, render: (r) => fmtInt(r.total_events), sortBy: (r) => num(r.total_events) },
+            { key: "users", label: "People", numeric: true, render: (r) => fmtInt(r.unique_users), sortBy: (r) => num(r.unique_users) },
+            { key: "last", label: "Last seen", render: (r) => fmtDateTime(r.last_seen), sortBy: (r) => str(r.last_seen) || undefined },
+          ]} />
+        )}
+      </ReportCard>
+    </div>
+  );
+  return (
+    <SplitView
+      list={list}
+      detailOpen={page !== ""}
+      onCloseDetail={() => setPage(null)}
+      detailTitle="Page detail"
+      detail={page ? <PageDetail scope={scope} path={page} onClose={() => setPage(null)} landingId={resolveLandingPage?.(page)} onOpenLandingPage={onOpenLandingPage} /> : undefined}
+    />
+  );
+}

package/blocks/web-analytics/components/ranked-table.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * RankedTable: the table every "top N" report uses. Rows are sorted first (click a header; the default sort is given),
+ * then cut to the first `initial` rows with a "Show all N" control, so a sort always ranks the whole list and never just
+ * the visible part. A read that came back full (`limit` rows) says "Showing the first N" because the API has no next page
+ * for these reports. A value that is unknown is a dash and sorts last.
+ *
+ * SDK operations: none.
+ */
+import { useMemo, useState, type ReactNode } from "react";
+import { ArrowDown, ArrowUp } from "lucide-react";
+import { Button, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, cn } from "@graph8/sdk/ui";
+import { FirstNotice } from "@/g8/components/paging-notices";
+
+export interface RankedColumn<R> {
+  key: string;
+  label: string;
+  /** Right-align numbers. */
+  numeric?: boolean;
+  /** What the cell shows. */
+  render: (row: R) => ReactNode;
+  /** The value that orders this column (omit and the column does not sort). */
+  sortBy?: (row: R) => number | string | undefined;
+}
+
+export interface RankedTableProps<R> {
+  rows: R[];
+  columns: RankedColumn<R>[];
+  rowKey: (row: R, index: number) => string;
+  /** Column key to sort by first (descending). */
+  defaultSort: string;
+  /** The `limit` the read was sent with, for the first-N notice. */
+  limit?: number;
+  noun: string;
+  initial?: number;
+  caption?: string;
+}
+
+function compare(a: number | string | undefined, b: number | string | undefined, dir: 1 | -1): number {
+  if (a === undefined && b === undefined) return 0;
+  if (a === undefined) return 1;
+  if (b === undefined) return -1;
+  if (typeof a === "number" && typeof b === "number") return (a - b) * dir;
+  return String(a).localeCompare(String(b)) * dir;
+}
+
+export function RankedTable<R>({ rows, columns, rowKey, defaultSort, limit, noun, initial = 10, caption }: RankedTableProps<R>) {
+  const [sort, setSort] = useState<{ key: string; dir: 1 | -1 }>({ key: defaultSort, dir: -1 });
+  const [all, setAll] = useState(false);
+  const sorted = useMemo(() => {
+    const col = columns.find((c) => c.key === sort.key);
+    if (!col?.sortBy) return rows;
+    const by = col.sortBy;
+    return [...rows].sort((x, y) => compare(by(x), by(y), sort.dir));
+  }, [rows, columns, sort]);
+  const shown = all ? sorted : sorted.slice(0, initial);
+  const click = (c: RankedColumn<R>) => {
+    if (!c.sortBy) return;
+    setSort((s) => (s.key === c.key ? { key: c.key, dir: s.dir === -1 ? 1 : -1 } : { key: c.key, dir: typeof c.sortBy!(rows[0] as R) === "string" ? 1 : -1 }));
+  };
+  return (
+    <div className="space-y-2">
+      <Table aria-label={caption ?? noun}>
+        <TableHeader>
+          <TableRow>
+            {columns.map((c) => {
+              const active = sort.key === c.key;
+              return (
+                <TableHead key={c.key} className={cn(c.numeric && "text-right")} aria-sort={active ? (sort.dir === -1 ? "descending" : "ascending") : undefined}>
+                  {c.sortBy ? (
+                    <button type="button" onClick={() => click(c)} className={cn("inline-flex items-center gap-1 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", c.numeric && "flex-row-reverse")}>
+                      {c.label}
+                      {active ? (sort.dir === -1 ? <ArrowDown className="size-3" aria-hidden /> : <ArrowUp className="size-3" aria-hidden />) : null}
+                    </button>
+                  ) : (
+                    c.label
+                  )}
+                </TableHead>
+              );
+            })}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {shown.map((r, i) => (
+            <TableRow key={rowKey(r, i)}>
+              {columns.map((c) => (
+                <TableCell key={c.key} className={cn(c.numeric && "text-right tabular-nums")}>{c.render(r)}</TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      {sorted.length > initial ? (
+        <div className="flex items-center justify-between text-xs text-text-color-muted">
+          <span role="status">Showing {shown.length.toLocaleString()} of {sorted.length.toLocaleString()} {noun}</span>
+          <Button type="button" size="sm" variant="outline" onClick={() => setAll((v) => !v)}>{all ? `Show top ${initial}` : `Show all ${sorted.length.toLocaleString()}`}</Button>
+        </div>
+      ) : null}
+      {limit ? <FirstNotice shown={rows.length} limit={limit} noun={noun} /> : null}
+    </div>
+  );
+}

package/blocks/web-analytics/components/realtime-tab.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * RealtimeTab: who is on the site right now. Sites and traffic switches apply; the window does not.
+ *   Now         active visitors and page views in the last 5 and 30 minutes, and how fresh the data is
+ *   Active pages / Traffic sources / Locations    what the last 5 minutes look like
+ * The "last 5 minutes" end at the newest stored event, not at the clock: events reach the warehouse in batches, so a quiet
+ * clock window would always read 0. `data_as_of` says where the window ends; a lag over a minute is shown. The tab re-reads
+ * every `refreshSeconds` (default 10, the endpoint's cache TTL; 0 turns it off) while the page is visible, without dimming
+ * what is on screen. Locations need GeoIP enrichment upstream, so an empty list says that instead of "no visitors".
+ *
+ * SDK operations, in order (all read, free). RankedTable-style first-N notices: a full read says "Showing the first N".
+ *   1. getRealtime           GET /analytics/realtime
+ *   2. getRealtimePages      GET /analytics/realtime/pages      (limit 20, maximum 50)
+ *   3. getRealtimeSources    GET /analytics/realtime/sources    (limit 20, maximum 50)
+ *   4. getRealtimeLocations  GET /analytics/realtime/locations  (limit 50)
+ */
+import { useEffect } from "react";
+import { BarList } from "@/g8/components/screen/bar-list";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useReport } from "../hooks/use-report";
+import { trafficQuery } from "../lib/analytics-scope";
+import type { ScopeState } from "../lib/analytics-scope";
+import { fmtDateTime, fmtInt, num, readRow, readRows, str } from "../lib/web-analytics-types";
+import type { RealtimeLocation, RealtimeOverview, RealtimePage, RealtimeSource } from "../lib/web-analytics-types";
+import { ReportCard } from "./report-card";
+
+const ROWS = 20;
+const LOCATION_ROWS = 50;
+
+export interface RealtimeTabProps {
+  scope: ScopeState;
+  refreshSeconds?: number;
+}
+
+function lagNote(d: RealtimeOverview): string {
+  const asOf = str(d.data_as_of);
+  if (!asOf) return "No page view was stored in the last 30 minutes.";
+  const lag = num(d.data_lag_seconds);
+  const behind = lag != null && lag >= 60 ? ` (${Math.round(lag / 60)} min behind the clock)` : "";
+  return `Live numbers end at the newest stored page view, ${fmtDateTime(asOf)}${behind}.`;
+}
+
+export function RealtimeTab({ scope, refreshSeconds = 10 }: RealtimeTabProps) {
+  const q = trafficQuery(scope);
+  const now = useReport(async (signal) => readRow<RealtimeOverview>(await g8Get("/analytics/realtime", q, { signal })), scope.key);
+  const pages = useReport(async (signal) => readRows<RealtimePage>(await g8Get("/analytics/realtime/pages", { ...q, limit: ROWS }, { signal })), scope.key);
+  const sources = useReport(async (signal) => readRows<RealtimeSource>(await g8Get("/analytics/realtime/sources", { ...q, limit: ROWS }, { signal })), scope.key);
+  const places = useReport(async (signal) => readRows<RealtimeLocation>(await g8Get("/analytics/realtime/locations", { ...q, limit: LOCATION_ROWS }, { signal })), scope.key);
+  const refetchers = [now.refetch, pages.refetch, sources.refetch, places.refetch];
+  useEffect(() => {
+    if (!refreshSeconds) return;
+    const timer = setInterval(() => {
+      if (typeof document === "undefined" || document.visibilityState !== "hidden") refetchers.forEach((r) => r());
+    }, refreshSeconds * 1000);
+    return () => clearInterval(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [refreshSeconds, scope.key]);
+  const none = (rows: unknown[]) => rows.length === 0;
+  return (
+    <div className="grid gap-4 lg:grid-cols-3">
+      <ReportCard className="lg:col-span-3" title="Now" description={refreshSeconds ? `Refreshes every ${refreshSeconds} seconds` : undefined} report={now} isEmpty={(d) => d === null}>
+        {(d) => (
+          <div className="space-y-2">
+            <StatStrip items={[
+              { label: "Active, last 5 minutes", value: fmtInt(d!.active_5m) },
+              { label: "Active, last 30 minutes", value: fmtInt(d!.active_30m) },
+              { label: "Page views, 5 minutes", value: fmtInt(d!.pageviews_5m) },
+              { label: "Page views, 30 minutes", value: fmtInt(d!.pageviews_30m) },
+            ]} />
+            <p className="text-xs text-text-color-muted" data-testid="realtime-freshness">{lagNote(d!)}</p>
+          </div>
+        )}
+      </ReportCard>
+      <ReportCard title="Active pages" report={pages} isEmpty={none} emptyTitle="No page views right now">
+        {(rows) => (
+          <div className="space-y-2">
+            <BarList items={rows.map((r) => ({ label: str(r.page_path) || str(r.page_title) || "Unknown page", value: num(r.visitors) ?? 0 }))} />
+            <FirstNotice shown={rows.length} limit={ROWS} noun="pages" />
+          </div>
+        )}
+      </ReportCard>
+      <ReportCard title="Traffic sources" report={sources} isEmpty={none} emptyTitle="No visitors right now">
+        {(rows) => (
+          <div className="space-y-2">
+            <BarList items={rows.map((r) => ({ label: str(r.source) || "Unknown", value: num(r.visitors) ?? 0 }))} />
+            <FirstNotice shown={rows.length} limit={ROWS} noun="sources" />
+          </div>
+        )}
+      </ReportCard>
+      <ReportCard title="Locations" report={places} isEmpty={none} emptyTitle="No locations right now" emptyDescription="Locations need GeoIP enrichment on the tracking pipeline, so this can be empty while visitors are on the site.">
+        {(rows) => (
+          <div className="space-y-2">
+            <BarList items={rows.map((r) => ({ label: [str(r.region), str(r.country)].filter(Boolean).join(", ") || "Unknown", value: num(r.visitors) ?? 0 }))} />
+            <FirstNotice shown={rows.length} limit={LOCATION_ROWS} noun="locations" />
+          </div>
+        )}
+      </ReportCard>
+    </div>
+  );
+}

package/blocks/web-analytics/components/report-card.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+/**
+ * ReportCard: one report in a titled card, with the five states every analytics card must get right.
+ *
+ *   loading      skeleton (first read, or Retry after a failure)
+ *   error        the error with Retry; the previous numbers are NOT shown under it
+ *   unavailable  the backend flagged the answer stale and there is nothing to show: "could not be computed", with Retry.
+ *                It is never shown as an empty report, and any summary tiles that belong to this report are hidden with it
+ *   empty        a real answer with no rows: "No data in this window" (the empty text can be overridden)
+ *   ready        the content; while a new scope loads it is dimmed and marked busy, never silently left as the old answer
+ *
+ * SDK operations: none.
+ */
+import type { ReactNode } from "react";
+import { TriangleAlert } from "lucide-react";
+import { Button, Skeleton, cn } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import type { Report } from "../hooks/use-report";
+
+export interface ReportCardProps<T> {
+  title: ReactNode;
+  description?: ReactNode;
+  report: Report<T>;
+  /** True when `data` holds nothing to draw (no rows, no row). */
+  isEmpty: (data: T) => boolean;
+  emptyTitle?: string;
+  emptyDescription?: ReactNode;
+  actions?: ReactNode;
+  /** Height of the loading skeleton. */
+  skeletonHeight?: number;
+  className?: string;
+  children: (data: T) => ReactNode;
+}
+
+export function ReportCard<T>({ title, description, report, isEmpty, emptyTitle = "No data in this window", emptyDescription, actions, skeletonHeight = 120, className, children }: ReportCardProps<T>) {
+  const { data, stale, loading, pending, error, refetch } = report;
+  let body: ReactNode;
+  if (error) {
+    body = <ApiError error={error} compact title="Could not load this report" onRetry={refetch} />;
+  } else if (loading || data === undefined) {
+    body = <Skeleton className="w-full" style={{ height: skeletonHeight }} aria-label="Loading report" aria-busy="true" />;
+  } else if (stale && isEmpty(data)) {
+    body = (
+      <div role="alert" className="flex items-start gap-2 rounded-md border border-border bg-muted px-3 py-3 text-sm">
+        <TriangleAlert className="mt-0.5 size-4 shrink-0 text-warning-foreground" strokeWidth={1.5} aria-hidden />
+        <div className="min-w-0 flex-1">
+          <p className="font-medium text-foreground">This report is unavailable right now</p>
+          <p className="text-text-color-muted">The query did not finish, so there is nothing to show. This is not zero traffic.</p>
+        </div>
+        <Button type="button" size="sm" variant="outline" onClick={refetch}>Retry</Button>
+      </div>
+    );
+  } else if (isEmpty(data)) {
+    body = <EmptyState compact title={emptyTitle} description={emptyDescription} />;
+  } else {
+    body = (
+      <div className={cn("space-y-3 transition-opacity", pending && "opacity-50")} aria-busy={pending || undefined} data-pending={pending ? "true" : undefined}>
+        {stale ? <p role="note" className="text-xs text-warning-foreground">The latest query failed. These are the last saved numbers and may be out of date.</p> : null}
+        {children(data)}
+      </div>
+    );
+  }
+  return (
+    <SectionCard title={title} description={description} actions={actions} className={className}>
+      {body}
+    </SectionCard>
+  );
+}

package/blocks/web-analytics/components/web-analytics-screen.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * WebAnalyticsScreen: the finished website analytics product page. Seven tabs share ONE site picker and ONE window
+ * (kept in the URL: ?site=, ?days= or ?from=&to=, ?bots=1, ?internal=1, ?tab=), so a link opens the same view anywhere.
+ *   Overview     audience, traffic over time, conversion, top pages
+ *   Acquisition  channels, sources, campaigns, referrals, social and search
+ *   Audience     countries, cities, languages, technology, new or returning
+ *   Pages        top, landing and exit pages, events, and a detail panel for any page (?page=/path)
+ *   Engagement   sessions, depth, time on site, bounce, by channel, campaign and landing page
+ *   Conversions  funnel, goals, forms and form analysis
+ *   Realtime     who is on the site now
+ *
+ * Every tab is read only: no confirmations, nothing billable. Any filter, site or window change shows a loading state on
+ * each card (never the old numbers as if they were the new answer). Glue to other blocks is injected by the app:
+ * `resolveLandingPage(path)` returns the id of the landing page at exactly that address, and `onOpenLandingPage(id)` opens it.
+ *
+ * SDK operations: none of its own. The tabs and AnalyticsFilters make the reads (see each file).
+ * Prerequisite: the tracking snippet pasted into the website (a step only a person can do, see the visitors block).
+ */
+import { useEffect, type ReactNode } from "react";
+import { ChartNoAxesCombined } from "lucide-react";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { useUrlState, writeUrlParam } from "@/g8/hooks/use-url-state";
+import { useAnalyticsScope } from "../lib/analytics-scope";
+import { AcquisitionTab } from "./acquisition-tab";
+import { AnalyticsFilters } from "./analytics-filters";
+import { AudienceTab } from "./audience-tab";
+import { ConversionsTab } from "./conversions-tab";
+import { EngagementTab } from "./engagement-tab";
+import { OverviewTab } from "./overview-tab";
+import { PagesTab } from "./pages-tab";
+import { RealtimeTab } from "./realtime-tab";
+
+export interface WebAnalyticsScreenProps {
+  /** The id of the landing page whose address is exactly this page path (one match only), or undefined. */
+  resolveLandingPage?: (path: string) => string | undefined;
+  /** Open that landing page (a route in the app, for example /pages?id=...). */
+  onOpenLandingPage?: (id: string) => void;
+  /** Re-read the realtime tab every N seconds (default 10; 0 turns it off). */
+  refreshSeconds?: number;
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+const TABS = [
+  { id: "overview", label: "Overview" },
+  { id: "acquisition", label: "Acquisition" },
+  { id: "audience", label: "Audience" },
+  { id: "pages", label: "Pages" },
+  { id: "engagement", label: "Engagement" },
+  { id: "conversions", label: "Conversions" },
+  { id: "realtime", label: "Realtime" },
+] as const;
+type TabId = (typeof TABS)[number]["id"];
+
+export function WebAnalyticsScreen({ resolveLandingPage, onOpenLandingPage, refreshSeconds, toolbarActions, className }: WebAnalyticsScreenProps) {
+  const [tabRaw, setTab] = useUrlState("tab", "overview");
+  const tab: TabId = TABS.some((t) => t.id === tabRaw) ? (tabRaw as TabId) : "overview";
+  const scope = useAnalyticsScope();
+  // The page detail belongs to the Pages tab: leaving it closes the panel so the next visit starts on the list.
+  useEffect(() => {
+    if (tab !== "pages") writeUrlParam("page", null);
+  }, [tab]);
+  const openPage = (path: string) => {
+    writeUrlParam("page", path);
+    setTab("pages");
+  };
+  return (
+    <ScreenLayout
+      className={className}
+      icon={<ChartNoAxesCombined />}
+      title="Web analytics"
+      description="Traffic, audience, engagement and conversions for your sites"
+      actions={toolbarActions}
+      tabs={TABS.map((t) => ({ id: t.id, label: t.label }))}
+      activeTab={tab}
+      onTabChange={(id) => setTab(id === "overview" ? null : id)}
+      toolbar={<AnalyticsFilters scope={scope} showWindow={tab !== "realtime"} />}
+    >
+      {tab === "overview" ? <OverviewTab scope={scope} onOpenPage={openPage} onGoTab={(id) => setTab(id)} /> : null}
+      {tab === "acquisition" ? <AcquisitionTab scope={scope} /> : null}
+      {tab === "audience" ? <AudienceTab scope={scope} /> : null}
+      {tab === "pages" ? <PagesTab scope={scope} resolveLandingPage={resolveLandingPage} onOpenLandingPage={onOpenLandingPage} /> : null}
+      {tab === "engagement" ? <EngagementTab scope={scope} /> : null}
+      {tab === "conversions" ? <ConversionsTab scope={scope} /> : null}
+      {tab === "realtime" ? <RealtimeTab scope={scope} refreshSeconds={refreshSeconds} /> : null}
+    </ScreenLayout>
+  );
+}

package/blocks/web-analytics/hooks/use-report.ts

@@ -0,0 +1,48 @@
+"use client";
+
+/**
+ * useReport: one report read with the states every card needs, so no card invents its own.
+ *
+ *  - `pending` is true while a request for the CURRENT scope is in flight and the data on screen belongs to an older
+ *    one (a site, window or switch just changed): the card dims or shows a skeleton. A background poll of the same
+ *    scope (realtime) does not set it, so a ticking card does not flicker.
+ *  - `error` clears `data`: the last query's numbers never stay on screen under a failure or a refusal.
+ *  - `stale` is the backend's `meta.stale` (the query failed and the service swallowed it).
+ *
+ * The caller passes the fetcher, so the component that calls g8Get declares the operation.
+ *
+ * SDK operations: none.
+ */
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+
+export interface Report<T> {
+  data: T | undefined;
+  stale: boolean;
+  /** First load: nothing to show yet. */
+  loading: boolean;
+  /** A new scope is loading while older data is still held. */
+  pending: boolean;
+  error: unknown;
+  refetch: () => void;
+}
+
+export function useReport<T>(
+  fetcher: (signal: AbortSignal) => Promise<{ data: T; stale: boolean }>,
+  key: string,
+  options: { enabled?: boolean } = {},
+): Report<T> {
+  // Each answer remembers the scope it was read for, so "this is an older scope's data" is known even in the render
+  // before the new request starts.
+  const q = useG8Query(async (signal) => ({ ...(await fetcher(signal)), key }), [key], { enabled: options.enabled });
+  const fresh = q.data?.key === key;
+  const failed = q.error !== undefined && !q.loading;
+  const hasData = q.data !== undefined && q.error === undefined;
+  return {
+    data: hasData ? q.data!.data : undefined,
+    stale: hasData ? q.data!.stale : false,
+    loading: !failed && !hasData,
+    pending: hasData && !fresh,
+    error: failed ? q.error : undefined,
+    refetch: () => void q.refetch(),
+  };
+}