@graph8/sdk 0.370.0 → 0.374.0

package/blocks/email-signatures/block.json

@@ -0,0 +1,341 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "email-signatures",
+  "title": "Email signatures",
+  "summary": "Design one signature for the team and keep every mailbox on it: templates with a live preview, assignment to mailboxes and employees, the organisation default, banner campaigns, policy and engagement.",
+  "features": [
+    "signature templates built from blocks and placeholders, with a safe live preview as a sample or as a real employee",
+    "apply a template to chosen mailboxes, a department or everyone, confirmed with the real number of mailboxes",
+    "make a template the organisation default or archive it, both confirmed",
+    "assign an employee to a mailbox (setup check first), push, restore the old signature and change a mailbox's source",
+    "banner campaigns for a time window with targeting, a preview and a who-would-see-it test",
+    "policy: off, managed or enforced, default and department templates, employee overrides, cold-send variant",
+    "impressions and clicks by mailbox and campaign, with the limits of the numbers"
+  ],
+  "dependsOn": [
+    "mailboxes"
+  ],
+  "operations": [
+    "archive_signature_template_signatures_templates__template_id__delete",
+    "assign_signature_identity_signatures_assignments_post",
+    "assign_signature_template_signatures_templates__template_id__assign_post",
+    "change_signature_source_signatures_mailboxes__mailbox_id__source_post",
+    "create_signature_campaign_signatures_campaigns_post",
+    "create_signature_template_signatures_templates_post",
+    "get_signature_report_signatures_reports_get",
+    "get_signature_settings_signatures_settings_get",
+    "get_signature_template_signatures_templates__template_id__get",
+    "list_mailboxes_mailboxes_get",
+    "list_signature_campaigns_signatures_campaigns_get",
+    "list_signature_deployments_signatures_mailboxes_get",
+    "list_signature_members_signatures_members_get",
+    "list_signature_templates_signatures_templates_get",
+    "preview_saved_signature_template_signatures_templates__template_id__preview_post",
+    "preview_signature_campaign_signatures_campaigns_preview_post",
+    "preview_signature_setup_signatures_setup_preview_post",
+    "preview_signature_template_signatures_preview_post",
+    "push_signature_signatures_mailboxes__mailbox_id__push_post",
+    "push_signatures_signatures_mailboxes_push_post",
+    "restore_signature_signatures_mailboxes__mailbox_id__restore_post",
+    "set_default_signature_template_signatures_templates__template_id__set_default_post",
+    "update_signature_campaign_signatures_campaigns__campaign_id__patch",
+    "update_signature_settings_signatures_settings_put",
+    "update_signature_template_signatures_templates__template_id__patch"
+  ],
+  "components": [
+    {
+      "name": "EmailSignaturesScreen",
+      "file": "components/email-signatures-screen.tsx",
+      "purpose": "Finished email-signatures workspace: templates with a live preview, apply to mailboxes, the organisation default, mailboxes with push, restore and source, banner campaigns, the policy and the engagement report.",
+      "operations": [
+        "get_signature_settings_signatures_settings_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_templates_signatures_templates_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SignatureTemplateForm",
+      "file": "components/signature-template-form.tsx",
+      "purpose": "Create or edit a signature template (layout, font, colour, blocks, placeholders) with a live preview; edit reads the full record first and a stale save is refused.",
+      "operations": [
+        "create_signature_template_signatures_templates_post",
+        "get_signature_template_signatures_templates__template_id__get",
+        "update_signature_template_signatures_templates__template_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureBlockEditor",
+      "file": "components/signature-block-editor.tsx",
+      "purpose": "The ordered block list of a template: type, text, link, image, locked, required, placeholders, reorder and remove. A pure control that calls no operation.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "TemplatePreview",
+      "file": "components/signature-preview.tsx",
+      "purpose": "Render a draft or a stored template as a sample or as a real employee on a real mailbox, in full, compact or campaign form, or as plain text; the HTML is shown in a sandboxed frame (also exports SafeSignatureFrame).",
+      "operations": [
+        "list_mailboxes_mailboxes_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "preview_saved_signature_template_signatures_templates__template_id__preview_post",
+        "preview_signature_template_signatures_preview_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureAssignTemplate",
+      "file": "components/signature-assign-template.tsx",
+      "purpose": "Apply a template to chosen mailboxes, a department or every mailbox; confirmed with the number of mailboxes it really covers.",
+      "operations": [
+        "assign_signature_template_signatures_templates__template_id__assign_post",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureTemplateDetails",
+      "file": "components/signature-template-details.tsx",
+      "purpose": "One template's facts, make it the organisation default (confirmed, sized from the mailboxes that follow it) and archive it (confirmed; disabled while it is in use).",
+      "operations": [
+        "archive_signature_template_signatures_templates__template_id__delete",
+        "get_signature_settings_signatures_settings_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "set_default_signature_template_signatures_templates__template_id__set_default_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SignatureMailboxes",
+      "file": "components/signature-mailboxes.tsx",
+      "purpose": "Every mailbox with its employee, template source and status; assign an employee, push (one or many), restore the old signature and change what a mailbox sends, each confirmed.",
+      "operations": [
+        "change_signature_source_signatures_mailboxes__mailbox_id__source_post",
+        "get_signature_settings_signatures_settings_get",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "list_signature_templates_signatures_templates_get",
+        "push_signature_signatures_mailboxes__mailbox_id__push_post",
+        "push_signatures_signatures_mailboxes_push_post",
+        "restore_signature_signatures_mailboxes__mailbox_id__restore_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureIdentityForm",
+      "file": "components/signature-identity-form.tsx",
+      "purpose": "Bind one mailbox to an employee: account and send-as derived from the choices, a dry-run setup check, then a confirmed takeover.",
+      "operations": [
+        "assign_signature_identity_signatures_assignments_post",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "list_signature_templates_signatures_templates_get",
+        "preview_signature_setup_signatures_setup_preview_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignaturePolicy",
+      "file": "components/signature-policy.tsx",
+      "purpose": "The organisation policy: off, managed or enforced, default and department templates, employee overrides, cold-send variant and native installation; a confirmed save of the changed fields.",
+      "operations": [
+        "get_signature_settings_signatures_settings_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "list_signature_templates_signatures_templates_get",
+        "update_signature_settings_signatures_settings_put"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureCampaigns",
+      "file": "components/signature-campaigns.tsx",
+      "purpose": "Banner campaigns with status, dates and priority; create and edit in a sheet.",
+      "operations": [
+        "list_signature_campaigns_signatures_campaigns_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SignatureCampaignForm",
+      "file": "components/signature-campaign-form.tsx",
+      "purpose": "Create or edit a banner campaign (banner, dates, status, priority, who sees it), preview the banner and test which mailbox and recipients it would reach.",
+      "operations": [
+        "create_signature_campaign_signatures_campaigns_post",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "preview_signature_campaign_signatures_campaigns_preview_post",
+        "update_signature_campaign_signatures_campaigns__campaign_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureReport",
+      "file": "components/signature-report.tsx",
+      "purpose": "Impressions and clicks by mailbox and campaign, with the limits the API states about the numbers.",
+      "operations": [
+        "get_signature_report_signatures_reports_get",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_campaigns_signatures_campaigns_get",
+        "list_signature_deployments_signatures_mailboxes_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useSignaturesData",
+      "file": "hooks/use-signatures-data.ts",
+      "purpose": "Shared cached reads: templates, one template, members, mailbox deployments, the policy, campaigns, and mailboxes merged with their deployments (the mailbox list is read once at the API's limit of 500 and says when it may be longer).",
+      "operations": [
+        "get_signature_settings_signatures_settings_get",
+        "get_signature_template_signatures_templates__template_id__get",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_campaigns_signatures_campaigns_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "list_signature_templates_signatures_templates_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/signatures-types.ts",
+      "purpose": "Template, policy, deployment and campaign types; the API's exact vocabularies (block kinds, layouts, fonts, modes, statuses, sources); the placeholder list; template rules checked before a save; local-time helpers for campaign dates."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-a-template-and-make-it-default.ts",
+      "title": "Create a signature template and make it the organisation default",
+      "when": "First-time setup; making it the default changes what mailboxes send, so a person confirms."
+    },
+    {
+      "file": "recipes/assign-a-signature-to-a-new-hire.ts",
+      "title": "Give a new hire's mailbox a managed signature",
+      "when": "Onboarding; a takeover of the mailbox's signature that a person agrees to."
+    },
+    {
+      "file": "recipes/signature-engagement-report.ts",
+      "title": "Report signature impressions and clicks",
+      "when": "A weekly digest or a dashboard backend."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "mailboxes",
+      "description": "Mailboxes connected in the app (Google or Microsoft) or added through the mailboxes block. A signature is bound to a mailbox.",
+      "where": "api",
+      "verify": "GET /api/v1/mailboxes lists the mailbox."
+    },
+    {
+      "id": "directory-employees",
+      "description": "The people who sign must be team members with an email address in the directory. An employee without an email cannot be assigned.",
+      "where": "api",
+      "verify": "GET /api/v1/signatures/members lists them."
+    },
+    {
+      "id": "workspace-signature-access",
+      "description": "Installing a signature inside a Google account needs the Google Workspace integration with the signature permission granted by a Workspace admin in the app. A deployment that stops at needs_admin_grant is missing it. Without native installation the signature is applied when mail is sent from the platform.",
+      "where": "app",
+      "verify": "A deployment reaches an installed status instead of needs_admin_grant."
+    },
+    {
+      "id": "signature-scopes",
+      "description": "The key needs signatures:read, signatures:write and signatures:delete (archive). Listing mailboxes needs campaigns:read.",
+      "where": "api",
+      "verify": "g8.api.me.describeCurrentKey() lists the scopes."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"signatures\" and \"mailboxes\" to allowedPrefixes in app/api/g8/[...path]/route.ts.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains them."
+    }
+  ],
+  "scopes": [
+    "campaigns:read",
+    "signatures:delete",
+    "signatures:read",
+    "signatures:write"
+  ],
+  "defaults": [
+    {
+      "decision": "New template",
+      "default": "Classic stacked layout, Arial, text colour #222222, brand kit colour and font, one required locked identity block with the employee's name and title",
+      "askHuman": false
+    },
+    {
+      "decision": "Which mailboxes get a template",
+      "default": "None: a person always chooses the mailboxes, a department or everyone, and confirms the count",
+      "askHuman": true
+    },
+    {
+      "decision": "Policy mode",
+      "default": "Leave it as it is; turning management on needs a default template, enforcing needs every active mailbox assigned",
+      "askHuman": true
+    },
+    {
+      "decision": "Assigning an employee to a mailbox",
+      "default": "Account = the employee's directory email, send-as = the mailbox address; only after a person agrees to the takeover",
+      "askHuman": true
+    },
+    {
+      "decision": "Stopping a campaign",
+      "default": "Set it to Paused (the API cannot delete a campaign)",
+      "askHuman": false
+    },
+    {
+      "decision": "Removing a template",
+      "default": "Archive it, after giving its mailboxes another template",
+      "askHuman": false
+    },
+    {
+      "decision": "After editing a template",
+      "default": "Push the mailboxes that use it from the Mailboxes tab",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}

package/blocks/email-signatures/components/email-signatures-screen.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+/**
+ * EmailSignaturesScreen: the finished workspace for managed email signatures. No props needed.
+ *
+ * Composes: ScreenLayout (title, tabs, stats), Toolbar (search), SplitView + DetailPanel (the selected template, deep link
+ * `?id=`), FormSheet (new template via SignatureTemplateForm), TemplatePreview, SignatureAssignTemplate,
+ * SignatureTemplateDetails, SignatureMailboxes, SignatureCampaigns, SignaturePolicy and SignatureReport.
+ *
+ * Tabs (`?tab=`): Templates (list and detail), Mailboxes, Campaigns, Policy, Report. A template's detail (`?id=`) has Preview,
+ * Edit, Use on mailboxes and Details; `&view=full` shows it as a full page.
+ *
+ * User flows: see every template (search; the list is complete because the API does not page it); create one with blocks,
+ * placeholders and a live preview; open it and preview it as a real employee on a real mailbox, in full, compact or campaign
+ * form, or as plain text; edit it (sends only after the full record has loaded; a stale save is refused and explained);
+ * apply it to chosen mailboxes, a department or everyone (confirmed with the real number of mailboxes); make it the
+ * organisation default or archive it (both confirmed). On the Mailboxes tab: assign an employee to a mailbox (check the setup
+ * first), push, restore the old signature and change what a mailbox sends, one by one or in bulk, each confirmed. Campaigns
+ * add a banner for a time window and can be previewed and tested against a mailbox and recipients. The Policy tab turns
+ * management off, on or enforced, sets the default and department templates. The Report tab reads impressions and clicks.
+ * The API has no variables list, template delete (only archive), campaign delete, asset upload or employee self-service
+ * (see the README for the gaps).
+ *
+ * SDK operations: none directly. Every call lives in the composed parts, which confirm every change to what a mailbox sends.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { PenLine, Plus } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+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 { useUrlState } from "@/g8/hooks/use-url-state";
+import { plural } from "@/g8/lib/plural";
+import { useSignatureDeployments, useSignaturePolicy, useSignatureTemplates } from "../hooks/use-signatures-data";
+import { LAYOUTS, POLICY_MODES, isManaged, templateName } from "../lib/signatures-types";
+import type { SignatureTemplate } from "../lib/signatures-types";
+import { SignatureAssignTemplate } from "./signature-assign-template";
+import { SignatureCampaigns } from "./signature-campaigns";
+import { SignatureMailboxes } from "./signature-mailboxes";
+import { SignaturePolicy } from "./signature-policy";
+import { SignatureReport } from "./signature-report";
+import { SignatureTemplateDetails } from "./signature-template-details";
+import { SignatureTemplateForm } from "./signature-template-form";
+import { TemplatePreview } from "./signature-preview";
+
+export interface EmailSignaturesScreenProps {
+  renderRowActions?: (template: SignatureTemplate) => ReactNode;
+  renderDetailActions?: (template: SignatureTemplate) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (template: SignatureTemplate) => ReactNode }[];
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+type Tab = "templates" | "mailboxes" | "campaigns" | "policy" | "report";
+const TABS: Tab[] = ["templates", "mailboxes", "campaigns", "policy", "report"];
+
+export function EmailSignaturesScreen({ renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, className }: EmailSignaturesScreenProps) {
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const [tabParam, setTabParam] = useUrlState("tab", "templates");
+  const tab = (TABS.includes(tabParam as Tab) ? tabParam : "templates") as Tab;
+  const [search, setSearch] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [savedVersion, setSavedVersion] = useState<{ id: string; version: number } | null>(null);
+  const list = useSignatureTemplates();
+  const deployments = useSignatureDeployments();
+  const policy = useSignaturePolicy();
+
+  const all = list.data ?? [];
+  const q = search.trim().toLowerCase();
+  const shown = all.filter((t) => !q || templateName(t).toLowerCase().includes(q));
+  const selected = all.find((t) => t.id === id);
+  const defaultId = policy.data?.data.default_template_id;
+  const closeDetail = (): void => { setId(null); setView(null); };
+  const rows = deployments.data ?? [];
+
+  const listBody = list.error && !list.data ? <ApiError error={list.error} title="Could not load templates" onRetry={() => void list.refetch()} /> : !list.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<PenLine className="size-8" />} title={all.length === 0 ? "No signature templates yet" : "No templates match"} description={all.length === 0 ? "A template is the shared design of your team's email signatures. Create one, then assign it to mailboxes." : "Try another search."} action={all.length === 0 ? <Button onClick={() => setCreating(true)}>Create your first template</Button> : undefined} />
+  ) : (
+    <>
+      <p role="status" className="text-muted-foreground mb-2 text-xs">{shown.length === all.length ? `All ${plural(all.length, "template")}` : `${shown.length.toLocaleString()} of ${plural(all.length, "template")}`}</p>
+      <ul className="grid gap-2">
+        {shown.map((t) => (
+          <li key={t.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${t.id === id ? "bg-muted" : ""}`}>
+            <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setId(t.id)}>
+              <span className="block truncate font-medium">{templateName(t)}</span>
+              <span className="text-muted-foreground block truncate text-xs">{LAYOUTS.find((l) => l.value === t.data?.layout)?.label ?? "Layout unknown"} · {plural((t.data?.blocks ?? []).length, "block")} · version {t.version}</span>
+            </button>
+            {t.id === defaultId ? <StatusPill tone="positive">Default</StatusPill> : null}
+            {renderRowActions?.(t)}
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+
+  const detail = selected ? (
+    <DetailPanel
+      title={templateName(selected)}
+      subtitle={LAYOUTS.find((l) => l.value === selected.data?.layout)?.label}
+      badges={selected.id === defaultId ? <StatusPill tone="positive">Organisation default</StatusPill> : undefined}
+      actions={renderDetailActions?.(selected)}
+      onClose={closeDetail}
+      onExpand={() => setView("full")}
+      onCollapse={view === "full" ? () => setView(null) : undefined}
+      tabs={[
+        { id: "preview", label: "Preview", content: <TemplatePreview key={`${selected.id}:${selected.version}`} templateId={selected.id} /> },
+        { id: "edit", label: "Edit", content: (
+          <div className="grid gap-3">
+            {savedVersion?.id === selected.id && savedVersion.version === selected.version ? <p role="status" className="text-sm">Template saved as version {selected.version}. To install it again on the mailboxes that use it, push them from the Mailboxes tab.</p> : null}
+            <SignatureTemplateForm key={selected.id} template={selected} onSaved={(saved) => setSavedVersion({ id: saved.id, version: saved.version })} />
+          </div>
+        ) },
+        { id: "use", label: "Use on mailboxes", content: <SignatureAssignTemplate key={selected.id} template={selected} /> },
+        { id: "details", label: "Details", content: <SignatureTemplateDetails template={selected} onArchived={closeDetail} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })),
+      ]}
+    />
+  ) : null;
+
+  const templatesTab = (
+    <SplitView
+      list={<div className="grid gap-3"><Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search templates" }} actions={toolbarActions} />{listBody}</div>}
+      detail={detail}
+      detailOpen={Boolean(selected)}
+      onCloseDetail={closeDetail}
+      expanded={view === "full"}
+      onExpandedChange={(e) => setView(e ? "full" : null)}
+      detailWidth="xl"
+    />
+  );
+
+  const mode = POLICY_MODES.find((m) => m.value === policy.data?.data.mode)?.label;
+  return (
+    <ScreenLayout
+      className={className}
+      title="Email signatures"
+      description="Design one signature for the team and keep every mailbox on it."
+      icon={<PenLine className="size-5" />}
+      actions={<Button size="sm" onClick={() => { setTabParam(null); setCreating(true); }}><Plus className="size-4" />New template</Button>}
+      tabs={[{ id: "templates", label: "Templates", count: list.data ? all.length : undefined }, { id: "mailboxes", label: "Mailboxes" }, { id: "campaigns", label: "Campaigns" }, { id: "policy", label: "Policy" }, { id: "report", label: "Report" }]}
+      activeTab={tab}
+      onTabChange={(next) => { setTabParam(next === "templates" ? null : next); closeDetail(); }}
+      stats={tab === "templates" ? [
+        { label: "Templates", value: list.data ? all.length.toLocaleString() : "..." },
+        { label: "Managed mailboxes", value: deployments.data ? rows.filter((d) => isManaged(d)).length.toLocaleString() : "..." },
+        { label: "Need attention", value: deployments.data ? rows.filter((d) => d.alert).length.toLocaleString() : "...", tone: rows.some((d) => d.alert) ? "negative" : undefined },
+        { label: "Management", value: mode ?? (policy.data ? "Not set" : policy.error ? "Unavailable" : "...") },
+      ] : undefined}
+    >
+      {tab === "templates" ? templatesTab : tab === "mailboxes" ? <SignatureMailboxes /> : tab === "campaigns" ? <SignatureCampaigns /> : tab === "policy" ? <SignaturePolicy /> : <SignatureReport />}
+      <FormSheet open={creating} onOpenChange={setCreating} width="xl" title="New signature template" description="Design the signature once. Nothing reaches a mailbox until you apply it.">
+        {creating ? <SignatureTemplateForm onCancel={() => setCreating(false)} onSaved={(created) => { setCreating(false); setId(created.id); }} /> : null}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

package/blocks/email-signatures/components/signature-assign-template.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * SignatureAssignTemplate: point mailboxes at a template. Choose the mailboxes one by one, every mailbox of a department, or
+ * every mailbox; the API then queues a re-install on each.
+ *
+ * SDK operations, in order (the mailbox, member and deployment reads come from the shared hooks):
+ *   1. assignSignatureTemplate (POST /signatures/templates/{template_id}/assign)   write   replaces the signature the chosen mailboxes SEND:
+ *      ConfirmSpendDialog (external) first, sized from the mailboxes the choice really covers.
+ * Targets are exclusive (mailbox ids, a department, or all mailboxes) and every target must already have an employee
+ * assigned (Mailboxes tab); the API refuses the whole call otherwise, so those mailboxes are shown disabled with the reason.
+ * "All mailboxes" is only offered when every active mailbox is assigned and the list is complete. The result says how many
+ * mailboxes were queued; progress then shows in the Mailboxes tab.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { MAILBOX_LIMIT, useSignatureMailboxes, useSignatureMembers } from "../hooks/use-signatures-data";
+import { isManaged, templateName } from "../lib/signatures-types";
+import type { SignatureTemplate } from "../lib/signatures-types";
+
+export interface SignatureAssignTemplateProps {
+  template: SignatureTemplate;
+  onAssigned?: (count: number) => void;
+}
+
+type Mode = "mailboxes" | "department" | "all";
+interface Result { count: number }
+
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+export function SignatureAssignTemplate({ template, onAssigned }: SignatureAssignTemplateProps) {
+  const box = useSignatureMailboxes();
+  const members = useSignatureMembers();
+  const [mode, setMode] = useState<Mode>("mailboxes");
+  const [picked, setPicked] = useState<number[]>([]);
+  const [department, setDepartment] = useState("");
+  const [confirm, setConfirm] = useState(false);
+  const [done, setDone] = useState<Result | null>(null);
+
+  const assigned = box.mailboxes.filter((m) => isManaged(m.deployment));
+  const unassigned = box.mailboxes.filter((m) => !isManaged(m.deployment));
+  const deptOf = (memberId: string | undefined): string | null => members.data?.find((x) => x.id === memberId)?.department ?? null;
+  const departments = [...new Set(assigned.map((m) => deptOf(m.deployment?.assignment?.member_id)).filter((d): d is string => Boolean(d)))].sort();
+  const inDepartment = assigned.filter((m) => deptOf(m.deployment?.assignment?.member_id) === department);
+  const allowAll = unassigned.length === 0 && !box.truncated && !box.mailboxesError && box.mailboxes.length > 0;
+  const covered = mode === "mailboxes" ? picked.filter((id) => assigned.some((m) => m.id === id)).length : mode === "department" ? inDepartment.length : box.mailboxes.length;
+  const ready = covered > 0 && (mode !== "department" || department !== "") && (mode !== "all" || allowAll);
+
+  const apply = useG8Mutation(async (): Promise<Result> => {
+    const body = mode === "mailboxes" ? { mailbox_ids: picked.filter((id) => assigned.some((m) => m.id === id)) } : mode === "department" ? { department } : { all_mailboxes: true };
+    return (await g8Post<Result>(`/signatures/templates/${encodeURIComponent(template.id)}/assign`, body)).data;
+  }, {
+    onSuccess: (r) => { setConfirm(false); setDone(r); setPicked([]); onAssigned?.(r.count); },
+    onError: () => setConfirm(false),
+    invalidates: [["signatures", "deployments"]],
+  });
+
+  if (box.loading) return <p className="text-muted-foreground text-sm" aria-busy="true">Loading mailboxes</p>;
+  if (box.error) return <ApiError error={box.error} title="Could not load mailboxes" onRetry={box.refetch} />;
+
+  return (
+    <div className="grid gap-3">
+      <p className="text-muted-foreground text-sm">Choose which mailboxes send {templateName(template)}. Each mailbox keeps its employee; only the template changes.</p>
+      <fieldset className="grid gap-1 text-sm">
+        <legend className="mb-1 font-medium">Apply to</legend>
+        <label className="flex items-center gap-2"><input type="radio" name="g8-sig-target" checked={mode === "mailboxes"} onChange={() => setMode("mailboxes")} />Chosen mailboxes</label>
+        <label className="flex items-center gap-2"><input type="radio" name="g8-sig-target" checked={mode === "department"} onChange={() => setMode("department")} />Every mailbox in a department</label>
+        <label className="flex items-center gap-2"><input type="radio" name="g8-sig-target" checked={mode === "all"} disabled={!allowAll} onChange={() => setMode("all")} />Every mailbox{allowAll ? "" : unassigned.length > 0 ? ` (${plural(unassigned.length, "mailbox")} still without an employee)` : " (the full list could not be confirmed)"}</label>
+      </fieldset>
+      {box.mailboxesError ? <ApiError compact error={box.mailboxesError} title="Mailboxes without a signature are not listed" onRetry={box.refetch} /> : null}
+      {mode === "mailboxes" ? (
+        <ul className="grid gap-1" aria-label="Mailboxes">
+          {box.mailboxes.map((m) => {
+            const ok = isManaged(m.deployment);
+            return (
+              <li key={m.id} className="flex items-center gap-2 text-sm">
+                <input type="checkbox" id={`g8-sig-mb-${m.id}`} disabled={!ok} checked={picked.includes(m.id)} onChange={(e) => setPicked(e.target.checked ? [...picked, m.id] : picked.filter((id) => id !== m.id))} />
+                <label htmlFor={`g8-sig-mb-${m.id}`}>{m.email}</label>
+                {!ok ? <StatusPill tone="neutral">No employee assigned</StatusPill> : null}
+              </li>
+            );
+          })}
+        </ul>
+      ) : null}
+      {mode === "department" ? (
+        <div className="grid gap-1">
+          <select aria-label="Department" className={SELECT} value={department} onChange={(e) => setDepartment(e.target.value)}>
+            <option value="">Choose a department</option>
+            {departments.map((d) => <option key={d} value={d}>{d}</option>)}
+          </select>
+          {departments.length === 0 ? <p className="text-muted-foreground text-xs">No assigned employee has a department yet.</p> : null}
+        </div>
+      ) : null}
+      <FirstNotice shown={box.mailboxes.length} limit={MAILBOX_LIMIT} noun="mailboxes" force={box.truncated} />
+      {apply.error ? <ApiError error={apply.error} title="Could not apply the template" /> : null}
+      {done ? <p role="status" className="text-sm">Queued {plural(done.count, "mailbox")} to install {templateName(template)}. Follow progress in the Mailboxes tab.</p> : null}
+      <div><Button type="button" disabled={!ready} onClick={() => setConfirm(true)}>Apply to {plural(covered, "mailbox")}</Button></div>
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="external"
+        title={`Apply ${templateName(template)} to ${plural(covered, "mailbox")}?`}
+        affected={covered}
+        description="These mailboxes will send this signature on new emails. Emails already sent do not change. A mailbox can be given its old signature back from the Mailboxes tab unless the policy is enforced."
+        confirmLabel="Apply template"
+        confirming={apply.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void apply.mutate(undefined)}
+      />
+    </div>
+  );
+}