@graph8/sdk 0.370.0 → 0.374.0

package/blocks/crm/block.json

@@ -10,7 +10,12 @@
     "CSV/Excel import wizard with column mapping and preview",
     "duplicate review with merge, bulk merge and undo",
     "locked (masked) emails and phones shown as Locked, never as values",
-    "finished ContactsScreen, CompaniesScreen and TasksScreen (list, detail, create, edit, delete, import, duplicates)"
+    "finished ContactsScreen, CompaniesScreen and TasksScreen (list, detail, create, edit, delete, import, duplicates)",
+    "assign owner to all contacts of a list with an injected team-member picker (never for a selection), confirmed with the list and N",
+    "contact tags: chips on the contact, add or remove on a selection, and a tag manager (create, rename, recolour, archive, delete, merge)",
+    "bulk edit of one field on a selection",
+    "verify emails and unlock locked contacts, each confirmed with the real count and cost",
+    "AI documents, signals and an on-demand next best step on the open contact"
   ],
   "dependsOn": [
     "foundation"
@@ -20,9 +25,13 @@
     "assert_company_companies_assert_put",
     "assert_contact_contacts_assert_put",
     "assert_contacts_batch_contacts_assert_batch_put",
+    "assign_contact_owner_contacts_assign_owner_post",
+    "assign_contact_tags_contacts_tags_assign_post",
+    "bulk_update_contacts_contacts_bulk_update_post",
     "create_company_companies_post",
     "create_company_note_companies__company_id__notes_post",
     "create_company_task_companies__company_id__tasks_post",
+    "create_contact_tag_contacts_tags_post",
     "create_contacts_contacts_post",
     "create_field_fields_post",
     "create_global_task_tasks_post",
@@ -31,13 +40,25 @@
     "create_task_contacts__contact_id__tasks_post",
     "delete_company_companies__company_id__delete",
     "delete_contact_contacts__contact_id__delete",
+    "delete_contact_tag_contacts_tags__tag_id__delete",
     "delete_note_notes__note_id__delete",
     "delete_task_tasks__task_id__delete",
     "duplicate_counts_duplicates_counts_get",
+    "generate_all_contact_documents_contacts__contact_id__documents_generate_all_post",
+    "generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post",
     "get_activity_feed_activity_feed_get",
     "get_bulk_merge_status_duplicates_bulk_merge__run_id__get",
     "get_company_companies__company_id__get",
+    "get_company_engagement_summary_companies__company_id__engagement_summary_get",
+    "get_company_sites_visited_companies__company_id__sites_visited_get",
     "get_contact_contacts__contact_id__get",
+    "get_contact_document_contacts__contact_id__documents_types__doc_type__get",
+    "get_contact_engagement_summary_contacts__contact_id__engagement_summary_get",
+    "get_contact_generation_status_contacts__contact_id__documents_generation_status_get",
+    "get_contact_next_best_step_contacts__contact_id__next_best_step_get",
+    "get_contact_signals_contacts__contact_id__signals_get",
+    "get_contact_sites_visited_contacts__contact_id__sites_visited_get",
+    "get_contact_tag_ids_contacts__contact_id__tags_get",
     "get_task_tasks__task_id__get",
     "import_contacts_imports__import_id__contacts_post",
     "list_all_tasks_tasks_get",
@@ -46,6 +67,7 @@
     "list_company_notes_companies__company_id__notes_get",
     "list_company_tasks_companies__company_id__tasks_get",
     "list_contact_fields_fields_get",
+    "list_contact_tags_contacts_tags_get",
     "list_contact_tasks_contacts__contact_id__tasks_get",
     "list_contacts_contacts_get",
     "list_duplicates_duplicates_get",
@@ -54,16 +76,22 @@
     "list_recent_merges_duplicates_recent_merges_get",
     "merge_company_companies__company_id__merge_post",
     "merge_contact_contacts__contact_id__merge_post",
+    "merge_contact_tags_contacts_tags_merge_post",
     "preview_import_file_imports__import_id__preview_post",
+    "regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post",
     "reject_suggestion_duplicates__suggestion_id__reject_post",
     "set_field_values_batch_fields_values_batch_patch",
     "start_bulk_merge_duplicates_bulk_merge_post",
+    "unassign_contact_tags_contacts_tags_unassign_post",
     "undo_merge_duplicates_undo_merge__merge_history_id__post",
+    "unlock_contact_info_contacts_unlock_info_post",
     "update_company_companies__company_id__patch",
     "update_contact_contacts__contact_id__patch",
+    "update_contact_tag_contacts_tags__tag_id__patch",
     "update_note_notes__note_id__patch",
     "update_task_tasks__task_id__patch",
-    "upload_import_file_imports_post"
+    "upload_import_file_imports_post",
+    "verify_contact_emails_contacts_verify_email_post"
   ],
   "components": [
     {
@@ -264,15 +292,36 @@
     {
       "name": "ContactsScreen",
       "file": "components/contacts-screen.tsx",
-      "purpose": "Finished contacts workspace: search, filters, sort, paging, bulk delete, detail panel with activity/notes/tasks, create, edit, CSV import and duplicate review. No required props; slot props for other blocks.",
+      "purpose": "Finished contacts workspace: search, filters, sort, paging, owner column, bulk delete, detail panel with activity/notes/tasks/AI documents/insights, create, edit, CSV import and duplicate review, plus record actions: assign owner to a whole list (with an injected picker), tags (chips, bulk, manager), bulk edit, verify email and unlock info. No required props; slot props for other blocks.",
       "operations": [
+        "assign_contact_owner_contacts_assign_owner_post",
+        "assign_contact_tags_contacts_tags_assign_post",
+        "bulk_update_contacts_contacts_bulk_update_post",
+        "create_contact_tag_contacts_tags_post",
         "delete_contact_contacts__contact_id__delete",
+        "delete_contact_tag_contacts_tags__tag_id__delete",
         "duplicate_counts_duplicates_counts_get",
+        "generate_all_contact_documents_contacts__contact_id__documents_generate_all_post",
+        "generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post",
         "get_contact_contacts__contact_id__get",
-        "list_contacts_contacts_get"
+        "get_contact_document_contacts__contact_id__documents_types__doc_type__get",
+        "get_contact_generation_status_contacts__contact_id__documents_generation_status_get",
+        "get_contact_next_best_step_contacts__contact_id__next_best_step_get",
+        "get_contact_signals_contacts__contact_id__signals_get",
+        "get_contact_tag_ids_contacts__contact_id__tags_get",
+        "list_contact_tags_contacts_tags_get",
+        "list_contacts_contacts_get",
+        "merge_contact_tags_contacts_tags_merge_post",
+        "regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post",
+        "unassign_contact_tags_contacts_tags_unassign_post",
+        "unlock_contact_info_contacts_unlock_info_post",
+        "update_contact_tag_contacts_tags__tag_id__patch",
+        "verify_contact_emails_contacts_verify_email_post"
       ],
       "tiers": [
         "read",
+        "write",
+        "billable",
         "destructive"
       ]
     },
@@ -296,17 +345,194 @@
       "file": "components/tasks-screen.tsx",
       "purpose": "Workspace-wide task queue: Open/Completed/All, search and filters, complete or reopen, create, edit, delete, bulk complete and delete, detail panel.",
       "operations": [
-        "list_all_tasks_tasks_get",
-        "get_task_tasks__task_id__get",
         "create_global_task_tasks_post",
-        "update_task_tasks__task_id__patch",
-        "delete_task_tasks__task_id__delete"
+        "delete_task_tasks__task_id__delete",
+        "get_task_tasks__task_id__get",
+        "list_all_tasks_tasks_get",
+        "update_task_tasks__task_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "ListSelect",
+      "file": "components/list-select.tsx",
+      "purpose": "Audience-list dropdown, searchable and paged (the foundation ListSelect with GET /lists wired in). Replaces a select fed by one capped list read.",
+      "operations": [
+        "list_lists_lists_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ContactLookupLink",
+      "file": "components/contact-lookup-link.tsx",
+      "purpose": "\"Open contact\" button for something that only knows an email (inbox thread, meeting attendee, visitor, form submission): looks the email up in the CRM and calls onOpen(contactId); renders nothing when nobody has it, or with createIfMissing offers \"Add to contacts\" (creates the contact from the email and opens it).",
+      "operations": [
+        "create_contacts_contacts_post",
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "RecordOpenLinks",
+      "file": "components/record-open-links.tsx",
+      "purpose": "\"Open contact\" and \"Open company\" buttons for something that only knows ids (a call log entry, a website visitor). The ids are verified against the CRM first (and a company's domain, when given), so a button never points at a missing or wrong record.",
+      "operations": [
+        "get_company_companies__company_id__get",
+        "get_contact_contacts__contact_id__get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "RecordEngagementTab",
+      "file": "components/record-engagement-tab.tsx",
+      "purpose": "Engagement counts, last touch and pages visited for one contact or company; an extraDetailTabs entry for ContactsScreen and CompaniesScreen.",
+      "operations": [
+        "get_contact_engagement_summary_contacts__contact_id__engagement_summary_get",
+        "get_company_engagement_summary_companies__company_id__engagement_summary_get",
+        "get_contact_sites_visited_contacts__contact_id__sites_visited_get",
+        "get_company_sites_visited_companies__company_id__sites_visited_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "OwnerAssignListButton",
+      "file": "components/owner-assign.tsx",
+      "purpose": "\"Assign owner to all N contacts in this list\" with an injected team-member picker (renderPicker), hidden without one. Never for a selection: the API assigns by filter. Both assign and remove are confirmed with the list and N.",
+      "operations": [
+        "assign_contact_owner_contacts_assign_owner_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "ContactTagChips",
+      "file": "components/contact-tag-chips.tsx",
+      "purpose": "The tags on one contact as chips with remove buttons and an Add tag picker that can create a tag.",
+      "operations": [
+        "assign_contact_tags_contacts_tags_assign_post",
+        "create_contact_tag_contacts_tags_post",
+        "get_contact_tag_ids_contacts__contact_id__tags_get",
+        "list_contact_tags_contacts_tags_get",
+        "unassign_contact_tags_contacts_tags_unassign_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "TagAssignButton",
+      "file": "components/tag-assign.tsx",
+      "purpose": "Add tags to, or remove tags from, a selection of contacts.",
+      "operations": [
+        "assign_contact_tags_contacts_tags_assign_post",
+        "list_contact_tags_contacts_tags_get",
+        "unassign_contact_tags_contacts_tags_unassign_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "TagManager",
+      "file": "components/tag-manager.tsx",
+      "purpose": "Create, rename, recolour, archive, delete and merge contact tags. Delete and merge are confirmed.",
+      "operations": [
+        "create_contact_tag_contacts_tags_post",
+        "delete_contact_tag_contacts_tags__tag_id__delete",
+        "list_contact_tags_contacts_tags_get",
+        "merge_contact_tags_contacts_tags_merge_post",
+        "update_contact_tag_contacts_tags__tag_id__patch"
       ],
       "tiers": [
         "read",
         "write",
         "destructive"
       ]
+    },
+    {
+      "name": "BulkUpdateButton",
+      "file": "components/bulk-update.tsx",
+      "purpose": "Set one field (title, department, seniority, city, state, country) on every selected contact.",
+      "operations": [
+        "bulk_update_contacts_contacts_bulk_update_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "VerifyEmailButton",
+      "file": "components/verify-email-button.tsx",
+      "purpose": "Verify the work emails of a selection (billable, confirmed with the real count and cost).",
+      "operations": [
+        "verify_contact_emails_contacts_verify_email_post"
+      ],
+      "tiers": [
+        "billable"
+      ]
+    },
+    {
+      "name": "UnlockInfoButton",
+      "file": "components/unlock-info-button.tsx",
+      "purpose": "Unlock the locked contacts of a selection (billable, confirmed with the locked count and cost).",
+      "operations": [
+        "unlock_contact_info_contacts_unlock_info_post"
+      ],
+      "tiers": [
+        "billable"
+      ]
+    },
+    {
+      "name": "ContactRowActions",
+      "file": "components/contact-row-actions.tsx",
+      "purpose": "The row's ... button: owner, tags, verify and unlock for one contact.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "ContactDocumentsTab",
+      "file": "components/contact-documents-tab.tsx",
+      "purpose": "AI documents about one contact: status, write, rewrite, write all (billable, confirmed) and read.",
+      "operations": [
+        "generate_all_contact_documents_contacts__contact_id__documents_generate_all_post",
+        "generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post",
+        "get_contact_document_contacts__contact_id__documents_types__doc_type__get",
+        "get_contact_generation_status_contacts__contact_id__documents_generation_status_get",
+        "regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "ContactInsightsTab",
+      "file": "components/contact-insights-tab.tsx",
+      "purpose": "Signals for one contact and an on-demand next best step (billable, confirmed).",
+      "operations": [
+        "get_contact_next_best_step_contacts__contact_id__next_best_step_get",
+        "get_contact_signals_contacts__contact_id__signals_get"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
     }
   ],
   "hooks": [
@@ -328,6 +554,19 @@
         "list_contact_fields_fields_get",
         "list_company_fields_fields_companies_get"
       ]
+    },
+    {
+      "name": "useAllLists",
+      "file": "hooks/use-all-lists.ts",
+      "purpose": "Every list, page after page, for lookups by id (a list's size or name); ListSelect is the picker."
+    },
+    {
+      "name": "useContactTags",
+      "file": "hooks/use-contact-tags.ts",
+      "purpose": "The org's contact tags with counts, cached so chips, dialogs and the manager refresh together.",
+      "operations": [
+        "list_contact_tags_contacts_tags_get"
+      ]
     }
   ],
   "lib": [
@@ -338,6 +577,14 @@
     {
       "file": "lib/screen-parts.tsx",
       "purpose": "Sorting, row selection, bulk delete and pager shared by ContactsScreen, CompaniesScreen and TasksScreen."
+    },
+    {
+      "file": "lib/read-lists.ts",
+      "purpose": "One page of audience lists (GET /lists), the read behind ListSelect and useAllLists."
+    },
+    {
+      "file": "lib/record-actions.ts",
+      "purpose": "Tag type, the id-set grid filter, the paid-batch cap, unlock and verify target sets and cost constants, bulk-edit fields and the verify summary, shared by the record-action components."
     }
   ],
   "recipes": [
@@ -372,7 +619,7 @@
     {
       "id": "api-key-scopes",
       "where": "api",
-      "description": "The server API key carries the scopes in this block's `scopes` (contacts, companies, lists and notes/tasks read+write; contacts:delete for bulk merge).",
+      "description": "The server API key carries the scopes in this block's `scopes` (contacts, companies, lists and notes/tasks read+write; contacts:delete for bulk merge; enrichment:run for verify email, unlock info, AI documents and next best step, all of which spend credits).",
       "verify": "recipes/verify-proxy-key.ts passes and g8.api.me.describeCurrentKey() lists the scopes."
     },
     {
@@ -389,6 +636,7 @@
     "contacts:delete",
     "contacts:read",
     "contacts:write",
+    "enrichment:run",
     "fields:read",
     "fields:write",
     "lists:read",

package/blocks/crm/components/bulk-update.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * BulkUpdateButton: set ONE field to the same value on every selected contact (job title, department, seniority, city,
+ * state, country). A dialog asks for the field and the value and says how many contacts change.
+ *
+ * SDK operations:
+ *   1. bulkUpdateContacts  POST /contacts/bulk-update  [{ id, CONTACT_<FIELD>: value }, ...]   (write)
+ *        The body is one object per contact. The API authorises the WHOLE set before the first write, so a contact the
+ *        key cannot write refuses the whole chunk; failures after that are reported per contact in `errors`, not as an
+ *        HTTP error. The selection is sent in chunks of 100 with Promise.allSettled so one refused chunk does not hide
+ *        the others, and the dialog reports "N of M updated".
+ *
+ * The value is required: the API gives no documented way to clear a field in bulk, so clearing is not offered (use the
+ * contact's own Edit form). The owner and tags have their own actions.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+import { ListChecks } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { BULK_FIELDS } from "../lib/record-actions";
+import type { BulkFieldKey } from "../lib/record-actions";
+
+const CHUNK = 100;
+
+export interface BulkUpdateButtonProps {
+  contactIds: ReadonlyArray<number>;
+  /** Called with the ids that were updated, so the screen can refetch. */
+  onDone?: (updated: number[]) => void;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  className?: string;
+}
+
+interface BulkResult { updated: number[]; failed: Array<{ id: number; error: string }>; refusedChunks: number }
+
+/** `{ updated, errors: [{ id, error }] }` from one chunk; ids not named as failed count as updated. */
+export function chunkOutcome(ids: number[], data: unknown): { ok: number[]; failed: Array<{ id: number; error: string }> } {
+  const errors = ((data as { errors?: Array<{ id?: unknown; error?: unknown }> } | null)?.errors ?? [])
+    .map((e) => ({ id: Number(e.id), error: String(e.error ?? "Update failed.") }))
+    .filter((e) => Number.isFinite(e.id));
+  const bad = new Set(errors.map((e) => e.id));
+  return { ok: ids.filter((id) => !bad.has(id)), failed: errors };
+}
+
+export function BulkUpdateButton({ contactIds, onDone, variant = "outline", size = "sm", className }: BulkUpdateButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [field, setField] = useState<BulkFieldKey>(BULK_FIELDS[0].key);
+  const [value, setValue] = useState("");
+  const [result, setResult] = useState<(BulkResult & { total: number; label: string }) | null>(null);
+  const label = BULK_FIELDS.find((f) => f.key === field)?.label ?? field;
+
+  const run = useG8Mutation(async (v: { ids: number[]; field: BulkFieldKey; value: string }): Promise<BulkResult> => {
+    const chunks: number[][] = [];
+    for (let i = 0; i < v.ids.length; i += CHUNK) chunks.push(v.ids.slice(i, i + CHUNK));
+    const settled = await Promise.allSettled(chunks.map((ids) => g8Post("/contacts/bulk-update", ids.map((id) => ({ id, [v.field]: v.value })))));
+    const out: BulkResult = { updated: [], failed: [], refusedChunks: 0 };
+    settled.forEach((s, i) => {
+      if (s.status === "rejected") { out.refusedChunks += 1; return; }
+      const o = chunkOutcome(chunks[i], s.value.data);
+      out.updated.push(...o.ok);
+      out.failed.push(...o.failed);
+    });
+    if (out.updated.length === 0 && out.refusedChunks === chunks.length && settled[0]?.status === "rejected") throw (settled[0] as PromiseRejectedResult).reason;
+    return out;
+  }, {
+    invalidates: [["contacts", "list"], ["contacts", "detail"], ["contacts", "record"]],
+    onSuccess: (r, v) => { setResult({ ...r, total: v.ids.length, label }); onDone?.(r.updated); },
+  });
+
+  const close = () => { setOpen(false); setValue(""); setResult(null); run.reset(); };
+  const count = contactIds.length;
+  const trimmed = value.trim();
+
+  return (
+    <>
+      <Button className={className} variant={variant} size={size} disabled={count === 0} onClick={() => setOpen(true)}><ListChecks className="size-4" aria-hidden />Bulk edit</Button>
+      <Dialog open={open} onOpenChange={(o) => (o ? setOpen(true) : close())}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Edit {plural(count, "contact")}</DialogTitle>
+            <DialogDescription>The same value is written to every selected contact. Existing values are replaced.</DialogDescription>
+          </DialogHeader>
+          {result ? (
+            <div role="status" className="text-sm">
+              <p className="font-medium">Updated {result.updated.length.toLocaleString()} of {result.total.toLocaleString()} ({result.label}).</p>
+              {result.failed.length > 0 ? <p className="mt-1 text-destructive">{plural(result.failed.length, "contact")} could not be updated: {[...new Set(result.failed.map((f) => f.error))].join("; ")}</p> : null}
+              {result.refusedChunks > 0 ? <p className="mt-1 text-destructive">{plural(result.refusedChunks, "batch", "batches")} of up to {CHUNK} was refused by the server. Those contacts are unchanged.</p> : null}
+            </div>
+          ) : (
+            <div className="flex flex-col gap-3">
+              <label className="flex flex-col gap-1 text-sm">Field
+                <select className="h-9 rounded-md border bg-background px-2" value={field} onChange={(e) => setField(e.target.value as BulkFieldKey)}>
+                  {BULK_FIELDS.map((f) => <option key={f.key} value={f.key}>{f.label}</option>)}
+                </select>
+              </label>
+              <label className="flex flex-col gap-1 text-sm">New value
+                <input className="h-9 rounded-md border bg-background px-3" maxLength={200} value={value} onChange={(e) => setValue(e.target.value)} />
+              </label>
+              {run.error ? <ApiError error={run.error} title="Could not update the contacts" /> : null}
+            </div>
+          )}
+          <DialogFooter>
+            {result ? <Button onClick={close}>Done</Button> : (
+              <>
+                <Button variant="ghost" onClick={close}>Cancel</Button>
+                <Button loading={run.loading} disabled={!trimmed || count === 0} onClick={() => void run.mutate({ ids: [...contactIds], field, value: trimmed })}>Update {plural(count, "contact")}</Button>
+              </>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/blocks/crm/components/companies-screen.tsx

@@ -37,8 +37,9 @@ import { RecordLink } from "@/g8/components/screen/record-link";
 import { plural } from "@/g8/lib/plural";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useUrlState } from "@/g8/hooks/use-url-state";
+import { useUrlFilters } from "@/g8/hooks/use-url-filters";
+import { MoreFilters, RangeFilter, TextFilter } from "@/g8/components/screen/filter-controls";
 import { g8Delete, g8Get } from "@/g8/lib/g8-client";
-import { useDebouncedValue } from "../hooks/use-debounced";
 import { usePageQuery } from "../hooks/use-page-query";
 import { companyName, errorStatus, location } from "../lib/crm-types";
 import type { CompanyRecord, ContactRecord, ScreenActionContext } from "../lib/crm-types";
@@ -67,8 +68,10 @@ export interface CompaniesScreenProps {
   className?: string;
 }
 
-interface Filters { name: string; domain: string; industry: string; country: string }
-const NO_FILTERS: Filters = { name: "", domain: "", industry: "", country: "" };
+/** Every filter the companies API takes: text (name, domain, industry, country, state, city, description) and four from/to ranges. */
+const FILTER_KEYS = ["name", "domain", "industry", "country", "state", "city", "description", "employee_count_min", "employee_count_max", "revenue_min", "revenue_max", "founded_year_min", "founded_year_max", "linkedin_followers_min", "linkedin_followers_max"] as const;
+type FilterKey = (typeof FILTER_KEYS)[number];
+const MORE_KEYS: readonly FilterKey[] = FILTER_KEYS.filter((k) => !["name", "domain", "industry", "country"].includes(k));
 
 function sortValue(row: CompanyRecord, key: string): string | null | undefined {
   if (key === "name") return row.name || row.domain;
@@ -91,8 +94,9 @@ export function CompaniesScreen(props: CompaniesScreenProps) {
   const parsedId = idParam ? Number(idParam) : null;
   /** A malformed deep link (`?id=abc`) opens nothing instead of fetching /companies/NaN. */
   const openId = parsedId != null && Number.isFinite(parsedId) ? parsedId : null;
-  const [draft, setDraft] = useState<Filters>(NO_FILTERS);
-  const filters = useDebouncedValue(draft);
+  // The filters live in the URL (`co_city=...`), so a filtered view survives reload, Back and sharing.
+  const urlFilters = useUrlFilters(FILTER_KEYS, { prefix: "co_" });
+  const { draft, filters } = urlFilters;
   const [sheet, setSheet] = useState<"new" | "dupes" | null>(null);
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [note, setNote] = useState<string | null>(null);
@@ -103,15 +107,16 @@ export function CompaniesScreen(props: CompaniesScreenProps) {
     [filters],
     pageSize,
     ["companies", "list", "screen"],
+    urlFilters.ready,
   );
   const dupes = useG8Query((signal) => g8Get<{ pending?: number; count?: number }>("/duplicates/counts", { entity_type: "company" }, { signal }), [], { key: ["duplicates", "counts", "company"] });
   const selection = useRowSelection<CompanyRecord>(JSON.stringify(filters));
   const rows = useMemo(() => sortRows(list.rows, sort, sortValue), [list.rows, sort]);
-  const hasFilters = Object.values(draft).some(Boolean);
+  const hasFilters = urlFilters.active;
   const pending = dupes.data?.data.pending ?? dupes.data?.data.count;
   const industries = new Set(list.rows.map((r) => r.industry).filter(Boolean)).size;
   const reload = () => { void list.refetch(); void dupes.refetch(); };
-  const set = (key: keyof Filters, v: string) => setDraft((f) => ({ ...f, [key]: v }));
+  const set = (key: FilterKey, v: string) => urlFilters.set(key, v);
   const allOnPage = rows.length > 0 && rows.every((r) => selection.selected.has(r.id));
 
   const bulk = useBulkDelete("/companies", (gone, total) => {
@@ -157,7 +162,16 @@ export function CompaniesScreen(props: CompaniesScreenProps) {
                   <input aria-label="Filter by domain" placeholder="Domain" className="h-9 w-36 rounded-md border bg-background px-3 text-sm" value={draft.domain} onChange={(e) => set("domain", e.target.value)} />
                   <input aria-label="Filter by industry" placeholder="Industry" className="h-9 w-36 rounded-md border bg-background px-3 text-sm" value={draft.industry} onChange={(e) => set("industry", e.target.value)} />
                   <input aria-label="Filter by country" placeholder="Country" className="h-9 w-32 rounded-md border bg-background px-3 text-sm" value={draft.country} onChange={(e) => set("country", e.target.value)} />
-                  {hasFilters ? <Button variant="ghost" size="sm" onClick={() => setDraft(NO_FILTERS)}>Clear filters</Button> : null}
+                  <MoreFilters activeCount={MORE_KEYS.filter((k) => draft[k]).length}>
+                    <TextFilter label="state" value={draft.state} onChange={(v) => set("state", v)} className="w-28" />
+                    <TextFilter label="city" value={draft.city} onChange={(v) => set("city", v)} className="w-32" />
+                    <TextFilter label="description" value={draft.description} onChange={(v) => set("description", v)} className="w-44" />
+                    <RangeFilter label="Employees" min={draft.employee_count_min} max={draft.employee_count_max} onMinChange={(v) => set("employee_count_min", v)} onMaxChange={(v) => set("employee_count_max", v)} />
+                    <RangeFilter label="Revenue" min={draft.revenue_min} max={draft.revenue_max} onMinChange={(v) => set("revenue_min", v)} onMaxChange={(v) => set("revenue_max", v)} />
+                    <RangeFilter label="Founded" min={draft.founded_year_min} max={draft.founded_year_max} onMinChange={(v) => set("founded_year_min", v)} onMaxChange={(v) => set("founded_year_max", v)} />
+                    <RangeFilter label="LinkedIn followers" min={draft.linkedin_followers_min} max={draft.linkedin_followers_max} onMinChange={(v) => set("linkedin_followers_min", v)} onMaxChange={(v) => set("linkedin_followers_max", v)} />
+                  </MoreFilters>
+                  {hasFilters ? <Button variant="ghost" size="sm" onClick={urlFilters.clear}>Clear filters</Button> : null}
                 </>
               }
             />
@@ -210,7 +224,7 @@ export function CompaniesScreen(props: CompaniesScreenProps) {
                 <EmptyState
                   title={hasFilters ? "No companies match these filters" : "No companies yet"}
                   description={hasFilters ? "Try fewer filters." : "Add a company, or import contacts and their companies are created from their domains."}
-                  action={hasFilters ? <Button variant="outline" onClick={() => setDraft(NO_FILTERS)}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New company</Button>}
+                  action={hasFilters ? <Button variant="outline" onClick={urlFilters.clear}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New company</Button>}
                 />
               ) : null}
               <Pager page={list.page} pageCount={list.pageCount} total={list.total} noun="companies" hasNext={list.hasNext} loading={list.loading} onPage={list.setPage} />

package/blocks/crm/components/company-detail.tsx

@@ -66,9 +66,9 @@ export function CompanyDetail({ companyId, onDeleted, onOpenContact, renderActio
   return (
     <div className={`flex flex-col gap-4 ${className ?? ""}`}>
       <header className="flex flex-wrap items-center gap-3">
-        <div aria-hidden className="flex size-12 items-center justify-center rounded-md bg-muted text-sm font-semibold">{initials(name)}</div>
+        <div aria-hidden className="flex size-12 items-center justify-center rounded-md bg-muted text-sm font-medium">{initials(name)}</div>
         <div className="min-w-0 flex-1">
-          <h2 className="truncate text-lg font-semibold">{name}</h2>
+          <h2 className="truncate text-lg font-medium">{name}</h2>
           <p className="truncate text-sm text-muted-foreground">{[company.domain, company.industry].filter(Boolean).join(" - ") || "No domain or industry"}</p>
         </div>
         <div className="flex flex-wrap items-center gap-2">

package/blocks/crm/components/contact-detail.tsx

@@ -25,7 +25,7 @@ import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { g8Delete, g8Get } from "@/g8/lib/g8-client";
-import { contactName, initials, isMasked, location } from "../lib/crm-types";
+import { contactName, contactSubtitle, initials, isMasked, location } from "../lib/crm-types";
 import type { ContactRecord } from "../lib/crm-types";
 import { ActivityTimeline } from "./activity-timeline";
 import { NotesPanel } from "./notes-panel";
@@ -75,11 +75,11 @@ export function ContactDetail({ contactId, onDeleted, onOpenCompany, renderActio
   return (
     <div className={`flex flex-col gap-4 ${className ?? ""}`}>
       <header className="flex flex-wrap items-center gap-3">
-        <div aria-hidden className="flex size-12 items-center justify-center rounded-full bg-muted text-sm font-semibold">{initials(name)}</div>
+        <div aria-hidden className="flex size-12 items-center justify-center rounded-full bg-muted text-sm font-medium">{initials(name)}</div>
         <div className="min-w-0 flex-1">
-          <h2 className="truncate text-lg font-semibold">{name}</h2>
+          <h2 className="truncate text-lg font-medium">{name}</h2>
           <p className="truncate text-sm text-muted-foreground">
-            {[contact.job_title, contact.company?.name].filter(Boolean).join(" at ") || "No title or company"}
+            {contactSubtitle(contact)}
           </p>
         </div>
         <div className="flex flex-wrap items-center gap-2">