@crossworks/content-core 0.230.43

package/src/block-list.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Unit tests for listBlocks — the TOC extraction that powers
+ * `page_blocks_list` (the agent's "what's in this page?" lookup).
+ */
+
+import { describe, expect, it } from 'vitest';
+import { ensureBlockIds } from './block-ids';
+import { listBlocks } from './block-list';
+
+function blocked(doc: Record<string, unknown>): Record<string, unknown> {
+  // Always run through ensureBlockIds so the listings have stable ids,
+  // matching the real call path (markdownToDoc / getPage / saveDraft).
+  return ensureBlockIds(doc);
+}
+
+describe('listBlocks', () => {
+  it('lists top-level blocks in document order with depth=1', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'Hi' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'World' }] },
+        { type: 'horizontalRule' },
+      ],
+    });
+    const blocks = listBlocks(doc);
+    expect(blocks).toHaveLength(3);
+    expect(blocks.map((b) => b.kind)).toEqual(['heading', 'paragraph', 'horizontalRule']);
+    expect(blocks.every((b) => b.depth === 1)).toBe(true);
+    expect(blocks.every((b) => typeof b.id === 'string' && b.id.length > 8)).toBe(true);
+  });
+
+  it('captures previews from text content, single-line + trimmed', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'text', text: '  Hello   ' },
+            { type: 'text', text: '  world\n', marks: [{ type: 'bold' }] },
+          ],
+        },
+      ],
+    });
+    const [p] = listBlocks(doc);
+    expect(p?.preview).toBe('Hello world');
+  });
+
+  it('truncates previews with an ellipsis past the cap', () => {
+    const long = 'x'.repeat(200);
+    const doc = blocked({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: long }] }],
+    });
+    const [p] = listBlocks(doc, { previewChars: 50 });
+    expect(p?.preview.length).toBeLessThanOrEqual(50);
+    expect(p?.preview.endsWith('…')).toBe(true);
+  });
+
+  it('includes meta — heading level, code language, callout variant', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'H' }] },
+        {
+          type: 'codeBlock',
+          attrs: { language: 'typescript' },
+          content: [{ type: 'text', text: 'const x = 1' }],
+        },
+        {
+          type: 'callout',
+          attrs: { variant: 'warning' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'careful' }] }],
+        },
+      ],
+    });
+    const blocks = listBlocks(doc);
+    expect(blocks[0]!.meta).toEqual({ level: 2 });
+    expect(blocks[1]!.meta).toEqual({ language: 'typescript' });
+    expect(blocks[2]!.meta).toEqual({ variant: 'warning' });
+  });
+
+  it('lists a diagram block with its declared type as meta', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'diagram', attrs: { source: 'flowchart LR\n  A --> B' } },
+        { type: 'diagram', attrs: { source: '---\ntitle: Plan\n---\nmindmap\n  root' } },
+      ],
+    });
+    const blocks = listBlocks(doc);
+    expect(blocks[0]!.kind).toBe('diagram');
+    expect(blocks[0]!.id).toBeTruthy();
+    expect(blocks[0]!.meta).toEqual({ diagram: 'flowchart' });
+    // Mermaid frontmatter is skipped when reading the declared type.
+    expect(blocks[1]!.meta).toEqual({ diagram: 'mindmap' });
+  });
+
+  it('diagram meta skips %% directives and yields none for unclosed frontmatter', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'diagram', attrs: { source: '%%{init: {"theme":"base"}}%%\nflowchart TD\n  A' } },
+        { type: 'diagram', attrs: { source: '---\ntitle: Broken\nmindmap\n  root' } },
+        { type: 'diagram', attrs: { source: '' } },
+      ],
+    });
+    const blocks = listBlocks(doc);
+    expect(blocks[0]!.meta).toEqual({ diagram: 'flowchart' });
+    expect(blocks[1]!.meta).toBeUndefined();
+    expect(blocks[2]!.meta).toBeUndefined();
+  });
+
+  it('walks into containers — callout body shows at depth=2', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          attrs: { variant: 'info' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'inside' }] }],
+        },
+      ],
+    });
+    const blocks = listBlocks(doc);
+    expect(blocks).toHaveLength(2); // callout + inner paragraph
+    expect(blocks[0]).toMatchObject({ kind: 'callout', depth: 1 });
+    expect(blocks[1]).toMatchObject({ kind: 'paragraph', depth: 2, preview: 'inside' });
+  });
+
+  it('respects maxDepth — only top-level when maxDepth=1', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          attrs: { variant: 'info' },
+          content: [
+            { type: 'paragraph', content: [{ type: 'text', text: 'inside' }] },
+            { type: 'paragraph', content: [{ type: 'text', text: 'too' }] },
+          ],
+        },
+        { type: 'paragraph', content: [{ type: 'text', text: 'after' }] },
+      ],
+    });
+    const blocks = listBlocks(doc, { maxDepth: 1 });
+    expect(blocks).toHaveLength(2); // callout + 'after' paragraph, no inner
+    expect(blocks.map((b) => b.kind)).toEqual(['callout', 'paragraph']);
+  });
+
+  it('columnList → columns → inner blocks all listed in document order', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        {
+          type: 'columnList',
+          content: [
+            {
+              type: 'column',
+              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'L' }] }],
+            },
+            {
+              type: 'column',
+              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'R' }] }],
+            },
+          ],
+        },
+      ],
+    });
+    const blocks = listBlocks(doc);
+    expect(blocks.map((b) => `${b.kind}@${b.depth}:${b.preview || '-'}`)).toEqual([
+      'columnList@1:L R',
+      'column@2:L',
+      'paragraph@3:L',
+      'column@2:R',
+      'paragraph@3:R',
+    ]);
+  });
+
+  it('kinds filter returns only matching blocks — but walker still descends', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'H' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'top P' }] },
+        {
+          type: 'callout',
+          attrs: { variant: 'info' },
+          content: [
+            { type: 'paragraph', content: [{ type: 'text', text: 'inner P' }] },
+            {
+              type: 'blockquote',
+              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'quote' }] }],
+            },
+          ],
+        },
+        {
+          type: 'blockquote',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'top quote' }] }],
+        },
+      ],
+    });
+
+    // Only blockquotes — should return both (one nested in a callout, one top).
+    const blockquotes = listBlocks(doc, { kinds: ['blockquote'] });
+    expect(blockquotes.map((b) => b.kind)).toEqual(['blockquote', 'blockquote']);
+    expect(blockquotes[0]!.preview).toBe('quote'); // the nested one (first in doc order)
+    expect(blockquotes[1]!.preview).toBe('top quote');
+
+    // Multi-kind filter.
+    const both = listBlocks(doc, { kinds: ['heading', 'blockquote'] });
+    expect(both.map((b) => b.kind)).toEqual(['heading', 'blockquote', 'blockquote']);
+
+    // No filter — everything.
+    const all = listBlocks(doc);
+    expect(all.length).toBeGreaterThan(4); // heading + p + callout + inner p + blockquote + inner p + top blockquote + inner p
+
+    // Empty filter array = no filter (treated as "all kinds").
+    const emptyFilter = listBlocks(doc, { kinds: [] });
+    expect(emptyFilter.length).toBe(all.length);
+  });
+
+  it('stays compact — 50–80 bytes per typical block in JSON', () => {
+    const doc = blocked({
+      type: 'doc',
+      content: Array.from({ length: 50 }, (_, i) => ({
+        type: 'paragraph',
+        content: [{ type: 'text', text: `Block ${i} with some moderately long content here.` }],
+      })),
+    });
+    const blocks = listBlocks(doc);
+    const serialized = JSON.stringify(blocks);
+    const bytesPerBlock = serialized.length / blocks.length;
+    expect(blocks).toHaveLength(50);
+    // Each entry: id (36) + kind (~9) + depth (1) + preview (~60) + JSON
+    // overhead. Generous upper bound — if we ever blow past this something
+    // changed in the shape and the agent's tool-result budget is at risk.
+    expect(bytesPerBlock).toBeLessThan(180);
+  });
+});

package/src/block-list.ts

@@ -0,0 +1,177 @@
+/**
+ * Block TOC extraction — flat listing of every addressable block in a
+ * ProseMirror doc, with type / depth / id / short text preview. Powers
+ * `page_blocks_list` (the agent's "what's in this page?" tool) and the
+ * Phase 3a editor's block picker.
+ *
+ * Designed to be cheap to send to a model: 50–80 bytes per block in
+ * JSON, so a 200-block page is ~10–15 KB total — well under the
+ * inline tool-result cap. Agent reads the TOC to decide WHICH blocks
+ * to touch, then fetches only those (Phase 2b mutation tools).
+ *
+ * Pure, no DB. Companion to block-ids.ts — and imports the addressable
+ * block-type set from there so the two stay in lockstep automatically.
+ * A new block type added to block-ids.ts is picked up here for free.
+ */
+
+import { BLOCK_NODE_TYPES as BLOCK_TYPES } from './block-ids';
+
+export type BlockListEntry = {
+  /** Stable per-block id (assigned by ensureBlockIds). May be the
+   *  empty string if the doc was somehow built without injection — the
+   *  walker is defensive and still lists the block. */
+  id: string;
+  /** PM node type (e.g. 'heading', 'paragraph', 'callout'). */
+  kind: string;
+  /** Tree depth: 1 = direct child of doc, 2 = inside a container, etc. */
+  depth: number;
+  /** First ~80 chars of textContent, single-line, trimmed. Empty
+   *  string for purely structural nodes (horizontalRule, table without
+   *  inner text yet, etc.). */
+  preview: string;
+  /** For headings: their level (1/2/3). For codeBlock: language. For
+   *  callout: variant. Helps the model choose. Omitted when N/A. */
+  meta?: Record<string, unknown>;
+};
+
+export type ListBlocksOptions = {
+  /** If set, only list blocks at this depth or shallower. Useful when
+   *  the model just wants a high-level outline (depth: 1) or top-level
+   *  + first-nested (depth: 2). Default: unlimited. */
+  maxDepth?: number;
+  /** Preview character cap. Default 80. */
+  previewChars?: number;
+  /** If set, only blocks whose `kind` is in this set are listed (but
+   *  the walker still DESCENDS through other types — a paragraph inside
+   *  a callout is still findable when filtering by 'paragraph'). Powers
+   *  targeted edits: 'find every blockquote', 'list every heading',
+   *  etc., without the spill risk of unfiltered output on a large doc. */
+  kinds?: ReadonlyArray<string>;
+};
+
+type AnyNode = {
+  type?: string;
+  attrs?: Record<string, unknown> | null;
+  content?: AnyNode[];
+  text?: string;
+};
+
+/**
+ * Walk the doc, return flat block list in document order. Container
+ * blocks appear BEFORE their children (so the agent sees structure
+ * top-down — heading first, then the paragraphs under it).
+ */
+export function listBlocks(
+  doc: Record<string, unknown>,
+  opts: ListBlocksOptions = {},
+): BlockListEntry[] {
+  const maxDepth = opts.maxDepth ?? Infinity;
+  const previewChars = opts.previewChars ?? 80;
+  const kindFilter = opts.kinds && opts.kinds.length > 0 ? new Set(opts.kinds) : null;
+  const out: BlockListEntry[] = [];
+  walk(doc as AnyNode, 0, out, maxDepth, previewChars, kindFilter);
+  return out;
+}
+
+function walk(
+  node: AnyNode,
+  depth: number,
+  out: BlockListEntry[],
+  maxDepth: number,
+  previewChars: number,
+  kindFilter: Set<string> | null,
+): void {
+  if (!node || typeof node !== 'object') return;
+  const kind = node.type;
+  if (kind && BLOCK_TYPES.has(kind)) {
+    // depth+1 because the doc root itself is depth 0; its first children
+    // are depth 1 (the natural reading: "block 1, block 2, …" at the
+    // top of the page).
+    const blockDepth = depth + 1;
+    // Two gates to PUSH: within maxDepth AND (no kind filter OR kind matches).
+    // The recursion always descends regardless of kind — a paragraph inside
+    // a filtered-out callout still gets listed if its own kind passes.
+    if (blockDepth <= maxDepth && (!kindFilter || kindFilter.has(kind))) {
+      out.push({
+        id: typeof node.attrs?.id === 'string' ? node.attrs.id : '',
+        kind,
+        depth: blockDepth,
+        preview: makePreview(node, previewChars),
+        ...(blockMeta(kind, node) ? { meta: blockMeta(kind, node)! } : {}),
+      });
+    }
+    // Always recurse INTO the block, even if we're at maxDepth — children
+    // beyond the cap simply don't get listed, but we still walk them in
+    // case of cap=1 (only top-level) the walker exits at the children
+    // loop without adding more entries. That's fine.
+    if (Array.isArray(node.content) && blockDepth < maxDepth) {
+      for (const child of node.content) {
+        walk(child, blockDepth, out, maxDepth, previewChars, kindFilter);
+      }
+    }
+    return;
+  }
+  // Non-block (doc root, text, marks): recurse children with same depth.
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) {
+      walk(child, depth, out, maxDepth, previewChars, kindFilter);
+    }
+  }
+}
+
+function makePreview(node: AnyNode, max: number): string {
+  const text = collectText(node).replace(/\s+/g, ' ').trim();
+  if (text.length <= max) return text;
+  return text.slice(0, max - 1).trimEnd() + '…';
+}
+
+function collectText(node: AnyNode): string {
+  if (!node || typeof node !== 'object') return '';
+  if (typeof node.text === 'string') return node.text;
+  if (!Array.isArray(node.content)) return '';
+  let acc = '';
+  for (const child of node.content) {
+    const t = collectText(child);
+    if (t) {
+      if (acc && !acc.endsWith(' ')) acc += ' ';
+      acc += t;
+    }
+  }
+  return acc;
+}
+
+function blockMeta(kind: string, node: AnyNode): Record<string, unknown> | null {
+  const attrs = node.attrs ?? {};
+  switch (kind) {
+    case 'heading':
+      return typeof attrs.level === 'number' ? { level: attrs.level } : null;
+    case 'codeBlock':
+      return typeof attrs.language === 'string' && attrs.language
+        ? { language: attrs.language }
+        : null;
+    case 'callout':
+      return typeof attrs.variant === 'string' ? { variant: attrs.variant } : null;
+    case 'aside':
+      return typeof attrs.color === 'string' ? { color: attrs.color } : null;
+    case 'taskItem':
+      return typeof attrs.checked === 'boolean' ? { checked: attrs.checked } : null;
+    case 'image':
+    case 'pageImage':
+      return typeof attrs.alt === 'string' && attrs.alt ? { alt: attrs.alt } : null;
+    case 'diagram': {
+      // Surface the declared diagram type (flowchart, sequenceDiagram, mindmap…)
+      // — the first meaningful word: skip ---frontmatter--- and %%…%% directive/
+      // comment lines; an unclosed frontmatter yields no meta rather than '---'.
+      if (typeof attrs.source !== 'string') return null;
+      const body = attrs.source.replace(/^\s*---[\s\S]*?---\s*/, '');
+      const first = body
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l && !l.startsWith('%%'));
+      const word = first?.split(/[\s:;{]/, 1)[0];
+      return word && word !== '---' ? { diagram: word } : null;
+    }
+    default:
+      return null;
+  }
+}

package/src/contacts-format.ts

@@ -0,0 +1,260 @@
+/**
+ * Pure shape + format helpers for contacts. NO database imports — this is the
+ * module the browser-side `/contacts` client pulls from (via the
+ * `@mantle/content/contacts-format` subpath) to avoid dragging `postgres` /
+ * `@mantle/db` into the client bundle.
+ *
+ * The DB-using CRUD lives in `./contacts.ts`, which re-exports these so
+ * server-side callers can keep importing from `@mantle/content`.
+ */
+
+/** Methods we count outbound contact attempts by. Open-ended on the data side
+ *  (the jsonb just stores keys), but typed here for the call sites we wire
+ *  ourselves so a typo becomes a compile error. Add new entries as we add
+ *  surfaces. */
+export type ContactMethod = 'email' | 'sms';
+
+export type ContactCounts = Partial<Record<string, number>>;
+export type ContactLastAt = Partial<Record<string, string>>;
+
+export type ContactRow = {
+  id: string;
+  title: string;
+  firstName: string;
+  lastName: string;
+  /** Organisation name. Independent of person name — supports both
+   *  "John Smith" (no company), "Modular" (company-only, e.g. a supplier),
+   *  and "John Smith @ Modular" (both). */
+  company: string;
+  /** Every email entry on the contact. Each is either a full address
+   *  (`alex@example.com`) or a `@domain` wildcard (`@example.com` = all mail
+   *  from that domain). The inbound gate matches against both; the outbound
+   *  send allowlist uses concrete addresses only (see `partitionEmailEntries`). */
+  emails: string[];
+  /** Derived convenience = `emails[0] ?? ''`. Kept so existing list rows /
+   *  tool projections that read a single `email` keep working unchanged. */
+  email: string;
+  countryCode: string;
+  cell: string;
+  /** E.164 normalised number, e.g. "+27760810774". Empty when no cell on file. */
+  cellE164: string;
+  /** Human-formatted cell with country code, e.g. "+27 76 081 0774". */
+  cellFormatted: string;
+  description: string;
+  tags: string[];
+  summary: string | null;
+  /** Per-method count of outbound contact attempts (bumped on send success).
+   *  Empty object when never contacted; missing keys read as 0. */
+  contactCounts: ContactCounts;
+  /** Per-method ISO timestamp of the most recent outbound. Missing keys = never. */
+  lastContactedAt: ContactLastAt;
+  /** Team membership (see @mantle/content/team-tokens). Null when the contact
+   *  is not a team member; the plaintext token is NEVER part of this row —
+   *  it's returned once at mint and only its hash is stored. */
+  team: { since: string; lastUsedAt: string | null } | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type CreateContactInput = {
+  firstName?: string;
+  lastName?: string;
+  company?: string;
+  /** Email entries — addresses and/or `@domain` wildcards. Preferred input. */
+  emails?: string[];
+  /** @deprecated single-email back-compat. Folded into `emails` if `emails`
+   *  is absent. New callers should pass `emails`. */
+  email?: string;
+  countryCode?: string;
+  cell?: string;
+  description?: string;
+  tags?: string[];
+};
+
+export type UpdateContactInput = CreateContactInput;
+
+/** Strip everything but digits. Robust to user pasting "(760) 810-0774" etc. */
+export function digitsOnly(s: string): string {
+  return (s ?? '').replace(/\D+/g, '');
+}
+
+/**
+ * Normalise a country-code input. Accepts "+27", "27", or "00 27" — returns
+ * "+27" if it looks like a plausible 1-4 digit country code, else "" (so the
+ * caller can refuse). Pure.
+ */
+export function normalizeCountryCode(input: string): string {
+  const raw = (input ?? '').trim();
+  if (!raw) return '';
+  // "00 27" / "0027" → "27"
+  const digits = digitsOnly(raw).replace(/^00/, '');
+  // 1–4 digits and must NOT start with 0 — ITU-T E.164 codes are non-zero.
+  if (digits.length < 1 || digits.length > 4 || digits.startsWith('0')) return '';
+  return `+${digits}`;
+}
+
+/** E.164: country code + digits-only cell. Returns "" if either part is missing. */
+export function toE164(countryCode: string, cell: string): string {
+  const cc = normalizeCountryCode(countryCode);
+  const local = digitsOnly(cell);
+  if (!cc || !local) return '';
+  return `${cc}${local}`;
+}
+
+/**
+ * Group a national-number string into chunks for display. Defensive default:
+ * group from the RIGHT into 4 + 3 + … so "760810774" → "76 081 0774". Country
+ * code prepended separately. Good enough for ZA/UK/AU/most ITU plans; not a
+ * libphonenumber replacement.
+ */
+export function formatCell(countryCode: string, cell: string): string {
+  const cc = normalizeCountryCode(countryCode);
+  const digits = digitsOnly(cell);
+  if (!cc && !digits) return '';
+  if (!digits) return cc;
+  // Right-to-left groups: last 4, then 3, then 3, …
+  const groups: string[] = [];
+  let i = digits.length;
+  while (i > 0) {
+    const take = groups.length === 0 ? 4 : 3;
+    const start = Math.max(0, i - take);
+    groups.unshift(digits.slice(start, i));
+    i = start;
+  }
+  return cc ? `${cc} ${groups.join(' ')}` : groups.join(' ');
+}
+
+/** Lower-case + trim. We compare emails case-insensitively across the system. */
+export function normalizeEmail(s: string): string {
+  return (s ?? '').trim().toLowerCase();
+}
+
+/** Cheap structural email check — `<local>@<host>.<tld>`. Deliberately permissive;
+ *  the SMTP server is the real authority. */
+export function isPlausibleEmail(s: string): boolean {
+  const e = normalizeEmail(s);
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e);
+}
+
+/** Domain shape for `@domain` wildcard entries (lower-cased, no leading `@`).
+ *  Mirrors the validator the retired senders UI used. */
+const DOMAIN_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+
+export type EmailEntryKind = 'address' | 'domain' | 'invalid';
+
+/**
+ * Classify one contact email-list entry. A leading `@` marks a **domain
+ * wildcard** (`@example.com` = all mail from that domain); anything else must
+ * be a plausible full address. A bare domain without `@` (`example.com`) is
+ * rejected so the wildcard intent is always explicit and never confused with a
+ * malformed address.
+ */
+export function classifyEntry(raw: string): EmailEntryKind {
+  const s = (raw ?? '').trim().toLowerCase();
+  if (!s) return 'invalid';
+  if (s.startsWith('@')) return DOMAIN_RE.test(s.slice(1)) ? 'domain' : 'invalid';
+  return isPlausibleEmail(s) ? 'address' : 'invalid';
+}
+
+/** Canonicalise an entry: lower-cased address, or `@domain` for a wildcard.
+ *  Returns '' for invalid input (caller decides whether to reject). */
+export function normalizeEmailEntry(raw: string): string {
+  const s = (raw ?? '').trim().toLowerCase();
+  switch (classifyEntry(s)) {
+    case 'address':
+      return s;
+    case 'domain':
+      return '@' + s.replace(/^@/, '');
+    default:
+      return '';
+  }
+}
+
+/** True when the entry is a usable address OR a `@domain` wildcard. */
+export function isPlausibleEmailOrDomain(raw: string): boolean {
+  return classifyEntry(raw) !== 'invalid';
+}
+
+/** Normalise + de-dupe a list of entries, dropping anything invalid. Lenient —
+ *  used for diffing/comparison where bad legacy values shouldn't throw. */
+export function normalizeEmailEntries(entries: string[] | undefined): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of entries ?? []) {
+    const norm = normalizeEmailEntry((raw ?? '').trim());
+    if (norm && !seen.has(norm)) {
+      seen.add(norm);
+      out.push(norm);
+    }
+  }
+  return out;
+}
+
+/**
+ * Split a contact's email entries into concrete `addresses` and bare `domains`
+ * (the `@` stripped). Entries are normalised + de-duped; invalid ones dropped.
+ *
+ * The **inbound** gate matches a From address against both sets. The
+ * **outbound** send allowlist uses `addresses` only — you can't send to a whole
+ * domain. This asymmetry is deliberate (a domain wildcard means "trust mail
+ * FROM here", not "I may send anywhere here").
+ */
+export function partitionEmailEntries(entries: string[] | undefined): {
+  addresses: string[];
+  domains: string[];
+} {
+  const addresses = new Set<string>();
+  const domains = new Set<string>();
+  for (const raw of entries ?? []) {
+    const norm = normalizeEmailEntry(raw);
+    if (!norm) continue;
+    if (norm.startsWith('@')) domains.add(norm.slice(1));
+    else addresses.add(norm);
+  }
+  return { addresses: [...addresses], domains: [...domains] };
+}
+
+/**
+ * A contact has a usable identity when at least one of name, last name, or
+ * company is set. Email/cell alone aren't enough — they're contact channels,
+ * not identities. Used by the save-side validation in `updateContact` and by
+ * the client form to pre-check before fetch. Pure + exported.
+ */
+export function hasIdentity(input: {
+  firstName?: string;
+  lastName?: string;
+  company?: string;
+}): boolean {
+  return Boolean(
+    (input.firstName ?? '').trim() || (input.lastName ?? '').trim() || (input.company ?? '').trim(),
+  );
+}
+
+/** Derive the title shown for a contact, in precedence order:
+ *   1. Person name ("First Last") — the most specific identifier when set.
+ *   2. Company / organisation name — for supplier/org contacts with no person.
+ *   3. Email address.
+ *   4. Formatted cell number.
+ *   5. "Untitled contact" — a brand-new empty draft (mirrors notes' "Untitled note").
+ *  Name beats company so "Jane @ Modular" titles as "Jane Smith" with the
+ *  company surfaced separately in the UI. Company-only contacts ("Modular"
+ *  with no person) get the company as the title. */
+export function deriveContactTitle(input: {
+  firstName?: string;
+  lastName?: string;
+  company?: string;
+  emails?: string[];
+  email?: string;
+  countryCode?: string;
+  cell?: string;
+}): string {
+  const name = `${(input.firstName ?? '').trim()} ${(input.lastName ?? '').trim()}`.trim();
+  if (name) return name.slice(0, 200);
+  const company = (input.company ?? '').trim();
+  if (company) return company.slice(0, 200);
+  const email = normalizeEmail(input.emails?.[0] ?? input.email ?? '');
+  if (email) return email.slice(0, 200);
+  const fmt = formatCell(input.countryCode ?? '', input.cell ?? '');
+  if (fmt) return fmt.slice(0, 200);
+  return 'Untitled contact';
+}