@graph8/sdk 0.362.0 → 0.373.0

package/blocks/_foundation/components/screen/record-link.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+/**
+ * RecordLink: a record's name as a real `<a href>`. A plain click runs `onOpen` (the screen opens the record
+ * the way it always did: its own URL state or component state); Cmd/Ctrl/Shift/Alt-click and middle-click fall
+ * through to the browser, so "open in a new tab" lands on the same screen with the record open. The href is
+ * `?<param>=<id>`, where `param` is the URL param the OWNING screen reads for this record type. Without a `param`
+ * there is no honest href (a new tab would open nothing, or the wrong record), so it renders a plain button that
+ * only runs `onOpen`. The href is relative (SSR-safe) and is completed with the current query when the pointer or
+ * focus reaches it, so Cmd-click keeps `tab`, `pipeline` and the rest. Add `full` for `view=full`. Only a screen
+ * without an `onOpen` of its own should pass `writeUrl`, which makes a plain click write the param itself.
+ *
+ * SDK operations: none.
+ */
+import type { MouseEvent, ReactNode, SyntheticEvent } from "react";
+import { cn } from "@graph8/sdk/ui";
+import { writeUrlParam } from "../../hooks/use-url-state";
+
+export interface RecordLinkProps {
+  /** The record id written to the URL param. */
+  id: string | number;
+  /** URL param the owning screen reads for this record. Omit it when the screen reads none: a button is rendered. */
+  param?: string;
+  /** Also set `view=full` (the record as a full page). */
+  full?: boolean;
+  /** Runs on a plain click: open the record the way the screen does (its URL setter or component state). */
+  onOpen?: () => void;
+  /** A plain click also writes `param` (and `view`) to the URL itself. Default false: `onOpen` owns the state. */
+  writeUrl?: boolean;
+  className?: string;
+  children: ReactNode;
+}
+
+/** Relative href that opens `id`: `?param=id[&view=full]`. Depends on nothing but its arguments, so server and client agree. */
+export function recordHref(id: string | number, param: string, full = false): string {
+  return `?${param}=${encodeURIComponent(String(id))}${full ? "&view=full" : ""}`;
+}
+
+/** The same href merged into the page's current query (call it at event time, never during render). */
+export function currentRecordHref(id: string | number, param: string, full = false): string {
+  const url = new URL(window.location.href);
+  url.searchParams.set(param, String(id));
+  if (full) url.searchParams.set("view", "full");
+  else url.searchParams.delete("view");
+  return `${url.pathname}${url.search}${url.hash}`;
+}
+
+export function RecordLink({ id, param, full = false, onOpen, writeUrl = false, className, children }: RecordLinkProps) {
+  const key = param ?? (writeUrl ? "id" : undefined);
+  const cls = cn("font-medium text-foreground underline-offset-2 hover:underline focus-visible:underline", className);
+  if (!key) {
+    return (
+      <button type="button" className={cn(cls, "text-left")} onClick={(e) => { e.stopPropagation(); onOpen?.(); }}>
+        {children}
+      </button>
+    );
+  }
+  const onClick = (e: MouseEvent<HTMLAnchorElement>): void => {
+    e.stopPropagation(); // the row around it also opens the record: do not do it twice
+    if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    if (!onOpen && !writeUrl) return; // nothing to do in place: let the browser follow the href
+    e.preventDefault();
+    if (writeUrl) {
+      writeUrlParam("view", full ? "full" : null);
+      writeUrlParam(key, String(id), { push: true });
+    }
+    onOpen?.();
+  };
+  /** Complete the href with the current query just before the browser can use it (hover, press, focus, context menu). */
+  const complete = (e: SyntheticEvent<HTMLAnchorElement>): void => e.currentTarget.setAttribute("href", currentRecordHref(id, key, full));
+  return (
+    <a href={recordHref(id, key, full)} onClick={onClick} onMouseEnter={complete} onMouseDown={complete} onFocus={complete} onContextMenu={complete} onTouchStart={complete} className={cls}>
+      {children}
+    </a>
+  );
+}

package/blocks/_foundation/components/screen/split-view.tsx

@@ -95,7 +95,7 @@ export function SplitView({ list, detail, detailOpen, onCloseDetail, detailWidth
 
   return (
     <div className={cn("flex h-full min-h-0 w-full min-w-0", className)} data-testid="split-view" data-detail-open={open ? "true" : "false"}>
-      <div className={cn("min-h-0 min-w-0 flex-1", listClassName)}>{list}</div>
+      <div className={cn("min-h-0 min-w-0 flex-1", listClassName)} data-g8-list="">{list}</div>
       {open && !narrow ? (
         <aside
           aria-label={detailTitle}

package/blocks/_foundation/components/screen/time-series-chart-recharts.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+/**
+ * The recharts half of TimeSeriesChart, in its own module so it is code-split: `time-series-chart.tsx`
+ * loads it on demand (React.lazy), and pages without a chart never download recharts. Import this file
+ * directly only if you need the chart rendered synchronously (it then joins your page bundle).
+ *
+ * SDK operations: none. Peer: recharts.
+ */
+import { useMemo } from "react";
+import { Area, AreaChart, Bar, BarChart, CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
+import { ChartContainer, ChartTooltip, ChartTooltipContent, cn, type ChartConfig } from "@graph8/sdk/ui";
+import { TONE_VAR, defaultFormatX, defaultFormatY } from "./time-series-format";
+import type { TimeSeries, TimeSeriesChartProps } from "./time-series-format";
+
+export function TimeSeriesChartRecharts({ data, xKey, series, kind = "line", height = 220, formatX = defaultFormatX, formatY = defaultFormatY, stacked, className }: TimeSeriesChartProps) {
+  const config = useMemo<ChartConfig>(
+    () => Object.fromEntries(series.map((s) => [s.key, { label: s.label ?? s.key, color: TONE_VAR[s.tone ?? "ink"] }])),
+    [series],
+  );
+  const axes = (
+    <>
+      <CartesianGrid vertical={false} strokeDasharray="0" stroke="var(--border)" strokeOpacity={0.9} />
+      <XAxis dataKey={xKey} tickLine={false} axisLine={false} tickMargin={8} minTickGap={24} tickFormatter={formatX} tick={{ fontSize: 11 }} />
+      <YAxis width={36} tickLine={false} axisLine={false} tickMargin={4} tickFormatter={formatY} tick={{ fontSize: 11 }} allowDecimals={false} />
+      <ChartTooltip cursor={{ stroke: "var(--border)" }} content={<ChartTooltipContent labelFormatter={(v) => formatX(v)} formatter={(v, name) => [`${formatY(Number(v))} `, String(config[String(name)]?.label ?? name)]} indicator="line" />} />
+    </>
+  );
+  const stroke = (s: TimeSeries) => ({
+    stroke: `var(--color-${s.key})`,
+    strokeWidth: s.tone === "prior" ? 1.25 : 1.5,
+    strokeDasharray: s.tone === "prior" ? "4 3" : undefined,
+    dot: false as const,
+    activeDot: { r: 3 },
+    isAnimationActive: false,
+  });
+  const style = { height } as const;
+
+  return (
+    <ChartContainer config={config} className={cn("aspect-auto w-full text-text-color-muted", className)} style={style} data-testid="time-series-chart">
+      {kind === "bar" ? (
+        <BarChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }} barCategoryGap="25%">
+          {axes}
+          {series.map((s) => (
+            <Bar key={s.key} dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone ? 0.85 : 1} radius={[2, 2, 0, 0]} isAnimationActive={false} />
+          ))}
+        </BarChart>
+      ) : kind === "area" ? (
+        <AreaChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
+          {axes}
+          {series.map((s) => (
+            <Area key={s.key} type="monotone" dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone === "prior" ? 0 : 0.06} {...stroke(s)} />
+          ))}
+        </AreaChart>
+      ) : (
+        <LineChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
+          {axes}
+          {series.map((s) => (
+            <Line key={s.key} type="monotone" dataKey={s.key} name={s.key} {...stroke(s)} />
+          ))}
+        </LineChart>
+      )}
+    </ChartContainer>
+  );
+}

package/blocks/_foundation/components/screen/time-series-chart.tsx

@@ -6,109 +6,27 @@
  * A `prior` series is the dashed warm-grey comparison. Chrome is recessive: hairline gridlines, muted
  * axis labels, no borders. Built on recharts through the UI kit's ChartContainer.
  *
+ * recharts is code-split: the chart module (time-series-chart-recharts.tsx) loads on first render, with a
+ * same-height skeleton meanwhile, so a page that shows no chart never downloads it. Same props as before.
+ *
  * SDK operations: none. Peer: recharts.
  */
-import { useMemo } from "react";
-import { Area, AreaChart, Bar, BarChart, CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
-import { ChartContainer, ChartTooltip, ChartTooltipContent, cn, type ChartConfig } from "@graph8/sdk/ui";
-import type { Tone } from "./status-pill";
-
-export interface TimeSeries {
-  /** The field of each row to plot. */
-  key: string;
-  label?: string;
-  /** Ink unless the direction means good or bad. "prior" is the dashed comparison line. */
-  tone?: Tone | "prior";
-}
-
-export interface TimeSeriesChartProps {
-  data: Array<Record<string, unknown>>;
-  /** Field holding the x value (an ISO date, a label). */
-  xKey: string;
-  series: TimeSeries[];
-  kind?: "line" | "area" | "bar";
-  height?: number;
-  /** Format an x value for the axis ("2026-10-01" -> "Oct 1"). */
-  formatX?: (value: unknown) => string;
-  /** Format a y value for the axis and the tooltip. */
-  formatY?: (value: number) => string;
-  /** Stack bars/areas. */
-  stacked?: boolean;
-  className?: string;
-}
+import { Suspense, lazy } from "react";
+import { Skeleton, cn } from "@graph8/sdk/ui";
+import type { TimeSeriesChartProps } from "./time-series-format";
 
-const TONE_VAR: Record<NonNullable<TimeSeries["tone"]> | "ink", string> = {
-  ink: "var(--foreground)",
-  neutral: "var(--text-color-muted)",
-  info: "var(--info-foreground)",
-  positive: "var(--positive-foreground)",
-  warning: "var(--warning-foreground)",
-  negative: "var(--error-foreground)",
-  prior: "var(--text-color-muted)",
-};
+export type { TimeSeries, TimeSeriesChartProps } from "./time-series-format";
+export { defaultFormatX, defaultFormatY } from "./time-series-format";
 
-export function defaultFormatX(value: unknown): string {
-  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
-    const d = new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
-    if (!Number.isNaN(d.getTime())) return d.toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: value.length === 10 ? "UTC" : undefined });
-  }
-  return String(value ?? "");
-}
-
-export function defaultFormatY(value: number): string {
-  if (Math.abs(value) >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
-  if (Math.abs(value) >= 10_000) return `${(value / 1_000).toFixed(0)}k`;
-  if (Math.abs(value) >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
-  return value.toLocaleString();
-}
+const Recharts = lazy(() => import("./time-series-chart-recharts").then((m) => ({ default: m.TimeSeriesChartRecharts })));
 
-export function TimeSeriesChart({ data, xKey, series, kind = "line", height = 220, formatX = defaultFormatX, formatY = defaultFormatY, stacked, className }: TimeSeriesChartProps) {
-  const config = useMemo<ChartConfig>(
-    () => Object.fromEntries(series.map((s) => [s.key, { label: s.label ?? s.key, color: TONE_VAR[s.tone ?? "ink"] }])),
-    [series],
+export function TimeSeriesChart(props: TimeSeriesChartProps) {
+  const fallback = (
+    <Skeleton className={cn("w-full", props.className)} style={{ height: props.height ?? 220 }} aria-label="Loading chart" data-testid="time-series-chart-loading" />
   );
-  const axes = (
-    <>
-      <CartesianGrid vertical={false} strokeDasharray="0" stroke="var(--border)" strokeOpacity={0.9} />
-      <XAxis dataKey={xKey} tickLine={false} axisLine={false} tickMargin={8} minTickGap={24} tickFormatter={formatX} tick={{ fontSize: 11 }} />
-      <YAxis width={36} tickLine={false} axisLine={false} tickMargin={4} tickFormatter={formatY} tick={{ fontSize: 11 }} allowDecimals={false} />
-      <ChartTooltip cursor={{ stroke: "var(--border)" }} content={<ChartTooltipContent labelFormatter={(v) => formatX(v)} formatter={(v, name) => [`${formatY(Number(v))} `, String(config[String(name)]?.label ?? name)]} indicator="line" />} />
-    </>
-  );
-  const stroke = (s: TimeSeries) => ({
-    stroke: `var(--color-${s.key})`,
-    strokeWidth: s.tone === "prior" ? 1.25 : 1.5,
-    strokeDasharray: s.tone === "prior" ? "4 3" : undefined,
-    dot: false as const,
-    activeDot: { r: 3 },
-    isAnimationActive: false,
-  });
-  const style = { height } as const;
-
   return (
-    <ChartContainer config={config} className={cn("aspect-auto w-full text-text-color-muted", className)} style={style} data-testid="time-series-chart">
-      {kind === "bar" ? (
-        <BarChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }} barCategoryGap="25%">
-          {axes}
-          {series.map((s) => (
-            <Bar key={s.key} dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone ? 0.85 : 1} radius={[2, 2, 0, 0]} isAnimationActive={false} />
-          ))}
-        </BarChart>
-      ) : kind === "area" ? (
-        <AreaChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
-          {axes}
-          {series.map((s) => (
-            <Area key={s.key} type="monotone" dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone === "prior" ? 0 : 0.06} {...stroke(s)} />
-          ))}
-        </AreaChart>
-      ) : (
-        <LineChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
-          {axes}
-          {series.map((s) => (
-            <Line key={s.key} type="monotone" dataKey={s.key} name={s.key} {...stroke(s)} />
-          ))}
-        </LineChart>
-      )}
-    </ChartContainer>
+    <Suspense fallback={fallback}>
+      <Recharts {...props} />
+    </Suspense>
   );
 }

package/blocks/_foundation/components/screen/time-series-format.ts

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * Types and formatters shared by TimeSeriesChart and its lazily loaded recharts implementation.
+ * No recharts here, so importing them costs nothing.
+ */
+import type { Tone } from "./status-pill";
+
+export interface TimeSeries {
+  /** The field of each row to plot. */
+  key: string;
+  label?: string;
+  /** Ink unless the direction means good or bad. "prior" is the dashed comparison line. */
+  tone?: Tone | "prior";
+}
+
+export interface TimeSeriesChartProps {
+  data: Array<Record<string, unknown>>;
+  /** Field holding the x value (an ISO date, a label). */
+  xKey: string;
+  series: TimeSeries[];
+  kind?: "line" | "area" | "bar";
+  height?: number;
+  /** Format an x value for the axis ("2026-10-01" -> "Oct 1"). */
+  formatX?: (value: unknown) => string;
+  /** Format a y value for the axis and the tooltip. */
+  formatY?: (value: number) => string;
+  /** Stack bars/areas. */
+  stacked?: boolean;
+  className?: string;
+}
+
+export const TONE_VAR: Record<NonNullable<TimeSeries["tone"]> | "ink", string> = {
+  ink: "var(--foreground)",
+  neutral: "var(--text-color-muted)",
+  info: "var(--info-foreground)",
+  positive: "var(--positive-foreground)",
+  warning: "var(--warning-foreground)",
+  negative: "var(--error-foreground)",
+  prior: "var(--text-color-muted)",
+};
+
+export function defaultFormatX(value: unknown): string {
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+    const d = new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
+    if (!Number.isNaN(d.getTime())) return d.toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: value.length === 10 ? "UTC" : undefined });
+  }
+  return String(value ?? "");
+}
+
+export function defaultFormatY(value: number): string {
+  if (Math.abs(value) >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+  if (Math.abs(value) >= 10_000) return `${(value / 1_000).toFixed(0)}k`;
+  if (Math.abs(value) >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
+  return value.toLocaleString();
+}
+

package/blocks/_foundation/hooks/use-all-pages.ts

@@ -0,0 +1,54 @@
+"use client";
+
+/**
+ * useAllPages: read every page of a list that a screen needs IN FULL (a lookup by id, a dropdown that must offer every
+ * row), instead of one call with a hopeful `limit`. Pages are fetched one after the other until the API says there is no
+ * next page, or `maxPages` is reached; then `truncated` is true and the screen must say so (see FirstNotice).
+ *
+ * It calls no operation itself: `fetchPage` does, so the caller's component declares the operation.
+ */
+import { useG8Query } from "./use-g8-query";
+import type { RowsPage } from "../lib/paging";
+
+export interface UseAllPagesOptions {
+  enabled?: boolean;
+  /** Stop after this many pages (default 20) so a runaway list cannot loop forever. */
+  maxPages?: number;
+  /** The page size you read with: when a page does not say `hasNext`, a full page of this size means "maybe more". */
+  pageSize?: number;
+}
+
+export interface UseAllPages<T> {
+  items: T[];
+  loading: boolean;
+  /** The first read has finished (a row list may still be empty). */
+  loaded: boolean;
+  error: unknown;
+  /** The page limit was reached with more rows still on the server: some rows are NOT in `items`. */
+  truncated: boolean;
+  refetch: () => void;
+}
+
+interface All<T> { items: T[]; truncated: boolean }
+
+export function useAllPages<T>(
+  fetchPage: (page: number, signal: AbortSignal) => Promise<RowsPage<T>>,
+  deps: readonly unknown[],
+  options: UseAllPagesOptions = {},
+): UseAllPages<T> {
+  const max = options.maxPages ?? 20;
+  const q = useG8Query<All<T>>(async (signal) => {
+    const items: T[] = [];
+    for (let page = 1; page <= max; page++) {
+      const got = await fetchPage(page, signal);
+      items.push(...got.rows);
+      if (got.hasNext === false || got.rows.length === 0) return { items, truncated: false };
+      if (got.hasNext === undefined && (options.pageSize === undefined || got.rows.length < options.pageSize)) return { items, truncated: false }; // could not tell, and not a full page
+    }
+    return { items, truncated: true };
+  }, deps, { enabled: options.enabled });
+  return { items: q.data?.items ?? EMPTY, loading: q.loading, loaded: q.data !== undefined, error: q.error, truncated: q.data?.truncated ?? false, refetch: () => { void q.refetch(); } };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const EMPTY: any[] = [];

package/blocks/_foundation/hooks/use-brand.ts

@@ -0,0 +1,52 @@
+"use client";
+
+/**
+ * White-label: who the app is and what the platform behind it is called. Every block reads the platform's name
+ * and link-outs from here ("Connect in graph8", "Open in graph8", the settings pages they open), so an agency or
+ * reseller can show its own name and its own app URL everywhere, from one config (`g8.config.ts` in a created app,
+ * passed to <BrandProvider>).
+ *
+ *   const brand = useBrand();           // { name, appUrl, linkLabel, logo? }
+ *   brandUrl(brand, "/studio/settings?tab=integrations")
+ *
+ * With no provider, or for any field left out, the default is graph8 itself (app.graph8.com), so nothing changes
+ * for an app that does not brand.
+ */
+
+import { createContext, useContext } from "react";
+
+export interface BrandConfig {
+  /** The app's own name (sidebar, page title). */
+  name: string;
+  /** Base URL of the platform's web app; link-outs append their path. No trailing slash needed. */
+  appUrl: string;
+  /** What the platform is called in copy and links ("Connect in <linkLabel>"). */
+  linkLabel: string;
+  /** Public path or URL of the logo (`/brand/logo.svg`). */
+  logo?: string;
+}
+
+export const DEFAULT_BRAND: BrandConfig = { name: "graph8 app", appUrl: "https://app.graph8.com", linkLabel: "graph8" };
+
+/** Fill the gaps of a partial config with the defaults; an appUrl that is not http(s) falls back to the default. */
+export function resolveBrand(partial?: Partial<BrandConfig> | null): BrandConfig {
+  const p = partial ?? {};
+  const text = (v: unknown, d: string) => (typeof v === "string" && v.trim() ? v.trim() : d);
+  let appUrl = DEFAULT_BRAND.appUrl;
+  if (typeof p.appUrl === "string" && /^https?:\/\/[^\s/]+/i.test(p.appUrl.trim())) appUrl = p.appUrl.trim().replace(/\/+$/, "");
+  const logo = typeof p.logo === "string" && p.logo.trim() ? p.logo.trim() : undefined;
+  return { name: text(p.name, DEFAULT_BRAND.name), appUrl, linkLabel: text(p.linkLabel, DEFAULT_BRAND.linkLabel), ...(logo ? { logo } : {}) };
+}
+
+export const BrandContext = createContext<BrandConfig>(DEFAULT_BRAND);
+
+/** The current brand: the nearest <BrandProvider>'s, else graph8's defaults. */
+export function useBrand(): BrandConfig {
+  return useContext(BrandContext);
+}
+
+/** `appUrl` + a path on the platform (`"/lists"`, `"/studio/settings?tab=api"`); no path gives the app's home. */
+export function brandUrl(brand: Pick<BrandConfig, "appUrl">, path = ""): string {
+  if (!path) return brand.appUrl;
+  return `${brand.appUrl}${path.startsWith("/") || path.startsWith("?") ? "" : "/"}${path}`;
+}

package/blocks/_foundation/hooks/use-g8-mutation.ts

@@ -1,10 +1,22 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
+import { g8QueryCache } from "../lib/g8-cache";
+import type { G8QueryKey } from "../lib/g8-cache";
 
 export interface UseG8MutationOptions<TVars, TResult> {
   onSuccess?: (result: TResult, vars: TVars) => void;
   onError?: (error: unknown, vars: TVars) => void;
+  /**
+   * Cache keys (prefixes) to mark stale after a successful write, so every list and detail showing them
+   * refreshes: `invalidates: ["contacts"]`, or a function of the result: `(r, v) => [["contacts", "detail", v.id]]`.
+   */
+  invalidates?: readonly G8QueryKey[] | ((result: TResult, vars: TVars) => readonly G8QueryKey[]);
+  /**
+   * Optimistic update: change cached data under `prefix` before the request; on failure it is put back.
+   * Either way the prefix is invalidated afterwards so the server's answer wins.
+   */
+  optimistic?: { prefix: G8QueryKey; update: (old: any, vars: TVars, key: readonly unknown[]) => any }; // eslint-disable-line @typescript-eslint/no-explicit-any
 }
 
 export interface UseG8MutationResult<TVars, TResult> {
@@ -54,15 +66,26 @@ export function useG8Mutation<TVars, TResult>(
     const id = ++latest.current;
     setLoading(true);
     setError(undefined);
+    const { optimistic } = optionsRef.current;
+    const snapshot = optimistic
+      ? g8QueryCache.setQueriesData(optimistic.prefix, (old, key) => optimistic.update(old, vars, key))
+      : null;
     try {
       const result = await mutationRef.current(vars);
       if (id === latest.current && mounted.current) {
         setData(result);
         setLoading(false);
       }
+      const inv = optionsRef.current.invalidates;
+      const prefixes = typeof inv === "function" ? inv(result, vars) : inv ?? [];
+      for (const prefix of optimistic ? [...prefixes, optimistic.prefix] : prefixes) void g8QueryCache.invalidate(prefix);
       optionsRef.current.onSuccess?.(result, vars);
       return result;
     } catch (err) {
+      if (snapshot && optimistic) {
+        g8QueryCache.restore(snapshot);
+        void g8QueryCache.invalidate(optimistic.prefix);
+      }
       if (id === latest.current && mounted.current) {
         setError(err);
         setLoading(false);

package/blocks/_foundation/hooks/use-g8-query.ts

@@ -1,12 +1,31 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { EMPTY_QUERY_STATE, g8QueryCache, hashKey } from "../lib/g8-cache";
+import type { G8QueryKey, G8QueryObserver, G8QueryState } from "../lib/g8-cache";
 
 export interface UseG8QueryOptions<T> {
   /** Set false to hold the request (for example until a required id is known). */
   enabled?: boolean;
   /** Shown until the first response lands. */
   initialData?: T;
+  /**
+   * Opt in to the shared cache (lib/g8-cache.ts). Every component asking for the same key shares one
+   * request and one answer; cached data shows instantly and refreshes in the background. The key must
+   * name every input the fetcher reads: `["contacts", "detail", id]`. Without a key nothing changes.
+   */
+  key?: G8QueryKey;
+  /** With `key`: how long (ms) cached data counts as fresh, so a mount does not refetch it. Default 0. */
+  staleTime?: number;
+  /** With `key`: refresh when the window regains focus or the network returns (throttled). Default true. */
+  refetchOnFocus?: boolean;
+  /** With `key`: keep showing the previous key's data while a new key loads (like the uncached hook does). Default true. */
+  keepPrevious?: boolean;
+  /**
+   * With `key`: shown while the key has no data yet (for example the row a detail was opened from), with
+   * `isPlaceholderData: true`. NEVER seed an edit form from it: wait until `isPlaceholderData` is false.
+   */
+  placeholderData?: T;
 }
 
 export interface UseG8QueryResult<T> {
@@ -16,6 +35,12 @@ export interface UseG8QueryResult<T> {
   loading: boolean;
   /** Re-run the request now. Resolves with the data, or undefined if it failed or was superseded. */
   refetch: () => Promise<T | undefined>;
+  /** With `key` only: `data` is `placeholderData` (not the real record yet). */
+  isPlaceholderData?: boolean;
+  /** With `key` only: `data` belongs to the previous key while the new one loads. */
+  isPreviousData?: boolean;
+  /** With `key` only: epoch ms when the data was fetched (0 = not yet). */
+  updatedAt?: number;
 }
 
 /**
@@ -34,6 +59,19 @@ export function useG8Query<T>(
   fetcher: (signal: AbortSignal) => Promise<T>,
   deps: readonly unknown[],
   options: UseG8QueryOptions<T> = {},
+): UseG8QueryResult<T> {
+  // Both are always called (rules of hooks); only one is ever active.
+  const keyed = options.key !== undefined;
+  const cached = useCachedQuery(fetcher, deps, options, keyed);
+  const plain = usePlainQuery(fetcher, deps, keyed ? { ...options, enabled: false } : options);
+  return keyed ? cached : plain;
+}
+
+/** The uncached hook, exactly as it was before the cache existed. */
+function usePlainQuery<T>(
+  fetcher: (signal: AbortSignal) => Promise<T>,
+  deps: readonly unknown[],
+  options: UseG8QueryOptions<T>,
 ): UseG8QueryResult<T> {
   const enabled = options.enabled ?? true;
   const fetcherRef = useRef(fetcher);
@@ -85,3 +123,91 @@ export function useG8Query<T>(
 
   return { data, error, loading, refetch: run };
 }
+
+const noopSubscribe = (): (() => void) => () => undefined;
+const emptySnapshot = (): G8QueryState => EMPTY_QUERY_STATE;
+
+/** The keyed hook: state lives in the shared cache, this component only subscribes to it. */
+function useCachedQuery<T>(
+  fetcher: (signal: AbortSignal) => Promise<T>,
+  deps: readonly unknown[],
+  options: UseG8QueryOptions<T>,
+  active: boolean,
+): UseG8QueryResult<T> {
+  const enabled = options.enabled ?? true;
+  const key = options.key ?? "";
+  const hash = active ? hashKey(key) : "";
+  const keyRef = useRef(key);
+  keyRef.current = key;
+  const fetcherRef = useRef(fetcher);
+  fetcherRef.current = fetcher;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const observer = useRef<G8QueryObserver>({
+    fetcher: () => (signal) => fetcherRef.current(signal),
+    enabled: () => optionsRef.current.enabled ?? true,
+    staleTime: () => optionsRef.current.staleTime ?? 0,
+    refetchOnFocus: () => (optionsRef.current.enabled ?? true) && (optionsRef.current.refetchOnFocus ?? true),
+  }).current;
+
+  const subscribe = useCallback(
+    (onChange: () => void) => (active ? g8QueryCache.subscribe(keyRef.current, onChange, observer) : () => undefined),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [active, hash],
+  );
+  const getSnapshot = useCallback(
+    () => (active ? g8QueryCache.getState(keyRef.current) : EMPTY_QUERY_STATE),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [active, hash],
+  );
+  const state = useSyncExternalStore(active ? subscribe : noopSubscribe, active ? getSnapshot : emptySnapshot, emptySnapshot) as G8QueryState<T>;
+
+  // Same key, new deps: the fetcher changed under the key, so the cached answer may be wrong. Refetch.
+  const lastRun = useRef<{ hash: string; deps: readonly unknown[] } | null>(null);
+  useEffect(() => {
+    if (!active || !enabled) return;
+    const prev = lastRun.current;
+    const depsChanged =
+      prev !== null && prev.hash === hash && (prev.deps.length !== deps.length || prev.deps.some((d, i) => !Object.is(d, deps[i])));
+    lastRun.current = { hash, deps };
+    if (depsChanged) void g8QueryCache.fetch(keyRef.current, observer.fetcher(), { force: true });
+    else void g8QueryCache.ensureFresh(keyRef.current, observer.fetcher(), optionsRef.current.staleTime ?? 0);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active, enabled, hash, ...deps]);
+
+  const previous = useRef<{ hash: string; data: T } | null>(null);
+  if (active && state.data !== undefined) previous.current = { hash, data: state.data };
+
+  const refetch = useCallback(
+    () =>
+      active
+        ? (g8QueryCache.fetch(keyRef.current, observer.fetcher(), { force: true, share: false }) as Promise<T | undefined>)
+        : Promise.resolve(undefined),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [active, hash],
+  );
+
+  let data = state.data;
+  let isPreviousData = false;
+  let isPlaceholderData = false;
+  if (data === undefined && (options.keepPrevious ?? true) && previous.current && previous.current.hash !== hash) {
+    data = previous.current.data;
+    isPreviousData = true;
+  }
+  if (data === undefined && options.placeholderData !== undefined) {
+    data = options.placeholderData;
+    isPlaceholderData = true;
+  }
+  if (data === undefined) data = options.initialData;
+  const neverLoaded = state.updatedAt === 0 && state.error === undefined;
+  return {
+    data,
+    error: state.error,
+    loading: enabled && (state.fetching || neverLoaded),
+    refetch,
+    isPlaceholderData,
+    isPreviousData,
+    updatedAt: state.updatedAt,
+  };
+}