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

id, title, status, priority, created, related_to

id	title	status	priority	created	related_to
0031	Layout estable al recargar — auto-save, halo placement, sin fit, physics off	in_progress	high	2026-05-01	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)

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.

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).

// 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:

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).