create-nextblock 0.16.1 → 0.16.2

package/templates/nextblock-template/lib/site-scripts/revisions.ts

@@ -1,71 +1,71 @@
-import type { SiteScript } from './types';
-
-export type SiteScriptRevisionType = 'create' | 'update' | 'delete' | 'revert';
-export type SiteScriptRevisionSource = 'cms' | 'mcp';
-
-export interface SiteScriptRevision {
-  id: string;
-  script_id: string | null;
-  script_name: string;
-  revision_type: SiteScriptRevisionType;
-  actor_user_id: string | null;
-  source: SiteScriptRevisionSource;
-  summary: string | null;
-  snapshot: SiteScriptSnapshot;
-  created_at: string;
-}
-
-/**
- * The restorable state of a script.
- *
- * Deliberately excludes `id`, `created_at`, and `updated_at`: restoring a revision
- * writes these fields onto the live row (or recreates it), and carrying identity or
- * timestamps across would either clash with the existing row or fake its history.
- */
-export interface SiteScriptSnapshot {
-  name: string;
-  description: string | null;
-  code: string;
-  src: string | null;
-  placement: string;
-  load_strategy: string;
-  is_active: boolean;
-  sort_order: number;
-}
-
-export const SITE_SCRIPT_REVISION_COLUMNS =
-  'id, script_id, script_name, revision_type, actor_user_id, source, summary, snapshot, created_at';
-
-/** Normalise a script row, a partial payload, or an existing snapshot into a snapshot. */
-export function buildSiteScriptSnapshot(
-  row: Partial<SiteScript> | SiteScriptSnapshot | Record<string, unknown>
-): SiteScriptSnapshot {
-  const value = row as Record<string, unknown>;
-
-  return {
-    code: typeof value['code'] === 'string' ? value['code'] : '',
-    description: typeof value['description'] === 'string' ? value['description'] : null,
-    is_active: Boolean(value['is_active']),
-    load_strategy: typeof value['load_strategy'] === 'string' ? value['load_strategy'] : 'default',
-    name: typeof value['name'] === 'string' ? value['name'] : '',
-    placement: typeof value['placement'] === 'string' ? value['placement'] : 'body_end',
-    sort_order: Number.isFinite(value['sort_order']) ? Number(value['sort_order']) : 0,
-    src: typeof value['src'] === 'string' && value['src'] ? (value['src'] as string) : null,
-  };
-}
-
-/** One-line human description of what a revision did, shown in the history list. */
-export function describeSiteScriptRevision(revision: SiteScriptRevision): string {
-  if (revision.summary) return revision.summary;
-
-  switch (revision.revision_type) {
-    case 'create':
-      return `Created “${revision.script_name}”`;
-    case 'delete':
-      return `Deleted “${revision.script_name}”`;
-    case 'revert':
-      return `Restored “${revision.script_name}”`;
-    default:
-      return `Updated “${revision.script_name}”`;
-  }
-}
+import type { SiteScript } from './types';
+
+export type SiteScriptRevisionType = 'create' | 'update' | 'delete' | 'revert';
+export type SiteScriptRevisionSource = 'cms' | 'mcp';
+
+export interface SiteScriptRevision {
+  id: string;
+  script_id: string | null;
+  script_name: string;
+  revision_type: SiteScriptRevisionType;
+  actor_user_id: string | null;
+  source: SiteScriptRevisionSource;
+  summary: string | null;
+  snapshot: SiteScriptSnapshot;
+  created_at: string;
+}
+
+/**
+ * The restorable state of a script.
+ *
+ * Deliberately excludes `id`, `created_at`, and `updated_at`: restoring a revision
+ * writes these fields onto the live row (or recreates it), and carrying identity or
+ * timestamps across would either clash with the existing row or fake its history.
+ */
+export interface SiteScriptSnapshot {
+  name: string;
+  description: string | null;
+  code: string;
+  src: string | null;
+  placement: string;
+  load_strategy: string;
+  is_active: boolean;
+  sort_order: number;
+}
+
+export const SITE_SCRIPT_REVISION_COLUMNS =
+  'id, script_id, script_name, revision_type, actor_user_id, source, summary, snapshot, created_at';
+
+/** Normalise a script row, a partial payload, or an existing snapshot into a snapshot. */
+export function buildSiteScriptSnapshot(
+  row: Partial<SiteScript> | SiteScriptSnapshot | Record<string, unknown>
+): SiteScriptSnapshot {
+  const value = row as Record<string, unknown>;
+
+  return {
+    code: typeof value['code'] === 'string' ? value['code'] : '',
+    description: typeof value['description'] === 'string' ? value['description'] : null,
+    is_active: Boolean(value['is_active']),
+    load_strategy: typeof value['load_strategy'] === 'string' ? value['load_strategy'] : 'default',
+    name: typeof value['name'] === 'string' ? value['name'] : '',
+    placement: typeof value['placement'] === 'string' ? value['placement'] : 'body_end',
+    sort_order: Number.isFinite(value['sort_order']) ? Number(value['sort_order']) : 0,
+    src: typeof value['src'] === 'string' && value['src'] ? (value['src'] as string) : null,
+  };
+}
+
+/** One-line human description of what a revision did, shown in the history list. */
+export function describeSiteScriptRevision(revision: SiteScriptRevision): string {
+  if (revision.summary) return revision.summary;
+
+  switch (revision.revision_type) {
+    case 'create':
+      return `Created “${revision.script_name}”`;
+    case 'delete':
+      return `Deleted “${revision.script_name}”`;
+    case 'revert':
+      return `Restored “${revision.script_name}”`;
+    default:
+      return `Updated “${revision.script_name}”`;
+  }
+}

package/templates/nextblock-template/lib/site-scripts/types.ts

@@ -1,46 +1,46 @@
-/** Where a site script's tag is emitted in the document. */
-export type SiteScriptPlacement = 'head' | 'body_start' | 'body_end';
-
-/** Loading hint for external (`src`) scripts. Inline code ignores it. */
-export type SiteScriptLoadStrategy = 'default' | 'defer' | 'async';
-
-export interface SiteScript {
-  id: string;
-  name: string;
-  description: string | null;
-  /** Raw JS without the surrounding <script> tag. Ignored when `src` is set. */
-  code: string;
-  /** External script URL. Takes precedence over `code`. */
-  src: string | null;
-  placement: SiteScriptPlacement;
-  load_strategy: SiteScriptLoadStrategy;
-  is_active: boolean;
-  sort_order: number;
-}
-
-export const SITE_SCRIPT_PLACEMENTS: SiteScriptPlacement[] = ['head', 'body_start', 'body_end'];
-export const SITE_SCRIPT_LOAD_STRATEGIES: SiteScriptLoadStrategy[] = ['default', 'defer', 'async'];
-
-export const SITE_SCRIPT_COLUMNS =
-  'id, name, description, code, src, placement, load_strategy, is_active, sort_order';
-
-export function isSiteScriptPlacement(value: unknown): value is SiteScriptPlacement {
-  return typeof value === 'string' && (SITE_SCRIPT_PLACEMENTS as string[]).includes(value);
-}
-
-export function isSiteScriptLoadStrategy(value: unknown): value is SiteScriptLoadStrategy {
-  return typeof value === 'string' && (SITE_SCRIPT_LOAD_STRATEGIES as string[]).includes(value);
-}
-
-/**
- * Guard against a script closing its own tag and escaping into markup.
- *
- * The code is emitted inside a <script> element, where the HTML parser ends the
- * element at the first literal `</script`, regardless of JavaScript syntax — so a
- * string containing it would terminate the script early and let whatever follows be
- * parsed as HTML. Escaping the slash keeps the sequence inert to the parser while
- * remaining the same string to JavaScript.
- */
-export function escapeInlineScript(code: string): string {
-  return code.replace(/<\/(script)/gi, '<\\/$1');
-}
+/** Where a site script's tag is emitted in the document. */
+export type SiteScriptPlacement = 'head' | 'body_start' | 'body_end';
+
+/** Loading hint for external (`src`) scripts. Inline code ignores it. */
+export type SiteScriptLoadStrategy = 'default' | 'defer' | 'async';
+
+export interface SiteScript {
+  id: string;
+  name: string;
+  description: string | null;
+  /** Raw JS without the surrounding <script> tag. Ignored when `src` is set. */
+  code: string;
+  /** External script URL. Takes precedence over `code`. */
+  src: string | null;
+  placement: SiteScriptPlacement;
+  load_strategy: SiteScriptLoadStrategy;
+  is_active: boolean;
+  sort_order: number;
+}
+
+export const SITE_SCRIPT_PLACEMENTS: SiteScriptPlacement[] = ['head', 'body_start', 'body_end'];
+export const SITE_SCRIPT_LOAD_STRATEGIES: SiteScriptLoadStrategy[] = ['default', 'defer', 'async'];
+
+export const SITE_SCRIPT_COLUMNS =
+  'id, name, description, code, src, placement, load_strategy, is_active, sort_order';
+
+export function isSiteScriptPlacement(value: unknown): value is SiteScriptPlacement {
+  return typeof value === 'string' && (SITE_SCRIPT_PLACEMENTS as string[]).includes(value);
+}
+
+export function isSiteScriptLoadStrategy(value: unknown): value is SiteScriptLoadStrategy {
+  return typeof value === 'string' && (SITE_SCRIPT_LOAD_STRATEGIES as string[]).includes(value);
+}
+
+/**
+ * Guard against a script closing its own tag and escaping into markup.
+ *
+ * The code is emitted inside a <script> element, where the HTML parser ends the
+ * element at the first literal `</script`, regardless of JavaScript syntax — so a
+ * string containing it would terminate the script early and let whatever follows be
+ * parsed as HTML. Escaping the slash keeps the sequence inert to the parser while
+ * remaining the same string to JavaScript.
+ */
+export function escapeInlineScript(code: string): string {
+  return code.replace(/<\/(script)/gi, '<\\/$1');
+}

package/templates/nextblock-template/lib/site-url.test.ts

@@ -1,89 +1,89 @@
-import { afterEach, describe, expect, it } from 'vitest';
-
-import { hasExplicitSiteUrl, isPubliclyRoutableSiteUrl } from './site-url';
-
-/**
- * A real send looked successful end to end — SMTP2GO accepted it, Microsoft returned
- * "250 Queued mail for delivery" — and the message still never arrived. The cause was
- * the link inside it: `resolveSiteUrl()` falls back to http://localhost:3000 when
- * nothing is configured, so the reply carried a dead button under a "Re:" subject, which
- * reads as phishing and gets quarantined without a bounce.
- *
- * Anything that mails a link has to ask this question first.
- */
-
-describe('isPubliclyRoutableSiteUrl', () => {
-  it.each([
-    'http://localhost:3000',
-    'http://localhost:4200',
-    'https://localhost',
-    'http://127.0.0.1:3000',
-    'http://[::1]:3000',
-    'http://0.0.0.0:8080',
-    'http://mymachine.local',
-    'http://site.localhost:3000',
-  ])('rejects the loopback address %s', (url) => {
-    expect(isPubliclyRoutableSiteUrl(url)).toBe(false);
-  });
-
-  it.each([
-    'http://10.0.0.5:3000',
-    'http://192.168.1.20',
-    'http://172.16.0.9',
-    'http://172.31.255.254',
-    'http://169.254.10.1',
-  ])('rejects the private-network address %s', (url) => {
-    expect(isPubliclyRoutableSiteUrl(url)).toBe(false);
-  });
-
-  it('rejects a bare hostname that only resolves on the local network', () => {
-    expect(isPubliclyRoutableSiteUrl('http://intranet')).toBe(false);
-  });
-
-  it('rejects anything that is not a URL at all', () => {
-    expect(isPubliclyRoutableSiteUrl('')).toBe(false);
-    expect(isPubliclyRoutableSiteUrl('not a url')).toBe(false);
-    expect(isPubliclyRoutableSiteUrl('ftp://example.com')).toBe(false);
-  });
-
-  it.each([
-    'https://nextblock.dev',
-    'https://www.newrootsherbal.com',
-    'https://shop.example.co.uk',
-    'https://my-app.vercel.app',
-    // 172.32 is outside the RFC1918 block, so it is a public address.
-    'http://172.32.0.1',
-  ])('accepts the publicly reachable address %s', (url) => {
-    expect(isPubliclyRoutableSiteUrl(url)).toBe(true);
-  });
-});
-
-describe('hasExplicitSiteUrl', () => {
-  const original = process.env.NEXT_PUBLIC_URL;
-  afterEach(() => {
-    if (original === undefined) delete process.env.NEXT_PUBLIC_URL;
-    else process.env.NEXT_PUBLIC_URL = original;
-  });
-
-  it('is false when nothing is configured, which is the case that must be refused', () => {
-    delete process.env.NEXT_PUBLIC_URL;
-    expect(hasExplicitSiteUrl()).toBe(false);
-  });
-
-  it('is true for a deliberately local address — testing on your own machine is valid', () => {
-    process.env.NEXT_PUBLIC_URL = 'http://localhost:3000';
-    expect(hasExplicitSiteUrl()).toBe(true);
-    // Still not routable: the send is allowed, but the log says who can open it.
-    expect(isPubliclyRoutableSiteUrl('http://localhost:3000')).toBe(false);
-  });
-
-  it('is true for a real public URL', () => {
-    process.env.NEXT_PUBLIC_URL = 'https://nextblock.dev';
-    expect(hasExplicitSiteUrl()).toBe(true);
-  });
-
-  it('treats whitespace as unset rather than as a choice', () => {
-    process.env.NEXT_PUBLIC_URL = '   ';
-    expect(hasExplicitSiteUrl()).toBe(false);
-  });
-});
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { hasExplicitSiteUrl, isPubliclyRoutableSiteUrl } from './site-url';
+
+/**
+ * A real send looked successful end to end — SMTP2GO accepted it, Microsoft returned
+ * "250 Queued mail for delivery" — and the message still never arrived. The cause was
+ * the link inside it: `resolveSiteUrl()` falls back to http://localhost:3000 when
+ * nothing is configured, so the reply carried a dead button under a "Re:" subject, which
+ * reads as phishing and gets quarantined without a bounce.
+ *
+ * Anything that mails a link has to ask this question first.
+ */
+
+describe('isPubliclyRoutableSiteUrl', () => {
+  it.each([
+    'http://localhost:3000',
+    'http://localhost:4200',
+    'https://localhost',
+    'http://127.0.0.1:3000',
+    'http://[::1]:3000',
+    'http://0.0.0.0:8080',
+    'http://mymachine.local',
+    'http://site.localhost:3000',
+  ])('rejects the loopback address %s', (url) => {
+    expect(isPubliclyRoutableSiteUrl(url)).toBe(false);
+  });
+
+  it.each([
+    'http://10.0.0.5:3000',
+    'http://192.168.1.20',
+    'http://172.16.0.9',
+    'http://172.31.255.254',
+    'http://169.254.10.1',
+  ])('rejects the private-network address %s', (url) => {
+    expect(isPubliclyRoutableSiteUrl(url)).toBe(false);
+  });
+
+  it('rejects a bare hostname that only resolves on the local network', () => {
+    expect(isPubliclyRoutableSiteUrl('http://intranet')).toBe(false);
+  });
+
+  it('rejects anything that is not a URL at all', () => {
+    expect(isPubliclyRoutableSiteUrl('')).toBe(false);
+    expect(isPubliclyRoutableSiteUrl('not a url')).toBe(false);
+    expect(isPubliclyRoutableSiteUrl('ftp://example.com')).toBe(false);
+  });
+
+  it.each([
+    'https://nextblock.dev',
+    'https://www.newrootsherbal.com',
+    'https://shop.example.co.uk',
+    'https://my-app.vercel.app',
+    // 172.32 is outside the RFC1918 block, so it is a public address.
+    'http://172.32.0.1',
+  ])('accepts the publicly reachable address %s', (url) => {
+    expect(isPubliclyRoutableSiteUrl(url)).toBe(true);
+  });
+});
+
+describe('hasExplicitSiteUrl', () => {
+  const original = process.env.NEXT_PUBLIC_URL;
+  afterEach(() => {
+    if (original === undefined) delete process.env.NEXT_PUBLIC_URL;
+    else process.env.NEXT_PUBLIC_URL = original;
+  });
+
+  it('is false when nothing is configured, which is the case that must be refused', () => {
+    delete process.env.NEXT_PUBLIC_URL;
+    expect(hasExplicitSiteUrl()).toBe(false);
+  });
+
+  it('is true for a deliberately local address — testing on your own machine is valid', () => {
+    process.env.NEXT_PUBLIC_URL = 'http://localhost:3000';
+    expect(hasExplicitSiteUrl()).toBe(true);
+    // Still not routable: the send is allowed, but the log says who can open it.
+    expect(isPubliclyRoutableSiteUrl('http://localhost:3000')).toBe(false);
+  });
+
+  it('is true for a real public URL', () => {
+    process.env.NEXT_PUBLIC_URL = 'https://nextblock.dev';
+    expect(hasExplicitSiteUrl()).toBe(true);
+  });
+
+  it('treats whitespace as unset rather than as a choice', () => {
+    process.env.NEXT_PUBLIC_URL = '   ';
+    expect(hasExplicitSiteUrl()).toBe(false);
+  });
+});

package/templates/nextblock-template/lib/site-url.ts

@@ -1,102 +1,102 @@
-// Resolve the canonical public site URL across deploy channels WITHOUT requiring
-// NEXT_PUBLIC_URL to be set. On Vercel it falls back to the auto-provisioned
-// production URL, so a one-click deploy needs no URL input at all.
-//
-// Dependency-free and safe to import anywhere — server components, route handlers,
-// or client components — like lib/setup/env-status.ts. It only reads `process.env`:
-// NEXT_PUBLIC_* names are inlined into the browser bundle at build time, the others
-// resolve server-side only (and are simply absent — harmless — in the browser).
-
-const stripTrailingSlash = (value: string): string => value.replace(/\/+$/, '');
-
-/**
- * Vercel always sets a production domain (even on preview deployments):
- * `VERCEL_PROJECT_PRODUCTION_URL` server-side, and Vercel exposes the
- * framework-prefixed `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` to the browser
- * bundle at build time. Neither includes the protocol. We prefer the production URL
- * over the per-deployment `VERCEL_URL` so absolute links (sitemap, canonical, OG)
- * stay stable across deploys.
- */
-function vercelProductionUrl(): string {
-  const host =
-    process.env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL?.trim() ||
-    process.env.VERCEL_PROJECT_PRODUCTION_URL?.trim();
-  return host ? `https://${stripTrailingSlash(host)}` : '';
-}
-
-/**
- * Canonical absolute site origin (e.g. `https://example.com`), no trailing slash.
- * Precedence: explicit `NEXT_PUBLIC_URL` → Vercel production URL → `fallback`.
- */
-export function resolveSiteUrl(fallback = 'http://localhost:3000'): string {
-  const explicit = process.env.NEXT_PUBLIC_URL?.trim();
-  if (explicit) return stripTrailingSlash(explicit);
-
-  const vercel = vercelProductionUrl();
-  if (vercel) return vercel;
-
-  return stripTrailingSlash(fallback);
-}
-
-/**
- * True when a real, production-intended site URL is available (an explicit
- * `NEXT_PUBLIC_URL` or the Vercel production URL) — i.e. {@link resolveSiteUrl}
- * is NOT returning the local-dev fallback. Use this to gate "URL not set" warnings.
- */
-export function hasResolvedSiteUrl(): boolean {
-  return Boolean(process.env.NEXT_PUBLIC_URL?.trim() || vercelProductionUrl());
-}
-
-/**
- * Whether the resolved site URL is one a stranger could actually open.
- *
- * `resolveSiteUrl()` falls back to http://localhost:3000 when nothing is configured,
- * which is correct for rendering local links but catastrophic in an email: the
- * recipient gets a dead button, and — because a non-routable host under a plain http
- * scheme alongside a long opaque token reads exactly like phishing — the message is
- * likely to be quarantined before they even see it. Anything that mails a link out
- * must check this first.
- */
-export function isPubliclyRoutableSiteUrl(url: string = resolveSiteUrl()): boolean {
-  try {
-    const parsed = new URL(url);
-    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return false;
-
-    const host = parsed.hostname.toLowerCase();
-    if (
-      host === 'localhost' ||
-      host === '127.0.0.1' ||
-      host === '::1' ||
-      host === '0.0.0.0' ||
-      host.endsWith('.local') ||
-      host.endsWith('.localhost') ||
-      // RFC1918 / link-local: reachable on someone's LAN, never from an inbox.
-      /^10\./.test(host) ||
-      /^192\.168\./.test(host) ||
-      /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
-      /^169\.254\./.test(host)
-    ) {
-      return false;
-    }
-
-    // A bare hostname with no dot cannot be resolved from outside this network.
-    return host.includes('.');
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Whether the site URL was actually chosen by the operator, rather than invented.
- *
- * This is the distinction that matters before mailing a link. A `localhost` URL is
- * perfectly workable when the person reading the mail is on the machine running the
- * server — that is an ordinary way to test. What is not workable is `resolveSiteUrl()`
- * quietly inventing `http://localhost:3000` because nothing was configured, and a link
- * to it going out to a real customer.
- *
- * So: honour an explicit choice, refuse an accidental default.
- */
-export function hasExplicitSiteUrl(): boolean {
-  return Boolean(process.env.NEXT_PUBLIC_URL?.trim() || vercelProductionUrl());
-}
+// Resolve the canonical public site URL across deploy channels WITHOUT requiring
+// NEXT_PUBLIC_URL to be set. On Vercel it falls back to the auto-provisioned
+// production URL, so a one-click deploy needs no URL input at all.
+//
+// Dependency-free and safe to import anywhere — server components, route handlers,
+// or client components — like lib/setup/env-status.ts. It only reads `process.env`:
+// NEXT_PUBLIC_* names are inlined into the browser bundle at build time, the others
+// resolve server-side only (and are simply absent — harmless — in the browser).
+
+const stripTrailingSlash = (value: string): string => value.replace(/\/+$/, '');
+
+/**
+ * Vercel always sets a production domain (even on preview deployments):
+ * `VERCEL_PROJECT_PRODUCTION_URL` server-side, and Vercel exposes the
+ * framework-prefixed `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` to the browser
+ * bundle at build time. Neither includes the protocol. We prefer the production URL
+ * over the per-deployment `VERCEL_URL` so absolute links (sitemap, canonical, OG)
+ * stay stable across deploys.
+ */
+function vercelProductionUrl(): string {
+  const host =
+    process.env.NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL?.trim() ||
+    process.env.VERCEL_PROJECT_PRODUCTION_URL?.trim();
+  return host ? `https://${stripTrailingSlash(host)}` : '';
+}
+
+/**
+ * Canonical absolute site origin (e.g. `https://example.com`), no trailing slash.
+ * Precedence: explicit `NEXT_PUBLIC_URL` → Vercel production URL → `fallback`.
+ */
+export function resolveSiteUrl(fallback = 'http://localhost:3000'): string {
+  const explicit = process.env.NEXT_PUBLIC_URL?.trim();
+  if (explicit) return stripTrailingSlash(explicit);
+
+  const vercel = vercelProductionUrl();
+  if (vercel) return vercel;
+
+  return stripTrailingSlash(fallback);
+}
+
+/**
+ * True when a real, production-intended site URL is available (an explicit
+ * `NEXT_PUBLIC_URL` or the Vercel production URL) — i.e. {@link resolveSiteUrl}
+ * is NOT returning the local-dev fallback. Use this to gate "URL not set" warnings.
+ */
+export function hasResolvedSiteUrl(): boolean {
+  return Boolean(process.env.NEXT_PUBLIC_URL?.trim() || vercelProductionUrl());
+}
+
+/**
+ * Whether the resolved site URL is one a stranger could actually open.
+ *
+ * `resolveSiteUrl()` falls back to http://localhost:3000 when nothing is configured,
+ * which is correct for rendering local links but catastrophic in an email: the
+ * recipient gets a dead button, and — because a non-routable host under a plain http
+ * scheme alongside a long opaque token reads exactly like phishing — the message is
+ * likely to be quarantined before they even see it. Anything that mails a link out
+ * must check this first.
+ */
+export function isPubliclyRoutableSiteUrl(url: string = resolveSiteUrl()): boolean {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return false;
+
+    const host = parsed.hostname.toLowerCase();
+    if (
+      host === 'localhost' ||
+      host === '127.0.0.1' ||
+      host === '::1' ||
+      host === '0.0.0.0' ||
+      host.endsWith('.local') ||
+      host.endsWith('.localhost') ||
+      // RFC1918 / link-local: reachable on someone's LAN, never from an inbox.
+      /^10\./.test(host) ||
+      /^192\.168\./.test(host) ||
+      /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+      /^169\.254\./.test(host)
+    ) {
+      return false;
+    }
+
+    // A bare hostname with no dot cannot be resolved from outside this network.
+    return host.includes('.');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the site URL was actually chosen by the operator, rather than invented.
+ *
+ * This is the distinction that matters before mailing a link. A `localhost` URL is
+ * perfectly workable when the person reading the mail is on the machine running the
+ * server — that is an ordinary way to test. What is not workable is `resolveSiteUrl()`
+ * quietly inventing `http://localhost:3000` because nothing was configured, and a link
+ * to it going out to a real customer.
+ *
+ * So: honour an explicit choice, refuse an accidental default.
+ */
+export function hasExplicitSiteUrl(): boolean {
+  return Boolean(process.env.NEXT_PUBLIC_URL?.trim() || vercelProductionUrl());
+}