create-nextblock 0.15.10 → 0.16.2

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

@@ -0,0 +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;
+}

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

@@ -0,0 +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;
+}

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;
+}

package/templates/nextblock-template/lib/messages/thread-reference.test.ts

@@ -1,70 +1,70 @@
-import { describe, expect, it } from 'vitest';
-
-import { threadReference } from './threads';
-
-/**
- * A real install stopped receiving replies and nothing reported a fault: SMTP accepted
- * every message, Outlook accepted every message, and they went straight to Deleted Items.
- * The cause was the subject. Every conversation from one form produced a byte-identical
- * "Re: Contact form"; Exchange derives its ConversationTopic from the subject rather than
- * from References, so an Ignore Conversation applied once applied to every enquiry the
- * site would ever receive.
- *
- * A per-conversation reference is what stops one filtering decision swallowing the lot.
- */
-
-const THREAD_A = 'f4c00aff-a458-40cb-8f6b-7ec66e98779c';
-const THREAD_B = '34b62e11-8209-4beb-98e9-10b364bd2807';
-
-describe('threadReference', () => {
-  it('is stable for a given thread', () => {
-    expect(threadReference(THREAD_A, 'New Roots Herbal')).toBe(
-      threadReference(THREAD_A, 'New Roots Herbal')
-    );
-  });
-
-  it('differs between threads, which is the entire point', () => {
-    expect(threadReference(THREAD_A, 'New Roots Herbal')).not.toBe(
-      threadReference(THREAD_B, 'New Roots Herbal')
-    );
-  });
-
-  it('reads as a ticket number rather than a hex dump', () => {
-    expect(threadReference(THREAD_A, 'New Roots Herbal')).toBe('NRH-VWQOLB');
-    expect(threadReference(THREAD_A, 'New Roots Herbal')).toMatch(/^[A-Z]{2,4}-[0-9A-Z]{6}$/);
-  });
-
-  it('builds initials from a multi-word site name', () => {
-    expect(threadReference(THREAD_A, 'New Roots Herbal')).toMatch(/^NRH-/);
-    expect(threadReference(THREAD_A, 'The Corner  Shop')).toMatch(/^TCS-/);
-  });
-
-  it('falls back to the first three letters of a one-word name', () => {
-    expect(threadReference(THREAD_A, 'NextBlock')).toMatch(/^NEX-/);
-  });
-
-  it('drops the prefix entirely when there is no usable site name', () => {
-    expect(threadReference(THREAD_A, '')).toBe('VWQOLB');
-    expect(threadReference(THREAD_A, '   ')).toBe('VWQOLB');
-    expect(threadReference(THREAD_A)).toBe('VWQOLB');
-  });
-
-  it('ignores punctuation in the site name rather than emitting it', () => {
-    expect(threadReference(THREAD_A, "Bob's Bikes & Co.")).toMatch(/^BBC-/);
-  });
-
-  it('survives a malformed id instead of throwing', () => {
-    expect(threadReference('', 'New Roots Herbal')).toBe('NRH-000000');
-    expect(threadReference('zzzzzzzz', 'New Roots Herbal')).toBe('NRH-000000');
-  });
-
-  it('keeps distinct conversations apart across a large sample', () => {
-    const seen = new Set<string>();
-    for (let i = 0; i < 2000; i += 1) {
-      seen.add(threadReference(crypto.randomUUID(), 'New Roots Herbal'));
-    }
-    // 2.2 billion references; a handful of collisions in 2000 draws would signal a bug
-    // in the fold, not birthday-paradox noise.
-    expect(seen.size).toBe(2000);
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { threadReference } from './threads';
+
+/**
+ * A real install stopped receiving replies and nothing reported a fault: SMTP accepted
+ * every message, Outlook accepted every message, and they went straight to Deleted Items.
+ * The cause was the subject. Every conversation from one form produced a byte-identical
+ * "Re: Contact form"; Exchange derives its ConversationTopic from the subject rather than
+ * from References, so an Ignore Conversation applied once applied to every enquiry the
+ * site would ever receive.
+ *
+ * A per-conversation reference is what stops one filtering decision swallowing the lot.
+ */
+
+const THREAD_A = 'f4c00aff-a458-40cb-8f6b-7ec66e98779c';
+const THREAD_B = '34b62e11-8209-4beb-98e9-10b364bd2807';
+
+describe('threadReference', () => {
+  it('is stable for a given thread', () => {
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).toBe(
+      threadReference(THREAD_A, 'New Roots Herbal')
+    );
+  });
+
+  it('differs between threads, which is the entire point', () => {
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).not.toBe(
+      threadReference(THREAD_B, 'New Roots Herbal')
+    );
+  });
+
+  it('reads as a ticket number rather than a hex dump', () => {
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).toBe('NRH-VWQOLB');
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).toMatch(/^[A-Z]{2,4}-[0-9A-Z]{6}$/);
+  });
+
+  it('builds initials from a multi-word site name', () => {
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).toMatch(/^NRH-/);
+    expect(threadReference(THREAD_A, 'The Corner  Shop')).toMatch(/^TCS-/);
+  });
+
+  it('falls back to the first three letters of a one-word name', () => {
+    expect(threadReference(THREAD_A, 'NextBlock')).toMatch(/^NEX-/);
+  });
+
+  it('drops the prefix entirely when there is no usable site name', () => {
+    expect(threadReference(THREAD_A, '')).toBe('VWQOLB');
+    expect(threadReference(THREAD_A, '   ')).toBe('VWQOLB');
+    expect(threadReference(THREAD_A)).toBe('VWQOLB');
+  });
+
+  it('ignores punctuation in the site name rather than emitting it', () => {
+    expect(threadReference(THREAD_A, "Bob's Bikes & Co.")).toMatch(/^BBC-/);
+  });
+
+  it('survives a malformed id instead of throwing', () => {
+    expect(threadReference('', 'New Roots Herbal')).toBe('NRH-000000');
+    expect(threadReference('zzzzzzzz', 'New Roots Herbal')).toBe('NRH-000000');
+  });
+
+  it('keeps distinct conversations apart across a large sample', () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 2000; i += 1) {
+      seen.add(threadReference(crypto.randomUUID(), 'New Roots Herbal'));
+    }
+    // 2.2 billion references; a handful of collisions in 2000 draws would signal a bug
+    // in the fold, not birthday-paradox noise.
+    expect(seen.size).toBe(2000);
+  });
+});