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

package/src/flows/flowCanvasModel.ts

@@ -0,0 +1,378 @@
+/**
+ * Derivações puras do canvas do editor: posições, arestas, contagem de conversas vivas e o nó que
+ * nasce de cada item da paleta.
+ *
+ * Viviam dentro do componente, e é ali que estava o risco. Uma aresta com destino errado não pinta
+ * errado — ela leva a conversa do cliente para o lugar errado, e o sintoma aparece longe de quem
+ * editou. Um card que o layout joga para fora da área visível se lê como "apaguei sem querer".
+ *
+ * A topologia sai daqui em forma neutra (`FlowEdgeSpec`) e o estilo fica no componente: o teste cobra
+ * o que importa e roda sem navegador nem `@xyflow/react`. Cor de traço ninguém quebra sem ver.
+ */
+
+import { namespaceNodeId, parseNamespacedId } from './flowEditorOps'
+import {
+  NODE_CARD_WIDTH,
+  cascadeOrder,
+  crossFlowKey,
+  estimateNodeHeight,
+  isCrossFlowTarget,
+  slugifyNodeId,
+  targetsOf,
+  type FlowGraphData,
+  type FlowNodeData,
+} from './flowGraph'
+import type { NewNodeSpec } from './FlowPalette'
+
+const COLUMN_GAP = 360
+const ROW_GAP = 40
+/** O rótulo da moldura é desenhado acima da borda, e precisa de espaço próprio. */
+const CHAIN_LABEL_ROOM = 24
+
+export type FlowNodePosition = { readonly x: number; readonly y: number }
+
+/** Onde cada conversa viva está parada agora — uma linha por sessão. */
+export type FlowLivePosition = {
+  readonly currentState: string
+  readonly flow: string | null
+  readonly nodeId: string | null
+  readonly menuNodeId: string | null
+}
+
+/**
+ * Quantas conversas estão paradas num nó — o formato que o servidor já agrega.
+ *
+ * `meta-whatsapp-module` responde `GROUP BY (flowKey, currentNodeId)`, e trazer uma linha por
+ * sessão só para o editor recontar em memória seria pior em toda base grande. Os dois formatos
+ * valem porque produto que já implementou o de sessão não deve quebrar numa release de correção.
+ */
+export type FlowLiveNodeCount = {
+  readonly flowKey: string
+  readonly nodeId: string
+  readonly count: number
+}
+
+export type FlowLivePositionInput = FlowLivePosition | FlowLiveNodeCount
+
+function isNodeCount(position: FlowLivePositionInput): position is FlowLiveNodeCount {
+  return typeof (position as FlowLiveNodeCount).count === 'number'
+}
+
+/**
+ * Pseudo-nó que representa um fluxo alvo ainda não mesclado no canvas.
+ *
+ * Um portal por (nó de origem, fluxo alvo): duas opções do mesmo nó indo para o mesmo fluxo
+ * compartilham o portal, senão o card ficaria cercado de caixas idênticas.
+ */
+export function portalNodeId(sourceNodeId: string, target: string): string {
+  return `__portal__${sourceNodeId}__${target}`
+}
+
+export function chainFrameNodeId(actionNodeId: string): string {
+  return `__chain__${actionNodeId}`
+}
+
+export const GROUP_HEADER_NODE_ID = '__group_header__'
+
+/**
+ * Quantas conversas estão paradas em cada nó de um fluxo.
+ *
+ * A raiz é caso à parte no formato por sessão: o servidor guarda o passo do menu em `menuNodeId`,
+ * num campo próprio, e uma conversa no menu não carrega `flow`. Ler `nodeId` ali daria contagem
+ * zero na tela mais visitada do editor. No formato agregado a chave do fluxo já vem na linha,
+ * então a raiz não tem exceção.
+ */
+export function countLiveByNode(params: {
+  readonly flowKey: string
+  readonly rootFlowKey: string
+  readonly positions: readonly FlowLivePositionInput[] | undefined
+}): Record<string, number> {
+  const { flowKey, rootFlowKey, positions } = params
+  const isRoot = flowKey === rootFlowKey
+  const counts: Record<string, number> = {}
+
+  for (const position of positions ?? []) {
+    if (isNodeCount(position)) {
+      if (position.flowKey !== flowKey) continue
+      counts[position.nodeId] = (counts[position.nodeId] ?? 0) + position.count
+      continue
+    }
+
+    if (position.flow !== flowKey && !isRoot) continue
+    const nodeId = isRoot ? position.menuNodeId : position.nodeId
+    if (!nodeId) continue
+    counts[nodeId] = (counts[nodeId] ?? 0) + 1
+  }
+
+  return counts
+}
+
+/**
+ * Um layout só para TODOS os nós de TODOS os fluxos abertos juntos, na mesma cascata do fluxo
+ * único: um passo para a direita a cada avanço da conversa, um degrau para baixo a cada card.
+ *
+ * Posicionar cada fluxo à parte e deslocar não resolve: nada impede dois fluxos de ocuparem o mesmo
+ * espaço, e a altura real de cada card é ignorada. Aqui a travessia roda sobre o grafo mesclado
+ * inteiro, com os saltos `flow:<key>` já resolvidos para o nó inicial do alvo.
+ */
+export function computeMergedLayout(params: {
+  readonly openKeys: readonly string[]
+  readonly graphs: Readonly<Record<string, FlowGraphData>>
+  readonly primaryFlowKey: string
+}): Map<string, FlowNodePosition> {
+  const { openKeys, graphs, primaryFlowKey } = params
+  const open = new Set(openKeys)
+
+  const nodeById = new Map<string, FlowNodeData>()
+  for (const key of openKeys) {
+    for (const node of Object.values(graphs[key]?.nodes ?? {})) {
+      nodeById.set(namespaceNodeId(key, node.id), node)
+    }
+  }
+
+  function forwardEdges(id: string): string[] {
+    const node = nodeById.get(id)
+    if (!node) return []
+    const flowKey = parseNamespacedId(id).flowKey
+    const result: string[] = []
+
+    for (const { target } of targetsOf(node)) {
+      if (isCrossFlowTarget(target)) {
+        const targetKey = crossFlowKey(target)
+        const targetGraph = open.has(targetKey) ? graphs[targetKey] : undefined
+        if (targetGraph) result.push(namespaceNodeId(targetKey, targetGraph.startNodeId))
+      } else if (graphs[flowKey]?.nodes[target]) {
+        result.push(namespaceNodeId(flowKey, target))
+      }
+    }
+
+    return result
+  }
+
+  const primaryGraph = graphs[primaryFlowKey]
+  const placed = cascadeOrder({
+    rootId: primaryGraph ? namespaceNodeId(primaryFlowKey, primaryGraph.startNodeId) : '',
+    allIds: [...nodeById.keys()],
+    forwardEdges,
+  })
+
+  const positions = new Map<string, FlowNodePosition>()
+  let cursorY = 0
+
+  for (const [id, { depth }] of [...placed.entries()].sort((a, b) => a[1].order - b[1].order)) {
+    positions.set(id, { x: depth * COLUMN_GAP, y: cursorY })
+    cursorY += estimateNodeHeight(nodeById.get(id)!) + ROW_GAP
+  }
+
+  return positions
+}
+
+/** Papel visual da aresta. O componente traduz em traço, cor e seta; o modelo só decide qual é. */
+export type FlowEdgeKind = 'linear' | 'branch' | 'fallback'
+
+export type FlowEdgeSpec = {
+  readonly id: string
+  readonly source: string
+  readonly target: string
+  readonly sourceHandle?: string
+  readonly kind: FlowEdgeKind
+  /** Salto entre fluxos — tracejado, esteja o alvo mesclado ou num portal. */
+  readonly crossFlow: boolean
+  readonly live: boolean
+}
+
+/**
+ * Arestas de todos os fluxos abertos.
+ *
+ * A regra que não é óbvia: um salto `flow:<key>` vira ligação real até o nó inicial do alvo quando
+ * esse fluxo já está no canvas, e só cai no portal quando não está. Sem isso, abrir dois fluxos
+ * ligados mostrava uma caixa de portal entre dois cards que já estavam ali do lado.
+ */
+export function buildFlowEdges(params: {
+  readonly openKeys: readonly string[]
+  readonly graphs: Readonly<Record<string, FlowGraphData>>
+  readonly rootFlowKey: string
+  readonly livePositions?: readonly FlowLivePositionInput[] | undefined
+}): FlowEdgeSpec[] {
+  const { openKeys, graphs, rootFlowKey, livePositions } = params
+  const open = new Set(openKeys)
+  const edges: FlowEdgeSpec[] = []
+
+  for (const flowKey of openKeys) {
+    const graph = graphs[flowKey]
+    if (!graph) continue
+    const liveCounts = countLiveByNode({ flowKey, rootFlowKey, positions: livePositions })
+
+    for (const [nodeId, node] of Object.entries(graph.nodes)) {
+      const live = (liveCounts[nodeId] ?? 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. Emitir a aresta criaria ligação para um nó
+        // que não existe — o React Flow a descarta em silêncio, então o sintoma seria uma opção que
+        // parece ligada e não está, com a conversa do cliente parando ali.
+        if (!target) continue
+
+        const crossFlow = isCrossFlowTarget(target)
+        let targetFlowKey = flowKey
+        let targetNodeId = target
+
+        if (crossFlow) {
+          const wantedKey = crossFlowKey(target)
+          const targetGraph = open.has(wantedKey) ? graphs[wantedKey] : undefined
+          if (targetGraph) {
+            targetFlowKey = wantedKey
+            targetNodeId = targetGraph.startNodeId
+          } else {
+            targetNodeId = portalNodeId(nodeId, target)
+          }
+        }
+
+        const source = namespaceNodeId(flowKey, nodeId)
+        const edgeTarget = namespaceNodeId(targetFlowKey, targetNodeId)
+
+        // Voltar ao próprio card não é trajeto, é comportamento — e como aresta não tem onde
+        // caber: por baixo some atrás do card, por cima o cobre. Quem mostra isso é o ícone de
+        // repetição na linha de saída, dentro do card (ver `FlowNodeCard`).
+        if (source === edgeTarget) continue
+
+        if (isDefault) {
+          edges.push({
+            id: `${source}->${edgeTarget}-default`,
+            source,
+            target: edgeTarget,
+            sourceHandle: '__default',
+            kind: 'fallback',
+            crossFlow,
+            // Fallback não anima: é o caminho que ninguém escolheu, e piscar sugeria que a conversa
+            // estava passando por ali.
+            live: false,
+          })
+          continue
+        }
+
+        if (optionId === undefined) {
+          edges.push({ id: `${source}->${edgeTarget}`, source, target: edgeTarget, kind: 'linear', crossFlow, live })
+          continue
+        }
+
+        edges.push({
+          id: `${source}->${edgeTarget}-${optionId}`,
+          source,
+          target: edgeTarget,
+          sourceHandle: optionId,
+          kind: 'branch',
+          crossFlow,
+          live,
+        })
+      }
+    }
+  }
+
+  return edges
+}
+
+/** Nós de um fluxo que ninguém aponta — o card ganha contorno tracejado para cobrar a ligação. */
+export function detachedNodeIds(graph: FlowGraphData): Set<string> {
+  const connected = new Set<string>()
+  for (const node of Object.values(graph.nodes)) {
+    for (const { target } of targetsOf(node)) {
+      if (!isCrossFlowTarget(target)) connected.add(target)
+    }
+  }
+
+  const detached = new Set<string>()
+  for (const nodeId of Object.keys(graph.nodes)) {
+    if (nodeId !== graph.startNodeId && !connected.has(nodeId)) detached.add(nodeId)
+  }
+
+  return detached
+}
+
+/** Retângulo que envolve uma cadeia de coleta, em coordenadas do canvas. */
+export function chainFrameBounds(params: {
+  readonly nodeIds: readonly string[]
+  readonly graph: FlowGraphData
+  readonly positionOf: (nodeId: string) => FlowNodePosition
+  readonly padding: number
+}): { x: number; y: number; width: number; height: number } {
+  const { nodeIds, graph, positionOf, padding } = params
+  const positions = nodeIds.map(positionOf)
+  const minX = Math.min(...positions.map((each) => each.x))
+  const maxX = Math.max(...positions.map((each) => each.x)) + NODE_CARD_WIDTH
+  const minY = Math.min(...positions.map((each) => each.y))
+  const maxY = Math.max(...nodeIds.map((id, index) => positions[index]!.y + estimateNodeHeight(graph.nodes[id]!)))
+
+  return {
+    x: minX - padding,
+    y: minY - padding - CHAIN_LABEL_ROOM,
+    width: maxX - minX + padding * 2,
+    height: maxY - minY + padding * 2 + CHAIN_LABEL_ROOM,
+  }
+}
+
+/**
+ * O nó que nasce de cada item da paleta.
+ *
+ * `contextKey` igual ao id porque é o que o motor usa para guardar a resposta: deixá-lo vazio faria a
+ * pergunta ser feita e a resposta descartada, sem erro em lugar nenhum.
+ */
+export function newNodeFromSpec(spec: NewNodeSpec, existingIds: ReadonlySet<string>): FlowNodeData {
+  if (spec.kind === 'question') {
+    const id = slugifyNodeId('nova_pergunta', existingIds)
+    return { id, type: 'question', questionType: spec.questionType, contextKey: id, question: '' }
+  }
+
+  if (spec.kind === 'decision') {
+    const id = slugifyNodeId('nova_decisao', existingIds)
+    return {
+      id,
+      type: 'question',
+      questionType: 'choice',
+      contextKey: id,
+      question: '',
+      options: [
+        ['1', 'Opção 1'],
+        ['2', 'Opção 2'],
+      ],
+    }
+  }
+
+  if (spec.kind === 'condition') {
+    const id = slugifyNodeId('nova_condicao', existingIds)
+    return { id, type: 'condition', conditionOperator: '>' }
+  }
+
+  const id = slugifyNodeId('nova_acao', existingIds)
+  return { id, type: 'action', actionKind: spec.actionKind }
+}
+
+/** Distância vertical mínima entre dois cards para que não se leiam como um só. */
+const FREE_SLOT_STEP = 120
+
+/**
+ * Empurra a posição para baixo até achar espaço livre na mesma coluna.
+ *
+ * O "+" põe o nó novo à direita de quem o criou — e é justamente ali que costuma estar o nó que
+ * acabou de perder a ligação. Sem isto, os dois se sobrepõem e a tela mostra um card onde há dois,
+ * que é o mesmo susto de "sumiu" por outro caminho.
+ */
+export function findFreeSlot(params: {
+  readonly desired: FlowNodePosition
+  readonly taken: readonly FlowNodePosition[]
+  readonly step?: number
+}): FlowNodePosition {
+  const step = params.step ?? FREE_SLOT_STEP
+  const isOccupied = (candidate: FlowNodePosition) =>
+    params.taken.some(
+      (each) => Math.abs(each.x - candidate.x) < NODE_CARD_WIDTH && Math.abs(each.y - candidate.y) < step,
+    )
+
+  let slot = params.desired
+  // Teto igual ao número de cards: com N ocupados, N descidas bastam para sair de todos.
+  for (let attempt = 0; attempt <= params.taken.length && isOccupied(slot); attempt += 1) {
+    slot = { x: slot.x, y: slot.y + step }
+  }
+
+  return slot
+}

package/src/flows/flowEditorOps.test.ts

@@ -0,0 +1,276 @@
+/**
+ * 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,
+  clearConnection,
+  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)
+  })
+})
+
+/**
+ * Desligar um fio é a operação que o relato de campo pegou errada: o card sumia. Some porque a
+ * opção deixa de existir no `byAnswer`, não porque alguém apagou o nó — e o teste fixa isso.
+ */
+describe('clearConnection', () => {
+  it('saída única vira destino vazio, e o nó continua lá', () => {
+    expect(clearConnection(node('a', 'b'), 'next').next).toBe('')
+  })
+
+  it('desligar uma opção NÃO apaga a chave — a opção sumindo levaria junto o botão do WhatsApp', () => {
+    const branching = node('a', { byAnswer: { sim: 'b', nao: 'c' }, default: 'd' })
+
+    const result = clearConnection(branching, 'sim')
+
+    expect(result.next).toEqual({ byAnswer: { sim: '', nao: 'c' }, default: 'd' })
+  })
+
+  it('desligar o fallback preserva as opções', () => {
+    const branching = node('a', { byAnswer: { sim: 'b' }, default: 'd' })
+
+    expect(clearConnection(branching, '__default').next).toEqual({ byAnswer: { sim: 'b' }, default: '' })
+  })
+
+  it('handle inexistente não inventa ramificação nem derruba as existentes', () => {
+    const branching = node('a', { byAnswer: { sim: 'b' }, default: 'd' })
+
+    expect(clearConnection(branching, 'talvez').next).toEqual({ byAnswer: { sim: 'b', talvez: '' }, default: 'd' })
+  })
+
+  it('nó sem next algum não quebra', () => {
+    expect(clearConnection(node('a'), 'next').next).toBe('')
+  })
+})