# Upgrade to WRNexusJS 0.3.0

## Before upgrading

Commit the project or create a backup. The updater also creates its own timestamped
backup, including the complete `app` directory.

Use the same Bun baseline used by the framework:

```bash
bun --version
# 1.3.0 or newer
```

## Preview the migration

```bash
bunx wrnexus update . --to 0.3.0 --dry-run
```

Review every reported `.wrn` file. The source migration is intentionally narrow:

- compact simple `props { ... }` declarations become multiline
- simple `attribute={expression}` becomes `attribute='{expression}'`
- nested brace values, ambiguous quotes, and complex expressions are not rewritten

## Apply and verify

```bash
bunx wrnexus update . --to 0.3.0
bun install
bun run format
bun run check
bun run build
bun run doctor
bun run analyze
```

The update is not marked verified until project verification succeeds.

## Files added by the migration

Runnable applications receive these scripts when missing:

```json
{
  "doctor": "wrnexus doctor .",
  "config:explain": "wrnexus config . --explain",
  "analyze": "wrnexus analyze .",
  "update:preview": "wrnexus update . --dry-run"
}
```

They also receive direct dependencies on `@wrnexus/syntax` and `@wrnexus/plugin`.
A report is written to `.wrnexus/migrations/0.3.0.json`.

## New optional configuration

```ts
import { defineConfig } from "@wrnexus/styles";

export default defineConfig({
  experimental: {
    partialHydration: true,
    streaming: true,
    typedRpc: true,
    pluginTransforms: true,
  },
  observability: {
    enabled: true,
    serverTiming: true,
    sampleRate: 1,
    exporter: "console",
  },
  tenancy: {
    mode: "subdomain",
    rootDomains: ["example.com"],
    required: true,
  },
  performance: {
    enforcement: "warn",
    analyze: true,
    budgets: {
      routeJsBytes: 80_000,
      routeCssBytes: 50_000,
      imageBytes: 300_000,
    },
  },
  build: {
    sourceMaps: true,
    report: true,
    adapter: "bun",
  },
});
```

All new sections are optional. Omitting them preserves previous behavior.

## Syntax adoption

Existing `.wrn` files continue working. New declarations can be introduced one at
a time:

```wrn
component AnalyticsChart {
    runtime = "universal"
    hydrate = "visible"

    props {
        points = []
    }

    computed {
        total = points.reduce((sum, point) => sum + point.value, 0)
    }

    view {
        <output>{total}</output>
    }
}
```

## Rollback

Use the updater's backup directory or restore the source-control commit. The
migration report contains the exact normalized files. Because the new APIs and
metadata are additive, an application that did not adopt new syntax can roll back
package versions without source changes.

## Release verification for framework maintainers

```bash
bun install
bun run verify:0.3
bun run typecheck
bun run lint
bun test packages
bun run format:check
node --test editors/vscode/test/*.test.js
cd editors/vscode && bun run validate && bun run package
```

Regenerate `bun.lock` and the VS Code `compiler.cjs`/VSIX in a Bun-enabled release
environment before publishing.