vitral 0.1.0 → 0.2.0

package/README.md

@@ -1,162 +1,100 @@
-<p align="center"><img src="docs/logo.svg" width="96" alt="vitral"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/logo.svg" width="96" alt="vitral"></p>
 
 <h1 align="center">vitral</h1>
 
 <p align="center"><strong>Feito de partes. Visto como um todo.</strong></p>
 
-[![CI](https://github.com/joaogabriel15/vitral/actions/workflows/ci.yml/badge.svg)](https://github.com/joaogabriel15/vitral/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/vitral)](https://www.npmjs.com/package/vitral)
-[![tamanho](https://img.shields.io/bundlejs/size/vitral)](https://bundlejs.com/?q=vitral)
-[![licença](https://img.shields.io/npm/l/vitral)](LICENSE)
-
-```bash
-npm install vitral
-```
+<p align="center">
+  <a href="https://github.com/joaogabriel15/vitral/actions/workflows/ci.yml"><img src="https://github.com/joaogabriel15/vitral/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/vitral"><img src="https://img.shields.io/npm/v/vitral" alt="npm"></a>
+  <a href="https://bundlejs.com/?q=vitral"><img src="https://img.shields.io/bundlejs/size/vitral" alt="tamanho"></a>
+  <a href="https://github.com/joaogabriel15/vitral/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/vitral" alt="licença MIT"></a>
+</p>
 
 Junte micro-frontends de qualquer framework numa página só, sem configuração de build no host.
 
-- Cada app publica um módulo e o host só precisa da URL dele.
-- React, Vue, Angular, Svelte e os outros convivem na mesma tela.
-- CSS, erros e deploys ficam isolados por app.
-
-```
-host (qualquer framework)                 remote (qualquer framework)
-┌────────────────────────────┐   URL      ┌──────────────────────────────┐
-│ configure({ remotes })     │ ─────────▶ │ vitral.json  { entry, css,   │
-│ <Remote name="carrinho" /> │            │              integrity }     │
-│                            │ ◀───────── │ remote.js  mount/update/     │
-│ events (barramento global) │  import()  │            unmount           │
-└────────────────────────────┘            └──────────────────────────────┘
+```bash
+npm install vitral
 ```
 
-## Por que é diferente
-
-| Dor comum (Module Federation, single-spa) | Como o vitral resolve |
-|---|---|
-| Host e remote precisam de config de build combinada | Host não tem config de build nenhuma. Só `configure({ remotes })` em runtime. |
-| `shared` / singletons quebram com versões diferentes de React/Vue | Por padrão cada remote leva o próprio framework, isolado na sua própria root. Nenhum conflito de versão. Compartilhar é opcional (import map). |
-| Erro de um remote derruba a página | Cada remote tem estado de loading, erro e "tentar de novo" próprios. |
-| CSS de um vaza no outro; Tailwind do remote sem classes ou quebrando o host | O remote leva o próprio CSS, já com escopo automático. `isolate="shadow"` isola de vez, e o `@property` do Tailwind v4 continua funcionando. |
-| Cache velho depois do deploy (`ChunkLoadError`) | Arquivos com hash; só o `vitral.json` é revalidado. |
-| Roteadores brigando | `navigate(url)` mantém host e remotes na mesma URL. |
-| Executar JS de outra origem sem garantia | Allowlist de origens + verificação de hash SRI antes de executar. |
-| Muitos conceitos (containers, exposes, lifecycles, root config) | Um contrato: `mount(el, props, ctx) → { update, unmount }`. |
-
-## Frameworks suportados
-
-| Framework | Remote (publicar) | Host (consumir) | Import |
-|---|---|---|---|
-| React 18/19 | `reactRemote(App)` | `<Remote>` | `vitral/react` |
-| Next.js (App e Pages Router) | igual ao React | `<Remote>` (já é `'use client'`, SSR seguro) | `vitral/react` |
-| Vue 3 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
-| Nuxt 3/4 | igual ao Vue | `<VitralRemote>` (SSR seguro) | `vitral/vue` |
-| Angular 17+ (standalone, com ou sem zone.js) | `angularRemote(AppComponent, { providers })` | `<vitral-remote>` + `provideVitral()` | `vitral/angular` |
-| Svelte 5 / SvelteKit | `svelteRemote(App)` | `use:remote` ou `<vitral-remote>` | `vitral/svelte` |
-| Solid / SolidStart | `solidRemote(App)` | `<Remote>` | `vitral/solid` |
-| Preact | `preactRemote(App)` | `<Remote>` | `vitral/preact` |
-| Lit, Stencil, Web Components | `elementRemote('meu-widget')` | `<vitral-remote>` | `vitral/element` |
-| JS / TypeScript puro | `component(render)` | `<vitral-remote>` | `vitral`, `vitral/element` |
-| Qualquer outro (Astro, Qwik, jQuery, HTML do servidor…) | `defineRemote({ mount })` | `<vitral-remote>` | `vitral/element` |
-
-Todas as 72 combinações host × remote dos exemplos (9 hosts × 8 remotes) são
-testadas no navegador a cada execução do e2e.
+- O host só precisa da URL de cada remote.
+- React, Vue, Angular, Svelte, Solid, Preact, Lit e JS puro na mesma página.
+- Cada remote tem o próprio CSS, os próprios erros e o próprio deploy.
 
-## Uso
+## Começo rápido
 
-### Publicar um remote
+Para gerar host e remote prontos: `npm create vitral@latest`.
 
-```js
-// React                                  // Vue
-import { reactRemote } from 'vitral/react'  import { vueRemote } from 'vitral/vue'
-export default reactRemote(Carrinho)      export default vueRemote(Catalogo, { setup: (app) => app.use(pinia) })
-
-// Svelte (o contexto chega na prop `vitral`)
-import { svelteRemote } from 'vitral/svelte'
-export default svelteRemote(Cartao)
-
-// Solid / Preact (o contexto chega na prop `vitral`)
-export default solidRemote(Cartao)        export default preactRemote(Cartao)
-
-// Angular: props viram inputs; contexto com injectVitral()
-import { angularRemote } from 'vitral/angular'
-export default angularRemote(CartaoComponent, { providers: [provideHttpClient()] })
+**1. No remote**, exporte o componente e use o plugin:
 
-// Lit / Web Component: props viram propriedades; contexto em `this.vitral`
-import { elementRemote } from 'vitral/element'
-export default elementRemote('lit-cartao', () => customElements.define('lit-cartao', LitCartao))
-```
-
-JS ou TypeScript puro, sem framework nenhum:
-
-```ts
-import { component, html } from 'vitral'
-
-export default component<{ mensagem?: string }>({
-  state: { cliques: 0 },
-  render: ({ mensagem }, state, ctx) => html`
-    <p>${mensagem}</p>
-    <button onclick=${() => state.cliques++}>cliques: ${state.cliques}</button>
-  `,
-})
+```jsx
+// src/App.jsx (ou .vue, .svelte, .tsx…)
+export default function Carrinho({ userId }) { … }
 ```
 
-Sem estado, basta a função: ``component(({ nome }) => html`<p>Olá, ${nome}</p>`)``.
-Tudo que entra no `${}` é escapado, então dá para colocar dado do usuário sem
-risco de XSS. Mudar o `state` ou receber props novas atualiza a tela sozinho.
-Se precisar de controle total, `defineRemote({ mount(el, props, ctx) { ... } })`
-continua disponível.
-
-Build com o plugin (o mesmo para todos os frameworks):
-
 ```js
 // vite.config.js
+import react from '@vitejs/plugin-react'
 import vitral from 'vitral/vite'
-export default { plugins: [react() /* ou vue(), svelte(), solid(), angular()… */, vitral({ entry: 'src/remote.jsx' })] }
-```
-
-`vite build` gera `dist/remote-[hash].js`, `dist/remote-[hash].css` e
-`dist/vitral.json` (com o hash `sha384` do JS). Suba a pasta em qualquer CDN com
-CORS. Para Angular use `@analogjs/vite-plugin-angular` (compila em AOT).
 
-### CSS e Tailwind
+export default { plugins: [react(), vitral()] }
+```
 
-Use Tailwind (ou qualquer CSS) no remote normalmente. O plugin prefixa o CSS
-com `[data-vitral-scope="nome"]` e transforma `:root`/`html`/`body` na raiz do
-remote, então o preflight e o tema não vazam para o host, e o host não precisa
-escanear os arquivos do remote. Com `isolate="shadow"`, as regras `@property`
-do Tailwind v4 sobem para o documento para que sombras, rings e gradientes
-funcionem. Veja [docs/PROBLEMAS.md](docs/PROBLEMAS.md).
+O plugin descobre o framework e embrulha o `export default` com o adaptador certo. A entrada padrão é `src/remote.*` ou `src/App.*`.
 
-Sem Vite? Qualquer bundler serve (webpack, Rspack, esbuild, Rollup, Angular
-CLI): basta gerar um módulo ES cujo `default` tenha `mount(el, props, ctx)`.
+`vite build` gera o JS, o CSS e um `vitral.json`. Publique a pasta `dist` em qualquer CDN com CORS.
 
-### Consumir no host (React / Next)
+**2. No host**, registre a URL e use o componente:
 
 ```jsx
 import { configure } from 'vitral'
-import { Remote, useEventValue } from 'vitral/react'
+import { Remote } from 'vitral/react'
 
-configure({ remotes: '/remotes.json' })            // ou um objeto { nome: url }
+configure({
+  remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' },
+})
 
-function App() {
-  const total = useEventValue('carrinho:total')
+export function App() {
   return (
     <Remote
       name="carrinho"
       props={{ userId: 42 }}
-      isolate="shadow"
-      fallback={<Spinner />}
-      error={(err, retry) => <button onClick={retry}>Tentar de novo</button>}
+      fallback={<p>Carregando…</p>}
+      error={(erro, tentarDeNovo) => <button onClick={tentarDeNovo}>Tentar de novo</button>}
     />
   )
 }
 ```
 
-`<Remote>` já é `'use client'`. No Next ele renderiza o `fallback` no servidor
-e monta o remote no cliente, então funciona no App Router e no Pages Router
-sem `dynamic(..., { ssr: false })`.
+Pronto. Mudar `props` atualiza o remote sem remontar.
+
+Sem build no host, numa página HTML qualquer:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/vitral/dist/auto.js"></script>
+<vitral-remote src="https://cdn.empresa.com/carrinho/vitral.json"></vitral-remote>
+```
+
+Todos os componentes de host aceitam `src` no lugar de `name`.
+
+## Frameworks
+
+| Framework | Remote | Host | Import |
+|---|---|---|---|
+| React 18/19 | `reactRemote(App)` | `<Remote>` | `vitral/react` |
+| Next.js (App e Pages Router) | `reactRemote(App)` | `<Remote>` | `vitral/react` |
+| Vue 3 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
+| Nuxt 3/4 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
+| Angular 17+ | `angularRemote(Component, { providers })` | `<vitral-remote>` + `provideVitral()` | `vitral/angular` |
+| Svelte 5 | `svelteRemote(App)` | `use:remote` | `vitral/svelte` |
+| Solid | `solidRemote(App)` | `<Remote>` | `vitral/solid` |
+| Preact | `preactRemote(App)` | `<Remote>` | `vitral/preact` |
+| Lit e Web Components | `elementRemote('meu-widget')` | `<vitral-remote>` | `vitral/element` |
+| JS e TypeScript puro | `component({ render })` | `<vitral-remote>` | `vitral` |
+
+No Next e no Nuxt o componente renderiza o `fallback` no servidor e monta o remote no cliente.
 
-### Consumir no host (Vue / Nuxt)
+### Host em Vue
 
 ```vue
 <script setup>
@@ -164,162 +102,257 @@ import { VitralRemote } from 'vitral/vue'
 </script>
 
 <template>
-  <VitralRemote name="carrinho" :props="{ userId: 42 }" isolate="shadow">
+  <VitralRemote name="carrinho" :props="{ userId: 42 }">
     <template #fallback>Carregando…</template>
-    <template #error="{ error, retry }"><button @click="retry">Tentar de novo</button></template>
+    <template #error="{ retry }"><button @click="retry">Tentar de novo</button></template>
   </VitralRemote>
 </template>
 ```
 
-No Nuxt, chame `configure()` num plugin `.client.ts`. O componente renderiza o
-fallback no SSR e monta o remote no cliente.
+### Host em qualquer outro lugar
 
-### Consumir no host (JS/TS puro, Angular, Svelte, qualquer coisa)
-
-O Web Component `<vitral-remote>` funciona em qualquer lugar que renderize HTML:
+`<vitral-remote>` funciona em HTML puro, Angular, Svelte, Astro ou HTML gerado no servidor:
 
 ```html
 <script type="module">
   import { configure } from 'vitral'
   import { defineVitralElement } from 'vitral/element'
-  configure({ remotes: '/remotes.json' })
+
+  configure({ remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' } })
   defineVitralElement()
 </script>
 
-<vitral-remote name="carrinho" props='{"userId": 42}' isolate="shadow">
+<vitral-remote name="carrinho" props='{"userId": 42}'>
   <p slot="fallback">Carregando…</p>
   <p slot="error">Indisponível</p>
 </vitral-remote>
 ```
 
-`el.props = {...}` atualiza sem remontar, `el.retry()` remonta, e os eventos
-`vitral-ready` / `vitral-error` avisam o estado.
-
-**Angular:**
+### Remote sem framework
 
 ```ts
-bootstrapApplication(App, { providers: [provideVitral({ remotes: '/remotes.json' })] })
+import { component, html } from 'vitral'
 
-@Component({
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  template: `<vitral-remote name="carrinho" [props]="{ userId: id() }" (vitral-error)="falhou()"></vitral-remote>`,
+export default component<{ nome: string }>({
+  state: { cliques: 0 },
+  render: ({ nome }, state) => html`
+    <p>Olá, ${nome}</p>
+    <button onclick=${() => state.cliques++}>cliques: ${state.cliques}</button>
+  `,
 })
 ```
 
-**Svelte:** `<div use:remote={{ name: 'carrinho', props: { userId } }}></div>`
-(com `import { remote } from 'vitral/svelte'`).
+O que entra em `${}` é escapado. Mudar `state` ou as props atualiza a tela.
+
+## Desenvolvimento
 
-**Solid / Preact:** `<Remote name="carrinho" props={{ userId }} fallback={…} error={(e, retry) => …} />`.
+- **HMR:** com o remote em `vite dev`, aponte o host para `http://localhost:5174/vitral.json`. Editar o remote atualiza o host sem recarregar a página.
+- **Overrides:** `http://localhost:3000/?vitral=carrinho@http://localhost:5174` troca a URL de um remote sem mexer no host. Só vale em `localhost` ou com `configure({ devOverrides: true })`. Para guardar no navegador, use `devtools()` de `vitral/devtools`.
+- **Tipos das props:** o build publica `vitral.d.ts`. No host, `npx vitral types` gera `vitral-env.d.ts`, e uma prop errada passa a não compilar.
 
-### Comunicação
+## Comunicação entre remotes
 
 ```js
 import { events } from 'vitral'
-events.emit('carrinho:adicionar', produto)
-const off = events.on('carrinho:adicionar', (p) => …)
-events.last('usuario')          // último valor emitido
+
+events.emit('carrinho:total', 120)
+const parar = events.on('carrinho:total', (total) => console.log(total))
+events.last('carrinho:total') // 120
 ```
 
-Dentro de remotes: `useVitral()` (contexto), `useEvent(tipo, fn)` e
-`useEventValue(tipo)` existem em `vitral/react` e `vitral/vue`. O barramento é o
-mesmo para todos, mesmo que cada remote tenha sua cópia da lib, e o que o
-remote assina por `ctx.events` é cancelado sozinho no unmount.
+Todos os remotes usam o mesmo barramento. O que um remote assina é cancelado quando ele desmonta.
 
-Para navegar de dentro de um remote, use `navigate('/pedidos/42')` (ou
-`ctx.navigate`). Ele atualiza o histórico e avisa todos os roteadores.
+Para estado comum (usuário, tema, carrinho), use o contexto compartilhado:
 
-### Erros
+```js
+import { provide, shared } from 'vitral'
 
-Todo erro é um `RemoteError` com `code` e o nome do remote. Falhas de
-download e erros de render dentro do remote (React, Vue) aparecem no `error`
-do componente de host (ou no slot `error` do `<vitral-remote>`), com `retry`
-para remontar só aquele remote.
+provide('usuario', { id: 42 })                    // host: cria e é o dono
+provide('tema', 'claro', { writable: false })     // só o dono altera
+shared('tema').subscribe((tema) => console.log(tema))
+const nome = useShared('usuario', (u) => u?.nome) // React, Preact, Vue e Solid
+```
 
-### Configuração
+Angular usa `injectShared`, Svelte usa `$tema` e Lit usa `SharedController`. Detalhes em [Contexto compartilhado](https://joaogabriel15.github.io/vitral/aprender/contexto).
+
+Para mudar de página de dentro de um remote, use `navigate('/pedidos/42')`. Todos os roteadores da página recebem a mudança.
+
+## CSS e Tailwind
+
+Use Tailwind ou qualquer CSS no remote. O plugin prefixa o CSS para valer só dentro do remote, então o CSS de um remote não muda o host nem os outros remotes.
+
+Para isolar por completo, use Shadow DOM:
+
+```jsx
+<Remote name="carrinho" isolate="shadow" />
+```
+
+Com Shadow DOM, as regras `@property` e `@font-face` sobem para o documento, então sombras, rings, gradientes e fontes do Tailwind v4 funcionam.
+
+O remote também pode usar o tema do host:
+
+```js
+vitral({ theme: 'host' })                                  // var(--x) usa o valor do host, se existir
+configure({ styles: { inherit: ['/assets/base.css'] } })   // CSS base do host dentro do Shadow DOM
+```
+
+Tema com Tailwind v4, dark mode, CSS legado e Tailwind v3 no host: [Estilos](https://joaogabriel15.github.io/vitral/aprender/estilos).
+
+## Configuração
 
 ```js
 configure({
-  remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' }, // ou URL de um JSON
-  allowedOrigins: ['https://cdn.empresa.com'], // padrão: página + origens registradas
-  timeout: 15000,
-  retries: 1,
-  isolate: 'none',                              // ou 'shadow' para todos
+  remotes: '/remotes.json',                    // ou { nome: url }
+  allowedOrigins: ['https://cdn.empresa.com'], // padrão: a página e as origens registradas
+  timeout: 15000,                              // ms por download
+  retries: 1,                                  // novas tentativas em erro de rede
+  isolate: 'none',                             // ou 'shadow'
 })
 ```
 
-Entradas podem ser objetos: `{ url, integrity, css, isolate }`, ou
-`{ module: () => import('./carrinho') }` para um remote local (monorepo) sem
-rede. A `integrity`
-declarada pelo host vence a do manifesto (fixe o hash no host quando o remote
-for de terceiros).
+Cada remote também aceita um objeto:
 
-## Segurança
+```js
+configure({
+  remotes: {
+    carrinho: { url: 'https://cdn.empresa.com/carrinho/vitral.json', integrity: 'sha384-…' },
+    menu: { module: () => import('./menu') }, // remote local, sem rede
+  },
+})
+```
+
+## Erros
+
+Todo erro é um `RemoteError` com `code`, o nome do remote e `docs`, o link da [página do erro](https://github.com/joaogabriel15/vitral/tree/main/docs/erros) com causas e correção. Um remote que falha mostra o próprio erro e não derruba a página. `retry` monta só aquele remote de novo.
+
+| `code` | Quando |
+|---|---|
+| `NOT_REGISTERED` | Nome não registrado em `configure` |
+| `ORIGIN_BLOCKED` | URL fora de `allowedOrigins` |
+| `TIMEOUT` | Não respondeu dentro de `timeout` |
+| `INTEGRITY` | O hash do JS não confere |
+| `INVALID_MODULE` | O arquivo não exporta `mount()` |
+| `LOAD_FAILED` | Erro de rede ou HTTP |
+| `MOUNT_FAILED` | O remote lançou erro ao montar |
+| `RENDER_FAILED` | O remote quebrou depois de montado |
 
-- **Allowlist de origens**: nenhum código é importado de origem não permitida,
-  nem mesmo se um manifesto apontar para fora.
-- **SRI**: quando há `integrity`, a lib baixa o JS, confere o hash e executa
-  exatamente os bytes verificados (via `blob:`). Com CSP, inclua `blob:` em
-  `script-src`.
-- **Sem `eval`**, sem iframes, sem globais além de um `Symbol.for('vitral.state.v1')`.
-- Shadow DOM isola CSS, não JS: um remote ainda roda com os privilégios da
-  página. Para código não confiável de verdade, use iframe.
+## Performance
 
-## Dependências compartilhadas (opcional)
+Remote com `import()` também gera `dist/split/`: o navegador baixa só o que o remote usa ao abrir, e o resto chega no `import()`, conferido pelo mesmo hash. Hosts antigos continuam usando o arquivo único.
 
-Para não baixar React/Vue duas vezes, marque-os como `shared` no remote e
-declare um import map no host:
+No CDN, sirva `vitral.json` com `Cache-Control: no-cache` e o resto (nome com hash) com `public, max-age=31536000, immutable`.
+
+
+Assim que o manifesto chega, o JS e o CSS do remote baixam juntos. A montagem
+espera os dois, para o remote não aparecer sem estilo. `configure()` abre a
+conexão com a origem de cada remote (`<link rel="preconnect">`).
 
 ```js
-vitral({ entry: 'src/remote.jsx', shared: ['react', 'react-dom', 'react-dom/client'] })
+import { preload } from 'vitral'
+// Baixa JS e CSS sem montar, por exemplo no hover de um link
+link.addEventListener('pointerenter', () => preload('checkout'), { once: true })
 ```
 
+Nos componentes de host e no `<vitral-remote>`:
+
 ```html
-<script type="importmap">
-{ "imports": { "react": "https://esm.sh/react@19.2.0", "react-dom/client": "https://esm.sh/react-dom@19.2.0/client" } }
-</script>
+<!-- monta perto de aparecer na tela; reserve o espaço para a página não pular -->
+<vitral-remote name="comentarios" loading="lazy" style="display:block;min-height:400px"></vitral-remote>
+<!-- monta com o navegador ocioso, mas já baixa no hover -->
+<vitral-remote name="checkout" loading="idle" prefetch="hover"></vitral-remote>
+<!-- remote que aparece logo ao abrir a página -->
+<vitral-remote name="cabecalho" priority="high"></vitral-remote>
+```
+
+```jsx
+<Remote name="checkout" loading="lazy" prefetch="visible" keepAlive />
 ```
 
-## Testes
+| Opção | Valores | O que faz |
+| --- | --- | --- |
+| `loading` | `lazy`, `idle` | Monta a 200px de aparecer na tela, ou com o navegador ocioso |
+| `prefetch` | `hover`, `visible`, `idle` | Chama `preload()` antes de montar |
+| `priority` | `high` | `fetchpriority` alto no manifesto, no JS e no CSS |
+| `keepAlive` (`keep-alive`) | `true` ou o máximo | Ao sair da página, o remote vai para um contêiner oculto (LRU, padrão 5); na volta só recebe as props novas |
+
+Com keep-alive, o remote pode pausar timers e assinaturas:
+
+```js
+mount(el, props, ctx) {
+  ctx.onDeactivate?.(() => clearInterval(timer))
+  ctx.onActivate?.(() => (timer = setInterval(tick, 1000)))
+}
+```
+
+### Métricas
+
+Cada etapa do carregamento vira um `performance.measure` com o nome
+`vitral:<remote>:<etapa>`. As etapas são `manifest`, `js`, `css` e `mount`.
+Elas aparecem na aba Performance do DevTools. Para mandar ao seu RUM:
+
+```js
+configure({
+  onMetric: ({ name, stage, duration }) => rum.send(`vitral.${stage}`, duration, { remote: name }),
+})
+```
+
+O evento `vitral-ready` (e o `ready` do componente Vue) traz os tempos em
+`detail.timings`, por exemplo `{ manifest: 12.3, js: 40.1, css: 8, mount: 2.4 }`.
+Um remote local (`module`) só mede `css` e `mount`. Erros dentro do
+`onMetric` são ignorados.
+
+## Dependências compartilhadas
+
+Para não baixar React ou Vue mais de uma vez, liste-os em `dedupe` no remote:
+
+```js
+vitral({ dedupe: ['react'] })
+```
+
+O remote usa a cópia que já está na página quando a versão serve (padrão: `^` da versão instalada no remote) e baixa a própria só quando não serve. Os componentes de host em React oferecem o React do host sem configuração.
+
+### Mais formas de usar
+
+Vários componentes por remote (`<Remote name="carrinho/MiniCarrinho" />`),
+módulos sem UI (`loadModule('carrinho/api')`), deploy novo sem recarregar a
+página (`watchUpdates()` e `refresh('carrinho')`) e app shell por rota
+(`routes()` e `<vitral-outlet>`, em `vitral/routes`). Veja
+[Exposes](https://joaogabriel15.github.io/vitral/aprender/exposes), [Atualização sem reload](https://joaogabriel15.github.io/vitral/aprender/atualizacoes) e [Rotas](https://joaogabriel15.github.io/vitral/aprender/rotas).
+
+## Segurança
+
+- Só importa JS de origens permitidas, mesmo que o `vitral.json` aponte para outra. O `src` de um componente de host entra na allowlist; o atributo `src` do `<vitral-remote>` não entra quando há `allowedOrigins`.
+- Com `integrity`, nada roda sem o hash conferir. A lib usa o primeiro caminho que o navegador garante: import map com `integrity` (Chrome 133+, Safari 18.4+), `<link rel="modulepreload" integrity>` (Firefox 115+) ou, nos outros, baixa, confere e executa exatamente os bytes conferidos via `blob:`. Aceita `sha256`, `sha384` e `sha512`, e vários hashes separados por espaço (vale o mais forte). O CSS do manifesto também é conferido.
+- Com CSP, a lib copia o `nonce` de um `<script nonce>` da página para o import map. Sem nonce, cai para o `modulepreload`.
+- O hash só protege contra CDN comprometido se vier de outro lugar: fixe `integrity` no host ou embuta o manifesto (`{ url, manifest }`).
+- Sem `eval` e sem iframes.
+- Shadow DOM isola o CSS, não o JS. Para código de terceiros em que você não confia, use iframe.
+
+## Testes do host
 
 ```ts
-// Teste do host sem subir nenhum remote
 import { mockRemote, failingRemote } from 'vitral/testing'
 
 const carrinho = mockRemote('carrinho', (el, props) => (el.textContent = `itens: ${props.itens}`))
-// …renderize o host…
+// renderize o host
 expect(carrinho.lastProps).toEqual({ itens: 2 })
-failingRemote('recomendacoes') // para testar a tela de erro
+
+failingRemote('recomendacoes') // testa a tela de erro
 ```
 
-No repositório (veja [CONTRIBUTING.md](CONTRIBUTING.md)):
+## Comparado com Module Federation e single-spa
 
-```bash
-pnpm install
-pnpm check       # build, tipos, publint/attw, tamanho e testes unitários
-pnpm test:e2e    # builda tudo e roda o Playwright: 9 hosts × 8 remotes + demo
-pnpm examples    # sobe os exemplos (hosts em :4201-:4207, remotes em :4100)
-```
+| | Module Federation / single-spa | vitral |
+|---|---|---|
+| Build do host | Config combinada com cada remote | Nenhuma. Só `configure()` |
+| Versões de React/Vue | `shared` e singletons, conflitos de versão | Cada remote leva a sua. Compartilhar é opcional |
+| Remote fora do ar | Pode derrubar a página | Só aquele remote mostra erro |
+| CSS | Vaza entre apps | Escopo automático ou Shadow DOM |
+| Deploy novo | `ChunkLoadError` com cache velho | Arquivos com hash; só o `vitral.json` revalida |
+| Conceitos | Containers, exposes, lifecycles, root config | `mount(el, props, ctx)` → `{ update, unmount }` |
+
+## Links
 
-O CI roda tudo isso em Node 20, 22 e 24 a cada push e PR. Versões novas saem
-pelo Changesets: `pnpm changeset`, merge do PR "Versionar pacote" e o GitHub
-Actions publica no npm com proveniência.
-
-## Exemplos e demo
-
-- `examples/remotes/*`: o mesmo cartão em React, Vue, Svelte, Solid, Preact,
-  Angular, Lit e TypeScript puro.
-- `examples/hosts/*`: hosts em JS puro (:4201), React (:4202), Vue (:4203),
-  Svelte (:4204), Solid (:4205), Preact (:4206), Angular (:4207), Next (:4208,
-  `pnpm --dir examples/hosts/next start`) e Nuxt (:4209,
-  `pnpm --dir examples/hosts/nuxt start`), cada um carregando os 8 remotes.
-- `demo/`: catálogo Vue + carrinho React com Tailwind (`pnpm demo`, em
-  http://localhost:5173 e :5174).
-
-## Estado
-
-Protótipo 0.1. Testado (32 testes unitários e 43 e2e): carregamento via
-manifesto com SRI, Shadow DOM, props reativas sem remontar, props que mudam
-durante o download, desmontar/remontar, StrictMode do React, erros de download
-e de render, eventos entre frameworks, Tailwind v4 com e sem Shadow DOM, escopo
-de CSS e SSR em Next e Nuxt. O que ainda falta está em
-[docs/PROBLEMAS.md](docs/PROBLEMAS.md#ainda-não-resolvidos-próximos-passos-sugeridos).
+- [Exemplos](https://github.com/joaogabriel15/vitral/tree/main/examples): o mesmo remote em 8 frameworks e 9 hosts.
+- [Como contribuir](https://github.com/joaogabriel15/vitral/blob/main/CONTRIBUTING.md)
+- Licença [MIT](https://github.com/joaogabriel15/vitral/blob/main/LICENSE)

package/dist/angular.d.ts

@@ -1,6 +1,7 @@
-import { InjectionToken, Type, ApplicationConfig, Provider, EnvironmentProviders } from '@angular/core';
-import { RemoteContext, Props, RemoteModule, VitralConfig } from './index.js';
-export { events, navigate } from './index.js';
+import { InjectionToken, Type, ApplicationConfig, Signal, Provider, EnvironmentProviders } from '@angular/core';
+import { R as RemoteContext, P as Props, a as RemoteModule, S as Shared, V as VitralConfig } from './types-BV-hUrms.js';
+export { e as events } from './events-DUdjhfps.js';
+export { n as navigate } from './navigate-BRG1WJUM.js';
 
 /**
  * Adaptador Angular (standalone, zoneless ou com zone.js).
@@ -18,10 +19,20 @@ declare const VITRAL_CONTEXT: InjectionToken<RemoteContext>;
 declare function angularRemote<P extends Props>(component: Type<unknown>, config?: Partial<ApplicationConfig>): RemoteModule<P>;
 /** Dentro de um remote Angular: `const vitral = injectVitral()`. */
 declare function injectVitral(): RemoteContext | null;
+/**
+ * Signal de uma chave compartilhada (`provide`/`shared`). Com seletor, só
+ * muda quando o resultado do seletor muda (`Object.is`). Chame num contexto de
+ * injeção (construtor, inicializador de campo); a assinatura acaba no destroy.
+ *
+ *   usuario = injectShared('usuario')
+ *   nome = injectShared('usuario', (u) => u?.nome)
+ */
+declare function injectShared<K extends keyof Shared, S = Shared[K] | undefined>(key: K, select?: (value: Shared[K] | undefined) => S): Signal<S>;
+declare function injectShared<T = unknown, S = T | undefined>(key: string, select?: (value: T | undefined) => S): Signal<S>;
 /**
  * Host Angular: configura o vitral e registra `<vitral-remote>`. Use junto com
  * `CUSTOM_ELEMENTS_SCHEMA` no componente que renderiza o remote.
  */
 declare function provideVitral(config?: VitralConfig): (Provider | EnvironmentProviders)[];
 
-export { VITRAL_CONTEXT, angularRemote, injectVitral, provideVitral };
+export { VITRAL_CONTEXT, angularRemote, injectShared, injectVitral, provideVitral };