@adatechnology/conversations-ui 0.1.0-rc.26 → 0.1.0-rc.28

package/src/flows/flowEditorOps.ts

@@ -0,0 +1,177 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Operações puras de grafo que o editor de fluxo precisa, e que viviam soltas dentro da página de
+ * 973 linhas do financiamento.
+ *
+ * Puras e separadas do hook de propósito: são a parte que dá para testar sem navegador, sem React e
+ * sem estado — e três delas (`removeNodeAndCleanRefs`, `resolveConnection`, `mergedFlowKeysFrom`)
+ * decidem o que acontece com o fluxo que alguém desenhou. Errar ali não dá erro; dá aresta apontando
+ * para nó que não existe mais, ou fluxo que some do canvas.
+ */
+
+// Os TIPOS do grafo vêm do meta-whatsapp-contracts, fonte única da verdade do trio
+// (`pluggable-module.md` §2) — mesmo motivo documentado em `flowGraph.ts`. `import type` puro: nada
+// do contracts entra por aqui em tempo de execução.
+import type { FlowGraphData, FlowNodeData, FlowNodeNext } from '@adatechnology/meta-whatsapp-contracts'
+
+// A constante vem do `flowGraph`, que já a define, e não do contracts: duas fontes do mesmo prefixo
+// divergem em silêncio, e o sintoma seria salto entre fluxos que o motor do bot não reconhece.
+import { CROSS_FLOW_PREFIX, crossFlowTargetsOf } from './flowGraph'
+
+const NAMESPACE_SEPARATOR = '::'
+
+/**
+ * Id de nó no canvas mesclado: vários fluxos dividem o mesmo espaço, e `boas-vindas` pode existir em
+ * dois deles. Sem o prefixo, arrastar um card moveria o homônimo do outro fluxo.
+ */
+export function namespaceNodeId(flowKey: string, nodeId: string): string {
+  return `${flowKey}${NAMESPACE_SEPARATOR}${nodeId}`
+}
+
+export function parseNamespacedId(value: string): { flowKey: string; nodeId: string } {
+  const index = value.indexOf(NAMESPACE_SEPARATOR)
+  // Sem separador é id de fluxo único — trata como do fluxo vazio para o chamador decidir.
+  if (index === -1) return { flowKey: '', nodeId: value }
+  return { flowKey: value.slice(0, index), nodeId: value.slice(index + NAMESPACE_SEPARATOR.length) }
+}
+
+/**
+ * Apaga o nó E as referências a ele.
+ *
+ * A limpeza não é cortesia: uma aresta apontando para nó inexistente faz o motor do bot parar a
+ * conversa no meio, e o sintoma aparece para o cliente, não para quem editou.
+ */
+export function removeNodeAndCleanRefs(
+  nodes: Readonly<Record<string, FlowNodeData>>,
+  removedId: string,
+): Record<string, FlowNodeData> {
+  const remaining: Record<string, FlowNodeData> = {}
+
+  for (const [id, node] of Object.entries(nodes)) {
+    if (id === removedId) continue
+    remaining[id] = { ...node, next: cleanNext(node.next, removedId) }
+  }
+
+  return remaining
+}
+
+function cleanNext(next: FlowNodeNext | undefined, removedId: string): FlowNodeNext | undefined {
+  if (next === undefined) return undefined
+  if (typeof next === 'string') return next === removedId ? '' : next
+
+  const byAnswer: Record<string, string> = {}
+  for (const [answer, target] of Object.entries(next.byAnswer ?? {})) {
+    // Resposta que levava ao nó apagado fica com destino vazio, e não é removida: apagar a chave
+    // esconderia da tela que aquela opção existe e não vai a lugar nenhum.
+    byAnswer[answer] = target === removedId ? '' : target
+  }
+
+  return { byAnswer, default: next.default === removedId ? '' : (next.default ?? '') }
+}
+
+/**
+ * O fecho transitivo dos fluxos alcançáveis a partir de um — é o conjunto que o canvas abre junto.
+ *
+ * BFS e não recursão: fluxo que referencia a si mesmo (menu que volta ao menu) é comum, e recursão
+ * ingênua estouraria a pilha no caso mais banal que existe.
+ */
+export function mergedFlowKeysFrom(
+  rootKey: string,
+  graphs: Readonly<Record<string, FlowGraphData>>,
+): readonly string[] {
+  const visited = new Set<string>()
+  const queue = [rootKey]
+
+  while (queue.length > 0) {
+    const key = queue.shift()!
+    if (visited.has(key) || !graphs[key]) continue
+    visited.add(key)
+    for (const target of crossFlowTargetsOf(graphs[key]!)) {
+      if (!visited.has(target) && graphs[target]) queue.push(target)
+    }
+  }
+
+  return [...visited]
+}
+
+export type ConnectionRequest = {
+  readonly source: string
+  readonly target: string
+  readonly sourceHandle?: string | null | undefined
+}
+
+export type ResolvedConnection = {
+  readonly flowKey: string
+  readonly nodeId: string
+  readonly handle: string
+  /** O que gravar no `next`: id de nó local, ou `flow:<key>` quando atravessa fluxo. */
+  readonly targetValue: string
+}
+
+/**
+ * Traduz um arraste de aresta no valor que vai para o `next` — e recusa o que o motor do bot não
+ * sabe executar.
+ *
+ * A regra que não é óbvia: conectar num nó de OUTRO fluxo só funciona se for o nó inicial dele,
+ * porque o motor só sabe pular para o começo de um fluxo, não para um nó do meio. Conectar no meio
+ * devolve `undefined` — recusa silenciosa é melhor que gravar um salto que o bot vai ignorar em
+ * produção, deixando a conversa parada sem ninguém entender por quê.
+ */
+export function resolveConnection(params: {
+  readonly connection: ConnectionRequest
+  readonly graphs: Readonly<Record<string, FlowGraphData>>
+}): ResolvedConnection | undefined {
+  const { source, target, sourceHandle } = params.connection
+  if (!source || !target || source === target) return undefined
+
+  const sourceRef = parseNamespacedId(source)
+  const targetRef = parseNamespacedId(target)
+
+  let targetValue: string
+  if (targetRef.flowKey === sourceRef.flowKey) {
+    targetValue = targetRef.nodeId
+  } else {
+    const targetGraph = params.graphs[targetRef.flowKey]
+    if (!targetGraph || targetGraph.startNodeId !== targetRef.nodeId) return undefined
+    targetValue = `${CROSS_FLOW_PREFIX}${targetRef.flowKey}`
+  }
+
+  return {
+    flowKey: sourceRef.flowKey,
+    nodeId: sourceRef.nodeId,
+    handle: sourceHandle ?? 'next',
+    targetValue,
+  }
+}
+
+/** Aplica a conexão resolvida no nó. `next` string para saída única, objeto para ramificação. */
+export function applyConnection(node: FlowNodeData, resolved: ResolvedConnection): FlowNodeData {
+  const currentNext = typeof node.next === 'object' && node.next ? node.next : undefined
+
+  if (resolved.handle === 'next') return { ...node, next: resolved.targetValue }
+
+  if (resolved.handle === '__default') {
+    return { ...node, next: { byAnswer: currentNext?.byAnswer ?? {}, default: resolved.targetValue } }
+  }
+
+  return {
+    ...node,
+    next: {
+      byAnswer: { ...(currentNext?.byAnswer ?? {}), [resolved.handle]: resolved.targetValue },
+      default: currentNext?.default ?? '',
+    },
+  }
+}
+
+/**
+ * Um fluxo está sujo quando o rascunho difere do publicado.
+ *
+ * Comparação estrutural por JSON: é grosseira, e é suficiente porque o grafo é dado serializável sem
+ * ordem significativa de chave — o servidor devolve o que gravou. Comparar campo a campo daria a
+ * mesma resposta com mais código para errar.
+ */
+export function isGraphDirty(working: FlowGraphData | undefined, published: FlowGraphData | undefined): boolean {
+  if (!working || !published) return false
+  return JSON.stringify(working) !== JSON.stringify(published)
+}

package/src/flows/flowGraph.ts

@@ -372,7 +372,7 @@ export function findCollectionChains(graph: FlowGraphData): CollectionChain[] {
 }
 
 // Gera um id de nó único e legível a partir do rótulo (ex.: "Qual sua renda?" → "qual_sua_renda").
-export function slugifyNodeId(label: string, existing: Set<string>): string {
+export function slugifyNodeId(label: string, existing: ReadonlySet<string>): string {
   const base =
     label
       .toLowerCase()

package/src/flows/index.ts

@@ -55,3 +55,19 @@ export type { FlowPortalNodeData } from './FlowPortalNode'
 export type { FlowPaletteProps, FlowPaletteActionOption, NewNodeSpec } from './FlowPalette'
 export type { FlowNodePanelProps } from './FlowNodePanel'
 export type { FlowWhatsAppPreviewProps } from './FlowWhatsAppPreview'
+
+/**
+ * Operações do EDITOR de fluxo, puras. Vinham soltas dentro da página de 973 linhas do
+ * financiamento; são a base do `FlowsWorkspace` (ADR 0002) e a parte que carrega o risco de perder
+ * trabalho de quem edita.
+ */
+export {
+  applyConnection,
+  isGraphDirty,
+  mergedFlowKeysFrom,
+  namespaceNodeId,
+  parseNamespacedId,
+  removeNodeAndCleanRefs,
+  resolveConnection,
+} from './flowEditorOps'
+export type { ConnectionRequest, ResolvedConnection } from './flowEditorOps'

package/src/flows/labels.ts

@@ -21,6 +21,8 @@ export interface FlowEditorLabels {
     question: string
     options: string
     addOption: string
+    removeOption: string
+    close: string
     optionId: string
     optionLabel: string
     next: string
@@ -186,6 +188,8 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     question: 'Texto da pergunta',
     options: 'Opções (choice)',
     addOption: 'Adicionar opção',
+    removeOption: 'Remover opção',
+    close: 'Fechar painel',
     optionId: 'Valor',
     optionLabel: 'Texto exibido',
     next: 'Próximo nó',

package/src/flows/workspaceContract.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * O subpath `/flows` precisa exportar a TELA, não só as peças.
+ *
+ * Existe porque a ausência disso já custou: exportando apenas `FlowMapCanvas`, `FlowPalette` e
+ * `FlowNodePanel`, o financiamento montou a tela por conta — 973 linhas de página mais um fork local
+ * dos componentes, que ficou atrás do pacote. O quickcart, para ter a mesma tela, teria que copiar o
+ * arquivo. É exatamente a divergência que `pluggable-module.md` §4 proíbe.
+ *
+ * O teste é de superfície, não de comportamento: não prova que o canvas desenha certo, prova que
+ * existe UM lugar onde a tela mora, e que ela aceita customização por contrato em vez de por fork.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import * as flows from './index'
+import { DEFAULT_FLOW_EDITOR_LABELS, mergeFlowEditorLabels } from './labels'
+
+const WORKSPACE_SOURCE = `${import.meta.dir}/FlowsWorkspace.tsx`
+
+describe('superfície composta', () => {
+  it('exporta a tela inteira', () => {
+    expect(typeof flows.FlowsWorkspace).toBe('function')
+  })
+
+  it('exporta as peças também — quem precisa de layout próprio não fica sem saída', () => {
+    // Workspace é o caminho recomendado, não uma prisão: um produto com layout radicalmente
+    // diferente compõe as peças, e isso é melhor que forkar o pacote.
+    for (const piece of ['FlowMapCanvas', 'FlowPalette', 'FlowNodePanel', 'FlowWhatsAppPreview']) {
+      expect(typeof (flows as Record<string, unknown>)[piece], piece).toBe('function')
+    }
+  })
+
+  it('as operações de grafo saem puras, sem passar pela tela', () => {
+    // São as que a tela consome de verdade (ver os imports em `FlowsWorkspace.tsx`). Exportá-las sem
+    // usá-las seria pior que não ter teste: teste verde sobre código que não roda em produção.
+    for (const operation of ['resolveConnection', 'applyConnection', 'removeNodeAndCleanRefs', 'mergedFlowKeysFrom']) {
+      expect(typeof (flows as Record<string, unknown>)[operation], operation).toBe('function')
+    }
+  })
+})
+
+describe('contrato de customização', () => {
+  it('nenhuma capacidade em forma de flag booleana `hasX`', async () => {
+    /**
+     * Capacidade opcional é por AUSÊNCIA de prop. `hasDelete` seria um segundo jeito de dizer o que
+     * `deletableFlowKeys` já diz, e dois jeitos divergem — alguém liga a flag sem a lista e a tela
+     * desenha um botão que não exclui nada.
+     */
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).not.toMatch(/readonly has[A-Z]/)
+  })
+
+  it('aceita labels, className e os slots de render', async () => {
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).toContain('labels?: Partial<')
+    // `className` é o que deixa o produto posicionar a tela no layout dele sem tocar no pacote.
+    expect(content).toContain('className?: string')
+    expect(content).toContain('renderMediaPicker?:')
+  })
+
+  it('nenhum texto visível escrito no componente — tudo passa por labels', async () => {
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+    /**
+     * Texto entre tags JSX que não seja `{...}`, que é o que `web.md` §6 proíbe.
+     *
+     * O `\s*` nas pontas não é detalhe: a primeira versão deste regex no notification-ui exigia o
+     * texto colado nas tags, e o Prettier põe o conteúdo em linha própria — o teste passava com
+     * `>\n  Configurações\n<` no meio do componente, provando nada.
+     */
+    const hardcoded = content.match(/>\s*[A-Za-zÀ-ÿ][A-Za-zÀ-ÿ ]{3,}\s*</g)
+
+    expect(hardcoded, `texto fixo: ${hardcoded?.join(' | ')}`).toBeNull()
+  })
+
+  it('o produto sobrescreve UM texto sem perder os outros do mesmo grupo', () => {
+    const merged = mergeFlowEditorLabels({ workspace: { ...DEFAULT_FLOW_EDITOR_LABELS.workspace, title: 'Jornadas' } })
+
+    expect(merged.workspace.title).toBe('Jornadas')
+    expect(merged.workspace.saveGraph).toBe(DEFAULT_FLOW_EDITOR_LABELS.workspace.saveGraph)
+  })
+
+  it('grupo novo de label entra no merge profundo', () => {
+    // Esquecer o grupo no `mergeFlowEditorLabels` deixa o override apagar os irmãos dele, e o
+    // sintoma é texto sumindo da tela — não erro.
+    for (const group of ['workspace', 'flowManager', 'validation', 'collectionChain'] as const) {
+      const merged = mergeFlowEditorLabels({ [group]: {} })
+
+      expect(Object.keys(merged[group]).length, group).toBe(Object.keys(DEFAULT_FLOW_EDITOR_LABELS[group]).length)
+    }
+  })
+})

package/src/hooks/useContainerWidth.ts

@@ -0,0 +1,35 @@
+/**
+ * Largura do próprio elemento, para decidir layout pelo espaço que ele tem — e não pelo tamanho da
+ * janela.
+ *
+ * Os breakpoints do Tailwind (`sm:`, `lg:`) leem a janela, e é aí que erram nestas telas: abrir a
+ * prévia do simulador, ou a lista de conversas ao lado, estreita a coluna sem a janela mudar de
+ * tamanho. O layout continua achando que está no desktop e espreme o conteúdo flexível — o campo de
+ * texto do composer e o nome do cliente no cabeçalho — para caber os botões, que não cedem.
+ *
+ * `undefined` enquanto não mediu (SSR e teste de markup incluídos): quem consome trata ausência de
+ * medida como espaçoso, que é o layout completo.
+ */
+
+import { useEffect, useState, type RefObject } from 'react'
+
+export function useContainerWidth(ref: RefObject<HTMLElement | null>): number | undefined {
+  const [width, setWidth] = useState<number | undefined>(undefined)
+
+  useEffect(() => {
+    const element = ref.current
+    if (!element || typeof ResizeObserver === 'undefined') return
+
+    // Sempre a mesma medida nos dois caminhos: o `contentRect` do observer desconta o padding e o
+    // `getBoundingClientRect` não. Misturar os dois desloca o limiar pela largura do padding — no
+    // cabeçalho, 32px — e o layout decide uma coisa ao montar e outra ao redimensionar.
+    const measure = () => setWidth(element.getBoundingClientRect().width)
+
+    measure()
+    const observer = new ResizeObserver(measure)
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [ref])
+
+  return width
+}

package/src/hooks/useConversationRealtime.ts

@@ -10,14 +10,16 @@ export function useConversationRealtime(
   conversationId: string | undefined,
   onEvent: ConversationRealtimeHandler,
 ): void {
-  const context = useConversations()
+  const sse = useConversations()?.sse
   const onEventRef = useRef(onEvent)
   onEventRef.current = onEvent
 
+  // Depende da porta SSE, não do objeto de contexto inteiro: reabrir o stream é caro (um ticket por
+  // abertura) e o contexto é o que mais muda de identidade quando o host renderiza.
   useEffect(() => {
-    if (!context || !conversationId) return
+    if (!sse || !conversationId) return
 
-    const source = context.sse.connectConversationStream(conversationId)
+    const source = sse.connectConversationStream(conversationId)
     const handler = (event: MessageEvent) => onEventRef.current(event)
     source.addEventListener('message', handler)
 
@@ -25,20 +27,20 @@ export function useConversationRealtime(
       source.removeEventListener('message', handler)
       source.close()
     }
-  }, [context, conversationId])
+  }, [sse, conversationId])
 }
 
 // Assina o stream global (ex: novas conversas entrando na fila, notificações cross-conversa)
 // — mesma porta SSEProvider, sem conversationId.
 export function useGlobalRealtime(onEvent: ConversationRealtimeHandler): void {
-  const context = useConversations()
+  const sse = useConversations()?.sse
   const onEventRef = useRef(onEvent)
   onEventRef.current = onEvent
 
   useEffect(() => {
-    if (!context) return
+    if (!sse) return
 
-    const source = context.sse.connectGlobalStream()
+    const source = sse.connectGlobalStream()
     const handler = (event: MessageEvent) => onEventRef.current(event)
     source.addEventListener('message', handler)
 
@@ -46,5 +48,5 @@ export function useGlobalRealtime(onEvent: ConversationRealtimeHandler): void {
       source.removeEventListener('message', handler)
       source.close()
     }
-  }, [context])
+  }, [sse])
 }

package/src/icon.constant.ts

@@ -0,0 +1,12 @@
+/**
+ * Tamanhos de ícone da UI de conversas, em px, na escala de 4 da grade.
+ *
+ * Ícone vem da biblioteca (lucide), nunca emoji. Emoji desenha diferente em cada sistema
+ * operacional, não herda `currentColor` — então não acompanha o estado do controle (ativo,
+ * desabilitado, variante destrutiva) — e não escala com o token de tipografia. Numa mesma faixa,
+ * metade emoji e metade SVG lê como duas famílias de botão.
+ */
+
+export const ICON_SIZE_PILL = 12
+export const ICON_SIZE_INLINE = 14
+export const ICON_SIZE_ACTION = 16

package/src/index.ts

@@ -28,6 +28,7 @@ export { DateDivider } from './DateDivider'
 export { Avatar, DEFAULT_AVATAR_LABELS } from './Avatar'
 export { ConversationListItem, DEFAULT_CONVERSATION_LIST_ITEM_LABELS } from './ConversationListItem'
 export { ToastProvider, useToast, toast } from './Toast'
+export { TooltipLayer, TOOLTIP_ATTRIBUTE } from './Tooltip'
 
 export { StatusTicks } from './StatusTicks'
 export { Lightbox, DEFAULT_LIGHTBOX_LABELS } from './Lightbox'

package/src/lib/composer-formatting.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  FORMATTING_ACTION,
+  FORMATTING_SEPARATOR,
+  activeFormattingIn,
+  canExecuteFormattingCommand,
+  isFormattingActive,
+  toggleFormattingCommand,
+} from './composer-formatting'
+import { ZERO_WIDTH_SPACE, htmlToWA, waToHTML } from './whatsapp-formatting'
+
+describe('isFormattingActive', () => {
+  it('reconhece cada formatação dentro do conjunto ativo', () => {
+    const active = [FORMATTING_ACTION.BOLD, FORMATTING_ACTION.MONOSPACE].join(FORMATTING_SEPARATOR)
+
+    expect(isFormattingActive({ active, action: FORMATTING_ACTION.BOLD })).toBe(true)
+    expect(isFormattingActive({ active, action: FORMATTING_ACTION.MONOSPACE })).toBe(true)
+    expect(isFormattingActive({ active, action: FORMATTING_ACTION.ITALIC })).toBe(false)
+  })
+
+  it('não acende nada quando o conjunto está vazio', () => {
+    expect(isFormattingActive({ active: '', action: FORMATTING_ACTION.BOLD })).toBe(false)
+  })
+})
+
+describe('activeFormattingIn', () => {
+  it('não acende nada quando não há seleção no documento', () => {
+    const editor = { contains: () => false } as unknown as HTMLElement
+
+    expect(activeFormattingIn(editor)).toBe('')
+  })
+})
+
+describe('toggleFormattingCommand', () => {
+  it('avisa que não executou onde o comando não existe, para o campo cair no wrap manual', () => {
+    if (canExecuteFormattingCommand()) return
+    expect(toggleFormattingCommand(FORMATTING_ACTION.BOLD)).toBe(false)
+  })
+
+  it('não tem comando nativo para monoespaçado', () => {
+    expect(toggleFormattingCommand(FORMATTING_ACTION.MONOSPACE)).toBe(false)
+  })
+})
+
+describe('waToHTML dentro do campo editável', () => {
+  it('escreve o tachado como <s>, que é o que o navegador consegue desfazer', () => {
+    expect(waToHTML('~riscado~')).toBe('<s>riscado</s>')
+  })
+
+  it('mantém o ida e volta do tachado', () => {
+    expect(htmlToWA(waToHTML('~riscado~'))).toBe('~riscado~')
+  })
+})
+
+describe('htmlToWA e a âncora do cursor', () => {
+  it('descarta o código que só tem a âncora, para não sair um par de crases vazio', () => {
+    expect(htmlToWA(`oi <code>${ZERO_WIDTH_SPACE}</code>`)).toBe('oi')
+  })
+
+  it('tira a âncora de dentro do código que o operador chegou a preencher', () => {
+    expect(htmlToWA(`<code>${ZERO_WIDTH_SPACE}npm run dev</code>`)).toBe('`npm run dev`')
+  })
+
+  it('não deixa a âncora vazar para o texto enviado', () => {
+    expect(htmlToWA(`oi${ZERO_WIDTH_SPACE} tudo bem`)).toBe('oi tudo bem')
+  })
+})
+
+describe('htmlToWA com a marcação do navegador', () => {
+  it('converte o <strike> do execCommand para o tachado do WhatsApp', () => {
+    expect(htmlToWA('<strike>cancelado</strike>')).toBe('~cancelado~')
+  })
+
+  it('converte o <b> e o <i> do navegador junto com as nossas tags', () => {
+    expect(htmlToWA('<b>oi</b> <i>tudo</i> <strong>bem</strong>')).toBe('*oi* _tudo_ *bem*')
+  })
+})

package/src/lib/composer-formatting.ts

@@ -0,0 +1,145 @@
+/**
+ * Estado e alternância da formatação dentro do campo rico.
+ *
+ * O botão precisa responder duas perguntas que o wrap manual não respondia: o cursor está dentro de
+ * um negrito? e, se está, como saio dele? `execCommand` é depreciado mas continua sendo o único
+ * caminho que alterna a formatação do cursor vazio — sem ele, ligar o negrito antes de digitar não
+ * existe, e era por isso que os botões não pareciam acender nem apagar.
+ *
+ * `queryCommandState` responde pelo estilo computado, então acende igual para `<strong>` (nosso) e
+ * `<b>` (do navegador). Onde o ambiente não tem as duas APIs — jsdom, teste — as funções avisam, e
+ * quem chama volta ao wrap manual.
+ */
+
+import { COMPOSER_MONOSPACE_CLASS } from '../composer.constant'
+import { ZERO_WIDTH_SPACE } from './whatsapp-formatting'
+
+export const FORMATTING_ACTION = {
+  BOLD: 'bold',
+  ITALIC: 'italic',
+  STRIKETHROUGH: 'strikethrough',
+  MONOSPACE: 'monospace',
+} as const
+export type FormattingAction = (typeof FORMATTING_ACTION)[keyof typeof FORMATTING_ACTION]
+
+/** Monoespaçado fica de fora: não existe comando nativo, o campo trata à mão. */
+const EXEC_COMMAND_BY_ACTION = {
+  [FORMATTING_ACTION.BOLD]: 'bold',
+  [FORMATTING_ACTION.ITALIC]: 'italic',
+  [FORMATTING_ACTION.STRIKETHROUGH]: 'strikeThrough',
+} as const
+
+/**
+ * O conjunto ativo viaja como string separada para o React comparar por valor: um `Set` novo a cada
+ * movimento do cursor rerenderizaria a barra inteira sem nada ter mudado.
+ */
+export const FORMATTING_SEPARATOR = '|'
+
+interface EditorNodeParams {
+  readonly node: Node
+  readonly editor: HTMLElement
+}
+
+/** O `<code>` que envolve o cursor, se houver — a marcação de monoespaçado que damos ao texto. */
+export function codeAncestorOf({ node, editor }: EditorNodeParams): HTMLElement | undefined {
+  let current: Node | null = node
+
+  while (current && current !== editor) {
+    if (current instanceof HTMLElement && current.tagName === 'CODE') return current
+    current = current.parentNode
+  }
+
+  return undefined
+}
+
+function canQueryCommandState(): boolean {
+  return typeof document !== 'undefined' && typeof document.queryCommandState === 'function'
+}
+
+export function canExecuteFormattingCommand(): boolean {
+  return typeof document !== 'undefined' && typeof document.execCommand === 'function'
+}
+
+function isCommandActive(command: string): boolean {
+  if (!canQueryCommandState()) return false
+  try {
+    return document.queryCommandState(command)
+  } catch {
+    // Fora de um campo editável o navegador lança em vez de responder `false`.
+    return false
+  }
+}
+
+export function activeFormattingIn(editor: HTMLElement): string {
+  const selection = typeof window !== 'undefined' ? window.getSelection() : null
+  const anchor = selection?.anchorNode
+  // Cursor fora do campo: nenhum botão aceso, senão a barra descreveria a seleção de outro lugar.
+  if (!anchor || !editor.contains(anchor)) return ''
+
+  const active: FormattingAction[] = []
+  for (const [action, command] of Object.entries(EXEC_COMMAND_BY_ACTION)) {
+    if (isCommandActive(command)) active.push(action as FormattingAction)
+  }
+  if (codeAncestorOf({ node: anchor, editor })) active.push(FORMATTING_ACTION.MONOSPACE)
+
+  return active.join(FORMATTING_SEPARATOR)
+}
+
+export function isFormattingActive({ active, action }: { active: string; action: FormattingAction }): boolean {
+  return active.split(FORMATTING_SEPARATOR).includes(action)
+}
+
+/**
+ * Liga o monoespaçado no cursor vago: abre o `<code>` e põe o cursor lá dentro, ancorado no espaço
+ * de largura zero — sem a âncora não há onde o cursor pousar, e o próximo caractere sai de fora.
+ * A âncora some na conversão para a notação do WhatsApp.
+ */
+export function startMonospaceAt(range: Range): void {
+  const code = document.createElement('code')
+  code.className = COMPOSER_MONOSPACE_CLASS
+  code.textContent = ZERO_WIDTH_SPACE
+  range.deleteContents()
+  range.insertNode(code)
+  placeCaretAfter(code.firstChild as Text, ZERO_WIDTH_SPACE.length)
+}
+
+/**
+ * Desliga o monoespaçado do cursor vago. Só mover o cursor para depois do `</code>` não basta — o
+ * navegador o traz de volta para dentro; é preciso uma âncora do lado de fora para ele pousar.
+ */
+export function exitMonospaceAfter(code: HTMLElement): void {
+  const anchor = document.createTextNode(ZERO_WIDTH_SPACE)
+  code.after(anchor)
+  placeCaretAfter(anchor, ZERO_WIDTH_SPACE.length)
+}
+
+/** Tira a marcação e devolve o texto ao redor — o que o clique com seleção dentro do código faz. */
+export function unwrapMonospace(code: HTMLElement): void {
+  code.replaceWith(document.createTextNode(code.textContent?.replace(ZERO_WIDTH_SPACE, '') ?? ''))
+}
+
+function placeCaretAfter(node: Text, offset: number): void {
+  const caret = document.createRange()
+  caret.setStart(node, offset)
+  caret.collapse(true)
+  const selection = window.getSelection()
+  selection?.removeAllRanges()
+  selection?.addRange(caret)
+}
+
+/**
+ * Alterna a formatação pelo navegador. Devolve `false` quando o comando não existe no ambiente,
+ * para o campo cair no wrap manual em vez de engolir o clique.
+ */
+export function toggleFormattingCommand(action: FormattingAction): boolean {
+  const command = EXEC_COMMAND_BY_ACTION[action as keyof typeof EXEC_COMMAND_BY_ACTION]
+  if (!command || !canExecuteFormattingCommand()) return false
+
+  try {
+    // Sem isto o Chrome escreve `<span style="font-weight:bold">`, que não sobrevive ao htmlToWA.
+    document.execCommand('styleWithCSS', false, 'false')
+    return document.execCommand(command)
+  } catch {
+    return false
+  }
+}