@graph8/sdk 0.362.0 → 0.373.0

package/blocks/social-ads/components/campaign-editor.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+/**
+ * CampaignEditor: change a campaign that already exists on an ad platform. Rename it, change the daily budget, the end
+ * date or the spend cap, and pause or resume it. Every change is previewed first and pushed to the platform only after
+ * a confirmation.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getAdCampaign                GET  /ad-campaigns/{id}                  (read; the saved values the form starts from)
+ *   2. getCampaignEditableFields    GET  /ad-campaigns/{id}/editable         (read; which fields this platform and state accept)
+ *   3. previewAdCampaignEdit        POST /ad-campaigns/{id}/edit-preview     (reads the platform, changes nothing; shows the changes and their consequences)
+ *   4. updateAdCampaign             PUT  /ad-campaigns/{id}                  (EXTERNAL, confirmed: changes the live campaign; only changed fields are sent)
+ *
+ * The form is read-only until both reads have loaded, so it can never save blanks over a real campaign. A field the
+ * platform will not accept is disabled with the platform's own reason. A 200 is not blanket success: a `partial` result
+ * lists which changes failed. The spend cap has no saved value to show, so it only changes when you type one.
+ */
+import { useState } from "react";
+import { Pause, Play } from "lucide-react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { asRec, campaignChanges, capabilityOf, dateInput, num, parseMoney, rowsOf, str } from "../lib/ads-extra";
+import type { CampaignEdit, Rec } from "../lib/ads-extra";
+
+export interface CampaignEditorProps {
+  campaignId: number;
+  /** Called after a change reached the platform, so lists and results refresh. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+const strings = (v: unknown): string[] => rowsOf<unknown>(v).map((x) => (typeof x === "string" ? x : str(asRec(x).description) || str(asRec(x).field) || JSON.stringify(x)));
+
+function Form({ campaign, editable, onChanged }: { campaign: Rec; editable: Rec; onChanged: () => void }) {
+  const base = `/ad-campaigns/${encodeURIComponent(str(campaign.id))}`;
+  const { ask, dialog, failure } = useConfirmAction();
+  // Only what the person typed is held as `edits`, shown over the saved copy: a reload never wipes typing, and a field they did not touch follows the server.
+  const saved = { name: str(campaign.name), daily_budget: num(campaign.daily_budget) == null ? "" : String(campaign.daily_budget), end_date: dateInput(campaign.end_date), spend_cap: "" };
+  const [edits, setEdits] = useState<Partial<typeof saved>>({});
+  const draft = { ...saved, ...edits };
+  const setDraft = (next: typeof saved): void => setEdits(Object.fromEntries(Object.entries(next).filter(([k, v]) => v !== saved[k as keyof typeof saved])) as Partial<typeof saved>);
+  const [review, setReview] = useState<{ body: CampaignEdit; changes: string[]; consequences: string[]; warnings: string[] } | null>(null);
+  const [outcome, setOutcome] = useState<{ ok: boolean; lines: string[] } | null>(null);
+  const body = campaignChanges(campaign, draft);
+  const cap = (f: string) => capabilityOf(editable, f);
+  const platform = str(campaign.platform);
+  const currency = str(campaign.currency, "USD");
+  const paused = str(campaign.status) === "paused";
+
+  const preview = useG8Mutation(async () => {
+    const d = asRec((await g8Post(`${base}/edit-preview`, body)).data);
+    setReview({ body, changes: strings(d.changes), consequences: strings(d.consequences), warnings: strings(d.warnings) });
+  });
+  const apply = (b: CampaignEdit | { action: "pause" | "resume" }, title: string, lines: string[]): void => ask({
+    tier: "external", title, confirmLabel: "Apply to the platform",
+    description: <><p>This changes the live campaign on {platform || "the platform"}. {platform ? `${platform} may review it again and a budget change can restart its learning phase.` : ""}</p>{lines.length ? <ul className="mt-2 list-disc pl-5 text-sm">{lines.map((l, i) => <li key={i}>{l}</li>)}</ul> : null}</>,
+    run: async () => {
+      const d = asRec((await g8Put(base, b)).data);
+      const failed = str(d.status) === "partial";
+      setOutcome({ ok: !failed, lines: [...strings(d.changes), ...strings(d.warnings)] });
+      setReview(null);
+      setEdits({});
+    },
+    onDone: onChanged,
+  });
+
+  const field = (key: "name" | "daily_budget" | "end_date" | "spend_cap", label: string, type: string, help?: string) => {
+    const c = cap(key);
+    return (
+      <div>
+        <Label htmlFor={`ce-${key}`} className="mb-1">{label}</Label>
+        <Input id={`ce-${key}`} type={type} value={draft[key]} disabled={!c.editable} onChange={(e) => { setDraft({ ...draft, [key]: e.target.value }); setReview(null); setOutcome(null); }} />
+        {!c.editable ? <p className="text-muted-foreground mt-1 text-xs">{c.reason ?? "The platform does not allow changing this right now."}</p> : help ? <p className="text-muted-foreground mt-1 text-xs">{help}</p> : null}
+      </div>
+    );
+  };
+  const budgetBad = draft.daily_budget.trim() !== "" && cap("daily_budget").editable && parseMoney(draft.daily_budget) === undefined;
+
+  return (
+    <div className="grid gap-4">
+      <form className="grid gap-3 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (Object.keys(body).length) void preview.mutate(undefined); }}>
+        {field("name", "Name", "text")}
+        {field("daily_budget", `Daily budget (${currency})`, "text", "Spent per day once the platform approves the campaign.")}
+        {field("end_date", "End date", "date")}
+        {field("spend_cap", `Spend cap (${currency})`, "text", "Pauses the campaign once this much is spent. Leave empty to keep the current cap.")}
+        {budgetBad ? <p role="alert" className="text-error-foreground text-xs sm:col-span-2">Enter a positive amount, for example 50 or 49.99.</p> : null}
+        <div className="flex gap-2 sm:col-span-2">
+          <Button type="submit" variant="outline" loading={preview.loading} disabled={Object.keys(body).length === 0 || budgetBad}>Review changes</Button>
+          {cap("status").editable ? (
+            <Button type="button" variant="ghost" onClick={() => apply({ action: paused ? "resume" : "pause" }, paused ? "Resume this campaign" : "Pause this campaign", [paused ? "The campaign starts delivering and spending again." : "The campaign stops delivering and spending."])}>
+              {paused ? <Play className="size-4" /> : <Pause className="size-4" />}{paused ? "Resume campaign" : "Pause campaign"}
+            </Button>
+          ) : null}
+        </div>
+      </form>
+      {preview.error ? <ApiError error={preview.error} title="Could not preview the changes" /> : null}
+      {review ? (
+        <SectionCard title="Review before applying" description="Nothing has changed yet.">
+          {review.changes.length ? <ul className="list-disc pl-5 text-sm">{review.changes.map((c, i) => <li key={i}>{c}</li>)}</ul> : <p className="text-sm">The platform reports no difference for these values.</p>}
+          {review.consequences.map((c, i) => <p key={i} className="text-muted-foreground mt-2 text-xs">{c}</p>)}
+          {review.warnings.map((w, i) => <p key={i} role="alert" className="mt-2 text-sm">{w}</p>)}
+          <div className="mt-3 flex gap-2"><Button onClick={() => apply(review.body, "Apply these changes", review.changes)}>Apply changes</Button><Button variant="ghost" onClick={() => setReview(null)}>Cancel</Button></div>
+        </SectionCard>
+      ) : null}
+      {outcome ? (
+        <p role="status" className="text-sm">{outcome.ok ? "Changes applied." : "Some changes were not applied."}{outcome.lines.length ? ` ${outcome.lines.join(" ")}` : ""}</p>
+      ) : null}
+      {failure ? <ApiError error={failure} title="The platform did not accept the change" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </div>
+  );
+}
+
+export function CampaignEditor({ campaignId, onChanged, className }: CampaignEditorProps) {
+  const base = `/ad-campaigns/${encodeURIComponent(String(campaignId))}`;
+  const campaign = useG8Query((signal) => g8Get(base, undefined, { signal }), [campaignId]);
+  const editable = useG8Query((signal) => g8Get(`${base}/editable`, undefined, { signal }), [campaignId]);
+  const error = campaign.error ?? editable.error;
+  return (
+    <div className={className}>
+      <SectionCard title="Edit campaign" description="Changes go to the ad platform after you confirm.">
+        {error ? <ApiError error={error} title="Could not load the campaign" onRetry={() => { void campaign.refetch(); void editable.refetch(); }} /> : !campaign.data || !editable.data ? <Skeleton className="h-32 w-full" aria-busy="true" /> : (
+          <Form key={campaignId} campaign={asRec(campaign.data.data)} editable={asRec(editable.data.data)} onChanged={() => { void campaign.refetch(); void editable.refetch(); onChanged?.(); }} />
+        )}
+      </SectionCard>
+    </div>
+  );
+}

package/blocks/social-ads/components/creative-concepts.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+/**
+ * CreativeConcepts: a concept board. Describe the ad and get 3 to 6 creative directions to react to before any image is
+ * generated; nothing is saved. Pick the one you like and hand its brief to your generator.
+ *
+ * SDK operations:
+ *   1. generateAdConcepts  POST /ad-creatives/concepts { brief?, count }   (BILLABLE, confirmed; one AI pass; saves nothing)
+ *
+ * The API quotes no price in advance and the balance is not checked here, so the dialog says what runs. Each concept is
+ * a name, a hook, a tone, a layout and two brand colours. `onUse` receives a ready-to-use brief for the chosen concept.
+ */
+import { useState } from "react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { g8Post } from "@/g8/lib/g8-client";
+import { rowsOf, str } from "../lib/ads-extra";
+import type { Rec } from "../lib/ads-extra";
+
+export interface CreativeConceptsProps {
+  /** Called with a brief built from the chosen concept (its name, hook, tone and layout). */
+  onUse?: (brief: string, concept: Rec) => void;
+  className?: string;
+}
+
+/** A hex colour the API sent, or undefined: a rogue value is never put in a style. */
+export function safeHex(v: unknown): string | undefined {
+  const t = str(v);
+  return /^#[0-9a-f]{3,8}$/i.test(t) ? t : undefined;
+}
+
+export function conceptBrief(c: Rec): string {
+  const tone = rowsOf<string>(c.tone).map(String).join(", ");
+  return [`Concept: ${str(c.name)}.`, str(c.hook) ? `Hook: ${str(c.hook)}.` : "", tone ? `Tone: ${tone}.` : "", str(c.layout) ? `Layout: ${str(c.layout)}.` : ""].filter(Boolean).join(" ");
+}
+
+export function CreativeConcepts({ onUse, className }: CreativeConceptsProps) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const [brief, setBrief] = useState("");
+  const [count, setCount] = useState(4);
+  const [items, setItems] = useState<Rec[] | null>(null);
+  const go = (): void => ask({
+    tier: "billable", title: `Get ${count} creative concepts`, confirmLabel: "Get concepts",
+    description: "One AI pass writes the directions. Nothing is saved and no image is generated. Uses credits; the API gives no price in advance and your balance is not checked here.",
+    run: async () => { const res = await g8Post("/ad-creatives/concepts", { brief: brief.trim() || undefined, count }); setItems(rowsOf<Rec>(res.data, "concepts")); },
+  });
+  return (
+    <SectionCard className={className} title="Concept board" description="React to a few directions before generating anything.">
+      <form className="mb-3 flex flex-wrap items-end gap-2" onSubmit={(e) => { e.preventDefault(); go(); }}>
+        <div className="min-w-60 flex-1"><Label htmlFor="cc-brief" className="mb-1">Brief for the concepts</Label><Input id="cc-brief" value={brief} maxLength={2000} onChange={(e) => setBrief(e.target.value)} /></div>
+        <div><Label htmlFor="cc-count" className="mb-1">How many</Label><select id="cc-count" className="border-input bg-background h-9 rounded-md border px-2 text-sm" value={count} onChange={(e) => setCount(Number(e.target.value))}>{[3, 4, 5, 6].map((n) => <option key={n} value={n}>{n}</option>)}</select></div>
+        <Button type="submit">Get concepts</Button>
+      </form>
+      {items === null ? <EmptyState compact title="No concepts yet" /> : items.length === 0 ? <EmptyState compact title="No concepts came back" description="Try a more specific brief." /> : (
+        <ul className="grid gap-3 sm:grid-cols-2">
+          {items.map((c, i) => (
+            <li key={i} className="grid gap-1 rounded-md border p-3">
+              <div className="flex items-center gap-2"><span className="size-4 rounded border" style={{ background: safeHex(c.bg) }} aria-hidden /><span className="size-4 rounded border" style={{ background: safeHex(c.accent) }} aria-hidden /><span className="text-sm font-medium">{str(c.name)}</span></div>
+              <p className="text-sm">{str(c.hook)}</p>
+              <p className="text-muted-foreground text-xs">{rowsOf<string>(c.tone).join(", ")}{str(c.layout) ? ` · ${str(c.layout)}` : ""}</p>
+              {onUse ? <div><Button size="sm" variant="outline" aria-label={`Use ${str(c.name)}`} onClick={() => onUse(conceptBrief(c), c)}>Use this concept</Button></div> : null}
+            </li>
+          ))}
+        </ul>
+      )}
+      {failure ? <ApiError error={failure} title="Could not get concepts" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </SectionCard>
+  );
+}

package/blocks/social-ads/components/creative-detail.tsx

@@ -0,0 +1,155 @@
+"use client";
+
+/**
+ * CreativeDetail: the complete screen for one AI ad creative. Finds it by id (so `?id=` deep links work), shows the image and every
+ * copy field, and offers every action: edit headline, primary text, description and call to action; make a new image (billable);
+ * move it to the gallery; delete. A creative that is still generating re-reads itself until it finishes. The AI tools tab edits by
+ * instruction, rewrites a field, reviews, makes other sizes and more (CreativeTools); Revisions lists and restores earlier versions.
+ *
+ * SDK operations, in order:
+ *   1. listAdCreatives          GET    /ad-creatives?limit=100                   (read)
+ *   2. updateAdCreative         PATCH  /ad-creatives/{id}                        (write)
+ *   3. regenerateAdCreativeImage POST  /ad-creatives/{id}/regenerate-image       (billable, confirmed; no advance price)
+ *   4. moveAdCreativeToGallery  POST   /ad-creatives/{id}/move-to-gallery        (write)
+ *   5. deleteAdCreative         DELETE /ad-creatives/{id}                        (destructive, confirmed; 404 counts as done)
+ *   6. getAdCreativeStatus      GET    /ad-creatives/{id}/status                 (read; polled every 4 s while the creative is generating.
+ *      The payload is open-shaped in the contract: only a string `status` is read, and a change reloads the creative.)
+ */
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import type { AdCreative } from "../lib/social-ads-types";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { AskButton, useConfirmAction } from "@/g8/components/confirmed-action";
+import { CreativeRevisions } from "./creative-revisions";
+import { CreativeTools } from "./creative-tools";
+
+export interface CreativeDetailProps {
+  creativeId: string;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  onChanged?: () => void;
+}
+
+const tone = (s: string) => (s === "gallery" || s === "completed" ? "positive" : s === "failed" ? "negative" : s === "generating" ? "info" : "neutral") as "positive" | "negative" | "info" | "neutral";
+
+export function CreativeDetail({ creativeId, onClose, onExpand, onCollapse, onChanged }: CreativeDetailProps) {
+  const { ask, dialog, failure } = useConfirmAction();
+  // Read the one creative by id (GET /ad-creatives/{id}), so an older creative outside the newest page still opens.
+  // A 404 means it no longer exists.
+  const list = useG8Query(async (signal) => {
+    try {
+      const body = (await g8Get<AdCreative | { data?: AdCreative }>(`/ad-creatives/${encodeURIComponent(creativeId)}`, undefined, { signal })).data;
+      const one = body && typeof body === "object" && "data" in body && body.data ? body.data : (body as AdCreative | null);
+      return one && one.id != null ? one : null;
+    } catch (err) {
+      if ((err as { status?: number })?.status === 404) return null;
+      throw err;
+    }
+  }, [creativeId]);
+  const creative = list.data ?? undefined;
+  const [form, setForm] = useState({ headline: "", primary_text: "", description: "", cta: "" });
+  const generating = creative?.status === "generating";
+
+  useEffect(() => {
+    if (!creative) return;
+    setForm({ headline: creative.headline ?? "", primary_text: creative.primary_text ?? "", description: creative.description ?? "", cta: creative.cta ?? "" });
+  }, [creative?.id, creative?.headline, creative?.primary_text, creative?.description, creative?.cta]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    if (!generating) return;
+    const timer = setInterval(() => {
+      void g8Get(`/ad-creatives/${creativeId}/status`)
+        .then((res) => {
+          const next = (res.data as { status?: unknown } | null | undefined)?.status;
+          if (typeof next === "string" && next !== "generating") void list.refetch();
+        })
+        .catch(() => void list.refetch());
+    }, 4000);
+    return () => clearInterval(timer);
+  }, [generating, creativeId, list.refetch]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const save = useG8Mutation(() => g8Patch(`/ad-creatives/${creativeId}`, form), { onSuccess: () => { void list.refetch(); onChanged?.(); } });
+  const gallery = useG8Mutation(() => g8Post(`/ad-creatives/${creativeId}/move-to-gallery`, {}), { onSuccess: () => { void list.refetch(); onChanged?.(); } });
+  const changed = () => { void list.refetch(); onChanged?.(); };
+
+  if (list.error) return <ApiError error={list.error} title="Could not load the creative" onRetry={() => void list.refetch()} />;
+  if (list.data === undefined) return <Skeleton className="h-40 w-full" />;
+  if (!creative) return <EmptyState title="Creative not found" description="It may have been deleted." />;
+
+  const actions = (
+    <div className="flex flex-wrap gap-1">
+      <AskButton ask={ask} label="New image" tier="billable" title={`Make a new image for "${creative.name}"`} confirmLabel="Generate" disabled={generating}
+        description="Uses credits. The API gives no price in advance and your balance is not checked here." run={() => g8Post(`/ad-creatives/${creativeId}/regenerate-image`, {})} onDone={changed} />
+      {creative.status !== "gallery" && !generating ? (
+        <Button size="sm" variant="outline" disabled={gallery.loading} onClick={() => void gallery.mutate(undefined)}>Move to gallery</Button>
+      ) : null}
+      <AskButton ask={ask} label="Delete" variant="ghost" tier="destructive" title={`Delete "${creative.name}"`} confirmLabel="Delete"
+        description="The creative and its revisions are removed." tolerateStatus={[404]} run={() => g8Delete(`/ad-creatives/${creativeId}`)} onDone={() => { changed(); onClose?.(); }} />
+    </div>
+  );
+
+  const field = (key: keyof typeof form, label: string) => (
+    <div className="flex flex-col gap-1" key={key}>
+      <Label htmlFor={`cd-${key}`}>{label}</Label>
+      <Input id={`cd-${key}`} value={form[key]} onChange={(e) => setForm({ ...form, [key]: e.target.value })} />
+    </div>
+  );
+  const tabs = [
+    {
+      id: "creative",
+      label: "Creative",
+      content: (
+        <div className="space-y-4">
+          {creative.image_url ? <img src={creative.image_url} alt={creative.headline ?? creative.name} className="aspect-video w-full rounded object-cover" /> : (
+            <div className="flex aspect-video items-center justify-center rounded bg-muted text-sm text-muted-foreground">{generating ? "Generating..." : "No image"}</div>
+          )}
+          {creative.status === "failed" && creative.error_message ? <p role="alert" className="text-sm text-error-foreground">{creative.error_message}</p> : null}
+          <KeyValueList columns={2} items={[
+            { label: "Platform", value: creative.platform },
+            { label: "Format", value: creative.ad_format },
+            { label: "Headline", value: creative.headline ?? "-" },
+            { label: "Call to action", value: creative.cta ?? "-" },
+            { label: "Primary text", value: creative.primary_text ?? "-" },
+            { label: "Description", value: creative.description ?? "-" },
+          ]} />
+        </div>
+      ),
+    },
+    {
+      id: "edit",
+      label: "Edit copy",
+      content: (
+        <SectionCard title="Edit copy">
+          <div className="space-y-3">
+            {field("headline", "Headline")}
+            {field("primary_text", "Primary text")}
+            {field("description", "Description")}
+            {field("cta", "Call to action")}
+            <Button size="sm" disabled={save.loading || generating} onClick={() => void save.mutate(undefined)}>Save copy</Button>
+            {save.error ? <ApiError error={save.error} title="Could not save" /> : null}
+            {gallery.error ? <ApiError error={gallery.error} title="Could not move to the gallery" /> : null}
+          </div>
+        </SectionCard>
+      ),
+    },
+    { id: "ai", label: "AI tools", content: <CreativeTools creativeId={creativeId} platform={creative.platform} status={creative.status} onChanged={changed} /> },
+    { id: "revisions", label: "Revisions", content: <CreativeRevisions creativeId={creativeId} onRestored={changed} /> },
+  ];
+  return (
+    <>
+      <DetailPanel title={creative.headline || creative.name} subtitle={`${creative.platform} · ${creative.ad_format}`} badges={<StatusPill tone={tone(creative.status)}>{creative.status}</StatusPill>} actions={actions} tabs={tabs} onClose={onClose} onExpand={onExpand} onCollapse={onCollapse} />
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </>
+  );
+}

package/blocks/social-ads/components/creative-gallery.tsx

@@ -7,7 +7,7 @@
  *
  * SDK operations, in order:
  *   1. getAdCreativeSpecs       GET    /ad-creatives/specs                         (read)  { platforms, specs: { platform: { format: { label } } }, ctas }
- *   2. listAdCreatives          GET    /ad-creatives?status&platform&limit&offset  (read)  { items }
+ *   2. listAdCreatives          GET    /ad-creatives?status&platform&limit&offset  (read)  { items }; 50 at a time, "Load more" reads the next 50
  *   3. createAdCreative         POST   /ad-creatives { platform, ad_format, prompt, name }  (billable)  ConfirmSpendDialog first; 201 with status "generating"
  *      While any card is `generating` the list is re-read with useJobPoll (no streams) until none is.
  *   5. updateAdCreative         PATCH  /ad-creatives/{id} { headline, primary_text, description, cta }  (write)
@@ -15,6 +15,7 @@
  *   7. moveAdCreativeToGallery  POST   /ad-creatives/{id}/move-to-gallery          (write)  needs the ads launch permission
  *   8. deleteAdCreative         DELETE /ad-creatives/{id}                          (destructive)
  * The API quotes no price for generation: the dialog says credits are used and the balance is not checked here.
+ * A "Concept board" (CreativeConcepts, billable and confirmed) offers directions to react to; choosing one fills the brief.
  */
 
 import { useState } from "react";
@@ -24,31 +25,45 @@ import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { byOffset, hasNextOf } from "@/g8/lib/paging";
+import { LoadMore } from "@/g8/components/paging-notices";
 import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
 import { listOf } from "../lib/social-ads-types";
+import { CreativeConcepts } from "./creative-concepts";
 import type { AdCreative } from "../lib/social-ads-types";
 
 export interface CreativeGalleryProps {
   /** Show only creatives in this state. Default: all working creatives. */
   status?: "draft" | "completed" | "gallery";
+  /** Called when a person opens a creative (show a CreativeDetail). */
+  onSelectCreative?: (creative: AdCreative) => void;
   className?: string;
 }
 
 interface Specs { platforms: string[]; specs: Record<string, Record<string, { label: string }>> }
 type Pending = { kind: "create" } | { kind: "regenerate" | "delete"; creative: AdCreative };
 
-export function CreativeGallery({ status, className }: CreativeGalleryProps) {
+/** Creatives per read; "Load more" appends the next page (the gallery used to stop silently at 50). */
+const CREATIVE_PAGE = 50;
+
+export function CreativeGallery({ status, onSelectCreative, className }: CreativeGalleryProps) {
   const [platform, setPlatform] = useState("");
   const [form, setForm] = useState({ platform: "meta", format: "", prompt: "", name: "" });
   const [pending, setPending] = useState<Pending | null>(null);
-  const [editing, setEditing] = useState<{ id: string; headline: string; primary_text: string } | null>(null);
+  const [editing, setEditing] = useState<{ id: string; headline: string; primary_text: string; orig: { headline: string; primary_text: string } } | null>(null);
   const [busy, setBusy] = useState<string | null>(null);
   const [failure, setFailure] = useState<unknown>(null);
 
   const specs = useG8Query(async (signal) => (await g8Get<Specs>("/ad-creatives/specs", undefined, { signal })).data, []);
-  const list = useG8Query(async (signal) => listOf<AdCreative>((await g8Get("/ad-creatives", { status, platform: platform || undefined, limit: 50 }, { signal })).data), [status, platform]);
+  const list = useLoadMoreList(byOffset<AdCreative>(CREATIVE_PAGE, async (offset, signal) => {
+    const env = await g8Get("/ad-creatives", { status, platform: platform || undefined, limit: CREATIVE_PAGE, offset: offset || undefined }, { signal });
+    const rows = listOf<AdCreative>(env.data);
+    return { rows, hasNext: hasNextOf(env, CREATIVE_PAGE, rows.length) };
+  }), [status, platform]);
   const items = list.data ?? [];
+  const [boardOpen, setBoardOpen] = useState(false);
   const generating = items.filter((c) => c.status === "generating");
   useJobPoll(async () => (await list.refetch()) ?? ([{ status: "generating" }] as AdCreative[]), { enabled: generating.length > 0, intervalMs: 4000, maxAttempts: 100, isTerminal: (rows) => !rows.some((c) => c.status === "generating") });
 
@@ -68,7 +83,15 @@ export function CreativeGallery({ status, className }: CreativeGalleryProps) {
     if (pending.kind === "regenerate") return void run(id, () => g8Post(`/ad-creatives/${id}/regenerate-image`, {}));
     return void run(id, () => g8Delete(`/ad-creatives/${id}`), true);
   };
-  const saveCopy = () => editing && void run(editing.id, async () => { await g8Patch(`/ad-creatives/${editing.id}`, { headline: editing.headline, primary_text: editing.primary_text }); setEditing(null); });
+  // Only the field(s) the person changed are sent (the backend overwrites whatever it receives, and a regenerate may finish while the copy is open); nothing changed means no request.
+  const saveCopy = () => {
+    if (!editing) return;
+    const changed: Record<string, string> = {};
+    if (editing.headline !== editing.orig.headline) changed.headline = editing.headline;
+    if (editing.primary_text !== editing.orig.primary_text) changed.primary_text = editing.primary_text;
+    if (Object.keys(changed).length === 0) return setEditing(null);
+    void run(editing.id, async () => { await g8Patch(`/ad-creatives/${editing.id}`, changed); setEditing(null); });
+  };
 
   const tier: ConfirmTier = pending?.kind === "delete" ? "destructive" : "billable";
   const name = pending && pending.kind !== "create" ? pending.creative.name : "";
@@ -101,10 +124,10 @@ export function CreativeGallery({ status, className }: CreativeGalleryProps) {
                 <Input aria-label="Primary text" value={editing.primary_text} onChange={(e) => setEditing({ ...editing, primary_text: e.target.value })} />
                 <div className="flex gap-1"><Button size="sm" loading={busy === c.id} onClick={saveCopy}>Save</Button><Button size="sm" variant="ghost" onClick={() => setEditing(null)}>Cancel</Button></div>
               </div>
-            ) : <div><p className="text-sm font-medium">{c.headline || c.name}</p><p className="line-clamp-2 text-sm text-muted-foreground">{c.primary_text}</p></div>}
+            ) : <div>{onSelectCreative ? <button type="button" className="text-left text-sm font-medium hover:underline" onClick={() => onSelectCreative(c)}>{c.headline || c.name}</button> : <p className="text-sm font-medium">{c.headline || c.name}</p>}<p className="line-clamp-2 text-sm text-muted-foreground">{c.primary_text}</p></div>}
             {c.status === "failed" && c.error_message ? <p className="text-xs text-destructive">{c.error_message}</p> : null}
             <div className="flex flex-wrap gap-1">
-              <Button size="sm" variant="ghost" disabled={busy != null || c.status === "generating"} onClick={() => setEditing({ id: c.id, headline: c.headline ?? "", primary_text: c.primary_text ?? "" })}>Edit copy</Button>
+              <Button size="sm" variant="ghost" disabled={busy != null || c.status === "generating"} onClick={() => setEditing({ id: c.id, headline: c.headline ?? "", primary_text: c.primary_text ?? "", orig: { headline: c.headline ?? "", primary_text: c.primary_text ?? "" } })}>Edit copy</Button>
               <Button size="sm" variant="ghost" loading={busy === c.id} disabled={busy != null || c.status === "generating"} onClick={() => setPending({ kind: "regenerate", creative: c })}>New image</Button>
               {c.status !== "gallery" && c.status !== "generating" ? <Button size="sm" variant="outline" disabled={busy != null} onClick={() => void run(c.id, () => g8Post(`/ad-creatives/${c.id}/move-to-gallery`, {}))}>Move to gallery</Button> : null}
               <Button size="sm" variant="ghost" disabled={busy != null} onClick={() => setPending({ kind: "delete", creative: c })}>Delete</Button>
@@ -112,6 +135,11 @@ export function CreativeGallery({ status, className }: CreativeGalleryProps) {
           </li>
         ))}
       </ul>
+      <LoadMore shown={items.length} noun="creatives" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+      <details className="rounded-md border p-3" onToggle={(e) => setBoardOpen((e.currentTarget as HTMLDetailsElement).open)}>
+        <summary className="cursor-pointer text-sm font-medium">Concept board</summary>
+        {boardOpen ? <CreativeConcepts className="mt-3" onUse={(brief) => setForm((f) => ({ ...f, prompt: brief.slice(0, 2000) }))} /> : null}
+      </details>
       <ConfirmSpendDialog open={pending != null} tier={tier}
         title={pending?.kind === "create" ? `Generate a ${form.platform} creative` : pending?.kind === "regenerate" ? `Make a new image for "${name}"` : `Delete "${name}"`}
         description={tier === "billable" ? "Uses credits (copy and image). The API gives no price in advance and your balance is not checked here." : "The creative and its revisions are removed."}

package/blocks/social-ads/components/creative-revisions.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * CreativeRevisions: the saved versions of one ad creative (every edit, rewrite and regeneration is kept), with restore.
+ *
+ * SDK operations:
+ *   1. listAdCreativeRevisions   GET  /ad-creatives/{id}/revisions                    (read; oldest first, as the API returns them)
+ *   2. restoreAdCreativeRevision POST /ad-creatives/{id}/restore-revision { index }   (write; the creative takes that version's copy and image)
+ *
+ * Revisions are open dicts: each row shows whatever of `label`, `source`, `headline` and `created_at` it has. Restoring
+ * asks for a second click because it replaces what the creative shows now.
+ */
+import { useState } from "react";
+import { Button, Skeleton } 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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { num, rowsOf, str, whenText } from "../lib/ads-extra";
+import type { Rec } from "../lib/ads-extra";
+
+export interface CreativeRevisionsProps {
+  creativeId: string;
+  /** Called after a revision was restored, so the detail reloads. */
+  onRestored?: () => void;
+  className?: string;
+}
+
+export function CreativeRevisions({ creativeId, onRestored, className }: CreativeRevisionsProps) {
+  const base = `/ad-creatives/${encodeURIComponent(creativeId)}`;
+  const list = useG8Query((signal) => g8Get(`${base}/revisions`, undefined, { signal }), [creativeId]);
+  const rows = rowsOf<Rec>(list.data?.data, "revisions");
+  const [sure, setSure] = useState<number | null>(null);
+  const restore = useG8Mutation((index: number) => g8Post(`${base}/restore-revision`, { index }), { onSuccess: () => { setSure(null); void list.refetch(); onRestored?.(); } });
+  return (
+    <SectionCard className={className} title="Revisions" description="Every change is kept. Restoring one replaces what the creative shows now.">
+      {list.error ? <ApiError error={list.error} title="Could not load the revisions" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? <Skeleton className="h-20 w-full" aria-busy="true" /> : rows.length === 0 ? (
+        <EmptyState compact title="No earlier versions" description="A version is kept each time the creative is edited." />
+      ) : (
+        <ul className="grid gap-2">
+          {rows.map((r, i) => {
+            const index = num(r.index) ?? i;
+            return (
+              <li key={index} className="flex items-center justify-between gap-3 rounded-md border p-3">
+                <div className="min-w-0 text-sm"><span className="font-medium">Version {index + 1}</span>{str(r.label) || str(r.source) ? <span className="text-muted-foreground"> {str(r.label) || str(r.source).replace(/_/g, " ")}</span> : null}<span className="text-muted-foreground block truncate text-xs">{whenText(r.created_at ?? r.at)}{str(r.headline) ? ` · ${str(r.headline)}` : ""}</span></div>
+                {sure === index ? <div className="flex gap-1"><Button size="sm" loading={restore.loading} onClick={() => void restore.mutate(index)}>Replace the current version</Button><Button size="sm" variant="ghost" onClick={() => setSure(null)}>Cancel</Button></div> : <Button size="sm" variant="outline" aria-label={`Restore version ${index + 1}`} onClick={() => setSure(index)}>Restore</Button>}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+      {restore.error ? <ApiError error={restore.error} title="Could not restore that version" /> : null}
+    </SectionCard>
+  );
+}