create-nextblock 0.16.1 → 0.16.3

package/templates/nextblock-template/lib/config/email-tls.test.ts

@@ -1,57 +1,57 @@
-import { describe, expect, it } from 'vitest';
-
-import { reconcileTlsForPort } from './email-settings';
-
-/**
- * The TLS mode is a property of the SMTP port, not a preference — and getting it wrong
- * produces "ssl3_get_record:wrong version number", which mentions neither TLS nor ports.
- * A real install hit exactly that: SMTP2GO on 2525 with the toggle left at its default
- * of ON. These tests pin the reconciliation that makes the combination unreachable.
- */
-
-describe('reconcileTlsForPort', () => {
-  it('forces implicit TLS on 465 even when the setting says otherwise', () => {
-    const result = reconcileTlsForPort(465, false, 'smtp.example.com');
-    expect(result.secure).toBe(true);
-    expect(result.requireTLS).toBe(false);
-    expect(result.correctedFrom).toBe(false);
-  });
-
-  it('leaves a correct 465 configuration untouched', () => {
-    const result = reconcileTlsForPort(465, true, 'smtp.example.com');
-    expect(result.secure).toBe(true);
-    expect(result.correctedFrom).toBeUndefined();
-  });
-
-  it.each([25, 587, 2525])('forces STARTTLS on port %i', (port) => {
-    const result = reconcileTlsForPort(port, true, 'mail.smtp2go.com');
-    expect(result.secure).toBe(false);
-    // Downgrading to plaintext would be worse than the bug being fixed.
-    expect(result.requireTLS).toBe(true);
-    expect(result.correctedFrom).toBe(true);
-  });
-
-  it('reproduces the reported failure: SMTP2GO on 2525 with the toggle left on', () => {
-    const result = reconcileTlsForPort(2525, true, 'mail.smtp2go.com');
-    expect(result.secure).toBe(false);
-    expect(result.correctedFrom).toBe(true);
-  });
-
-  it('does not demand STARTTLS from a local test relay', () => {
-    for (const host of ['localhost', '127.0.0.1', '::1', 'LocalHost']) {
-      expect(reconcileTlsForPort(587, false, host).requireTLS).toBe(false);
-    }
-  });
-
-  it('honours the operator on a non-standard port, either way', () => {
-    expect(reconcileTlsForPort(1025, false, 'localhost')).toMatchObject({
-      secure: false,
-      requireTLS: false,
-    });
-    expect(reconcileTlsForPort(2526, true, 'smtp.example.com')).toMatchObject({
-      secure: true,
-      requireTLS: false,
-    });
-    expect(reconcileTlsForPort(2526, true, 'smtp.example.com').correctedFrom).toBeUndefined();
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { reconcileTlsForPort } from './email-settings';
+
+/**
+ * The TLS mode is a property of the SMTP port, not a preference — and getting it wrong
+ * produces "ssl3_get_record:wrong version number", which mentions neither TLS nor ports.
+ * A real install hit exactly that: SMTP2GO on 2525 with the toggle left at its default
+ * of ON. These tests pin the reconciliation that makes the combination unreachable.
+ */
+
+describe('reconcileTlsForPort', () => {
+  it('forces implicit TLS on 465 even when the setting says otherwise', () => {
+    const result = reconcileTlsForPort(465, false, 'smtp.example.com');
+    expect(result.secure).toBe(true);
+    expect(result.requireTLS).toBe(false);
+    expect(result.correctedFrom).toBe(false);
+  });
+
+  it('leaves a correct 465 configuration untouched', () => {
+    const result = reconcileTlsForPort(465, true, 'smtp.example.com');
+    expect(result.secure).toBe(true);
+    expect(result.correctedFrom).toBeUndefined();
+  });
+
+  it.each([25, 587, 2525])('forces STARTTLS on port %i', (port) => {
+    const result = reconcileTlsForPort(port, true, 'mail.smtp2go.com');
+    expect(result.secure).toBe(false);
+    // Downgrading to plaintext would be worse than the bug being fixed.
+    expect(result.requireTLS).toBe(true);
+    expect(result.correctedFrom).toBe(true);
+  });
+
+  it('reproduces the reported failure: SMTP2GO on 2525 with the toggle left on', () => {
+    const result = reconcileTlsForPort(2525, true, 'mail.smtp2go.com');
+    expect(result.secure).toBe(false);
+    expect(result.correctedFrom).toBe(true);
+  });
+
+  it('does not demand STARTTLS from a local test relay', () => {
+    for (const host of ['localhost', '127.0.0.1', '::1', 'LocalHost']) {
+      expect(reconcileTlsForPort(587, false, host).requireTLS).toBe(false);
+    }
+  });
+
+  it('honours the operator on a non-standard port, either way', () => {
+    expect(reconcileTlsForPort(1025, false, 'localhost')).toMatchObject({
+      secure: false,
+      requireTLS: false,
+    });
+    expect(reconcileTlsForPort(2526, true, 'smtp.example.com')).toMatchObject({
+      secure: true,
+      requireTLS: false,
+    });
+    expect(reconcileTlsForPort(2526, true, 'smtp.example.com').correctedFrom).toBeUndefined();
+  });
+});

package/templates/nextblock-template/lib/cortex-ai/alt-text-request.ts

@@ -1,86 +1,86 @@
-/**
- * Helpers for assembling a valid `POST /api/ai/seo/alt-text` body from what the CMS has
- * on hand. Both call sites — the image block editor and the media library edit form —
- * face the same two problems, so they are solved once here.
- */
-
-/**
- * Turn whatever the CMS has for an image into a URL the AI vision call can actually fetch.
- *
- * Why this is not just "pass the src along": `/api/ai/seo/alt-text` does not receive the
- * image bytes, it receives a URL, and the AI SDK downloads that URL *server-side* before
- * handing the image to the model. A relative path is meaningless in that context — there
- * is no document base to resolve it against — so the route rejects anything that is not
- * absolute http(s).
- *
- * And relative is the common case, not the exotic one. `resolveMediaUrl()` returns
- * `/${objectKey}` whenever `NEXT_PUBLIC_R2_BASE_URL` is unset, which is exactly how the
- * native Supabase-storage backend runs. So on a default install every single image in
- * the library would otherwise fail the alt-text call. Resolving against
- * `window.location.origin` fixes that for any deployment the browser can reach, which is
- * the same origin the server is serving from.
- *
- * The remaining failure the caller must surface rather than swallow is a `blob:` or
- * `data:` src (an un-uploaded local preview): the server cannot fetch either, so we
- * return null and let the UI say so instead of firing a request that is certain to 400.
- */
-export function toAbsoluteImageUrl(url: string | null | undefined): string | null {
-  const candidate = (url ?? '').trim();
-  if (!candidate) {
-    return null;
-  }
-
-  if (/^https?:\/\//i.test(candidate)) {
-    return candidate;
-  }
-
-  // Only the browser knows the origin this CMS is being served from; on the server we
-  // have no basis to invent one, so a relative path stays unusable and the caller warns.
-  if (typeof window === 'undefined') {
-    return null;
-  }
-
-  try {
-    const absolute = new URL(candidate, window.location.origin);
-    return absolute.protocol === 'http:' || absolute.protocol === 'https:'
-      ? absolute.toString()
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Shared copy for the inline warning shown when {@link toAbsoluteImageUrl} returns null. */
-export const UNRESOLVABLE_IMAGE_URL_MESSAGE =
-  'This image has no public http(s) address yet, so Cortex AI cannot look at it. Save it to the media library first.';
-
-/**
- * The route validates `context` with `z.string().max(2000)` inside a `z.strictObject`, so
- * an over-long value does not get trimmed server-side — it fails the whole request with a
- * 400. Captions are free-text inputs with no length limit of their own, which makes that
- * reachable: a long caption would break the alt-text button for reasons the operator could
- * never guess from the error. Trimming client-side keeps the request valid, and losing the
- * tail of a 2,000-character caption costs nothing, since context is a hint and the model
- * has the image itself.
- */
-const ALT_TEXT_CONTEXT_MAX_LENGTH = 2000;
-
-/**
- * Join the context fragments a caller has into one string the route will accept, or return
- * `undefined` when there is nothing worth sending — the field is optional, and an empty
- * string is a different (and less honest) thing to send than no field at all.
- */
-export function buildAltTextContext(...fragments: Array<string | null | undefined>): string | undefined {
-  const joined = fragments
-    .map((fragment) => (fragment ?? '').trim())
-    .filter(Boolean)
-    .join(' ');
-
-  if (!joined) {
-    return undefined;
-  }
-
-  return joined.length > ALT_TEXT_CONTEXT_MAX_LENGTH
-    ? joined.slice(0, ALT_TEXT_CONTEXT_MAX_LENGTH)
-    : joined;
-}
+/**
+ * Helpers for assembling a valid `POST /api/ai/seo/alt-text` body from what the CMS has
+ * on hand. Both call sites — the image block editor and the media library edit form —
+ * face the same two problems, so they are solved once here.
+ */
+
+/**
+ * Turn whatever the CMS has for an image into a URL the AI vision call can actually fetch.
+ *
+ * Why this is not just "pass the src along": `/api/ai/seo/alt-text` does not receive the
+ * image bytes, it receives a URL, and the AI SDK downloads that URL *server-side* before
+ * handing the image to the model. A relative path is meaningless in that context — there
+ * is no document base to resolve it against — so the route rejects anything that is not
+ * absolute http(s).
+ *
+ * And relative is the common case, not the exotic one. `resolveMediaUrl()` returns
+ * `/${objectKey}` whenever `NEXT_PUBLIC_R2_BASE_URL` is unset, which is exactly how the
+ * native Supabase-storage backend runs. So on a default install every single image in
+ * the library would otherwise fail the alt-text call. Resolving against
+ * `window.location.origin` fixes that for any deployment the browser can reach, which is
+ * the same origin the server is serving from.
+ *
+ * The remaining failure the caller must surface rather than swallow is a `blob:` or
+ * `data:` src (an un-uploaded local preview): the server cannot fetch either, so we
+ * return null and let the UI say so instead of firing a request that is certain to 400.
+ */
+export function toAbsoluteImageUrl(url: string | null | undefined): string | null {
+  const candidate = (url ?? '').trim();
+  if (!candidate) {
+    return null;
+  }
+
+  if (/^https?:\/\//i.test(candidate)) {
+    return candidate;
+  }
+
+  // Only the browser knows the origin this CMS is being served from; on the server we
+  // have no basis to invent one, so a relative path stays unusable and the caller warns.
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  try {
+    const absolute = new URL(candidate, window.location.origin);
+    return absolute.protocol === 'http:' || absolute.protocol === 'https:'
+      ? absolute.toString()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Shared copy for the inline warning shown when {@link toAbsoluteImageUrl} returns null. */
+export const UNRESOLVABLE_IMAGE_URL_MESSAGE =
+  'This image has no public http(s) address yet, so Cortex AI cannot look at it. Save it to the media library first.';
+
+/**
+ * The route validates `context` with `z.string().max(2000)` inside a `z.strictObject`, so
+ * an over-long value does not get trimmed server-side — it fails the whole request with a
+ * 400. Captions are free-text inputs with no length limit of their own, which makes that
+ * reachable: a long caption would break the alt-text button for reasons the operator could
+ * never guess from the error. Trimming client-side keeps the request valid, and losing the
+ * tail of a 2,000-character caption costs nothing, since context is a hint and the model
+ * has the image itself.
+ */
+const ALT_TEXT_CONTEXT_MAX_LENGTH = 2000;
+
+/**
+ * Join the context fragments a caller has into one string the route will accept, or return
+ * `undefined` when there is nothing worth sending — the field is optional, and an empty
+ * string is a different (and less honest) thing to send than no field at all.
+ */
+export function buildAltTextContext(...fragments: Array<string | null | undefined>): string | undefined {
+  const joined = fragments
+    .map((fragment) => (fragment ?? '').trim())
+    .filter(Boolean)
+    .join(' ');
+
+  if (!joined) {
+    return undefined;
+  }
+
+  return joined.length > ALT_TEXT_CONTEXT_MAX_LENGTH
+    ? joined.slice(0, ALT_TEXT_CONTEXT_MAX_LENGTH)
+    : joined;
+}

package/templates/nextblock-template/lib/cortex-ai/sandbox-headers.ts

@@ -1,60 +1,60 @@
-/**
- * Sandbox credential passthrough for browser-initiated Cortex AI requests.
- *
- * On the hosted sandbox there is no server-side OpenRouter key, because every visitor
- * shares one deployment and we will not spend the project's credits on strangers.
- * Instead each visitor pastes their own key into the Cortex AI settings screen, which
- * stores it in `localStorage`, and every AI call made from the browser forwards it on
- * the request as a header. The route only reads those headers when
- * `NEXT_PUBLIC_IS_SANDBOX === 'true'`, so on a real install the headers are ignored
- * even if something were to send them.
- *
- * This lived inline in `NotionEditor.handleAiGenerate` and was about to be copied into
- * three more call sites (image alt text, media alt text, page/post metadata). Copies
- * drift: the day a storage key or header name changes, the forgotten copy silently
- * stops authenticating and the sandbox user sees "no credentials" from one button and
- * not another. One exported builder keeps that impossible.
- */
-
-/** localStorage key holding the visitor's own OpenRouter API key on the sandbox. */
-export const CORTEX_AI_SANDBOX_API_KEY_STORAGE_KEY = 'cortex_ai_sandbox_openrouter_api_key';
-
-/** localStorage key holding the visitor's serialized model selection on the sandbox. */
-export const CORTEX_AI_SANDBOX_MODEL_STORAGE_KEY = 'cortex_ai_sandbox_openrouter_model_selection';
-
-/**
- * Builds the headers for a JSON POST to a Cortex AI route, adding the sandbox
- * credential headers when — and only when — this build is the sandbox and the visitor
- * has actually stored a key.
- *
- * `localStorage` access is wrapped in try/catch on purpose: a browser configured to
- * block site data throws on the *accessor itself*, not just on read, and an AI button
- * that explodes before it can send a request is a far worse failure than one that sends
- * an unauthenticated request and gets a clean 403 back.
- */
-export function buildCortexAiRequestHeaders(): Record<string, string> {
-  const headers: Record<string, string> = {
-    'content-type': 'application/json',
-  };
-
-  if (process.env.NEXT_PUBLIC_IS_SANDBOX !== 'true' || typeof window === 'undefined') {
-    return headers;
-  }
-
-  try {
-    const sandboxKey = window.localStorage.getItem(CORTEX_AI_SANDBOX_API_KEY_STORAGE_KEY);
-    const sandboxModel = window.localStorage.getItem(CORTEX_AI_SANDBOX_MODEL_STORAGE_KEY);
-
-    if (sandboxKey) {
-      headers['x-sandbox-openrouter-key'] = sandboxKey;
-    }
-    if (sandboxModel) {
-      headers['x-sandbox-openrouter-model'] = sandboxModel;
-    }
-  } catch {
-    // Storage is unavailable (private window, blocked site data). Fall through with the
-    // plain content-type header; the route will answer 403 and the caller will toast it.
-  }
-
-  return headers;
-}
+/**
+ * Sandbox credential passthrough for browser-initiated Cortex AI requests.
+ *
+ * On the hosted sandbox there is no server-side OpenRouter key, because every visitor
+ * shares one deployment and we will not spend the project's credits on strangers.
+ * Instead each visitor pastes their own key into the Cortex AI settings screen, which
+ * stores it in `localStorage`, and every AI call made from the browser forwards it on
+ * the request as a header. The route only reads those headers when
+ * `NEXT_PUBLIC_IS_SANDBOX === 'true'`, so on a real install the headers are ignored
+ * even if something were to send them.
+ *
+ * This lived inline in `NotionEditor.handleAiGenerate` and was about to be copied into
+ * three more call sites (image alt text, media alt text, page/post metadata). Copies
+ * drift: the day a storage key or header name changes, the forgotten copy silently
+ * stops authenticating and the sandbox user sees "no credentials" from one button and
+ * not another. One exported builder keeps that impossible.
+ */
+
+/** localStorage key holding the visitor's own OpenRouter API key on the sandbox. */
+export const CORTEX_AI_SANDBOX_API_KEY_STORAGE_KEY = 'cortex_ai_sandbox_openrouter_api_key';
+
+/** localStorage key holding the visitor's serialized model selection on the sandbox. */
+export const CORTEX_AI_SANDBOX_MODEL_STORAGE_KEY = 'cortex_ai_sandbox_openrouter_model_selection';
+
+/**
+ * Builds the headers for a JSON POST to a Cortex AI route, adding the sandbox
+ * credential headers when — and only when — this build is the sandbox and the visitor
+ * has actually stored a key.
+ *
+ * `localStorage` access is wrapped in try/catch on purpose: a browser configured to
+ * block site data throws on the *accessor itself*, not just on read, and an AI button
+ * that explodes before it can send a request is a far worse failure than one that sends
+ * an unauthenticated request and gets a clean 403 back.
+ */
+export function buildCortexAiRequestHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+  };
+
+  if (process.env.NEXT_PUBLIC_IS_SANDBOX !== 'true' || typeof window === 'undefined') {
+    return headers;
+  }
+
+  try {
+    const sandboxKey = window.localStorage.getItem(CORTEX_AI_SANDBOX_API_KEY_STORAGE_KEY);
+    const sandboxModel = window.localStorage.getItem(CORTEX_AI_SANDBOX_MODEL_STORAGE_KEY);
+
+    if (sandboxKey) {
+      headers['x-sandbox-openrouter-key'] = sandboxKey;
+    }
+    if (sandboxModel) {
+      headers['x-sandbox-openrouter-model'] = sandboxModel;
+    }
+  } catch {
+    // Storage is unavailable (private window, blocked site data). Fall through with the
+    // plain content-type header; the route will answer 403 and the caller will toast it.
+  }
+
+  return headers;
+}

package/templates/nextblock-template/lib/email/placeholder-address.test.ts

@@ -1,59 +1,59 @@
-import { describe, expect, it } from 'vitest';
-
-import { isPlaceholderEmail, usableEmail } from './placeholder-address';
-
-/**
- * The starter content ships a contact page addressed to `contact@example.com`, and an
- * install ran that way without knowing: the visitor was thanked, the relay accepted the
- * message, and it went to a domain RFC 2606 reserves so it can never exist. No error
- * anywhere. Treating these as unset is what lets the recipient ladder reach something
- * real — and lets the CMS say so.
- */
-
-describe('isPlaceholderEmail', () => {
-  it.each([
-    'contact@example.com',
-    'CONTACT@EXAMPLE.COM',
-    '  hello@example.com  ',
-    'privacy@example.org',
-    'support@example.net',
-    'someone@example.edu',
-    'a@host.example',
-    'a@something.invalid',
-    'a@my.test',
-    'a@dev.localhost',
-    'a@printer.local',
-  ])('treats %s as a placeholder', (email) => {
-    expect(isPlaceholderEmail(email)).toBe(true);
-    expect(usableEmail(email)).toBeNull();
-  });
-
-  it.each([
-    'hosts@newrootsherbal.com',
-    'sales@nextblock.dev',
-    // A real domain that merely contains the word, and a real TLD lookalike.
-    'hi@example-company.com',
-    'hi@myexample.com',
-    'hi@shop.exampleshop.co.uk',
-  ])('leaves the real address %s alone', (email) => {
-    expect(isPlaceholderEmail(email)).toBe(false);
-    expect(usableEmail(email)).toBe(email);
-  });
-
-  it('does not treat an empty or malformed value as a placeholder', () => {
-    // Empty means "unset", which callers already handle; malformed is not our call.
-    for (const value of ['', '   ', null, undefined, 'not-an-email']) {
-      expect(isPlaceholderEmail(value)).toBe(false);
-    }
-  });
-
-  it('reports an empty value as unusable without calling it a placeholder', () => {
-    expect(usableEmail('')).toBeNull();
-    expect(usableEmail(null)).toBeNull();
-    expect(usableEmail('  ')).toBeNull();
-  });
-
-  it('trims a usable address rather than returning it padded', () => {
-    expect(usableEmail('  sales@nextblock.dev ')).toBe('sales@nextblock.dev');
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { isPlaceholderEmail, usableEmail } from './placeholder-address';
+
+/**
+ * The starter content ships a contact page addressed to `contact@example.com`, and an
+ * install ran that way without knowing: the visitor was thanked, the relay accepted the
+ * message, and it went to a domain RFC 2606 reserves so it can never exist. No error
+ * anywhere. Treating these as unset is what lets the recipient ladder reach something
+ * real — and lets the CMS say so.
+ */
+
+describe('isPlaceholderEmail', () => {
+  it.each([
+    'contact@example.com',
+    'CONTACT@EXAMPLE.COM',
+    '  hello@example.com  ',
+    'privacy@example.org',
+    'support@example.net',
+    'someone@example.edu',
+    'a@host.example',
+    'a@something.invalid',
+    'a@my.test',
+    'a@dev.localhost',
+    'a@printer.local',
+  ])('treats %s as a placeholder', (email) => {
+    expect(isPlaceholderEmail(email)).toBe(true);
+    expect(usableEmail(email)).toBeNull();
+  });
+
+  it.each([
+    'hosts@newrootsherbal.com',
+    'sales@nextblock.dev',
+    // A real domain that merely contains the word, and a real TLD lookalike.
+    'hi@example-company.com',
+    'hi@myexample.com',
+    'hi@shop.exampleshop.co.uk',
+  ])('leaves the real address %s alone', (email) => {
+    expect(isPlaceholderEmail(email)).toBe(false);
+    expect(usableEmail(email)).toBe(email);
+  });
+
+  it('does not treat an empty or malformed value as a placeholder', () => {
+    // Empty means "unset", which callers already handle; malformed is not our call.
+    for (const value of ['', '   ', null, undefined, 'not-an-email']) {
+      expect(isPlaceholderEmail(value)).toBe(false);
+    }
+  });
+
+  it('reports an empty value as unusable without calling it a placeholder', () => {
+    expect(usableEmail('')).toBeNull();
+    expect(usableEmail(null)).toBeNull();
+    expect(usableEmail('  ')).toBeNull();
+  });
+
+  it('trims a usable address rather than returning it padded', () => {
+    expect(usableEmail('  sales@nextblock.dev ')).toBe('sales@nextblock.dev');
+  });
+});

package/templates/nextblock-template/lib/email/placeholder-address.ts

@@ -1,39 +1,39 @@
-/**
- * Addresses that look configured but can never receive mail.
- *
- * Seed data has to put *something* in a contact field, and `contact@example.com` is the
- * conventional choice. The trouble is that it is indistinguishable from a real setting to
- * every code path downstream: the form reports success, the transport accepts the
- * message, and it is delivered nowhere. An operator can run that way for months without
- * a single error to notice.
- *
- * The domains here are reserved by RFC 2606 and RFC 6761 precisely so they can never be
- * registered, which is what makes this a safe judgement rather than a guess: nothing at
- * `example.com` is ever a real inbox. Treating them as unset lets the recipient ladder
- * fall through to something that works, and lets the CMS say so out loud.
- *
- * Deliberately dependency-free so both server modules and the CMS can use it.
- */
-
-const RESERVED_DOMAINS = new Set(['example.com', 'example.org', 'example.net', 'example.edu']);
-const RESERVED_TLDS = ['.example', '.invalid', '.test', '.localhost', '.local'];
-
-export function isPlaceholderEmail(value: string | null | undefined): boolean {
-  const email = value?.trim().toLowerCase() ?? '';
-  if (!email) return false;
-
-  const at = email.lastIndexOf('@');
-  if (at === -1) return false;
-
-  const domain = email.slice(at + 1);
-  if (!domain) return false;
-
-  return RESERVED_DOMAINS.has(domain) || RESERVED_TLDS.some((tld) => domain.endsWith(tld));
-}
-
-/** The address if it could actually receive mail, otherwise null. */
-export function usableEmail(value: string | null | undefined): string | null {
-  const email = value?.trim() ?? '';
-  if (!email || isPlaceholderEmail(email)) return null;
-  return email;
-}
+/**
+ * Addresses that look configured but can never receive mail.
+ *
+ * Seed data has to put *something* in a contact field, and `contact@example.com` is the
+ * conventional choice. The trouble is that it is indistinguishable from a real setting to
+ * every code path downstream: the form reports success, the transport accepts the
+ * message, and it is delivered nowhere. An operator can run that way for months without
+ * a single error to notice.
+ *
+ * The domains here are reserved by RFC 2606 and RFC 6761 precisely so they can never be
+ * registered, which is what makes this a safe judgement rather than a guess: nothing at
+ * `example.com` is ever a real inbox. Treating them as unset lets the recipient ladder
+ * fall through to something that works, and lets the CMS say so out loud.
+ *
+ * Deliberately dependency-free so both server modules and the CMS can use it.
+ */
+
+const RESERVED_DOMAINS = new Set(['example.com', 'example.org', 'example.net', 'example.edu']);
+const RESERVED_TLDS = ['.example', '.invalid', '.test', '.localhost', '.local'];
+
+export function isPlaceholderEmail(value: string | null | undefined): boolean {
+  const email = value?.trim().toLowerCase() ?? '';
+  if (!email) return false;
+
+  const at = email.lastIndexOf('@');
+  if (at === -1) return false;
+
+  const domain = email.slice(at + 1);
+  if (!domain) return false;
+
+  return RESERVED_DOMAINS.has(domain) || RESERVED_TLDS.some((tld) => domain.endsWith(tld));
+}
+
+/** The address if it could actually receive mail, otherwise null. */
+export function usableEmail(value: string | null | undefined): string | null {
+  const email = value?.trim() ?? '';
+  if (!email || isPlaceholderEmail(email)) return null;
+  return email;
+}