@graph8/sdk 0.361.0 → 0.370.0

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

@@ -0,0 +1,150 @@
+"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.
+ *
+ * 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";
+
+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>
+      ),
+    },
+  ];
+  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

@@ -32,17 +32,19 @@ 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) {
+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);
 
@@ -68,7 +70,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 +111,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>

package/blocks/social-ads/components/post-composer.tsx

@@ -26,6 +26,7 @@ import { g8Patch, g8Post } from "@/g8/lib/g8-client";
 import { useSocialAccounts } from "../hooks/use-social-accounts";
 import { formatInstant, isFuture, localInputToIso } from "../lib/social-ads-types";
 import type { PostVariant, SocialPost } from "../lib/social-ads-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface PostComposerProps {
   /** Called after a post was saved, scheduled or published. */
@@ -37,6 +38,7 @@ type Action = "schedule" | "publish";
 const newKey = () => globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`;
 
 export function PostComposer({ onSaved, className }: PostComposerProps) {
+  const brand = useBrand();
   const { accounts, loading, error, refetch } = useSocialAccounts();
   const [account, setAccount] = useState("");
   const [body, setBody] = useState("");
@@ -76,7 +78,7 @@ export function PostComposer({ onSaved, className }: PostComposerProps) {
   });
 
   if (error) return <ApiError error={error} title="Could not load social accounts" onRetry={() => void refetch()} />;
-  if (!loading && accounts.length === 0) return <EmptyState title="No social account connected" description="Connect a LinkedIn account in graph8 (Settings, Channels), then come back. It cannot be done through the API." />;
+  if (!loading && accounts.length === 0) return <EmptyState title="No social account connected" description={`Connect a LinkedIn account in ${brand.linkLabel} (Settings, Channels), then come back. It cannot be done through the API.`} />;
 
   const ready = body.trim().length > 0 && Boolean(chosen);
   const dialog = confirm === "publish"

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

@@ -0,0 +1,160 @@
+"use client";
+
+/**
+ * PostDetail: the complete screen for one social post. Loads the post by id (so `?id=` deep links work), shows every field
+ * (body, media, account, status, schedule, publish time, failure reason, link), and offers every action that fits its state:
+ * edit the draft, schedule, publish now, cancel a scheduled post, delete.
+ *
+ * SDK operations, in order:
+ *   1. getSocialPost      GET    /social/posts/{post_id}           (read)
+ *   2. updateSocialPost   PATCH  /social/posts/{post_id}           (write; draft body)
+ *   3. scheduleSocialPost POST   /social/posts/{post_id}/schedule  (external, confirmed)
+ *   4. publishSocialPost  POST   /social/posts/{post_id}/publish   (external, confirmed)
+ *   5. cancelSocialPost   POST   /social/posts/{post_id}/cancel    (destructive, confirmed)
+ *   6. deleteSocialPost   DELETE /social/posts/{post_id}           (destructive, confirmed; 404 counts as done)
+ * Times are instants shown in the viewer's zone with its name.
+ */
+import { useState } from "react";
+import { Button, Input, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+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 { formatInstant, isFuture, localInputToIso } from "../lib/social-ads-types";
+import type { SocialPost } from "../lib/social-ads-types";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { AskButton, useConfirmAction } from "@/g8/components/confirmed-action";
+
+export interface PostDetailProps {
+  postId: string;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  /** Called after any change (edit, publish, schedule, cancel, delete) so the list can reload. */
+  onChanged?: () => void;
+  /** Called after the post was deleted. */
+  onDeleted?: () => void;
+}
+
+const tone = (s: string) => (s === "live" ? "positive" : s === "failed" ? "negative" : s === "scheduled" ? "info" : "neutral") as "positive" | "negative" | "info" | "neutral";
+
+export function PostDetail({ postId, onClose, onExpand, onCollapse, onChanged, onDeleted }: PostDetailProps) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const query = useG8Query(async (signal) => (await g8Get<SocialPost>(`/social/posts/${postId}`, undefined, { signal })).data, [postId]);
+  const [body, setBody] = useState<string | null>(null);
+  const [when, setWhen] = useState("");
+  const save = useG8Mutation((text: string) => g8Patch(`/social/posts/${postId}`, { body: text }), {
+    onSuccess: () => {
+      setBody(null);
+      void query.refetch();
+      onChanged?.();
+    },
+  });
+  const post = query.data;
+  const changed = () => {
+    void query.refetch();
+    onChanged?.();
+  };
+
+  if (query.error) return <ApiError error={query.error} title="Could not load the post" onRetry={() => void query.refetch()} />;
+  if (!post) return <Skeleton className="h-40 w-full" />;
+  const editable = ["draft", "ready", "failed"].includes(post.status);
+  const preview = post.body.length > 60 ? `${post.body.slice(0, 60)}...` : post.body;
+
+  const actions = (
+    <div className="flex flex-wrap gap-1">
+      {editable ? (
+        <AskButton ask={ask} label="Publish now" tier="external" title={`Publish: "${preview}"`} confirmLabel="Publish"
+          description="The post goes live now on the connected account and cannot be recalled from here."
+          run={() => g8Post(`/social/posts/${postId}/publish`, {})} onDone={changed} />
+      ) : null}
+      {post.status === "scheduled" ? (
+        <AskButton ask={ask} label="Cancel schedule" tier="destructive" title={`Cancel: "${preview}"`} confirmLabel="Cancel post"
+          description="The scheduled post will not be published. It stays as a cancelled record."
+          run={() => g8Post(`/social/posts/${postId}/cancel`, {})} onDone={changed} />
+      ) : null}
+      {post.status !== "publishing" ? (
+        <AskButton ask={ask} label="Delete" variant="ghost" tier="destructive" title={`Delete: "${preview}"`} confirmLabel="Delete"
+          description="The post is removed. A post that is already live stays live on the network."
+          tolerateStatus={[404]} run={() => g8Delete(`/social/posts/${postId}`)} onDone={() => { onChanged?.(); onDeleted?.(); onClose?.(); }} />
+      ) : null}
+    </div>
+  );
+
+  const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const tabs = [
+    {
+      id: "post",
+      label: "Post",
+      content: (
+        <div className="space-y-4">
+          <SectionCard title="Content">
+            {body == null ? (
+              <p className="whitespace-pre-wrap text-sm">{post.body}</p>
+            ) : (
+              <div className="space-y-2">
+                <Textarea aria-label="Post body" rows={8} value={body} onChange={(e) => setBody(e.target.value)} />
+                <div className="flex gap-2">
+                  <Button size="sm" disabled={!body.trim() || save.loading} onClick={() => void save.mutate(body.trim())}>Save draft</Button>
+                  <Button size="sm" variant="ghost" onClick={() => setBody(null)}>Cancel</Button>
+                </div>
+                {save.error ? <ApiError error={save.error} title="Could not save" /> : null}
+              </div>
+            )}
+            {editable && body == null ? <Button size="sm" variant="outline" className="mt-3" onClick={() => setBody(post.body)}>Edit text</Button> : null}
+            {(post.media ?? []).length > 0 ? (
+              <ul className="mt-3 grid grid-cols-2 gap-2">
+                {(post.media ?? []).map((m) => (
+                  <li key={m.url}><img src={m.url} alt={m.alt ?? ""} className="aspect-video w-full rounded object-cover" /></li>
+                ))}
+              </ul>
+            ) : null}
+          </SectionCard>
+          <KeyValueList columns={2} items={[
+            { label: "Type", value: post.post_type },
+            { label: "Network", value: post.provider ?? "-" },
+            { label: "Account", value: post.account_ref ?? "-" },
+            { label: "Created", value: post.created_at ? formatInstant(post.created_at) : "-" },
+            { label: "Scheduled for", value: post.scheduled_at ? formatInstant(post.scheduled_at) : "-" },
+            { label: "Published", value: post.published_at ? formatInstant(post.published_at) : "-" },
+          ]} />
+          {post.failure_reason ? <p role="alert" className="text-sm text-error-foreground">{post.failure_reason}</p> : null}
+          {post.external_post_url ? <a className="text-sm underline" href={post.external_post_url} target="_blank" rel="noreferrer">View on the network</a> : null}
+        </div>
+      ),
+    },
+    ...(editable || post.status === "scheduled"
+      ? [{
+          id: "schedule",
+          label: "Schedule",
+          content: (
+            <SectionCard title="Schedule this post" description={`Pick a time in your zone (${zone}).`}>
+              <div className="flex flex-wrap items-center gap-2">
+                <Input type="datetime-local" aria-label="Publish at" value={when} onChange={(e) => setWhen(e.target.value)} className="w-56" />
+                {when && isFuture(when) ? (
+                  <AskButton ask={ask} label="Schedule" tier="external" title={`Schedule: "${preview}"`} confirmLabel="Schedule"
+                    description={`Publishes at ${formatInstant(localInputToIso(when))}.`}
+                    run={() => g8Post(`/social/posts/${postId}/schedule`, { scheduled_at: localInputToIso(when) })} onDone={() => { setWhen(""); changed(); }} />
+                ) : (
+                  <span className="text-xs text-muted-foreground">Choose a time at least a minute from now.</span>
+                )}
+              </div>
+            </SectionCard>
+          ),
+        }]
+      : []),
+  ];
+
+  return (
+    <>
+    <DetailPanel title={preview || "Post"} subtitle={post.provider ?? undefined} badges={<StatusPill tone={tone(post.status)}>{post.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/social-post-list.tsx

@@ -28,6 +28,10 @@ export interface SocialPostListProps {
   /** Change to reload the list, for example after PostComposer saved a post. */
   refreshKey?: number;
   pageSize?: number;
+  /** Called when a person opens a post (show a PostDetail). */
+  onSelectPost?: (post: SocialPost) => void;
+  /** Highlights the open post. */
+  selectedId?: string | null;
   className?: string;
 }
 
@@ -39,7 +43,7 @@ const COPY: Record<Pending["kind"], { tier: ConfirmTier; verb: string; text: str
   delete: { tier: "destructive", verb: "Delete", text: "The post is removed. A post that is already live stays live on the network." },
 };
 
-export function SocialPostList({ refreshKey = 0, pageSize = 20, className }: SocialPostListProps) {
+export function SocialPostList({ refreshKey = 0, pageSize = 20, onSelectPost, selectedId, className }: SocialPostListProps) {
   const [status, setStatus] = useState<(typeof STATUSES)[number]>("all");
   const [page, setPage] = useState(1);
   const [pending, setPending] = useState<Pending | null>(null);
@@ -87,9 +91,13 @@ export function SocialPostList({ refreshKey = 0, pageSize = 20, className }: Soc
       {!query.loading && !query.error && items.length === 0 ? <EmptyState title="No posts here" description="Write one with the composer." /> : null}
       <ul className="flex flex-col gap-2">
         {items.map((p) => (
-          <li key={p.id} className="flex flex-wrap items-start justify-between gap-2 rounded-md border p-3" data-testid="post">
+          <li key={p.id} className={`flex flex-wrap items-start justify-between gap-2 rounded-md border p-3 ${selectedId === p.id ? "bg-muted/50" : ""}`} data-testid="post">
             <div className="flex min-w-0 flex-1 flex-col gap-1">
-              <p className="line-clamp-3 text-sm">{p.body}</p>
+              {onSelectPost ? (
+                <button type="button" className="line-clamp-3 text-left text-sm hover:underline" onClick={() => onSelectPost(p)}>{p.body}</button>
+              ) : (
+                <p className="line-clamp-3 text-sm">{p.body}</p>
+              )}
               <p className="text-xs text-muted-foreground">
                 {p.status}
                 {p.status === "scheduled" && p.scheduled_at ? ` for ${formatInstant(p.scheduled_at)}` : ""}

package/blocks/social-ads/components/social-screen.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+/**
+ * SocialScreen: the finished social publishing page. Two tabs:
+ *   Posts     every post by status (SocialPostList): publish a draft, cancel a scheduled post, delete. "New post" opens the
+ *             composer in a side sheet (PostComposer): write or draft with AI, save, schedule or publish.
+ *   Accounts  the connected social accounts with their publishing capacity. Connecting an account (LinkedIn sign-in) only
+ *             works in the graph8 app, so this tab links out instead of offering a dead button.
+ *
+ * Every post opens a complete detail screen (PostDetail, `?id=`, full page with `?view=full`).
+ *
+ * SDK operations: one read of listSocialPosts (page_size 1) for the per-status counts in the stat strip. Composes
+ * PostComposer (billable AI drafts, external schedule/publish, all confirmed), SocialPostList (external + destructive,
+ * confirmed) and useSocialAccounts (read).
+ */
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { Megaphone, Plus } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { useSocialAccounts } from "../hooks/use-social-accounts";
+import type { SocialPostPage } from "../lib/social-ads-types";
+import { PostComposer } from "./post-composer";
+import { SocialPostList } from "./social-post-list";
+import { PostDetail } from "./post-detail";
+import { brandUrl, useBrand } from "@/g8/hooks/use-brand";
+
+export interface SocialScreenProps {
+  /** Where "Connect" sends people. Default: graph8 Settings > Integrations. */
+  connectUrl?: string;
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+/** Integrations settings on the platform's web app, resolved against the brand. */
+const APP_PATH = "/studio/settings?tab=integrations";
+
+function Accounts({ connectUrl }: { connectUrl: string }) {
+  const brand = useBrand();
+  const { accounts, loading, error, refetch } = useSocialAccounts();
+  if (error) return <ApiError error={error} onRetry={() => void refetch()} />;
+  if (loading && accounts.length === 0) return <p className="text-sm text-muted-foreground" role="status">Loading accounts...</p>;
+  if (accounts.length === 0) {
+    return (
+      <EmptyState
+        title="No social account connected"
+        description={`Sign in with LinkedIn in ${brand.linkLabel} to publish from here.`}
+        action={<Button asChild><a href={connectUrl} target="_blank" rel="noreferrer">Connect in {brand.linkLabel}</a></Button>}
+      />
+    );
+  }
+  return (
+    <ul className="grid gap-3 md:grid-cols-2">
+      {accounts.map((a) => (
+        <li key={a.id}>
+          <SectionCard title={a.display_name ?? a.provider} description={a.provider}>
+            <div className="flex items-center gap-3">
+              <EntityAvatar name={a.display_name ?? a.provider} kind="person" />
+              <div className="min-w-0 flex-1 text-sm">
+                <StatusPill tone={a.status === "active" || a.status === "connected" ? "positive" : "warning"}>{a.status ?? "unknown"}</StatusPill>
+                <p className="mt-1 text-xs text-muted-foreground tabular-nums">
+                  {a.capacity.publish_used} of {a.capacity.publish_limit} posts used
+                </p>
+              </div>
+              {a.profile_url ? <a className="text-sm underline" href={a.profile_url} target="_blank" rel="noreferrer">Profile</a> : null}
+            </div>
+          </SectionCard>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export function SocialScreen(props: SocialScreenProps) {
+  const brand = useBrand();
+  const connectUrl = props.connectUrl ?? brandUrl(brand, APP_PATH);
+  const [tabValue, setTab] = useUrlState("tab", "posts");
+  const tab = tabValue === "accounts" ? "accounts" : "posts";
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const expanded = view === "full" && Boolean(id);
+  const [composing, setComposing] = useState(false);
+  const [refreshKey, setRefreshKey] = useState(0);
+  const counts = useG8Query(async (signal) => (await g8Get<SocialPostPage>("/social/posts", { page: 1, page_size: 1 }, { signal })).data, [refreshKey]);
+
+  const c = counts.data?.counts ?? {};
+  const stats: StatItem[] | undefined = counts.data
+    ? [
+        { label: "Live", value: c.live ?? 0, tone: "positive" },
+        { label: "Scheduled", value: c.scheduled ?? 0, tone: "info" },
+        { label: "Drafts", value: c.draft ?? 0 },
+        { label: "Failed", value: c.failed ?? 0, tone: c.failed ? "negative" : "neutral" },
+      ]
+    : undefined;
+
+  return (
+    <ScreenLayout
+      title="Social"
+      description="Write, schedule and publish posts, and see what is live."
+      icon={<Megaphone className="size-5" />}
+      actions={
+        <>
+          {props.toolbarActions}
+          <Button onClick={() => setComposing(true)}>
+            <Plus className="mr-1.5 size-4" /> New post
+          </Button>
+        </>
+      }
+      tabs={[
+        { id: "posts", label: "Posts" },
+        { id: "accounts", label: "Accounts" },
+      ]}
+      activeTab={tab}
+      onTabChange={(next) => {
+        setTab(next);
+        setId("");
+        setView("");
+      }}
+      stats={tab === "posts" ? stats : undefined}
+      className={props.className}
+    >
+      {tab === "posts" ? (
+        <SplitView
+          detailOpen={Boolean(id)}
+          onCloseDetail={() => { setId(""); setView(""); }}
+          expanded={expanded}
+          onExpandedChange={(next) => setView(next ? "full" : "")}
+          detailWidth="lg"
+          list={<SocialPostList refreshKey={refreshKey} selectedId={id} onSelectPost={(p) => setId(p.id)} />}
+          detail={id ? (
+            <PostDetail key={id} postId={id} onClose={() => { setId(""); setView(""); }}
+              onExpand={expanded ? undefined : () => setView("full")} onCollapse={expanded ? () => setView("") : undefined}
+              onChanged={() => setRefreshKey((k) => k + 1)} />
+          ) : null}
+        />
+      ) : (
+        <Accounts connectUrl={connectUrl} />
+      )}
+      <FormSheet open={composing} onOpenChange={setComposing} title="New post" description="Write it, draft it with AI, then save, schedule or publish.">
+        <PostComposer
+          onSaved={() => {
+            setComposing(false);
+            setRefreshKey((k) => k + 1);
+          }}
+        />
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

package/blocks/visitors/README.md

@@ -5,6 +5,16 @@ and chart traffic. The Apollo / 6sense "website visitors" screen.
 
 Depends on: `crm`. Install: `npx @graph8/sdk add visitors`.
 
+## Screens
+
+`VisitorsScreen` (`components/visitors-screen.tsx`) is the finished page: copy it as your route. No props are required.
+
+- **Visitors tab**: bots/internal-traffic toggles, 7-day stat strip (visitors, sessions, page views with sparklines), the polled company/people feed, and a detail
+  panel for a clicked person with the pages they viewed. Company cards expand to the full journey.
+- **Traffic tab**: 7/30/90 day window, trend chart, top pages, "on the site now". **Install tab**: the snippet and an install check.
+- Slots: `toolbarActions`, `renderDetailActions(visit, kind)`, `extraDetailTabs` (each `{ id, label, render(visit, kind) }`; shown once the visitor row is known). Everything is read tier.
+- Prerequisite: the snippet pasted into your site (only a person can do this); People also needs `contacts:read`.
+
 ## Components
 
 | Component | What it does | Tiers |

package/blocks/visitors/block.json

@@ -71,6 +71,29 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "VisitorsScreen",
+      "file": "components/visitors-screen.tsx",
+      "purpose": "Finished website-visitors page: week stat strip, company and people feed with person detail, traffic charts and the snippet install check.",
+      "operations": [
+        "get_audience_trend_analytics_audience_trend_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "VisitorDetail",
+      "file": "components/visitor-detail.tsx",
+      "purpose": "Complete screen for one visiting company or identified person: fields, pages viewed, full journey.",
+      "operations": [
+        "list_company_visitor_events_visitors_companies_events_get",
+        "list_contact_visitor_events_visitors_contacts_events_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [],
@@ -134,6 +157,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400"
   }
 }