keystone-design-bootstrap 1.0.103 → 1.0.105-dev.0

package/dist/utils/markdown-toc.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/markdown-toc.ts"],"sourcesContent":["/**\n * Utility functions for extracting table of contents from markdown\n */\n\nexport interface TableOfContentsItem {\n  id: string;\n  title: string;\n  level: number;\n}\n\n/**\n * Generate a URL-friendly ID from a heading text\n */\nfunction slugify(text: string): string {\n  return text\n    .toLowerCase()\n    .trim()\n    .replace(/[^\\w\\s-]/g, '') // Remove special characters\n    .replace(/[\\s_-]+/g, '-') // Replace spaces and underscores with hyphens\n    .replace(/^-+|-+$/g, ''); // Remove leading/trailing hyphens\n}\n\n/**\n * Extract headings from markdown content and generate table of contents\n */\nexport function extractTableOfContents(markdown: string): TableOfContentsItem[] {\n  if (!markdown) return [];\n\n  const toc: TableOfContentsItem[] = [];\n  const lines = markdown.split('\\n');\n\n  for (const line of lines) {\n    // Match markdown headings (##, ###, etc.)\n    const headingMatch = line.match(/^(#{1,6})\\s+(.+)$/);\n    if (headingMatch) {\n      const level = headingMatch[1].length;\n      const title = headingMatch[2].trim();\n      \n      // Only include h2 and h3 headings in TOC\n      if (level >= 2 && level <= 3) {\n        const id = slugify(title);\n        toc.push({\n          id,\n          title,\n          level,\n        });\n      }\n    }\n  }\n\n  return toc;\n}\n\n\n"],"mappings":";AAaA,SAAS,QAAQ,MAAsB;AACrC,SAAO,KACJ,YAAY,EACZ,KAAK,EACL,QAAQ,aAAa,EAAE,EACvB,QAAQ,YAAY,GAAG,EACvB,QAAQ,YAAY,EAAE;AAC3B;AAKO,SAAS,uBAAuB,UAAyC;AAC9E,MAAI,CAAC,SAAU,QAAO,CAAC;AAEvB,QAAM,MAA6B,CAAC;AACpC,QAAM,QAAQ,SAAS,MAAM,IAAI;AAEjC,aAAW,QAAQ,OAAO;AAExB,UAAM,eAAe,KAAK,MAAM,mBAAmB;AACnD,QAAI,cAAc;AAChB,YAAM,QAAQ,aAAa,CAAC,EAAE;AAC9B,YAAM,QAAQ,aAAa,CAAC,EAAE,KAAK;AAGnC,UAAI,SAAS,KAAK,SAAS,GAAG;AAC5B,cAAM,KAAK,QAAQ,KAAK;AACxB,YAAI,KAAK;AAAA,UACP;AAAA,UACA;AAAA,UACA;AAAA,QACF,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

package/dist/utils/phone-helpers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * List of countries with their respective country code, flag, phone code, and phone mask.
+ */
+declare const countries: ({
+    name: string;
+    code: string;
+    flag: string;
+    phoneCode: string;
+    phoneMask: string;
+} | {
+    name: string;
+    code: string;
+    flag: string;
+    phoneCode: string;
+    phoneMask?: undefined;
+})[];
+
+type Country = (typeof countries)[0];
+/** Get national-format mask from country by stripping the country code prefix (e.g. "+1 (###) ###-####" → "(###) ###-####"). */
+declare function getNationalMask(country: Country | undefined): string;
+/** Format a raw digit string into a mask pattern where '#' represents one digit. No trailing literals so backspace works naturally. */
+declare function formatDigitsToMask(digits: string, mask: string): string;
+
+export { formatDigitsToMask, getNationalMask };

package/dist/utils/phone-helpers.js

@@ -0,0 +1,26 @@
+// src/utils/phone-helpers.ts
+function getNationalMask(country) {
+  if (!(country == null ? void 0 : country.phoneMask)) return "";
+  const code = country.phoneCode.startsWith("+") ? country.phoneCode : `+${country.phoneCode}`;
+  const escaped = code.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return country.phoneMask.replace(new RegExp(`^\\s*${escaped}[\\s-]*`), "").trim();
+}
+function formatDigitsToMask(digits, mask) {
+  if (digits.length === 0) return "";
+  let i = 0;
+  let out = "";
+  for (const c of mask) {
+    if (c === "#") {
+      if (i < digits.length) out += digits[i++];
+      else break;
+    } else if (i < digits.length) {
+      out += c;
+    }
+  }
+  return out;
+}
+export {
+  formatDigitsToMask,
+  getNationalMask
+};
+//# sourceMappingURL=phone-helpers.js.map

package/dist/utils/phone-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/phone-helpers.ts"],"sourcesContent":["import type countries from './countries';\n\ntype Country = (typeof countries)[0];\n\n/** Get national-format mask from country by stripping the country code prefix (e.g. \"+1 (###) ###-####\" → \"(###) ###-####\"). */\nexport function getNationalMask(country: Country | undefined): string {\n  if (!country?.phoneMask) return '';\n  const code = country.phoneCode.startsWith('+') ? country.phoneCode : `+${country.phoneCode}`;\n  const escaped = code.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n  return country.phoneMask.replace(new RegExp(`^\\\\s*${escaped}[\\\\s-]*`), '').trim();\n}\n\n/** Format a raw digit string into a mask pattern where '#' represents one digit. No trailing literals so backspace works naturally. */\nexport function formatDigitsToMask(digits: string, mask: string): string {\n  if (digits.length === 0) return '';\n  let i = 0;\n  let out = '';\n  for (const c of mask) {\n    if (c === '#') {\n      if (i < digits.length) out += digits[i++];\n      else break;\n    } else if (i < digits.length) {\n      out += c;\n    }\n  }\n  return out;\n}\n"],"mappings":";AAKO,SAAS,gBAAgB,SAAsC;AACpE,MAAI,EAAC,mCAAS,WAAW,QAAO;AAChC,QAAM,OAAO,QAAQ,UAAU,WAAW,GAAG,IAAI,QAAQ,YAAY,IAAI,QAAQ,SAAS;AAC1F,QAAM,UAAU,KAAK,QAAQ,uBAAuB,MAAM;AAC1D,SAAO,QAAQ,UAAU,QAAQ,IAAI,OAAO,QAAQ,OAAO,SAAS,GAAG,EAAE,EAAE,KAAK;AAClF;AAGO,SAAS,mBAAmB,QAAgB,MAAsB;AACvE,MAAI,OAAO,WAAW,EAAG,QAAO;AAChC,MAAI,IAAI;AACR,MAAI,MAAM;AACV,aAAW,KAAK,MAAM;AACpB,QAAI,MAAM,KAAK;AACb,UAAI,IAAI,OAAO,OAAQ,QAAO,OAAO,GAAG;AAAA,UACnC;AAAA,IACP,WAAW,IAAI,OAAO,QAAQ;AAC5B,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/utils/photo-helpers.d.ts

@@ -0,0 +1,38 @@
+import { P as PhotoAttachment } from '../photos-CmBdWiuZ.js';
+import { W as WebsitePhotos } from '../website-photos-Cl1YqAno.js';
+
+/**
+ * Helper functions for extracting photo URLs from photo associations
+ */
+
+/**
+ * True if the URL looks like a video by path extension. Used to avoid using video URLs in img src.
+ */
+declare function isVideoUrl(url: string | null | undefined): boolean;
+/**
+ * Get the best available photo URL from a photos array
+ * Priority: featured photo > first photo > fallback
+ */
+declare function getPhotoUrl(photos?: PhotoAttachment[]): string | null;
+/**
+ * Get avatar URL for team members or authors.
+ * Returns a URL only when there is a real photo in attachments; otherwise null.
+ * Callers should use PhotoWithFallback (gradient fallback) or Avatar with initials when null.
+ */
+/** Optional fallbackId/name reserved for future use (e.g. deterministic fallback). */
+declare function getAvatarUrl(photos?: PhotoAttachment[], _fallbackId?: number | string, _name?: string): string | null;
+/**
+ * Get featured image URL for blog posts
+ */
+declare function getFeaturedImageUrl(photos?: PhotoAttachment[]): string | null;
+/**
+ * Get logo URL from website_photos API (which aggregates from account_photos)
+ *
+ * The website_photos API endpoint returns logos from account_photos with photo_type: 'logo',
+ * with industry fallback. This is the primary and only source for logos.
+ *
+ * Returns undefined if no logo is available (for PhotoWithFallback gradient fallback)
+ */
+declare function getLogoUrl(websitePhotos?: WebsitePhotos | null): string | undefined;
+
+export { PhotoAttachment, getAvatarUrl, getFeaturedImageUrl, getLogoUrl, getPhotoUrl, isVideoUrl };

package/dist/utils/photo-helpers.js

@@ -0,0 +1,41 @@
+// src/utils/photo-helpers.ts
+var VIDEO_EXTENSIONS = [".mp4", ".mov", ".webm", ".m4v", ".avi", ".mkv", ".flv", ".wmv"];
+function isVideoUrl(url) {
+  var _a;
+  if (!url || typeof url !== "string") return false;
+  const path = (_a = url.split("?")[0]) != null ? _a : "";
+  const ext = path.slice(path.lastIndexOf(".")).toLowerCase();
+  return VIDEO_EXTENSIONS.includes(ext);
+}
+function getPhotoUrl(photos) {
+  if (photos && photos.length > 0) {
+    const featuredPhoto = photos.find((pa) => pa.featured);
+    const photoToUse = featuredPhoto || photos[0];
+    const photo = photoToUse.photo;
+    if (photo) {
+      return photo.large_url || photo.medium_url || photo.thumbnail_url || photo.original_url || null;
+    }
+  }
+  return null;
+}
+function getAvatarUrl(photos, _fallbackId, _name) {
+  return getPhotoUrl(photos);
+}
+function getFeaturedImageUrl(photos) {
+  return getPhotoUrl(photos);
+}
+function getLogoUrl(websitePhotos) {
+  var _a;
+  if ((_a = websitePhotos == null ? void 0 : websitePhotos.logo) == null ? void 0 : _a.url) {
+    return websitePhotos.logo.url;
+  }
+  return void 0;
+}
+export {
+  getAvatarUrl,
+  getFeaturedImageUrl,
+  getLogoUrl,
+  getPhotoUrl,
+  isVideoUrl
+};
+//# sourceMappingURL=photo-helpers.js.map

package/dist/utils/photo-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/photo-helpers.ts"],"sourcesContent":["/**\n * Helper functions for extracting photo URLs from photo associations\n */\n\nimport type { PhotoAttachment } from '../types/api/photos';\nimport type { WebsitePhotos } from '../types/api/website-photos';\n\nexport type { PhotoAttachment } from '../types/api/photos';\n\n/** Video file extensions treated as video (match backend ExternalPhotoService.video_url?) */\nconst VIDEO_EXTENSIONS = ['.mp4', '.mov', '.webm', '.m4v', '.avi', '.mkv', '.flv', '.wmv'];\n\n/**\n * True if the URL looks like a video by path extension. Used to avoid using video URLs in img src.\n */\nexport function isVideoUrl(url: string | null | undefined): boolean {\n  if (!url || typeof url !== 'string') return false;\n  const path = url.split('?')[0] ?? '';\n  const ext = path.slice(path.lastIndexOf('.')).toLowerCase();\n  return VIDEO_EXTENSIONS.includes(ext);\n}\n\n/**\n * Get the best available photo URL from a photos array\n * Priority: featured photo > first photo > fallback\n */\nexport function getPhotoUrl(\n  photos?: PhotoAttachment[]\n): string | null {\n  // Priority 1: Featured photo from photos array\n  if (photos && photos.length > 0) {\n    const featuredPhoto = photos.find(pa => pa.featured);\n    const photoToUse = featuredPhoto || photos[0];\n    const photo = photoToUse.photo;\n    \n    if (photo) {\n      return photo.large_url || photo.medium_url || photo.thumbnail_url || photo.original_url || null;\n    }\n  }\n  \n  // Fallback (gradient or null)\n  return null;\n}\n\n/**\n * Get avatar URL for team members or authors.\n * Returns a URL only when there is a real photo in attachments; otherwise null.\n * Callers should use PhotoWithFallback (gradient fallback) or Avatar with initials when null.\n */\n/** Optional fallbackId/name reserved for future use (e.g. deterministic fallback). */\n/* eslint-disable @typescript-eslint/no-unused-vars -- _fallbackId, _name reserved for API */\nexport function getAvatarUrl(\n  photos?: PhotoAttachment[],\n  _fallbackId?: number | string,\n  _name?: string\n): string | null {\n  return getPhotoUrl(photos);\n}\n/* eslint-enable @typescript-eslint/no-unused-vars */\n\n/**\n * Get featured image URL for blog posts\n */\nexport function getFeaturedImageUrl(\n  photos?: PhotoAttachment[]\n): string | null {\n  return getPhotoUrl(photos);\n}\n\n/**\n * Get logo URL from website_photos API (which aggregates from account_photos)\n * \n * The website_photos API endpoint returns logos from account_photos with photo_type: 'logo',\n * with industry fallback. This is the primary and only source for logos.\n * \n * Returns undefined if no logo is available (for PhotoWithFallback gradient fallback)\n */\nexport function getLogoUrl(\n  websitePhotos?: WebsitePhotos | null\n): string | undefined {\n  if (websitePhotos?.logo?.url) {\n    return websitePhotos.logo.url;\n  }\n  \n  return undefined;\n}\n\n"],"mappings":";AAUA,IAAM,mBAAmB,CAAC,QAAQ,QAAQ,SAAS,QAAQ,QAAQ,QAAQ,QAAQ,MAAM;AAKlF,SAAS,WAAW,KAAyC;AAfpE;AAgBE,MAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO;AAC5C,QAAM,QAAO,SAAI,MAAM,GAAG,EAAE,CAAC,MAAhB,YAAqB;AAClC,QAAM,MAAM,KAAK,MAAM,KAAK,YAAY,GAAG,CAAC,EAAE,YAAY;AAC1D,SAAO,iBAAiB,SAAS,GAAG;AACtC;AAMO,SAAS,YACd,QACe;AAEf,MAAI,UAAU,OAAO,SAAS,GAAG;AAC/B,UAAM,gBAAgB,OAAO,KAAK,QAAM,GAAG,QAAQ;AACnD,UAAM,aAAa,iBAAiB,OAAO,CAAC;AAC5C,UAAM,QAAQ,WAAW;AAEzB,QAAI,OAAO;AACT,aAAO,MAAM,aAAa,MAAM,cAAc,MAAM,iBAAiB,MAAM,gBAAgB;AAAA,IAC7F;AAAA,EACF;AAGA,SAAO;AACT;AASO,SAAS,aACd,QACA,aACA,OACe;AACf,SAAO,YAAY,MAAM;AAC3B;AAMO,SAAS,oBACd,QACe;AACf,SAAO,YAAY,MAAM;AAC3B;AAUO,SAAS,WACd,eACoB;AA/EtB;AAgFE,OAAI,oDAAe,SAAf,mBAAqB,KAAK;AAC5B,WAAO,cAAc,KAAK;AAAA,EAC5B;AAEA,SAAO;AACT;","names":[]}

package/dist/website-photos-Cl1YqAno.d.ts

@@ -0,0 +1,21 @@
+interface WebsitePhoto {
+    id: number;
+    url: string;
+    thumbnail_url?: string;
+    medium_url?: string;
+    alt: string;
+    source: 'account' | 'industry';
+}
+interface WebsitePhotos {
+    logo?: WebsitePhoto | null;
+    favicon?: WebsitePhoto | null;
+    hero?: WebsitePhoto | null;
+    contact?: WebsitePhoto | null;
+    about?: WebsitePhoto | null;
+    careers?: WebsitePhoto | null;
+    preview_image?: WebsitePhoto | null;
+    stock_photos?: WebsitePhoto[];
+}
+type WebsitePhotosResponse = WebsitePhotos;
+
+export type { WebsitePhotos as W, WebsitePhoto as a, WebsitePhotosResponse as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keystone-design-bootstrap",
-  "version": "1.0.103",
+  "version": "1.0.105-dev.0",
   "description": "Keystone Design Bootstrap - Sections, Elements, and Theme System for customer websites",
   "type": "module",
   "main": "./src/index.ts",

package/src/design_system/components/ChatWidget.tsx

@@ -7,6 +7,7 @@ import { cx } from '../../utils/cx';
 import { captureEvent } from '../../tracking/captureEvent';
 import { useRealtimeReplyOrchestrator, type RealtimeSubscriptionData } from '../chat/useRealtimeReplyOrchestrator';
 import { error as logError } from '../../tracking/logging';
+import { RAILS_BACKEND, SOR_BACKEND, type ChatBackend } from '../../lib/chat-backend';
 
 interface Message {
   id: string;
@@ -25,6 +26,18 @@ interface TeamMember {
 
 interface ChatWidgetProps {
   position?: 'bottom-right' | 'bottom-left';
+  /**
+   * Which backend the site's `/api/chat` proxy talks to. The two backends have
+   * architecturally different reply delivery: 'rails' (keystone-mono-proto)
+   * pushes replies over ActionCable realtime; 'sor' (sor-service) has no
+   * realtime channel and the widget polls for the reply instead. The paths are
+   * mutually exclusive — a 'sor' widget never probes/subscribes realtime, a
+   * 'rails' widget never polls.
+   *
+   * TODO(webchat): default is 'rails' while keystone-mono-proto is still a live
+   * backend; flip the default to 'sor' once the Rails backend is scrapped.
+   */
+  chatBackend?: ChatBackend;
   primaryColor?: string;
   /**
    * Anonymous session identifier. Used when the visitor is not authenticated.
@@ -66,6 +79,7 @@ const formatTime = (isoString: string) => {
 export function ChatWidget({
   position = 'bottom-right',
   primaryColor,
+  chatBackend = RAILS_BACKEND,
   sessionId: providedSessionId,
   contactId,
   displayName: providedDisplayName,
@@ -146,7 +160,10 @@ export function ChatWidget({
     );
   }, []);
 
+  const isSorBackend = chatBackend === SOR_BACKEND;
+
   const fetchRealtimeData = useCallback(async (): Promise<RealtimeSubscriptionData | null> => {
+    if (isSorBackend) return null; // sor has no realtime channel — never probe
     if (!contactId && !sessionId) return null;
     const query = contactId
       ? `contact_id=${encodeURIComponent(contactId)}`
@@ -159,7 +176,7 @@ export function ChatWidget({
     const cableUrl = result?.data?.cable_url as string | undefined;
     if (!token || !contactIdForStream || !cableUrl) return null;
     return { token, contact_id: contactIdForStream, cable_url: cableUrl };
-  }, [contactId, sessionId]);
+  }, [contactId, isSorBackend, sessionId]);
 
   const {
     beginReplyWait,
@@ -179,13 +196,48 @@ export function ChatWidget({
 
   const hasPersistedMessages = messages.some((message) => !String(message.id).startsWith('temp_'));
 
+  // rails reply delivery: ActionCable realtime subscription.
   useEffect(() => {
+    if (isSorBackend) return;
     if (!isOpen || (!contactId && !sessionId)) return;
     // Anonymous sessions do not have a contact row until the first message is sent.
     // Ignore optimistic temp rows to avoid pre-contact token probes (404 noise).
     if (!contactId && !hasPersistedMessages) return;
     ensureRealtimeSubscription();
-  }, [contactId, ensureRealtimeSubscription, hasPersistedMessages, isOpen, sessionId]);
+  }, [contactId, ensureRealtimeSubscription, hasPersistedMessages, isOpen, isSorBackend, sessionId]);
+
+  // sor reply delivery: no realtime channel exists, so while waiting for the
+  // agent reply, poll the thread and resolve as soon as an agent message with
+  // a body lands (or after a timeout). Never runs for the rails backend.
+  useEffect(() => {
+    if (!isSorBackend || !waitingForReply) return;
+    let cancelled = false;
+    let inFlight = false; // don't stack requests when a poll outlives the interval
+    let attempts = 0;
+    const maxAttempts = 40; // ~60s at 1.5s
+    const interval = setInterval(async () => {
+      if (inFlight) return;
+      inFlight = true;
+      attempts += 1;
+      try {
+        const msgs = await loadMessages();
+        if (cancelled) return;
+        if (hasAgentReplyWithBody(msgs) || attempts >= maxAttempts) {
+          clearInterval(interval);
+          setWaitingForReply(false);
+          setIsLoading(false);
+        }
+      } catch {
+        // transient — keep polling until maxAttempts
+      } finally {
+        inFlight = false;
+      }
+    }, 1500);
+    return () => {
+      cancelled = true;
+      clearInterval(interval);
+    };
+  }, [isSorBackend, waitingForReply, loadMessages, hasAgentReplyWithBody]);
 
   const sendMessage = async () => {
     if (!inputValue.trim() || (!contactId && !sessionId)) return;
@@ -220,15 +272,19 @@ export function ChatWidget({
         captureEvent('chat_message_sent', { is_authenticated: Boolean(contactId) });
 
         if (result.data?.job_id) {
+          // setWaitingForReply arms the sor polling effect; rails additionally
+          // subscribes to the realtime channel for push delivery.
           setWaitingForReply(true);
-          const realtimeFromSend = result.data?.realtime_token && result.data?.contact_id && result.data?.cable_url
-            ? {
-              token: result.data.realtime_token,
-              contact_id: result.data.contact_id,
-              cable_url: result.data.cable_url,
-            }
-            : null;
-          beginReplyWait({ realtimeData: realtimeFromSend });
+          if (!isSorBackend) {
+            const realtimeFromSend = result.data?.realtime_token && result.data?.contact_id && result.data?.cable_url
+              ? {
+                token: result.data.realtime_token,
+                contact_id: result.data.contact_id,
+                cable_url: result.data.cable_url,
+              }
+              : null;
+            beginReplyWait({ realtimeData: realtimeFromSend });
+          }
         } else if (result.data?.status === 'agent_unavailable' || result.data?.status === 'no_auto_reply') {
           setIsLoading(false);
           setWaitingForReply(false);

package/src/design_system/portal/LoginForm.tsx

@@ -204,30 +204,7 @@ export function LoginForm({ onSuccess, onClose }: LoginFormProps) {
         body: JSON.stringify({ phone: fullPhone, code }),
       });
       const result = await res.json().catch(() => ({}));
-      if (!res.ok) {
-        setError(result.error || 'That code is invalid or expired.');
-        captureEvent('portal_login_failed', { step: 'signin', reason: result.code || 'verification_failed' });
-        return;
-      }
-
-      // Compatibility path: verify_code may directly authenticate and set the
-      // session cookie via the route handler (no passwordless_auth needed).
-      if (result.authenticated) {
-        await setPixelUserData({ email: result.email || undefined, phone: fullPhone });
-        firePixelEvent('Lead', undefined, result?.eventId);
-        captureEvent('portal_login_step_advanced', {
-          from_step: 'signin',
-          to_step: 'authenticated',
-          reason: 'verification_direct_auth',
-        });
-        captureEvent('portal_login_completed', { flow: 'signin' });
-        setResendAvailableAt(null);
-        setSecondsUntilResend(0);
-        if (onSuccess) onSuccess(); else router.refresh();
-        return;
-      }
-
-      if (!result.verification_token) {
+      if (!res.ok || !result.verification_token) {
         setError(result.error || 'That code is invalid or expired.');
         captureEvent('portal_login_failed', { step: 'signin', reason: result.code || 'verification_failed' });
         return;

package/src/lib/chat-backend.ts

@@ -0,0 +1,36 @@
+/**
+ * Which chat backend the site's /api/chat proxy targets.
+ *
+ * The two backends have architecturally different webchat contracts:
+ * - 'rails' (keystone-mono-proto): /public/messages + ActionCable realtime.
+ * - 'sor'   (sor-service): /public/chat/* + widget long-polling.
+ *
+ * Resolution order:
+ * 1. CHAT_BACKEND env ('rails' | 'sor') — explicit override; needed for
+ *    custom domains or local dev, where the API_URL hostname carries no signal.
+ * 2. Derived from API_URL: a hostname containing a `sor` label
+ *    (sor.localkeystone.com, sor.dev.localkeystone.com, …) ⇒ 'sor'.
+ * 3. Default 'rails'.
+ *
+ * TODO(webchat): default is 'rails' while keystone-mono-proto is still a live
+ * backend; flip the default to 'sor' once the Rails backend is scrapped.
+ */
+import { serverError } from './server-log';
+
+export const RAILS_BACKEND = 'rails' as const;
+export const SOR_BACKEND = 'sor' as const;
+export type ChatBackend = typeof RAILS_BACKEND | typeof SOR_BACKEND;
+
+export function resolveChatBackend(): ChatBackend {
+  const explicit = process.env.CHAT_BACKEND;
+  if (explicit === SOR_BACKEND || explicit === RAILS_BACKEND) return explicit;
+
+  const apiUrl = process.env.API_URL || '';
+  try {
+    const host = new URL(apiUrl).hostname;
+    if (host.split('.').includes(SOR_BACKEND)) return SOR_BACKEND;
+  } catch (error) {
+    serverError('CHAT_BACKEND_API_URL_PARSE_ERROR', error, { apiUrl });
+  }
+  return RAILS_BACKEND;
+}

package/src/lib/consumer-session.ts

@@ -8,8 +8,10 @@ export const CONSUMER_TOKEN_COOKIE = 'ks_consumer_token';
 import type { Consumer, ConversationSummary, Message, ContactSummary } from '../types/api/consumer';
 export type { Consumer, ConversationSummary, Message, ContactSummary };
 
+// AUTH_API_URL (when set) points consumer auth/session endpoints at a dedicated
+// auth service (e.g. Heimdal); everything else keeps using API_URL.
 function getApiUrl(): string {
-  return process.env.API_URL || 'http://localhost:3000/api/v1';
+  return process.env.AUTH_API_URL || process.env.API_URL || 'http://localhost:3000/api/v1';
 }
 
 async function consumerFetch<T>(path: string, token: string): Promise<T | null> {

package/src/next/layouts/root-layout.tsx

@@ -11,6 +11,7 @@ import {
   KeystoneAnalyticsTracker,
 } from '../../tracking';
 import { ChatWidget } from '../../design_system/components/ChatWidget';
+import { resolveChatBackend } from '../../lib/chat-backend';
 import { FormDefinitionsProvider } from '../contexts/form-definitions';
 import { KeystoneSSRProvider } from '../providers/ssr-provider';
 import {
@@ -182,6 +183,9 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
   const portalUrl = ci?.portal_url?.trim() || null;
   const bookingHref = portalUrl ?? externalManagementUrl ?? null;
   const chatEnabled = Boolean(ci?.chat_enabled);
+  // Which backend the site's /api/chat proxy targets — same resolution as the
+  // route handlers (CHAT_BACKEND override, else derived from API_URL).
+  const chatBackend = resolveChatBackend();
 
   const headerOverrides = options?.headerOverrides;
   const posthogHost = options?.posthogHost?.trim() || undefined;
@@ -229,6 +233,7 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
             {chatEnabled ? (
               <ChatWidget
                 position={options?.chatPosition || 'bottom-right'}
+                chatBackend={chatBackend}
                 teamMembers={teamMembers}
               />
             ) : null}