@adatechnology/conversations-ui 0.1.0-rc.6 → 0.1.0-rc.8

package/dist/preview/index.js

@@ -6,7 +6,7 @@ import {
   DocumentsLibrary,
   MessageBubble,
   MessageComposer
-} from "../chunk-LITPZCWW.js";
+} from "../chunk-73MW5HNT.js";
 import "../chunk-OGRRHQQW.js";
 
 // src/preview/previewStore.ts
@@ -845,9 +845,89 @@ function createMockSSEProvider(params) {
 }
 
 // src/preview/ConversationPreview.tsx
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback as useCallback2, useEffect, useMemo, useRef as useRef2, useState as useState2 } from "react";
+
+// src/preview/AudioRecorderButton.tsx
+import { useCallback, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+var DEFAULT_AUDIO_RECORDER_BUTTON_LABELS = {
+  start: "Gravar \xE1udio",
+  stop: "Parar grava\xE7\xE3o",
+  unsupported: "Este navegador n\xE3o grava \xE1udio.",
+  denied: "Sem permiss\xE3o para usar o microfone."
+};
+var RECORDING_FORMATS = [
+  { mimeType: "audio/ogg;codecs=opus", uploadMimeType: "audio/ogg", extension: "ogg" },
+  { mimeType: "audio/mp4", uploadMimeType: "audio/mp4", extension: "m4a" },
+  { mimeType: "audio/webm", uploadMimeType: "audio/webm", extension: "webm" }
+];
+function resolveRecordingFormat() {
+  if (typeof MediaRecorder === "undefined") return void 0;
+  if (typeof MediaRecorder.isTypeSupported !== "function") return RECORDING_FORMATS[0];
+  return RECORDING_FORMATS.find((format) => MediaRecorder.isTypeSupported(format.mimeType));
+}
+function AudioRecorderButton({ onRecorded, onFailure, labels, disabled }) {
+  const startLabel = labels?.start ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.start;
+  const stopLabel = labels?.stop ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.stop;
+  const [isRecording, setIsRecording] = useState(false);
+  const recorderRef = useRef(null);
+  const stop = useCallback(() => {
+    recorderRef.current?.stop();
+  }, []);
+  const start = useCallback(async () => {
+    const format = resolveRecordingFormat();
+    if (!format || !navigator.mediaDevices?.getUserMedia) {
+      onFailure?.(labels?.unsupported ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.unsupported);
+      return;
+    }
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      const recorder = new MediaRecorder(stream, { mimeType: format.mimeType });
+      const chunks = [];
+      recorder.addEventListener("dataavailable", (event) => {
+        if (event.data.size > 0) chunks.push(event.data);
+      });
+      recorder.addEventListener("stop", () => {
+        stream.getTracks().forEach((track) => track.stop());
+        setIsRecording(false);
+        recorderRef.current = null;
+        const blob = new Blob(chunks, { type: format.uploadMimeType });
+        void onRecorded(
+          new File([blob], `audio-${Date.now()}.${format.extension}`, { type: format.uploadMimeType })
+        );
+      });
+      recorderRef.current = recorder;
+      recorder.start();
+      setIsRecording(true);
+    } catch {
+      onFailure?.(labels?.denied ?? DEFAULT_AUDIO_RECORDER_BUTTON_LABELS.denied);
+    }
+  }, [labels?.denied, labels?.unsupported, onFailure, onRecorded]);
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      disabled,
+      onClick: () => isRecording ? stop() : void start(),
+      title: isRecording ? stopLabel : startLabel,
+      "aria-label": isRecording ? stopLabel : startLabel,
+      "aria-pressed": isRecording,
+      className: `flex h-9 w-9 items-center justify-center rounded-full transition-colors ${isRecording ? "bg-red-100 text-red-600 dark:bg-red-900/40" : "text-gray-500 hover:bg-gray-100 dark:hover:bg-gray-700"}`,
+      children: isRecording ? "\u25A0" : "\u{1F3A4}"
+    }
+  );
+}
+
+// src/preview/ConversationPreview.tsx
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function mediaTypeOf(mimeType) {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("video/")) return "video";
+  if (mimeType.startsWith("audio/")) return "audio";
+  return "document";
+}
 var GROUPING_WINDOW_MS = 5 * 60 * 1e3;
+var FOLLOW_UP_REFRESH_MS = [400, 1200, 3e3];
 function decorate(messages) {
   return messages.map((message, index) => {
     const previous = index > 0 ? messages[index - 1] : void 0;
@@ -860,23 +940,52 @@ function decorate(messages) {
     };
   });
 }
+function statusOf(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const candidate = error;
+  const value = candidate.status ?? candidate.statusCode;
+  return typeof value === "number" ? value : void 0;
+}
+function isNotFound(error) {
+  return statusOf(error) === 404;
+}
+function describeLoadFailure(error) {
+  const status = statusOf(error);
+  if (status === 401 || status === 403) {
+    return "Sem sess\xE3o de administrador nesta aba: a mensagem \xE9 entregue no webhook, mas o transcript n\xE3o pode ser lido. Entre no painel nesta mesma aba e reabra o simulador.";
+  }
+  if (error instanceof Error && error.message) return `N\xE3o foi poss\xEDvel ler o transcript: ${error.message}`;
+  return "N\xE3o foi poss\xEDvel ler o transcript da conversa.";
+}
 function ConversationPreview({
   client,
   sse,
   conversationId,
   loadMessages,
-  placeholder
+  placeholder,
+  pollIntervalMs,
+  uploadMedia
 }) {
-  const [messages, setMessages] = useState([]);
-  const [failure, setFailure] = useState(void 0);
-  const loadMessagesRef = useRef(loadMessages);
-  const bottomRef = useRef(null);
+  const [messages, setMessages] = useState2([]);
+  const [failure, setFailure] = useState2(void 0);
+  const [loadFailure, setLoadFailure] = useState2(void 0);
+  const [pendingLocal, setPendingLocal] = useState2([]);
+  const loadMessagesRef = useRef2(loadMessages);
+  const bottomRef = useRef2(null);
   loadMessagesRef.current = loadMessages;
-  const refresh = useCallback(async () => {
+  const refresh = useCallback2(async () => {
     try {
-      setMessages(await loadMessagesRef.current(conversationId));
-    } catch {
-      setMessages([]);
+      const loaded = await loadMessagesRef.current(conversationId);
+      setMessages(loaded);
+      setLoadFailure(void 0);
+      if (loaded.length > 0) setPendingLocal([]);
+    } catch (error) {
+      if (isNotFound(error)) {
+        setMessages([]);
+        setLoadFailure(void 0);
+        return;
+      }
+      setLoadFailure(describeLoadFailure(error));
     }
   }, [conversationId]);
   useEffect(() => {
@@ -893,42 +1002,105 @@ function ConversationPreview({
       source.close();
     };
   }, [sse, conversationId, refresh]);
+  useEffect(() => {
+    if (!pollIntervalMs) return;
+    const timer = setInterval(() => void refresh(), pollIntervalMs);
+    return () => clearInterval(timer);
+  }, [pollIntervalMs, refresh]);
   useEffect(() => {
     bottomRef.current?.scrollIntoView({ behavior: "smooth" });
   }, [messages]);
-  const rendered = useMemo(() => decorate(messages), [messages]);
+  const rendered = useMemo(() => decorate([...messages, ...pendingLocal]), [messages, pendingLocal]);
+  async function refreshWithFollowUps() {
+    await refresh();
+    for (const atraso of FOLLOW_UP_REFRESH_MS) {
+      setTimeout(() => void refresh(), atraso);
+    }
+  }
   async function handleSend(text) {
     setFailure(void 0);
     try {
       await client.sendText(text);
-      await refresh();
+      setPendingLocal((current) => [
+        ...current,
+        {
+          id: `local-${current.length}-${text.length}`,
+          type: "text",
+          content: text,
+          // Do ponto de vista do servidor, mensagem do cliente é inbound — é assim que ela aparece
+          // como "minha" nesta visão.
+          direction: "inbound",
+          sender: "customer",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          status: "sent"
+        }
+      ]);
+      await refreshWithFollowUps();
     } catch (error) {
       setFailure(error instanceof Error ? error.message : "Falha ao entregar a mensagem no webhook.");
     }
   }
+  async function handleInteractiveSelect(selection) {
+    setFailure(void 0);
+    const reply = { id: selection.option.id, title: selection.option.title };
+    try {
+      await (selection.kind === "button" ? client.sendButtonReply(reply) : client.sendListReply(reply));
+      await refreshWithFollowUps();
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : "Falha ao entregar a resposta no webhook.");
+    }
+  }
+  async function handleAttach(file) {
+    if (!uploadMedia) return;
+    setFailure(void 0);
+    try {
+      const uploaded = await uploadMedia(file);
+      await client.sendMedia({
+        mediaType: mediaTypeOf(uploaded.mimeType ?? file.type),
+        mediaId: uploaded.mediaId,
+        mimeType: uploaded.mimeType ?? file.type,
+        filename: uploaded.filename ?? file.name
+      });
+      await refreshWithFollowUps();
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : "Falha ao enviar o arquivo.");
+    }
+  }
   return /* @__PURE__ */ jsxs("div", { className: "flex h-full min-h-0 flex-col", children: [
     /* @__PURE__ */ jsxs(ConversationWallpaper, { className: "flex-1 min-h-0 overflow-y-auto px-4 py-3", children: [
       rendered.map(({ message, isFirstInGroup, showDateDivider }) => /* @__PURE__ */ jsxs("div", { children: [
-        showDateDivider ? /* @__PURE__ */ jsx(DateDivider, { iso: message.timestamp }) : null,
-        /* @__PURE__ */ jsx(
+        showDateDivider ? /* @__PURE__ */ jsx2(DateDivider, { iso: message.timestamp }) : null,
+        /* @__PURE__ */ jsx2(
           MessageBubble,
           {
             message,
             isMine: message.direction === "inbound",
-            isFirstInGroup
+            isFirstInGroup,
+            onInteractiveSelect: message.direction === "outbound" ? (selection) => void handleInteractiveSelect(selection) : void 0
           }
         )
       ] }, message.id)),
-      /* @__PURE__ */ jsx("div", { ref: bottomRef })
+      /* @__PURE__ */ jsx2("div", { ref: bottomRef })
     ] }),
-    failure ? /* @__PURE__ */ jsx("p", { role: "alert", className: "px-4 py-2 text-sm text-red-600 dark:text-red-400", children: failure }) : null,
-    /* @__PURE__ */ jsx(
-      MessageComposer,
-      {
-        onSend: (text) => void handleSend(text),
-        placeholder: placeholder ?? "Escreva como o cliente\u2026"
-      }
-    )
+    failure ? /* @__PURE__ */ jsx2("p", { role: "alert", className: "px-4 py-2 text-sm text-red-600 dark:text-red-400", children: failure }) : null,
+    loadFailure ? /* @__PURE__ */ jsx2("p", { role: "status", className: "px-4 py-2 text-sm text-amber-700 dark:text-amber-400", children: loadFailure }) : null,
+    /* @__PURE__ */ jsxs("div", { className: "flex items-end gap-1", children: [
+      /* @__PURE__ */ jsx2("div", { className: "min-w-0 flex-1", children: /* @__PURE__ */ jsx2(
+        MessageComposer,
+        {
+          onSend: (text) => void handleSend(text),
+          onAttach: uploadMedia ? (file) => void handleAttach(file) : void 0,
+          placeholder: placeholder ?? "Escreva como o cliente\u2026"
+        }
+      ) }),
+      uploadMedia ? /* @__PURE__ */ jsx2(
+        AudioRecorderButton,
+        {
+          onRecorded: (file) => void handleAttach(file),
+          onFailure: (message) => setFailure(message)
+        }
+      ) : null
+    ] })
   ] });
 }
 
@@ -936,6 +1108,7 @@ function ConversationPreview({
 import {
   buildInboundAudioPayload,
   buildInboundInteractivePayload,
+  buildInboundMediaPayload,
   buildInboundTextPayload,
   serializeWebhookPayload
 } from "@adatechnology/meta-whatsapp-contracts/testing";
@@ -955,7 +1128,7 @@ var PreviewWebhookRejectedError = class extends Error {
 function assertPreviewEnvironment(isProduction) {
   if (isProduction) throw new PreviewInProductionError();
 }
-async function signWithWebCrypto(params) {
+async function signPreviewPayload(params) {
   const encoder = new TextEncoder();
   const key = await globalThis.crypto.subtle.importKey(
     "raw",
@@ -967,6 +1140,7 @@ async function signWithWebCrypto(params) {
   const signature = await globalThis.crypto.subtle.sign("HMAC", key, encoder.encode(params.rawBody));
   return `sha256=${[...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
+var signWithWebCrypto = signPreviewPayload;
 function createPreviewWebhookClient(params) {
   const sendPayload = async (payload) => {
     const rawBody = serializeWebhookPayload(payload);
@@ -984,7 +1158,8 @@ function createPreviewWebhookClient(params) {
     sendText: (text) => sendPayload(buildInboundTextPayload({ ...envelope, text })),
     sendButtonReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, buttonReply: reply })),
     sendListReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, listReply: reply })),
-    sendAudio: (mediaId) => sendPayload(buildInboundAudioPayload({ ...envelope, mediaId }))
+    sendAudio: (mediaId) => sendPayload(buildInboundAudioPayload({ ...envelope, mediaId })),
+    sendMedia: (media) => sendPayload(buildInboundMediaPayload({ ...envelope, ...media }))
   };
 }
 
@@ -1026,7 +1201,7 @@ function startPreviewScript(params) {
 
 // src/preview/MediaTypesPreview.tsx
 import { useMemo as useMemo2 } from "react";
-import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
 var MEDIA_TYPES_CONVERSATION_ID = "5511944443333";
 function MediaTypesPreview({
   conversationId = MEDIA_TYPES_CONVERSATION_ID,
@@ -1041,9 +1216,9 @@ function MediaTypesPreview({
   const messages = PREVIEW_MESSAGES[conversationId] ?? [];
   const documents = PREVIEW_DOCUMENTS[conversationId] ?? [];
   const mimeTypes = [...new Set(documents.map((document) => document.mimeType))];
-  return /* @__PURE__ */ jsx2(ConversationsProvider, { api, sse, children: /* @__PURE__ */ jsxs2("div", { className, children: [
+  return /* @__PURE__ */ jsx3(ConversationsProvider, { api, sse, children: /* @__PURE__ */ jsxs2("div", { className, children: [
     /* @__PURE__ */ jsxs2("header", { className: "border-b px-4 py-3 dark:border-gray-700", children: [
-      /* @__PURE__ */ jsx2("h1", { className: "text-lg font-semibold", children: "Teste manual de m\xEDdia" }),
+      /* @__PURE__ */ jsx3("h1", { className: "text-lg font-semibold", children: "Teste manual de m\xEDdia" }),
       /* @__PURE__ */ jsxs2("p", { className: "text-sm text-gray-500", children: [
         documents.length,
         " arquivos, ",
@@ -1053,14 +1228,14 @@ function MediaTypesPreview({
     ] }),
     /* @__PURE__ */ jsxs2("div", { className: "grid gap-4 p-4 lg:grid-cols-2", children: [
       /* @__PURE__ */ jsxs2("section", { className: "space-y-3", children: [
-        /* @__PURE__ */ jsx2("h2", { className: "text-sm font-semibold uppercase tracking-wide text-gray-500", children: "Biblioteca da empresa" }),
-        /* @__PURE__ */ jsx2(DocumentsLibrary, { perPage: documents.length || 20 })
+        /* @__PURE__ */ jsx3("h2", { className: "text-sm font-semibold uppercase tracking-wide text-gray-500", children: "Biblioteca da empresa" }),
+        /* @__PURE__ */ jsx3(DocumentsLibrary, { perPage: documents.length || 20 })
       ] }),
       /* @__PURE__ */ jsxs2("section", { className: "space-y-3", children: [
-        /* @__PURE__ */ jsx2("h2", { className: "text-sm font-semibold uppercase tracking-wide text-gray-500", children: "Painel da conversa" }),
-        /* @__PURE__ */ jsx2(ConversationDocumentsPanel, { conversationId, open: true, perPage: documents.length || 20 }),
-        /* @__PURE__ */ jsx2("h2", { className: "text-sm font-semibold uppercase tracking-wide text-gray-500", children: "Bolhas na thread" }),
-        /* @__PURE__ */ jsx2(ConversationWallpaper, { className: "max-h-[70vh] overflow-y-auto rounded-lg px-3 py-2", children: messages.map((message, index) => /* @__PURE__ */ jsx2(
+        /* @__PURE__ */ jsx3("h2", { className: "text-sm font-semibold uppercase tracking-wide text-gray-500", children: "Painel da conversa" }),
+        /* @__PURE__ */ jsx3(ConversationDocumentsPanel, { conversationId, open: true, perPage: documents.length || 20 }),
+        /* @__PURE__ */ jsx3("h2", { className: "text-sm font-semibold uppercase tracking-wide text-gray-500", children: "Bolhas na thread" }),
+        /* @__PURE__ */ jsx3(ConversationWallpaper, { className: "max-h-[70vh] overflow-y-auto rounded-lg px-3 py-2", children: messages.map((message, index) => /* @__PURE__ */ jsx3(
           MessageBubble,
           {
             message,
@@ -1074,7 +1249,9 @@ function MediaTypesPreview({
   ] }) });
 }
 export {
+  AudioRecorderButton,
   ConversationPreview,
+  DEFAULT_AUDIO_RECORDER_BUTTON_LABELS,
   DEFAULT_PREVIEW_SCRIPT,
   GLOBAL_CHANNEL,
   MEDIA_TYPES_CONVERSATION_ID,
@@ -1093,8 +1270,10 @@ export {
   createPreviewMediaResolver,
   createPreviewStore,
   createPreviewWebhookClient,
+  mediaTypeOf,
   previewFileBase64,
   previewFileUrl,
   resolvePreviewFileSample,
+  signPreviewPayload,
   startPreviewScript
 };

package/dist/{types-CeixG2Z9.d.ts → types-B5C1DLu1.d.ts}

@@ -19,9 +19,50 @@ interface ConversationsFeatures {
     emoji?: boolean;
     darkMode?: boolean;
 }
+/**
+ * Recorte do bloco `interactive` da Meta que a UI precisa para desenhar o menu. Fica solto (e não
+ * espelhando o contrato inteiro) porque o que chega do banco é o payload cru já enviado ao
+ * WhatsApp: qualquer campo que a UI não conheça é ignorado, nunca causa erro de render.
+ */
+interface InteractiveOption {
+    id: string;
+    title: string;
+    description?: string;
+}
+interface InteractiveSection {
+    title?: string;
+    rows?: InteractiveOption[];
+}
+interface InteractivePayload {
+    type?: 'button' | 'list' | string;
+    header?: {
+        text?: string;
+    };
+    body?: {
+        text?: string;
+    };
+    footer?: {
+        text?: string;
+    };
+    action?: {
+        /** Rótulo do botão que abre a lista — só existe em `type: 'list'`. */
+        button?: string;
+        sections?: InteractiveSection[];
+        buttons?: {
+            reply?: InteractiveOption;
+        }[];
+    };
+}
+/** Como o cliente respondeu a um menu: por botão ou por item de lista. */
+type InteractiveSelection = {
+    readonly kind: 'button' | 'list';
+    readonly option: InteractiveOption;
+};
 interface MessagePayload {
     id: string;
-    type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template';
+    type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template' | 'interactive';
+    /** Payload cru da mensagem. Em `type: 'interactive'`, carrega o menu que o cliente vê. */
+    payload?: InteractivePayload | null;
     content?: string;
     caption?: string;
     mediaUrl?: string;
@@ -321,4 +362,4 @@ interface ConversationDocument {
     linkedAt: string;
 }
 
-export { contactFlag as A, formatContactHandle as B, CHANNEL_CAPABILITIES as C, DEFAULT_CONVERSATION_CHANNEL as D, type FormatContactHandleParams as F, HANDLE_KIND as H, type ListConversationsParams as L, MediaRenderer as M, REOPEN_MECHANISM as R, type SSEProvider as S, CHANNEL_FILTER_ALL as a, CONVERSATION_CHANNEL as b, type ChannelCapabilities as c, type ChannelFilter as d, type ChannelFilterOption as e, type CompanyDocument as f, type CompanyDocumentPage as g, type ConversationChannel as h, type ConversationDocument as i, type ConversationDocumentPage as j, type ConversationEventSource as k, type ConversationPage as l, type ConversationSummary as m, type ConversationTemplate as n, type ConversationsApi as o, type ConversationsFeatures as p, type ConversationsTheme as q, type ConversationsUIConfig as r, type HandleKind as s, type ListDocumentsParams as t, type MediaRendererProps as u, type MessagePayload as v, type ReopenMechanism as w, type ResolveMediaUrl as x, capabilitiesOf as y, channelFiltersFor as z };
+export { type ResolveMediaUrl as A, capabilitiesOf as B, CHANNEL_CAPABILITIES as C, DEFAULT_CONVERSATION_CHANNEL as D, channelFiltersFor as E, type FormatContactHandleParams as F, contactFlag as G, HANDLE_KIND as H, type InteractiveOption as I, formatContactHandle as J, type ListConversationsParams as L, MediaRenderer as M, REOPEN_MECHANISM as R, type SSEProvider as S, CHANNEL_FILTER_ALL as a, CONVERSATION_CHANNEL as b, type ChannelCapabilities as c, type ChannelFilter as d, type ChannelFilterOption as e, type CompanyDocument as f, type CompanyDocumentPage as g, type ConversationChannel as h, type ConversationDocument as i, type ConversationDocumentPage as j, type ConversationEventSource as k, type ConversationPage as l, type ConversationSummary as m, type ConversationTemplate as n, type ConversationsApi as o, type ConversationsFeatures as p, type ConversationsTheme as q, type ConversationsUIConfig as r, type HandleKind as s, type InteractivePayload as t, type InteractiveSection as u, type InteractiveSelection as v, type ListDocumentsParams as w, type MediaRendererProps as x, type MessagePayload as y, type ReopenMechanism as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/conversations-ui",
-  "version": "0.1.0-rc.6",
+  "version": "0.1.0-rc.8",
   "description": "WhatsApp conversation UI components — parametrizável por endpoint, tema e feature flags",
   "publishConfig": {
     "access": "public"
@@ -31,7 +31,7 @@
     "clsx": "^2.1.1",
     "lucide-react": "^1.21.0",
     "tailwind-merge": "^3.6.0",
-    "@adatechnology/meta-whatsapp-contracts": "0.2.0-rc.5"
+    "@adatechnology/meta-whatsapp-contracts": "0.2.0-rc.6"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/ConversationHeader.tsx

@@ -52,6 +52,20 @@ export interface ConversationHeaderClassNames {
   mobileMenu: string
 }
 
+/**
+ * Utilitário extra que o host pendura no cabeçalho — ícone no desktop, item de menu no celular,
+ * como os nativos. Entra por aqui, e não por um slot de ReactNode, porque é isso que preserva o
+ * comportamento responsivo: um nó solto viraria um quarto ícone em 375px, sem área de toque.
+ */
+export interface ConversationHeaderUtility {
+  key: string
+  /** Emoji, para casar com os utilitários nativos do cabeçalho. */
+  icon: string
+  label: string
+  run: () => void
+  active?: boolean
+}
+
 export interface ConversationHeaderProps {
   conversation: ConversationSummary
   busy?: boolean
@@ -61,6 +75,8 @@ export interface ConversationHeaderProps {
   onDownload?: () => void
   onOpenDocuments?: () => void
   documentsOpen?: boolean
+  /** Ações do produto que não existem no contrato do pacote (ex.: ferramentas de dev). */
+  extraUtilities?: readonly ConversationHeaderUtility[]
   onBack?: () => void
   labels?: Partial<ConversationHeaderLabels>
   className?: string
@@ -76,6 +92,7 @@ export function ConversationHeader({
   onDownload,
   onOpenDocuments,
   documentsOpen = false,
+  extraUtilities,
   onBack,
   labels: labelsOverride,
   className,
@@ -96,6 +113,7 @@ export function ConversationHeader({
       ? { key: 'documents', icon: '📄', label: labels.documents, run: onOpenDocuments, active: documentsOpen }
       : undefined,
     onDownload ? { key: 'download', icon: '⬇️', label: labels.download, run: onDownload, active: false } : undefined,
+    ...(extraUtilities ?? []).map((utility) => ({ ...utility, active: utility.active ?? false })),
   ].filter(
     (utility): utility is { key: string; icon: string; label: string; run: () => void; active: boolean } =>
       Boolean(utility),

package/src/EmojiPicker.tsx

@@ -1,39 +1,27 @@
-import { useState, useCallback } from 'react'
+import { useState, useCallback, useMemo } from 'react'
+import { EMOJI_CATEGORIES, searchEmojis, type EmojiEntry } from './emojiCatalog'
+
+export interface EmojiPickerLabels {
+  search: string
+  noResults: string
+}
+
+export const DEFAULT_EMOJI_PICKER_LABELS: EmojiPickerLabels = {
+  search: 'Buscar emoji',
+  noResults: 'Nenhum emoji encontrado',
+}
 
 export interface EmojiPickerProps {
   onSelect: (emoji: string) => void
+  labels?: Partial<EmojiPickerLabels>
   className?: string
 }
 
-const EMOJI_CATEGORIES: { name: string; emojis: string[] }[] = [
-  {
-    name: 'Smileys',
-    emojis: ['😀', '😃', '😄', '😁', '😅', '😂', '🤣', '😊', '😇', '🙂', '😉', '😌', '😍', '🥰', '😘', '😗', '😋', '😛', '😜', '🤪'],
-  },
-  {
-    name: 'Gestures',
-    emojis: ['👍', '👎', '👌', '✌️', '🤞', '🤟', '🤘', '🤙', '👋', '🤚', '🖐️', '✋', '🖖', '👏', '🙌', '🤝', '🙏', '✍️', '💅', '🤳'],
-  },
-  {
-    name: 'Hearts',
-    emojis: ['❤️', '🧡', '💛', '💚', '💙', '💜', '🖤', '🤍', '🤎', '💔', '❣️', '💕', '💞', '💓', '💗', '💖', '💘', '💝', '💟', '♥️'],
-  },
-  {
-    name: 'Food',
-    emojis: ['🍔', '🍟', '🍕', '🌭', '🍿', '🧂', '🥓', '🥚', '🍳', '🧇', '🥞', '🧈', '🍞', '🥐', '🥨', '🥯', '🥖', '🧀', '🥗', '🥙'],
-  },
-  {
-    name: 'Drinks',
-    emojis: ['☕', '🍵', '🍶', '🍾', '🍷', '🍸', '🍹', '🍺', '🍻', '🥂', '🥃', '🥤', '🧋', '🧃', '🧉', '🧊', '🥢', '🍽️', '🍴', '🥄'],
-  },
-  {
-    name: 'Objects',
-    emojis: ['🎁', '🎂', '🎈', '🎉', '🎊', '🎀', '📱', '💻', '⌚', '📷', '🔑', '💰', '💳', '📝', '📌', '📍', '✂️', '🔍', '💡', '🔔'],
-  },
-]
-
-export const EmojiPicker = ({ onSelect, className = '' }: EmojiPickerProps) => {
+export const EmojiPicker = ({ onSelect, labels, className = '' }: EmojiPickerProps) => {
+  const searchLabel = labels?.search ?? DEFAULT_EMOJI_PICKER_LABELS.search
+  const noResultsLabel = labels?.noResults ?? DEFAULT_EMOJI_PICKER_LABELS.noResults
   const [activeCategory, setActiveCategory] = useState(0)
+  const [query, setQuery] = useState('')
 
   const handleSelect = useCallback(
     (emoji: string) => {
@@ -42,36 +30,62 @@ export const EmojiPicker = ({ onSelect, className = '' }: EmojiPickerProps) => {
     [onSelect],
   )
 
+  // Buscando, as abas de categoria saem do caminho: o resultado atravessa todas elas, e manter uma
+  // aba destacada sugeriria que a busca está restrita àquela categoria.
+  const isSearching = query.trim().length > 0
+  const visibleEntries: readonly EmojiEntry[] = useMemo(
+    () => (isSearching ? searchEmojis(query) : EMOJI_CATEGORIES[activeCategory].entries),
+    [isSearching, query, activeCategory],
+  )
+
   return (
     <div className={`bg-white border border-gray-200 rounded-lg shadow-lg overflow-hidden ${className}`}>
-      <div className="flex border-b border-gray-200 overflow-x-auto">
-        {EMOJI_CATEGORIES.map((category, index) => (
-          <button
-            key={category.name}
-            onClick={() => setActiveCategory(index)}
-            className={`px-3 py-2 text-xs font-medium whitespace-nowrap border-b-2 transition-colors ${
-              activeCategory === index
-                ? 'border-blue-500 text-blue-600'
-                : 'border-transparent text-gray-500 hover:text-gray-700'
-            }`}
-          >
-            {category.emojis[0]} {category.name}
-          </button>
-        ))}
+      <div className="p-2 border-b border-gray-200">
+        <input
+          type="search"
+          value={query}
+          onChange={(event) => setQuery(event.target.value)}
+          placeholder={searchLabel}
+          aria-label={searchLabel}
+          className="w-full rounded-md border border-gray-200 px-2 py-1.5 text-sm outline-none focus:border-blue-500"
+        />
       </div>
 
-      <div className="grid grid-cols-10 gap-0.5 p-2 max-h-[240px] overflow-y-auto">
-        {EMOJI_CATEGORIES[activeCategory].emojis.map((emoji) => (
-          <button
-            key={emoji}
-            onClick={() => handleSelect(emoji)}
-            className="w-8 h-8 flex items-center justify-center text-lg hover:bg-gray-100 rounded transition-colors cursor-pointer"
-            aria-label={emoji}
-          >
-            {emoji}
-          </button>
-        ))}
-      </div>
+      {isSearching ? null : (
+        <div className="flex border-b border-gray-200 overflow-x-auto">
+          {EMOJI_CATEGORIES.map((category, index) => (
+            <button
+              key={category.name}
+              onClick={() => setActiveCategory(index)}
+              className={`px-3 py-2 text-xs font-medium whitespace-nowrap border-b-2 transition-colors ${
+                activeCategory === index
+                  ? 'border-blue-500 text-blue-600'
+                  : 'border-transparent text-gray-500 hover:text-gray-700'
+              }`}
+            >
+              {category.entries[0].emoji} {category.name}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {visibleEntries.length === 0 ? (
+        <p className="px-3 py-6 text-center text-sm text-gray-500">{noResultsLabel}</p>
+      ) : (
+        <div className="grid grid-cols-10 gap-0.5 p-2 max-h-[240px] overflow-y-auto">
+          {visibleEntries.map((entry) => (
+            <button
+              key={entry.emoji}
+              onClick={() => handleSelect(entry.emoji)}
+              className="w-8 h-8 flex items-center justify-center text-lg hover:bg-gray-100 rounded transition-colors cursor-pointer"
+              aria-label={entry.emoji}
+              title={entry.keywords[0]}
+            >
+              {entry.emoji}
+            </button>
+          ))}
+        </div>
+      )}
     </div>
   )
 }