@nyris/nyris-webapp 0.3.97 → 0.3.99

package/src/translations.ts

@@ -51,6 +51,30 @@ export const translations = {
       'Are these results useful?': 'Are these results useful?',
       'Thank you for your feedback': 'Thank you for your feedback',
       'Select a Filter': 'Select a Filter',
+      'Select scope': 'Select scope',
+      'Identify your machine': 'Identify your machine',
+      'Machine identified': 'Machine identified',
+      'Identify machine': 'Identify machine',
+      'Find part': 'Find part',
+      'Scan type plate': 'Scan type plate',
+      'Scan Type plate': 'Scan Type plate',
+      'Searching within parts for {{scopeId}}. You may scan another type plate.':
+        'Searching within parts for {{scopeId}}. You may scan another type plate.',
+      "Scan your machine's type plate first to see only parts that fit it":
+        "Scan your machine's type plate first to see only parts that fit it",
+      'Upload image': 'Upload image',
+      'Upload new type plate': 'Upload new type plate',
+      'Take a photo': 'Take a photo',
+      'Find machine': 'Find machine',
+      'Skip and search all parts': 'Skip and search all parts',
+      'Back to results': 'Back to results',
+      'Skip and search with all parts': 'Skip and search with all parts',
+      'Where to find it': 'Where to find it',
+      'Serial number': 'Serial number',
+      'A metal or foil label on the machine housing, usually near the motor or the main panel. Make sure the serial number is sharp and readable.':
+        'A metal or foil label on the machine housing, usually near the motor or the main panel. Make sure the serial number is sharp and readable.',
+      'The serial number we read is not in our index.':
+        'The serial number we read is not in our index.',
       'Get personalised help from our team of product experts.':
         'Get personalised help from our team of product experts.',
       'Adjust the selection frame for better results':
@@ -70,6 +94,52 @@ export const translations = {
       'We have successfully defined the search criteria':
         'Nameplate detected and matched to {{prefilter_value}}. Items are shown for this {{preFilterTitle}}. You can now upload an image or enter a keyword to search.',
       'Type plates': 'Type plates',
+      'Start with a type plate': 'Start with a type plate',
+      'Scope ID is': 'Scope ID is',
+      'Upload typeplate': 'Upload typeplate',
+      'Enter value here': 'Enter value here',
+      "Can't scan? Enter serial number manually.":
+        "Can't scan? Enter serial number manually.",
+      'Enter serial number manually': 'Enter serial number manually',
+      'e.g. 2234GH': 'e.g. 2234GH',
+      'Configurable: Manual input placeholder':
+        'Configurable: Manual input placeholder',
+      'Scope data loaded successfully.': 'Scope data loaded successfully.',
+      'Scope data could not be loaded.': 'Scope data could not be loaded.',
+      'Clear the type-plate image to enter a scope ID.':
+        'Clear the type-plate image to enter a scope ID.',
+      'Clear the scope ID to upload a type plate.':
+        'Clear the scope ID to upload a type plate.',
+      'Scope loaded successfully.': 'Scope loaded successfully.',
+      'Scope {{scopeId}} loaded successfully.':
+        'Scope {{scopeId}} loaded successfully.',
+      'You can now upload an image to search.':
+        'You can now upload an image to search.',
+      'Sorry, no matching scope was found.':
+        'Sorry, no matching scope was found.',
+      'Sorry, the search returned no results.':
+        'Sorry, the search returned no results.',
+      'You may start from type plate uploading':
+        'You may start from type plate uploading',
+      'Searching with': 'Searching with',
+      'Searching within scope': 'Searching within scope',
+      'Parts for machine': 'Parts for machine',
+      'Searching within parts for {{scope_id}}. You can search with keyword or image to find the right item':
+        'Searching within parts for {{scope_id}}. You can search with keyword or image to find the right item',
+      'Scan a new type plate': 'Scan a new type plate',
+      'Search part names, SKU, or description...':
+        'Search part names, SKU, or description...',
+      'Check the number against the plate and correct it if needed.':
+        'Check the number against the plate and correct it if needed.',
+      'The serial number was not found. Please check again.':
+        'The serial number was not found. Please check again.',
+      'Applying...': 'Applying...',
+      'Showing {{resultCount}} results from all machines':
+        'Showing {{resultCount}} results from all machines',
+      'Scan your type plate to see only parts for your equipment.':
+        'Scan your type plate to see only parts for your equipment.',
+      Close: 'Close',
+      'Search all products': 'Search all products',
       Parts: 'Parts',
       Labels: 'Labels',
       Barcodes: 'Barcodes',
@@ -134,6 +204,30 @@ export const translations = {
       'Are these results useful?': 'Sind diese Ergebnisse nützlich?',
       'Thank you for your feedback': 'Vielen Dank für Ihr Feedback',
       'Select a Filter': 'Filter wählen',
+      'Select scope': 'Scope auswählen',
+      'Identify your machine': 'Identifizieren Sie Ihre Maschine',
+      'Machine identified': 'Maschine identifiziert',
+      'Identify machine': 'Maschine identifizieren',
+      'Find part': 'Teil finden',
+      'Scan type plate': 'Typenschild scannen',
+      'Scan Type plate': 'Typenschild scannen',
+      'Searching within parts for {{scopeId}}. You may scan another type plate.':
+        'Suche innerhalb der Teile für {{scopeId}}. Sie können ein anderes Typenschild scannen.',
+      "Scan your machine's type plate first to see only parts that fit it":
+        'Scannen Sie zuerst das Typenschild Ihrer Maschine, um nur passende Teile zu sehen',
+      'Upload image': 'Bild hochladen',
+      'Upload new type plate': 'Neues Typenschild hochladen',
+      'Take a photo': 'Foto aufnehmen',
+      'Find machine': 'Maschine finden',
+      'Skip and search all parts': 'Überspringen und alle Teile durchsuchen',
+      'Back to results': 'Zurück zu den Ergebnissen',
+      'Skip and search with all parts': 'Überspringen und alle Teile durchsuchen',
+      'Where to find it': 'Wo Sie es finden',
+      'Serial number': 'Seriennummer',
+      'A metal or foil label on the machine housing, usually near the motor or the main panel. Make sure the serial number is sharp and readable.':
+        'Ein Metall- oder Folienetikett am Maschinengehäuse, meist in der Nähe des Motors oder der Haupttafel. Stellen Sie sicher, dass die Seriennummer scharf und lesbar ist.',
+      'The serial number we read is not in our index.':
+        'Die gelesene Seriennummer ist nicht in unserem Index.',
       'Get personalised help from our team of product experts.':
         'Holen Sie sich persönliche Hilfe von unserem Team von Produktexperten.',
       'No matches found': 'Keine Treffer gefunden',
@@ -154,6 +248,53 @@ export const translations = {
       'We have successfully defined the search criteria':
         'Typenschild erkannt und mit {{prefilter_value}} abgeglichen. Es werden Artikel für dieses {{preFilterTitle}}. Sie können nun ein Bild hochladen oder ein Stichwort zur Suche eingeben.',
       'Type plates': 'Typenschilder',
+      'Start with a type plate': 'Mit Typenschild starten',
+      'Scope ID is': 'Scope-ID ist',
+      'Upload typeplate': 'Typenschild hochladen',
+      'Enter value here': 'Wert hier eingeben',
+      "Can't scan? Enter serial number manually.":
+        'Kein Scan möglich? Seriennummer manuell eingeben.',
+      'Enter serial number manually': 'Seriennummer manuell eingeben',
+      'e.g. 2234GH': 'z. B. 2234GH',
+      'Configurable: Manual input placeholder':
+        'Konfigurierbar: Platzhalter für manuelle Eingabe',
+      'Scope data loaded successfully.': 'Scope-Daten erfolgreich geladen.',
+      'Scope data could not be loaded.':
+        'Scope-Daten konnten nicht geladen werden.',
+      'Clear the type-plate image to enter a scope ID.':
+        'Löschen Sie das Typenschild-Bild, um eine Scope-ID einzugeben.',
+      'Clear the scope ID to upload a type plate.':
+        'Löschen Sie die Scope-ID, um ein Typenschild hochzuladen.',
+      'Scope loaded successfully.': 'Scope erfolgreich geladen.',
+      'Scope {{scopeId}} loaded successfully.':
+        'Scope {{scopeId}} erfolgreich geladen.',
+      'You can now upload an image to search.':
+        'Sie können jetzt ein Bild hochladen, um zu suchen.',
+      'Sorry, no matching scope was found.':
+        'Entschuldigung, es wurde kein passender Scope gefunden.',
+      'Sorry, the search returned no results.':
+        'Entschuldigung, die Suche hat keine Ergebnisse geliefert.',
+      'You may start from type plate uploading':
+        'Sie können mit dem Hochladen des Typenschilds beginnen',
+      'Searching with': 'Suche mit',
+      'Searching within scope': 'Suche innerhalb des Scopes',
+      'Parts for machine': 'Teile für Maschine',
+      'Searching within parts for {{scope_id}}. You can search with keyword or image to find the right item':
+        'Suche innerhalb der Teile für {{scope_id}}. Sie können mit einem Suchbegriff oder Bild das passende Teil finden',
+      'Scan a new type plate': 'Neues Typenschild scannen',
+      'Search part names, SKU, or description...':
+        'Teilename, SKU oder Beschreibung suchen...',
+      'Check the number against the plate and correct it if needed.':
+        'Nummer anhand des Typenschilds prüfen und ggf. korrigieren.',
+      'The serial number was not found. Please check again.':
+        'Die Seriennummer wurde nicht gefunden. Bitte versuchen Sie es erneut.',
+      'Applying...': 'Wird angewendet...',
+      'Showing {{resultCount}} results from all machines':
+        '{{resultCount}} Ergebnisse von allen Maschinen werden angezeigt',
+      'Scan your type plate to see only parts for your equipment.':
+        'Scannen Sie Ihr Typenschild, um nur Teile für Ihre Ausrüstung zu sehen.',
+      Close: 'Schließen',
+      'Search all products': 'Alle Produkte durchsuchen',
       Parts: 'Teile',
       Labels: 'Etiketten',
       Barcodes: 'Barcodes',
@@ -219,6 +360,30 @@ export const translations = {
         'Comece sua busca visual selecionando uma imagem abaixo.',
       'Thank you for your feedback': 'Obrigado pelo seu feedback',
       'Select a Filter': 'Selecione um filtro',
+      'Select scope': 'Selecionar scope',
+      'Identify your machine': 'Identifique a sua máquina',
+      'Machine identified': 'Máquina identificada',
+      'Identify machine': 'Identificar máquina',
+      'Find part': 'Encontrar peça',
+      'Scan type plate': 'Digitalizar placa de identificação',
+      'Scan Type plate': 'Digitalizar placa de identificação',
+      'Searching within parts for {{scopeId}}. You may scan another type plate.':
+        'A pesquisar dentro das peças para {{scopeId}}. Pode digitalizar outra placa de identificação.',
+      "Scan your machine's type plate first to see only parts that fit it":
+        'Digitalize primeiro a placa de identificação da máquina para ver apenas as peças compatíveis',
+      'Upload image': 'Carregar imagem',
+      'Upload new type plate': 'Carregar nova placa de identificação',
+      'Take a photo': 'Tirar uma foto',
+      'Find machine': 'Encontrar máquina',
+      'Skip and search all parts': 'Ignorar e pesquisar todas as peças',
+      'Back to results': 'Voltar aos resultados',
+      'Skip and search with all parts': 'Ignorar e pesquisar todas as peças',
+      'Where to find it': 'Onde encontrar',
+      'Serial number': 'Número de série',
+      'A metal or foil label on the machine housing, usually near the motor or the main panel. Make sure the serial number is sharp and readable.':
+        'Uma etiqueta de metal ou folha no invólucro da máquina, geralmente perto do motor ou do painel principal. Certifique-se de que o número de série está nítido e legível.',
+      'The serial number we read is not in our index.':
+        'O número de série que lemos não está no nosso índice.',
       'Get personalised help from our team of product experts.':
         'Obtenha ajuda personalizada de nossa equipe de especialistas em produtos.',
       'Adjust the selection frame for better results':
@@ -239,6 +404,54 @@ export const translations = {
       'We have successfully defined the search criteria':
         'Placa de identificação detetada e correspondente a {{prefilter_value}}. São apresentados os itens para esta {{preFilterTitle}}. Agora pode carregar uma imagem ou introduzir uma palavra-chave para pesquisar.',
       'Type plates': 'Placa de identificação',
+      'Start with a type plate': 'Começar com uma placa de identificação',
+      'Scope ID is': 'O Scope ID é',
+      'Upload typeplate': 'Carregar placa de identificação',
+      'Enter value here': 'Introduza o valor aqui',
+      "Can't scan? Enter serial number manually.":
+        'Não consegue digitalizar? Introduza o número de série manualmente.',
+      'Enter serial number manually': 'Inserir número de série manualmente',
+      'e.g. 2234GH': 'ex. 2234GH',
+      'Configurable: Manual input placeholder':
+        'Configurável: Marcador de posição de entrada manual',
+      'Scope data loaded successfully.':
+        'Dados de scope carregados com sucesso.',
+      'Scope data could not be loaded.':
+        'Não foi possível carregar os dados de scope.',
+      'Clear the type-plate image to enter a scope ID.':
+        'Limpe a imagem da placa para introduzir um Scope ID.',
+      'Clear the scope ID to upload a type plate.':
+        'Limpe o Scope ID para carregar uma placa de identificação.',
+      'Scope loaded successfully.': 'Scope carregado com sucesso.',
+      'Scope {{scopeId}} loaded successfully.':
+        'Scope {{scopeId}} carregado com sucesso.',
+      'You can now upload an image to search.':
+        'Agora pode carregar uma imagem para pesquisar.',
+      'Sorry, no matching scope was found.':
+        'Lamentamos, não foi encontrado nenhum scope correspondente.',
+      'Sorry, the search returned no results.':
+        'Lamentamos, a pesquisa não devolveu resultados.',
+      'You may start from type plate uploading':
+        'Você pode começar enviando a placa de identificação',
+      'Searching with': 'Pesquisando com',
+      'Searching within scope': 'A pesquisar dentro do scope',
+      'Parts for machine': 'Peças para máquina',
+      'Searching within parts for {{scope_id}}. You can search with keyword or image to find the right item':
+        'A pesquisar dentro das peças para {{scope_id}}. Pode pesquisar por palavra-chave ou imagem para encontrar o item certo',
+      'Scan a new type plate': 'Digitalizar nova placa de identificação',
+      'Search part names, SKU, or description...':
+        'Pesquisar nomes de peças, SKU ou descrição...',
+      'Check the number against the plate and correct it if needed.':
+        'Verifique o número na placa e corrija-o se necessário.',
+      'The serial number was not found. Please check again.':
+        'O número de série não foi encontrado. Por favor, tente novamente.',
+      'Applying...': 'A aplicar...',
+      'Showing {{resultCount}} results from all machines':
+        'A mostrar {{resultCount}} resultados de todas as máquinas',
+      'Scan your type plate to see only parts for your equipment.':
+        'Digitalize a sua placa de identificação para ver apenas peças do seu equipamento.',
+      Close: 'Fechar',
+      'Search all products': 'Pesquisar todos os produtos',
       Parts: 'Peças',
       Labels: 'Etiquetas',
       Barcodes: 'Códigos de barras',

package/src/types.ts

@@ -27,6 +27,37 @@ export interface Rfq {
   enabled?: boolean;
   emailTemplateId?: string;
 }
+
+export interface ScopesSettings {
+  scopeID?: boolean;
+  typePlateButtonLabel?: string;
+  typePlateStepOne?: string;
+  typePlateStepTwo?: string;
+  typePlatePopupTitle?: string;
+  typePlatePopupTitleSuccess?: string;
+  typePlatePopupCtaButton?: string;
+  typePlatePopupCtaTextButton?: string;
+  typePlatePopupFindMachineButton?: string;
+  typePlatePopupSkipButton?: string;
+  typePlatePopupBackButton?: string;
+  typePlatePopupUploadButton?: string;
+  typePlatePopupUploadNewButton?: string;
+  typePlatePopupTakePhotoButton?: string;
+  typePlatePopupApplyingLabel?: string;
+  typePlateResultsScopeLabel?: string;
+  typePlateResultsNoScopeLabel?: string;
+  typePlateResultsClearScopeLabel?: string;
+  typePlatePopupErrorMessage?: string;
+  typePlateManualInputLabel?: string;
+  typePlateManualInputPlaceholder?: string;
+  typePlateWhereToFindTitle?: string;
+  typePlateWhereToFindDescription?: string;
+  typePlateSerialNumberLabel?: string;
+  /** Legacy label aliases. Not set in settings.js. */
+  typePlateButtonText?: string;
+  typePlateFindMachineButton?: string;
+  typePlateSkipButton?: string;
+}
 export interface Cadenas {
   cadenas3dWebView?: boolean;
   cadenasAPIKey?: string;
@@ -86,6 +117,12 @@ export interface AppSettings extends NyrisAPISettings {
   };
   clarityId?: string;
   CTAButton?: CTAButtonSettings;
+  /**
+   * Feedback API events that must never be sent. Entries may be event types
+   * (`click`, `conversion`, `feedback`, `region`) or subtypes
+   * (`copy_details`, `add_to_cart`, ...). Case-insensitive.
+   */
+  disabledFeedbackEvents?: string[];
   experienceVisualSearch?: boolean;
   experienceVisualSearchImages?: string[];
   geoLocation?: boolean;
@@ -106,6 +143,7 @@ export interface AppSettings extends NyrisAPISettings {
   noImageUrl?: string;
   noSimilarSearch?: boolean;
   postFilterOption?: boolean;
+  postFilterUseApi?: boolean;
   preFilterOption?: boolean;
   preFilterTitle?: string;
   preview: boolean;
@@ -115,6 +153,7 @@ export interface AppSettings extends NyrisAPISettings {
   regions: boolean;
   rfq?: Rfq;
   scopeFilter?: boolean;
+  scopes?: ScopesSettings;
   secondaryCTAButton?: SecondaryCTAButton;
   secondaryCTAButtonText?: string;
   secondaryTitle: string;
@@ -125,6 +164,7 @@ export interface AppSettings extends NyrisAPISettings {
   showGroup?: boolean;
   showImageDetails?: boolean;
   useSmartFilters?: boolean;
+  requestQuality?: boolean;
   showPoweredByNyris?: boolean;
   simpleCardView?: boolean;
   support: Support;

package/src/utils/derivePostFilterFacets.ts

@@ -0,0 +1,68 @@
+interface PostFilterFacetValue {
+  value: string;
+  count: number;
+}
+
+export interface PostFilterFacet {
+  name: string;
+  values: PostFilterFacetValue[];
+}
+
+interface ProductWithFilters {
+  filters?: Record<string, unknown>;
+}
+
+/**
+ * Aggregates post-filter facet options from result.filters when the find API
+ * does not return top-level facets (e.g. visual search). Matches the pre-02ede11
+ * PostFilterFindApi counting behavior.
+ */
+export function derivePostFilterFacetsFromResults(
+  results: ProductWithFilters[] | undefined | null,
+): PostFilterFacet[] {
+  if (!results?.length) {
+    return [];
+  }
+
+  const countsByAttribute: Record<string, Record<string, number>> = {};
+
+  results.forEach(product => {
+    const filters = product?.filters;
+    if (!filters || typeof filters !== 'object') {
+      return;
+    }
+
+    Object.entries(filters).forEach(([attribute, filterValues]) => {
+      if (!Array.isArray(filterValues)) {
+        return;
+      }
+
+      if (!countsByAttribute[attribute]) {
+        countsByAttribute[attribute] = {};
+      }
+
+      filterValues.forEach((val: unknown) => {
+        if (typeof val === 'string' && val) {
+          countsByAttribute[attribute][val] =
+            (countsByAttribute[attribute][val] || 0) + 1;
+        }
+      });
+    });
+  });
+
+  return Object.entries(countsByAttribute).map(([name, counts]) => ({
+    name,
+    values: Object.entries(counts).map(([value, count]) => ({ value, count })),
+  }));
+}
+
+export function resolvePostFilterFacets(
+  apiFacets: unknown,
+  results: ProductWithFilters[] | undefined | null,
+): PostFilterFacet[] {
+  if (Array.isArray(apiFacets) && apiFacets.length > 0) {
+    return apiFacets as PostFilterFacet[];
+  }
+
+  return derivePostFilterFacetsFromResults(results);
+}

package/src/utils/fetchProductImage.ts

@@ -101,6 +101,7 @@ export async function fetchProductImageBase64(
 export function getProductImageUrl(product: any): string | null {
   return (
     product.matches?.[0]?.url ||
+    product['image(main_similarity)'] ||
     product.main_image_link ||
     product.image ||
     product.images?.[0] ||

package/src/utils/normalizeChatAssistantResponse.ts

@@ -0,0 +1,227 @@
+import { ActionType, QuickReplyOption } from 'stores/chat/conversationStore';
+
+export interface P3Response {
+  message: string;
+  action: {
+    type: ActionType;
+    key?: string;
+    value?: string;
+    matched_ids?: string[];
+    matched_indices?: number[];
+  };
+  options: QuickReplyOption[];
+}
+
+const EMPTY_RESPONSE: P3Response = {
+  message: '',
+  action: {
+    type: 'none',
+    matched_ids: [],
+  },
+  options: [],
+};
+
+/** Fresh empty P3Response — never share nested refs with prior responses. */
+function createEmptyResponse(): P3Response {
+  return {
+    message: EMPTY_RESPONSE.message,
+    action: {
+      type: EMPTY_RESPONSE.action.type,
+      matched_ids: [],
+    },
+    options: [],
+  };
+}
+
+/** Generic helper preambles that are clearly separate from the answer. */
+const GENERIC_PREAMBLE_PATTERN = /^I can help you[^.]*\.\s+/i;
+
+function isCompatibleP3Response(value: unknown): value is P3Response {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  return typeof candidate.message === 'string';
+}
+
+/**
+ * Finds the first balanced JSON object in `text` that parses and looks like
+ * a P3Response. Respects nested braces and braces inside quoted strings.
+ */
+function extractCompatibleJsonObject(text: string): P3Response | null {
+  for (let start = 0; start < text.length; start += 1) {
+    if (text[start] !== '{') {
+      continue;
+    }
+
+    let depth = 0;
+    let inString = false;
+    let isEscaped = false;
+
+    for (let end = start; end < text.length; end += 1) {
+      const char = text[end];
+
+      if (inString) {
+        if (isEscaped) {
+          isEscaped = false;
+        } else if (char === '\\') {
+          isEscaped = true;
+        } else if (char === '"') {
+          inString = false;
+        }
+        continue;
+      }
+
+      if (char === '"') {
+        inString = true;
+        continue;
+      }
+
+      if (char === '{') {
+        depth += 1;
+        continue;
+      }
+
+      if (char === '}') {
+        depth -= 1;
+        if (depth !== 0) {
+          continue;
+        }
+
+        const candidate = text.slice(start, end + 1);
+        try {
+          const parsed: unknown = JSON.parse(candidate);
+          if (isCompatibleP3Response(parsed)) {
+            return parsed;
+          }
+        } catch {
+          // Not valid JSON for this brace pair; try the next `{`.
+        }
+        break;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Locates a `matched_ids: [...]` fragment, parses the array, and returns
+ * the ids plus the text with that fragment removed.
+ */
+function extractMatchedIdsFromPlainText(text: string): {
+  matchedIds: string[];
+  message: string;
+} {
+  const markerMatch = /matched_ids\s*:\s*/i.exec(text);
+  if (!markerMatch || markerMatch.index === undefined) {
+    return { matchedIds: [], message: text };
+  }
+
+  const arrayStart = markerMatch.index + markerMatch[0].length;
+  if (text[arrayStart] !== '[') {
+    return { matchedIds: [], message: text };
+  }
+
+  let depth = 0;
+  let inString = false;
+  let isEscaped = false;
+
+  for (let index = arrayStart; index < text.length; index += 1) {
+    const char = text[index];
+
+    if (inString) {
+      if (isEscaped) {
+        isEscaped = false;
+      } else if (char === '\\') {
+        isEscaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+
+    if (char === '[') {
+      depth += 1;
+      continue;
+    }
+
+    if (char === ']') {
+      depth -= 1;
+      if (depth !== 0) {
+        continue;
+      }
+
+      const arrayLiteral = text.slice(arrayStart, index + 1);
+          try {
+            const parsed: unknown = JSON.parse(arrayLiteral);
+            if (
+              Array.isArray(parsed) &&
+              parsed.every((item): item is string => typeof item === 'string')
+            ) {
+              const before = text.slice(0, markerMatch.index).trimEnd();
+              const after = text.slice(index + 1).trimStart();
+              const message = [before, after].filter(Boolean).join(' ').trim();
+
+              return { matchedIds: parsed, message };
+            }
+          } catch {
+            // Fall through to return the original text unchanged.
+          }
+
+      return { matchedIds: [], message: text };
+    }
+  }
+
+  return { matchedIds: [], message: text };
+}
+
+function normalizePlainText(text: string): P3Response {
+  const { matchedIds, message: withoutIds } =
+    extractMatchedIdsFromPlainText(text);
+  const message = withoutIds.replace(GENERIC_PREAMBLE_PATTERN, '').trim();
+
+  return {
+    message,
+    action: {
+      type: 'none',
+      matched_ids: matchedIds,
+    },
+    options: [],
+  };
+}
+
+/**
+ * Normalizes chat_assistant_prompt output into a P3Response.
+ * Handles object responses, JSON embedded in prose, and plain-text fallbacks.
+ * Never throws — always returns a safe P3Response.
+ */
+export function normalizeChatAssistantResponse(
+  response: P3Response | string | unknown,
+): P3Response {
+  if (isCompatibleP3Response(response)) {
+    return response;
+  }
+
+  if (typeof response !== 'string') {
+    return createEmptyResponse();
+  }
+
+  const trimmed = response.trim();
+  if (!trimmed) {
+    return createEmptyResponse();
+  }
+
+  const fromJson = extractCompatibleJsonObject(trimmed);
+  if (fromJson) {
+    return fromJson;
+  }
+
+  return normalizePlainText(trimmed);
+}