Configuración para web y escritorio

Tres niveles diferentes

Cambiar una opción JSON no transforma un ejecutable nativo en una aplicación web. Ambos artefactos se construyen a partir del mismo código compartido.

Archivos propuestos

config/common.json     → Valores compartidos
config/desktop.json    → Ajustes del host de escritorio
config/web.json        → Ajustes del host web

Los ejemplos siguientes son un contrato de configuración para implementar. No existe todavía un cargador que los ejecute.

Configuración común

{
  "schema_version": 1,
  "app": {
    "id": "guaba-container",
    "title": "Guaba Core",
    "subtitle": "Espacio de trabajo"
  },
  "appearance": {
    "theme": "dark",
    "density": "comfortable"
  },
  "layout": {
    "header_height": 43,
    "menu_height": 30,
    "toolbar_height": 53,
    "tabs_height": 38,
    "footer_height": 27,
    "sidebar_width": 221,
    "sidebar_collapsed_width": 62,
    "context_panel_width": 269,
    "compact_breakpoint": 760,
    "overlay_breakpoint": 1050
  },
  "visibility": {
    "header": true,
    "menu": true,
    "sidebar": true,
    "toolbar": true,
    "tabs": true,
    "context_panel": true,
    "footer": true
  },
  "workspace": {
    "start_screen": "home",
    "confirm_close_when_dirty": true,
    "screens": {
      "home": {
        "instance_policy": "single"
      },
      "demo-editor": {
        "instance_policy": "multiple",
        "max_instances": 2
      }
    }
  },
  "preferences": {
    "enabled": true,
    "namespace": "guaba-container-ui-v1"
  }
}

El editor de ejemplo tiene un máximo de dos instancias para comprobar la independencia entre pestañas. Otros tipos de vista pueden definir sus propios límites.

Perfil de escritorio

{
  "schema_version": 1,
  "host": {
    "kind": "desktop",
    "native_decorations": true,
    "window": {
      "initial_width": 1440,
      "initial_height": 1000,
      "min_width": 960,
      "min_height": 640,
      "resizable": true
    }
  }
}

Las dimensiones son puntos lógicos. La ventana inicial debe ajustarse al área útil del monitor. Con native_decorations activado, el sistema operativo aporta su barra de título y controles; el header interno no los duplica.

Perfil web

{
  "schema_version": 1,
  "host": {
    "kind": "web",
    "canvas_id": "guaba_canvas",
    "fit_to_viewport": true,
    "show_loading_state": true,
    "show_startup_error": true
  }
}

La página host aporta el canvas y los estados de arranque. Al finalizar la inicialización, oculta el indicador de carga. Un fallo mantiene un mensaje visible con opción de reintento. El tamaño del canvas sigue al área disponible en el navegador.

Composición de valores

El orden de precedencia será:

Valores predeterminados tipados
    → common.json
    → perfil del target compilado
    → preferencias válidas permitidas

Cada capa sobrescribe únicamente los campos que proporciona. El perfil tiene una estructura tipada y solo puede ajustar campos permitidos para esa plataforma. La selección del adaptador real depende del target compilado; host.kind debe coincidir con él.

Las preferencias solo podrán cambiar tema, densidad, contracción del sidebar y visibilidad o ancho del panel contextual. No podrán redefinir identidades de pantallas, sus límites de instancias o las capacidades del host.

Carga por plataforma

Escritorio: los valores comunes y el perfil predeterminado se incluyen en el ejecutable. Una ruta explícita de configuración podrá reemplazar el perfil mediante un argumento de arranque. No se dependerá del directorio desde el que se ejecutó el programa.

Web: los valores comunes y el perfil predeterminado también estarán incluidos. Opcionalmente se podrá cargar un archivo público config/web.json relativo a la URL base de despliegue antes de iniciar el contenedor. Si no existe, se utilizan los valores incluidos. No se requiere leer variables de entorno del equipo del usuario.

La página de arranque debe aplicar un tiempo máximo a la lectura del archivo web opcional para evitar una pantalla de carga indefinida.

Validación y recuperación

La configuración se deserializa y valida antes de crear el contenedor. Se verificarán la versión del esquema, los rangos de tamaños, la relación entre breakpoints, las opciones enumeradas y los identificadores de pantallas registradas.

Un archivo desconocido o inválido se rechaza como una unidad y se utilizan los valores incluidos. El footer y un mensaje de configuración informarán del uso de valores predeterminados. Una preferencia dañada se omite sin impedir el inicio.

Los anchos restaurados se ajustan al espacio disponible. No se debe restaurar una configuración que deje inaccesible el área central.

Preferencias persistentes

El contenedor define un adaptador de preferencias. La integración de persistencia de eframe puede utilizarse como implementación inicial: el framework ofrece almacenamiento del estado en escritorio y navegador cuando se activa la característica correspondiente. La aplicación decide qué valores guardar. Contrato de persistencia.

Solo se guardan los ajustes visuales permitidos y una versión del esquema. La falta de almacenamiento conserva los valores en memoria durante la sesión; el contenedor debe seguir funcionando.

Construcción y distribución

Una vez implementado el proyecto, Cargo generará el ejecutable nativo y Trunk generará el paquete web. En desarrollo se usará el servidor local de Trunk; el resultado web se distribuirá mediante un servidor estático.

Los comandos exactos, los targets y las versiones se añadirán al README de la implementación cuando se haya comprobado la construcción. Abrir el HTML por doble clic seguirá siendo una facilidad del prototipo actual, no el mecanismo de ejecución previsto para WebAssembly.