# cpp/PATTERNS.md — App shell canonico

Patron obligatorio para apps C++ del registry (`cpp/apps/*`, `projects/*/apps/*`).
Cumplir estas reglas garantiza coherencia visual, theming uniforme, About/Settings
funcionando, paneles toggleables y layouts persistentes con cero codigo boilerplate.

## Checklist obligatorio

Antes de mergear una app, verificar uno por uno:

- [ ] **No `glfwInit` directo**. La app SOLO usa `fn::run_app(AppConfig{...}, render_fn)`.
      El framework gestiona GLFW + ImGui + ImPlot + theming + Settings + About + FPS overlay.
- [ ] **About registrado**. La app pasa `AppConfig::about = {name, version, description}`
      o llama explicitamente `fn_ui::about_window_set_info(...)` en su init.
- [ ] **Settings extras** (si aplica). Si la app expone settings propios (toggles,
      sliders, paths…), los registra con `fn_ui::settings_window_add_section("Mi App", cb)`.
- [ ] **Paneles toggleables** (si aplica). Si la app tiene >=1 panel:
      ```cpp
      static constexpr fn_ui::PanelToggle panels[] = {
          {"Inspector", "Ctrl+1", &show_inspector},
          {"Console",   "Ctrl+2", &show_console},
      };
      ```
      Pasarlo a `AppConfig::panels` + `AppConfig::panel_count = 2`.
- [ ] **Layouts persistentes**. Vienen activos por defecto: `fn::run_app` abre
      un `LayoutStorage` SQLite en `<exe_dir>/local_files/layouts.db` y enchufa
      el menu Layouts (Save / Apply / Delete / Reset) sin codigo. La app solo
      pasa `AppConfig::layouts_cb` si quiere personalizar (ej. on_reset que
      restaure paneles especificos como en `shaders_lab`). Para apagar el
      auto-storage: `cfg.auto_layouts = false`. Para cambiar el nombre del
      archivo: `cfg.auto_layouts_db = "myapp_layouts.db"`.
- [ ] **GL loader** (si la app usa OpenGL >= 2.0 directamente). Pasar
      `AppConfig::init_gl_loader = true` para que `fn::run_app()` llame
      `fn::gfx::gl_loader_init()` tras crear el contexto.
- [ ] **Auto-dockspace** (default `true`). El framework llama
      `ImGui::DockSpaceOverViewport(0, GetMainViewport(), PassthruCentralNode)`
      antes de `render_fn()` cada frame. **NO** llamar `DockSpaceOverViewport`
      manual en `render()` — duplica nodes y causa flicker. Apps que usan
      layout custom con `ImGui::DockSpace` propio o `fullscreen_window` deben
      poner `cfg.auto_dockspace = false`.
- [ ] **No `fn_ui::app_menubar(...)` manual**. El framework ya lo dibuja en
      cada frame leyendo `cfg.panels`/`cfg.layouts_cb`/`cfg.view_extras`.
      Llamarlo manualmente provoca barra duplicada o pisada.
- [ ] **Tokens en lugar de hex literales**. Usar `fn_tokens::colors`,
      `fn_tokens::spacing`, `fn_tokens::radius`. Nunca `IM_COL32(0x12,0x34,...)`,
      nunca `ImVec4(0.5f, 0.5f, 0.5f, 1.0f)` ad-hoc.
- [ ] **Componentes del registry, no raw ImGui con styling manual**. Evitar
      `ImGui::BeginTable / Selectable / BeginPopupModal / BeginChild` con estilos
      pegados a mano cuando ya existe primitiva:
        - `fn_ui::dashboard_grid` / `fn_ui::dashboard_panel` para layouts grid.
        - `fn_ui::tree_view` / `fn_ui::select` para listas seleccionables.
        - `fn_ui::modal_dialog` para popups modales.
- [ ] **Iconos via `TI_*`** (Tabler). Nunca emojis ni hex UTF-8 inline.
      Ver `cpp/functions/core/icons_tabler.h`.
- [ ] **Build incremental**. La app aparece en `cpp/CMakeLists.txt` con su
      `add_subdirectory(apps/<nombre>)`. Sin warnings nuevos.

## Crear app nueva — usar el scaffolder

```bash
# App suelta en cpp/apps/<name>/
fn run init_cpp_app my_tool --desc "Herramienta para X"

# App dentro de un proyecto
fn run init_cpp_app finance_panel --project budget --desc "Panel de finanzas"
```

`init_cpp_app_bash_pipelines` genera la estructura canonica (main.cpp + CMakeLists.txt + app.md) cumpliendo este documento, registra la app en `cpp/CMakeLists.txt`, crea repo Gitea `dataforge/<name>` y ejecuta `fn index`. Despues solo se completa `uses_functions` cuando se importan funciones del registry.

## Esqueleto minimo

```cpp
#include "framework/app_base.h"
#include "core/icons_tabler.h"
#include "imgui.h"

namespace {
bool show_inspector = true;
bool show_console   = false;

constexpr fn_ui::PanelToggle k_panels[] = {
    {"Inspector", "Ctrl+1", &show_inspector},
    {"Console",   "Ctrl+2", &show_console},
};
} // namespace

static void render_my_app() {
    // Sin DockSpaceOverViewport ni app_menubar manual — los da el framework.
    if (show_inspector) {
        ImGui::Begin(TI_INFO_CIRCLE " Inspector", &show_inspector);
        ImGui::TextUnformatted("Inspector contents");
        ImGui::End();
    }
    if (show_console) {
        ImGui::Begin(TI_TERMINAL_2 " Console", &show_console);
        ImGui::TextUnformatted("Console contents");
        ImGui::End();
    }
}

int main() {
    fn::AppConfig cfg;
    cfg.title          = "My App";
    cfg.about          = {"My App", "0.1.0", "Demo de app shell canonica"};
    cfg.log            = {"my_app.log", 1};
    cfg.panels         = k_panels;
    cfg.panel_count    = sizeof(k_panels) / sizeof(k_panels[0]);
    cfg.init_gl_loader = false; // true si usas OpenGL directo
    // cfg.auto_dockspace = false; // solo si gestionas DockSpace propio (ej. shaders_lab)
    return fn::run_app(cfg, render_my_app);
}
```

Con esto la app obtiene gratis: MainMenuBar (View/**Layouts**/Settings/About),
ventana About, ventana Settings, ventana Logs, FPS overlay configurable, theming
`FnDark`, fuentes vectoriales + iconos Tabler mergeados, multi-viewport opcional,
**y persistencia de layouts ImGui en `<exe_dir>/local_files/layouts.db`** sin
escribir una linea de codigo.

## Anti-patrones

| Mal patron                            | Patron correcto                                |
|---------------------------------------|------------------------------------------------|
| `glfwInit()` en `main`                | `fn::run_app()`                                |
| `ImVec4(0.5,0.5,0.5,1)` ad-hoc        | `fn_tokens::colors::text_dim`                  |
| Crear menubar a mano en cada frame    | `AppConfig::panels` + `AppConfig::layouts_cb`  |
| `fn_ui::app_menubar(nullptr,0,nullptr)` en render | El framework ya lo dibuja             |
| `ImGui::DockSpaceOverViewport(...)` en render     | `auto_dockspace=true` por defecto    |
| `ImGui::Begin(u8"\xEF\xA0\x83 ...")`  | `ImGui::Begin(TI_HOME " ...")`                 |
| Settings dispersos por la app         | `settings_window_add_section()`                |
| About hardcoded en un `Begin/End`     | `AppConfig::about` o `about_window_set_info()` |
| Llamar `gl*` sin loader en Windows    | `AppConfig::init_gl_loader = true`             |

## Cuando NO usar `fn::run_app`

Solo si la app es:
- un test headless que no necesita ventana (usar `googletest` directo);
- un binario CLI sin UI (no es una "app C++" en este sentido).

En cualquier otro caso, usar `fn::run_app`. Si `AppConfig` no expone algo que
necesitas, **abrir un issue para extender el shell**, no duplicar boilerplate.

## Tests visuales y CI gate (issue 0048)

`primitives_gallery` soporta un modo `--capture <output_dir>` que renderiza
cada demo en una ventana GLFW invisible y guarda un PNG por demo. Se usa
para tests visuales tipo golden-image:

```bash
# Regenerar goldens (cuando tu cambio es intencional):
cpp/scripts/update_goldens.sh

# Equivalente manual:
LIBGL_ALWAYS_SOFTWARE=1 \
    cpp/build/apps/primitives_gallery/primitives_gallery \
    --capture cpp/tests/golden
```

`cpp/tests/test_visual.cpp` corre la captura sobre un tmpdir y compara contra
`cpp/tests/golden/<demo>.png` con tolerancia 1% de pixels distintos
(threshold 5/255 por canal). Skipea si:

- `cpp/tests/golden/` esta vacio (no hay goldens todavia).
- El binario `primitives_gallery` no se construyo.
- El entorno no puede crear contexto GL (WSL minimo, container sin Mesa) —
  el test reporta SKIP en lugar de FAIL.

Para diagnosticar un diff: revisar el PNG actual en
`cpp/build/tests/visual_actual/<demo>.png` vs el golden en
`cpp/tests/golden/<demo>.png`.

### Tests de UI headless (Dear ImGui Test Engine)

`fn::run_app_test` (el harness del Test Engine usado por `/e2e-cpp`) crea la
ventana GLFW **oculta por defecto** (`GLFW_VISIBLE=FALSE`). El contexto OpenGL
real se crea igual, así que el render que el Test Engine ejercita sigue siendo
fiel, pero la ventana nunca se mapea en pantalla: cero parpadeo y no roba foco
mientras corre la suite. Es el comportamiento preferente para tests de
frontend en C++.

Control del modo (en orden de prioridad):

| Mecanismo | Efecto |
|---|---|
| `FN_HEADLESS=0` (env) | Fuerza ventana **visible** — para depurar un test a ojo. |
| `FN_HEADLESS=1` (env) | Fuerza oculta (es el default del path de test). |
| `cfg.headless = true` | Oculta también `fn::run_app` (apps reales, p.ej. smoke/capture). |
| sin nada | `run_app_test` → oculta; `run_app` → visible. |

Cómo correr la suite sin parpadeo:

```bash
# Host con GL nativo (GPU real): binario directo, ventana oculta, sin parpadeo.
./build/linux_tests/apps/<app>/<app>_tests

# CI / WSL sin display: display virtual en RAM (también headless).
xvfb-run -a -s "-screen 0 1280x800x24" \
    env LIBGL_ALWAYS_SOFTWARE=1 GALLIUM_DRIVER=llvmpipe \
    ./build/linux_tests/apps/<app>/<app>_tests

# Ver un test a ojo (desactiva headless):
FN_HEADLESS=0 ./build/linux_tests/apps/<app>/<app>_tests
```

### CI gate `check_tested.sh`

`cpp/scripts/check_tested.sh [days]` (default `30`) consulta `registry.db` y
falla con codigo != 0 si alguna funcion C++ creada en los ultimos N dias no
tiene `tested: true` en su frontmatter. Esta hookeado al final de
`cpp/scripts/run_tests.sh`, por lo que el flujo CI (`./scripts/run_tests.sh`)
falla si se anade una funcion C++ nueva sin test asociado.

Para satisfacer el gate:
1. Crear `cpp/tests/test_<name>.cpp` (puede ser placeholder Catch2 si la
   logica visual se cubre via `primitives_gallery`).
2. Anadirlo a `cpp/tests/CMakeLists.txt` con `add_fn_test(test_<name> ...)`.
3. Marcar `tested: true` + `test_file_path: cpp/tests/test_<name>.cpp` en el
   frontmatter del `.md` de la funcion.
4. Correr `fn index` para refrescar `registry.db`.