WRNexusJS/docs/ROADMAP-V1.md

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:

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:

runtime = "server"
runtime = "edge"
runtime = "client"
runtime = "worker"

Or:

export const runtime = "edge";

The compiler should prevent incompatible imports.

For example:

// 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)

Recommended internal abstraction

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

Then packages can declare requirements:

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:

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

Or:

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)

Commands could be:

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:

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:

wrnexus build --analyze

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)

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:

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

Example:

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)

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:

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.

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.

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:

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

And lifecycle cleanup:

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.

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:

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:

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

When changing it:

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

The framework should detect incompatible changes:

wrnexus contracts check

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:

wrnexus dev --services

Output:

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:

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:

Why was this page rendered dynamically?

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

Or:

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:

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:

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:

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

Or:

<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)

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:

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:

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:

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:

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:

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

A database plugin might request:

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

Dangerous permissions should produce a warning:

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:

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:

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)

---

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:

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

WRNA11Y001: Image is missing alt text.

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

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:

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

Compiler command:

wrnexus i18n extract
wrnexus i18n validate

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:

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:

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)

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:

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

Phase 2: Compiler intelligence

Then:

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

Phase 3: Production platform

Then:

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

Phase 4: Ecosystem growth

Finally:

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.”