release: WRNexusJS 0.3.0

2026-07-22 17:29:08 +05:30
parent 13dfa31d19
commit 07d8fb59d6
145 changed files with 9664 additions and 3881 deletions
@@ -0,0 +1,136 @@
+# WRNexusJS 0.3 Architecture
+
+## Design goals
+
+WRNexusJS 0.3 is an additive architecture release focused on one invariant:
+
+> A valid `.wrn` file must be parsed, diagnosed, compiled, rendered, hydrated,
+> formatted, migrated, and edited from one shared language model.
+
+The release keeps existing application contracts while adding extension seams for
+full-stack data, plugins, partial hydration, observability, tenancy, advanced
+routing, build analysis, jobs, and deployment adapters.
+
+## Package boundaries
+
+### Language and compilation
+
+- `@wrnexus/syntax`: canonical tokens, AST, source positions, diagnostics, and spec
+- `@wrnexus/compiler`: SSR/client code generation and deprecated parser re-exports
+- `@wrnexus/csr`: browser navigation and fine-grained reactive hydration
+- `@wrnexus/reactive`: framework-independent signals, computed values, effects, and batching
+
+### Request and application runtime
+
+- `@wrnexus/core`: context, middleware, security, typed endpoints, loaders/actions,
+  tenant APIs, tracing, feature flags, and performance budgets
+- `@wrnexus/router`: route discovery, matching, groups, optional/catch-all params,
+  conflicts, and typed URL generation
+- `@wrnexus/ssr`: document rendering plus string, promise, and async-iterable streaming
+- `@wrnexus/dev-server`: shared dev/production request runtime and portable fetch handlers
+
+### Extension and operations
+
+- `@wrnexus/plugin`: deterministic plugin ordering and lifecycle hooks
+- `@wrnexus/dev-toolbar`: source-linked page diagnostics
+- `@wrnexus/cli`: build, doctor, config explanation, analyzer, migrations, and generators
+- `@wrnexus/queue`: jobs, priority, concurrency, idempotency, cancellation, cron helpers,
+  and workflows
+- `@wrnexus/pubsub`: realtime scaling adapters
+
+## Compatibility layers
+
+The compiler's former parser, tokenizer, and AST modules re-export the canonical
+syntax package. No existing public compiler import must be changed immediately.
+
+The client runtime continues to support legacy hydration scopes, `data-for`, and
+`{#each}` output. New hydration metadata is additive:
+
+```html
+<div data-wrn-hydration="stable-id" data-wrn-hydrate="visible" data-wrn-runtime="universal"></div>
+```
+
+The updater creates a full application-source backup before source normalization.
+Its migration report lists every changed file.
+
+## Request flow
+
+```text
+Request
+  -> security/CORS/body-size boundary
+  -> optional tracing middleware
+  -> optional tenant middleware
+  -> application middleware
+  -> route matcher
+  -> loader/API/page/realtime dispatch
+  -> SSR document assembly
+  -> response cookies/security/compression
+```
+
+Development and production use the same `createHandlers` runtime. Production also
+exposes `createProductionHandlers`, a portable web-standard fetch seam used by Bun,
+Node, and future edge/serverless adapters.
+
+## Reactive update flow
+
+```text
+signal write
+  -> dependency invalidation
+  -> microtask batch
+  -> computed values refresh on demand
+  -> only subscribed renderers/effects run
+  -> DOM bindings update
+```
+
+Renderer scheduling is coalesced so repeated writes in one task do not cause a full
+component rerender for each write.
+
+## Plugin lifecycle
+
+Plugins are ordered deterministically with `enforce`, `before`, and `after`:
+
+```text
+configure
+configResolved
+buildStart / configureServer
+transformAst
+plugin diagnostics
+transformCode
+buildEnd
+```
+
+Duplicate names and ordering cycles fail with stable plugin errors. Plugin hooks
+are optional and the absence of plugins has zero behavioral effect.
+
+## Build outputs
+
+A production build can emit:
+
+- compiled route/component modules
+- source maps when enabled
+- route and asset measurements
+- `dist/build-report.json`
+- performance-budget violations
+- generated production entry with security, observability, tenancy, storage,
+  databases, realtime, mobile, PWA, and SEO configuration
+
+Use:
+
+```bash
+wrnexus config . --explain
+wrnexus build .
+wrnexus analyze .
+wrnexus doctor .
+```
+
+## Stability levels
+
+- **Stable**: existing behavior, canonical syntax ownership, diagnostics, router
+  compatibility, typed core primitives, build reports, migration safety
+- **Additive stable API**: plugin contracts, tracing, tenancy, loaders/actions,
+  endpoint definitions, job definitions
+- **Experimental runtime behavior**: server components, broader streaming boundaries,
+  custom adapter implementations, and plugin transforms can be gated in config
+
+Experimental flags make feature adoption explicit without forcing existing apps to
+change their runtime behavior.