# Referencia de composición y permisos Contratos de instancias, principals, manifests, facades y wrappers con parámetros y diferencias de distribución. Consulta las versiones, cambios y requisitos en [Framework 4.0 y CLI 1.2](/es/docs/guides/releases/). Esta referencia reúne las APIs con las que el host configura identidad y autoridad. Los ejemplos usan `wu` importado desde `wu-framework`; un objeto llamado `manifests` se crea con `new WuManifest()`. ## Distribución y receptor El singleton es autoridad de host. La facade `context.wu` se recibe desde el lifecycle y concede solo la intersección de solicitudes del manifest y grants del host. Los roles del principal controlan acceso de interfaz; la autorización de datos del servidor se verifica en el servidor. ## Preparar un wrapper sobre una app registrada ```js import { wu, WuManifest } from 'wu-framework'; const manifests = new WuManifest(); await wu.init({ apps: [{ name: 'widget', url: '/apps/widget' }] }); const widget = wu.app('widget', { url: '/apps/widget', container: '#widget-slot', }); await widget.mount(); ``` El destino debe existir en el documento. Las fichas del wrapper describen sus métodos de runtime; la declaración TypeScript de WuApp solo enumera una parte. Crear otro wrapper no sustituye los grants de un registro existente. ## wu.app Crea un objeto reutilizable que conserva la identidad y configuración de una microapp. `wu.app(name: string, config: Partial): WuApp` - **Parámetros:** name y config.url; container acepta un selector string o, desde 3.2, un HTMLElement. Los demás campos pertenecen al host. - **Retorno:** WuApp con registro diferido hasta `mount()`. - **Errores:** El montaje propaga fallos del manifest, permisos, carga y contenedor. - **Permisos:** El wrapper conserva configuración y grants del host y registra mediante el core. - **Limpieza:** unmount retira renderer; destroy del wrapper no limpia todos los registros de manifest. ```js const catalog = wu.app('catalog', { url: '/apps/catalog', container: '#catalog-slot', }); console.log(catalog.info); ``` Referencia: `src/index.js`. ## new WuCore Crea una instancia con store propio o uno inyectado de forma deliberada. `new WuCore(options?): WuCore` - **Parámetros:** store, storeBufferSize y compatibility son opcionales. - **Retorno:** Instancia independiente; el import wu continúa siendo el singleton. - **Errores:** No inicia apps; errores de opciones/compatibility se propagan. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** await runtime.destroy() al retirar la instancia. ```js import { WuCore, WuStore } from 'wu-framework'; const runtime = new WuCore({ store: new WuStore(512) }); ``` Referencia: `src/core/wu-core.js`. ## wu.setPrincipal Establece el principal usado por el control de acceso al montaje. `wu.setPrincipal(principal | null): object | null` - **Parámetros:** role, roles y permissions como mount:catalog o mount:*; null cierra la identidad. - **Retorno:** El mismo principal o null; proyecta auth.principal e informa el cambio. - **Errores:** Una escritura fallida en el store no revierte el principal. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** wu.setPrincipal(null) cuando termine la sesión. ```js wu.setPrincipal({ roles: ['catalog-reader'] }); ``` Referencia: `src/core/wu-core.js`. ## wu.getPrincipal Lee el principal actual que utiliza el host. `wu.getPrincipal(): object | null` - **Parámetros:** Sin argumentos. - **Retorno:** Referencia del principal, o null. - **Errores:** No valida sesión ni consulta al servidor. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js console.log(wu.getPrincipal()?.roles); ``` Referencia: `src/core/wu-core.js`. ## wu.can Comprueba si el principal satisface los roles de una aplicación. `wu.can(appName: string): boolean` - **Parámetros:** Nombre registrado; consulta roles normalizados del manifest. - **Retorno:** Booleano; apps sin roles se consideran públicas. - **Errores:** No comprueba existencia del entry ni concede capabilities del store/bus. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js if (wu.can('catalog')) await wu.mount('catalog', '#catalog-slot'); ``` Referencia: `src/core/wu-core.js`. ## context.wu Entrega a cada lifecycle una autoridad revocable de aplicación. `mount(container, context: { appName, wu: WuAppFacade }): void | Promise` - **Parámetros:** El core entrega context; no se construye una facade a partir de un nombre. - **Retorno:** Facade congelada con eventos, RPC, contratos y store limitado. - **Errores:** WU_APP_SCOPE_REVOKED tras teardown; WU_CAPABILITY_DENIED al acceder a recursos sin grant. - **Permisos:** Intersección manifest.wu.permissions y config.grants; no expone init, destroy ni administración global. - **Limpieza:** Libera trabajo propio en unmount; no reutilices la facade después. ```js wu.define('catalog', { mount(container, { wu: appWu }) { container.textContent = String(appWu.store.get('catalog.count') ?? 0); }, }); ``` Referencia: `src/core/wu-core.js`. ## new WuManifest Crea un lector y validador de manifests con caché propia. `new WuManifest(): WuManifest` - **Parámetros:** Sin argumentos requeridos. - **Retorno:** Instancia para load, validate, create y clearCache. - **Errores:** No otorga permisos ni registra apps en un core. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** clearCache() descarta manifests cacheados. ```js import { WuManifest } from 'wu-framework'; const manifests = new WuManifest(); ``` Referencia: `src/core/wu-manifest.js`. ## WuManifest.load Descarga y normaliza wu.json desde la URL base de una app. `manifests.load(appUrl, { expectedName? }?): Promise` - **Parámetros:** appUrl: base pública; expectedName vincula la identidad del registro. - **Retorno:** Manifest normalizado; un 404 real usa el manifest por defecto. - **Errores:** WU_MANIFEST_LOAD_FAILED, WU_MANIFEST_INVALID y WU_MANIFEST_NAME_MISMATCH; red/HTML/500 no son defaults. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** clearCache(base) cuando necesites descartar la lectura. ```js const manifest = await manifests.load('/apps/catalog', { expectedName: 'catalog' }); ``` Referencia: `src/core/wu-manifest.js`. ## WuManifest.validate Valida estructura, límites, rutas y permisos declarativos sin concederlos. `manifests.validate(manifest, { expectedName? }?): object` - **Parámetros:** Objeto de datos propio; resource es obligatorio en declaraciones objeto. - **Retorno:** Manifest normalizado con snapshots congelados. - **Errores:** WU_MANIFEST_INVALID o identidad distinta de expectedName. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js const manifest = manifests.validate({ name: 'catalog', entry: 'entry.js', wu: { permissions: [] } }); ``` Referencia: `src/core/wu-manifest.js`. ## WuManifest.create Produce un manifest desde una identidad y configuración declarativa. `manifests.create(name, config?): object` - **Parámetros:** name; config.entry (index.js por defecto), exports, imports, permissions, roles, metadata, styleMode, version y folder. routes no vacías no son válidas en wu.routes. - **Retorno:** Manifest construido y validado. - **Errores:** Las mismas restricciones estructurales de validate. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js const manifest = manifests.create('catalog', { entry: 'entry.js' }); ``` Referencia: `src/core/wu-manifest.js`. ## WuManifest.clearCache Descarta manifests almacenados para volver a descargarlos. `manifests.clearCache(pattern?): void` - **Parámetros:** Expresión regular en string; sin patrón elimina toda la caché de esta instancia. - **Retorno:** void. - **Errores:** Un patrón RegExp inválido advierte y no elimina entradas; no altera registros compilados del core. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js manifests.clearCache('/apps/catalog'); ``` Referencia: `src/core/wu-manifest.js`. ## wu.compatibility.configure Configura puentes acotados de migración entre perfiles strict y compat-v2. `wu.compatibility.configure(config): WuCompatibility` - **Parámetros:** profile, warnings y opciones ai/plugins/apps/sync; no es un sandbox adicional. - **Retorno:** La misma instancia. - **Errores:** Configuración o feature desconocida puede lanzar. - **Permisos:** Solo host; cada puente debe habilitarse explícitamente. - **Limpieza:** No crea recursos que deban liberarse. ```js wu.compatibility.configure({ profile: 'strict', warnings: 'once' }); ``` Referencia: `src/core/wu-compatibility.js`. ## wu.compatibility.getConfig Consulta el perfil efectivo y sus puentes de migración. `wu.compatibility.getConfig(): object` - **Parámetros:** Sin argumentos. - **Retorno:** Configuración de compatibilidad. - **Errores:** No demuestra que un consumidor esté usando un puente. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js console.log(wu.compatibility.getConfig()); ``` Referencia: `src/core/wu-compatibility.js`. ## wu.compatibility.getMigrationReport Lee advertencias acumuladas de uso de compatibilidad. `wu.compatibility.getMigrationReport(): object[]` - **Parámetros:** Sin argumentos. - **Retorno:** Entradas con código, mensaje, conteo y tiempos. - **Errores:** Solo registra usos instrumentados; no es un análisis estático de tus apps. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js console.table(wu.compatibility.getMigrationReport()); ``` Referencia: `src/core/wu-compatibility.js`. ## wu.compatibility.clearMigrationReport Reinicia el registro de advertencias de migración. `wu.compatibility.clearMigrationReport(): void` - **Parámetros:** Sin argumentos. - **Retorno:** void. - **Errores:** No cambia las opciones de compatibilidad. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js wu.compatibility.clearMigrationReport(); ``` Referencia: `src/core/wu-compatibility.js`. ## WuApp.mount Monta la identidad del wrapper y recuerda el selector. `widget.mount(target?: string | HTMLElement): Promise` - **Parámetros:** Selector opcional; utiliza config.container cuando falta. - **Retorno:** Promise - **Errores:** Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar. - **Permisos:** Autoridad del core propietario del wrapper. - **Limpieza:** Equilibra con widget.unmount(). ```js await widget.mount('#widget-slot'); ``` Referencia: `src/core/wu-app.js`. ## WuApp.unmount Libera la referencia del wrapper o conserva keep-alive. `widget.unmount(options?: { force?: boolean; keepAlive?: boolean }): Promise` - **Parámetros:** force retira completamente; keepAlive conserva DOM. - **Retorno:** Promise - **Errores:** Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar. - **Permisos:** Autoridad del core propietario del wrapper. - **Limpieza:** Llama al unmount del renderer cuando corresponde. ```js await widget.unmount({ force: true }); ``` Referencia: `src/core/wu-app.js`. ## WuApp.hide Oculta una instancia conservada por el wrapper. `widget.hide(): Promise` - **Parámetros:** Sin argumentos; requiere una instancia montada. - **Retorno:** Promise - **Errores:** Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar. - **Permisos:** Autoridad del core propietario del wrapper. - **Limpieza:** deactivate debe pausar timers propios. ```js await widget.hide(); ``` Referencia: `src/core/wu-app.js`. ## WuApp.show Reactiva la instancia keep-alive del wrapper. `widget.show(): Promise` - **Parámetros:** Sin argumentos; requiere estado oculto. - **Retorno:** Promise - **Errores:** Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar. - **Permisos:** Autoridad del core propietario del wrapper. - **Limpieza:** Finaliza después con unmount. ```js await widget.show(); ``` Referencia: `src/core/wu-app.js`. ## WuApp.remount Fuerza desmontaje y monta otra vez sobre el destino elegido. `widget.remount(target?: string | HTMLElement): Promise` - **Parámetros:** Selector opcional; conserva el último destino. - **Retorno:** Promise - **Errores:** Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar. - **Permisos:** Autoridad del core propietario del wrapper. - **Limpieza:** Destruye el renderer anterior. ```js await widget.remount('#widget-slot'); ``` Referencia: `src/core/wu-app.js`. ## WuApp.reload Limpia las cachés de loader/manifest disponibles y vuelve a montar. `widget.reload(): Promise` - **Parámetros:** Sin argumentos; utiliza el destino recordado. - **Retorno:** Promise - **Errores:** Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar. - **Permisos:** Autoridad del core propietario del wrapper. - **Limpieza:** No invalida el caché nativo de import ESM del navegador. ```js await widget.reload(); ``` Referencia: `src/core/wu-app.js`. ## WuApp.verify Inspecciona registro, montaje y ShadowRoot del slot. `widget.verify(): Promise` - **Parámetros:** Sin argumentos; hasContent cuenta hijos del ShadowRoot. - **Retorno:** Promise - **Errores:** Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar. - **Permisos:** Autoridad del core propietario del wrapper. - **Limpieza:** Lectura; no asegura contenido de un renderer en light DOM. ```js console.log(await widget.verify()); ``` Referencia: `src/core/wu-app.js`. ## WuApp.destroy Desmonta y elimina el nombre del mapa público de apps. `widget.destroy(): Promise` - **Parámetros:** Sin argumentos. - **Retorno:** Promise - **Errores:** Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar. - **Permisos:** Autoridad del core propietario del wrapper. - **Limpieza:** No elimina todos los registros de manifest; no lo uses como reemplazo general de identidad. ```js await widget.destroy(); ``` Referencia: `src/core/wu-app.js`. ## WuApp.info / isMounted / isHidden Consulta identidad, selector y estado de un wrapper. `widget.info; widget.isMounted; widget.isHidden` - **Parámetros:** Son getters, no funciones. - **Retorno:** info es objeto; isMounted/isHidden son valores de estado. - **Errores:** No sustituyen la comprobación de contenido del renderer. - **Permisos:** Host; no está disponible en la facade de aplicación. - **Limpieza:** No crea recursos que deban liberarse. ```js console.log(widget.info, widget.isMounted, widget.isHidden); ``` Referencia: `src/core/wu-app.js`. Consulta [supervisión, recuperación y replay](/es/docs/framework/runtime-reliability/) para `superviseApp`, `createReplaySession` y los métodos scoped `reportError`, `now` y `random`. El primer proveedor conserva la propiedad del nombre de un contrato. Otra app, o el host sobre un contrato de app, recibe `WU_CAPABILITY_OWNED` hasta que el propietario revoque el contrato o se desmonte. El mismo propietario puede reemplazar su implementación. Cuando hay `shape`, los puertos remotos solo exponen los métodos declarados por ella.