wu-framework 1.1.8 → 1.1.10

package/README.md

@@ -1,135 +1,144 @@
-# Wu Framework
+<p align="center">
+  <img src="https://wu-framework.dev/favicon.svg" width="80" alt="Wu Framework" />
+</p>
+
+<h1 align="center">Wu Framework</h1>
+
+<p align="center">
+  <strong>Universal microfrontends with built-in AI. Zero dependencies.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/wu-framework"><img src="https://img.shields.io/npm/v/wu-framework.svg?color=8b5cf6&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/wu-framework/wu-framework/actions"><img src="https://img.shields.io/github/actions/workflow/status/wu-framework/wu-framework/ci.yml?label=tests&color=10b981" alt="tests" /></a>
+  <img src="https://img.shields.io/badge/tests-650%20passed-10b981" alt="650 tests" />
+  <img src="https://img.shields.io/badge/dependencies-0-8b5cf6" alt="zero deps" />
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+</p>
+
+<p align="center">
+  <a href="https://wu-framework.dev">Documentation</a> &middot;
+  <a href="https://wu-framework.dev/docs/quick-start">Quick Start</a> &middot;
+  <a href="https://wu-framework.dev/docs/ai/overview">AI Integration</a> &middot;
+  <a href="#wucommerce--real-world-example">Live Example</a>
+</p>
 
-**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.**
+---
+
+Run **React, Vue, Angular, Svelte, Solid, Preact, Lit, and Vanilla JS** micro-apps side by side in the same page. Each app lives in its own Shadow DOM with full CSS isolation. Apps communicate through a shared event bus and store — no tight coupling, no iframes.
 
-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.
+Add AI to any app with one line. Connect your own LLM (OpenAI, Anthropic, Ollama) and your app gains context-aware tool calling, autonomous agents, and cross-app orchestration. **WebMCP ready** for Chrome 146+.
 
 ```bash
 npm install wu-framework
 ```
 
----
-
-## 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);
-```
+## 30-Second Demo
 
-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.**
+```js
+import { wu } from 'wu-framework';
+import { wuReact } from 'wu-framework/adapters/react';
+import { wuVue } from 'wu-framework/adapters/vue';
 
-### What makes Wu different
+// Register micro-apps from different frameworks
+wuReact.register('cart', CartApp);
+wuVue.register('catalog', CatalogApp);
 
-| | 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** |
+// Mount them — each gets its own Shadow DOM
+await wu.mount('cart', '#cart-container');
+await wu.mount('catalog', '#catalog-container');
 
----
+// They talk to each other via events
+wu.emit('cart:item-added', { productId: 'SKU-42' });
+wu.on('catalog:product-selected', (e) => console.log(e.data));
 
-## WuCommerce — Real-World Example
+// Add AI with one line — BYOL (Bring Your Own LLM)
+wu.ai.provider('openai', { endpoint: '/api/ai/chat', model: 'gpt-4o' });
+wu.ai.action('addToCart', {
+  description: 'Add a product to the shopping cart',
+  parameters: { productId: { type: 'string', required: true } },
+  handler: async (params) => wu.emit('cart:item-added', params),
+});
 
-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.
+// Now the AI can control your app
+await wu.ai.send('Add product SKU-42 to the cart');
+```
 
-| 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 |
+## Why Wu?
 
-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.
+| | **Wu Framework** | **single-spa** | **Module Federation** | **iframes** |
+|---|:---:|:---:|:---:|:---:|
+| Framework adapters | **8** | 4 | 1* | Any |
+| Shadow DOM isolation | Yes | No | No | Yes (heavy) |
+| Shared event bus | Built-in | Manual | Manual | postMessage |
+| Shared store | Built-in | Manual | Manual | No |
+| Standalone mode | Automatic | No | No | N/A |
+| AI integration | Built-in | No | No | No |
+| WebMCP (Chrome 146+) | Built-in | No | No | No |
+| MCP Server (dev tools) | Built-in | No | No | No |
+| Dependencies | **0** | 0 | Webpack 5 | N/A |
+| Bundle size (min) | ~174 KB | ~10 KB | Varies | N/A |
+
+*Module Federation is Webpack-coupled; Wu is bundler-agnostic.
 
-```
-npm run dev    # starts all 9 servers (1 shell + 8 micro-apps)
-open http://localhost:4321
-```
+---
 
-Source: `examples/astro-multi-framework/`
+## Features
+
+### Core
+
+- **8 Framework Adapters** — React, Vue, Angular, Svelte, Solid, Preact, Lit, Vanilla
+- **Shadow DOM Isolation** — CSS and DOM fully sandboxed per app
+- **3 Sandbox Strategies** — Shadow DOM, Proxy, iframe — choose per app
+- **3 CSS Isolation Modes** — `shared`, `isolated`, `fully-isolated` per app
+- **Event Bus** — Namespaced pub/sub with wildcards, replay, and middleware
+- **Shared Store** — Cross-app reactive state with dot-path notation and persistence
+- **Plugin System** — Extend Wu with lifecycle hooks
+- **Performance Monitor** — Mount time, memory, FPS tracking per app
+- **Error Boundaries** — Catch and recover from micro-app failures
+- **Keep-Alive** — Preserve app state when hiding/showing
+- **Prefetch** — Speculation Rules API with automatic fallback chain
+- **Cookie Overrides** — QA redirects individual apps to different URLs per-browser
+- **Standalone Mode** — Every micro-app works without a shell, zero lock-in
+
+### AI (BYOL — Bring Your Own LLM)
+
+- **4 Paradigms** — App→LLM, LLM→App, Autonomous Agent, Cross-App Orchestration
+- **Tool Calling** — Register actions the AI executes autonomously
+- **Streaming** — Async generator for real-time responses
+- **Multi-turn** — Namespaced conversations with history
+- **Reactive Triggers** — Events automatically invoke the AI
+- **Auto Context** — Store state, apps, events injected into the system prompt
+- **10 Browser Actions** — Screenshot, click, type, navigate, read console/network
+- **WebMCP** — `wu.ai.expose()` registers tools via `navigator.modelContext` (Chrome 146+)
+- **MCP Server** — Connect Claude Code, Cursor, or any MCP client to your live app
+- **4-Layer Security** — Permissions, rate limiting, circuit breaker, loop protection
+- **Workflows** — Reusable parameterized AI recipes
 
 ---
 
 ## Quick Start
 
-### 1. Register your micro app
+### 1. Register your micro-app
 
-**React:**
 ```jsx
+// React
 import { wuReact } from 'wu-framework/adapters/react';
-import App from './App';
 wuReact.register('orders', App);
-```
 
-**Vue:**
-```js
+// Vue
 import { wuVue } from 'wu-framework/adapters/vue';
-import App from './App.vue';
 wuVue.register('products', App);
-```
 
-**Angular (standalone component):**
-```ts
-import 'zone.js';
-import '@angular/compiler';
-import { createApplication } from '@angular/platform-browser';
-import { createComponent, provideZoneChangeDetection } from '@angular/core';
+// Angular (standalone)
 import { wuAngular } from 'wu-framework/adapters/angular';
-import { AppComponent } from './app/app.component';
+wuAngular.registerStandalone('settings', AppComponent, { createApplication, createComponent });
 
-wuAngular.registerStandalone('settings', AppComponent, {
-  createApplication,
-  createComponent,
-  provideZoneChangeDetection,
-});
-```
-
-**Svelte 5:**
-```js
+// Svelte 5
 import { wuSvelte } from 'wu-framework/adapters/svelte';
-import App from './App.svelte';
 wuSvelte.registerSvelte5('dashboard', App);
-```
-
-**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
+// Same pattern for Solid, Preact, Lit, Vanilla
 ```
 
 ### 2. Mount from the shell
@@ -141,7 +150,7 @@ await wu.init({
   apps: [
     { name: 'header',  url: 'http://localhost:3001' },
     { name: 'sidebar', url: 'http://localhost:3002' },
-    { name: 'content', url: 'http://localhost:3003' }
+    { name: 'content', url: 'http://localhost:3003' },
   ]
 });
 
@@ -150,568 +159,184 @@ await wu.mount('sidebar', '#sidebar-container');
 await wu.mount('content', '#content-container');
 ```
 
-Each app runs inside its own Shadow DOM with a JS sandbox that tracks and cleans up all side effects on unmount.
+### 3. Cross-app communication
 
----
+```js
+import { emit, on, getState, setState } from 'wu-framework';
 
-## 8 Framework Adapters
+// Events
+emit('user:login', { userId: 123 });
+on('user:*', (event) => console.log(event.data));
 
-Wu doesn't give you a generic API and tell you to figure it out. Each adapter speaks the native language of its framework.
+// Shared store
+setState('user.name', 'John');
+getState('user.name'); // 'John'
+```
 
-| 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 |
+### 4. Add AI (optional)
 
-> **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.
+```js
+wu.ai.provider('ollama', {
+  endpoint: 'http://localhost:11434/api/chat',
+  model: 'llama3',
+});
 
-Every adapter detects if Wu is present. If not, the app mounts standalone. Your microfrontend never stops working.
+const response = await wu.ai.send('What apps are mounted?');
+```
 
 ---
 
-## 3 CSS Isolation Modes
-
-This is something no other microfrontend framework offers: **per-app configurable style isolation**.
-
-| 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 |
+## WuCommerce — Real-World Example
 
-Set it in `wu.json`:
+Wu ships with **WuCommerce**, a Shopify-like merchant dashboard where every section is a real micro-app built with a different framework.
 
-```json
-{
-  "name": "my-app",
-  "entry": "index.js",
-  "styleMode": "isolated"
-}
-```
+| 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 |
 
-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.
+All 8 apps communicate through Wu's event bus and shared store. Click a customer → orders filter. Toggle theme → all 8 apps update. Change store name in settings → topbar updates.
 
 ---
 
-## JS Sandbox — Three Modes, Real Isolation
-
-Wu offers three sandbox modes. Pick the one that fits your workflow:
+## 3 Sandbox Strategies
 
 | 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) |
+| `module` (default) | `import()` + Proxy side-effect tracking | Yes | Yes | Yes | Side effects only |
+| `strict` | Hidden iframe + real `import()` | Yes | Yes | Yes | **Full** (separate window) |
+| `eval` | Fetch HTML → parse → `with(proxy){}` | No | No | No | **Full** (proxy traps) |
 
 ```js
-// Global setting
-await wu.init({
-  sandbox: 'strict',  // or 'module' (default) or 'eval'
-  apps: [...]
-});
-
-// 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
+    { name: 'header',    url: '...', sandbox: 'module' },
+    { name: 'analytics', url: '...', sandbox: 'strict' },
+    { name: 'legacy',    url: '...', sandbox: 'eval' },
   ]
 });
 ```
 
-**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.
+**Auto-cleaned on unmount:** timers, intervals, rAF, event listeners, localStorage keys, DOM mutations.
 
-**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.
+---
 
-**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.
+## 3 CSS Isolation Modes
 
-### How strict mode works
+| Mode | What happens | When to use |
+|------|-------------|-------------|
+| `shared` | Host styles injected into Shadow DOM | Apps sharing a design system (Tailwind) |
+| `isolated` | Pure Shadow DOM — no external styles | Fully independent apps |
+| `fully-isolated` | Only the app's own styles | Apps that need their CSS but not global CSS |
 
+```json
+{ "name": "my-app", "entry": "index.js", "styleMode": "isolated" }
 ```
-┌── 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
-
-**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}_`
-
-**277 tests verify this works.** Unit tests for every isolation feature, integration tests proving two sandboxes don't contaminate each other.
 
 ---
 
-## Cross-App Communication
+## AI Paradigms
 
-### Event Bus
+### 1. App → LLM → App
 
 ```js
-import { emit, on, once, off } from 'wu-framework';
-
-emit('user:login', { userId: 123 });
-
-const unsub = on('user:*', (event) => {
-  console.log(event.name, event.data);
-});
-
-once('app:ready', (e) => console.log('Ready'));
-unsub();
+const response = await wu.ai.send('What items are in the cart?');
 ```
 
-Features: wildcard patterns (`user:*`, `*.error`, `app.*.ready`), event replay for late-joining apps, strict mode (only registered apps can emit), history buffer.
-
-### Store
+### 2. LLM → App → LLM (WebMCP)
 
 ```js
-import { getState, setState, onStateChange } from 'wu-framework';
-
-setState('user.name', 'John');
-setState('user.preferences.theme', 'dark');
-
-getState('user.name');  // 'John'
-
-const unsub = onStateChange('user.*', (value, path) => {
-  console.log(`${path} = ${value}`);
-});
-
-// Batch updates
-wu.store.batch({ 'cart.count': 5, 'cart.total': 99.99 });
-```
-
-Ring buffer event history. Wildcard subscriptions. Dot-notation paths with auto-creation of nested objects.
-
----
-
-## Framework-Native Integration Examples
-
-> 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.
-
-### React — Orders (mf-eventlab)
-
-```jsx
-// main.jsx
-import { wuReact } from 'wu-framework/adapters/react';
-import App from './App';
-wuReact.register('orders', App);
-
-// 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';
-
-const useWuEvents = createUseWuEvents(React);
-const useWuStore = createUseWuStore(React);
-
-function Orders() {
-  const { emit, on } = useWuEvents();
-  const [filter, setFilter] = useState('all');
-
-  useEffect(() => {
-    const unsub = on('customer:selected', (e) => {
-      setFilter(e.data?.customerName || 'all');
-    });
-    return unsub;
-  }, []);
-
-  return <button onClick={() => emit('order:new', { id: 1001, total: 49.99 })}>New Order</button>;
-}
-```
-
-### Vue 3 — Products (mf-statebridge)
-
-```vue
-<!-- main.js -->
-<!-- import { wuVue } from 'wu-framework/adapters/vue'; -->
-<!-- import App from './App.vue'; -->
-<!-- wuVue.register('products', App); -->
-
-<script setup>
-import { ref, computed, onMounted, onUnmounted } from 'vue';
-import { wuVue } from 'wu-framework/adapters/vue';
-
-const { useWuEvents, useWuStore } = wuVue;
-const events = useWuEvents();
-
-onMounted(() => {
-  events.on('search:global', (e) => {
-    search.value = e.data?.query || '';
-  });
-});
-
-function handleStockAlert(product) {
-  events.emit('product:stockAlert', { productId: product.id, stock: product.stock });
-}
-
-onUnmounted(() => events.cleanup());
-</script>
+wu.ai.expose(); // Registers all tools via navigator.modelContext (Chrome 146+)
 ```
 
-### Svelte 5 — Dashboard (mf-hero)
-
-```svelte
-<!-- main.js: wuSvelte.registerSvelte5('dashboard', App) -->
-<script>
-  import { wuSvelte } from 'wu-framework/adapters/svelte';
-
-  const { createWuStore, createWuEventStore, useWuEvents } = wuSvelte;
-  const { emit, on, cleanup } = useWuEvents();
-
-  let stats = $state({ revenue: 12847, orders: 156, visitors: 2341, conversion: 4.2 });
-
-  on('theme:toggle', (e) => console.log('Theme:', e.data?.theme));
-
-  function handleNewOrder() {
-    emit('order:new', { orderId: `ORD-${Date.now()}`, total: 49.99, status: 'pending' });
-  }
-
-  // cleanup is called automatically on component destroy
-</script>
-```
-
-### Solid.js — Customers (mf-features)
-
-```jsx
-// main.jsx: wuSolid.register('customers', App)
-import { createSignal, onMount } from 'solid-js';
-import { wuSolid } from 'wu-framework/adapters/solid';
-
-export default function Customers() {
-  const [search, setSearch] = createSignal('');
-  const { emit, on } = wuSolid.useWuEvents(); // auto-cleanup via onCleanup
-
-  onMount(() => {
-    on('search:global', (e) => setSearch(e.data?.query || ''));
-  });
-
-  const handleRowClick = (customer) => {
-    emit('customer:selected', { customerId: customer.id, customerName: customer.name });
-    emit('nav:section', { section: 'orders' });
-  };
-
-  return <div>...</div>;
-}
-```
-
-### Preact — Topbar (mf-header)
-
-```jsx
-// main.jsx: wuPreact.register('topbar', App)
-import { useState, useCallback, useEffect, useRef } from 'preact/hooks';
-import { wuPreact } from 'wu-framework/adapters/preact';
-
-// Factory pattern — pass hooks as argument
-const useWuEvents = wuPreact.createUseWuEvents({ useCallback, useEffect, useRef });
-const useWuStore = wuPreact.createUseWuStore({ useState, useCallback, useEffect });
-
-function Topbar() {
-  const { emit, on } = useWuEvents();
-  const storeData = useWuStore('store');
-
-  const handleSearch = (query) => emit('search:global', { query });
-  const toggleTheme = () => emit('theme:toggle', { theme: isDark ? 'light' : 'dark' });
-
-  return <header>...</header>;
-}
-```
-
-### Angular 21 — Settings (mf-pluginperf)
-
-```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';
-
-wuAngular.registerStandalone('settings', SettingsComponent, {
-  standaloneContainer: '#app',
-  createApplication,          // pass Angular APIs to avoid bundler issues
-  createComponent,
-  provideZoneChangeDetection,
-});
-
-// settings.component.ts — use createWuService for events/store
-import { Component, OnInit, OnDestroy } from '@angular/core';
-import { createWuService } from 'wu-framework/adapters/angular';
-
-@Component({ selector: 'app-settings', standalone: true, template: '...' })
-export class SettingsComponent implements OnInit, OnDestroy {
-  private wu = createWuService();
-  storeName = '';
-
-  ngOnInit() {
-    this.storeName = this.wu.getState('store')?.name || '';
-    this.wu.on('theme:toggle', (e) => console.log('Theme:', e.data?.theme));
-  }
-
-  save() {
-    this.wu.setState('store', { name: this.storeName });
-    this.wu.emit('settings:saved', { name: this.storeName });
-  }
-
-  ngOnDestroy() { this.wu.destroy(); }
-}
-```
-
-> **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`.
-
-### Lit — Analytics (mf-showcase)
+### 3. Autonomous Agent
 
 ```js
-// main.js: wuLit.register('analytics', AnalyticsApp)
-import { LitElement, html, css } from 'lit';
-import { WuMixin } from 'wu-framework/adapters/lit';
-
-class AnalyticsApp extends WuMixin(LitElement) {
-  static styles = css`...`;
-
-  connectedCallback() {
-    super.connectedCallback();
-    this.wuOn('theme:toggle', () => this.requestUpdate());
-    const stats = this.wuGetState('stats');
-  }
-
-  render() {
-    return html`
-      <button @click=${() => this.wuEmit('analytics:export')}>Export</button>
-    `;
-  }
+for await (const step of wu.ai.agent('Find the top customer and show their profile')) {
+  console.log(`Step ${step.step}: ${step.content}`);
 }
-customElements.define('analytics-app', AnalyticsApp);
 ```
 
-### Vanilla JS — Chat Widget (mf-sandbox)
+### 4. Cross-App Orchestration
 
 ```js
-// main.js — default import
-import wuVanilla from 'wu-framework/adapters/vanilla';
-
-const { useWuEvents, useWuStore } = wuVanilla;
-const events = useWuEvents();
-const store = useWuStore();
-
-function mount(container) {
-  events.on('theme:toggle', (e) => applyTheme(e.data?.theme));
-  const user = store.get('user');
-  // render chat UI into container...
-}
-
-function unmount(container) {
-  events.cleanup();
-  container.innerHTML = '';
-}
+const result = await wu.ai.intent('Find customer Emma and refund order #4821');
+console.log(result.appsInvolved); // ['customers', 'orders']
 ```
 
 ---
 
-## Plugins & Lifecycle Hooks
+## Plugins & Hooks
 
 ```js
-import { usePlugin, createPlugin, useHook, createGuardHook } from 'wu-framework';
+import { usePlugin, createPlugin, useHook } from 'wu-framework';
 
-// Plugin
 usePlugin(createPlugin({
   name: 'analytics',
   install: (api) => api.on('app:mounted', (e) => track(e)),
   afterMount: async (ctx) => log('mounted in', ctx.mountTime, 'ms')
 }));
 
-// Lifecycle hook
 useHook('beforeMount', async (context, next) => {
   console.log('Mounting:', context.appName);
   await next();
 });
-
-// Guard — can cancel mount
-useHook('beforeMount', createGuardHook(async () => isAuthenticated()));
 ```
 
 Phases: `beforeInit` → `afterInit` → `beforeLoad` → `afterLoad` → `beforeMount` → `afterMount` → `beforeUnmount` → `afterUnmount`
 
 ---
 
-## Loading Strategies
-
-```js
-await wu.init({
-  apps: [
-    { name: 'header',    url: '/mfe/header',    strategy: 'eager' },
-    { name: 'content',   url: '/mfe/content',   strategy: 'lazy' },
-    { name: 'analytics', url: '/mfe/analytics', strategy: 'idle' }
-  ]
-});
-```
-
-| Strategy | Behavior |
-|----------|----------|
-| `lazy` | Load when mounted (default) |
-| `eager` | Load immediately |
-| `preload` | `<link rel="prefetch">` |
-| `idle` | `requestIdleCallback` |
-| `speculate` | Speculation Rules API with automatic fallback chain |
-
----
-
-## Intelligent Prefetch (Speculation Rules API)
-
-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.
-
-### Fallback chain
-
-```
-Speculation Rules API  →  <link rel="modulepreload">  →  <link rel="prefetch">
-   (Chrome 121+)            (modern browsers)              (all browsers)
-```
-
-### Usage
+## Prefetch (Speculation Rules API)
 
 ```js
-// Prefetch specific apps
 wu.prefetch(['sidebar', 'analytics']);
-
-// Prefetch all registered apps
+wu.prefetch(['sidebar'], { trigger: 'hover', action: 'prerender' });
 wu.prefetchAll();
-
-// With options
-wu.prefetch(['sidebar'], {
-  trigger: 'hover',      // 'immediate' | 'hover' | 'visible' | 'idle'
-  action: 'prefetch',    // 'prefetch' | 'prerender'
-  eagerness: 'moderate', // 'immediate' | 'eager' | 'moderate' | 'conservative'
-});
 ```
 
-### Triggers
-
-| 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`) |
-
-### 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' },
-  ]
-});
-```
-
-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+.
+Fallback chain: Speculation Rules API (Chrome 121+) → `<link rel="modulepreload">` → `<link rel="prefetch">`
 
 ---
 
-## Cookie Overrides for QA/Testing
-
-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.
-
-### How it works
-
-```
-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
-```
-
-### Programmatic API
+## Cookie Overrides for QA
 
 ```js
-// Set an override (persists as cookie for 24h)
 wu.override('sidebar', 'http://localhost:5174');
-
-// Check active overrides
-wu.getOverrides();
-// → { sidebar: 'http://localhost:5174' }
-
-// Remove one
+wu.getOverrides();   // { sidebar: 'http://localhost:5174' }
 wu.removeOverride('sidebar');
-
-// Clear all
-wu.clearOverrides();
 ```
 
-### Security model (3 layers)
-
-| 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. |
-
-### Enable in production (for QA teams)
-
-```js
-wu.overrides.configure({
-  enabled: true,
-  allowedDomains: ['*.mycompany.com', 'localhost', '*.vercel.app'],
-  showIndicator: true,
-});
-```
+QA sets a cookie → only **their browser** sees the override. Everyone else sees production. 3-layer security: environment gate, domain allowlist, visual indicator.
 
-### Cookie format
-
-```
-wu-override:<appName>=<url>
+---
 
-# Examples:
-wu-override:sidebar=http://localhost:5174
-wu-override:header=https://staging.mycompany.com/header
-```
+## Project Stats
 
-No proxy. No server changes. Pure client-side URL substitution at init time.
+| Metric | Value |
+|---|---|
+| Source files | 79 |
+| Lines of code | 23,442 |
+| Test cases | **650** |
+| Framework adapters | 8 |
+| AI modules | 12 |
+| Core modules | 23 |
+| Runtime dependencies | **0** |
+| Bundle (ESM, minified) | ~174 KB |
 
 ---
 
-## Build & Test
+## Build
 
 ```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           # 650 tests (Vitest)
 npm run test:coverage  # Coverage report
 ```
 
@@ -728,80 +353,56 @@ npm run test:coverage  # Coverage report
 
 ```
 ┌───────────────────────────────────────────────────────────────────────┐
-│                       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              │
-└───────────────────────────────────────────────────────────────────────┘
+│                       SHELL (any framework)                          │
+├──────────┬──────────┬──────────┬──────────┬──────────┬───────────────┤
+│ 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             │
+├──────────────────────────────────────────────────────────────────────┤
+│                       WU AI (BYOL)                                   │
+│  Provider · Actions · Agent · Orchestrate · Triggers · Context       │
+│  Browser Actions · WebMCP · MCP Server · Workflows · Security        │
+└──────────────────────────────────────────────────────────────────────┘
 ```
 
-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.
-
 ---
 
-## API Reference
-
-```js
-// Core
-import { wu, init, mount, unmount, destroy, app, define } from 'wu-framework';
-
-// Events
-import { emit, on, once, off } from 'wu-framework';
+## Documentation
 
-// State
-import { getState, setState, onStateChange } from 'wu-framework';
+Full documentation at **[wu-framework.dev](https://wu-framework.dev)**
 
-// Plugins & Hooks
-import { usePlugin, createPlugin, useHook } from 'wu-framework';
-import { createGuardHook, createTimedHook, createTransformHook } from 'wu-framework';
+- [Quick Start](https://wu-framework.dev/docs/quick-start) — Get running in 5 minutes
+- [Getting Started](https://wu-framework.dev/docs/getting-started) — Deeper tutorial with cross-app communication
+- [API Reference](https://wu-framework.dev/docs/core/api) — Full API docs
+- [Event Bus](https://wu-framework.dev/docs/core/event-bus) — Inter-app communication
+- [Shared Store](https://wu-framework.dev/docs/core/store) — Cross-app reactive state
+- [Sandbox](https://wu-framework.dev/docs/core/sandbox) — JS isolation strategies
+- [AI Overview](https://wu-framework.dev/docs/ai/overview) — 4 AI paradigms
+- [AI Actions](https://wu-framework.dev/docs/ai/actions) — Register tools for the LLM
+- [Browser Actions](https://wu-framework.dev/docs/ai/browser-actions) — 10 built-in browser tools
+- [MCP Server](https://wu-framework.dev/docs/ai/mcp-server) — Connect AI agents to live apps
+- [CSS Isolation](https://wu-framework.dev/docs/guides/css-isolation) — Shadow DOM style modes
+- [Deployment](https://wu-framework.dev/docs/guides/deployment) — Production deployment guide
 
-// Performance
-import { startMeasure, endMeasure, generatePerformanceReport } from 'wu-framework';
+---
 
-// Prefetch (Speculation Rules API)
-import { prefetch, prefetchAll } from 'wu-framework';
+## Browser Support
 
-// Overrides (QA/Testing)
-import { override, removeOverride, getOverrides, clearOverrides } from 'wu-framework';
+Chrome 80+, Firefox 78+, Safari 14+, Edge 80+. Shadow DOM v1 required.
 
-// 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 { wuVanilla } from 'wu-framework/adapters/vanilla';
+## Contributing
 
-// Prefetch
-wu.prefetch(['sidebar', 'analytics']);
-wu.prefetch(['sidebar'], { trigger: 'hover' });
-wu.prefetchAll();
-
-// Overrides (QA)
-wu.override('sidebar', 'http://localhost:5174');
-wu.removeOverride('sidebar');
-wu.getOverrides();
-wu.clearOverrides();
-wu.overrides.configure({ enabled: true, allowedDomains: ['*.company.com'] });
-
-// Log control
-wu.silence();
-wu.verbose();
-```
-
----
+Contributions welcome. Please open an issue first to discuss what you'd like to change.
 
 ## License
 
-MIT
+[MIT](./LICENSE) — Free for personal and commercial use.
+
+See [LICENSE-COMMERCIAL.md](./LICENSE-COMMERCIAL.md) for optional enterprise support and consulting.