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

package/src/flows/FlowsWorkspace.tsx

@@ -24,6 +24,16 @@ import { FlowNodePanel } from './FlowNodePanel'
 import { FlowPalette, type FlowPaletteActionOption, type NewNodeSpec } from './FlowPalette'
 import { FlowMapCanvas } from './FlowMapCanvas'
 import { mergeFlowEditorLabels, type FlowEditorLabels } from './labels'
+// Operações puras do grafo, com teste próprio. As decisões que elas tomam não dão erro quando estão
+// erradas: dão aresta apontando para nó apagado, ou salto que o motor do bot ignora.
+import {
+  applyConnection,
+  mergedFlowKeysFrom,
+  namespaceNodeId,
+  parseNamespacedId,
+  removeNodeAndCleanRefs,
+  resolveConnection,
+} from './flowEditorOps'
 import {
   computeAutoLayout,
   slugifyNodeId,
@@ -40,6 +50,7 @@ import {
   type FlowNodeData,
   type GraphIssue,
 } from './flowGraph'
+import { TooltipLayer } from '../Tooltip'
 
 const RF_NODE_TYPES = {
   ...flowNodeTypes,
@@ -118,20 +129,6 @@ function portalNodeId(sourceId: string, target: string): string {
   return `__portal__${sourceId}__${target}`
 }
 
-// Namespacing de ids: com fusão editável, nós de fluxos diferentes convivem no mesmo canvas
-// React Flow, que exige ids únicos globalmente — "flowKey::nodeId" evita colisão entre fluxos
-// que reutilizem o mesmo id de nó (ex.: vários fluxos com um nó "root").
-function ns(flowKey: string, nodeId: string): string {
-  return `${flowKey}${NS_SEP}${nodeId}`
-}
-
-function parseNs(id: string): { flowKey: string; nodeId: string } {
-  const index = id.indexOf(NS_SEP)
-  return index === -1
-    ? { flowKey: '', nodeId: id }
-    : { flowKey: id.slice(0, index), nodeId: id.slice(index + NS_SEP.length) }
-}
-
 // Um fluxo aberto no canvas de detalhe — o primeiro da lista é o "primário" (dono da paleta,
 // organizar, publicar e excluir-fluxo); os demais chegaram por fusão editável (clique num portal)
 // e ficam com um cabeçalho flutuante pra focar neles sozinhos ou fechar.
@@ -141,17 +138,9 @@ type OpenFlow = { key: string; offset: { x: number; y: number } }
 // fluxo já traz junto tudo que ele referencia (e o que essas referências referenciam), sem
 // precisar clicar em cada portal manualmente.
 function autoMergeAll(rootKey: string, graphsSource: Record<string, FlowGraphData>): OpenFlow[] {
-  const visited = new Set<string>()
-  const queue = [rootKey]
-  while (queue.length > 0) {
-    const key = queue.shift()!
-    if (visited.has(key) || !graphsSource[key]) continue
-    visited.add(key)
-    for (const target of crossFlowTargetsOf(graphsSource[key]!)) {
-      if (!visited.has(target) && graphsSource[target]) queue.push(target)
-    }
-  }
-  return [...visited].map((key) => ({ key, offset: { x: 0, y: 0 } }))
+  // O fecho em si vem de `flowEditorOps`, que é onde ele tem teste — inclusive para o caso mais banal
+  // que existe, o fluxo que volta a si mesmo.
+  return mergedFlowKeysFrom(rootKey, graphsSource).map((key) => ({ key, offset: { x: 0, y: 0 } }))
 }
 
 // Layout único pra TODOS os nós de TODOS os fluxos abertos juntos — ao contrário de posicionar
@@ -170,7 +159,7 @@ function computeMergedLayout(
   for (const { key } of openFlows) {
     const graph = workingGraphs[key]
     if (!graph) continue
-    for (const node of Object.values(graph.nodes)) nodeByNsId.set(ns(key, node.id), node)
+    for (const node of Object.values(graph.nodes)) nodeByNsId.set(namespaceNodeId(key, node.id), node)
   }
 
   function forwardEdges(flowKey: string, node: FlowNodeData): string[] {
@@ -179,9 +168,9 @@ function computeMergedLayout(
       if (isCrossFlowTarget(target)) {
         const targetFlowKey = crossFlowKey(target)
         const targetGraph = openKeys.has(targetFlowKey) ? workingGraphs[targetFlowKey] : undefined
-        if (targetGraph) result.push(ns(targetFlowKey, targetGraph.startNodeId))
+        if (targetGraph) result.push(namespaceNodeId(targetFlowKey, targetGraph.startNodeId))
       } else if (workingGraphs[flowKey]?.nodes[target]) {
-        result.push(ns(flowKey, target))
+        result.push(namespaceNodeId(flowKey, target))
       }
     }
     return result
@@ -189,7 +178,7 @@ function computeMergedLayout(
 
   const rank = new Map<string, number>()
   const primaryGraph = workingGraphs[primaryFlowKey]
-  const rootId = primaryGraph ? ns(primaryFlowKey, primaryGraph.startNodeId) : undefined
+  const rootId = primaryGraph ? namespaceNodeId(primaryFlowKey, primaryGraph.startNodeId) : undefined
   if (rootId && nodeByNsId.has(rootId)) {
     rank.set(rootId, 0)
     const queue = [rootId]
@@ -197,7 +186,7 @@ function computeMergedLayout(
       const id = queue.shift()!
       const node = nodeByNsId.get(id)
       if (!node) continue
-      for (const nextId of forwardEdges(parseNs(id).flowKey, node)) {
+      for (const nextId of forwardEdges(parseNamespacedId(id).flowKey, node)) {
         if (!rank.has(nextId)) {
           rank.set(nextId, rank.get(id)! + 1)
           queue.push(nextId)
@@ -269,6 +258,12 @@ function buildAllEdges(
     for (const [id, node] of Object.entries(graph.nodes)) {
       const isLive = (liveCounts[id] ?? 0) > 0
       for (const { target, optionId, isDefault } of targetsOf(node)) {
+        // Destino vazio é estado NORMAL, não anomalia: apagar um nó zera quem apontava para ele, e
+        // `targetsOf` devolve o `default` mesmo em branco. Sem esta linha a aresta ia para um nó que
+        // não existe, o React Flow a descartava em silêncio, e a opção parecia ligada sem estar — a
+        // conversa do cliente para ali e quem editou não vê nada de errado.
+        if (!target) continue
+
         const crossFlow = isCrossFlowTarget(target)
         let targetFlowKey = flowKey
         let rawTargetId = target
@@ -282,8 +277,8 @@ function buildAllEdges(
             rawTargetId = portalNodeId(id, target)
           }
         }
-        const source = ns(flowKey, id)
-        const edgeTarget = ns(targetFlowKey, rawTargetId)
+        const source = namespaceNodeId(flowKey, id)
+        const edgeTarget = namespaceNodeId(targetFlowKey, rawTargetId)
 
         if (optionId === undefined && !isDefault) {
           const color = crossFlow ? EDGE_COLOR_CROSS_FLOW : isLive ? EDGE_COLOR_LIVE : EDGE_COLOR_LINEAR
@@ -357,35 +352,6 @@ function newNodeFromSpec(spec: NewNodeSpec, existingIds: Set<string>): FlowNodeD
   return { id, type: 'action', actionKind: spec.actionKind }
 }
 
-// Remove referências ao nó excluído: destinos apontando para ele viram '' (destino vazio),
-// para a validação sinalizar claramente em vez de manter uma string órfã silenciosa.
-function removeNodeAndCleanRefs(
-  nodes: Record<string, FlowNodeData>,
-  nodeId: string,
-): Record<string, FlowNodeData> {
-  const { [nodeId]: _removed, ...rest } = nodes
-  return Object.fromEntries(
-    Object.entries(rest).map(([id, node]) => {
-      if (!node.next) return [id, node]
-      if (typeof node.next === 'string') {
-        return [id, node.next === nodeId ? { ...node, next: undefined } : node]
-      }
-      return [
-        id,
-        {
-          ...node,
-          next: {
-            byAnswer: Object.fromEntries(
-              Object.entries(node.next.byAnswer).map(([key, value]) => [key, value === nodeId ? '' : value]),
-            ),
-            default: node.next.default === nodeId ? '' : node.next.default,
-          },
-        },
-      ]
-    }),
-  )
-}
-
 function extractErrorMessage(error: unknown): string | undefined {
   if (error instanceof Error) return error.message
   return undefined
@@ -637,7 +603,7 @@ export function FlowsWorkspace({
 
       function resolvePosition(nodeId: string): { x: number; y: number } {
         if (mergedPositions) {
-          const nsId = ns(flowKey, nodeId)
+          const nsId = namespaceNodeId(flowKey, nodeId)
           return renderedPositionsRef.current.get(nsId) ?? mergedPositions.get(nsId) ?? { x: 0, y: 0 }
         }
         const local = graph!.nodes[nodeId]?.position ?? fallbackPositions[nodeId] ?? { x: 0, y: 0 }
@@ -647,7 +613,7 @@ export function FlowsWorkspace({
       for (const node of Object.values(graph.nodes)) {
         const position = resolvePosition(node.id)
         allNodes.push({
-          id: ns(flowKey, node.id),
+          id: namespaceNodeId(flowKey, node.id),
           type: 'flowNode',
           position,
           draggable: true,
@@ -672,7 +638,7 @@ export function FlowsWorkspace({
           const targetFlowKey = crossFlowKey(target)
           if (openFlows.some((flow) => flow.key === targetFlowKey)) return
           allNodes.push({
-            id: ns(flowKey, portalNodeId(node.id, target)),
+            id: namespaceNodeId(flowKey, portalNodeId(node.id, target)),
             type: 'flowPortal',
             draggable: false,
             selectable: false,
@@ -696,7 +662,7 @@ export function FlowsWorkspace({
         const minY = Math.min(...positions.map((point) => point.y))
         const maxY = Math.max(...positions.map((point) => point.y)) + estimateNodeHeight(graph.nodes[chain.actionNodeId]!)
         allNodes.push({
-          id: ns(flowKey, `__chain__${chain.actionNodeId}`),
+          id: namespaceNodeId(flowKey, `__chain__${chain.actionNodeId}`),
           type: 'flowGroupFrame',
           draggable: false,
           selectable: false,
@@ -717,7 +683,7 @@ export function FlowsWorkspace({
       if (!isPrimary) {
         const startPosition = resolvePosition(graph.startNodeId)
         allNodes.push({
-          id: ns(flowKey, '__group_header__'),
+          id: namespaceNodeId(flowKey, '__group_header__'),
           type: 'flowGroupHeader',
           draggable: false,
           selectable: false,
@@ -777,10 +743,21 @@ export function FlowsWorkspace({
   const onNodeDragStop = useCallback(
     (_event: unknown, node: Node) => {
       renderedPositionsRef.current.set(node.id, node.position)
-      const { flowKey, nodeId } = parseNs(node.id)
+      const { flowKey, nodeId } = parseNamespacedId(node.id)
       const openFlow = openFlows.find((flow) => flow.key === flowKey)
       if (!openFlow) return
-      const localPosition = { x: node.position.x - openFlow.offset.x, y: node.position.y - openFlow.offset.y }
+
+      /**
+       * O deslocamento só entra na conta quando ele foi usado para DESENHAR.
+       *
+       * Com mais de um fluxo aberto o layout mesclado posiciona tudo em coordenadas absolutas e
+       * ignora `offset` — subtrair aqui gravava no grafo uma posição que nunca foi a do card. O
+       * sintoma aparecia só depois: recarregar a tela e achar o nó deslocado sozinho.
+       */
+      const drawnWithOffset = openFlows.length === 1
+      const localPosition = drawnWithOffset
+        ? { x: node.position.x - openFlow.offset.x, y: node.position.y - openFlow.offset.y }
+        : node.position
       updateFlow(flowKey, (graph) =>
         graph.nodes[nodeId]
           ? { ...graph, nodes: { ...graph.nodes, [nodeId]: { ...graph.nodes[nodeId]!, position: localPosition } } }
@@ -792,36 +769,18 @@ export function FlowsWorkspace({
 
   const onConnect = useCallback(
     (connection: Connection) => {
-      const { source, sourceHandle, target } = connection
-      if (!source || !target || source === target) return
-      const sourceRef = parseNs(source)
-      const targetRef = parseNs(target)
-
-      // Conectar num nó de outro fluxo só faz sentido se for o nó inicial dele — vira um salto
-      // "flow:<key>" (o motor do bot não sabe pular pra um nó específico de outro fluxo, só
-      // pro início). Conectar num nó do meio de outro fluxo é ignorado silenciosamente.
-      let targetValue: string
-      if (targetRef.flowKey === sourceRef.flowKey) {
-        targetValue = targetRef.nodeId
-      } else {
-        const targetGraph = workingGraphs[targetRef.flowKey]
-        if (!targetGraph || targetGraph.startNodeId !== targetRef.nodeId) return
-        targetValue = `${CROSS_FLOW_PREFIX}${targetRef.flowKey}`
-      }
+      // Traduzir o arraste e aplicar no nó são as duas decisões que mandam a conversa do cliente
+      // para o lugar certo ou errado, sem erro no meio — por isso vivem em `flowEditorOps`, testadas.
+      const resolved = resolveConnection({
+        connection: { source: connection.source, target: connection.target, sourceHandle: connection.sourceHandle },
+        graphs: workingGraphs,
+      })
+      if (!resolved) return
 
-      updateFlow(sourceRef.flowKey, (graph) => {
-        const node = graph.nodes[sourceRef.nodeId]
+      updateFlow(resolved.flowKey, (graph) => {
+        const node = graph.nodes[resolved.nodeId]
         if (!node) return graph
-        const handle = sourceHandle ?? 'next'
-        const currentByAnswer = typeof node.next === 'object' && node.next ? node.next.byAnswer : {}
-        const currentDefault = typeof node.next === 'object' && node.next ? node.next.default : ''
-        const updatedNode: FlowNodeData =
-          handle === 'next'
-            ? { ...node, next: targetValue }
-            : handle === '__default'
-              ? { ...node, next: { byAnswer: currentByAnswer, default: targetValue } }
-              : { ...node, next: { byAnswer: { ...currentByAnswer, [handle]: targetValue }, default: currentDefault } }
-        return { ...graph, nodes: { ...graph.nodes, [sourceRef.nodeId]: updatedNode } }
+        return { ...graph, nodes: { ...graph.nodes, [resolved.nodeId]: applyConnection(node, resolved) } }
       })
     },
     [workingGraphs, updateFlow],
@@ -834,7 +793,7 @@ export function FlowsWorkspace({
     newNode.position = { x: 0, y: maxY + 170 }
     updateFlow(primaryFlowKey, (graph) => ({ ...graph, nodes: { ...graph.nodes, [newNode.id]: newNode } }))
     setEditingRef({ flowKey: primaryFlowKey, nodeId: newNode.id })
-    setPendingFocusNodeId(ns(primaryFlowKey, newNode.id))
+    setPendingFocusNodeId(namespaceNodeId(primaryFlowKey, newNode.id))
   }
 
   function handleNodePanelChange(updated: FlowNodeData) {
@@ -862,7 +821,7 @@ export function FlowsWorkspace({
           ...graph,
           nodes: Object.fromEntries(
             Object.entries(graph.nodes).map(([id, node]) => {
-              const position = positions.get(ns(key, id))
+              const position = positions.get(namespaceNodeId(key, id))
               return [
                 id,
                 position ? { ...node, position: { x: position.x - offset.x, y: position.y - offset.y } } : node,
@@ -966,6 +925,7 @@ export function FlowsWorkspace({
 
   return (
     <div className={`space-y-4 h-full flex flex-col ${className ?? ''}`}>
+      <TooltipLayer />
       <div className="flex items-center justify-between flex-wrap gap-3">
         <div>
           <h2 className="text-2xl font-bold text-gray-900 dark:text-gray-100">{labels.workspace.title}</h2>
@@ -977,6 +937,7 @@ export function FlowsWorkspace({
             <span className="text-sm text-red-600">{saveErrorMessage ?? labels.workspace.saveError}</span>
           )}
           <button
+            data-cv-tooltip={viewMode === 'map' ? labels.flowMap.toggleToDetail : labels.flowMap.toggleToMap} aria-label={viewMode === 'map' ? labels.flowMap.toggleToDetail : labels.flowMap.toggleToMap}
             type="button"
             onClick={() => setViewMode((mode) => (mode === 'map' ? 'detail' : 'map'))}
             className={OUTLINE_BUTTON}
@@ -990,7 +951,7 @@ export function FlowsWorkspace({
                 type="button"
                 onClick={handleOrganize}
                 className={OUTLINE_BUTTON}
-                title={labels.workspace.organizeTooltip}
+                data-cv-tooltip={labels.workspace.organizeTooltip} aria-label={labels.workspace.organizeTooltip}
                 disabled={!primaryGraph}
               >
                 <LayoutGrid size={14} aria-hidden="true" /> {labels.workspace.organize}
@@ -999,12 +960,13 @@ export function FlowsWorkspace({
                 type="button"
                 onClick={handleDiscardChanges}
                 className={OUTLINE_BUTTON}
-                title={labels.workspace.discardTooltip}
+                data-cv-tooltip={labels.workspace.discardTooltip} aria-label={labels.workspace.discardTooltip}
                 disabled={!isDirty || saveState === 'saving'}
               >
                 <Undo2 size={14} aria-hidden="true" /> {labels.workspace.discardChanges}
               </button>
               <button
+                data-cv-tooltip={labels.workspace.saveGraph} aria-label={labels.workspace.saveGraph}
                 type="button"
                 onClick={() => void handlePublish()}
                 className={PRIMARY_BUTTON}
@@ -1024,6 +986,7 @@ export function FlowsWorkspace({
             {graphs &&
               Object.values(graphs).map((graph) => (
                 <button
+                  data-cv-tooltip={graph.label} aria-label={graph.label}
                   key={graph.key}
                   type="button"
                   onClick={() => focusFlow(graph.key)}
@@ -1038,6 +1001,7 @@ export function FlowsWorkspace({
               ))}
             {canCreateFlow && (
               <button
+                data-cv-tooltip={labels.flowManager.newFlow} aria-label={labels.flowManager.newFlow}
                 type="button"
                 onClick={() => {
                   setFlowMutationState({ pending: false })
@@ -1059,6 +1023,7 @@ export function FlowsWorkspace({
             )}
             {primaryGraph && canDeleteFlow && (
               <button
+                data-cv-tooltip={labels.flowManager.deleteFlow} aria-label={labels.flowManager.deleteFlow}
                 type="button"
                 onClick={() => {
                   setFlowMutationState({ pending: false })
@@ -1186,10 +1151,11 @@ export function FlowsWorkspace({
             {flowMutationState.error && <p className="text-xs text-red-600">{flowMutationState.error}</p>}
           </div>
           <div className="flex justify-end gap-2 mt-4">
-            <button type="button" className={OUTLINE_BUTTON} onClick={() => setShowCreateDialog(false)}>
+            <button data-cv-tooltip={labels.nodePanel.cancel} aria-label={labels.nodePanel.cancel} type="button" className={OUTLINE_BUTTON} onClick={() => setShowCreateDialog(false)}>
               {labels.nodePanel.cancel}
             </button>
             <button
+              data-cv-tooltip={labels.flowManager.create} aria-label={labels.flowManager.create}
               type="button"
               className={PRIMARY_BUTTON}
               onClick={() => void handleCreateFlow()}
@@ -1208,10 +1174,11 @@ export function FlowsWorkspace({
           </p>
           {flowMutationState.error && <p className="text-xs text-red-600 mt-2">{flowMutationState.error}</p>}
           <div className="flex justify-end gap-2 mt-4">
-            <button type="button" className={OUTLINE_BUTTON} onClick={() => setShowDeleteDialog(false)}>
+            <button data-cv-tooltip={labels.nodePanel.cancel} aria-label={labels.nodePanel.cancel} type="button" className={OUTLINE_BUTTON} onClick={() => setShowDeleteDialog(false)}>
               {labels.nodePanel.cancel}
             </button>
             <button
+              data-cv-tooltip={labels.flowManager.deleteFlow} aria-label={labels.flowManager.deleteFlow}
               type="button"
               className="inline-flex items-center gap-1.5 rounded-lg bg-red-600 px-3 py-1.5 text-xs font-medium text-white hover:bg-red-700 disabled:opacity-40"
               onClick={() => void handleDeleteFlow()}

package/src/flows/flowEditorOps.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Estas funções decidem o que acontece com o fluxo que alguém desenhou, e o modo de falhar delas é
+ * silencioso: aresta apontando para nó apagado não dá erro no editor — dá conversa travada no meio
+ * para o cliente. Salto para nó do meio de outro fluxo não dá erro — o motor simplesmente ignora, e
+ * o atendimento para sem ninguém entender.
+ *
+ * São puras de propósito: rodam sem navegador, sem React e sem estado, o que é exatamente o que
+ * faltava enquanto elas viviam dentro de uma página de 973 linhas.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import type { FlowGraphData, FlowNodeData } from '@adatechnology/meta-whatsapp-contracts'
+
+import {
+  applyConnection,
+  isGraphDirty,
+  mergedFlowKeysFrom,
+  namespaceNodeId,
+  parseNamespacedId,
+  removeNodeAndCleanRefs,
+  resolveConnection,
+} from './flowEditorOps'
+
+/** Nó mínimo VÁLIDO pelo contrato — sem `as`, para o teste falhar se a forma do nó mudar. */
+function node(id: string, next?: FlowNodeData['next']): FlowNodeData {
+  return { id, type: 'question', question: id, ...(next === undefined ? {} : { next }) }
+}
+
+/**
+ * Grafo mínimo VÁLIDO. `key` e `version` são obrigatórios no contrato, e sem `as` o teste passa a
+ * quebrar quando o contrato ganhar campo novo — que é exatamente o drift que o comentário do
+ * `flowGraph.ts` registra ter acontecido antes com o `version`.
+ */
+function graph(params: { key: string; start: string; nodes: FlowNodeData[] }): FlowGraphData {
+  return {
+    key: params.key,
+    label: params.key,
+    version: 1,
+    startNodeId: params.start,
+    nodes: Object.fromEntries(params.nodes.map((each) => [each.id, each])),
+  }
+}
+
+describe('id no canvas mesclado', () => {
+  it('vai e volta', () => {
+    expect(parseNamespacedId(namespaceNodeId('menu', 'inicio'))).toEqual({ flowKey: 'menu', nodeId: 'inicio' })
+  })
+
+  it('nó com separador no próprio id não parte errado', () => {
+    // O separador aparece no PRIMEIRO índice: um id que contenha `::` continua íntegro.
+    expect(parseNamespacedId('menu::passo::dois')).toEqual({ flowKey: 'menu', nodeId: 'passo::dois' })
+  })
+
+  it('id sem prefixo devolve fluxo vazio, em vez de adivinhar', () => {
+    expect(parseNamespacedId('inicio')).toEqual({ flowKey: '', nodeId: 'inicio' })
+  })
+})
+
+describe('apagar nó limpa quem apontava para ele', () => {
+  it('saída única que ia para o apagado fica vazia, não pendurada', () => {
+    const nodes = { a: node('a', 'b'), b: node('b') }
+
+    const result = removeNodeAndCleanRefs(nodes, 'b')
+
+    expect(Object.keys(result)).toEqual(['a'])
+    // Vazio e não `'b'`: aresta para nó inexistente trava a conversa no motor do bot.
+    expect(result.a?.next).toBe('')
+  })
+
+  it('ramificação perde o destino mas MANTÉM a opção', () => {
+    const nodes = {
+      pergunta: node('pergunta', { byAnswer: { sim: 'aprovado', nao: 'recusado' }, default: 'aprovado' }),
+      aprovado: node('aprovado'),
+      recusado: node('recusado'),
+    }
+
+    const result = removeNodeAndCleanRefs(nodes, 'aprovado')
+    const next = result.pergunta?.next as { byAnswer: Record<string, string>; default: string }
+
+    // A chave `sim` continua existindo com destino vazio: removê-la esconderia da tela que a opção
+    // existe e não leva a lugar nenhum, e alguém publicaria assim.
+    expect(next.byAnswer).toEqual({ sim: '', nao: 'recusado' })
+    expect(next.default).toBe('')
+  })
+
+  it('não mexe em quem não apontava para o apagado', () => {
+    const nodes = { a: node('a', 'c'), b: node('b'), c: node('c') }
+
+    expect(removeNodeAndCleanRefs(nodes, 'b').a?.next).toBe('c')
+  })
+
+  it('nó sem next segue sem next, e não ganha um vazio', () => {
+    expect(removeNodeAndCleanRefs({ a: node('a'), b: node('b') }, 'b').a?.next).toBeUndefined()
+  })
+})
+
+describe('fecho transitivo dos fluxos abertos juntos', () => {
+  const graphs = {
+    menu: graph({ key: 'menu', start: 'inicio', nodes: [node('inicio', 'flow:simulacao')] }),
+    simulacao: graph({ key: 'simulacao', start: 's1', nodes: [node('s1', 'flow:documentos')] }),
+    documentos: graph({ key: 'documentos', start: 'd1', nodes: [node('d1')] }),
+    orfao: graph({ key: 'orfao', start: 'o1', nodes: [node('o1')] }),
+  }
+
+  it('alcança em profundidade e ignora quem ninguém referencia', () => {
+    expect([...mergedFlowKeysFrom('menu', graphs)].sort()).toEqual(['documentos', 'menu', 'simulacao'])
+  })
+
+  it('ciclo não estoura — menu que volta ao menu é o caso mais comum que existe', () => {
+    const cyclic = {
+      menu: graph({ key: 'menu', start: 'i', nodes: [node('i', 'flow:sub')] }),
+      sub: graph({ key: 'sub', start: 's', nodes: [node('s', 'flow:menu')] }),
+    }
+
+    expect([...mergedFlowKeysFrom('menu', cyclic)].sort()).toEqual(['menu', 'sub'])
+  })
+
+  it('referência para fluxo que não existe é ignorada em vez de abrir aba vazia', () => {
+    const dangling = { menu: graph({ key: 'menu', start: 'i', nodes: [node('i', 'flow:apagado')] }) }
+
+    expect(mergedFlowKeysFrom('menu', dangling)).toEqual(['menu'])
+  })
+})
+
+describe('conectar aresta', () => {
+  const graphs = {
+    menu: graph({ key: 'menu', start: 'inicio', nodes: [node('inicio'), node('meio')] }),
+    simulacao: graph({ key: 'simulacao', start: 's1', nodes: [node('s1'), node('s2')] }),
+  }
+
+  it('dentro do mesmo fluxo grava o id local', () => {
+    const resolved = resolveConnection({
+      connection: { source: 'menu::inicio', target: 'menu::meio' },
+      graphs,
+    })
+
+    expect(resolved).toMatchObject({ flowKey: 'menu', nodeId: 'inicio', targetValue: 'meio' })
+  })
+
+  it('para o nó INICIAL de outro fluxo grava o salto `flow:`', () => {
+    const resolved = resolveConnection({
+      connection: { source: 'menu::inicio', target: 'simulacao::s1' },
+      graphs,
+    })
+
+    expect(resolved?.targetValue).toBe('flow:simulacao')
+  })
+
+  it('para o MEIO de outro fluxo é RECUSADO — o motor não sabe pular para lá', () => {
+    // Recusa silenciosa é melhor que gravar um salto que o bot ignora em produção: o sintoma seria
+    // conversa parada, longe de quem editou.
+    const resolved = resolveConnection({
+      connection: { source: 'menu::inicio', target: 'simulacao::s2' },
+      graphs,
+    })
+
+    expect(resolved).toBeUndefined()
+  })
+
+  it('nó em si mesmo é recusado', () => {
+    expect(
+      resolveConnection({ connection: { source: 'menu::inicio', target: 'menu::inicio' }, graphs }),
+    ).toBeUndefined()
+  })
+
+  it('fluxo de destino inexistente é recusado', () => {
+    expect(resolveConnection({ connection: { source: 'menu::inicio', target: 'sumiu::x' }, graphs })).toBeUndefined()
+  })
+})
+
+describe('aplicar a conexão no nó', () => {
+  it('handle `next` vira saída única', () => {
+    const result = applyConnection(node('a'), { flowKey: 'menu', nodeId: 'a', handle: 'next', targetValue: 'b' })
+
+    expect(result.next).toBe('b')
+  })
+
+  it('handle de resposta acrescenta no byAnswer e PRESERVA o resto', () => {
+    const existing = node('a', { byAnswer: { sim: 'x' }, default: 'y' })
+
+    const result = applyConnection(existing, { flowKey: 'menu', nodeId: 'a', handle: 'nao', targetValue: 'z' })
+    const next = result.next as { byAnswer: Record<string, string>; default: string }
+
+    expect(next.byAnswer).toEqual({ sim: 'x', nao: 'z' })
+    // O default não pode ser perdido ao ligar um ramo: seria mudança silenciosa de comportamento.
+    expect(next.default).toBe('y')
+  })
+
+  it('handle `__default` troca só o default', () => {
+    const existing = node('a', { byAnswer: { sim: 'x' }, default: 'y' })
+
+    const next = applyConnection(existing, { flowKey: 'menu', nodeId: 'a', handle: '__default', targetValue: 'z' })
+      .next as { byAnswer: Record<string, string>; default: string }
+
+    expect(next).toEqual({ byAnswer: { sim: 'x' }, default: 'z' })
+  })
+
+  it('ramificar um nó que tinha saída única não carrega a antiga como default', () => {
+    // A saída única vira ramificação: o default nasce vazio, e a validação do grafo cobra. Herdar a
+    // antiga faria o ramo não configurado seguir para onde o nó ia antes, sem ninguém pedir.
+    const next = applyConnection(node('a', 'antigo'), {
+      flowKey: 'menu',
+      nodeId: 'a',
+      handle: 'sim',
+      targetValue: 'novo',
+    }).next as { byAnswer: Record<string, string>; default: string }
+
+    expect(next).toEqual({ byAnswer: { sim: 'novo' }, default: '' })
+  })
+})
+
+describe('rascunho sujo', () => {
+  const published = graph({ key: 'menu', start: 'i', nodes: [node('i', 'b'), node('b')] })
+
+  it('igual ao publicado não está sujo', () => {
+    expect(isGraphDirty(structuredClone(published), published)).toBe(false)
+  })
+
+  it('texto mudado está sujo', () => {
+    const working = structuredClone(published)
+    working.nodes.i!.question = 'outro'
+
+    expect(isGraphDirty(working, published)).toBe(true)
+  })
+
+  it('posição mudada TAMBÉM está sujo — arrastar card é edição que se publica', () => {
+    const working = structuredClone(published)
+    working.nodes.i!.position = { x: 10, y: 20 }
+
+    expect(isGraphDirty(working, published)).toBe(true)
+  })
+
+  it('sem rascunho ou sem publicado não está sujo, em vez de sujo por ausência', () => {
+    // Durante o carregamento os dois lados chegam separados; sujo aqui faria a tela pedir
+    // confirmação de descarte antes de o usuário ter tocado em nada.
+    expect(isGraphDirty(undefined, published)).toBe(false)
+    expect(isGraphDirty(published, undefined)).toBe(false)
+  })
+})