# WRNexusJS foundation roadmap

This document is a governed backlog, not a list of already shipped claims. Status was
reconciled against the repository on 2026-08-02. `Delivered` means executable tests or CI
evidence exists; `Partial` means a usable foundation exists but the complete design below
does not; `Future` means no production implementation is claimed.

| #   | Capability                             | Status    | Current evidence / remaining boundary                                                                                                                                                                                |
| --- | -------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | Explicit runtime environments          | Delivered | Bun, Node, browser, Edge, worker and service-worker capability sets, WRN targets, import diagnostics, package requirements and build enforcement ship.                                                               |
| 2   | Compatibility date / behaviour version | Delivered | Typed date/behaviour policy, strict validation, scaffold defaults, and backed-up idempotent `check`, `explain`, and `upgrade` CLI commands ship.                                                                     |
| 3   | Compiler-powered optimization          | Delivered | Literal branches are folded before code generation and analysis reports static/reactive nodes, dead state/handlers/CSS, constant props, batching, memoization, preload and server-only opportunities.                |
| 4   | Static shell with dynamic regions      | Delivered | `partial-static`, `<Static>` and `<Dynamic>` compile into build-time `dist/partial-shells.json`; production embeds that shell in its manifest and streams only request-rendered regions with CSP nonces.             |
| 5   | Unified request context                | Delivered | One execution context covers HTTP/API/action/loader/middleware/realtime/queue/cron/webhook operations, trusted identity, services, tracing, cancellation and authorization.                                          |
| 6   | Cancellation, timeouts and cleanup     | Delivered | Abort signals and shutdown tests cover HTTP, DB, queue, pub/sub, upload and AI paths.                                                                                                                                |
| 7   | Resilience primitives                  | Delivered | Universal cancellation-aware timeout/retry/backoff/fallback API, shared circuit health, bounded bulkheads, health registry, idempotency and locks ship.                                                              |
| 8   | Contracts for every boundary           | Delivered | Typed registries cover API, action, webhook, realtime, queue, cron, pub/sub, plugin, config and env; snapshot/check CLI gates breaking changes.                                                                      |
| 9   | Local production simulator             | Delivered | `dev --services` provides bounded database/cache/mail/SMS/webhook/storage/queue/cron/auth/metrics viewers, realtime and multi-domain routing, plus portable generated localhost HTTPS with an explicit HTTP opt-out. |
| 10  | Doctor and explainability              | Delivered | `doctor` and `explain route/build/hydration/bundle/cache/permission` consume persisted compiler, cache-policy and authorization evidence.                                                                            |
| 11  | Production mode during development     | Delivered | Exact-output `preview` and supervised `dev --production-runtime` rebuild/restart ship; its opt-in production WebSocket client reconnects after restart and morphs fresh HTML without a visible document reload.      |
| 12  | Navigation state preservation          | Delivered | Per-page UI restoration excludes sensitive fields, while keyed `<KeepAlive>` regions preserve the same bounded live DOM/runtime instances across navigation.                                                         |
| 13  | Zero-downtime DB migration support     | Delivered | Locks, dry-run, rollback and cancellation ship; `db check` detects destructive/type/null/index risks and migrate gates pending breaking operations.                                                                  |
| 14  | Supply-chain security                  | Delivered | Frozen locks, audits, SBOM, staged integrity hashes, package normalization and isolated consumer probes are gated.                                                                                                   |
| 15  | Plugin permissions                     | Delivered | Manifests declare framework capabilities and opt-in app grants fail closed across dev/build for routes, middleware, migrations, transforms, server hooks and assets.                                                 |
| 16  | Plugin compatibility test kit          | Delivered | Package/staged-consumer probes plus reusable runtime, capability, Bun-version and OS matrix checks ship; discovery enforces declared deployment support.                                                             |
| 17  | Accessibility compiler diagnostics     | Delivered | Canonical compiler/LSP diagnostics and all UI/example page accessibility gates are executable.                                                                                                                       |
| 18  | International application support      | Delivered | Routing, ICU plural/select/gender, alternate calendars/timezones, extraction/validation, route and tenant messages, pseudo-locales and RTL ship.                                                                     |
| 19  | Sanitized reproduction generator       | Delivered | `wrnexus report` creates a bounded, traversal-safe bundle with sanitized source/config, versions, diagnostics, errors and reproduction commands.                                                                     |
| 20  | Online playground                      | Partial   | A deployable CSP/sandbox playground provides examples, compiler/client/SSR output, interactive previews, Unicode shares and pluggable version comparison; public hosting remains an operator task.                   |

The cross-editor language tooling requested by the release plan is now delivered through
`@wrnexus/language-server`. Its stdio LSP provides diagnostics, formatting, completion,
hover, symbols, definition, references, rename and quick fixes. VS Code bundles the same
server; other editors launch `wrnexus-language-server --stdio`.

Beyond the earlier roadmap, the following sections preserve the detailed target designs.

# 1. Explicit Runtime Environments

WRNexusJS should understand that code may run in different environments:

```text
Browser
Bun server
Node.js server
Edge runtime
Service worker
Background worker
Cron worker
Build process
Test environment
```

A file or function should be able to declare its runtime:

```wrn
runtime = "server"
runtime = "edge"
runtime = "client"
runtime = "worker"
```

Or:

```ts
export const runtime = "edge";
```

The compiler should prevent incompatible imports.

For example:

```ts
// Should fail during compilation in an edge environment
import fs from "node:fs";
```

This would let WRNexusJS eventually deploy the same application to:

- Bun
- Node.js
- Cloudflare Workers
- Docker
- Serverless functions
- Static hosting
- Edge environments

Vite’s Environment API now explicitly models multiple execution environments rather than assuming only client and SSR environments. Cloudflare similarly emphasizes Web-standard APIs so code can move between browsers and server runtimes more easily. ([vitejs][1])

## Recommended internal abstraction

```ts
interface RuntimeEnvironment {
  name: string;
  capabilities: Set<"filesystem" | "tcp" | "websocket" | "crypto" | "streams" | "background-tasks">;
}
```

Then packages can declare requirements:

```ts
definePackage({
  requires: ["filesystem", "tcp"],
});
```

The compiler can explain why a package cannot run on a particular deployment target.

---

# 2. Compatibility Date or Behaviour Version

This is extremely important for long-term stability.

Add something like:

```ts
export default defineConfig({
  compatibilityDate: "2026-08-02",
});
```

Or:

```ts
export default defineConfig({
  frameworkBehaviour: 1,
});
```

This means a project does not silently receive new framework defaults after upgrading.

For example, WRNexusJS might later change:

- Cache defaults
- Cookie defaults
- Hydration behavior
- Route matching
- Form serialization
- Security headers
- Error handling
- Environment-variable handling

Existing applications should retain their old behavior until they explicitly migrate.

Nuxt uses a compatibility date to keep application behavior stable across framework and runtime updates instead of silently applying changed defaults. It also allows applications to opt into future major-version behavior early. ([Nuxt][2])

Commands could be:

```bash
wrnexus compatibility check
wrnexus compatibility upgrade
wrnexus compatibility explain
```

This would work very well with your existing `update.ts` migration system.

---

# 3. Compiler-Powered Automatic Optimization

Because WRNexusJS owns the `.wrn` compiler, it should optimize applications automatically.

The compiler could determine:

- Which state is used by which DOM element
- Which expressions are static
- Which components never hydrate
- Which event handlers are unused
- Which props are constant
- Which branches can be removed
- Which CSS classes are unused
- Which state updates can be batched
- Which components can be memoized
- Which dependencies can be preloaded
- Which modules belong only on the server

Example:

```wrn
state count = 0
state username = ""

view {
  <p>{count}</p>
  <button @click='count++'>Increment</button>
  <UserCard name='username' />
}
```

Changing `count` should update only the `<p>`, not re-render the full component.

The compiler should produce an optimization report:

```bash
wrnexus build --analyze
```

```text
Dashboard.wrn
✓ 14 static nodes hoisted
✓ 3 reactive regions generated
✓ 2 components lazy-loaded
✓ Client bundle reduced by 18.4 KB
⚠ UserTable hydration includes unused state
```

React Compiler demonstrates the value of build-time automatic optimization rather than requiring developers to manually add memoization everywhere. ([React][3])

This is one area where WRNexusJS can outperform frameworks that primarily rely on runtime rendering.

---

# 4. Static Shell With Dynamic Regions

A page should not have to be entirely static or entirely dynamic.

WRNexusJS could generate:

```text
Static header
Static navigation
Static page structure
Dynamic user information
Dynamic notifications
Static footer
```

Example:

```wrn
page Dashboard {
  render = "partial-static"

  view {
    <Header />

    <Dynamic>
      <UserSummary />
    </Dynamic>

    <Static>
      <DocumentationLinks />
    </Static>
  }
}
```

At build time, the framework creates the static shell. At request time, only dynamic sections are rendered and streamed.

Next.js Partial Prerendering follows this model by producing a static shell at build time and streaming dynamic portions at request time. ([Next.js][4])

For WRNexusJS, this would be useful for:

- Public portals with logged-in headers
- Product pages with personalized pricing
- Dashboards with mostly static navigation
- Government pages with dynamic status widgets
- Documentation with dynamic user information

---

# 5. Unified Request Context

Every server operation should receive the same trusted context:

```ts
interface WRNexusContext {
  request: Request;
  response: ResponseContext;

  user: AuthenticatedUser | null;
  session: Session | null;
  tenant: Tenant | null;

  locale: string;
  timezone: string;

  db: DatabaseContext;
  cache: CacheContext;
  logger: Logger;
  trace: TraceContext;

  signal: AbortSignal;
  deadline: Date | null;
}
```

The same context should work in:

- API routes
- Server actions
- Middleware
- Page loaders
- Realtime handlers
- Queue jobs
- Cron jobs
- Webhooks

This gives developers one predictable programming model.

```ts
async function createUser(ctx: WRNexusContext, input: CreateUserInput) {
  await ctx.authorize("users.create");

  return ctx.db.users.create({
    tenantId: ctx.tenant.id,
    name: input.name,
  });
}
```

It would also solve duplicated authentication, tenant, logging and tracing logic.

---

# 6. Cancellation, Timeouts and Cleanup

Every request, data loader and server action should support cancellation.

```ts
await fetch(url, {
  signal: ctx.signal,
});
```

When the browser disconnects or navigates away:

- Stop unnecessary database queries where possible
- Cancel outgoing HTTP requests
- Stop AI streaming
- Stop report generation
- Release file handles
- Release database connections
- Stop rendering abandoned UI

Add framework primitives:

```ts
await withTimeout("5s", async (signal) => {
  return externalService.call({ signal });
});
```

And lifecycle cleanup:

```wrn
onCleanup {
  subscription.close()
}
```

This is not a flashy feature, but it is essential for production performance and preventing resource leaks.

---

# 7. Resilience Primitives

Applications repeatedly implement retries and failure handling incorrectly. WRNexusJS should provide safe standard primitives.

```ts
const result = await resilientCall({
  timeout: "5s",
  retries: 3,
  backoff: "exponential",
  circuitBreaker: {
    failures: 5,
    resetAfter: "30s",
  },
  run: (signal) => paymentProvider.checkStatus({ signal }),
});
```

Support:

- Timeouts
- Controlled retries
- Exponential backoff
- Circuit breakers
- Bulkheads
- Concurrency limits
- Fallback responses
- Health tracking
- Idempotency
- Distributed locks

The DevToolbar should show:

```text
Payment provider
Status: Circuit open
Failures: 7
Retry after: 18 seconds
```

This would be particularly useful for WRNexus integrations involving SMS, email, WhatsApp, payments and external government systems.

---

# 8. Contract System for Every Boundary

Do not limit contracts to HTTP APIs.

WRNexusJS should provide schemas for:

- APIs
- Server actions
- Webhooks
- Realtime events
- Queue jobs
- Cron jobs
- Pub/sub events
- Plugin interfaces
- Configuration
- Environment variables

Example:

```ts
defineEvent({
  name: "user.created",
  version: 1,
  payload: schema.object({
    userId: schema.uuid(),
    tenantId: schema.uuid(),
    createdAt: schema.datetime(),
  }),
});
```

When changing it:

```ts
defineEvent({
  name: "user.created",
  version: 2,
  payload: NewUserCreatedSchema,
});
```

The framework should detect incompatible changes:

```bash
wrnexus contracts check
```

```text
Breaking change detected:

Event: user.created@1
Field removed: email
Consumers affected:
- notification-worker
- crm-sync
- audit-service
```

This becomes highly valuable in monorepos and enterprise systems.

---

# 9. Local Production Simulator

`wrnexus dev` should eventually simulate the whole production environment locally.

It should provide local versions of:

- Database
- Redis-compatible cache
- Queue
- Cron scheduler
- Object storage
- Email inbox
- SMS testing inbox
- Webhook receiver
- Realtime server
- Multi-domain gateway
- HTTPS certificates
- Authentication server
- Observability collector

Example:

```bash
wrnexus dev --services
```

Output:

```text
Web:          https://localhost:3000
Admin:        https://admin.localhost:3000
SSO:          https://sso.localhost:3000
Mail viewer:  https://mail.localhost:3000
Queue UI:     https://queue.localhost:3000
Storage UI:   https://storage.localhost:3000
```

This would reduce the difference between development and production.

It is especially useful for your multi-app WRNexus and Police Management monorepos.

---

# 10. Framework Doctor and Explainability

The framework should not only report errors—it should explain them.

Commands:

```bash
wrnexus doctor
wrnexus explain route /users/123
wrnexus explain build
wrnexus explain hydration UserCard
wrnexus explain bundle
wrnexus explain cache /products
wrnexus explain permission users.delete
```

Example:

```text
Why was this page rendered dynamically?

1. Dashboard.wrn reads ctx.session.
2. UserHeader.wrn reads request cookies.
3. Notifications.wrn disables caching.
```

Or:

```text
Why is UserChart included in the client bundle?

Dashboard.wrn
└── AnalyticsSection.wrn
    └── UserChart.wrn
        └── imports browser-chart-library
```

This can become one of the strongest WRNexusJS developer-experience features.

Most developers do not only need automation; they need to understand **why** the framework made a decision.

---

# 11. Production Mode During Development

Many errors appear only after building for production.

Add:

```bash
wrnexus dev --production-runtime
```

This mode should use:

- Production module resolution
- Production serialization
- Real cache behavior
- Minified client code
- Production security headers
- Production environment validation
- Production routing rules
- Production asset paths

But retain development error reporting and hot reload.

Also provide:

```bash
wrnexus preview
```

This must run the exact production output, not a development approximation.

---

# 12. Navigation State Preservation

When navigating between pages, WRNexusJS should optionally preserve:

- Scroll position
- Form values
- Tab selection
- Expanded accordions
- Table filters
- Pagination
- Component state
- Partially completed workflows

Example:

```wrn
page Users {
  navigation {
    preserve = ["filters", "pagination", "scroll"]
  }
}
```

Or:

```wrn
<KeepAlive key='user-dashboard'>
  <DashboardFilters />
</KeepAlive>
```

Next.js now uses React’s Activity mechanism in parts of its navigation model to preserve component state instead of always destroying hidden route content. ([Next.js][5])

WRNexusJS should implement a simpler, framework-native version.

---

# 13. Zero-Downtime Database Migration Support

Your migration tooling should understand production rollout safety.

For example, this migration is dangerous:

```sql
ALTER TABLE users
RENAME COLUMN name TO full_name;
```

Old application instances may still expect `name`.

WRNexusJS should support an expand-and-contract migration workflow:

```text
Release 1:
Add full_name
Write to name and full_name

Release 2:
Read from full_name
Continue dual write

Release 3:
Stop writing name

Release 4:
Remove name
```

Commands:

```bash
wrnexus migration analyze
wrnexus migration plan
wrnexus migration verify
```

The analyzer should warn about:

- Dropping active columns
- Adding non-null columns without defaults
- Long table locks
- Destructive type changes
- Index creation risks
- Application/schema incompatibility
- Rollback limitations

This is essential before positioning WRNexusJS for large enterprise applications.

---

# 14. Supply-Chain Security

WRNexusJS should help developers secure dependencies and builds.

Generate:

- Software Bill of Materials
- Dependency vulnerability report
- License report
- Build provenance
- Package integrity hashes
- Signed release artifacts
- Secret scanning
- Malicious package checks

Commands:

```bash
wrnexus security dependencies
wrnexus security licenses
wrnexus security secrets
wrnexus build --provenance
wrnexus sbom generate
```

The framework should also warn when:

- A dependency unexpectedly introduces install scripts
- A client package imports server secrets
- Multiple vulnerable versions of the same dependency exist
- A plugin requests dangerous capabilities
- The lockfile differs in CI

---

# 15. Plugin Permissions

Third-party plugins should not automatically receive unrestricted access.

A plugin manifest could declare:

```json
{
  "name": "analytics-plugin",
  "permissions": ["compiler:transform", "routes:read", "devtoolbar:register"]
}
```

A database plugin might request:

```json
{
  "permissions": ["database:connect", "config:read:database"]
}
```

Dangerous permissions should produce a warning:

```text
Plugin @example/deployer requests:

- filesystem:write
- process:execute
- environment:secrets

Continue installation?
```

This will not create a perfect security sandbox, but it makes capabilities visible and auditable.

---

# 16. Plugin Compatibility Test Kit

Every plugin author should be able to run:

```bash
wrnexus plugin test
```

It should test:

- Supported framework versions
- Development server integration
- Production build
- HMR
- SSR
- CSR
- Edge compatibility
- Type declarations
- Multiple operating systems
- Multiple Bun versions
- Security permissions
- Upgrade behavior

Plugin metadata:

```ts
definePlugin({
  compatibility: {
    wrnexus: ">=1.0 <2.0",
    runtimes: ["bun", "node", "edge"],
  },
});
```

Nuxt provides compatibility utilities so modules can check and assert supported framework versions. ([Nuxt][6])

---

# 17. Accessibility as a Compiler Feature

Do not make accessibility only a DevToolbar audit.

The `.wrn` compiler should catch problems while code is being written:

```wrn
<img src="/officer.png" />
```

```text
WRNA11Y001: Image is missing alt text.
```

```wrn
<div @click='submit'>Submit</div>
```

```text
WRNA11Y014: Clickable non-interactive element requires keyboard support.
Consider using <button>.
```

Check:

- Missing labels
- Invalid ARIA attributes
- Incorrect heading order
- Keyboard-inaccessible elements
- Insufficient accessible names
- Invalid role combinations
- Missing dialog focus management
- Missing language declaration
- Animation without reduced-motion handling

The UI package should be accessible by default, not only configurable to become accessible.

---

# 18. Complete International Application Support

You already plan i18n, but it should go beyond translation strings.

Support:

- Locale-based routing
- ICU message syntax
- Pluralization
- Gender-aware translations
- Right-to-left layouts
- Localized numbers
- Localized currency
- Localized dates
- Calendar systems
- Timezone conversion
- Translation extraction
- Missing-key detection
- Per-tenant translation overrides
- Translation loading by route

Example:

```wrn
<p>{t("campaign.sent", { count: sentCount })}</p>
```

Compiler command:

```bash
wrnexus i18n extract
wrnexus i18n validate
```

```text
Missing in Marathi:
- campaign.schedule
- officer.transfer.approved

Unused keys:
- old.dashboard.title
```

This would be especially valuable for Indian government and public-facing systems.

---

# 19. Reproduction Generator

When a developer finds a framework bug, they should be able to run:

```bash
wrnexus report
```

The command creates a minimal reproduction containing:

- Relevant configuration
- Framework version
- Runtime version
- Operating-system details
- Sanitized route/component
- Compiler diagnostics
- Dependency list
- Error stack
- Reproduction commands

It must automatically remove:

- Environment secrets
- API keys
- Database credentials
- User data
- Internal domains

This would significantly improve the quality of issue reports and reduce debugging time.

---

# 20. Online WRNexusJS Playground

Create a browser-based playground where developers can:

- Write `.wrn`
- See SSR output
- See client output
- Inspect generated JavaScript
- Inspect generated HTML
- Test reactive state
- Share examples through URLs
- Reproduce compiler issues
- Try UI components
- Compare framework versions

Modes:

```text
Editor
Preview
Generated server code
Generated client code
Compiler AST
Diagnostics
Bundle analysis
```

The React ecosystem provides a compiler playground for inspecting compiler behavior; a WRNexusJS playground could similarly make the custom language and compiler much easier to understand. ([React Playground][7])

# The Most Important New Points

From this additional list, I would prioritize these six:

1. **Runtime environment and capability system**
2. **Compatibility date with automatic migrations**
3. **Compiler-powered fine-grained optimization**
4. **Unified context and contract system**
5. **Local production simulator**
6. **Framework doctor and explain commands**

These are more valuable now than creating another twenty utility packages.

# Recommended Architecture Order

## Phase 1: Stability foundation

Implement first:

```text
Compatibility date
Runtime boundaries
Unified context
Contract registry
Plugin compatibility metadata
Framework doctor
```

## Phase 2: Compiler intelligence

Then:

```text
Fine-grained reactive compilation
Static analysis
Client/server import detection
Accessibility diagnostics
Bundle explanation
Partial static rendering
```

## Phase 3: Production platform

Then:

```text
Local service simulator
Resilience primitives
Zero-downtime migration analysis
Supply-chain security
Plugin permissions
Production-runtime development mode
```

## Phase 4: Ecosystem growth

Finally:

```text
Online playground
Reproduction generator
Plugin testing kit
Official presets
Community registry
Cross-runtime deployment adapters
```

The long-term strength of WRNexusJS should not be:

> “It has more packages than other frameworks.”

It should be:

> **“The compiler understands the application, the framework explains its decisions, secure production behavior is built in, and upgrades do not unexpectedly break existing applications.”**

[1]: https://vite.dev/guide/api-environment?utm_source=chatgpt.com "Environment API | Vite"
[2]: https://nuxt.com/docs/4.x/errors/b5001?utm_source=chatgpt.com "NUXT_B5001 · Nuxt v4"
[3]: https://react.dev/learn/react-compiler/introduction?utm_source=chatgpt.com "Introduction – React"
[4]: https://nextjs.org/docs/app/guides/ppr-platform-guide?utm_source=chatgpt.com "Guides: PPR Platform Guide | Next.js"
[5]: https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents?utm_source=chatgpt.com "next.config.js: cacheComponents | Next.js"
[6]: https://nuxt.com/docs/3.x/api/kit/compatibility?utm_source=chatgpt.com "Compatibility · Nuxt Kit v3"
[7]: https://playground.react.dev/?utm_source=chatgpt.com "React Compiler Playground"
