# Referência pública

Consulte imports, parâmetros, retornos e exemplos das APIs de composição, comunicação, estado e extensões.

Veja versões, mudanças e requisitos em [Framework 4.0 e CLI 1.2](/pt/docs/guides/releases/).


<span class="section-anchor" id="section-1"></span>

## Import principal

```js
import { wu } from 'wu-framework';
// Equivalente para el singleton:
// import wu from 'wu-framework';
```

O pacote define pontos de entrada ESM, CommonJS e UMD. Os subcaminhos de adaptadores, integrações, servidor, sandbox e IA são declarados em `package.json`. Importar um caminho interno não exportado não faz parte do contrato de distribuição.

<span id="core-y-lifecycle"></span>

<span class="section-anchor" id="section-2"></span>

## Core e ciclo de vida

| API | Entrada / retorno | Uso |
| --- | --- | --- |
| `wu.init(config)` | Objeto com `apps`; `Promise<void>` | Inicialização única |
| `wu.whenReady()` | `Promise<boolean>` | Aguardar um init em andamento |
| `wu.define(name, lifecycle)` | `mount` obrigatório | Registrar implementação |
| `wu.mount(name, selector)` | Seletor string; promise | Montar em um nó acessível por `document.querySelector` |
| `wu.unmount(name, options?)` | `{ force?, keepAlive? }`; promise | Liberar ou ocultar |
| `wu.update(name, props)` | Record; `Promise<boolean>` | Props vivas |
| `wu.hide(name)` / `show(name)` | Promises | Preservar/reativar uma app |
| `wu.isHidden(name)` | Booleano | Estado keep-alive |
| `wu.destroy()` | Promise | Liberar todo o runtime |
| `wu.app(name, config)` | `WuApp` | Identidade e configuração reutilizáveis; registra ao montar |

O helper exportado `init(apps)` **recebe o array**, enquanto `wu.init({ apps })` recebe o objeto. As sintaxes não são intercambiáveis. Os helpers exportados `mount`, `unmount`, `define`, `app`, `hide`, `show`, `isHidden` e `destroy` delegam ao singleton.

<span id="inicialización-tipada"></span>

<span class="section-anchor" id="section-3"></span>

### Inicialização tipada

```ts
import { wu, type WuAppConfig } from 'wu-framework';

const catalog: WuAppConfig = {
  name: 'catalog',
  url: '/apps/catalog',
  grants: [{ capability: 'store.read', resource: 'catalog' }],
};

await wu.init({ apps: [catalog], sandbox: 'module' });
await wu.mount(catalog.name, '#catalog-slot');
// Al retirar este consumidor del shell:
await wu.unmount(catalog.name);
```

O slot deve existir antes de `mount`; o manifesto deve declarar a mesma identidade e solicitar os recursos que a app usará. `unmount` libera uma referência e aplica as regras de keep-alive; `{ force: true }` solicita a desmontagem completa.

<span id="comunicación"></span>

<span class="section-anchor" id="section-4"></span>

## Comunicação

| API do singleton/fachada | Retorno |
| --- | --- |
| `emit(event, data, opts?)` | Booleano de aceitação |
| `on(event, callback)` | Função unsubscribe |
| `once(event, callback)` | Função unsubscribe |
| `off(event, callback)` | Booleano do barramento |
| `request(channel, data, opts?)` | Promise de resposta |
| `handle(channel, handler)` | Função de liberação; opções em eventBus/fachada |
| `provide(name, impl, opts?)` | Handle com `revoke()` |
| `consume(name, range?, opts?)` | Proxy; promise se `wait: true` |

`WuEvent` contém `name`, `data`, `timestamp`, `appName`, `meta`, `verified`. `WuRpcOptions` aceita `timeout`, `signal`, `version` e `range`; `WuRpcHandleOptions` aceita `version`, `allow` e `replace`.

`request` e `handle` são métodos de `wu`, `wu.eventBus` e da fachada; não são exportados como funções avulsas do pacote principal. `emit`, `on`, `once`, `off`, `provide` e `consume` também existem como helpers exportados.

`wu.handle(channel, handler, options)` preserva `version`, `allow` e `replace`. Dentro do lifecycle, `context.wu.handle` também adiciona a identidade e os grants da app; use essa facade para handlers de uma microapp.

<span id="elegir-evento-o-petición"></span>

<span class="section-anchor" id="section-5"></span>

### Escolher evento ou solicitação

```js
const unsubscribe = wu.on('catalog:selected', (event) => {
  console.log(event.data.productId);
});
wu.emit('catalog:selected', { productId: 'p-42' });

const stopLookup = wu.handle('catalog:lookup', ({ productId }) => {
  return { productId, available: true };
});
const result = await wu.request('catalog:lookup', { productId: 'p-42' });
console.log(result.available);

unsubscribe();
stopLookup();
```

O callback de evento recebe um envelope `WuEvent`; o handler RPC recebe diretamente o payload da solicitação. Mantenha as funções de remoção no ciclo de vida que instalou cada listener/provedor. Dentro de uma aplicação, use `context.wu` com as concessões correspondentes.

<span class="section-anchor" id="section-6"></span>

## Store

| Método | Retorno / observação |
| --- | --- |
| `get(path?)` / `getSnapshot(path?)` | Snapshot separado; sem identidade estável de objetos entre leituras |
| `set(path, value)` | Número de sequência |
| `update(path, updater)` | Número; updater síncrono |
| `on(pattern, callback)` | Limpeza; payload diferente em wildcard |
| `batch(record)` | Array de sequências; verificação prévia de todas as entradas |
| `tap(fn)` | Limpeza; observa commits síncronos |
| `hydrate(state, options?)` | Substitui o estado com opções de notificação |
| `sync(options?)` | Handle com `ready`, `stop`, `status` |
| `getMetrics()` | Contadores do store |
| `reset()` / `dispose()` / `clear()` | Operações de ciclo do store; não são API de persistência |

O `store` exportado pela raiz aponta para `wu.store`. Os helpers `getState`, `setState`, `onStateChange` e `syncStore` usam essa mesma instância. `new WuCore()` cria seu próprio store por padrão; o construtor permite injetar outro para composição intencional.

<span id="inspección-rendimiento-y-extensiones"></span>

<span class="section-anchor" id="section-7"></span>

## Inspeção, desempenho e extensões

| API | Função |
| --- | --- |
| `wu.inspect({ events? })` | Snapshot de apps, estado e diagnósticos |
| `wu.getAppInfo(name)` | Informações da app registrada |
| `wu.getSandboxInfo(name)` | Modo solicitado/real e propriedade |
| `wu.getManifestDiagnostics()` | Dependências declarativas inválidas |
| `wu.getStats()` | Resumo operacional |
| `wu.showInspector()` / `hideInspector()` | UI de inspeção carregada sob demanda |
| `wu.performance.startMeasure(name, app?)` | Iniciar medição |
| `wu.performance.endMeasure(name, app?)` | Terminar e retornar a duração |
| `wu.performance.generateReport()` | Relatório de medições |
| `wu.prefetch` / `prefetchAll` | Antecipar recursos |
| `wu.use('app.component')` | Carregar default export ou namespace declarado em `wu.exports`; consulte a nota sobre tipos |
| `wu.override` / `removeOverride` / `getOverrides` / `clearOverrides` | Substituição de URLs |
| `wu.pluginSystem.use(plugin, options)` | Instalação assíncrona |
| `wu.hooks.use(phase, middleware, options?)` | Middleware de lifecycle |
| `wu.aiReady()` / `timelineReady()` | Carregar subsistema adiado |

As classes exportadas incluem `WuCore`, `WuCompatibility`, `WuLoader`, `WuSandbox`, `WuManifest`, `WuStore`, `WuApp`, `WuStyleBridge`, `WuCache`, `WuEventBus`, `WuPerformance`, `WuProxySandbox`, `WuPluginSystem`, `WuLoadingStrategy`, `WuPrefetch`, `WuOverrides`, `WuErrorBoundary`, `WuContracts` e `WuLifecycleHooks`. Usar diretamente uma classe de baixo nível exige configurar suas garantias: `new WuEventBus()` começa permissivo; `wu.init()` ativa o modo estrito para o barramento do core.

<span id="tipos-que-conviene-conocer"></span>

<span class="section-anchor" id="section-8"></span>

## Tipos que convém conhecer

`WuAppConfig` descreve a configuração do host. `WuLifecycle` e `WuAppLifecycleContext` descrevem a montagem. `WuAppFacade`/`WuScopedStore` descrevem a autoridade da app. `WuPermissionRequest`, `WuCapabilityGrant` e `WuCompiledPolicy` descrevem a política. `WuSyncHandle`, `WuTimelineFacade` e `WuInspectSnapshot` descrevem subsistemas opcionais.

<span id="compatibilidad-de-las-declaraciones-typescript"></span>

<span class="section-anchor" id="section-9"></span>

### Compatibilidade das declarações TypeScript

Os esclarecimentos a seguir permitem escrever entradas válidas e consumir corretamente os retornos, inclusive onde a declaração de tipos não expressa todo o contrato:

- `resource?` em solicitações/concessões é tipado como opcional, mas o parser exige a propriedade.
- A união de entrada permite apenas a capacidade; o parser string exige `capability:resource`.
- `strategy` e `fullBleed` são lidos no runtime, mas faltam em `WuAppConfig`.
- `wu.use` existe no core, mas falta na declaração pública de `WuCore`.
- `WuLifecycleHooks.use` aparece com retorno `void`, embora a implementação retorne uma função de limpeza.
- A assinatura genérica do store não expressa corretamente o envelope wildcard.
- O tipo do host oferece `styleMode`; configure o valor efetivo no manifesto.

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-10"></span>

## Referência de implementação

Exportações efetivas: `src/index.js`; helpers: `src/index.js`; tipos públicos: `src/index.d.ts`, `src/index.d.ts`, `src/index.d.ts`, `src/index.d.ts`; subcaminhos: `package.json`. Testes: `tests/unit/package-exports.test.js`, `tests/unit/adapter-conformance.test.js`, `tests/unit/store-subscription-semantics.test.js`.

<span id="apis-de-la-versión-32"></span>

<span class="section-anchor" id="section-11"></span>

## APIs da versão 3.2

O catálogo inclui manifests declarados, foco, transições, janelas, drag and drop, shadow deployment, portas e apps instaláveis. Os [percursos de atualização](/pt/docs/guides/releases/) vinculam contratos completos, imports opcionais e tratamento de erros. As APIs anteriores de estado, eventos, IA e lifecycle continuam nas referências correspondentes.

Consulte [supervisão, recuperação e replay](/pt/docs/framework/runtime-reliability/) para `superviseApp`, `createReplaySession` e os métodos scoped `reportError`, `now` e `random`.

As entradas opcionais `ai`, `timeline`, `devtools`, `mcp`, `store-sync`, `shadow`, `windows`, `dnd`, `ports`, `wuapp`, `sandbox/iframe` e `sandbox/html-parser` têm declarações públicas. `typesVersions` também as resolve com `moduleResolution: "node10"`. Importe tipos dos subpaths publicados, não de arquivos internos.