wu-framework 1.1.7 → 1.1.8

package/README.md

@@ -1,893 +1,570 @@
 # Wu Framework
 
-**Universal Microfrontends Made Simple**
+**The easiest way to turn any app into a microfrontend — and the only one that doesn't force you to stop working as a standalone app.**
 
-Wu Framework es la libreria de microfrontends mas simple y poderosa del mercado. Framework agnostic, zero config, Shadow DOM nativo.
-
-## Por que Wu Framework?
-
-| Caracteristica | Module Federation | qiankun | single-spa | **Wu Framework** |
-|---|---|---|---|---|
-| **Setup** | Webpack config complejo | Configuracion manual | Config extensa | **Zero config** |
-| **Framework Support** | React-first | Multi framework | Multi framework | **8 frameworks nativos** |
-| **Bundler Required** | Solo Webpack 5 | Agnostico | Agnostico | **Ninguno requerido** |
-| **CSS Isolation** | Basico | CSS hacks | Manual | **Shadow DOM nativo** |
-| **JS Isolation** | No | Proxy basico | No | **Proxy + Snapshot Sandbox** |
-| **Style Modes** | No | No | No | **3 modos (shared/isolated/fully-isolated)** |
-| **Runtime Config** | No | Limitado | Limitado | **Completamente dinamico** |
-| **Self-Healing** | No | No | No | **Auto-recovery** |
-| **Build Protection** | No | No | No | **Minify + Obfuscate + Base64** |
-| **API Complexity** | Alta | Media | Alta | **1 linea de codigo** |
-
-## Instalacion
+Wu speaks the language of your framework. One line to register a React component, a Vue app, an Angular module. Your app works inside a microfrontend shell AND as a standalone app — same code, zero changes.
 
 ```bash
 npm install wu-framework
 ```
 
-Sin webpack config, sin plugins, sin configuracion adicional.
-
 ---
 
-## Frameworks Soportados
+## Why Wu?
+
+Every microfrontend framework forces you to learn its language. Single-spa makes you export `bootstrap`, `mount`, `unmount`. Module Federation requires webpack config. Qiankun needs manual registration with lifecycle callbacks.
+
+Wu doesn't. You write React code. You write Vue code. You write Angular code. Wu adapts to you.
+
+```jsx
+// That's it. Your React app is now a microfrontend.
+wuReact.register('header', App);
+```
 
-Wu Framework incluye **adapters nativos** para los frameworks mas populares:
+If Wu isn't running? Your app mounts directly to `#root` and works by itself. No lock-in. No dependency on a shell being alive. **Microfrontends that don't chain you.**
 
-| Framework | Adapter | Registro |
-|-----------|---------|----------|
-| React | `wuReact` | `wuReact.register('app', App)` |
-| Vue | `wuVue` | `wuVue.register('app', App)` |
-| Angular | `wuAngular` | `wuAngular.register('app', AppModule)` |
-| Angular Standalone | `wuAngular` | `wuAngular.registerStandalone('app', Component)` |
-| Angular Elements | `wuAngular` | `wuAngular.registerElement('app', Component)` |
-| Svelte | `wuSvelte` | `wuSvelte.register('app', App)` |
-| Preact | `wuPreact` | `wuPreact.register('app', App)` |
-| Solid.js | `wuSolid` | `wuSolid.register('app', App)` |
-| Lit | `wuLit` | `wuLit.register('app', MyElement)` |
-| Vanilla JS | `wuVanilla` | `wuVanilla.register('app', config)` |
+### What makes Wu different
+
+| | single-spa | qiankun | Module Federation | **Wu** |
+|---|---|---|---|---|
+| **Registration** | Export lifecycle functions | Manual lifecycle callbacks | Webpack config | **One line, framework-native** |
+| **CSS isolation** | Manual | CSS prefixing (fragile) | None | **Shadow DOM + 3 configurable modes** |
+| **JS isolation** | None | Basic Proxy | None | **Proxy sandbox with side-effect cleanup** |
+| **Standalone mode** | No | No | No | **Automatic — works without shell** |
+| **Framework API** | Generic | Generic | Generic | **Native hooks, composables, stores per framework** |
+| **Prefetch** | Manual | Manual preload | None | **Speculation Rules API + fallbacks** |
+| **QA Overrides** | None | None | None | **Cookie-based URL overrides (secure)** |
+| **Config required** | Extensive | Moderate | Webpack plugin | **Zero** |
 
 ---
 
-## Quick Start
+## WuCommerce — Real-World Example
 
-### 1. Micro App: Crear `wu.json`
+Wu Framework ships with **WuCommerce**, a Shopify-like merchant dashboard where every section is a real micro-app built with a different framework. The narrative: each module was built by a different team or acquired, unified under wu-framework.
 
-Cada microfrontend necesita un archivo `wu.json` en su raiz:
+| Micro-app | Framework | What it does |
+|-----------|-----------|-------------|
+| **Topbar** | Preact | Store name, nav tabs, search, notifications, theme toggle |
+| **Dashboard** | Svelte 5 | KPI cards, sparklines, recent orders, revenue chart |
+| **Orders** | React | Order table with filters, search, status badges |
+| **Products** | Vue 3 | Product catalog grid, stock badges, category filter |
+| **Customers** | Solid.js | Customer list, segment badges, click-to-filter-orders |
+| **Analytics** | Lit | Revenue bar chart, traffic donut, top products |
+| **Chat** | Vanilla JS | Floating chat widget with conversations and messages |
+| **Settings** | Angular 21 | Store config form, shipping zones, payment methods |
 
-```json
-{
-  "name": "header",
-  "version": "1.0.0",
-  "entry": "index.js",
-  "styleMode": "shared",
-  "wu": {
-    "exports": {
-      "NavBar": "components/NavBar.js",
-      "UserMenu": "components/UserMenu.js"
-    },
-    "imports": [],
-    "routes": ["/", "/home"],
-    "permissions": ["events", "store"]
-  }
-}
+All 8 apps communicate through Wu's event bus and shared store. Click a customer → orders filter by that customer. Toggle theme → all 8 apps update. Change store name in settings → topbar updates.
+
+```
+npm run dev    # starts all 9 servers (1 shell + 8 micro-apps)
+open http://localhost:4321
 ```
 
-| Campo | Descripcion |
-|-------|-------------|
-| `name` | Nombre unico del microfrontend |
-| `version` | Version del microfrontend |
-| `entry` | Archivo JS principal (default: `index.js`) |
-| `styleMode` | Modo de estilos: `shared`, `isolated`, `fully-isolated` |
-| `wu.exports` | Componentes que expone a otros microfrontends |
-| `wu.imports` | Componentes que importa de otros microfrontends |
-| `wu.routes` | Rutas que maneja este microfrontend |
-| `wu.permissions` | Permisos requeridos (`events`, `store`, `dom`) |
+Source: `examples/astro-multi-framework/`
+
+---
+
+## Quick Start
 
-### 2. Micro App: Registrar con Adapter (1 linea)
+### 1. Register your micro app
 
 **React:**
-```tsx
+```jsx
 import { wuReact } from 'wu-framework/adapters/react';
 import App from './App';
-
-wuReact.register('header', App);
+wuReact.register('orders', App);
 ```
 
 **Vue:**
-```ts
+```js
 import { wuVue } from 'wu-framework/adapters/vue';
 import App from './App.vue';
-
-wuVue.register('sidebar', App);
+wuVue.register('products', App);
 ```
 
-**Angular:**
+**Angular (standalone component):**
 ```ts
+import 'zone.js';
+import '@angular/compiler';
+import { createApplication } from '@angular/platform-browser';
+import { createComponent, provideZoneChangeDetection } from '@angular/core';
 import { wuAngular } from 'wu-framework/adapters/angular';
-import { AppModule } from './app/app.module';
+import { AppComponent } from './app/app.component';
 
-wuAngular.register('content', AppModule);
+wuAngular.registerStandalone('settings', AppComponent, {
+  createApplication,
+  createComponent,
+  provideZoneChangeDetection,
+});
 ```
 
-El adapter se encarga de todo: deteccion de contexto, modo standalone, cleanup automatico.
+**Svelte 5:**
+```js
+import { wuSvelte } from 'wu-framework/adapters/svelte';
+import App from './App.svelte';
+wuSvelte.registerSvelte5('dashboard', App);
+```
 
-### 3. Shell (Host Application)
+**Solid:**
+```jsx
+import { wuSolid } from 'wu-framework/adapters/solid';
+import App from './App';
+wuSolid.register('customers', App);
+```
+
+**Preact:**
+```jsx
+import { wuPreact } from 'wu-framework/adapters/preact';
+import App from './App';
+wuPreact.register('topbar', App);
+```
+
+**Lit:**
+```js
+import { wuLit } from 'wu-framework/adapters/lit';
+import { MyApp } from './my-app.js';
+wuLit.register('analytics', MyApp);
+```
+
+**Vanilla JS:**
+```js
+import wuVanilla from 'wu-framework/adapters/vanilla';
+// use wuVanilla.useWuEvents() and wuVanilla.useWuStore() inside mount/unmount
+```
+
+### 2. Mount from the shell
 
-**Desarrollo:**
 ```js
 import { wu } from 'wu-framework';
 
 await wu.init({
   apps: [
-    { name: 'header', url: 'http://localhost:3001' },
+    { name: 'header',  url: 'http://localhost:3001' },
     { name: 'sidebar', url: 'http://localhost:3002' },
     { name: 'content', url: 'http://localhost:3003' }
   ]
 });
 
-await wu.mount('header', '#header-container');
+await wu.mount('header',  '#header-container');
 await wu.mount('sidebar', '#sidebar-container');
 await wu.mount('content', '#content-container');
 ```
 
-**Produccion:**
-```js
-import { wu } from 'wu-framework';
+Each app runs inside its own Shadow DOM with a JS sandbox that tracks and cleans up all side effects on unmount.
 
-await wu.init({
-  apps: [
-    { name: 'header', url: 'https://cdn.mycompany.com/mfe/header' },
-    { name: 'sidebar', url: 'https://cdn.mycompany.com/mfe/sidebar' },
-    { name: 'content', url: 'https://cdn.mycompany.com/mfe/content' }
-  ]
-});
-```
+---
 
-### Estructura de Archivos (Microfrontend)
+## 8 Framework Adapters
 
-```
-my-header-mfe/
-├── wu.json          # Manifest requerido
-├── index.js         # Entry point (registra con adapter)
-├── App.jsx          # Componente principal
-├── components/
-│   ├── NavBar.js
-│   └── UserMenu.js
-└── package.json
-```
+Wu doesn't give you a generic API and tell you to figure it out. Each adapter speaks the native language of its framework.
+
+| Framework | Adapter | Register | Native APIs |
+|-----------|---------|----------|-------------|
+| React | `wuReact` | `.register(name, Component)` | `createUseWuEvents(React)`, `createUseWuStore(React)` |
+| Vue 3 | `wuVue` | `.register(name, Component)` | `useWuEvents()`, `useWuStore()`, `WuSlot`, plugin |
+| Angular 14+ | `wuAngular` | `.registerStandalone(name, Component, opts)` | `createWuService()` |
+| Angular (NgModule) | `wuAngular` | `.register(name, Module)` | Same |
+| Angular Elements | `wuAngular` | `.registerElement(name, Component)` | Same |
+| Svelte 3/4 | `wuSvelte` | `.register(name, Component)` | `createWuStore()`, `useWuEvents()` |
+| Svelte 5 | `wuSvelte` | `.registerSvelte5(name, Component)` | Same + `createWuEventStore()` |
+| Preact | `wuPreact` | `.register(name, Component)` | `createUseWuEvents(hooks)`, `createUseWuStore(hooks)` |
+| Preact (compat) | `wuPreact` | `.registerCompat(name, Component)` | Same |
+| Solid.js | `wuSolid` | `.register(name, Component)` | `useWuEvents()`, `createWuStore()`, `createWuEvent()` |
+| Lit | `wuLit` | `.register(name, Element)` | `WuMixin(LitElement)`, `wuProperty()` decorator |
+| Web Component | `wuLit` | `.registerWebComponent(name, Element)` | Same |
+| Vanilla JS | `wuVanilla` | `.register(name, config)` | `useWuEvents()`, `useWuStore()`, `createComponent()` |
+| Vanilla (class) | `wuVanilla` | `.registerClass(name, Class)` | Same |
+| Vanilla (template) | `wuVanilla` | `.registerTemplate(name, html)` | Same |
+
+> **Note:** React and Preact hooks are *factory functions* — pass `React` or `{ useCallback, useEffect, useRef }` to get the actual hooks. Vue composables work directly with no arguments. Angular's `registerStandalone` is recommended over `register` because it works inside Shadow DOM.
+
+Every adapter detects if Wu is present. If not, the app mounts standalone. Your microfrontend never stops working.
 
 ---
 
-## Modos de Inyeccion de Estilos
+## 3 CSS Isolation Modes
 
-Wu Framework soporta **3 modos de inyeccion de estilos** en Shadow DOM:
+This is something no other microfrontend framework offers: **per-app configurable style isolation**.
 
-| Modo | Descripcion | Riesgo Colision |
-|------|-------------|-----------------|
-| `shared` | Inyecta TODOS los estilos del documento padre | Alto |
-| `isolated` | NO inyecta estilos externos (Shadow DOM nativo) | Ninguno |
-| `fully-isolated` | Inyecta SOLO estilos propios de la app | Ninguno |
+| Mode | What happens | When to use |
+|------|-------------|-------------|
+| `shared` | Host document styles are injected into Shadow DOM | Apps sharing a design system (Tailwind, Element Plus) |
+| `isolated` | Pure Shadow DOM — no external styles enter | Fully independent apps with their own CSS |
+| `fully-isolated` | Only the app's own styles are injected | Apps that need their CSS but not global CSS |
 
-### Configuracion en wu.json
+Set it in `wu.json`:
 
 ```json
 {
   "name": "my-app",
+  "entry": "index.js",
   "styleMode": "isolated"
 }
 ```
 
-### shared (default)
-
-- Inyecta estilos de librerias (Element Plus, Tailwind, Vue Flow, etc.)
-- Inyecta estilos globales del documento
-- Observer HMR para cambios en desarrollo
-- **Ideal para:** Apps que comparten un design system comun
-
-### isolated
-
-- NO inyecta ningun estilo externo
-- Usa encapsulamiento nativo del Shadow DOM
-- La app debe incluir sus propios estilos (CSS-in-JS, scoped, imports)
-- **Ideal para:** Apps con estilos completamente independientes
-
-### fully-isolated
-
-- Detecta y inyecta SOLO estilos propios de la app especifica
-- Patron de deteccion: `packages/appName/src/`
-- MutationObserver persistente para HMR de Vite
-- **Ideal para:** Apps que necesitan sus estilos pero no los globales
+In a real team, your header might need `shared` (same design system as the shell), your analytics dashboard might need `isolated` (completely independent), and your sidebar might need `fully-isolated` (own styles only). Wu handles all three in the same page.
 
 ---
 
-## React Adapter
+## JS Sandbox — Three Modes, Real Isolation
 
-### Registro Basico
+Wu offers three sandbox modes. Pick the one that fits your workflow:
 
-```tsx
-import { wuReact } from 'wu-framework/adapters/react';
-import App from './App';
-
-wuReact.register('my-app', App);
-```
+| Mode | How it works | Tree shaking | Source maps | HMR | JS isolation |
+|------|-------------|:---:|:---:|:---:|:---:|
+| `module` (default) | `import()` + Proxy side-effect tracking | ✅ | ✅ | ✅ | Side effects only |
+| `strict` | Hidden iframe + real `import()` | ✅ | ✅ | ✅ | **Full** (separate window) |
+| `eval` | Fetch HTML → parse → `with(proxy){}` | ❌ | ❌ | ❌ | **Full** (proxy traps) |
 
-### Con Opciones
+```js
+// Global setting
+await wu.init({
+  sandbox: 'strict',  // or 'module' (default) or 'eval'
+  apps: [...]
+});
 
-```tsx
-wuReact.register('my-app', App, {
-  strictMode: true,           // Envolver en React.StrictMode
-  props: { theme: 'dark' },   // Props iniciales
-  standalone: true,           // Ejecutar independiente si Wu no esta
-  standaloneContainer: '#root',
-  onMount: (container) => console.log('Mounted!'),
-  onUnmount: (container) => console.log('Unmounted!')
+// Per-app override — mix modes in the same page
+await wu.init({
+  apps: [
+    { name: 'header',    url: '...', sandbox: 'module' },  // Fast dev, no isolation
+    { name: 'analytics', url: '...', sandbox: 'strict' },  // Full isolation + modern DX
+    { name: 'legacy',    url: '...', sandbox: 'eval' },    // UMD bundle, max isolation
+  ]
 });
 ```
 
-### Hooks para React
+**Module mode** loads your app via `import()`. Side effects (timers, listeners, storage) are tracked through the Proxy and cleaned on unmount. App code runs in the global scope — the proxy is a cleanup tracker. Works with ES modules, Vite HMR, and all modern tooling.
 
-```tsx
-import React from 'react';
-import { createUseWuEvents, createUseWuStore } from 'wu-framework/adapters/react';
+**Strict mode** creates a hidden iframe as an isolated execution context, then runs `import()` inside it. Your app gets a **separate `window`** — globals, timers, and listeners are isolated by the browser itself. Document operations (`querySelector`, `createElement`, `body`) are proxied to the Shadow DOM container. Destroying the iframe nukes all side effects at once. If `import()` fails (CORS), it falls back to eval mode automatically.
 
-const useWuEvents = createUseWuEvents(React);
-const useWuStore = createUseWuStore(React);
+**Eval mode** fetches your app's HTML, parses out `<script>` and `<style>` tags, and executes all scripts inside the Proxy sandbox using `with(proxy){}`. Every unqualified identifier (`setTimeout`, `document`, `fetch`) resolves through the proxy's traps. This is qiankun-level isolation. Requires bundled apps (UMD/IIFE), not ES modules.
 
-function MyComponent() {
-  const { emit, on } = useWuEvents();
-  const { state, setState } = useWuStore('user');
-
-  useEffect(() => {
-    const unsub = on('cart:updated', (data) => {
-      console.log('Cart updated:', data);
-    });
-    return unsub;
-  }, [on]);
+### How strict mode works
 
-  return (
-    <button onClick={() => emit('user:logout')}>
-      Logout {state?.name}
-    </button>
-  );
-}
 ```
-
-### Cargar Microfrontends en React (Shell)
-
-```tsx
-import React from 'react';
-import { createWuSlot } from 'wu-framework/adapters/react';
-
-const WuSlot = createWuSlot(React);
-
-const HEADER_URL = process.env.REACT_APP_HEADER_URL || 'http://localhost:3001';
-
-function Shell() {
-  return (
-    <div>
-      <WuSlot
-        name="header"
-        url={HEADER_URL}
-        onLoad={() => console.log('Header loaded!')}
-        onError={(err) => console.error(err)}
-      />
-    </div>
-  );
-}
+┌── Main Window ──────────────────────────────────┐
+│  ┌── Shadow DOM ──────────────────────────────┐ │
+│  │  App renders here (CSS isolated)            │ │
+│  │  document.querySelector → scoped here       │ │
+│  └────────────────────────────────────────────┘ │
+│  ┌── Hidden iframe ──────────────────────────┐  │
+│  │  import() runs here (REAL ES modules)      │  │
+│  │  window = separate context (ISOLATED)      │  │
+│  │  document.createElement → main document    │  │
+│  │  Destroy iframe = kill everything          │  │
+│  └────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────┘
 ```
 
----
+Strict mode preserves your entire development workflow:
+- **Tree shaking** — real `import()`, bundler optimizations work as normal
+- **Source maps** — browser loads real modules, maps resolve correctly
+- **Vite HMR** — HMR client runs inside iframe, WebSocket connects to dev server
+- **Full isolation** — separate `window` context, no global leaks between apps
 
-## Vue Adapter
+**What gets tracked and auto-cleaned (all modes):**
+- `setTimeout` / `setInterval` / `requestAnimationFrame` — all IDs tracked, all cleared
+- `addEventListener` / `removeEventListener` — all listeners tracked, all removed
+- `document.querySelector` — scoped to the app's Shadow DOM
+- `localStorage` / `sessionStorage` — keys prefixed with `wu_{appName}_`
 
-### Registro Basico
+**277 tests verify this works.** Unit tests for every isolation feature, integration tests proving two sandboxes don't contaminate each other.
 
-```ts
-import { wuVue } from 'wu-framework/adapters/vue';
-import App from './App.vue';
-
-wuVue.register('my-app', App);
-```
-
-### Con Plugins (Pinia, Router, etc.)
+---
 
-```ts
-import { wuVue } from 'wu-framework/adapters/vue';
-import { createPinia } from 'pinia';
-import router from './router';
-import App from './App.vue';
+## Cross-App Communication
 
-wuVue.register('my-app', App, {
-  setup: (app) => {
-    app.use(createPinia());
-    app.use(router);
-  }
-});
-```
-
-### Composables para Vue
+### Event Bus
 
-```vue
-<script setup>
-import { onMounted, onUnmounted } from 'vue';
-import { useWuEvents, useWuStore } from 'wu-framework/adapters/vue';
+```js
+import { emit, on, once, off } from 'wu-framework';
 
-const { emit, on, cleanup } = useWuEvents();
-const { state, setState } = useWuStore('cart');
+emit('user:login', { userId: 123 });
 
-onMounted(() => {
-  on('user:login', (data) => console.log('Login:', data));
+const unsub = on('user:*', (event) => {
+  console.log(event.name, event.data);
 });
 
-onUnmounted(() => cleanup());
-</script>
-
-<template>
-  <div>
-    <p>Items: {{ state?.items?.length }}</p>
-    <button @click="emit('cart:clear')">Clear Cart</button>
-  </div>
-</template>
+once('app:ready', (e) => console.log('Ready'));
+unsub();
 ```
 
-### Cargar Microfrontends en Vue (Shell)
+Features: wildcard patterns (`user:*`, `*.error`, `app.*.ready`), event replay for late-joining apps, strict mode (only registered apps can emit), history buffer.
 
-```vue
-<script setup>
-import { WuSlot } from 'wu-framework/adapters/vue';
-
-const headerUrl = import.meta.env.VITE_HEADER_URL || 'http://localhost:3001';
-</script>
-
-<template>
-  <div>
-    <WuSlot
-      name="header"
-      :url="headerUrl"
-      @load="onLoad"
-      @error="onError"
-    />
-  </div>
-</template>
-```
-
-### Plugin Global
-
-```ts
-import { createApp } from 'vue';
-import { wuVuePlugin } from 'wu-framework/adapters/vue';
-
-const app = createApp(App);
-app.use(wuVuePlugin); // Registra <WuSlot> globalmente
-```
+### Store
 
----
+```js
+import { getState, setState, onStateChange } from 'wu-framework';
 
-## Angular Adapter
+setState('user.name', 'John');
+setState('user.preferences.theme', 'dark');
 
-### Registro con NgModule
+getState('user.name');  // 'John'
 
-```ts
-import { wuAngular } from 'wu-framework/adapters/angular';
-import { AppModule } from './app/app.module';
+const unsub = onStateChange('user.*', (value, path) => {
+  console.log(`${path} = ${value}`);
+});
 
-wuAngular.register('my-app', AppModule);
+// Batch updates
+wu.store.batch({ 'cart.count': 5, 'cart.total': 99.99 });
 ```
 
-### Registro con Standalone Components (Angular 14+)
+Ring buffer event history. Wildcard subscriptions. Dot-notation paths with auto-creation of nested objects.
 
-```ts
-import { wuAngular } from 'wu-framework/adapters/angular';
-import { AppComponent } from './app/app.component';
-import { appConfig } from './app/app.config';
+---
 
-wuAngular.registerStandalone('my-app', AppComponent, {
-  appConfig
-});
-```
+## Framework-Native Integration Examples
 
-### Registro con Angular Elements (Web Components)
+> All examples below are from **WuCommerce**, a real merchant dashboard built with Wu Framework.
+> 8 micro-apps, 8 different frameworks, running together in one shell.
+> See `examples/astro-multi-framework/` for the full source.
 
-Para proyectos que usan Angular Elements para crear Web Components:
+### React — Orders (mf-eventlab)
 
-```ts
-import { wuAngular } from 'wu-framework/adapters/angular';
-import { AppComponent } from './app/app.component';
-import { appConfig } from './app/app.config';
-
-wuAngular.registerElement('my-app', AppComponent, {
-  elementTag: 'my-app-element',  // Tag del custom element
-  appConfig,                      // Configuracion de Angular
-  standaloneContainer: '#root',   // Container para modo standalone
-  onMount: (container, element) => {
-    console.log('Angular Element mounted');
-  },
-  onUnmount: (container, element) => {
-    console.log('Angular Element unmounted');
-  }
-});
-```
-
-El adapter se encarga de:
-- Crear la aplicacion Angular
-- Registrar el Custom Element con `customElements.define()`
-- Gestionar el ciclo de vida mount/unmount
-- Soportar modo standalone si Wu Framework no esta disponible
+```jsx
+// main.jsx
+import { wuReact } from 'wu-framework/adapters/react';
+import App from './App';
+wuReact.register('orders', App);
 
-### Servicio para Componentes
+// App.jsx — hooks are factories, pass React to get the hook
+import React, { useState, useEffect, useMemo } from 'react';
+import { createUseWuEvents, createUseWuStore } from 'wu-framework/adapters/react';
 
-```ts
-import { Component, OnInit, OnDestroy } from '@angular/core';
-import { createWuService } from 'wu-framework/adapters/angular';
+const useWuEvents = createUseWuEvents(React);
+const useWuStore = createUseWuStore(React);
 
-@Component({
-  selector: 'app-root',
-  template: `<button (click)="sendEvent()">Send Event</button>`
-})
-export class AppComponent implements OnInit, OnDestroy {
-  private wuService = createWuService();
+function Orders() {
+  const { emit, on } = useWuEvents();
+  const [filter, setFilter] = useState('all');
 
-  ngOnInit() {
-    this.wuService.on('user:login', (data) => {
-      console.log('User logged in:', data);
+  useEffect(() => {
+    const unsub = on('customer:selected', (e) => {
+      setFilter(e.data?.customerName || 'all');
     });
-  }
-
-  sendEvent() {
-    this.wuService.emit('app:ready', { timestamp: Date.now() });
-  }
+    return unsub;
+  }, []);
 
-  ngOnDestroy() {
-    this.wuService.destroy();
-  }
+  return <button onClick={() => emit('order:new', { id: 1001, total: 49.99 })}>New Order</button>;
 }
 ```
 
----
-
-## Svelte Adapter
+### Vue 3 — Products (mf-statebridge)
 
-### Registro Basico
+```vue
+<!-- main.js -->
+<!-- import { wuVue } from 'wu-framework/adapters/vue'; -->
+<!-- import App from './App.vue'; -->
+<!-- wuVue.register('products', App); -->
 
-```js
-import { wuSvelte } from 'wu-framework/adapters/svelte';
-import App from './App.svelte';
+<script setup>
+import { ref, computed, onMounted, onUnmounted } from 'vue';
+import { wuVue } from 'wu-framework/adapters/vue';
 
-wuSvelte.register('my-app', App);
-```
+const { useWuEvents, useWuStore } = wuVue;
+const events = useWuEvents();
 
-### Svelte 5 (con runes)
+onMounted(() => {
+  events.on('search:global', (e) => {
+    search.value = e.data?.query || '';
+  });
+});
 
-```js
-import { wuSvelte } from 'wu-framework/adapters/svelte';
-import App from './App.svelte';
+function handleStockAlert(product) {
+  events.emit('product:stockAlert', { productId: product.id, stock: product.stock });
+}
 
-wuSvelte.registerSvelte5('my-app', App);
+onUnmounted(() => events.cleanup());
+</script>
 ```
 
-### Stores Reactivos
+### Svelte 5 — Dashboard (mf-hero)
 
 ```svelte
+<!-- main.js: wuSvelte.registerSvelte5('dashboard', App) -->
 <script>
-  import { createWuStore, useWuEvents } from 'wu-framework/adapters/svelte';
-  import { onDestroy } from 'svelte';
+  import { wuSvelte } from 'wu-framework/adapters/svelte';
 
-  const userStore = createWuStore('user');
+  const { createWuStore, createWuEventStore, useWuEvents } = wuSvelte;
   const { emit, on, cleanup } = useWuEvents();
 
-  on('cart:updated', (data) => {
-    console.log('Cart updated:', data);
-  });
-
-  onDestroy(cleanup);
-</script>
+  let stats = $state({ revenue: 12847, orders: 156, visitors: 2341, conversion: 4.2 });
 
-<p>Hello, {$userStore?.name}</p>
-<button on:click={() => emit('user:logout')}>Logout</button>
-```
+  on('theme:toggle', (e) => console.log('Theme:', e.data?.theme));
 
----
+  function handleNewOrder() {
+    emit('order:new', { orderId: `ORD-${Date.now()}`, total: 49.99, status: 'pending' });
+  }
 
-## Preact Adapter
+  // cleanup is called automatically on component destroy
+</script>
+```
 
-### Registro Basico
+### Solid.js — Customers (mf-features)
 
 ```jsx
-import { wuPreact } from 'wu-framework/adapters/preact';
-import App from './App';
+// main.jsx: wuSolid.register('customers', App)
+import { createSignal, onMount } from 'solid-js';
+import { wuSolid } from 'wu-framework/adapters/solid';
 
-wuPreact.register('my-app', App);
-```
+export default function Customers() {
+  const [search, setSearch] = createSignal('');
+  const { emit, on } = wuSolid.useWuEvents(); // auto-cleanup via onCleanup
 
-### Compatible con React (preact/compat)
+  onMount(() => {
+    on('search:global', (e) => setSearch(e.data?.query || ''));
+  });
 
-```jsx
-import { wuPreact } from 'wu-framework/adapters/preact';
-import App from './App';
+  const handleRowClick = (customer) => {
+    emit('customer:selected', { customerId: customer.id, customerName: customer.name });
+    emit('nav:section', { section: 'orders' });
+  };
 
-wuPreact.registerCompat('my-app', App);
+  return <div>...</div>;
+}
 ```
 
-### Hooks
+### Preact — Topbar (mf-header)
 
 ```jsx
-import { h } from 'preact';
-import { useState, useEffect, useCallback, useRef } from 'preact/hooks';
-import { createUseWuEvents, createUseWuStore } from 'wu-framework/adapters/preact';
+// main.jsx: wuPreact.register('topbar', App)
+import { useState, useCallback, useEffect, useRef } from 'preact/hooks';
+import { wuPreact } from 'wu-framework/adapters/preact';
 
-const useWuEvents = createUseWuEvents({ useCallback, useEffect, useRef });
-const useWuStore = createUseWuStore({ useState, useCallback, useEffect });
+// Factory pattern — pass hooks as argument
+const useWuEvents = wuPreact.createUseWuEvents({ useCallback, useEffect, useRef });
+const useWuStore = wuPreact.createUseWuStore({ useState, useCallback, useEffect });
 
-function MyComponent() {
+function Topbar() {
   const { emit, on } = useWuEvents();
-  const { state } = useWuStore('user');
+  const storeData = useWuStore('store');
+
+  const handleSearch = (query) => emit('search:global', { query });
+  const toggleTheme = () => emit('theme:toggle', { theme: isDark ? 'light' : 'dark' });
 
-  return <div>Hello {state?.name}</div>;
+  return <header>...</header>;
 }
 ```
 
----
+### Angular 21 — Settings (mf-pluginperf)
 
-## Solid.js Adapter
+```ts
+// main.ts — full setup (JIT mode, no AnalogJS needed)
+import 'zone.js';
+import '@angular/compiler';
+import { createApplication } from '@angular/platform-browser';
+import { createComponent, provideZoneChangeDetection } from '@angular/core';
+import { wuAngular } from 'wu-framework/adapters/angular';
+import { SettingsComponent } from './app/settings.component';
 
-### Registro Basico
+wuAngular.registerStandalone('settings', SettingsComponent, {
+  standaloneContainer: '#app',
+  createApplication,          // pass Angular APIs to avoid bundler issues
+  createComponent,
+  provideZoneChangeDetection,
+});
 
-```jsx
-import { wuSolid } from 'wu-framework/adapters/solid';
-import App from './App';
+// settings.component.ts — use createWuService for events/store
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { createWuService } from 'wu-framework/adapters/angular';
 
-wuSolid.register('my-app', App);
-```
+@Component({ selector: 'app-settings', standalone: true, template: '...' })
+export class SettingsComponent implements OnInit, OnDestroy {
+  private wu = createWuService();
+  storeName = '';
 
-### Stores Reactivos
+  ngOnInit() {
+    this.storeName = this.wu.getState('store')?.name || '';
+    this.wu.on('theme:toggle', (e) => console.log('Theme:', e.data?.theme));
+  }
 
-```jsx
-import { createWuStore, createWuEvent } from 'wu-framework/adapters/solid';
-
-function MyComponent() {
-  const [user, setUser] = createWuStore('user');
-  const lastEvent = createWuEvent('notification:*');
-
-  return (
-    <div>
-      <p>Hello, {user()?.name}</p>
-      <Show when={lastEvent()}>
-        <p>Last notification: {lastEvent()?.data}</p>
-      </Show>
-      <button onClick={() => setUser('name', 'John')}>
-        Set Name
-      </button>
-    </div>
-  );
+  save() {
+    this.wu.setState('store', { name: this.storeName });
+    this.wu.emit('settings:saved', { name: this.storeName });
+  }
+
+  ngOnDestroy() { this.wu.destroy(); }
 }
 ```
 
----
-
-## Lit Adapter (Web Components)
+> **Angular + Vite setup:** No AnalogJS or Angular CLI required. Plain Vite with
+> `esbuild: { target: 'es2022' }` and `tsconfig.json` with `experimentalDecorators: true`.
+> `@angular/compiler` import enables JIT mode at runtime. Pass `createApplication`,
+> `createComponent`, `provideZoneChangeDetection` as options to `registerStandalone`
+> so the bundler resolves them from your app's `node_modules`.
 
-### Registro con LitElement
+### Lit — Analytics (mf-showcase)
 
 ```js
+// main.js: wuLit.register('analytics', AnalyticsApp)
 import { LitElement, html, css } from 'lit';
-import { wuLit } from 'wu-framework/adapters/lit';
-
-class MyApp extends LitElement {
-  static styles = css`
-    :host { display: block; padding: 16px; }
-  `;
-
-  render() {
-    return html`<h1>Hello from Lit!</h1>`;
-  }
-}
-
-wuLit.register('my-app', MyApp);
-```
-
-### Con WuMixin
-
-```js
-import { LitElement, html } from 'lit';
 import { WuMixin } from 'wu-framework/adapters/lit';
 
-class MyApp extends WuMixin(LitElement) {
+class AnalyticsApp extends WuMixin(LitElement) {
+  static styles = css`...`;
+
   connectedCallback() {
     super.connectedCallback();
-    this.wuOn('user:login', (data) => {
-      console.log('User logged in:', data);
-    });
-  }
-
-  handleClick() {
-    this.wuEmit('button:clicked', { id: 'my-button' });
+    this.wuOn('theme:toggle', () => this.requestUpdate());
+    const stats = this.wuGetState('stats');
   }
 
   render() {
     return html`
-      <button @click=${this.handleClick}>Click me</button>
+      <button @click=${() => this.wuEmit('analytics:export')}>Export</button>
     `;
   }
 }
-
-wuLit.register('my-app', MyApp);
+customElements.define('analytics-app', AnalyticsApp);
 ```
 
-### Web Component Vanilla (sin Lit)
+### Vanilla JS — Chat Widget (mf-sandbox)
 
 ```js
-import { wuLit } from 'wu-framework/adapters/lit';
+// main.js — default import
+import wuVanilla from 'wu-framework/adapters/vanilla';
 
-class MyComponent extends HTMLElement {
-  connectedCallback() {
-    this.attachShadow({ mode: 'open' });
-    this.shadowRoot.innerHTML = '<h1>Hello Web Component!</h1>';
-  }
-}
-
-wuLit.registerWebComponent('my-component', MyComponent);
-```
-
----
+const { useWuEvents, useWuStore } = wuVanilla;
+const events = useWuEvents();
+const store = useWuStore();
 
-## Vanilla JS Adapter
-
-### Registro con Objeto
-
-```js
-import { wuVanilla } from 'wu-framework/adapters/vanilla';
-
-wuVanilla.register('my-app', {
-  state: { count: 0 },
-
-  render: (container, state) => {
-    container.innerHTML = `
-      <div>
-        <h1>Count: ${state.count}</h1>
-        <button id="increment">+</button>
-      </div>
-    `;
-    container.querySelector('#increment').onclick = () => {
-      state.count++;
-    };
-  },
-
-  destroy: (container) => {
-    container.innerHTML = '';
-  }
-});
-```
-
-### Registro con Clase
-
-```js
-import { wuVanilla } from 'wu-framework/adapters/vanilla';
-
-class TodoApp {
-  constructor(container) {
-    this.container = container;
-    this.todos = [];
-  }
-
-  render() {
-    this.container.innerHTML = `
-      <ul>
-        ${this.todos.map(t => `<li>${t}</li>`).join('')}
-      </ul>
-      <input type="text" id="input" />
-      <button id="add">Add</button>
-    `;
-
-    this.container.querySelector('#add').onclick = () => {
-      const input = this.container.querySelector('#input');
-      this.todos.push(input.value);
-      this.render();
-    };
-  }
-
-  destroy() {
-    this.container.innerHTML = '';
-  }
+function mount(container) {
+  events.on('theme:toggle', (e) => applyTheme(e.data?.theme));
+  const user = store.get('user');
+  // render chat UI into container...
 }
 
-wuVanilla.registerClass('todo-app', TodoApp);
-```
-
-### Registro con Template
-
-```js
-import { wuVanilla } from 'wu-framework/adapters/vanilla';
-
-wuVanilla.registerTemplate('header', `
-  <header>
-    <h1>My Header</h1>
-    <nav>
-      <a href="/">Home</a>
-      <a href="/about">About</a>
-    </nav>
-  </header>
-`);
-
-// Template dinamico
-wuVanilla.registerTemplate('greeting',
-  (data) => `<h1>Hello, ${data.name}!</h1>`,
-  { data: { name: 'World' } }
-);
-```
-
-### Componente Reactivo
-
-```js
-import { wuVanilla } from 'wu-framework/adapters/vanilla';
-
-const Counter = wuVanilla.createComponent({
-  state: { count: 0 },
-
-  template: (state) => `
-    <div>
-      <h1>Count: ${state.count}</h1>
-      <button data-action="increment">+</button>
-      <button data-action="decrement">-</button>
-    </div>
-  `,
-
-  actions: {
-    increment: (state) => ({ count: state.count + 1 }),
-    decrement: (state) => ({ count: state.count - 1 })
-  }
-});
-
-wuVanilla.register('counter', Counter);
-```
-
----
-
-## Event Bus
-
-Sistema de eventos para comunicacion entre microfrontends con soporte para wildcards y replay.
-
-```js
-import { emit, on, once, off, replayEvents } from 'wu-framework';
-
-// Emitir evento
-emit('user:login', { userId: 123, name: 'John' });
-
-// Suscribirse a evento
-const unsubscribe = on('user:login', (event) => {
-  console.log('User logged in:', event.data);
-});
-
-// Suscribirse con wildcards
-on('user:*', (event) => {
-  console.log('User event:', event.name, event.data);
-});
-
-// Suscribirse una sola vez
-once('app:ready', (event) => {
-  console.log('App is ready!');
-});
-
-// Desuscribirse
-off('user:login', callback);
-unsubscribe();
-
-// Replay eventos del historial
-replayEvents('user:*', (event) => {
-  console.log('Past event:', event);
-});
-```
-
----
-
-## Store (State Management)
-
-Store de alto rendimiento con pattern matching.
-
-```js
-import {
-  getState,
-  setState,
-  onStateChange,
-  batchState,
-  clearState,
-  getStoreMetrics
-} from 'wu-framework';
-
-// Establecer estado (dot notation)
-setState('user.name', 'John');
-setState('user.preferences.theme', 'dark');
-
-// Obtener estado
-const name = getState('user.name'); // 'John'
-const user = getState('user');      // { name: 'John', preferences: { theme: 'dark' } }
-
-// Suscribirse a cambios
-const unsubscribe = onStateChange('user.name', (value, path) => {
-  console.log(`${path} changed to:`, value);
-});
-
-// Suscribirse con wildcards
-onStateChange('user.*', (value, path) => {
-  console.log(`User property changed: ${path} =`, value);
-});
-
-// Batch updates (mas eficiente)
-batchState({
-  'user.name': 'Jane',
-  'user.email': 'jane@example.com',
-  'settings.notifications': true
-});
-
-// Metricas de performance
-const metrics = getStoreMetrics();
+function unmount(container) {
+  events.cleanup();
+  container.innerHTML = '';
+}
 ```
 
 ---
 
-## Sistema de Plugins
+## Plugins & Lifecycle Hooks
 
 ```js
-import { usePlugin, createPlugin, uninstallPlugin } from 'wu-framework';
+import { usePlugin, createPlugin, useHook, createGuardHook } from 'wu-framework';
 
-const analyticsPlugin = createPlugin({
+// Plugin
+usePlugin(createPlugin({
   name: 'analytics',
-  permissions: ['events', 'store'],
-
-  install: (api, options) => {
-    api.on('app:mounted', (event) => {
-      trackEvent('mount', event.data.appName);
-    });
-  },
+  install: (api) => api.on('app:mounted', (e) => track(e)),
+  afterMount: async (ctx) => log('mounted in', ctx.mountTime, 'ms')
+}));
 
-  beforeMount: async (context) => {
-    console.log('Before mount:', context.appName);
-  },
-
-  afterMount: async (context) => {
-    console.log('Mounted in', context.mountTime, 'ms');
-  }
-});
-
-usePlugin(analyticsPlugin, { trackingId: 'UA-123456' });
-```
-
----
-
-## Lifecycle Hooks
-
-```js
-import { useHook, createGuardHook, createTimedHook } from 'wu-framework';
-
-// Hook basico
+// Lifecycle hook
 useHook('beforeMount', async (context, next) => {
-  console.log('Before mounting:', context.appName);
+  console.log('Mounting:', context.appName);
   await next();
-}, { name: 'my-hook', priority: 10 });
-
-// Guard hook (puede cancelar)
-const authGuard = createGuardHook(async (ctx) => {
-  return await isUserAuthenticated();
 });
-useHook('beforeMount', authGuard);
 
-// Hook con timeout
-const timedHook = createTimedHook(async (ctx) => {
-  await slowOperation();
-}, 5000);
+// Guard — can cancel mount
+useHook('beforeMount', createGuardHook(async () => isAuthenticated()));
 ```
 
-### Fases Disponibles
-
-| Fase | Descripcion |
-|------|-------------|
-| `beforeInit` | Antes de inicializar framework |
-| `afterInit` | Despues de inicializar |
-| `beforeLoad` | Antes de cargar una app |
-| `afterLoad` | Despues de cargar |
-| `beforeMount` | Antes de montar |
-| `afterMount` | Despues de montar |
-| `beforeUnmount` | Antes de desmontar |
-| `afterUnmount` | Despues de desmontar |
+Phases: `beforeInit` → `afterInit` → `beforeLoad` → `afterLoad` → `beforeMount` → `afterMount` → `beforeUnmount` → `afterUnmount`
 
 ---
 
@@ -896,378 +573,235 @@ const timedHook = createTimedHook(async (ctx) => {
 ```js
 await wu.init({
   apps: [
-    { name: 'header', url: '/mfe/header', strategy: 'lazy' },
-    { name: 'sidebar', url: '/mfe/sidebar', strategy: 'eager' },
-    { name: 'footer', url: '/mfe/footer', strategy: 'preload' },
+    { name: 'header',    url: '/mfe/header',    strategy: 'eager' },
+    { name: 'content',   url: '/mfe/content',   strategy: 'lazy' },
     { name: 'analytics', url: '/mfe/analytics', strategy: 'idle' }
   ]
 });
 ```
 
-| Estrategia | Descripcion | Uso recomendado |
-|------------|-------------|-----------------|
-| `lazy` | Carga cuando se monta (default) | Contenido below-the-fold |
-| `eager` | Precarga inmediata | Componentes criticos |
-| `preload` | Usa `<link rel="prefetch">` | Navegacion anticipada |
-| `idle` | Usa `requestIdleCallback` | Analytics, features secundarias |
+| Strategy | Behavior |
+|----------|----------|
+| `lazy` | Load when mounted (default) |
+| `eager` | Load immediately |
+| `preload` | `<link rel="prefetch">` |
+| `idle` | `requestIdleCallback` |
+| `speculate` | Speculation Rules API with automatic fallback chain |
 
 ---
 
-## Performance Monitoring
+## Intelligent Prefetch (Speculation Rules API)
 
-```js
-import {
-  startMeasure,
-  endMeasure,
-  getPerformanceMetrics,
-  generatePerformanceReport
-} from 'wu-framework';
-
-// Medicion personalizada
-startMeasure('data-fetch', 'my-app');
-await fetchData();
-const duration = endMeasure('data-fetch', 'my-app');
-
-// Reporte completo
-const report = generatePerformanceReport();
-```
-
----
+Wu uses the browser-native [Speculation Rules API](https://developer.chrome.com/docs/web-platform/prerender-pages) (Chrome 121+) for near-instant microfrontend loads, with automatic fallbacks for older browsers.
 
-## Error Handling
+### Fallback chain
 
-```js
-import { registerErrorHandler, configureErrorBoundary } from 'wu-framework';
-
-registerErrorHandler({
-  name: 'api-error',
-  canHandle: (error) => error.message.includes('API'),
-  handle: async (error, context) => {
-    if (context.retryCount < 3) {
-      return { recovered: true, action: 'retry' };
-    }
-    return { recovered: false, action: 'fallback' };
-  }
-});
-
-configureErrorBoundary({
-  maxRetries: 3,
-  retryDelay: 1000,
-  showErrorUI: true
-});
+```
+Speculation Rules API  →  <link rel="modulepreload">  →  <link rel="prefetch">
+   (Chrome 121+)            (modern browsers)              (all browsers)
 ```
 
----
-
-## API Simplificada (wu.app)
+### Usage
 
 ```js
-import { wu } from 'wu-framework';
-
-const header = wu.app('header', {
-  url: 'http://localhost:3001',
-  container: '#header-container'
-});
-
-await header.mount();
-console.log(header.isMounted); // true
+// Prefetch specific apps
+wu.prefetch(['sidebar', 'analytics']);
 
-await header.unmount();
-await header.remount();
-await header.reload();  // Limpia cache
+// Prefetch all registered apps
+wu.prefetchAll();
 
-const health = await header.verify();
-await header.destroy();
+// With options
+wu.prefetch(['sidebar'], {
+  trigger: 'hover',      // 'immediate' | 'hover' | 'visible' | 'idle'
+  action: 'prefetch',    // 'prefetch' | 'prerender'
+  eagerness: 'moderate', // 'immediate' | 'eager' | 'moderate' | 'conservative'
+});
 ```
 
----
-
-## Sistema de Build
-
-Wu Framework incluye un sistema de build completo para proteger el codigo.
-
-### Comandos Disponibles
-
-```bash
-# Instalar dependencias
-npm install
-
-# Build completo (todos los formatos)
-npm run build
+### Triggers
 
-# Builds individuales
-npm run build:dev        # Desarrollo (sin minificar)
-npm run build:prod       # Produccion (minificado)
-npm run build:obf        # Ofuscado
-npm run build:umd        # UMD para browsers
-npm run build:cjs        # CommonJS para Node
+| Trigger | Behavior |
+|---------|----------|
+| `immediate` | Prefetch now (default) |
+| `hover` | Prefetch when user hovers over the app's container |
+| `visible` | Prefetch when app's container enters viewport (IntersectionObserver, 200px margin) |
+| `idle` | Prefetch during browser idle time (`requestIdleCallback`) |
 
-# Build protegido (pipeline completo)
-npm run build:protected  # Bundle -> Minify -> Obfuscate -> Base64
-```
-
-### Pipeline de Proteccion
+### As loading strategy
 
+```js
+await wu.init({
+  apps: [
+    { name: 'header',    url: '/mfe/header',    strategy: 'eager' },
+    { name: 'sidebar',   url: '/mfe/sidebar',   strategy: 'speculate' },
+    { name: 'analytics', url: '/mfe/analytics', strategy: 'idle' },
+  ]
+});
 ```
-Source Code
-    |
-    v
-[1] Bundle (Rollup)      -> Empaqueta todos los modulos
-    |
-    v
-[2] Minify (Terser)      -> Reduce ~60% del tamanio
-    |
-    v
-[3] Obfuscate            -> Codigo ilegible
-    |
-    v
-[4] Base64 Encode        -> Capa adicional de proteccion
-    |
-    v
-Output: wu-framework.protected.js (~250KB)
-```
-
-### Archivos Generados
 
-| Archivo | Formato | Uso |
-|---------|---------|-----|
-| `wu-framework.dev.js` | ES Module | Desarrollo |
-| `wu-framework.min.js` | ES Module | Produccion |
-| `wu-framework.obf.js` | ES Module | Produccion protegida |
-| `wu-framework.protected.js` | ES Module | Maxima proteccion |
-| `wu-framework.umd.js` | UMD | Browsers via CDN |
-| `wu-framework.cjs.js` | CommonJS | Node.js |
+The `speculate` strategy uses the Speculation Rules API by default with `immediate` trigger. It degrades gracefully — your app works on any browser, it just loads faster on Chrome 121+.
 
 ---
 
-## Sandbox System
+## Cookie Overrides for QA/Testing
 
-Wu Framework usa dos estrategias de aislamiento JS:
+Redirect individual microfrontends to different URLs without changing code or deploying. QA sets a cookie, and only **their browser** sees the override — everyone else sees production.
 
-### Proxy Sandbox (Default)
+### How it works
 
-- Usa ES6 Proxy para interceptar acceso a globales
-- Aislamiento completo sin side effects
-- Requiere soporte de Proxy (navegadores modernos)
-
-### Snapshot Sandbox (Fallback)
+```
+1. QA opens DevTools → Application → Cookies
+2. Sets: wu-override:sidebar=http://localhost:5174
+3. Reloads → only "sidebar" loads from localhost
+4. Everyone else sees production sidebar
+```
 
-- Toma snapshots del estado global
-- Restaura al desmontar
-- Compatible con navegadores legacy
+### Programmatic API
 
 ```js
-// El framework detecta automaticamente la mejor estrategia
-const stats = wu.sandbox.getStats();
-console.log(stats.strategy); // 'proxy' o 'snapshot'
-```
+// Set an override (persists as cookie for 24h)
+wu.override('sidebar', 'http://localhost:5174');
 
----
+// Check active overrides
+wu.getOverrides();
+// → { sidebar: 'http://localhost:5174' }
 
-## Deployment
+// Remove one
+wu.removeOverride('sidebar');
 
-### Estructura de Produccion
-
-```
-https://cdn.mycompany.com/
-├── mfe/
-│   ├── header/
-│   │   ├── wu.json
-│   │   ├── index.js
-│   │   └── assets/
-│   ├── sidebar/
-│   │   ├── wu.json
-│   │   ├── index.js
-│   │   └── assets/
-│   └── content/
-│       ├── wu.json
-│       ├── index.js
-│       └── assets/
+// Clear all
+wu.clearOverrides();
 ```
 
-### Configuracion por Entorno
+### Security model (3 layers)
 
-```js
-const config = {
-  development: {
-    header: 'http://localhost:3001',
-    sidebar: 'http://localhost:3002',
-    content: 'http://localhost:3003'
-  },
-  staging: {
-    header: 'https://staging-cdn.mycompany.com/mfe/header',
-    sidebar: 'https://staging-cdn.mycompany.com/mfe/sidebar',
-    content: 'https://staging-cdn.mycompany.com/mfe/content'
-  },
-  production: {
-    header: 'https://cdn.mycompany.com/mfe/header',
-    sidebar: 'https://cdn.mycompany.com/mfe/sidebar',
-    content: 'https://cdn.mycompany.com/mfe/content'
-  }
-};
+| Layer | Protection |
+|-------|-----------|
+| **Environment gate** | Disabled in production by default. Auto-enabled only on `localhost` / `127.0.0.1`. Must explicitly opt-in for production. |
+| **Domain allowlist** | Only overrides to whitelisted domains are accepted. Supports wildcards: `*.company.com`. |
+| **Visual indicator** | Fixed yellow banner shows active overrides. Prevents silent phishing. Click to hide, double-click to clear. |
 
-const env = process.env.NODE_ENV || 'development';
-const urls = config[env];
+### Enable in production (for QA teams)
 
-await wu.init({
-  apps: [
-    { name: 'header', url: urls.header },
-    { name: 'sidebar', url: urls.sidebar },
-    { name: 'content', url: urls.content }
-  ]
+```js
+wu.overrides.configure({
+  enabled: true,
+  allowedDomains: ['*.mycompany.com', 'localhost', '*.vercel.app'],
+  showIndicator: true,
 });
 ```
 
-### CORS Configuration
+### Cookie format
 
-```nginx
-location /mfe/ {
-    add_header Access-Control-Allow-Origin *;
-    add_header Access-Control-Allow-Methods "GET, OPTIONS";
-    add_header Access-Control-Allow-Headers "Content-Type";
-}
 ```
+wu-override:<appName>=<url>
 
-### Versionado
-
-```json
-{
-  "name": "header",
-  "version": "1.2.0",
-  "entry": "index.js"
-}
+# Examples:
+wu-override:sidebar=http://localhost:5174
+wu-override:header=https://staging.mycompany.com/header
 ```
 
-```js
-await wu.init({
-  apps: [
-    { name: 'header', url: 'https://cdn.mycompany.com/mfe/header/v1.2.0' },
-    { name: 'sidebar', url: 'https://cdn.mycompany.com/mfe/sidebar/v2.0.0' }
-  ]
-});
-```
+No proxy. No server changes. Pure client-side URL substitution at init time.
 
 ---
 
-## Arquitectura
+## Build & Test
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     HOST APPLICATION                         │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
-│  │  #shadow-root   │  │  #shadow-root   │  │ #shadow-root│  │
-│  │  ┌───────────┐  │  │  ┌───────────┐  │  │ ┌─────────┐ │  │
-│  │  │  Header   │  │  │  │  Sidebar  │  │  │ │ Content │ │  │
-│  │  │  (React)  │  │  │  │  (Vue)    │  │  │ │(Angular)│ │  │
-│  │  └───────────┘  │  │  └───────────┘  │  │ └─────────┘ │  │
-│  │  CSS Isolated   │  │  CSS Isolated   │  │ CSS Isolated│  │
-│  │  JS Sandboxed   │  │  JS Sandboxed   │  │ JS Sandboxed│  │
-│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
-├─────────────────────────────────────────────────────────────┤
-│                      WU FRAMEWORK CORE                       │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐  │
-│  │ EventBus │ │  Store   │ │ Plugins  │ │ Sandbox Pool   │  │
-│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘  │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐  │
-│  │  Loader  │ │ Manifest │ │  Hooks   │ │ Style Bridge   │  │
-│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
+```bash
+npm run build          # ESM + CJS + UMD + Dev
+npm run build:prod     # Production (minified)
+npm run build:dev      # Development (unminified)
+npm run test           # 277 tests (Vitest)
+npm run test:coverage  # Coverage report
 ```
 
----
+| Output | Format | Use |
+|--------|--------|-----|
+| `wu-framework.esm.js` | ES Module | Bundler imports |
+| `wu-framework.cjs.js` | CommonJS | Node.js require |
+| `wu-framework.umd.js` | UMD | CDN / script tag |
+| `wu-framework.dev.js` | ES Module | Development |
 
-## API Reference
+---
 
-### Core
+## Architecture
 
-```js
-import { wu, init, mount, unmount, destroy, getStats } from 'wu-framework';
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│                       SHELL (Astro)                                   │
+│   Sidebar + Section Containers + wu.init() + wu.mount()               │
+├──────────┬──────────┬──────────┬──────────┬──────────┬────────────────┤
+│ Shadow   │ Shadow   │ Shadow   │ Shadow   │ Shadow   │ Shadow    ... │
+│ ┌──────┐ │ ┌──────┐ │ ┌──────┐ │ ┌──────┐ │ ┌──────┐ │ ┌──────┐     │
+│ │Topbar│ │ │Dashbd│ │ │Orders│ │ │Produc│ │ │Custo.│ │ │Analyt│     │
+│ │Preact│ │ │Svelte│ │ │React │ │ │Vue 3 │ │ │Solid │ │ │ Lit  │     │
+│ └──────┘ │ └──────┘ │ └──────┘ │ └──────┘ │ └──────┘ │ └──────┘     │
+├──────────┴──────────┴──────────┴──────────┴──────────┴────────────────┤
+│                       WU FRAMEWORK CORE                               │
+│  Sandbox (module/strict/eval) · EventBus (wildcards, replay)          │
+│  Store (dot-paths, batch) · StyleBridge (shared/isolated/fully-iso)   │
+│  Loader · Hooks · Plugins · Cache · Prefetch · Overrides              │
+└───────────────────────────────────────────────────────────────────────┘
 ```
 
-### Event Bus
+Each micro-app runs inside its own Shadow DOM with configurable CSS isolation and a JS sandbox that tracks and auto-cleans all side effects on unmount.
 
-```js
-import { emit, on, once, off, replayEvents, getEventBusStats } from 'wu-framework';
-```
+---
 
-### Store
+## API Reference
 
 ```js
-import { getState, setState, onStateChange, batchState, clearState } from 'wu-framework';
-```
+// Core
+import { wu, init, mount, unmount, destroy, app, define } from 'wu-framework';
 
-### Plugins & Hooks
+// Events
+import { emit, on, once, off } from 'wu-framework';
 
-```js
-import { usePlugin, createPlugin, useHook, removeHook } from 'wu-framework';
-```
+// State
+import { getState, setState, onStateChange } from 'wu-framework';
 
-### Performance & Errors
+// Plugins & Hooks
+import { usePlugin, createPlugin, useHook } from 'wu-framework';
+import { createGuardHook, createTimedHook, createTransformHook } from 'wu-framework';
 
-```js
+// Performance
 import { startMeasure, endMeasure, generatePerformanceReport } from 'wu-framework';
-import { registerErrorHandler, configureErrorBoundary } from 'wu-framework';
-```
 
-### Style Management
-
-```js
-import { configureStyleSharing, reinjectStyles, getStyleStats } from 'wu-framework';
-```
+// Prefetch (Speculation Rules API)
+import { prefetch, prefetchAll } from 'wu-framework';
 
-### Adapters
+// Overrides (QA/Testing)
+import { override, removeOverride, getOverrides, clearOverrides } from 'wu-framework';
 
-```js
-import { wuReact } from 'wu-framework/adapters/react';
-import { wuVue } from 'wu-framework/adapters/vue';
+// Adapters
+import { wuReact }   from 'wu-framework/adapters/react';
+import { wuVue }     from 'wu-framework/adapters/vue';
 import { wuAngular } from 'wu-framework/adapters/angular';
-import { wuSvelte } from 'wu-framework/adapters/svelte';
-import { wuPreact } from 'wu-framework/adapters/preact';
-import { wuSolid } from 'wu-framework/adapters/solid';
-import { wuLit } from 'wu-framework/adapters/lit';
+import { wuSvelte }  from 'wu-framework/adapters/svelte';
+import { wuPreact }  from 'wu-framework/adapters/preact';
+import { wuSolid }   from 'wu-framework/adapters/solid';
+import { wuLit }     from 'wu-framework/adapters/lit';
 import { wuVanilla } from 'wu-framework/adapters/vanilla';
-```
-
-### Utilities
-
-```js
-import { presets, dev, events } from 'wu-framework';
 
-// Presets
-await wu.init(presets.development([{ name: 'app', port: 3001 }]));
-await wu.init(presets.production([{ name: 'app', url: 'https://...' }]));
+// Prefetch
+wu.prefetch(['sidebar', 'analytics']);
+wu.prefetch(['sidebar'], { trigger: 'hover' });
+wu.prefetchAll();
 
-// Dev tools
-dev.enableDebug();
-dev.inspect();
-await dev.reload('app');
+// Overrides (QA)
+wu.override('sidebar', 'http://localhost:5174');
+wu.removeOverride('sidebar');
+wu.getOverrides();
+wu.clearOverrides();
+wu.overrides.configure({ enabled: true, allowedDomains: ['*.company.com'] });
 
-// Silenciar logs
+// Log control
 wu.silence();
 wu.verbose();
 ```
 
 ---
 
-## Contributing
-
-Las contribuciones son bienvenidas!
-
-1. **Fork** el repositorio
-2. **Crear** branch (`git checkout -b feature/amazing-feature`)
-3. **Commit** tus cambios (`git commit -m 'Add amazing feature'`)
-4. **Push** al branch (`git push origin feature/amazing-feature`)
-5. **Abrir** un Pull Request
-
----
-
 ## License
 
-MIT License - Copyright (c) 2025 Wu Framework Team
-
----
-
-**Wu Framework - Universal Microfrontends Made Simple**
-
-*Zero dependencies - 8 Frameworks - Shadow DOM - Proxy Sandbox - Self-Healing - Build Protection*
+MIT