# Configuration and manifests
What the shell configures, what wu.json can declare, and how startup is validated in Framework 4.
See versions, changes and requirements in [Framework 4.0 and CLI 1.2](/docs/guides/releases/).
## Two documents with different authority
`wu.init()` configuration belongs to the shell. `wu.json` belongs to an application and is downloaded from `/wu.json`. The manifest requests resources; the shell grants the maximum authority. No manifest field can grant itself permissions.
```js
import { wu } from 'wu-framework';
await wu.init({
sandbox: 'module',
strictEvents: true,
strictFallback: false,
manifestPolicy: { imports: 'error' },
apps: [{
name: 'catalog',
url: '/apps/catalog',
framework: 'react',
container: '#catalog-slot',
keepAlive: false,
grants: [
{ capability: 'store.read', resource: 'catalog' },
{ capability: 'events.emit', resource: 'catalog:selected' },
],
}],
});
```
`container` configures a target that `wu.app()` can use. An explicit `wu.mount('catalog', '#catalog-slot')` call makes each mount's target visible.
## Global options
| Option | Initial value / behavior |
| --- | --- |
| `apps` | Configuration list with `name` and `url` |
| `sandbox` | `module`; also `strict` and `eval` |
| `strictFallback` | `false`; enabling it allows a failed strict load to fall back to eval |
| `strictEvents` | Forced to `true` on initialization unless explicitly `false` |
| `eventBus` | Bus settings; `strictEvents` takes precedence over `strictMode` |
| `manifestPolicy.imports` | `error`; also `warn` and `off` |
| `overrides` | Settings for the development URL override system |
| `compatibility` | `strict` profile or explicit migration configuration |
`init` groups concurrent calls, waits for plugin installation, registers apps, and validates imports after all registrations complete. A failed initialization rolls back registrations created in that attempt. After successful initialization, another `init` call warns and returns: it is not an API for replacing configuration live.
`whenReady()` returns a promise containing a boolean. If nobody has started WU, it returns `false`; if startup is pending, it waits for the result. `mount()` already waits for an in-flight `init`.
## A complete, valid manifest
```json
{
"name": "catalog",
"version": "1.2.0",
"entry": "assets/catalog.js",
"styleMode": "own-only",
"wu": {
"exports": { "ProductCard": "components/product-card.js" },
"imports": [],
"permissions": [
{ "capability": "store.read", "resource": "catalog", "required": true },
{ "capability": "events.emit", "resource": "catalog:selected" }
],
"roles": ["catalog-reader"]
},
"metadata": {
"description": "Explorador del catálogo",
"routes": ["/catalog", "/catalog/:id"]
}
}
```
Supported top-level fields are `name`, `entry`, `wu`, `metadata`, `styleMode`, `version`, `folder`, and `roles`. Within `wu`, recognized fields are `exports`, `imports`, `permissions`, `roles`, and the historical name `routes`, although nonempty routes there are rejected during Framework 4 normalization. Use `metadata.routes` for descriptive information.
`framework`, `sandbox`, `grants`, `domOwnership`, and `keepAlive` belong to shell configuration. Extra fields are not accepted indiscriminately: store your own metadata inside `metadata`.
## Loading and validation rules
A **real 404** allows generation of the default manifest with `entry: 'index.js'` and empty permissions. A network error, 500, invalid JSON, or HTML page returned as a manifest produces an error. This prevents a misconfigured server from being interpreted as an application without a manifest.
| Limit | Value in code |
| --- | --- |
| Manifest size | 100 KiB |
| Name length | 50 characters |
| Entry length | 200 characters |
| Exports | 100 |
| Declarative imports | 50 |
| Descriptive routes | 100 |
| Requests / grants | 50 declarations per list |
Validation checks that the downloaded name matches the registered name. It inspects own properties, rejects accessors and dangerous structures, and returns a frozen snapshot. Do not use `manifest.wu.permissions.push(...)` to change policy after registration.
## Permissions: exact syntax
An object declaration requires `capability` and an **explicit `resource`**. A valid string form is, for example, `store.read:catalog`. Use an object to also declare `required`; use a string when you only need a capability and resource.
```js
// Solicitud de la aplicación:
const permission = {
capability: 'store.read',
resource: 'catalog',
required: true,
};
// Dos formas equivalentes de conceder esa lectura desde el host:
const objectGrant = { capability: 'store.read', resource: 'catalog' };
const stringGrant = 'store.read:catalog';
```
`store.read` alone is not a valid declaration for the parser. The input TypeScript declaration permits some broader values, so explicitly supplying the resource is necessary even when the editor does not require it.
`required` defaults to `false`. A denied optional permission is recorded in diagnostics, and its operation will be rejected if attempted. `required: true` makes registration fail when the shell does not cover the entire request.
## Loading strategy, layout, and styles
`strategy` selects how to preload an application; see [loading and prefetching](/docs/framework/loading/) to choose between loading on mount, importing immediately, or prefetching resources. `fullBleed` controls whether the app fills the host height or flows with content. Both fields are read from application configuration, although they are not listed in `WuAppConfig`.
Configure `styleMode` in the manifest. Mounting passes `app.manifest.styleMode` to the sandbox; the same-named field in top-level host configuration does not replace it. The [sandbox and CSS guide](/docs/framework/sandbox/) explains how to combine app and shared styles.
## Implementation references
Implementation: `src/core/wu-core.js`, `src/core/wu-core.js`, `src/core/wu-core.js`; parser and limits: `src/core/wu-manifest.js`, `src/core/wu-manifest.js`, `src/core/wu-manifest.js`; policy: `src/core/wu-policy.js` and `src/core/wu-policy.js`. Tests: `tests/unit/manifest-policy.test.js`, `tests/unit/manifest-dependencies.test.js`, `tests/unit/init-race.test.js`.