vitral 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Remote em JS/TS puro sem escrever mount/update/unmount na mão.
+ *
+ *   export default component<{ mensagem?: string }>({
+ *     state: { cliques: 0 },
+ *     render: ({ mensagem }, state, ctx) => html`
+ *       <p>${mensagem}</p>
+ *       <button onclick=${() => state.cliques++}>ping ${state.cliques}</button>
+ *     `,
+ *   })
+ *
+ * Valores interpolados são escapados (sem XSS). Mudar `state` ou receber
+ * props novas renderiza de novo. Funções em `on<evento>=${fn}` viram listeners.
+ */
+
+declare const TEMPLATE: unique symbol;
+interface Template {
+    readonly [TEMPLATE]: true;
+    readonly strings: readonly string[];
+    readonly values: readonly unknown[];
+}
+/** Template HTML seguro: tudo que é interpolado é escapado, menos outro `html`. */
+declare function html(strings: TemplateStringsArray, ...values: unknown[]): Template;
+/** Marca uma string como HTML confiável (não é escapada). Use com cuidado. */
+declare function unsafeHTML(markup: string): Template;
+/** Renderiza `view` dentro de `el`, ligando os listeners declarados com `on<evento>=${fn}`. */
+declare function render(view: Template | string | Node, el: Element): void;
+type View = Template | string | Node | null | undefined;
+type RenderFn<P extends Props, S extends object> = (props: P, state: S, ctx: RemoteContext) => View;
+interface ComponentOptions<P extends Props, S extends object> {
+    /** Estado local. Alterar qualquer campo renderiza de novo. */
+    state?: S | (() => S);
+    render: RenderFn<P, S>;
+    /** Roda depois do primeiro render. Pode devolver uma função de limpeza. */
+    mounted?(el: HTMLElement, state: S, ctx: RemoteContext): void | (() => void);
+}
+/**
+ * Cria um remote a partir de uma função que devolve HTML. Aceita só a função
+ * (`component((props) => html\`...\`)`) ou `{ state, render, mounted }`.
+ */
+declare function component<P extends Props = Props, S extends object = Record<string, never>>(options: RenderFn<P, S> | ComponentOptions<P, S>): RemoteModule<P>;
+
+/**
+ * vitral: micro-frontends com um único contrato.
+ *
+ * Um remote é um módulo ES que exporta `mount(el, props, ctx)` e devolve
+ * `{ update?, unmount }`. O host só precisa saber a URL. Nada de config
+ * compartilhada em tempo de build, nada de container global de dependências.
+ */
+type Props = Record<string, unknown>;
+interface RemoteContext {
+    /** Nome com que o host registrou este remote. */
+    name: string;
+    /** URL base de onde o remote foi carregado (útil para assets). */
+    baseUrl: string;
+    /**
+     * Barramento de eventos compartilhado entre host e todos os remotes. As
+     * assinaturas feitas por aqui são canceladas sozinhas no unmount.
+     */
+    events: EventBus;
+    /** Shadow root quando o host pediu isolamento, senão `null`. */
+    shadowRoot: ShadowRoot | null;
+    /** 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`. */
+    navigate(url: string, options?: {
+        replace?: boolean;
+    }): void;
+}
+interface MountedRemote<P extends Props = Props> {
+    update?(props: P): void;
+    unmount(): void;
+}
+interface RemoteModule<P extends Props = Props> {
+    mount(el: HTMLElement, props: P, ctx: RemoteContext): MountedRemote<P> | Promise<MountedRemote<P>>;
+}
+interface RemoteEntry {
+    /** URL do módulo JS do remote, ou do `vitral.json` gerado pelo plugin. */
+    url?: string;
+    /**
+     * Remote local, sem rede: o próprio módulo ou uma função que o importa
+     * (ex.: `() => import('./carrinho')`). Útil em monorepos e testes.
+     */
+    module?: RemoteModule<any> | (() => Promise<RemoteModule<any> | {
+        default: RemoteModule<any>;
+    }>);
+    /** Hash SRI (`sha256-…`, `sha384-…`, `sha512-…`) do JS. Verificado antes de executar. */
+    integrity?: string;
+    /** CSS extra para carregar junto. */
+    css?: string[];
+    /** Isolamento padrão para este remote. */
+    isolate?: Isolation;
+}
+type Isolation = 'shadow' | 'none';
+interface VitralConfig {
+    /** Mapa nome → URL (ou entrada completa), ou a URL de um JSON com esse mapa. */
+    remotes?: Record<string, string | RemoteEntry> | string;
+    /**
+     * Origens de onde é permitido carregar código. Padrão: a própria origem da
+     * página mais as origens das URLs registradas. Use `['*']` para liberar tudo.
+     */
+    allowedOrigins?: string[];
+    /** Tempo máximo para baixar um remote, em ms. Padrão 15000. */
+    timeout?: number;
+    /** Tentativas extras se o download falhar. Padrão 1. */
+    retries?: number;
+    /** Isolamento padrão para todos os remotes. Padrão `'none'`. */
+    isolate?: Isolation;
+}
+type RemoteErrorCode = 'NOT_REGISTERED' | 'ORIGIN_BLOCKED' | 'TIMEOUT' | 'INTEGRITY' | 'INVALID_MODULE' | 'LOAD_FAILED' | 'MOUNT_FAILED' | 'RENDER_FAILED';
+declare class RemoteError extends Error {
+    code: RemoteErrorCode;
+    remote: string;
+    cause?: unknown | undefined;
+    constructor(code: RemoteErrorCode, remote: string, message: string, cause?: unknown | undefined);
+}
+/** Formato do `vitral.json` emitido pelo plugin de build. */
+interface RemoteManifest {
+    name: string;
+    version?: string;
+    entry: string;
+    css?: string[];
+    integrity?: string;
+    /** Escopo usado pelo plugin para prefixar o CSS (`[data-vitral-scope]`). */
+    scope?: string;
+}
+/** Configura a lib. Pode ser chamada mais de uma vez; as opções são mescladas. */
+declare function configure(config: VitralConfig): void;
+/** Registra (ou substitui) um remote. */
+declare function register(name: string, entry: string | RemoteEntry): void;
+/** Baixa (uma vez só) e devolve o módulo de um remote. */
+declare function loadRemote<P extends Props = Props>(name: string): Promise<RemoteModule<P>>;
+/** Começa a baixar um remote sem montar (ex.: no hover de um link). */
+declare function preload(name: string): void;
+interface MountOptions {
+    isolate?: Isolation;
+    /** Chamado quando o remote quebra depois de montado (erro de render, handler etc.). */
+    onError?: (error: RemoteError) => void;
+}
+/**
+ * Monta um remote dentro de `target`. Devolve um handle com `update` e
+ * `unmount` que funciona igual para qualquer framework.
+ */
+declare function mountRemote<P extends Props = Props>(target: HTMLElement, name: string, props: P, options?: MountOptions): Promise<MountedRemote<P>>;
+type SlotStatus = 'loading' | 'ready' | 'error';
+interface SlotOptions<P extends Props = Props> {
+    name: string;
+    props?: P;
+    isolate?: Isolation;
+    /** Chamado a cada mudança de estado (para mostrar fallback / erro). */
+    onStatus?: (status: SlotStatus, error: RemoteError | null) => void;
+}
+interface RemoteSlot<P extends Props = Props> {
+    /** Atualiza as props sem remontar. */
+    update(props: P): void;
+    /** Troca de remote ou de isolamento (remonta). */
+    set(options: Partial<Pick<SlotOptions<P>, 'name' | 'isolate'>>): void;
+    /** Remonta do zero (botão "tentar de novo"). */
+    retry(): void;
+    destroy(): void;
+    readonly status: SlotStatus;
+}
+/**
+ * Cuida do ciclo de vida de um remote dentro de `target`: monta, atualiza,
+ * remonta ao trocar de nome, ignora respostas atrasadas e limpa tudo no fim.
+ * Os adaptadores de host (Web Component, Svelte, Solid, Preact…) usam isto.
+ */
+declare function createSlot<P extends Props = Props>(target: HTMLElement, options: SlotOptions<P>): RemoteSlot<P>;
+/** Declara um remote. É só uma função identidade com tipos. */
+declare function defineRemote<P extends Props = Props>(remote: RemoteModule<P>): RemoteModule<P>;
+type Handler<T = unknown> = (payload: T) => void;
+interface EventBus {
+    emit<T = unknown>(type: string, payload?: T): void;
+    on<T = unknown>(type: string, handler: Handler<T>): () => void;
+    /** Último valor emitido em `type` (útil para estado como "usuário logado"). */
+    last<T = unknown>(type: string): T | undefined;
+}
+declare function createEventBus(): EventBus;
+/** Barramento global. É o mesmo objeto que os remotes recebem em `ctx.events`. */
+declare const events: EventBus;
+/**
+ * Navega mantendo todos os roteadores em sincronia (React Router, Vue Router,
+ * Next, Nuxt…): atualiza o histórico e dispara `popstate`, que todos escutam.
+ */
+declare function navigate(url: string, options?: {
+    replace?: boolean;
+}): void;
+/** Só para testes: limpa todo o estado global. */
+declare function __reset(): void;
+
+export { type ComponentOptions, type EventBus, type Handler, type Isolation, type MountOptions, type MountedRemote, type Props, type RemoteContext, type RemoteEntry, RemoteError, type RemoteErrorCode, type RemoteManifest, type RemoteModule, type RemoteSlot, type RenderFn, type SlotOptions, type SlotStatus, type Template, type View, type VitralConfig, __reset, component, configure, createEventBus, createSlot, defineRemote, events, html, loadRemote, mountRemote, navigate, preload, register, render, unsafeHTML };

package/dist/index.js

@@ -0,0 +1,36 @@
+import {
+  RemoteError,
+  __reset,
+  component,
+  configure,
+  createEventBus,
+  createSlot,
+  defineRemote,
+  events,
+  html,
+  loadRemote,
+  mountRemote,
+  navigate,
+  preload,
+  register,
+  render,
+  unsafeHTML
+} from "./chunk-TTL52BF2.js";
+export {
+  RemoteError,
+  __reset,
+  component,
+  configure,
+  createEventBus,
+  createSlot,
+  defineRemote,
+  events,
+  html,
+  loadRemote,
+  mountRemote,
+  navigate,
+  preload,
+  register,
+  render,
+  unsafeHTML
+};

package/dist/preact.d.ts

@@ -0,0 +1,22 @@
+import * as preact from 'preact';
+import { VNode, ComponentType } from 'preact';
+import { Props, Isolation, RemoteError, SlotStatus, RemoteModule } from './index.js';
+export { RemoteContext, events, navigate } from './index.js';
+
+/** Transforma um componente Preact em um remote. O contexto chega na prop `vitral`. */
+declare function preactRemote<P extends Props>(Component: ComponentType<any>): RemoteModule<P>;
+interface RemoteProps<P extends Props = Props> {
+    name: string;
+    props?: P;
+    isolate?: Isolation;
+    fallback?: VNode | string | null;
+    error?: VNode | string | ((error: RemoteError, retry: () => void) => VNode | string | null) | null;
+    class?: string;
+}
+declare function Remote<P extends Props = Props>({ name, props, isolate, fallback, error, ...rest }: RemoteProps<P>): VNode<preact.ClassAttributes<HTMLElement> & {
+    'data-vitral': string;
+    'data-vitral-status': SlotStatus;
+    class: string | undefined;
+}>;
+
+export { Remote, type RemoteProps, preactRemote };

package/dist/preact.js

@@ -0,0 +1,43 @@
+import {
+  createSlot,
+  defineRemote,
+  events,
+  navigate
+} from "./chunk-TTL52BF2.js";
+
+// src/preact.ts
+import { h, render } from "preact";
+import { useEffect, useRef, useState } from "preact/hooks";
+function preactRemote(Component) {
+  return defineRemote({
+    mount(el, props, ctx) {
+      const draw = (p) => render(h(Component, { ...p, vitral: ctx }), el);
+      draw(props);
+      return { update: draw, unmount: () => render(null, el) };
+    }
+  });
+}
+function Remote({ name, props, isolate, fallback = null, error = null, ...rest }) {
+  const ref = useRef(null);
+  const slot = useRef(null);
+  const [state, setState] = useState({ status: "loading", error: null });
+  useEffect(() => {
+    slot.current = createSlot(ref.current, { name, props: props ?? {}, isolate, onStatus: (status, error2) => setState({ status, error: error2 }) });
+    return () => slot.current?.destroy();
+  }, []);
+  useEffect(() => slot.current?.set({ name, isolate }), [name, isolate]);
+  useEffect(() => slot.current?.update(props ?? {}), [props]);
+  const retry = () => slot.current?.retry();
+  return h("div", { "data-vitral": name, "data-vitral-status": state.status, class: rest.class }, [
+    state.status === "loading" ? fallback : null,
+    state.status === "error" && state.error ? typeof error === "function" ? error(state.error, retry) : error : null,
+    // O Preact nunca coloca filhos neste div: ele pertence ao remote.
+    h("div", { ref })
+  ]);
+}
+export {
+  Remote,
+  events,
+  navigate,
+  preactRemote
+};

package/dist/react.d.ts

@@ -0,0 +1,32 @@
+import * as react from 'react';
+import { ReactNode, ComponentType } from 'react';
+import { Props, Isolation, RemoteModule, RemoteContext } from './index.js';
+export { EventBus, events } from './index.js';
+
+/** Transforma um componente React em um remote. */
+declare function reactRemote<P extends Props>(Component: ComponentType<P>): RemoteModule<P>;
+/** Dentro de um remote: dá acesso ao contexto (nome, eventos, baseUrl). */
+declare function useVitral(): RemoteContext | null;
+/** Assina um evento do barramento global enquanto o componente estiver montado. */
+declare function useEvent<T = unknown>(type: string, handler: (payload: T) => void): void;
+/** Estado derivado do último valor emitido em `type`. */
+declare function useEventValue<T = unknown>(type: string): T | undefined;
+
+interface RemoteProps<P extends Props = Props> {
+    name: string;
+    props?: P;
+    isolate?: Isolation;
+    /** Mostrado enquanto o remote baixa. */
+    fallback?: ReactNode;
+    /** Mostrado se o remote falhar. Recebe o erro e uma função para tentar de novo. */
+    error?: ReactNode | ((error: Error, retry: () => void) => ReactNode);
+    onError?: (error: Error) => void;
+    className?: string;
+}
+/**
+ * Renderiza um remote. No servidor (Next SSR) renderiza só o fallback; o
+ * remote monta no cliente, então não há erro de hidratação.
+ */
+declare function Remote<P extends Props = Props>({ name, props, isolate, fallback, error, onError, className, }: RemoteProps<P>): react.JSX.Element;
+
+export { Remote, type RemoteProps, reactRemote, useEvent, useEventValue, useVitral };

package/dist/react.js

@@ -0,0 +1,117 @@
+"use client";
+import {
+  defineRemote,
+  events,
+  mountRemote
+} from "./chunk-TTL52BF2.js";
+
+// src/react.tsx
+import { Component as ReactComponent, createContext, useContext, useEffect, useRef, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { jsx, jsxs } from "react/jsx-runtime";
+var VitralContext = createContext(null);
+var Boundary = class extends ReactComponent {
+  constructor() {
+    super(...arguments);
+    this.state = { failed: false };
+  }
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  componentDidCatch(error) {
+    this.props.ctx.reportError(error);
+  }
+  render() {
+    return this.state.failed ? null : this.props.children;
+  }
+};
+function reactRemote(Component) {
+  return defineRemote({
+    mount(el, props, ctx) {
+      const root = createRoot(el, { onUncaughtError: (e) => ctx.reportError(e) });
+      const render = (p) => root.render(
+        /* @__PURE__ */ jsx(VitralContext.Provider, { value: ctx, children: /* @__PURE__ */ jsx(Boundary, { ctx, children: /* @__PURE__ */ jsx(Component, { ...p }) }) })
+      );
+      render(props);
+      return { update: render, unmount: () => root.unmount() };
+    }
+  });
+}
+function useVitral() {
+  return useContext(VitralContext);
+}
+function useEvent(type, handler) {
+  const ref = useRef(handler);
+  ref.current = handler;
+  useEffect(() => events.on(type, (p) => ref.current(p)), [type]);
+}
+function useEventValue(type) {
+  const [value, setValue] = useState(() => events.last(type));
+  useEvent(type, setValue);
+  return value;
+}
+function Remote({
+  name,
+  props,
+  isolate,
+  fallback = null,
+  error,
+  onError,
+  className
+}) {
+  const slot = useRef(null);
+  const handle = useRef(null);
+  const latestProps = useRef(props ?? {});
+  latestProps.current = props ?? {};
+  const [status, setStatus] = useState("loading");
+  const [err, setErr] = useState(null);
+  const [attempt, setAttempt] = useState(0);
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+  useEffect(() => {
+    const el = slot.current;
+    if (!el) return;
+    let cancelled = false;
+    setStatus("loading");
+    const fail = (e) => {
+      if (cancelled) return;
+      setErr(e);
+      setStatus("error");
+      if (onErrorRef.current) onErrorRef.current(e);
+      else console.error(e);
+    };
+    const initial = latestProps.current;
+    mountRemote(el, name, initial, { isolate, onError: fail }).then(
+      (h) => {
+        if (cancelled) return h.unmount();
+        handle.current = h;
+        if (latestProps.current !== initial) h.update?.(latestProps.current);
+        setStatus("ready");
+      },
+      fail
+    );
+    return () => {
+      cancelled = true;
+      const h = handle.current;
+      handle.current = null;
+      if (h) queueMicrotask(() => h.unmount());
+    };
+  }, [name, isolate, attempt]);
+  useEffect(() => {
+    handle.current?.update?.(latestProps.current);
+  }, [props]);
+  const retry = () => setAttempt((a) => a + 1);
+  return /* @__PURE__ */ jsxs("div", { className, "data-vitral": name, "data-vitral-status": status, children: [
+    status === "loading" && fallback,
+    status === "error" && err && (typeof error === "function" ? error(err, retry) : error ?? null),
+    /* @__PURE__ */ jsx("div", { ref: slot, style: status === "error" ? { display: "none" } : void 0 }, `${name}:${isolate}:${attempt}`)
+  ] });
+}
+export {
+  Remote,
+  events,
+  reactRemote,
+  useEvent,
+  useEventValue,
+  useVitral
+};

package/dist/solid.d.ts

@@ -0,0 +1,24 @@
+import { JSX, Component } from 'solid-js';
+import { Props, Isolation, RemoteError, RemoteModule } from './index.js';
+export { RemoteContext, events, navigate } from './index.js';
+
+/**
+ * Adaptador Solid (e SolidStart).
+ *
+ * Remote: export default solidRemote(App)
+ * Host:   <Remote name="carrinho" props={{ userId: id() }} />
+ */
+
+/** Transforma um componente Solid em um remote. O contexto chega na prop `vitral`. */
+declare function solidRemote<P extends Props>(Comp: Component<any>): RemoteModule<P>;
+interface RemoteProps<P extends Props = Props> {
+    name: string;
+    props?: P;
+    isolate?: Isolation;
+    fallback?: JSX.Element;
+    error?: (error: RemoteError, retry: () => void) => JSX.Element;
+    class?: string;
+}
+declare function Remote<P extends Props = Props>(p: RemoteProps<P>): JSX.Element;
+
+export { Remote, type RemoteProps, solidRemote };

package/dist/solid.js

@@ -0,0 +1,60 @@
+import {
+  createSlot,
+  defineRemote,
+  events,
+  navigate
+} from "./chunk-TTL52BF2.js";
+
+// src/solid.ts
+import { createComponent, createEffect, createSignal, mergeProps, on, onCleanup, onMount } from "solid-js";
+import { createStore, reconcile } from "solid-js/store";
+import { isServer, render } from "solid-js/web";
+function solidRemote(Comp) {
+  return defineRemote({
+    mount(el, props, ctx) {
+      const [state, setState] = createStore({ ...props });
+      const dispose = render(() => createComponent(Comp, mergeProps(state, { vitral: ctx })), el);
+      return {
+        update: (next) => setState(reconcile({ ...next })),
+        unmount: dispose
+      };
+    }
+  });
+}
+function Remote(p) {
+  if (isServer) return p.fallback ?? null;
+  const [status, setStatus] = createSignal("loading");
+  const [error, setError] = createSignal(null);
+  const host = document.createElement("div");
+  host.setAttribute("data-vitral", p.name);
+  if (p.class) host.className = p.class;
+  const target = document.createElement("div");
+  let slot = null;
+  onMount(() => {
+    slot = createSlot(target, {
+      name: p.name,
+      props: p.props ?? {},
+      isolate: p.isolate,
+      onStatus: (s, e) => {
+        host.setAttribute("data-vitral-status", s);
+        setError(() => e);
+        setStatus(s);
+      }
+    });
+  });
+  createEffect(on(() => [p.name, p.isolate], ([name, isolate]) => slot?.set({ name, isolate }), { defer: true }));
+  createEffect(on(() => ({ ...p.props ?? {} }), (props) => slot?.update(props), { defer: true }));
+  onCleanup(() => slot?.destroy());
+  const retry = () => slot?.retry();
+  return [
+    () => status() === "loading" ? p.fallback : null,
+    () => status() === "error" && error() && p.error ? p.error(error(), retry) : null,
+    (host.appendChild(target), host)
+  ];
+}
+export {
+  Remote,
+  events,
+  navigate,
+  solidRemote
+};

package/dist/svelte.d.ts

@@ -0,0 +1,27 @@
+import { Component } from 'svelte';
+import { Props, Isolation, SlotStatus, RemoteError, RemoteModule } from './index.js';
+export { RemoteContext, events, navigate } from './index.js';
+
+/**
+ * Adaptador Svelte 5 (e SvelteKit).
+ *
+ * Remote: export default svelteRemote(App)
+ * Host:   <div use:remote={{ name: 'carrinho', props: { userId } }}></div>
+ *         ou o Web Component <vitral-remote> de 'vitral/element'.
+ */
+
+/** Transforma um componente Svelte em um remote. O contexto chega na prop `vitral`. */
+declare function svelteRemote<P extends Props>(component: Component<any>): RemoteModule<P>;
+interface RemoteActionParams<P extends Props = Props> {
+    name: string;
+    props?: P;
+    isolate?: Isolation;
+    onStatus?: (status: SlotStatus, error: RemoteError | null) => void;
+}
+/** Action Svelte: `<div use:remote={{ name, props }}>`. Funciona também em SvelteKit (só roda no cliente). */
+declare function remote<P extends Props = Props>(node: HTMLElement, params: RemoteActionParams<P>): {
+    update(next: RemoteActionParams<P>): void;
+    destroy: () => void;
+};
+
+export { type RemoteActionParams, remote, svelteRemote };

package/dist/svelte.js

@@ -0,0 +1,36 @@
+import {
+  createSlot,
+  defineRemote,
+  events,
+  navigate
+} from "./chunk-TTL52BF2.js";
+
+// src/svelte.ts
+import { createClassComponent } from "svelte/legacy";
+function svelteRemote(component) {
+  return defineRemote({
+    mount(el, props, ctx) {
+      const instance = createClassComponent({ component, target: el, props: { ...props, vitral: ctx } });
+      return {
+        update: (next) => instance.$set({ ...next, vitral: ctx }),
+        unmount: () => instance.$destroy()
+      };
+    }
+  });
+}
+function remote(node, params) {
+  const slot = createSlot(node, params);
+  return {
+    update(next) {
+      slot.set({ name: next.name, isolate: next.isolate });
+      slot.update(next.props ?? {});
+    },
+    destroy: () => slot.destroy()
+  };
+}
+export {
+  events,
+  navigate,
+  remote,
+  svelteRemote
+};

package/dist/testing.d.ts

@@ -0,0 +1,28 @@
+import { Props, RemoteContext } from './index.js';
+export { __reset as resetVitral } from './index.js';
+
+/**
+ * Utilidades de teste: monte o host sem subir nenhum remote de verdade.
+ *
+ *   import { mockRemote } from 'vitral/testing'
+ *   const carrinho = mockRemote('carrinho', (el, props) => (el.textContent = `itens: ${props.itens}`))
+ *   render(<App />)
+ *   expect(carrinho.lastProps).toEqual({ itens: 2 })
+ */
+
+interface MockRemote<P extends Props = Props> {
+    /** Quantas vezes foi montado. */
+    readonly mounts: number;
+    /** Props mais recentes recebidas (mount ou update). */
+    readonly lastProps: P | undefined;
+    /** Contexto da última montagem (eventos, navigate…). */
+    readonly ctx: RemoteContext | undefined;
+    /** Está montado agora? */
+    readonly mounted: boolean;
+}
+/** Registra um remote falso. `render` é chamado no mount e a cada update. */
+declare function mockRemote<P extends Props = Props>(name: string, render?: (el: HTMLElement, props: P, ctx: RemoteContext) => void): MockRemote<P>;
+/** Remote que sempre falha ao montar, para testar telas de erro. */
+declare function failingRemote(name: string, message?: string): void;
+
+export { type MockRemote, failingRemote, mockRemote };

package/dist/testing.js

@@ -0,0 +1,47 @@
+import {
+  __reset,
+  register
+} from "./chunk-TTL52BF2.js";
+
+// src/testing.ts
+function mockRemote(name, render = (el) => {
+  el.setAttribute("data-mock-remote", name);
+}) {
+  const stats = { mounts: 0, lastProps: void 0, ctx: void 0, mounted: false };
+  register(name, {
+    module: {
+      mount(el, props, ctx) {
+        stats.mounts++;
+        stats.mounted = true;
+        stats.lastProps = props;
+        stats.ctx = ctx;
+        render(el, props, ctx);
+        return {
+          update(next) {
+            stats.lastProps = next;
+            render(el, next, ctx);
+          },
+          unmount() {
+            stats.mounted = false;
+            el.replaceChildren();
+          }
+        };
+      }
+    }
+  });
+  return stats;
+}
+function failingRemote(name, message = "falha simulada") {
+  register(name, {
+    module: {
+      mount() {
+        throw new Error(message);
+      }
+    }
+  });
+}
+export {
+  failingRemote,
+  mockRemote,
+  __reset as resetVitral
+};