@graph8/sdk 0.373.0 → 0.374.0

package/blocks/programmatic-pages/components/programmatic-generated-pages.tsx

@@ -0,0 +1,210 @@
+"use client";
+
+/**
+ * ProgrammaticGeneratedPages: the generated pages of one campaign, with row and bulk lifecycle actions.
+ *
+ * SDK operations, in order:
+ *   1. listProgrammaticGeneratedPages (GET /programmatic-campaigns/{id}/pages)                     read      50 per read, offset paged
+ *   2. runProgrammaticPageAction (POST /programmatic-campaigns/{id}/pages/{page_id}/actions)       external  mark ready, unpublish, mark for
+ *      regeneration, replace the HTML (override), undo the replacement. Unpublish takes the page OFF the live site: confirmed.
+ *   3. runProgrammaticBulkPageAction (POST /programmatic-campaigns/{id}/pages/actions)             external  the same on a selection; delete
+ *      removes pages (destructive, confirmed); queue_search_console submits live URLs to Google (confirmed); export_urls only reads.
+ * A confirm counts exactly the pages the request sends: the selection is filtered once to the pages the action applies to (live
+ * pages for unpublish and Search Console, rendered drafts for mark ready) and that array is both counted and sent. The list is
+ * paged by the API without a filter, so search and the status filter work on the pages loaded so far and say so.
+ */
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { ExternalLink, FileDown, Trash2 } from "lucide-react";
+import { Button, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { LoadMore } from "@/g8/components/paging-notices";
+import { EmptyValue } from "@/g8/components/screen/key-value-list";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SelectFilter } from "@/g8/components/screen/filter-controls";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { invalidate } from "@/g8/lib/g8-cache";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { byOffset } from "@/g8/lib/paging";
+import { plural } from "@/g8/lib/plural";
+import { asRec, num, rowsOf, shortDate } from "@/g8/pages/lib/studio";
+import { PAGE_SIZE, PAGE_STATUSES, bulkTargets, isLive, pageActionBlock, wording } from "../lib/programmatic-types";
+import type { BulkActionName, Campaign, GeneratedPage, PageActionName } from "../lib/programmatic-types";
+
+export interface ProgrammaticGeneratedPagesProps {
+  campaign: Campaign;
+}
+
+type Pending = { kind: "page"; page: GeneratedPage; action: "unpublish" } | { kind: "bulk"; action: BulkActionName; ids: string[] };
+const tone = (s?: string | null) => (s === "published" ? "positive" : s === "failed" ? "negative" : s === "generated" ? "info" : "neutral");
+const LABELS: Record<string, string> = { mark_ready_to_deploy: "Mark ready", unpublish: "Unpublish", mark_for_regeneration: "Regenerate", override: "Replace HTML", reset_override: "Undo HTML edit" };
+
+export function ProgrammaticGeneratedPages({ campaign }: ProgrammaticGeneratedPagesProps) {
+  const base = `/programmatic-campaigns/${encodeURIComponent(campaign.id)}`;
+  const total = useRef<number | undefined>(undefined);
+  const list = useLoadMoreList(byOffset<GeneratedPage>(PAGE_SIZE, async (offset, signal) => {
+    const data = asRec((await g8Get(`${base}/pages`, { limit: PAGE_SIZE, offset: offset || undefined }, { signal })).data);
+    const rows = rowsOf<GeneratedPage>(data, "pages");
+    if (offset === 0) total.current = num(data.total); // the first read of a campaign replaces the count; a later page never keeps another campaign's
+    return { rows, hasNext: total.current === undefined ? undefined : offset + rows.length < total.current };
+  }), [campaign.id]);
+  const pages = list.data ?? [];
+  const [search, setSearch] = useState("");
+  const [status, setStatus] = useState("");
+  const [selected, setSelected] = useState<ReadonlySet<string>>(new Set());
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [editing, setEditing] = useState<GeneratedPage | null>(null);
+  const [html, setHtml] = useState("");
+  const [busy, setBusy] = useState<string | null>(null);
+  const [note, setNote] = useState("");
+  const [urls, setUrls] = useState<string[] | null>(null);
+
+  // Selection follows the data: ids that are no longer loaded (a refetch, a delete) leave the selection.
+  useEffect(() => { setSelected((cur) => { const alive = new Set(pages.map((p) => p.id)); const next = new Set([...cur].filter((id) => alive.has(id))); return next.size === cur.size ? cur : next; }); }, [list.data]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => { setSelected(new Set()); setNote(""); }, [campaign.id]);
+
+  const shown = useMemo(() => {
+    const q = search.trim().toLowerCase();
+    return pages.filter((p) => (!status || p.status === status) && (!q || `${p.slug ?? ""} ${p.published_url ?? ""}`.toLowerCase().includes(q)));
+  }, [pages, search, status]);
+
+  const refresh = (): void => { void invalidate(["programmatic"]); void list.refetch(); };
+  const rowAction = useG8Mutation((v: { page: GeneratedPage; action: PageActionName; html?: string }) => {
+    const body: Record<string, unknown> = { action: v.action };
+    if (v.action === "override") { body.html_output = v.html; body.manual_override = { fields: ["html_output"] }; }
+    return g8Post(`${base}/pages/${encodeURIComponent(v.page.id)}/actions`, body);
+  }, { onSuccess: (_r, v) => { setBusy(null); setPending(null); setEditing(null); setNote(`${LABELS[v.action]} done for ${v.page.slug ?? "the page"}.`); refresh(); }, onError: () => setBusy(null) });
+  const bulk = useG8Mutation((v: { action: BulkActionName; ids: string[] }) => g8Post<{ urls?: string[]; count?: number }>(`${base}/pages/actions`, { action: v.action, page_ids: v.ids }), {
+    onSuccess: (res, v) => {
+      setPending(null);
+      const d = asRec(res.data);
+      if (v.action === "export_urls") setUrls(Array.isArray(d.urls) ? (d.urls as string[]) : []);
+      else { setSelected(new Set()); setNote(`${plural(num(d.count) ?? v.ids.length, "page")} updated.`); refresh(); }
+    },
+  });
+
+  const run = (page: GeneratedPage, action: PageActionName): void => {
+    rowAction.reset();
+    if (action === "unpublish") return setPending({ kind: "page", page, action });
+    if (action === "override") { setHtml(""); return setEditing(page); }
+    setBusy(page.id);
+    void rowAction.mutate({ page, action });
+  };
+  const ask = (action: BulkActionName): void => {
+    const ids = bulkTargets(pages, selected, action);
+    if (ids.length === 0) return;
+    if (action === "unpublish_selected" || action === "delete_selected" || action === "queue_search_console") { bulk.reset(); setPending({ kind: "bulk", action, ids }); }
+    else void bulk.mutate({ action, ids });
+  };
+  const toggle = (id: string): void => setSelected((cur) => { const n = new Set(cur); if (n.has(id)) n.delete(id); else n.add(id); return n; });
+  const allShown = shown.length > 0 && shown.every((p) => selected.has(p.id));
+  const count = (a: BulkActionName): number => bulkTargets(pages, selected, a).length;
+
+  const copy = pending?.kind === "bulk" ? pending : null;
+  const liveInPick = (ids: string[]): number => bulkTargets(pages, new Set(ids), "unpublish_selected").length;
+  const confirmText = pending?.kind === "page"
+    ? { tier: "external" as const, title: `Take ${pending.page.slug ?? "this page"} off the live site?`, body: "Visitors to its address will no longer see it. On a custom domain the last published copy may stay up until the next publish. You can mark it ready and publish it again.", label: "Unpublish", affected: 1 }
+    : copy?.action === "delete_selected"
+      ? { tier: "destructive" as const, title: `Delete ${plural(copy.ids.length, "page")}?`, body: `The pages are removed from this campaign. ${liveInPick(copy.ids) === 0 ? "None of them is live." : `${plural(liveInPick(copy.ids), "of them is", "of them are")} live.`} On a hosted address a deleted live page stops being served right away; on a custom domain its last published copy may stay up until the next publish. Unpublish first if you only want it offline.`, label: "Delete", affected: copy.ids.length }
+      : copy?.action === "queue_search_console"
+        ? { tier: "external" as const, title: `Send ${plural(copy.ids.length, "live page")} to Google Search Console?`, body: "The live addresses are queued for submission to the connected Search Console property.", label: "Send", affected: copy.ids.length }
+        : copy
+          ? { tier: "external" as const, title: `Unpublish ${plural(copy.ids.length, "live page")}?`, body: "Visitors to their addresses will no longer see them (on a custom domain the last published copy may stay up until the next publish). Pages that are not live are left out.", label: "Unpublish", affected: copy.ids.length }
+          : null;
+  const confirming = rowAction.loading || bulk.loading;
+
+  if (list.error && !list.data) return <ApiError error={list.error} title="Could not load the pages" onRetry={() => void list.refetch()} />;
+  if (!list.data) return <div aria-busy="true" className="grid gap-2"><Skeleton className="h-10 w-full" /><Skeleton className="h-10 w-full" /></div>;
+  if (pages.length === 0) return <EmptyState title="No pages yet" description="Render the pages from the Overview tab. One page is made for every row of the source." />;
+  return (
+    <div className="grid gap-3">
+      <Toolbar
+        search={{ value: search, onChange: setSearch, placeholder: "Search loaded pages" }}
+        filters={<SelectFilter label="page status" value={status} onChange={setStatus} any="Any status" options={PAGE_STATUSES.map((s) => ({ value: s, label: wording(s) }))} />}
+      />
+      <p role="status" className="text-muted-foreground text-xs">
+        {shown.length === pages.length ? `${pages.length.toLocaleString()} of ${(total.current ?? pages.length).toLocaleString()} pages loaded` : `${shown.length.toLocaleString()} of ${pages.length.toLocaleString()} loaded pages match`}
+        {list.hasMore ? ". Search and the filter look only at the pages loaded so far." : ""}
+      </p>
+      {selected.size > 0 ? (
+        <div role="group" aria-label="Actions for the selected pages" className="bg-muted flex flex-wrap items-center gap-2 rounded-md p-2 text-sm">
+          <span className="mr-2">{plural(selected.size, "page")} selected</span>
+          <Button size="sm" variant="outline" disabled={count("mark_ready_to_deploy_selected") === 0} loading={bulk.loading} onClick={() => ask("mark_ready_to_deploy_selected")}>Mark {count("mark_ready_to_deploy_selected")} ready</Button>
+          <Button size="sm" variant="outline" disabled={count("mark_for_regeneration_selected") === 0} onClick={() => ask("mark_for_regeneration_selected")}>Regenerate {count("mark_for_regeneration_selected")}</Button>
+          <Button size="sm" variant="outline" disabled={count("unpublish_selected") === 0} onClick={() => ask("unpublish_selected")}>Unpublish {count("unpublish_selected")}</Button>
+          <Button size="sm" variant="outline" disabled={count("queue_search_console") === 0} onClick={() => ask("queue_search_console")}>Send {count("queue_search_console")} to Search Console</Button>
+          <Button size="sm" variant="outline" disabled={count("export_urls") === 0} onClick={() => ask("export_urls")}><FileDown className="size-4" />Export {count("export_urls")} addresses</Button>
+          <Button size="sm" variant="outline" onClick={() => ask("delete_selected")}><Trash2 className="size-4" />Delete {count("delete_selected")}</Button>
+        </div>
+      ) : null}
+      {note ? <p role="status" className="text-xs">{note}</p> : null}
+      {!pending && bulk.error ? <ApiError error={bulk.error} title="Could not run the action" /> : null}
+      {!pending && !editing && rowAction.error ? <ApiError error={rowAction.error} title="Could not run the action" /> : null}
+      <div className="overflow-x-auto rounded-md border">
+        <table className="w-full text-sm">
+          <thead className="text-muted-foreground text-left text-xs">
+            <tr>
+              <th className="w-8 p-2"><input type="checkbox" aria-label="Select all shown pages" checked={allShown} onChange={() => setSelected(allShown ? new Set() : new Set(shown.map((p) => p.id)))} /></th>
+              <th className="p-2">Page</th><th className="p-2">Status</th><th className="p-2">Changes</th><th className="p-2">Search score</th><th className="p-2">Rendered</th><th className="p-2 text-right">Actions</th>
+            </tr>
+          </thead>
+          <tbody>
+            {shown.length === 0 ? <tr><td colSpan={7} className="text-muted-foreground p-4 text-center">No loaded page matches.</td></tr> : shown.map((p) => (
+              <tr key={p.id} className="border-t align-top">
+                <td className="p-2"><input type="checkbox" aria-label={`Select ${p.slug ?? "page"}`} checked={selected.has(p.id)} onChange={() => toggle(p.id)} /></td>
+                <td className="p-2">
+                  <span className="block font-medium">{p.slug || <EmptyValue />}</span>
+                  {p.published_url ? <a className="text-muted-foreground inline-flex items-center gap-1 text-xs underline" href={p.published_url} target="_blank" rel="noopener noreferrer">Open live page<ExternalLink className="size-3" /></a> : null}
+                  {p.error_message ? <span className="text-error block text-xs">{p.error_message}</span> : null}
+                </td>
+                <td className="p-2"><StatusPill tone={tone(p.status)}>{p.status ? wording(p.status) : "Unknown"}</StatusPill></td>
+                <td className="p-2">{p.change_state && p.change_state !== "no_changes" ? wording(p.change_state) : <EmptyValue />}</td>
+                <td className="p-2">{p.seo_health?.score == null ? <EmptyValue /> : p.seo_health.score}</td>
+                <td className="p-2">{shortDate(p.last_generated_at) || <EmptyValue />}</td>
+                <td className="p-2"><div className="flex flex-wrap justify-end gap-1">
+                  {(["mark_ready_to_deploy", "unpublish", "mark_for_regeneration", "override", "reset_override"] as PageActionName[]).map((a) => {
+                    const why = pageActionBlock(p, a);
+                    return <Button key={a} size="sm" variant="ghost" aria-label={`${LABELS[a]} ${p.slug ?? "page"}`} title={why || undefined} disabled={Boolean(why) || busy === p.id} loading={busy === p.id && a !== "unpublish" && a !== "override"} onClick={() => run(p, a)}>{LABELS[a]}</Button>;
+                  })}
+                </div></td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      <LoadMore shown={pages.length} noun="pages" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+      <FormSheet open={editing !== null} onOpenChange={(o) => { if (!o) setEditing(null); }} title={`Replace the HTML of ${editing?.slug ?? "this page"}`} description="Your HTML replaces the rendered page. The API removes scripts, forms, styles and event handlers from it. The page keeps its edit until you undo it or regenerate.">
+        <div className="grid gap-3">
+          <Textarea aria-label="Page HTML" rows={14} value={html} onChange={(e) => setHtml(e.target.value)} placeholder="Paste the complete page HTML" />
+          <p className="text-muted-foreground text-xs">The API does not return a page&apos;s current HTML, so paste the whole replacement. {isLive(editing ?? {} as GeneratedPage) ? "This page is live; the edit reaches visitors after the next publish." : ""}</p>
+          {rowAction.error ? <ApiError error={rowAction.error} title="Could not replace the HTML" /> : null}
+          <div className="flex gap-2">
+            <Button loading={rowAction.loading} disabled={html.trim() === "" || !editing} onClick={() => editing && void rowAction.mutate({ page: editing, action: "override", html })}>Replace HTML</Button>
+            <Button variant="outline" onClick={() => setEditing(null)}>Cancel</Button>
+          </div>
+        </div>
+      </FormSheet>
+      <FormSheet open={urls !== null} onOpenChange={(o) => { if (!o) setUrls(null); }} title="Page addresses" description={`${plural(urls?.length ?? 0, "live address")} for the selected pages.`}>
+        {urls && urls.length === 0 ? <p className="text-muted-foreground text-sm">None of the selected pages has a live address.</p> : <Textarea aria-label="Page addresses" readOnly rows={12} value={(urls ?? []).join("\n")} />}
+      </FormSheet>
+      {confirmText ? (
+        <ConfirmSpendDialog
+          open
+          tier={confirmText.tier}
+          title={confirmText.title}
+          affected={confirmText.affected}
+          description={<><p>{confirmText.body}</p>{pending && (bulk.error || rowAction.error) ? <ApiError error={bulk.error ?? rowAction.error} title="Could not run the action" /> : null}</>}
+          confirmLabel={confirmText.label}
+          confirming={confirming}
+          onCancel={() => setPending(null)}
+          onConfirm={() => (pending?.kind === "page" ? (setBusy(pending.page.id), void rowAction.mutate({ page: pending.page, action: "unpublish" })) : pending && void bulk.mutate({ action: pending.action, ids: pending.ids }))}
+        />
+      ) : null}
+    </div>
+  );
+}

package/blocks/programmatic-pages/components/programmatic-overview.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+/**
+ * ProgrammaticOverview: where a campaign stands: readiness checks, the numbers, the template, search health and what the next
+ * render and publish will do. Hosts the Generate and Publish panels.
+ *
+ * SDK operations, in order:
+ *   1. getProgrammaticWorkspace (GET /programmatic-campaigns/{id}/workspace)   read   readiness, counts, search, links, deployment
+ *   2. getLandingPage (GET /landing-pages/{landing_page_id})                   read   the template page's name, only when the workspace names it
+ * Generating and publishing live in ProgrammaticGenerate and ProgrammaticPublish, which confirm what reaches the live site.
+ * A missing number is shown as a dash, never as 0.
+ */
+
+import { CheckCircle2, Circle, ExternalLink } from "lucide-react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { asRec, shortDate, text } from "@/g8/pages/lib/studio";
+import { useProgrammaticWorkspace } from "../hooks/use-programmatic-workspace";
+import type { Campaign } from "../lib/programmatic-types";
+import { wording } from "../lib/programmatic-types";
+import { ProgrammaticGenerate } from "./programmatic-generate";
+import { ProgrammaticPublish } from "./programmatic-publish";
+
+export interface ProgrammaticOverviewProps {
+  campaign: Campaign;
+  /** Where the template page is edited. Default: the pages screen at /pages?id=. */
+  pagesHref?: (templatePageId: string) => string;
+}
+
+const n = (v: number | null | undefined): string | null => (v == null ? null : v.toLocaleString());
+
+export function ProgrammaticOverview({ campaign, pagesHref = (id) => `/pages?id=${encodeURIComponent(id)}` }: ProgrammaticOverviewProps) {
+  const ws = useProgrammaticWorkspace(campaign.id);
+  const templateId = ws.data?.template?.template_page_id ?? campaign.template_page_id ?? "";
+  const template = useG8Query(
+    (signal) => g8Get(`/landing-pages/${encodeURIComponent(templateId)}`, undefined, { signal }).then((r) => asRec(r.data)),
+    [templateId], { enabled: Boolean(templateId), key: ["programmatic", "template", templateId] },
+  );
+  if (ws.error && !ws.data) return <ApiError error={ws.error} title="Could not load the campaign" onRetry={() => void ws.refetch()} />;
+  if (!ws.data) return <Skeleton className="h-40 w-full" aria-busy="true" />;
+  const o = ws.data.overview ?? {};
+  const seo = ws.data.seo;
+  const issues = Object.entries(seo?.issues ?? {}).filter(([, c]) => c > 0);
+  const name = text(template.data?.name);
+  return (
+    <div className="grid gap-4">
+      <ul aria-label="Readiness" className="grid gap-1 text-sm">
+        {(o.readiness ?? []).map((r) => (
+          <li key={r.key} className="flex items-center gap-2">
+            {r.complete ? <CheckCircle2 className="size-4" aria-label="Done" /> : <Circle className="text-muted-foreground size-4" aria-label="Not done" />}
+            <span>{r.label}</span>
+            {!r.complete && r.details?.length ? <span className="text-muted-foreground text-xs">Missing: {r.details.join(", ")}</span> : null}
+          </li>
+        ))}
+      </ul>
+      <KeyValueList columns={2} items={[
+        { label: "Source rows", value: n(o.total_rows) },
+        { label: "Pages rendered", value: n(o.generated_pages) },
+        { label: "Live", value: n(o.live_pages) },
+        { label: "Failed", value: n(o.failed_pages) },
+        { label: "Changed since render", value: n(o.changed_rows) },
+        { label: "Hand-edited", value: n(o.manual_overrides) },
+        { label: "Last render", value: shortDate(o.last_generation) || null },
+        { label: "Last publish", value: shortDate(o.last_publish) || null },
+        { label: "Next automatic render", value: o.next_regeneration || null },
+        { label: "Search score (average)", value: seo?.average_score == null ? null : String(seo.average_score) },
+        { label: "Search issues", value: issues.length ? issues.map(([k, c]) => `${wording(k)}: ${c}`).join(", ") : null, wide: true },
+        { label: "Pages with no links in", value: n(ws.data.links?.orphan_pages?.length) },
+        { label: "Address pattern", value: ws.data.template?.slug_template ?? campaign.slug_template ?? null, mono: true },
+        {
+          label: "Template page",
+          wide: true,
+          value: templateId ? <a className="inline-flex items-center gap-1 underline" href={pagesHref(templateId)}>{name || "Open the template page"}<ExternalLink className="size-3" /></a> : null,
+        },
+      ]} />
+      {campaign.error_message ? <p role="alert" className="text-error text-sm">{campaign.error_message}</p> : null}
+      <ProgrammaticGenerate campaign={campaign} />
+      <ProgrammaticPublish campaign={campaign} />
+    </div>
+  );
+}

package/blocks/programmatic-pages/components/programmatic-pages-screen.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+/**
+ * ProgrammaticPagesScreen: the finished workspace for programmatic pages: one template landing page plus a data source makes one
+ * page per row (a page per account, per city, per integration). No props needed.
+ *
+ * Composes: ScreenLayout (title, stats), Toolbar (search, status and source filters), SplitView + DetailPanel (the selected
+ * campaign, deep link `?id=`, detail tab `?tab=`), FormSheet (new campaign via ProgrammaticCampaignForm), ProgrammaticOverview
+ * (with ProgrammaticGenerate and ProgrammaticPublish), ProgrammaticGeneratedPages, ProgrammaticPreview, ProgrammaticVariables,
+ * ProgrammaticSource, ProgrammaticSettings and the form again in edit mode.
+ *
+ * User flows: see every campaign with its state, source and page counts (search; filter by state and source); create one from a
+ * template page and a list or table; open it to see its readiness and numbers; render all pages (free; confirmed when the approval
+ * mode publishes automatically) and follow the run; read, search and filter the generated pages, replace one page's HTML, mark pages
+ * ready, regenerate them, take them off the live site (confirmed), delete them (confirmed), export their addresses, send live ones to
+ * Search Console (confirmed); publish waiting pages, republish everything or roll the last publish back (each confirmed with its
+ * page count); preview one row; set per-variable fallbacks and limits; switch or import the source (a sitemap); set regeneration,
+ * publishing, search and link settings; edit the name and address pattern; delete a campaign (confirmed). The template page is edited
+ * in the pages screen, linked from the Overview.
+ *
+ * SDK operations: listProgrammaticCampaigns, deleteProgrammaticCampaign (destructive, confirmed); everything else lives in the
+ * composed parts, which confirm every action that changes the live site.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Layers, Plus, Trash2 } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { SelectFilter } from "@/g8/components/screen/filter-controls";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { shortDate } from "@/g8/pages/lib/studio";
+import { CAMPAIGN_STATUSES, SOURCE_TYPES, campaignRows, sourceOf, wording } from "../lib/programmatic-types";
+import type { Campaign } from "../lib/programmatic-types";
+import { ProgrammaticCampaignForm } from "./programmatic-campaign-form";
+import { ProgrammaticGeneratedPages } from "./programmatic-generated-pages";
+import { ProgrammaticOverview } from "./programmatic-overview";
+import { ProgrammaticPreview } from "./programmatic-preview";
+import { ProgrammaticSettings } from "./programmatic-settings";
+import { ProgrammaticSource } from "./programmatic-source";
+import { ProgrammaticVariables } from "./programmatic-variables";
+
+export interface ProgrammaticPagesScreenProps {
+  /** Where a campaign's template page is edited. Default: /pages?id=<id> (the pages screen). */
+  pagesHref?: (templatePageId: string) => string;
+  renderRowActions?: (campaign: Campaign) => ReactNode;
+  renderDetailActions?: (campaign: Campaign) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (campaign: Campaign) => ReactNode }[];
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+const tone = (s?: string | null) => (s === "completed" ? "positive" : s === "failed" ? "negative" : s === "generating" || s === "validating" ? "info" : "neutral");
+const sourceLabel = (c: Campaign): string => SOURCE_TYPES.find((t) => t.value === sourceOf(c).type)?.label ?? "";
+const sum = (rows: Campaign[], pick: (c: Campaign) => number | null | undefined): number | null => {
+  const known = rows.map(pick).filter((v): v is number => typeof v === "number");
+  return known.length ? known.reduce((a, b) => a + b, 0) : null;
+};
+
+export function ProgrammaticPagesScreen({ pagesHref, renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, className }: ProgrammaticPagesScreenProps) {
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const [tab, setTab] = useUrlState("tab", "overview");
+  const expandProps = { onExpand: () => setView("full"), onCollapse: view === "full" ? () => setView(null) : undefined };
+  const [search, setSearch] = useState("");
+  const [status, setStatus] = useState("");
+  const [source, setSource] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [toDelete, setToDelete] = useState<Campaign | null>(null);
+
+  const list = useG8Query((signal) => g8Get("/programmatic-campaigns", {}, { signal }).then((r) => campaignRows(r.data)), [], { key: ["programmatic", "list"] });
+  const remove = useG8Mutation((c: Campaign) => g8Delete(`/programmatic-campaigns/${encodeURIComponent(c.id)}`), {
+    onSuccess: (_r, c) => { setToDelete(null); if (c.id === id) { setId(null); setView(null); } },
+    invalidates: [["programmatic"]],
+  });
+
+  const all = list.data ?? [];
+  const q = search.trim().toLowerCase();
+  const shown = all.filter((c) => (!status || c.status === status) && (!source || sourceOf(c).type === source) && (!q || `${c.name} ${c.slug_template ?? ""}`.toLowerCase().includes(q)));
+  const selected = all.find((c) => c.id === id);
+  const closeDetail = (): void => { setId(null); setView(null); setTab(null); };
+  const rendered = sum(all, (c) => c.pages_generated);
+  const failed = sum(all, (c) => c.pages_failed);
+
+  const rows = list.error ? <ApiError error={list.error} title="Could not load programmatic campaigns" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<Layers className="size-8" />} title={all.length === 0 ? "No programmatic campaigns yet" : "No campaigns match"} description={all.length === 0 ? "Pick a template landing page and a list or table. One page is made for every row: a page per account, per city, per integration." : "Try another search or filter."} action={all.length === 0 ? <Button onClick={() => setCreating(true)}>Create your first campaign</Button> : undefined} />
+  ) : (
+    <>
+      <p role="status" className="text-muted-foreground mb-2 text-xs">{shown.length === all.length ? `All ${plural(all.length, "campaign")}` : `${shown.length.toLocaleString()} of ${plural(all.length, "campaign")}`}</p>
+      <ul className="grid gap-2">
+        {shown.map((c) => (
+          <li key={c.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${c.id === id ? "bg-muted" : ""}`}>
+            <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setId(c.id)}>
+              <span className="block truncate font-medium">{c.name}</span>
+              <span className="text-muted-foreground block truncate text-xs">{sourceLabel(c) || "Source unknown"} · {c.pages_generated == null ? "-" : c.pages_generated.toLocaleString()} of {c.total_pages == null ? "-" : c.total_pages.toLocaleString()} pages · {shortDate(c.last_generated_at) || "not rendered"}</span>
+            </button>
+            <StatusPill tone={tone(c.status)}>{c.status ? wording(c.status) : "Unknown"}</StatusPill>
+            <div className="flex gap-1">
+              <Button size="sm" variant="ghost" aria-label={`Delete ${c.name}`} onClick={() => { remove.reset(); setToDelete(c); }}><Trash2 className="size-4" /></Button>
+              {renderRowActions?.(c)}
+            </div>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+
+  const detail = selected ? (
+    <DetailPanel
+      title={selected.name}
+      subtitle={selected.slug_template ?? undefined}
+      badges={<StatusPill tone={tone(selected.status)}>{selected.status ? wording(selected.status) : "Unknown"}</StatusPill>}
+      actions={renderDetailActions?.(selected)}
+      onClose={closeDetail}
+      {...expandProps}
+      activeTab={tab}
+      onTabChange={(t) => setTab(t === "overview" ? null : t)}
+      tabs={[
+        { id: "overview", label: "Overview", content: <ProgrammaticOverview key={selected.id} campaign={selected} pagesHref={pagesHref} /> },
+        { id: "pages", label: "Pages", content: <ProgrammaticGeneratedPages key={selected.id} campaign={selected} /> },
+        { id: "preview", label: "Preview", content: <ProgrammaticPreview key={selected.id} campaign={selected} /> },
+        { id: "variables", label: "Variables", content: <ProgrammaticVariables key={selected.id} campaign={selected} /> },
+        { id: "source", label: "Source", content: <ProgrammaticSource key={selected.id} campaign={selected} /> },
+        { id: "settings", label: "Settings", content: <ProgrammaticSettings key={selected.id} campaign={selected} /> },
+        { id: "edit", label: "Edit", content: <ProgrammaticCampaignForm key={selected.id} campaign={selected} onSaved={() => void list.refetch()} /> },
+        { id: "details", label: "Details", content: <CampaignDetails campaign={selected} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })),
+      ]}
+    />
+  ) : null;
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Programmatic pages"
+      description="One template page and one data source make a page for every row: a page per account, per city, per integration."
+      icon={<Layers className="size-5" />}
+      actions={<Button size="sm" onClick={() => setCreating(true)}><Plus className="size-4" />New campaign</Button>}
+      stats={[
+        { label: "Campaigns", value: list.data ? all.length.toLocaleString() : "..." },
+        { label: "Pages rendered", value: list.data ? (rendered == null ? "-" : rendered.toLocaleString()) : "..." },
+        { label: "Failed pages", value: list.data ? (failed == null ? "-" : failed.toLocaleString()) : "...", tone: failed ? "negative" : undefined },
+        { label: "Rendering now", value: list.data ? all.filter((c) => c.status === "generating").length.toLocaleString() : "...", tone: "positive" },
+      ]}
+    >
+      <SplitView
+        list={(
+          <div className="grid gap-3">
+            <Toolbar
+              search={{ value: search, onChange: setSearch, placeholder: "Search campaigns" }}
+              filters={(<>
+                <SelectFilter label="state" value={status} onChange={setStatus} any="Any state" options={CAMPAIGN_STATUSES.map((s) => ({ value: s, label: wording(s) }))} />
+                <SelectFilter label="source" value={source} onChange={setSource} any="Any source" options={SOURCE_TYPES.map((t) => ({ value: t.value, label: t.label }))} />
+              </>)}
+              actions={toolbarActions}
+            />
+            {rows}
+          </div>
+        )}
+        detail={detail}
+        detailOpen={Boolean(selected)}
+        onCloseDetail={closeDetail}
+        expanded={view === "full"}
+        onExpandedChange={(e) => setView(e ? "full" : null)}
+        detailWidth="xl"
+      />
+      <FormSheet open={creating} onOpenChange={setCreating} title="New programmatic campaign" description="Nothing is rendered or published until you ask.">
+        {creating ? <ProgrammaticCampaignForm onCancel={() => setCreating(false)} onSaved={(created) => { setCreating(false); void list.refetch(); setTab(null); setId(created.id); }} /> : null}
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={toDelete !== null}
+        tier="destructive"
+        title={`Delete ${toDelete?.name ?? "this campaign"} and at least its ${plural(toDelete ? (toDelete.pages_generated ?? 0) + (toDelete.pages_failed ?? 0) : 0, "page")}?`}
+        affected={toDelete ? (toDelete.pages_generated ?? 0) + (toDelete.pages_failed ?? 0) : undefined}
+        description={<><p>The campaign and every page it generated are removed. The count is at least this many: a re-run keeps earlier pages, so more can go. On a hosted address a live page stops being served as soon as it is deleted; on a custom domain its last published copy may stay up until the next publish. Unpublish first if you only want pages offline.</p>{remove.error ? <ApiError error={remove.error} title="Could not delete the campaign" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={remove.loading}
+        onCancel={() => setToDelete(null)}
+        onConfirm={() => { if (toDelete) void remove.mutate(toDelete); }}
+      />
+    </ScreenLayout>
+  );
+}
+
+function CampaignDetails({ campaign }: { campaign: Campaign }) {
+  const src = sourceOf(campaign);
+  return (
+    <KeyValueList
+      columns={2}
+      items={[
+        { label: "Name", value: campaign.name },
+        { label: "State", value: campaign.status ? wording(campaign.status) : null },
+        { label: "Lifecycle", value: campaign.lifecycle_state ? wording(campaign.lifecycle_state) : null },
+        { label: "Changes", value: campaign.change_state && campaign.change_state !== "no_changes" ? wording(campaign.change_state) : null },
+        { label: "Source", value: sourceLabel(campaign) || null },
+        { label: "Source name", value: src.name || null },
+        { label: "Address pattern", value: campaign.slug_template ?? null, mono: true, wide: true },
+        { label: "Pages rendered", value: campaign.pages_generated == null ? null : campaign.pages_generated.toLocaleString() },
+        { label: "Pages failed", value: campaign.pages_failed == null ? null : campaign.pages_failed.toLocaleString() },
+        { label: "Created", value: shortDate(campaign.created_at) || null },
+        { label: "Updated", value: shortDate(campaign.updated_at) || null },
+        { label: "Campaign id", value: campaign.id, mono: true },
+      ]}
+    />
+  );
+}

package/blocks/programmatic-pages/components/programmatic-preview.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+/**
+ * ProgrammaticPreview: see one page rendered for one source row, without saving anything.
+ *
+ * SDK operations, in order:
+ *   1. getProgrammaticWorkspace (GET /programmatic-campaigns/{id}/workspace)    read   the first sample rows of the source
+ *   2. previewProgrammaticPage (POST /programmatic-campaigns/{id}/preview)      write  renders one row; FREE, saves nothing
+ * A row is chosen from the sample rows the workspace returns (only rows with a numeric id can be asked for by id); "First row" sends
+ * no row at all and the API uses the source's first row. The HTML is shown in a sandboxed frame with scripts off.
+ */
+
+import { useState } from "react";
+import { Eye } from "lucide-react";
+import { Button, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyValue, KeyValueList } from "@/g8/components/screen/key-value-list";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { text } from "@/g8/pages/lib/studio";
+import type { Rec } from "@/g8/pages/lib/studio";
+import { useProgrammaticWorkspace } from "../hooks/use-programmatic-workspace";
+import type { Campaign } from "../lib/programmatic-types";
+
+export interface ProgrammaticPreviewProps {
+  campaign: Campaign;
+}
+
+interface Rendered { html?: string; slug?: string; contact_id?: number | null; contact_name?: string }
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+/** A readable name for a source row: a person, company or title field, else its position. */
+export function rowLabel(row: Rec, index: number): string {
+  const person = [text(row.first_name), text(row.last_name)].filter(Boolean).join(" ");
+  return person || text(row.name) || text(row.company) || text(row.company_name) || text(row.title) || text(row.email) || `Row ${index + 1}`;
+}
+
+export function ProgrammaticPreview({ campaign }: ProgrammaticPreviewProps) {
+  const ws = useProgrammaticWorkspace(campaign.id);
+  const [rowId, setRowId] = useState("");
+  const rows = (ws.data?.data?.sample_rows ?? []).map((r, i) => ({ id: typeof r.id === "number" ? r.id : null, label: rowLabel(r, i) })).filter((r): r is { id: number; label: string } => r.id !== null);
+  const render = useG8Mutation((id: string) => g8Post<Rendered>(`/programmatic-campaigns/${encodeURIComponent(campaign.id)}/preview`, id ? { contact_id: Number(id) } : {}));
+  const out = render.data?.data;
+  return (
+    <section aria-label="Preview" className="grid gap-3">
+      <div className="flex flex-wrap items-end gap-2">
+        <div>
+          <Label htmlFor="g8-pp-prev-row" className="mb-1">Source row</Label>
+          <select id="g8-pp-prev-row" className={SELECT} value={rowId} onChange={(e) => setRowId(e.target.value)}>
+            <option value="">First row</option>
+            {rows.map((r) => <option key={r.id} value={r.id}>{r.label}</option>)}
+          </select>
+        </div>
+        <Button size="sm" loading={render.loading} onClick={() => void render.mutate(rowId)}><Eye className="size-4" />Render preview</Button>
+      </div>
+      {ws.error ? <ApiError error={ws.error} title="Could not load the source rows" onRetry={() => void ws.refetch()} /> : null}
+      {render.error ? <ApiError error={render.error} title="Could not render the preview" /> : null}
+      {out ? (
+        <>
+          <KeyValueList columns={2} items={[{ label: "Row", value: out.contact_name || null }, { label: "Page address", value: out.slug || null, mono: true }]} />
+          {out.html ? <iframe title="Page preview" sandbox="" srcDoc={out.html} className="bg-background h-[28rem] w-full rounded-md border" /> : <p className="text-muted-foreground text-sm">The API returned no HTML <EmptyValue /></p>}
+        </>
+      ) : <p className="text-muted-foreground text-sm">Pick a row and render it to see the finished page. Nothing is saved.</p>}
+    </section>
+  );
+}