vitral 0.3.0 → 0.5.0

package/dist/svelte.js

@@ -1,15 +1,15 @@
 import {
   hostSlot
-} from "./chunk-IHTUM6LT.js";
+} from "./chunk-4Z77XNBR.js";
 import {
   defineRemote,
   events,
   navigate
-} from "./chunk-I3VSKSAZ.js";
-import "./chunk-TD4S3IHA.js";
-import "./chunk-ZAC6QQI6.js";
-import "./chunk-GNHCZRQP.js";
-import "./chunk-AKNNHQ2H.js";
+} from "./chunk-KZBH5MPD.js";
+import "./chunk-5JNV45BB.js";
+import "./chunk-KU6HF2EW.js";
+import "./chunk-TW7KYJQ6.js";
+import "./chunk-463H6B56.js";
 import "./chunk-GNPFWISJ.js";
 
 // src/svelte.ts

package/dist/testing.d.ts

@@ -1,9 +1,177 @@
-import { P as Props, R as RemoteContext } from './types-Czvm-siZ.js';
+import { P as Props, R as RemoteContext, a as RemoteModule } from './types-DUtcF3HO.js';
 export { r as resetVitral } from './state-BDdCwc21.js';
 import './errors-kjBv6IH_.js';
 
+/** Endereço do JSON Schema do contrato. Vai no `$schema` do arquivo gravado. */
+declare const CONTRACT_SCHEMA = "https://joaogabriel15.github.io/vitral/schema/vitral-contract.json";
 /**
- * Utilidades de teste: monte o host sem subir nenhum remote de verdade.
+ * Contrato do consumidor: o que um host passou para um remote e o que ele
+ * espera de volta, gravado com `record()`. Arquivo `<remote>.contract.json`.
+ */
+interface Contract {
+    $schema?: string;
+    /** Nome com que o host monta o remote. */
+    remote: string;
+    /** Quem gravou (o host). */
+    host?: string;
+    /** `version` do manifesto do remote na gravação. */
+    version?: string;
+    /** Uma montagem por caso, sem repetições. */
+    cases: ContractCase[];
+}
+/** Quando o remote emitiu: no `mount`, num `update`, ao receber um evento do host, ou depois (clique, timer). */
+type EmitPhase = 'mount' | 'update' | 'input' | 'later';
+/**
+ * Uma montagem gravada. Valores que o JSON não guarda viram marcadores:
+ * `{ "$fn": true }` (função), `{ "$date": "…" }` e `{ "$unknown": "Classe" }`.
+ */
+interface ContractCase {
+    /** Props do mount. */
+    props: Props;
+    /** Props de cada `update`, em ordem. */
+    updates?: Props[];
+    /** Eventos que o host emitiu e o remote escutava, em ordem. */
+    inputs?: {
+        type: string;
+        payload?: unknown;
+    }[];
+    /** Valores que o remote leu com `ctx.events.last`. */
+    last?: Record<string, unknown>;
+    /** Chaves de `ctx.shared` que o remote leu, com o primeiro valor lido. */
+    shared?: Record<string, unknown>;
+    /** Eventos que o remote emitiu e o host escuta. */
+    emits?: {
+        type: string;
+        phase: EmitPhase;
+    }[];
+    /** Eventos que o remote assinou. */
+    listens?: string[];
+}
+interface HarnessOptions<P extends Props = Props> {
+    props: P;
+    /** Nome do remote em `ctx.name`. Padrão `'remote'`. */
+    name?: string;
+    /** Monta dentro de um shadow root (`ctx.shadowRoot` e `ctx.portalContainer` ficam nele). */
+    shadow?: boolean;
+    /** Valores iniciais de `ctx.shared`. */
+    shared?: Record<string, unknown>;
+    /** Valores iniciais de `ctx.events.last`. */
+    last?: Record<string, unknown>;
+    /** Campos que substituem os do `ctx` simulado. */
+    ctx?: Partial<RemoteContext>;
+    /** Onde montar. Padrão: um `<div>` novo no `document.body`. */
+    target?: HTMLElement;
+}
+interface Harness<P extends Props = Props> {
+    /** Elemento onde o remote montou. */
+    readonly el: HTMLElement;
+    /** O `ctx` que o remote recebeu. */
+    readonly ctx: RemoteContext;
+    /** Eventos que o remote emitiu por `ctx.events`, em ordem. */
+    readonly events: {
+        type: string;
+        payload: unknown;
+    }[];
+    /** Erros de `ctx.reportError` e de handlers de eventos. */
+    readonly errors: unknown[];
+    /** Chamadas de `ctx.navigate`. */
+    readonly navigations: {
+        url: string;
+        options?: {
+            replace?: boolean;
+        };
+    }[];
+    /** Tipos de evento que o remote escuta agora. */
+    listens(): string[];
+    /** Emite um evento como se fosse o host. */
+    emit(type: string, payload?: unknown): void;
+    update(props: P): void;
+    /** Dispara `ctx.onActivate` (keep-alive). */
+    activate(): void;
+    /** Dispara `ctx.onDeactivate` (keep-alive). */
+    deactivate(): void;
+    unmount(): void;
+}
+/**
+ * Monta `mod` com um `ctx` simulado: barramento de eventos próprio, `shared`
+ * em memória, `portalContainer`, `customElements`, `navigate` e
+ * `reportError` gravados.
+ *
+ *   const h = await harness(remote, { props: { itens: 2 } })
+ *   expect(h.el.textContent).toContain('2 itens')
+ *   h.emit('tema', 'escuro')
+ *   expect(h.events).toContainEqual({ type: 'carrinho:aberto', payload: undefined })
+ */
+declare function harness<P extends Props = Props>(mod: RemoteModule<P> | {
+    default: RemoteModule<P>;
+}, options: HarnessOptions<P>): Promise<Harness<P>>;
+interface VerifyOptions {
+    /**
+     * Código do remote (o texto dos arquivos JS). Um evento que o host escuta e
+     * que o remote só emite depois (clique, timer) é procurado aqui pelo nome.
+     */
+    sources?: string[];
+    /** Quanto esperar depois de cada etapa, em ms. Padrão 0. */
+    wait?: number;
+}
+interface VerifyResult {
+    /** Casos reproduzidos. */
+    cases: number;
+    /** O que quebra o host. Vazio quando o contrato passa. */
+    failures: string[];
+    /** O que mudou sem quebrar. */
+    warnings: string[];
+}
+/**
+ * Reproduz cada caso de `contract` em `mod` (props, updates, eventos do host,
+ * `shared` e `last`) e confere: mount, update e unmount sem erro, nenhum
+ * `reportError`, e cada evento que o host escuta ainda emitido (ou, se só sai
+ * depois de um clique, ainda presente no código).
+ */
+declare function verify(contract: Contract, mod: RemoteModule<any> | {
+    default: RemoteModule<any>;
+}, options?: VerifyOptions): Promise<VerifyResult>;
+
+/**
+ * Gravação do contrato do consumidor, no host: para cada remote montado,
+ * guarda as props, os updates, os eventos que o host emitiu para ele, o que
+ * ele leu de `ctx.shared` e `ctx.events.last`, e os eventos dele que o host
+ * escuta. O remote reproduz o arquivo no CI com `vitral test --contract`.
+ *
+ * Funciona trocando métodos do protocolo global (`load` e o barramento), sem
+ * nada no núcleo: o host só paga por isto quando importa `vitral/testing`.
+ */
+
+interface RecordOptions {
+    /** Nome do host, gravado no contrato. */
+    host?: string;
+    /** Máximo de casos diferentes por remote. Padrão 50. */
+    max?: number;
+}
+interface Recorder {
+    /** Contratos gravados até agora, por nome do remote. */
+    contracts(): Record<string, Contract>;
+    /** Grava `<remote>.contract.json` em `dir` (só no Node). Devolve os caminhos. */
+    save(dir?: string): Promise<string[]>;
+    /** Para de gravar e devolve o protocolo como estava. */
+    stop(): void;
+}
+/**
+ * Começa a gravar. Chame antes de o host montar os remotes e de assinar
+ * eventos (o recorder só vê as assinaturas feitas depois dele).
+ *
+ *   const rec = record({ host: 'loja' })
+ *   // ...testes do host montam os remotes...
+ *   await rec.save('contracts')
+ *
+ * Remotes em `isolate: 'iframe'` e partes (`carrinho/Mini`) não são gravados.
+ */
+declare function record(options?: RecordOptions): Recorder;
+
+/**
+ * Utilidades de teste: monte o host sem subir nenhum remote de verdade, monte
+ * um remote com `ctx` simulado (`harness`) e grave o contrato do consumidor
+ * (`record`) que o remote reproduz no CI com `vitral test --contract`.
  *
  *   import { mockRemote } from 'vitral/testing'
  *   const carrinho = mockRemote('carrinho', (el, props) => (el.textContent = `itens: ${props.itens}`))
@@ -26,4 +194,4 @@ declare function mockRemote<P extends Props = Props>(name: string, render?: (el:
 /** Remote que sempre falha ao montar, para testar telas de erro. */
 declare function failingRemote(name: string, message?: string): void;
 
-export { type MockRemote, failingRemote, mockRemote };
+export { CONTRACT_SCHEMA, type Contract, type ContractCase, type EmitPhase, type Harness, type HarnessOptions, type MockRemote, type RecordOptions, type Recorder, type VerifyOptions, type VerifyResult, failingRemote, harness, mockRemote, record, verify };

package/dist/testing.js

@@ -1,14 +1,197 @@
-import "./chunk-I3VSKSAZ.js";
+import {
+  CONTRACT_SCHEMA,
+  encode,
+  harness,
+  verify
+} from "./chunk-DAESKNQ6.js";
+import "./chunk-KZBH5MPD.js";
 import {
   register
-} from "./chunk-TD4S3IHA.js";
-import "./chunk-ZAC6QQI6.js";
-import "./chunk-GNHCZRQP.js";
-import "./chunk-AKNNHQ2H.js";
+} from "./chunk-5JNV45BB.js";
+import "./chunk-KU6HF2EW.js";
+import "./chunk-TW7KYJQ6.js";
+import "./chunk-463H6B56.js";
 import {
+  protocol,
   resetProtocol
 } from "./chunk-GNPFWISJ.js";
 
+// src/recorder.ts
+function record(options = {}) {
+  const p = protocol();
+  const bus = p.events;
+  const { load, emit, on } = { load: p.load, emit: bus.emit, on: bus.on };
+  const cases = /* @__PURE__ */ new Map();
+  const versions = /* @__PURE__ */ new Map();
+  const hostListens = /* @__PURE__ */ new Set();
+  const wrapped = /* @__PURE__ */ new WeakMap();
+  let viaRemote = 0;
+  let hostEmitting = [];
+  bus.on = (type, handler) => {
+    if (viaRemote) return on.call(bus, type, handler);
+    hostListens.add(type);
+    return on.call(bus, type, (payload) => {
+      const before = viaRemote;
+      viaRemote = 0;
+      try {
+        handler(payload);
+      } finally {
+        viaRemote = before;
+      }
+    });
+  };
+  bus.emit = (type, payload) => {
+    hostEmitting.push(!viaRemote);
+    try {
+      return emit.call(bus, type, payload);
+    } finally {
+      hostEmitting.pop();
+    }
+  };
+  const scope = (live, events) => ({
+    emit(type, payload) {
+      live.emits.push({ type, phase: live.phase });
+      viaRemote++;
+      try {
+        events.emit(type, payload);
+      } finally {
+        viaRemote--;
+      }
+    },
+    on(type, handler) {
+      live.listens.add(type);
+      viaRemote++;
+      try {
+        return events.on(type, (payload) => {
+          if (!hostEmitting.at(-1)) return handler(payload);
+          live.inputs.push({ type, payload: encode(payload) });
+          const before = live.phase;
+          live.phase = "input";
+          try {
+            handler(payload);
+          } finally {
+            live.phase = before;
+          }
+        });
+      } finally {
+        viaRemote--;
+      }
+    },
+    last(type) {
+      const v = events.last(type);
+      if (v !== void 0 && !(type in live.last)) live.last[type] = encode(v);
+      return v;
+    }
+  });
+  const sharedOf = (live, api) => {
+    const seen = (key, v) => {
+      if (v !== void 0 && !(key in live.shared)) live.shared[key] = encode(v);
+      return v;
+    };
+    const wrap = (key) => {
+      const h = api(key);
+      return { ...h, get: () => seen(key, h.get()), subscribe: (fn) => h.subscribe((v) => fn(seen(key, v))) };
+    };
+    return Object.assign(wrap, { provide: api.provide, batch: api.batch });
+  };
+  const wrapModule = (mod) => {
+    let w = wrapped.get(mod);
+    if (w) return w;
+    w = Object.create(mod, {
+      mount: {
+        value: async (el, props, ctx) => {
+          const live = { props: encode(props), updates: [], inputs: [], last: {}, shared: {}, emits: [], listens: /* @__PURE__ */ new Set(), phase: "mount" };
+          const list = cases.get(ctx.name) ?? [];
+          cases.set(ctx.name, list);
+          list.push(live);
+          const own = { ...ctx, events: scope(live, ctx.events) };
+          if (ctx.shared) own.shared = sharedOf(live, ctx.shared);
+          let mounted;
+          try {
+            mounted = await mod.mount(el, props, own);
+          } finally {
+            live.phase = "later";
+          }
+          return {
+            update(next) {
+              live.updates.push(encode(next));
+              live.phase = "update";
+              try {
+                mounted.update?.(next);
+              } finally {
+                live.phase = "later";
+              }
+            },
+            unmount: () => mounted.unmount()
+          };
+        }
+      }
+    });
+    wrapped.set(mod, w);
+    return w;
+  };
+  p.load = (name, fetcher) => load.call(p, name, fetcher).then((r) => {
+    if (r.version) versions.set(r.name ?? name, r.version);
+    return typeof r.module?.mount === "function" ? { ...r, module: wrapModule(r.module) } : r;
+  });
+  const contracts = () => {
+    const out = {};
+    for (const [remote, lives] of cases) {
+      const unique = /* @__PURE__ */ new Map();
+      for (const live of lives) {
+        const c = { props: live.props };
+        if (live.updates.length) c.updates = live.updates;
+        if (live.inputs.length) c.inputs = live.inputs;
+        if (Object.keys(live.last).length) c.last = live.last;
+        if (Object.keys(live.shared).length) c.shared = live.shared;
+        const emits = /* @__PURE__ */ new Map();
+        for (const e of live.emits) if (hostListens.has(e.type) && (!emits.has(e.type) || emits.get(e.type) === "later")) emits.set(e.type, e.phase);
+        if (emits.size) c.emits = [...emits].map(([type, phase]) => ({ type, phase }));
+        if (live.listens.size) c.listens = [...live.listens].sort();
+        const key = JSON.stringify(c);
+        if (!unique.has(key) && unique.size < (options.max ?? 50)) unique.set(key, c);
+      }
+      out[remote] = {
+        $schema: CONTRACT_SCHEMA,
+        remote,
+        ...options.host && { host: options.host },
+        ...versions.has(remote) && { version: versions.get(remote) },
+        cases: [...unique.values()]
+      };
+    }
+    return out;
+  };
+  return {
+    contracts,
+    async save(dir = ".") {
+      const fs = "node:fs/promises";
+      const path = "node:path";
+      const { mkdir, writeFile } = await import(
+        /* @vite-ignore */
+        fs
+      );
+      const { join } = await import(
+        /* @vite-ignore */
+        path
+      );
+      await mkdir(dir, { recursive: true });
+      const files = [];
+      for (const [name, c] of Object.entries(contracts())) {
+        const file = join(dir, `${name.replace(/[^\w.-]+/g, "_")}.contract.json`);
+        await writeFile(file, JSON.stringify(c, null, 2) + "\n");
+        files.push(file);
+      }
+      return files;
+    },
+    stop() {
+      p.load = load;
+      bus.emit = emit;
+      bus.on = on;
+      hostEmitting = [];
+    }
+  };
+}
+
 // src/testing.ts
 function mockRemote(name, render = (el) => {
   el.setAttribute("data-mock-remote", name);
@@ -47,7 +230,11 @@ function failingRemote(name, message = "falha simulada") {
   });
 }
 export {
+  CONTRACT_SCHEMA,
   failingRemote,
+  harness,
   mockRemote,
-  resetProtocol as resetVitral
+  record,
+  resetProtocol as resetVitral,
+  verify
 };

package/dist/{types-Czvm-siZ.d.ts → types-DUtcF3HO.d.ts}

@@ -99,6 +99,17 @@ interface RemoteContext {
      * Hosts antigos não mandam este campo.
      */
     portalContainer?: HTMLElement;
+    /**
+     * Registro de custom elements do remote. No Shadow DOM, onde o navegador
+     * tem Scoped Custom Element Registries (Chrome 146+, Safari 26+), é um
+     * registro só deste remote, usado pelo shadow root e pelo elemento `el`:
+     * dois remotes podem definir `<ds-button>` de versões diferentes. Sem
+     * suporte, e fora do Shadow DOM, é o `customElements` global. No Shadow
+     * DOM, `define` de uma tag já definida não lança: fica a definição que já
+     * existe, com um aviso em dev quando ela veio de outro remote. Hosts
+     * antigos não mandam este campo: use `ctx.customElements ?? customElements`.
+     */
+    customElements?: CustomElementRegistry;
     /** Avisa o host de um erro em tempo de execução (os adaptadores já chamam). */
     reportError(error: unknown): void;
     /** Navega a página inteira (host e todos os roteadores) para `url`. */
@@ -124,6 +135,21 @@ interface RemoteContext {
      * (`provide`, `shared` ou um hook); senão, importe `shared` de 'vitral'.
      */
     shared?: SharedApi;
+    /**
+     * Só quando o remote roda como MCP App (`vitral({ target: 'mcp-app' })`):
+     * fala JSON-RPC direto com o host MCP, para o que `events` não cobre
+     * (`tools/call`, `resources/read`, `ui/request-display-mode`…).
+     */
+    mcp?: McpAppBridge;
+}
+/** `ctx.mcp` de um remote empacotado como MCP App. */
+interface McpAppBridge {
+    /** Pedido ao host; resolve com `result` ou rejeita com `error.message`. */
+    request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /** Notificação ao host (sem resposta). */
+    notify(method: string, params?: Record<string, unknown>): void;
+    /** O `hostContext` atual (tema, idioma, tamanho do container…), já com as mudanças. */
+    hostContext(): Record<string, unknown> | undefined;
 }
 interface MountedRemote<P extends Props = Props> {
     update?(props: P): void;
@@ -131,6 +157,15 @@ interface MountedRemote<P extends Props = Props> {
 }
 interface RemoteModule<P extends Props = Props> {
     mount(el: HTMLElement, props: P, ctx: RemoteContext): MountedRemote<P> | Promise<MountedRemote<P>>;
+    /**
+     * Opcional. Quando o gateway de `vitral/edge` já renderizou o remote no
+     * servidor, o `<vitral-remote>` chama `hydrate` com `el` cheio do HTML de
+     * `render` (no Shadow DOM declarativo, se for o caso), em vez de limpar e
+     * chamar `mount`. Deve assumir o DOM que existe, sem recriar.
+     */
+    hydrate?(el: HTMLElement, props: P, ctx: RemoteContext): MountedRemote<P> | Promise<MountedRemote<P>>;
+    /** Opcional, só no servidor: o HTML do remote para estas props (SSR pelo gateway). */
+    render?(props: P): string | Promise<string>;
 }
 interface RemoteEntry {
     /** URL do módulo JS do remote, ou do `vitral.json` gerado pelo plugin. */
@@ -149,7 +184,7 @@ interface RemoteEntry {
     /** Isolamento padrão para este remote. */
     isolate?: Isolation;
     /**
-     * O `vitral.json` já baixado (ex.: por `vitral registry`), para não buscá-lo
+     * O `vitral.json` já baixado (ex.: no build do host), para não buscá-lo
      * na hora. Os caminhos dele são relativos a `url`, e os hashes ficam fixos
      * no host.
      */
@@ -159,12 +194,68 @@ interface RemoteEntry {
      * Vence a de `configure`. Veja `VitralConfig.contract`.
      */
     contract?: string;
+    /**
+     * Com `url` apontando para um canal (`canal.json`): escolhe a versão deste
+     * usuário. Devolve a versão (`'1.5.0'`) ou a URL de um `vitral.json`;
+     * `undefined` usa a regra padrão (`canary.percent`). Veja `Channel`.
+     */
+    resolve?: (channel: Channel, ctx: ChannelContext) => string | undefined | Promise<string | undefined>;
+    /**
+     * Volta para a estável, até o fim da sessão, quando a versão que não é a
+     * estável gera `errors` erros numa janela de `mounts` montagens. Padrão
+     * `{ errors: 3, mounts: 20 }`. `false` desliga.
+     */
+    rollback?: {
+        errors?: number;
+        mounts?: number;
+    } | false;
+}
+/**
+ * Arquivo-ponteiro de um remote (o canal, ex.: `canal.json`): diz que versão
+ * cada usuário recebe. Cada versão fica na própria pasta, ao lado do canal
+ * (`'1.4.0'` → `1.4.0/vitral.json`), ou é a URL de um `vitral.json`.
+ *
+ *   { "stable": "1.4.0", "canary": { "version": "1.5.0", "percent": 10 } }
+ */
+interface Channel {
+    /** Versão de todos os usuários fora da canary. */
+    stable: string;
+    /** Versão nova para `percent`% dos usuários (0 a 100). */
+    canary?: {
+        version: string;
+        percent: number;
+    };
+    /** Campos próprios, para o `resolve` do host ler (ex.: `"beta": "1.6.0"`). */
+    [key: string]: unknown;
+}
+/** O que o `resolve` de um canal recebe além do canal. */
+interface ChannelContext {
+    /** Nome do remote. */
+    name: string;
+    /**
+     * Número de 0 a 99, sempre o mesmo para este navegador (ou para
+     * `canaryKey`) e este remote. A regra padrão dá a canary a quem tem
+     * `bucket < percent`.
+     */
+    bucket: number;
+}
+/** Aviso de rollback automático, para `configure({ onRollback })`. */
+interface RollbackInfo {
+    name: string;
+    /** Versão abandonada (como o canal ou o `resolve` a escreveram). */
+    from: string;
+    /** Versão estável, usada daqui até o fim da sessão. */
+    to: string;
+    errors: number;
+    mounts: number;
 }
 /**
  * `none`: CSS com escopo. `shadow`: Shadow DOM. `iframe`: iframe com
  * `sandbox`, para código de terceiros (precisa de `enableIframe()`).
+ * `reframe`: JS num iframe oculto de mesma origem (globals próprios) e DOM
+ * no Shadow DOM da página. Não é fronteira de segurança.
  */
-type Isolation = 'shadow' | 'none' | 'iframe';
+type Isolation = 'shadow' | 'none' | 'iframe' | 'reframe';
 /** Estilos do host dentro do Shadow DOM. Sem efeito no modo escopo. */
 interface StyleOptions {
     /**
@@ -178,6 +269,15 @@ interface StyleOptions {
      */
     mirrorTheme?: boolean;
 }
+/** Opções de `configure({ devOverrides })`. */
+interface DevOverrides {
+    /**
+     * Modelo da URL de um apelido: `?vitral=checkout@pr-123` com
+     * `'https://{name}-{ref}.preview.empresa.com'` vira
+     * `https://checkout-pr-123.preview.empresa.com/vitral.json`.
+     */
+    preview?: string;
+}
 interface VitralConfig {
     /** Mapa nome → URL (ou entrada completa), ou a URL de um JSON com esse mapa. */
     remotes?: Record<string, string | RemoteEntry> | string;
@@ -196,9 +296,10 @@ interface VitralConfig {
      * Liga os overrides de desenvolvimento (`?vitral=nome@url` e
      * `localStorage['vitral:overrides']`) fora de localhost. Em localhost já
      * valem. Nunca ligue em produção: um link com `?vitral=` executaria código
-     * de qualquer origem.
+     * de qualquer origem. O objeto também liga e aceita `preview`, o modelo de
+     * URL dos apelidos (`?vitral=checkout@pr-123`).
      */
-    devOverrides?: boolean;
+    devOverrides?: boolean | DevOverrides;
     /** Estilos do host no Shadow DOM: `{ inherit: ['/assets/base.css'] }`. */
     styles?: StyleOptions;
     /** Recebe o tempo de cada etapa do carregamento (para RUM). */
@@ -232,6 +333,16 @@ interface VitralConfig {
      * conferido. `'*'` confere só as dependências.
      */
     contract?: string;
+    /**
+     * Chave estável do usuário (ex.: o id dele) para sortear quem recebe a
+     * canary de um canal. Padrão: um id aleatório guardado no `localStorage`.
+     */
+    canaryKey?: string;
+    /**
+     * Chamado quando a versão canary de um canal passa do limite de erros e o
+     * host volta para a estável (veja `RemoteEntry.rollback`).
+     */
+    onRollback?: (info: RollbackInfo) => void;
 }
 /** Módulos de um grupo de `dedupe`, por especificador (`'react-dom/client'`). */
 type SharedModules = Record<string, unknown>;
@@ -294,6 +405,14 @@ interface RemoteManifest {
      * antigos), o runtime faz esse trabalho em cada página.
      */
     shadow?: ShadowCss;
+    /**
+     * SBOM CycloneDX do remote (opção `sbom` do plugin): o arquivo, relativo
+     * ao manifesto, e o hash dele. O runtime não usa; é para auditoria.
+     */
+    sbom?: {
+        file: string;
+        integrity: string;
+    };
 }
 /** Contrato do remote no `vitral.json`. */
 interface RemoteContract {
@@ -324,4 +443,4 @@ interface EventBus {
     last<T = unknown>(type: string): T | undefined;
 }
 
-export { type CheckedProps as C, type EventBus as E, type Handler as H, type Isolation as I, type MountedRemote as M, type Props as P, type RemoteContext as R, type Shared as S, type VitralConfig as V, type RemoteModule as a, type StyleOptions as b, type RemoteEntry as c, type SharedValue as d, type PropsOf as e, type ProvideOptions as f, type ProvidedValue as g, type RemoteContract as h, type RemoteManifest as i, type RemoteMetric as j, type Remotes as k, type SharedApi as l, type SharedModules as m, type SharedType as n, batch as o, provide as p, shared as s };
+export { type CheckedProps as C, type DevOverrides as D, type EventBus as E, type Handler as H, type Isolation as I, type MountedRemote as M, type Props as P, type RemoteContext as R, type Shared as S, type VitralConfig as V, type RemoteModule as a, type SharedModules as b, type RemoteEntry as c, type StyleOptions as d, type SharedValue as e, type Channel as f, type ChannelContext as g, type McpAppBridge as h, type PropsOf as i, type ProvideOptions as j, type ProvidedValue as k, type RemoteContract as l, type RemoteManifest as m, type RemoteMetric as n, type Remotes as o, type RollbackInfo as p, type SharedApi as q, type SharedType as r, batch as s, provide as t, shared as u };

package/dist/vitals.d.ts

@@ -0,0 +1,29 @@
+type VitalName = 'LCP' | 'CLS' | 'INP' | 'FCP' | 'TTFB';
+type VitalRating = 'good' | 'needs-improvement' | 'poor';
+interface VitalReport {
+    name: VitalName;
+    /** Remote dono do elemento. Ausente quando é do host ou da página. */
+    remote?: string;
+    /** Versão do remote (do manifesto) na hora da medição. */
+    version?: string;
+    /** Rota: pathname da navegação (soft ou não). */
+    route: string;
+    /** `navigationId` das entradas, só com Soft Navigations. */
+    navigationId?: string;
+    /** ms para LCP, INP, FCP e TTFB; sem unidade para CLS. */
+    value: number;
+    rating: VitalRating;
+}
+interface VitalsOptions {
+    onReport: (report: VitalReport) => void;
+}
+declare const rating: (name: VitalName, value: number) => VitalRating;
+/** Dono de `node`: o `data-vitral-root` mais próximo, atravessando shadow roots. `''` é o host. */
+declare function owner(node: Node | null | undefined): string;
+/**
+ * Observa as Web Vitals e chama `onReport` com cada uma, por remote e rota.
+ * Devolve `stop`, que relata o que falta e desliga os observers.
+ */
+declare function vitals({ onReport }: VitalsOptions): () => void;
+
+export { type VitalName, type VitalRating, type VitalReport, type VitalsOptions, owner, rating, vitals };