# Public reference

Look up imports, parameters, returns, and examples for composition, communication, state, and extension APIs.

See versions, changes and requirements in [Framework 4.0 and CLI 1.2](/docs/guides/releases/).


<span id="import-principal"></span>

<span class="section-anchor" id="section-1"></span>

## Main import

```js
import { wu } from 'wu-framework';
// Equivalente para el singleton:
// import wu from 'wu-framework';
```

The package defines ESM, CommonJS, and UMD entrypoints. Adapter, integration, server, sandbox, and AI subpaths are declared in `package.json`. Importing an unexported internal path is outside the distribution contract.

<span id="core-y-lifecycle"></span>

<span class="section-anchor" id="section-2"></span>

## Core and lifecycle

| API | Input / return | Usage |
| --- | --- | --- |
| `wu.init(config)` | Object with `apps`; `Promise<void>` | Initialize once |
| `wu.whenReady()` | `Promise<boolean>` | Await an in-flight init |
| `wu.define(name, lifecycle)` | Required `mount` | Register implementation |
| `wu.mount(name, selector)` | String selector; promise | Mount into a node accessible through `document.querySelector` |
| `wu.unmount(name, options?)` | `{ force?, keepAlive? }`; promise | Release or hide |
| `wu.update(name, props)` | Record; `Promise<boolean>` | Live props |
| `wu.hide(name)` / `show(name)` | Promises | Preserve/reactivate an app |
| `wu.isHidden(name)` | Boolean | Keep-alive state |
| `wu.destroy()` | Promise | Release the entire runtime |
| `wu.app(name, config)` | `WuApp` | Reusable identity and configuration; registers on mount |

The exported `init(apps)` helper **takes the array**, whereas `wu.init({ apps })` takes the object. Their syntax is not interchangeable. The exported `mount`, `unmount`, `define`, `app`, `hide`, `show`, `isHidden`, and `destroy` helpers delegate to the singleton.

<span id="inicialización-tipada"></span>

<span class="section-anchor" id="section-3"></span>

### Typed initialization

```ts
import { wu, type WuAppConfig } from 'wu-framework';

const catalog: WuAppConfig = {
  name: 'catalog',
  url: '/apps/catalog',
  grants: [{ capability: 'store.read', resource: 'catalog' }],
};

await wu.init({ apps: [catalog], sandbox: 'module' });
await wu.mount(catalog.name, '#catalog-slot');
// Al retirar este consumidor del shell:
await wu.unmount(catalog.name);
```

The slot must exist before `mount`; the manifest must declare the same identity and request resources the app will use. `unmount` releases a reference and applies keep-alive rules; `{ force: true }` requests full unmounting.

<span id="comunicación"></span>

<span class="section-anchor" id="section-4"></span>

## Communication

| Singleton/facade API | Return |
| --- | --- |
| `emit(event, data, opts?)` | Acceptance boolean |
| `on(event, callback)` | Unsubscribe function |
| `once(event, callback)` | Unsubscribe function |
| `off(event, callback)` | Bus boolean |
| `request(channel, data, opts?)` | Response promise |
| `handle(channel, handler)` | Release function; options on eventBus/facade |
| `provide(name, impl, opts?)` | Handle with `revoke()` |
| `consume(name, range?, opts?)` | Proxy; promise if `wait: true` |

`WuEvent` contains `name`, `data`, `timestamp`, `appName`, `meta`, and `verified`. `WuRpcOptions` accepts `timeout`, `signal`, `version`, and `range`; `WuRpcHandleOptions` accepts `version`, `allow`, and `replace`.

`request` and `handle` are methods of `wu`, `wu.eventBus`, and the facade; they are not exported as standalone functions from the main package. `emit`, `on`, `once`, `off`, `provide`, and `consume` also exist as exported helpers.

`wu.handle(channel, handler, options)` preserves `version`, `allow` and `replace`. Inside the lifecycle, `context.wu.handle` also adds the app’s identity and grants; use that facade for microapp handlers.

<span id="elegir-evento-o-petición"></span>

<span class="section-anchor" id="section-5"></span>

### Choose an event or a request

```js
const unsubscribe = wu.on('catalog:selected', (event) => {
  console.log(event.data.productId);
});
wu.emit('catalog:selected', { productId: 'p-42' });

const stopLookup = wu.handle('catalog:lookup', ({ productId }) => {
  return { productId, available: true };
});
const result = await wu.request('catalog:lookup', { productId: 'p-42' });
console.log(result.available);

unsubscribe();
stopLookup();
```

The event callback receives a `WuEvent` envelope; the RPC handler receives the request payload directly. Keep unsubscribe functions in the lifecycle that installed each listener/provider. Inside an application, use `context.wu` with the corresponding grants.

<span class="section-anchor" id="section-6"></span>

## Store

| Method | Returns / notes |
| --- | --- |
| `get(path?)` / `getSnapshot(path?)` | Detached snapshot; object identity is not stable between reads |
| `set(path, value)` | Sequence number |
| `update(path, updater)` | Number; synchronous updater |
| `on(pattern, callback)` | Cleanup; different payload for wildcard |
| `batch(record)` | Array of sequence numbers; preflight for all entries |
| `tap(fn)` | Cleanup; observes synchronous commits |
| `hydrate(state, options?)` | Replaces state with notification options |
| `sync(options?)` | Handle with `ready`, `stop`, `status` |
| `getMetrics()` | Store counters |
| `reset()` / `dispose()` / `clear()` | Store lifecycle operations; not a persistence API |

The root export `store` points to `wu.store`. The `getState`, `setState`, `onStateChange`, and `syncStore` helpers use that same instance. `new WuCore()` creates its own store by default; the constructor allows another store to be injected for intentional composition.

<span id="inspección-rendimiento-y-extensiones"></span>

<span class="section-anchor" id="section-7"></span>

## Inspection, performance, and extensions

| API | Function |
| --- | --- |
| `wu.inspect({ events? })` | Snapshot of apps, state, and diagnostics |
| `wu.getAppInfo(name)` | Registered app information |
| `wu.getSandboxInfo(name)` | Requested/actual mode and ownership |
| `wu.getManifestDiagnostics()` | Invalid declarative dependencies |
| `wu.getStats()` | Operational summary |
| `wu.showInspector()` / `hideInspector()` | Inspection UI loaded on demand |
| `wu.performance.startMeasure(name, app?)` | Start measurement |
| `wu.performance.endMeasure(name, app?)` | Finish and return duration |
| `wu.performance.generateReport()` | Measurement report |
| `wu.prefetch` / `prefetchAll` | Preload resources |
| `wu.use('app.component')` | Load the default export or namespace declared in `wu.exports`; see the type note |
| `wu.override` / `removeOverride` / `getOverrides` / `clearOverrides` | URL replacement |
| `wu.pluginSystem.use(plugin, options)` | Asynchronous installation |
| `wu.hooks.use(phase, middleware, options?)` | Lifecycle middleware |
| `wu.aiReady()` / `timelineReady()` | Load a deferred subsystem |

Exported classes include `WuCore`, `WuCompatibility`, `WuLoader`, `WuSandbox`, `WuManifest`, `WuStore`, `WuApp`, `WuStyleBridge`, `WuCache`, `WuEventBus`, `WuPerformance`, `WuProxySandbox`, `WuPluginSystem`, `WuLoadingStrategy`, `WuPrefetch`, `WuOverrides`, `WuErrorBoundary`, `WuContracts`, and `WuLifecycleHooks`. Using a low-level class directly requires configuring its guarantees: `new WuEventBus()` starts permissive; `wu.init()` enables strict mode for the core bus.

<span id="tipos-que-conviene-conocer"></span>

<span class="section-anchor" id="section-8"></span>

## Types to know

`WuAppConfig` describes host configuration. `WuLifecycle` and `WuAppLifecycleContext` describe mounting. `WuAppFacade`/`WuScopedStore` describe app authority. `WuPermissionRequest`, `WuCapabilityGrant`, and `WuCompiledPolicy` describe policy. `WuSyncHandle`, `WuTimelineFacade`, and `WuInspectSnapshot` describe optional subsystems.

<span id="compatibilidad-de-las-declaraciones-typescript"></span>

<span class="section-anchor" id="section-9"></span>

### TypeScript declaration compatibility

The following details help you write valid inputs and correctly consume return values, even where the type declaration does not express the entire contract:

- `resource?` in requests/grants is typed as optional, but the parser requires the property.
- The input union permits a capability alone; the string parser requires `capability:resource`.
- `strategy` and `fullBleed` are read at runtime but are missing from `WuAppConfig`.
- `wu.use` exists in the core but is missing from the public `WuCore` declaration.
- `WuLifecycleHooks.use` is declared to return `void`, although the implementation returns a cleanup function.
- The generic store signature does not correctly express the wildcard envelope.
- The host type offers `styleMode`; configure the effective value in the manifest.

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-10"></span>

## Implementation references

Actual exports: `src/index.js`; helpers: `src/index.js`; public types: `src/index.d.ts`, `src/index.d.ts`, `src/index.d.ts`, `src/index.d.ts`; subpaths: `package.json`. Tests: `tests/unit/package-exports.test.js`, `tests/unit/adapter-conformance.test.js`, `tests/unit/store-subscription-semantics.test.js`.

<span id="apis-de-la-versión-32"></span>

<span class="section-anchor" id="section-11"></span>

## Version 3.2 APIs

The catalog includes declared manifests, focus, transitions, windows, drag and drop, shadow deployment, ports and installable apps. The [upgrade walkthroughs](/docs/guides/releases/) link complete contracts, optional imports and error handling. Earlier state, event, AI and lifecycle APIs remain in their respective references.

See [supervision, recovery and replay](/docs/framework/runtime-reliability/) for `superviseApp`, `createReplaySession` and the scoped `reportError`, `now` and `random` methods.

The optional `ai`, `timeline`, `devtools`, `mcp`, `store-sync`, `shadow`, `windows`, `dnd`, `ports`, `wuapp`, `sandbox/iframe` and `sandbox/html-parser` entries have public declarations. `typesVersions` also resolves them with `moduleResolution: "node10"`. Import types from published subpaths, not internal files.