# Referência de composição e permissões Contratos de instâncias, principals, manifestos, facades e wrappers com parâmetros e diferenças de distribuição. Veja versões, mudanças e requisitos em [Framework 4.0 e CLI 1.2](/pt/docs/guides/releases/). Esta referência reúne as APIs com as quais o host configura identidade e autoridade. Os exemplos usam `wu` importado de `wu-framework`; um objeto chamado `manifests` é criado com `new WuManifest()`. ## Distribuição e receptor O singleton é a autoridade do host. A facade `context.wu` é recebida a partir do lifecycle e concede apenas a interseção entre as solicitações do manifesto e os grants do host. Os papéis do principal controlam o acesso à interface; a autorização dos dados do servidor é verificada no servidor. ## Preparar um wrapper sobre uma 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(); ``` O destino deve existir no documento. As fichas do wrapper descrevem seus métodos de runtime; a declaração TypeScript de WuApp enumera apenas uma parte. Criar outro wrapper não substitui os grants de um registro existente. ## wu.app Cria um objeto reutilizável que mantém a identidade e a configuração de uma microapp. `wu.app(name: string, config: Partial): WuApp` - name e config.url; container aceita um seletor string ou, desde a versão 3.2, um HTMLElement. Os outros campos pertencem ao host. - **Retorno:** WuApp com registro adiado até `mount()`. - **Erros:** A montagem propaga falhas de manifest, permissões, carga e contêiner. - **Permissões:** O wrapper preserva configuração e grants do host e registra pelo core. - **Limpeza:** unmount remove o renderer; destroy do wrapper não limpa todos os registros de manifesto. ```js const catalog = wu.app('catalog', { url: '/apps/catalog', container: '#catalog-slot', }); console.log(catalog.info); ``` Referência: `src/index.js`. ## new WuCore Cria uma instância com store próprio ou um injetado deliberadamente. `new WuCore(options?): WuCore` - **Parâmetros:** store, storeBufferSize e compatibility são opcionais. - **Retorno:** Instância independente; o import wu continua sendo o singleton. - **Erros:** Não inicia apps; erros de opções/compatibility são propagados. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** await runtime.destroy() ao remover a instância. ```js import { WuCore, WuStore } from 'wu-framework'; const runtime = new WuCore({ store: new WuStore(512) }); ``` Referência: `src/core/wu-core.js`. ## wu.setPrincipal Define o principal usado pelo controle de acesso à montagem. `wu.setPrincipal(principal | null): object | null` - **Parâmetros:** role, roles e permissions como mount:catalog ou mount:*; null encerra a identidade. - **Retorno:** O mesmo principal ou null; projeta auth.principal e informa a mudança. - **Erros:** Uma gravação malsucedida no store não reverte o principal. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** wu.setPrincipal(null) quando a sessão terminar. ```js wu.setPrincipal({ roles: ['catalog-reader'] }); ``` Referência: `src/core/wu-core.js`. ## wu.getPrincipal Lê o principal atual usado pelo host. `wu.getPrincipal(): object | null` - **Parâmetros:** Sem argumentos. - **Retorno:** Referência do principal, ou null. - **Erros:** Não valida a sessão nem consulta o servidor. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js console.log(wu.getPrincipal()?.roles); ``` Referência: `src/core/wu-core.js`. ## wu.can Verifica se o principal atende aos papéis de uma aplicação. `wu.can(appName: string): boolean` - **Parâmetros:** Nome registrado; consulta os papéis normalizados do manifesto. - **Retorno:** Booleano; apps sem papéis são consideradas públicas. - **Erros:** Não verifica a existência da entrada nem concede capabilities do store/barramento. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js if (wu.can('catalog')) await wu.mount('catalog', '#catalog-slot'); ``` Referência: `src/core/wu-core.js`. ## context.wu Fornece a cada lifecycle uma autoridade revogável de aplicação. `mount(container, context: { appName, wu: WuAppFacade }): void | Promise` - **Parâmetros:** O core fornece context; uma facade não é construída a partir de um nome. - **Retorno:** Facade congelada com eventos, RPC, contratos e store limitado. - **Erros:** WU_APP_SCOPE_REVOKED após teardown; WU_CAPABILITY_DENIED ao acessar recursos sem grant. - **Permissões:** Interseção entre manifest.wu.permissions e config.grants; não expõe init, destroy nem administração global. - **Limpeza:** Libere o trabalho próprio em unmount; não reutilize a facade depois. ```js wu.define('catalog', { mount(container, { wu: appWu }) { container.textContent = String(appWu.store.get('catalog.count') ?? 0); }, }); ``` Referência: `src/core/wu-core.js`. ## new WuManifest Cria um leitor e validador de manifestos com cache próprio. `new WuManifest(): WuManifest` - **Parâmetros:** Sem argumentos obrigatórios. - **Retorno:** Instância para load, validate, create e clearCache. - **Erros:** Não concede permissões nem registra apps em um core. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** clearCache() descarta os manifestos em cache. ```js import { WuManifest } from 'wu-framework'; const manifests = new WuManifest(); ``` Referência: `src/core/wu-manifest.js`. ## WuManifest.load Baixa e normaliza wu.json a partir da URL base de uma app. `manifests.load(appUrl, { expectedName? }?): Promise` - **Parâmetros:** appUrl: base pública; expectedName vincula a identidade do registro. - **Retorno:** Manifesto normalizado; um 404 real usa o manifesto padrão. - **Erros:** WU_MANIFEST_LOAD_FAILED, WU_MANIFEST_INVALID e WU_MANIFEST_NAME_MISMATCH; rede/HTML/500 não são padrões. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** clearCache(base) quando precisar descartar a leitura. ```js const manifest = await manifests.load('/apps/catalog', { expectedName: 'catalog' }); ``` Referência: `src/core/wu-manifest.js`. ## WuManifest.validate Valida estrutura, limites, caminhos e permissões declarativas sem concedê-las. `manifests.validate(manifest, { expectedName? }?): object` - **Parâmetros:** Objeto de dados próprio; resource é obrigatório em declarações de objeto. - **Retorno:** Manifesto normalizado com snapshots congelados. - **Erros:** WU_MANIFEST_INVALID ou identidade diferente de expectedName. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js const manifest = manifests.validate({ name: 'catalog', entry: 'entry.js', wu: { permissions: [] } }); ``` Referência: `src/core/wu-manifest.js`. ## WuManifest.create Produz um manifesto a partir de uma identidade e uma configuração declarativa. `manifests.create(name, config?): object` - **Parâmetros:** name; config.entry (index.js por padrão), exports, imports, permissions, roles, metadata, styleMode, version e folder. routes não vazias não são válidas em wu.routes. - **Retorno:** Manifesto construído e validado. - **Erros:** As mesmas restrições estruturais de validate. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js const manifest = manifests.create('catalog', { entry: 'entry.js' }); ``` Referência: `src/core/wu-manifest.js`. ## WuManifest.clearCache Descarta os manifestos armazenados para baixá-los novamente. `manifests.clearCache(pattern?): void` - **Parâmetros:** Expressão regular em string; sem padrão, remove todo o cache desta instância. - **Retorno:** void. - **Erros:** Um padrão RegExp inválido emite um aviso e não remove entradas; não altera os registros compilados do core. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js manifests.clearCache('/apps/catalog'); ``` Referência: `src/core/wu-manifest.js`. ## wu.compatibility.configure Configura pontes limitadas de migração entre os perfis strict e compat-v2. `wu.compatibility.configure(config): WuCompatibility` - **Parâmetros:** profile, warnings e opções ai/plugins/apps/sync; não é um sandbox adicional. - **Retorno:** A mesma instância. - **Erros:** Configuração ou feature desconhecida pode lançar um erro. - **Permissões:** Apenas host; cada ponte deve ser habilitada explicitamente. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js wu.compatibility.configure({ profile: 'strict', warnings: 'once' }); ``` Referência: `src/core/wu-compatibility.js`. ## wu.compatibility.getConfig Consulta o perfil efetivo e suas pontes de migração. `wu.compatibility.getConfig(): object` - **Parâmetros:** Sem argumentos. - **Retorno:** Configuração de compatibilidade. - **Erros:** Não comprova que um consumidor esteja usando uma ponte. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js console.log(wu.compatibility.getConfig()); ``` Referência: `src/core/wu-compatibility.js`. ## wu.compatibility.getMigrationReport Lê avisos acumulados de uso de compatibilidade. `wu.compatibility.getMigrationReport(): object[]` - **Parâmetros:** Sem argumentos. - **Retorno:** Entradas com código, mensagem, contagem e tempos. - **Erros:** Registra apenas usos instrumentados; não é uma análise estática das suas apps. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js console.table(wu.compatibility.getMigrationReport()); ``` Referência: `src/core/wu-compatibility.js`. ## wu.compatibility.clearMigrationReport Reinicia o registro de avisos de migração. `wu.compatibility.clearMigrationReport(): void` - **Parâmetros:** Sem argumentos. - **Retorno:** void. - **Erros:** Não altera as opções de compatibilidade. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js wu.compatibility.clearMigrationReport(); ``` Referência: `src/core/wu-compatibility.js`. ## WuApp.mount Monta a identidade do wrapper e guarda o seletor. `widget.mount(target?: string | HTMLElement): Promise` - **Parâmetros:** Seletor opcional; usa config.container quando ausente. - **Retorno:** Promise - **Erros:** Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar. - **Permissões:** Autoridade do core proprietário do wrapper. - **Limpeza:** Equilibre com widget.unmount(). ```js await widget.mount('#widget-slot'); ``` Referência: `src/core/wu-app.js`. ## WuApp.unmount Libera a referência do wrapper ou mantém keep-alive. `widget.unmount(options?: { force?: boolean; keepAlive?: boolean }): Promise` - **Parâmetros:** force remove completamente; keepAlive mantém o DOM. - **Retorno:** Promise - **Erros:** Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar. - **Permissões:** Autoridade do core proprietário do wrapper. - **Limpeza:** Chama o unmount do renderizador quando necessário. ```js await widget.unmount({ force: true }); ``` Referência: `src/core/wu-app.js`. ## WuApp.hide Oculta uma instância mantida pelo wrapper. `widget.hide(): Promise` - **Parâmetros:** Sem argumentos; requer uma instância montada. - **Retorno:** Promise - **Erros:** Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar. - **Permissões:** Autoridade do core proprietário do wrapper. - **Limpeza:** deactivate deve pausar os timers próprios. ```js await widget.hide(); ``` Referência: `src/core/wu-app.js`. ## WuApp.show Reativa a instância keep-alive do wrapper. `widget.show(): Promise` - **Parâmetros:** Sem argumentos; requer estado oculto. - **Retorno:** Promise - **Erros:** Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar. - **Permissões:** Autoridade do core proprietário do wrapper. - **Limpeza:** Finalize depois com unmount. ```js await widget.show(); ``` Referência: `src/core/wu-app.js`. ## WuApp.remount Força a desmontagem e monta novamente no destino escolhido. `widget.remount(target?: string | HTMLElement): Promise` - **Parâmetros:** Seletor opcional; mantém o último destino. - **Retorno:** Promise - **Erros:** Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar. - **Permissões:** Autoridade do core proprietário do wrapper. - **Limpeza:** Destrói o renderizador anterior. ```js await widget.remount('#widget-slot'); ``` Referência: `src/core/wu-app.js`. ## WuApp.reload Limpa os caches disponíveis de loader/manifesto e monta novamente. `widget.reload(): Promise` - **Parâmetros:** Sem argumentos; usa o destino guardado. - **Retorno:** Promise - **Erros:** Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar. - **Permissões:** Autoridade do core proprietário do wrapper. - **Limpeza:** Não invalida o cache nativo de import ESM do navegador. ```js await widget.reload(); ``` Referência: `src/core/wu-app.js`. ## WuApp.verify Inspeciona registro, montagem e ShadowRoot do slot. `widget.verify(): Promise` - **Parâmetros:** Sem argumentos; hasContent conta os filhos do ShadowRoot. - **Retorno:** Promise - **Erros:** Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar. - **Permissões:** Autoridade do core proprietário do wrapper. - **Limpeza:** Leitura; não garante conteúdo de um renderizador no light DOM. ```js console.log(await widget.verify()); ``` Referência: `src/core/wu-app.js`. ## WuApp.destroy Desmonta e remove o nome do mapa público de apps. `widget.destroy(): Promise` - **Parâmetros:** Sem argumentos. - **Retorno:** Promise - **Erros:** Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar. - **Permissões:** Autoridade do core proprietário do wrapper. - **Limpeza:** Não remove todos os registros de manifesto; não use como substituição geral de identidade. ```js await widget.destroy(); ``` Referência: `src/core/wu-app.js`. ## WuApp.info / isMounted / isHidden Consulta identidade, seletor e estado de um wrapper. `widget.info; widget.isMounted; widget.isHidden` - **Parâmetros:** São getters, não funções. - **Retorno:** info é um objeto; isMounted/isHidden são valores de estado. - **Erros:** Não substituem a verificação de conteúdo do renderizador. - **Permissões:** Host; não está disponível na facade da aplicação. - **Limpeza:** Não cria recursos que precisem ser liberados. ```js console.log(widget.info, widget.isMounted, widget.isHidden); ``` Referência: `src/core/wu-app.js`. Consulte [supervisão, recuperação e replay](/pt/docs/framework/runtime-reliability/) para `superviseApp`, `createReplaySession` e os métodos scoped `reportError`, `now` e `random`. O primeiro provider é dono do nome de um contrato. Outra app, ou o host substituindo um contrato de app, recebe `WU_CAPABILITY_OWNED` até o proprietário revogar o contrato ou desmontar. O mesmo proprietário pode substituir sua implementação. Quando há `shape`, portas remotas só expõem os métodos declarados por ela.