# 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`, `` and `` 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 `` 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 {

{count}

} ``` Changing `count` should update only the `

`, 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 {

} } ``` 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 ``` 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 ``` ```text WRNA11Y001: Image is missing alt text. ``` ```wrn
Submit
``` ```text WRNA11Y014: Clickable non-interactive element requires keyboard support. Consider using