graph_explorer/issues/completed/0031-stable-layout-on-reload.md

---
id: 0031
title: Layout estable al recargar — auto-save, halo placement, sin fit, physics off
status: in_progress
priority: high
created: 2026-05-01
related_to: [0026]
---

## Problema

Cuando un enricher (issue 0026) crea entidades nuevas, el `dirty_counter`
dispara `want_reload` y el grafo pierde la disposicion que tenia el
usuario:

1. **`graph_viewport_fit()` se llama en cada reload** → recentra y
   reescala la camara, sensacion de "todo se movio".
2. **`layout_store_save` solo se ejecuta al pulsar "Save layout"** →
   si el usuario no lo pulsa, las posiciones en RAM se pierden y los
   nodos viejos vuelven a (0,0) tras el reload.
3. **`layout_circular` se aplica si todos los nodos estan en (0,0)**
   tras reload → si no hay nada guardado en `layout_store`, todo se
   reorganiza en circulo.
4. **Nodos creados por enrichers llegan en (0,0)** → quedan apilados
   sobre el origen tras `layout_store_load`. Con physics ON se reparten
   violentamente al chocar entre si.

## Decisiones (confirmadas por el usuario)

- **A. Auto-save antes de cada reload**: preservar las posiciones que el
  usuario tiene en RAM sin que tenga que pulsar "Save layout" jamas.
- **B. No `graph_viewport_fit` en reloads**: solo en la primera carga
  de cada proyecto/archivo. La camara permanece donde la tenia el usuario.
- **C. Halo placement para nodos huerfanos**: nodos que tras
  `layout_store_load` siguen en (0,0) se posicionan junto a su primer
  vecino con coordenadas conocidas, **garantizando no solapamiento** con
  nodos existentes ni entre ellos.
- **D. No `layout_circular` en reloads**: la condicion `zero_pos == node_count`
  solo aplica en la primera carga.
- **E. Physics siempre pausadas**: `layout_running = false` al cargar y
  al recargar. El usuario las activa explicitamente con el toggle
  Physics si quiere ver fuerzas.

## Implementacion

### main.cpp:want_reload (sustituye el bloque actual)

```cpp
if (g_app.want_reload) {
    g_app.want_reload = false;

    // (A) auto-save: persistir posiciones actuales antes de liberar grafo.
    if (g_loaded) ge::layout_store_save(g_graph_hash, g_graph);

    graph::GraphLoadStats stats{};
    if (ge::reload_graph(g_input, &g_graph, &stats)) {
        ge::views_reset_visibility(g_app);
        ge::views_apply_visibility(g_app);
        g_graph.update_bounds();
        // (B) NO graph_viewport_fit aqui.
        int restored = ge::layout_store_load(g_graph_hash, g_graph);
        // (C) huerfanos -> halo placement junto a vecinos.
        place_orphans_near_neighbors(g_graph, /*min_dist=*/60.0f);
        if (restored > 0 || g_graph.node_count > 0) g_graph.update_bounds();
        g_atlas_bound = false;
        g_gpu_dirty = true;
        // (E) physics siempre pausadas tras reload.
        g_viewport.layout_running = false;
    }
}
```

### load_input — distinguir primera carga de reload

Anadir flag `bool first_load`. La condicion `zero_pos == node_count` y
el `graph_viewport_fit()` solo se aplican si `first_load == true`.

```cpp
static bool load_input(bool first_load = true);
```

Internamente: `reload_graph()` ya no llama a `load_input`, sino a una
version que pasa `first_load=false`. O `want_reload` hace el flujo
manualmente como arriba (sin reusar load_input).

### Nuevo helper `place_orphans_near_neighbors`

Vive en `main.cpp` (O nuevo `layout_helpers.{h,cpp}` si crece).

```cpp
// Para cada nodo en (0,0) (huerfano tras reload):
//   1. Busca su primer vecino (via aristas) con posicion no-cero.
//   2. Coloca el huerfano en un anillo a r=80 px alrededor del padre,
//      eligiendo el primer slot angular (de 12) que no colisione con
//      ningun otro nodo a min_dist. Si todos ocupados, expande radio
//      (140, 200, 280, 400). Jitter deterministico por user_data para
//      que dos huerfanos del mismo padre no caigan en el mismo slot.
//   3. Si el huerfano no tiene vecinos colocados (ej. componente
//      conexa nueva), lo aparca en una columna a la derecha del bbox
//      del grafo, separados verticalmente min_dist.
//
// Complejidad O(N * orphans). Suficiente para grafos bajo 5k nodos.
static void place_orphans_near_neighbors(GraphData& g, float min_dist);
```

Algoritmo de un huerfano:

```cpp
int parent = first_placed_neighbor(g, i);  // O(edges)
if (parent < 0) { park_in_free_column(...); continue; }
const float radii[] = {80, 140, 200, 280, 400};
const int   slots   = 12;  // 30 grados
float jitter = ((g.nodes[i].user_data >> 16) & 0xFF) / 255.0f * (2*PI/slots);
for (float r : radii) {
    for (int s = 0; s < slots; ++s) {
        float a = jitter + s * (2*PI/slots);
        float cx = g.nodes[parent].x + r * cosf(a);
        float cy = g.nodes[parent].y + r * sinf(a);
        if (no_collision(g, i, cx, cy, min_dist)) {
            g.nodes[i].x = cx; g.nodes[i].y = cy;
            goto placed;
        }
    }
}
// Fallback: ultima posicion del ultimo radio + slot 0 (acepta solape).
placed:
```

`no_collision` es O(n) — itera todos los nodos del grafo y rechaza si
algun otro esta a < min_dist. Marca el huerfano recien colocado para
que el siguiente huerfano sepa de el.

## Definicion de hecho

- Reload tras enricher NO mueve la camara.
- Reload tras enricher NO cambia las posiciones de los nodos que ya
  tenian sitio.
- Las entidades nuevas creadas por el enricher aparecen visibles, cerca
  de su nodo padre semantico, sin solaparse con nadie.
- Physics permanecen OFF tras el reload (el usuario las activa
  manualmente si quiere).
- Si el usuario nunca pulsa "Save layout", el cierre normal de la app
  no preserva estado, pero cualquier reload SI preserva (gracias al
  auto-save antes de reload).