@decido/shell-core

Decido OS Shared State, Stores and Base Hooks
Gestor de estado unificado, puente de sincronización bidireccional y utilidades de renderizado espacial para el núcleo de Decido OS.

── Descripción General ──

@decido/shell-core es la columna vertebral de persistencia, instrumentación y distribución de estado en la interfaz de usuario de Decido OS. Su responsabilidad es coordinar el puente de comunicación entre el núcleo agnóstico escrito en TypeScript Puro (impulsado por Signals en @decido/yo-decido-core) y el motor de renderizado de React (impulsado por Zustand en @decido/shell-core), garantizando reactividad extrema libre de bucles infinitos.

── Arquitectura del Sistema (Mermaid) ──

El siguiente diagrama ilustra la arquitectura de sincronización bidireccional del StateBridgeAgent y sus compuertas lógicas síncronas que neutralizan loops recursivos de renderizado:

sequenceDiagram
    autonumber
    participant Core as 🟢 yo-decido-core (TS Signals)
    participant Bridge as 🔄 StateBridgeAgent (Puente)
    participant UI as ⚛️ shell-core (Zustand Stores)

    rect rgb(240, 248, 255)
        note right of Bridge: Flujo 1: Core (Signals) ➜ React (Zustand)
        Core->>Bridge: Cambios en morphInstances() o activeMorphId()
        activate Bridge
        note right of Bridge: Activa Guard: isSyncingFromSignal = true
        Bridge->>UI: Sincroniza Map & Active ID (setState)
        note right of Bridge: Desactiva Guard: isSyncingFromSignal = false
        deactivate Bridge
    end

    rect rgb(255, 240, 245)
        note right of Bridge: Flujo 2: React (Zustand) ➜ Core (Signals)
        UI->>Bridge: Mutación en useMorphInstanceStore (subscribe)
        activate Bridge
        alt isSyncingFromSignal == true
            Bridge->>UI: Descarta (Cortocircuito de loop)
        else isSyncingFromSignal == false
            note right of Bridge: Activa Guard: isSyncingFromZustand = true
            Bridge->>Core: Llama a setters sigSetMorphInstances() o sigSetActiveMorphId()
            note right of Bridge: Desactiva Guard: isSyncingFromZustand = false
        end
        deactivate Bridge
    end

── Tabla de APIs y Tiendas ──

| Módulo / Tienda | Tipo | Responsabilidad Técnica | | :--- | :--- | :--- | | dlog (debugLogger.ts) | Servicio | Emisor de logs de telemetría estructurados con soporte de throttle síncrono (límite 50 logs/seg) que alimenta el Panel de Depuración y la Línea de Tiempo. | | useMorphInstanceStore | Zustand Store | Almacena y gestiona las pestañas/instancias espaciales activas, artefactos integrados (Gemini Canvas), y pilas históricas de Undo/Redo (límite 20 versiones). | | StateBridgeAgent | Agente | Orquestador bidireccional asíncrono que sincroniza la reactividad fina de Signals con las sub-tiendas Zustand de React. | | workspaceUtils | Utilidad Pura | Funciones puras de flex-layout para calcular transformaciones del árbol de splits (splits binarios, colapsos inteligentes y poda recursiva). | | useDebugPanelStore | Zustand Store | Registra los logs internos estructurados y permite filtrado dinámico por nivel y categorías en el Panel de Depuración. | | useActionTimelineStore | Zustand Store | Sigue el linaje secuencial de eventos y mutaciones del estado de la shell. |

── Instalación y Configuración ──

Instala el paquete de forma local en el monorepo de Decido:

pnpm add @decido/shell-core --filter @decido/os

Asegúrate de inicializar el puente de sincronización en el arranque (bootstrap) de tu aplicación React:

import { initStateBridge } from '@decido/shell-core';

async function bootstrap() {
    // Inicializar el agente síncrono antes del primer render
    await initStateBridge();
    
    // Iniciar renderizado de la UI
    renderApp();
}

── Ejemplos de Consumo Práctico ──

1. Gestión de Instancias Espaciales (Morphs) y Artefactos

import { useMorphInstanceStore } from '@decido/shell-core';

// 1. Registrar o actualizar un morph asociado a un chat
useMorphInstanceStore.getState().upsertInstance({
    id: 'chat-45',
    sourceChatId: 'chat-45',
    shellType: 'shell-canvas',
    label: 'Diagrama de Flujo',
    data: { zoom: 1 }
});

// 2. Agregar un artefacto interactivo (Gemini Canvas)
useMorphInstanceStore.getState().pushArtifact('chat-45', {
    id: 'artifact-01',
    name: 'diagram.flow',
    type: 'canvas',
    content: JSON.stringify({ nodes: [] }),
    data: { grid: true }
});

// 3. Deshacer el último cambio de configuración (Undo)
if (useMorphInstanceStore.getState().canUndo('chat-45')) {
    useMorphInstanceStore.getState().undo('chat-45');
}

2. Instrumentación y Telemetría Limpia

Evita el uso de console.log en producción. Utiliza el registrador estructurado del sistema:

import { dlog } from '@decido/shell-core';

// Registrar eventos de ciclo de vida o cambios espaciales
dlog.morph('pushStage', { type: '3d', stageId: 'lienzo-principal' });

// Depurar llamadas asíncronas a modelos fundacionales
dlog.gemini('POST generateContent', { model: 'gemini-1.5-pro', latency: 450 }, 'info');

// Capturar errores críticos de red
dlog.error('network', 'Failed to reconnect socket.io stream', { retries: 3 });

── Robustez y Suites de Pruebas (Decido Testing Shield) ──

Este paquete cuenta con una cobertura matemática estricta del 100% de cobertura en todas las categorías y archivos:

• Statements (Sentencias): 100.00%
• Branches (Ramificaciones): 100.00%
• Functions (Funciones): 100.00%
• Lines (Líneas): 100.00%

Ejecutar Pruebas Locales

Para correr el conjunto completo de pruebas unitarias locales con Vitest:

pnpm test

Ejecutar Pruebas con Reporte de Cobertura V8

Para evaluar el estado exacto de la cobertura local y auditar que ningún archivo de test influe el bundle:

pnpm test:coverage