# WRNexusJS 0.4 architecture

## Goals

WRNexusJS 0.4 keeps the existing SSR-first model while making advanced systems installable without application-owned copies or manual wiring. The framework remains conservative: HTML is rendered on the server, the reactive runtime loads only for reactive pages, and package browser code loads only when its component or markup declares a runtime requirement.

## Request and render path

1. The CLI or development server loads `wrnexus.config.*`.
2. `@wrnexus/plugin` discovers explicit plugins and installed package manifests.
3. Contributions are normalized and validated for duplicate IDs, paths, routes, and migrations.
4. The router combines application and package components/routes/middleware.
5. `.wrn` sources compile through plugin AST/code transforms.
6. SSR renders page and component HTML.
7. Rendered `data-wrnexus-runtime` markers are matched against registered client runtimes.
8. Only referenced runtime scripts are added to the response.
9. CSR navigation loads newly required runtime chunks, calls `mount`, and calls `unmount` before replacing old page content.

## Package contribution model

A package can contribute:

- component directories
- client runtimes
- static or generated assets
- stylesheet entries and Tailwind scan sources
- page, API, and realtime routes
- middleware
- database migrations
- DevToolbar panels
- compiler diagnostics and transforms
- build and server lifecycle hooks

Contributions are declared by a package plugin or by the `wrnexus` field in `package.json`.

## Client runtime rules

A runtime has a stable ID, source entry, loading policy, module/classic format, and singleton policy. Development serves it from `/__wrnexus/assets/`; TypeScript runtime entries are browser-bundled on demand. Production builds emit content-hashed immutable runtime chunks and store their paths in the static server manifest.

Runtime code should register:

```js
window.__wrnexusRuntimes = window.__wrnexusRuntimes || {};
window.__wrnexusRuntimes.example = {
  mount(root) {},
  unmount(root) {},
};
```

Mount and unmount must be idempotent. Event listeners, observers, audio, timers, and provider widgets must be cleaned up during unmount.

## Package assets and styles

Package assets use validated framework paths and receive correct MIME and `nosniff` headers. Production stores package assets in content-addressed files while preserving their declared public URLs; immutable caching remains opt-in. Package component directories and style sources are automatically added to application stylesheet processing, so apps do not need manual Tailwind `@source` entries for installed systems.

Production stylesheet processing fails closed by default. A Tailwind/PostCSS failure cannot silently ship unprocessed CSS unless the application explicitly selects fallback behavior.

## Package migrations

Packages can register inline SQL, a SQL file, or an ordered directory. Migration names are namespaced by package migration ID and may target the default or a named database. Development applies application and package migrations through the same migration table. Production copies both into the build output.

## Development experience

The development server watches application and workspace package component/runtime/style sources. Package `.wrn` changes invalidate both compiled modules and the stylesheet cache. `wrnexus inspect` exposes packages, plugins, routes, assets, runtimes, styles, migrations, and build reports. DevToolbar receives a platform snapshot and package panels.

## Compatibility

The 0.4 migration removes legacy CAPTCHA script tags, archives manually copied runtime files instead of deleting them, and leaves user-authored application code intact. Existing explicit plugins continue to work and take precedence over automatically discovered plugins with the same name.