@adatechnology/conversations-ui 0.1.0-rc.3 → 0.1.0-rc.31

package/src/flows/flowCanvasModel.test.ts

@@ -0,0 +1,312 @@
+/**
+ * O que se prova aqui é topologia e posição, não estilo.
+ *
+ * Aresta com destino errado não pinta errado — ela manda a conversa do cliente para outro lugar, e
+ * quem editou nunca vê. Card que o layout joga para fora da área visível se lê como "apaguei sem
+ * querer". São os dois modos de falhar que já aconteceram nesta tela, e os dois são silenciosos.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import {
+  buildFlowEdges,
+  chainFrameBounds,
+  computeMergedLayout,
+  countLiveByNode,
+  detachedNodeIds,
+  newNodeFromSpec,
+  portalNodeId,
+  type FlowLivePosition,
+} from './flowCanvasModel'
+import type { FlowGraphData, FlowNodeData } from './flowGraph'
+
+const ROOT = 'menu'
+
+/** Nós mínimos VÁLIDOS pelo contrato — sem `as`, para quebrar quando a forma do nó mudar. */
+function node(id: string, next?: FlowNodeData['next']): FlowNodeData {
+  return { id, type: 'question', question: id, ...(next === undefined ? {} : { next }) }
+}
+
+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])),
+  }
+}
+
+function live(params: Partial<FlowLivePosition>): FlowLivePosition {
+  return { currentState: 'x', flow: null, nodeId: null, menuNodeId: null, ...params }
+}
+
+describe('arestas', () => {
+  it('saída única vira aresta linear sem handle', () => {
+    const graphs = { menu: graph({ key: 'menu', start: 'a', nodes: [node('a', 'b'), node('b')] }) }
+
+    expect(buildFlowEdges({ openKeys: ['menu'], graphs, rootFlowKey: ROOT })).toEqual([
+      { id: 'menu::a->menu::b', source: 'menu::a', target: 'menu::b', kind: 'linear', crossFlow: false, live: false },
+    ])
+  })
+
+  it('ramificação leva o id da opção no handle, e o default vira fallback', () => {
+    const graphs = {
+      menu: graph({
+        key: 'menu',
+        start: 'p',
+        nodes: [node('p', { byAnswer: { sim: 'x' }, default: 'y' }), node('x'), node('y')],
+      }),
+    }
+
+    const edges = buildFlowEdges({ openKeys: ['menu'], graphs, rootFlowKey: ROOT })
+
+    expect(edges.find((each) => each.kind === 'branch')).toMatchObject({ sourceHandle: 'sim', target: 'menu::x' })
+    // O handle do fallback é fixo `__default` — é o que `applyConnection` espera de volta quando
+    // alguém arrasta esse fio.
+    expect(edges.find((each) => each.kind === 'fallback')).toMatchObject({
+      sourceHandle: '__default',
+      target: 'menu::y',
+    })
+  })
+
+  it('destino vazio NÃO gera aresta', () => {
+    // Apagar um nó zera quem apontava para ele. A aresta iria para `menu::`, que não existe, e o
+    // React Flow descarta em silêncio — a opção pareceria ligada sem estar.
+    const graphs = {
+      menu: graph({ key: 'menu', start: 'p', nodes: [node('p', { byAnswer: { sim: '' }, default: '' })] }),
+    }
+
+    expect(buildFlowEdges({ openKeys: ['menu'], graphs, rootFlowKey: ROOT })).toEqual([])
+  })
+
+  it('salto para fluxo MESCLADO liga no nó inicial dele, não num portal', () => {
+    const graphs = {
+      menu: graph({ key: 'menu', start: 'a', nodes: [node('a', 'flow:sim')] }),
+      sim: graph({ key: 'sim', start: 's1', nodes: [node('s1')] }),
+    }
+
+    expect(buildFlowEdges({ openKeys: ['menu', 'sim'], graphs, rootFlowKey: ROOT })[0]).toMatchObject({
+      target: 'sim::s1',
+      crossFlow: true,
+    })
+  })
+
+  it('salto para fluxo NÃO mesclado cai no portal', () => {
+    const graphs = {
+      menu: graph({ key: 'menu', start: 'a', nodes: [node('a', 'flow:sim')] }),
+      sim: graph({ key: 'sim', start: 's1', nodes: [node('s1')] }),
+    }
+
+    expect(buildFlowEdges({ openKeys: ['menu'], graphs, rootFlowKey: ROOT })[0]!.target).toBe(
+      `menu::${portalNodeId('a', 'flow:sim')}`,
+    )
+  })
+
+  it('duas opções para o mesmo fluxo compartilham UM portal', () => {
+    const graphs = {
+      menu: graph({
+        key: 'menu',
+        start: 'p',
+        nodes: [node('p', { byAnswer: { um: 'flow:sim', dois: 'flow:sim' }, default: '' })],
+      }),
+      sim: graph({ key: 'sim', start: 's1', nodes: [node('s1')] }),
+    }
+
+    const edges = buildFlowEdges({ openKeys: ['menu'], graphs, rootFlowKey: ROOT })
+
+    // Duas arestas (uma por opção), um só destino: senão o card fica cercado de caixas iguais.
+    expect(edges).toHaveLength(2)
+    expect(new Set(edges.map((each) => each.target)).size).toBe(1)
+  })
+
+  it('conversa parada no nó anima a aresta que sai dele, mas nunca o fallback', () => {
+    const graphs = {
+      menu: graph({
+        key: 'menu',
+        start: 'p',
+        nodes: [node('p', { byAnswer: { sim: 'x' }, default: 'y' }), node('x'), node('y')],
+      }),
+    }
+
+    const edges = buildFlowEdges({
+      openKeys: ['menu'],
+      graphs,
+      rootFlowKey: ROOT,
+      livePositions: [live({ menuNodeId: 'p' })],
+    })
+
+    expect(edges.find((each) => each.kind === 'branch')!.live).toBe(true)
+    // Fallback piscando sugeria que a conversa estava passando pelo caminho que ninguém escolheu.
+    expect(edges.find((each) => each.kind === 'fallback')!.live).toBe(false)
+  })
+
+  it('ids de aresta são únicos entre fluxos com nós homônimos', () => {
+    const graphs = {
+      menu: graph({ key: 'menu', start: 'inicio', nodes: [node('inicio', 'fim'), node('fim')] }),
+      sim: graph({ key: 'sim', start: 'inicio', nodes: [node('inicio', 'fim'), node('fim')] }),
+    }
+
+    const edges = buildFlowEdges({ openKeys: ['menu', 'sim'], graphs, rootFlowKey: ROOT })
+
+    expect(new Set(edges.map((each) => each.id)).size).toBe(edges.length)
+  })
+})
+
+describe('contagem ao vivo', () => {
+  it('no fluxo RAIZ a posição vem de menuNodeId', () => {
+    // O servidor guarda o passo do menu num campo próprio, e conversa no menu não carrega `flow`.
+    // Ler `nodeId` aqui daria zero na tela mais visitada do editor.
+    const positions = [live({ menuNodeId: 'saudacao' }), live({ menuNodeId: 'saudacao' })]
+
+    expect(countLiveByNode({ flowKey: ROOT, rootFlowKey: ROOT, positions })).toEqual({ saudacao: 2 })
+  })
+
+  it('fora da raiz a posição vem de nodeId, e outro fluxo é ignorado', () => {
+    const positions = [live({ flow: 'sim', nodeId: 'renda' }), live({ flow: 'outro', nodeId: 'renda' })]
+
+    expect(countLiveByNode({ flowKey: 'sim', rootFlowKey: ROOT, positions })).toEqual({ renda: 1 })
+  })
+
+  it('sem posições devolve vazio, em vez de estourar', () => {
+    expect(countLiveByNode({ flowKey: ROOT, rootFlowKey: ROOT, positions: undefined })).toEqual({})
+  })
+
+  it('linha já agregada pelo servidor soma pelo count, inclusive na raiz', () => {
+    // `meta-whatsapp-module` responde `GROUP BY (flowKey, currentNodeId)`. Contando como uma sessão
+    // por linha, dez conversas paradas no mesmo nó apareciam como uma — ou como nenhuma, porque a
+    // linha agregada não tem `menuNodeId` para a raiz ler.
+    const positions = [
+      { flowKey: ROOT, nodeId: 'saudacao', count: 7 },
+      { flowKey: 'sim', nodeId: 'renda', count: 3 },
+    ]
+
+    expect(countLiveByNode({ flowKey: ROOT, rootFlowKey: ROOT, positions })).toEqual({ saudacao: 7 })
+    expect(countLiveByNode({ flowKey: 'sim', rootFlowKey: ROOT, positions })).toEqual({ renda: 3 })
+  })
+
+  it('os dois formatos convivem na mesma resposta', () => {
+    const positions = [live({ flow: 'sim', nodeId: 'renda' }), { flowKey: 'sim', nodeId: 'renda', count: 2 }]
+
+    expect(countLiveByNode({ flowKey: 'sim', rootFlowKey: ROOT, positions })).toEqual({ renda: 3 })
+  })
+})
+
+describe('layout mesclado', () => {
+  it('ranqueia da esquerda para a direita a partir do início do fluxo primário', () => {
+    const graphs = { menu: graph({ key: 'menu', start: 'a', nodes: [node('a', 'b'), node('b', 'c'), node('c')] }) }
+
+    const positions = computeMergedLayout({ openKeys: ['menu'], graphs, primaryFlowKey: 'menu' })
+
+    expect(positions.get('menu::a')!.x).toBe(0)
+    expect(positions.get('menu::b')!.x).toBeGreaterThan(positions.get('menu::a')!.x)
+    expect(positions.get('menu::c')!.x).toBeGreaterThan(positions.get('menu::b')!.x)
+  })
+
+  it('atravessa o salto entre fluxos ao ranquear', () => {
+    const graphs = {
+      menu: graph({ key: 'menu', start: 'a', nodes: [node('a', 'flow:sim')] }),
+      sim: graph({ key: 'sim', start: 's1', nodes: [node('s1')] }),
+    }
+
+    const positions = computeMergedLayout({ openKeys: ['menu', 'sim'], graphs, primaryFlowKey: 'menu' })
+
+    expect(positions.get('sim::s1')!.x).toBeGreaterThan(positions.get('menu::a')!.x)
+  })
+
+  it('TODOS os órfãos ficam na MESMA coluna extra', () => {
+    // Uma coluna por órfão empurrava cada um mais para longe da área visível, e desligar um fio se
+    // lia como "o card sumiu". É o motivo de existir uma camada única.
+    const graphs = {
+      menu: graph({ key: 'menu', start: 'a', nodes: [node('a'), node('o1'), node('o2'), node('o3')] }),
+    }
+
+    const positions = computeMergedLayout({ openKeys: ['menu'], graphs, primaryFlowKey: 'menu' })
+    const strayX = ['o1', 'o2', 'o3'].map((id) => positions.get(`menu::${id}`)!.x)
+
+    expect(new Set(strayX).size).toBe(1)
+    expect(strayX[0]).toBeGreaterThan(positions.get('menu::a')!.x)
+  })
+
+  it('órfãos na mesma coluna não se sobrepõem', () => {
+    const graphs = { menu: graph({ key: 'menu', start: 'a', nodes: [node('a'), node('o1'), node('o2')] }) }
+
+    const positions = computeMergedLayout({ openKeys: ['menu'], graphs, primaryFlowKey: 'menu' })
+
+    expect(positions.get('menu::o1')!.y).not.toBe(positions.get('menu::o2')!.y)
+  })
+
+  it('ciclo não estoura a pilha', () => {
+    const graphs = { menu: graph({ key: 'menu', start: 'a', nodes: [node('a', 'b'), node('b', 'a')] }) }
+
+    expect(computeMergedLayout({ openKeys: ['menu'], graphs, primaryFlowKey: 'menu' }).size).toBe(2)
+  })
+
+  it('fluxo primário ausente ainda posiciona todo mundo, em vez de devolver vazio', () => {
+    const graphs = { sim: graph({ key: 'sim', start: 's1', nodes: [node('s1')] }) }
+
+    // Acontece entre o clique em "focar" e a chegada do grafo: sem isto o canvas fica em branco.
+    expect(computeMergedLayout({ openKeys: ['sim'], graphs, primaryFlowKey: 'menu' }).size).toBe(1)
+  })
+})
+
+describe('nós soltos', () => {
+  it('quem ninguém aponta está solto; o nó inicial nunca está', () => {
+    const target = graph({ key: 'menu', start: 'a', nodes: [node('a', 'b'), node('b'), node('solto')] })
+
+    expect(detachedNodeIds(target)).toEqual(new Set(['solto']))
+  })
+
+  it('salto para outro fluxo não conta como ligação local', () => {
+    const target = graph({ key: 'menu', start: 'a', nodes: [node('a', 'flow:sim'), node('b')] })
+
+    expect(detachedNodeIds(target).has('b')).toBe(true)
+  })
+})
+
+describe('moldura da cadeia de coleta', () => {
+  it('envolve todos os nós e abre espaço para o rótulo acima', () => {
+    const target = graph({ key: 'menu', start: 'a', nodes: [node('a'), node('b')] })
+    const positions: Record<string, { x: number; y: number }> = { a: { x: 0, y: 0 }, b: { x: 100, y: 50 } }
+
+    const bounds = chainFrameBounds({
+      nodeIds: ['a', 'b'],
+      graph: target,
+      positionOf: (id) => positions[id]!,
+      padding: 10,
+    })
+
+    expect(bounds.x).toBe(-10)
+    // O rótulo é desenhado acima da borda, então o topo sobe além do padding.
+    expect(bounds.y).toBeLessThan(-10)
+    expect(bounds.width).toBeGreaterThan(100)
+    expect(bounds.height).toBeGreaterThan(50)
+  })
+})
+
+describe('nó novo da paleta', () => {
+  it('pergunta nasce com contextKey igual ao id', () => {
+    // Sem contextKey o motor faz a pergunta e descarta a resposta, sem erro em lugar nenhum.
+    const created = newNodeFromSpec({ kind: 'question', questionType: 'text' }, new Set())
+
+    expect(created.contextKey).toBe(created.id)
+  })
+
+  it('decisão nasce com duas opções, para já dar o que ligar', () => {
+    const created = newNodeFromSpec({ kind: 'decision' }, new Set())
+
+    expect(created.options).toHaveLength(2)
+    expect(created.questionType).toBe('choice')
+  })
+
+  it('id não colide com o que já existe', () => {
+    const first = newNodeFromSpec({ kind: 'condition' }, new Set())
+    const second = newNodeFromSpec({ kind: 'condition' }, new Set([first.id]))
+
+    expect(second.id).not.toBe(first.id)
+  })
+
+  it('ação carrega o kind escolhido na paleta', () => {
+    expect(newNodeFromSpec({ kind: 'action', actionKind: 'handoff' }, new Set()).actionKind).toBe('handoff')
+  })
+})

package/src/flows/flowCanvasModel.ts

@@ -0,0 +1,368 @@
+/**
+ * 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,
+  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.
+ *
+ * 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 o ranqueamento por BFS 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(flowKey: string, node: FlowNodeData): string[] {
+    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 rank = new Map<string, number>()
+  const primaryGraph = graphs[primaryFlowKey]
+  const rootId = primaryGraph ? namespaceNodeId(primaryFlowKey, primaryGraph.startNodeId) : undefined
+
+  if (rootId && nodeById.has(rootId)) {
+    rank.set(rootId, 0)
+    const queue = [rootId]
+    while (queue.length > 0) {
+      const id = queue.shift()!
+      const node = nodeById.get(id)
+      if (!node) continue
+      for (const nextId of forwardEdges(parseNamespacedId(id).flowKey, node)) {
+        if (!rank.has(nextId)) {
+          rank.set(nextId, rank.get(id)! + 1)
+          queue.push(nextId)
+        }
+      }
+    }
+  }
+
+  // Todo nó não alcançado vai para UMA coluna extra depois de tudo. Uma coluna por órfão empurrava
+  // cada um mais para longe da área visível — e desligar um fio se lia como "o card sumiu".
+  const strayRank = Math.max(0, ...rank.values()) + 1
+  for (const id of nodeById.keys()) {
+    if (!rank.has(id)) rank.set(id, strayRank)
+  }
+
+  const layers = new Map<number, string[]>()
+  for (const [id, value] of rank) {
+    const layer = layers.get(value)
+    if (layer) layer.push(id)
+    else layers.set(value, [id])
+  }
+
+  const positions = new Map<string, FlowNodePosition>()
+  for (const value of [...layers.keys()].sort((a, b) => a - b)) {
+    // Alinhado pelo topo, e não centralizado: coluna centralizada saltava inteira a cada nó a mais
+    // num ramo qualquer.
+    let cursorY = 0
+    for (const id of layers.get(value)!) {
+      positions.set(id, { x: value * 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)
+
+        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 }
+}