# Composition and permission reference Contracts for instances, principals, manifests, facades, and wrappers, with parameters and distribution differences. See versions, changes and requirements in [Framework 4.0 and CLI 1.2](/docs/guides/releases/). This reference gathers the APIs the host uses to configure identity and authority. Examples use `wu` imported from `wu-framework`; an object named `manifests` is created with `new WuManifest()`. ## Distribution and receiver The singleton has host authority. The `context.wu` facade is received through lifecycle and grants only the intersection of manifest requests and host grants. Principal roles control interface access; server data authorization is checked on the server. ## Preparing a wrapper around a registered app ```js import { wu, WuManifest } from 'wu-framework'; const manifests = new WuManifest(); await wu.init({ apps: [{ name: 'widget', url: '/apps/widget' }] }); const widget = wu.app('widget', { url: '/apps/widget', container: '#widget-slot', }); await widget.mount(); ``` The target must exist in the document. Wrapper entries describe its runtime methods; the WuApp TypeScript declaration lists only some. Creating another wrapper does not replace an existing registration's grants. ## wu.app Creates a reusable object preserving a microapp's identity and configuration. `wu.app(name: string, config: Partial): WuApp` - name and config.url; container accepts a string selector or, since 3.2, an HTMLElement. Other fields belong to the host. - **Returns:** WuApp with registration deferred until `mount()`. - **Errors:** Mounting propagates manifest, permission, loading and container failures. - **Permissions:** The wrapper preserves host configuration and grants and registers through the core. - **Cleanup:** unmount removes the renderer; wrapper destroy does not clear every manifest registration. ```js const catalog = wu.app('catalog', { url: '/apps/catalog', container: '#catalog-slot', }); console.log(catalog.info); ``` Reference: `src/index.js`. ## new WuCore Creates an instance with its own store or one deliberately injected. `new WuCore(options?): WuCore` - **Parameters:** Optional store, storeBufferSize, and compatibility. - **Returns:** Independent instance; the wu import remains the singleton. - **Errors:** Does not start apps; option/compatibility errors propagate. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** await runtime.destroy() when removing the instance. ```js import { WuCore, WuStore } from 'wu-framework'; const runtime = new WuCore({ store: new WuStore(512) }); ``` Reference: `src/core/wu-core.js`. ## wu.setPrincipal Sets the principal used by mount access control. `wu.setPrincipal(principal | null): object | null` - **Parameters:** role, roles, and permissions such as mount:catalog or mount:*; null clears identity. - **Returns:** The same principal or null; projects auth.principal and reports the change. - **Errors:** A failed store write does not roll back the principal. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** wu.setPrincipal(null) when the session ends. ```js wu.setPrincipal({ roles: ['catalog-reader'] }); ``` Reference: `src/core/wu-core.js`. ## wu.getPrincipal Reads the current principal used by the host. `wu.getPrincipal(): object | null` - **Parameters:** No arguments. - **Returns:** Principal reference, or null. - **Errors:** Does not validate the session or query the server. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js console.log(wu.getPrincipal()?.roles); ``` Reference: `src/core/wu-core.js`. ## wu.can Checks whether the principal satisfies an application's roles. `wu.can(appName: string): boolean` - **Parameters:** Registered name; queries normalized manifest roles. - **Returns:** Boolean; apps without roles are considered public. - **Errors:** Does not check entrypoint existence or grant store/bus capabilities. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js if (wu.can('catalog')) await wu.mount('catalog', '#catalog-slot'); ``` Reference: `src/core/wu-core.js`. ## context.wu Provides each lifecycle with revocable application authority. `mount(container, context: { appName, wu: WuAppFacade }): void | Promise` - **Parameters:** The core supplies context; a facade cannot be constructed from a name. - **Returns:** Frozen facade with events, RPC, contracts, and restricted store. - **Errors:** WU_APP_SCOPE_REVOKED after teardown; WU_CAPABILITY_DENIED when accessing resources without a grant. - **Permissions:** Intersection of manifest.wu.permissions and config.grants; does not expose init, destroy, or global administration. - **Cleanup:** Release your own work in unmount; do not reuse the facade afterward. ```js wu.define('catalog', { mount(container, { wu: appWu }) { container.textContent = String(appWu.store.get('catalog.count') ?? 0); }, }); ``` Reference: `src/core/wu-core.js`. ## new WuManifest Creates a manifest reader and validator with its own cache. `new WuManifest(): WuManifest` - **Parameters:** No required arguments. - **Returns:** Instance for load, validate, create, and clearCache. - **Errors:** Does not grant permissions or register apps in a core. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** clearCache() discards cached manifests. ```js import { WuManifest } from 'wu-framework'; const manifests = new WuManifest(); ``` Reference: `src/core/wu-manifest.js`. ## WuManifest.load Downloads and normalizes wu.json from an app's base URL. `manifests.load(appUrl, { expectedName? }?): Promise` - **Parameters:** appUrl: public base; expectedName binds registration identity. - **Returns:** Normalized manifest; a real 404 uses the default manifest. - **Errors:** WU_MANIFEST_LOAD_FAILED, WU_MANIFEST_INVALID, and WU_MANIFEST_NAME_MISMATCH; network/HTML/500 failures are not defaults. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** clearCache(base) when you need to discard the read. ```js const manifest = await manifests.load('/apps/catalog', { expectedName: 'catalog' }); ``` Reference: `src/core/wu-manifest.js`. ## WuManifest.validate Validates structure, limits, paths, and declarative permissions without granting them. `manifests.validate(manifest, { expectedName? }?): object` - **Parameters:** Your own data object; resource is required in object declarations. - **Returns:** Normalized manifest with frozen snapshots. - **Errors:** WU_MANIFEST_INVALID or identity differing from expectedName. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js const manifest = manifests.validate({ name: 'catalog', entry: 'entry.js', wu: { permissions: [] } }); ``` Reference: `src/core/wu-manifest.js`. ## WuManifest.create Produces a manifest from an identity and declarative configuration. `manifests.create(name, config?): object` - **Parameters:** name; config.entry (index.js by default), exports, imports, permissions, roles, metadata, styleMode, version, and folder. Nonempty routes are invalid in wu.routes. - **Returns:** Constructed and validated manifest. - **Errors:** The same structural constraints as validate. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js const manifest = manifests.create('catalog', { entry: 'entry.js' }); ``` Reference: `src/core/wu-manifest.js`. ## WuManifest.clearCache Discards stored manifests so they can be downloaded again. `manifests.clearCache(pattern?): void` - **Parameters:** Regular expression string; without a pattern, clears this instance's entire cache. - **Returns:** void. - **Errors:** An invalid RegExp pattern warns and removes no entries; does not alter compiled core registrations. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js manifests.clearCache('/apps/catalog'); ``` Reference: `src/core/wu-manifest.js`. ## wu.compatibility.configure Configures limited migration bridges between strict and compat-v2 profiles. `wu.compatibility.configure(config): WuCompatibility` - **Parameters:** profile, warnings, and ai/plugins/apps/sync options; not an additional sandbox. - **Returns:** The same instance. - **Errors:** Unknown configuration or feature may throw. - **Permissions:** Host only; each bridge must be explicitly enabled. - **Cleanup:** Creates no resources requiring release. ```js wu.compatibility.configure({ profile: 'strict', warnings: 'once' }); ``` Reference: `src/core/wu-compatibility.js`. ## wu.compatibility.getConfig Queries the effective profile and its migration bridges. `wu.compatibility.getConfig(): object` - **Parameters:** No arguments. - **Returns:** Compatibility configuration. - **Errors:** Does not establish whether a consumer is using a bridge. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js console.log(wu.compatibility.getConfig()); ``` Reference: `src/core/wu-compatibility.js`. ## wu.compatibility.getMigrationReport Reads accumulated compatibility-use warnings. `wu.compatibility.getMigrationReport(): object[]` - **Parameters:** No arguments. - **Returns:** Entries with code, message, count, and times. - **Errors:** Records only instrumented usage; not a static analysis of your apps. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js console.table(wu.compatibility.getMigrationReport()); ``` Reference: `src/core/wu-compatibility.js`. ## wu.compatibility.clearMigrationReport Resets the migration warning log. `wu.compatibility.clearMigrationReport(): void` - **Parameters:** No arguments. - **Returns:** void. - **Errors:** Does not change compatibility options. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js wu.compatibility.clearMigrationReport(); ``` Reference: `src/core/wu-compatibility.js`. ## WuApp.mount Mounts the wrapper identity and remembers the selector. `widget.mount(target?: string | HTMLElement): Promise` - **Parameters:** Optional selector; uses config.container when omitted. - **Returns:** Promise - **Errors:** Propagates registration/mount failures; missing visibility methods warn without mounting. - **Permissions:** Authority of the core owning the wrapper. - **Cleanup:** Balance with widget.unmount(). ```js await widget.mount('#widget-slot'); ``` Reference: `src/core/wu-app.js`. ## WuApp.unmount Releases the wrapper reference or preserves keep-alive. `widget.unmount(options?: { force?: boolean; keepAlive?: boolean }): Promise` - **Parameters:** force removes completely; keepAlive preserves DOM. - **Returns:** Promise - **Errors:** Propagates registration/mount failures; missing visibility methods warn without mounting. - **Permissions:** Authority of the core owning the wrapper. - **Cleanup:** Calls renderer unmount when appropriate. ```js await widget.unmount({ force: true }); ``` Reference: `src/core/wu-app.js`. ## WuApp.hide Hides an instance retained by the wrapper. `widget.hide(): Promise` - **Parameters:** No arguments; requires a mounted instance. - **Returns:** Promise - **Errors:** Propagates registration/mount failures; missing visibility methods warn without mounting. - **Permissions:** Authority of the core owning the wrapper. - **Cleanup:** deactivate must pause your own timers. ```js await widget.hide(); ``` Reference: `src/core/wu-app.js`. ## WuApp.show Reactivates the wrapper's keep-alive instance. `widget.show(): Promise` - **Parameters:** No arguments; requires hidden state. - **Returns:** Promise - **Errors:** Propagates registration/mount failures; missing visibility methods warn without mounting. - **Permissions:** Authority of the core owning the wrapper. - **Cleanup:** Finish with unmount afterward. ```js await widget.show(); ``` Reference: `src/core/wu-app.js`. ## WuApp.remount Forces unmount, then mounts again at the chosen target. `widget.remount(target?: string | HTMLElement): Promise` - **Parameters:** Optional selector; retains the last target. - **Returns:** Promise - **Errors:** Propagates registration/mount failures; missing visibility methods warn without mounting. - **Permissions:** Authority of the core owning the wrapper. - **Cleanup:** Destroys the previous renderer. ```js await widget.remount('#widget-slot'); ``` Reference: `src/core/wu-app.js`. ## WuApp.reload Clears available loader/manifest caches and mounts again. `widget.reload(): Promise` - **Parameters:** No arguments; uses the remembered target. - **Returns:** Promise - **Errors:** Propagates registration/mount failures; missing visibility methods warn without mounting. - **Permissions:** Authority of the core owning the wrapper. - **Cleanup:** Does not invalidate the browser's native ESM import cache. ```js await widget.reload(); ``` Reference: `src/core/wu-app.js`. ## WuApp.verify Inspects registration, mounting, and the slot ShadowRoot. `widget.verify(): Promise` - **Parameters:** No arguments; hasContent counts ShadowRoot children. - **Returns:** Promise - **Errors:** Propagates registration/mount failures; missing visibility methods warn without mounting. - **Permissions:** Authority of the core owning the wrapper. - **Cleanup:** Read-only; does not guarantee renderer content in light DOM. ```js console.log(await widget.verify()); ``` Reference: `src/core/wu-app.js`. ## WuApp.destroy Unmounts and removes the name from the public apps map. `widget.destroy(): Promise` - **Parameters:** No arguments. - **Returns:** Promise - **Errors:** Propagates registration/mount failures; missing visibility methods warn without mounting. - **Permissions:** Authority of the core owning the wrapper. - **Cleanup:** Does not remove every manifest registration; do not use it as general identity replacement. ```js await widget.destroy(); ``` Reference: `src/core/wu-app.js`. ## WuApp.info / isMounted / isHidden Queries a wrapper's identity, selector, and state. `widget.info; widget.isMounted; widget.isHidden` - **Parameters:** These are getters, not functions. - **Returns:** info is an object; isMounted/isHidden are state values. - **Errors:** They do not replace checking renderer content. - **Permissions:** Host only; unavailable in the application facade. - **Cleanup:** Creates no resources requiring release. ```js console.log(widget.info, widget.isMounted, widget.isHidden); ``` Reference: `src/core/wu-app.js`. See [supervision, recovery and replay](/docs/framework/runtime-reliability/) for `superviseApp`, `createReplaySession` and the scoped `reportError`, `now` and `random` methods. The first provider owns a contract name. Another app, or the host replacing an app’s contract, receives `WU_CAPABILITY_OWNED` until the owner revokes the contract or unmounts. The same owner can replace its implementation. When a `shape` exists, remote ports expose only its declared methods.