WorkRoot/WRNexusJS
2
0
Fork 0
Code Issues Pull Requests Actions 33 Packages Projects Releases Wiki Activity

release: WRNexusJS 0.3.0

Browse Source
This commit is contained in:
Clintchiz
2026-07-22 17:29:08 +05:30
parent 13dfa31d19
commit 07d8fb59d6
145 changed files with 9664 additions and 3881 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/40-POINT-IMPLEMENTATION-0.3.md
+68
View File
@@ -0,0 +1,68 @@
# WRNexusJS 0.3 — 40-Point Implementation Matrix
Legend:
- **Existing + hardened**: capability already existed and was preserved or extended
- **Implemented**: new usable public API/runtime behavior in 0.3
- **Foundation / experimental**: contract and integration seam exist; advanced provider-specific
implementations should remain opt-in until they receive production soak testing
| # | Improvement | 0.3 implementation | Level |
| --: | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| 1 | Formal language specification | Canonical spec constants, stable diagnostics, and `docs/WRN-LANGUAGE-SPEC-1.0.md` | Implemented |
| 2 | Shared parser and AST | New `@wrnexus/syntax`; compiler compatibility re-exports | Implemented |
| 3 | Compile-time/runtime separation | Runtime metadata, server-only suppression, compile-time diagnostics and transforms | Existing + hardened |
| 4 | Fine-grained reactivity | Batched signals, dependency-tracked computed/effects, coalesced renderers | Implemented |
| 5 | Deterministic SSR/hydration | Stable hydration IDs, runtime/strategy metadata, mismatch diagnostics, keyed `data-for` reconciliation and keyed `{#each}` syntax | Implemented |
| 6 | Partial hydration/islands | load/idle/visible/interaction/media/none strategies | Implemented |
| 7 | Server-only execution | `runtime = "server"`, `load server`, browser-interactivity rejection | Implemented |
| 8 | Data-loading model | `defineLoader`, `defineAction`, request-local dedupe, WRN loaders/actions | Foundation / experimental |
| 9 | Streaming SSR | Promise and `AsyncIterable` document streams and response helper | Implemented |
| 10 | Routing | groups, optional and catch-all params, conflict checks, typed builders | Implemented |
| 11 | Middleware | Existing ordered middleware plus tracing and tenancy middleware | Existing + hardened |
| 12 | Typed API/RPC | validated endpoint definitions, typed RPC client, structured errors | Implemented |
| 13 | Security defaults | Existing CSP/CSRF/cookies/CORS/body guards plus WRN security metadata | Existing + hardened |
| 14 | DevToolbar | Runtime diagnostic bridge and existing accessibility/performance/SEO/security rules | Existing + hardened |
| 15 | Optimization reports | `dist/build-report.json`, CLI analyzer, route/assets/budget measurements | Implemented |
| 16 | Error messages | Stable WRN codes, positions, code frames, hints | Implemented |
| 17 | Language server/editor | VS Code diagnostics/completion/grammar/snippets aligned to 0.3 syntax | Existing + hardened |
| 18 | Schemas/validation | Existing shared form/API validation retained; endpoint schema contract added | Existing + hardened |
| 19 | Authentication primitives | Existing auth/session/OAuth/passkey-related packages retained; security metadata seam | Existing + hardened |
| 20 | Multi-tenancy | tenant context, resolver/middleware, subdomain/domain/path runtime config | Implemented |
| 21 | Jobs/cron/workflows | priority, concurrency, idempotency, cancellation, job/workflow/cron helpers | Implemented |
| 22 | Realtime | Existing rooms/pub-sub/Redis bridge retained with shared runtime | Existing + hardened |
| 23 | Plugin system | deterministic lifecycle, AST/code transforms, diagnostics, server/build hooks | Implemented |
| 24 | Infrastructure adapters | portable fetch handler and existing Bun/Node seams; adapter config/reporting | Foundation / experimental |
| 25 | Build caching/monorepo | Existing compile cache and targeted HMR retained; build cache config seam | Existing + hardened |
| 26 | Compatibility/migrations | reversible 0.3 migration, source backup/report, `doctor`, unique versions | Implemented |
| 27 | Testing | new syntax/core/compiler/router/queue/SSR/update/editor regressions | Implemented |
| 28 | Performance budgets | configurable route JS/CSS, HTML, image, hydration, and SSR budgets | Implemented |
| 29 | Observability | tracer/span APIs, request middleware, Server-Timing, console exporter | Implemented |
| 30 | Component architecture | Existing `@wrnexus/ui` inventory retained; syntax metadata supports typed tooling | Existing + hardened |
| 31 | Design tokens | Existing `--wire-*` system and theme resolution retained | Existing + hardened |
| 32 | Accessibility | compile-time missing-alt diagnostic plus existing DevToolbar scanning | Implemented |
| 33 | Motion/transitions | Existing CSR/lifecycle foundation retained; strategy can be plugin/runtime extended | Foundation / experimental |
| 34 | Documentation | language, architecture, upgrade, implementation, test checklist docs | Implemented |
| 35 | AI-friendly framework | machine-readable spec/AST/diagnostics/build report and existing AI package | Implemented |
| 36 | Feature flags/experimental APIs | async context-aware feature flags and typed config gates | Implemented |
| 37 | Public API boundaries | syntax/compiler separation and explicit package exports | Implemented |
| 38 | Configuration | typed validation, source explanation, profile/env visibility | Implemented |
| 39 | Gateway | existing host routing/auth/WebSocket/security gateway preserved; internal contracts unchanged | Existing + hardened |
| 40 | Focused roadmap/release gates | 0.3 stability levels, verification script, audit and test matrix | Implemented |
## Important release distinction
This matrix records code present in the 0.3 source tree. “Foundation / experimental”
does not mean absent; it means the API or adapter seam is implemented but should not
be advertised as provider-complete until the relevant deployment, animation, cache,
or server-component adapters receive real production tests.
## Backward-compatibility gates
1. Existing compiler imports continue through re-exports.
2. Existing `.wrn` members and directives remain accepted.
3. New runtime behavior is disabled unless syntax/config opts in.
4. Source migration is conservative, backed up, idempotent, and reported.
5. Existing route syntax retains matching precedence.
6. Existing dev and production request runtimes remain shared.
7. Every bug fix receives a regression test or static verification assertion.
docs/ARCHITECTURE-0.3.md
+136
View File
@@ -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.
docs/AUDIT-0.3.md
+45
View File
@@ -0,0 +1,45 @@
# WRNexusJS 0.3 — Source Audit and Validation Record
## Audit scope
The uploaded monorepo was inspected package-by-package before changes. The baseline already contained compiler, SSR/CSR, reactive runtime, routing, gateway/dev-server integration, authentication and authorization packages, validation, database, queue, pub/sub/realtime, upload/storage helpers, UI, DevToolbar, AI tooling, mobile/native support, CLI migrations, and a VS Code extension.
The 0.3 work therefore extends existing contracts instead of replacing them. The baseline archive was committed locally before edits so every source change remained reviewable and reversible.
## Compatibility decisions
- Existing `@wrnexus/compiler` parser/type imports remain available through re-exports from `@wrnexus/syntax`.
- Existing `.wrn` roots, directives, route forms, component mounts, SSR output, and gateway configuration remain accepted.
- New hydration, plugin, tenancy, observability, feature-flag, performance-budget, and build-analysis behavior is opt-in.
- The updater backs up the complete `app/` directory and important project configuration before writing.
- Source normalization only rewrites simple unquoted dynamic attributes and safely parseable one-line props blocks. Nested-brace expressions are left unchanged for manual review.
- The updater writes a machine-readable changed-file report and is source-idempotent.
## Validation completed in this sandbox
- TypeScript static validation across all package source files: passed.
- TypeScript emit of all package sources for runtime smoke testing: passed.
- Compiled smoke tests for syntax/compiler, batched reactivity, computed/effects, typed endpoints, tracing, optional/catch-all routing, plugin ordering/transforms, queue priority/idempotency/workflows/cron, and streaming SSR: passed.
- Generated browser reactive runtime JavaScript syntax check: passed.
- All 913 checked-in `.wrn` files compile with the 0.3 compiler: passed.
- All 913 checked-in `.wrn` files remain valid and formatter-idempotent after formatting: passed.
- VS Code Node regression tests: 15 passed, 0 failed.
- VS Code asset/compiler validation: passed; `src/compiler.cjs` was rebuilt from the 0.3 compiler and shared syntax source.
- 0.3 structural release verification: 30 named packages and 66 migration entries passed.
- Git whitespace/error check: passed.
- Synthetic 0.2.70 to 0.3.0 migration: backup, dependency bump, scripts, new packages, conservative source normalization, report, nested-expression preservation, and second-run source idempotency all passed.
## Environment limitations
The sandbox did not contain Bun and could not reach the package registry. Therefore these release gates must still be run in the normal WRNexusJS development environment:
```bash
bun install
bun run check
bun run build
cd editors/vscode && bun run check && bun run package
```
Because VSCE dependencies were unavailable, a new 0.3.0 VSIX binary was not packaged here. The compiler bundle, source, grammar, snippets, metadata, Node tests, and extension validation were updated; run `bun run package` before Marketplace publishing.
The broad provider-specific parts of infrastructure adapters, advanced cache backends, and motion adapters remain deliberately marked as foundation/experimental in the implementation matrix until they receive real deployment and browser soak tests. They are not advertised as provider-complete.
docs/GUIDE.md
+10 -10
View File
@@ -310,15 +310,15 @@ identifiers, member/index access, calls, arrays/objects, `+ - * / %`, comparison
### Directives (the `data-*` the runtime understands)
| Directive | Syntax | What it does |
| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-scope` | `data-scope="count: 0, name: 'x'"` | Declares reactive state on a subtree. The compiler emits this automatically when a page/component has state. A binding is owned by its **nearest** `data-scope` ancestor (nesting is safe). |
| `data-on-<event>` | `data-on-click="count++"` | Event handler (the compiled form of `@event`). |
| `data-text` | `data-text="count * 2"` | `textContent` follows the expression. Emitted by state interpolation; you can also hand‑write it. |
| `data-show` | `data-show="open"` | Toggles `display` on truthiness. **Hand‑authored** (no `{}` sugar). |
| `data-for` | `data-for="item in items"` or `data-for="item, i in items"` | Repeats the element per list item. Inside, `item`/`i` are locals; per‑item `data-text`, `data-on-*`, attribute mustaches, and text mustaches are filled. **Hand‑authored.** |
| `data-component` | `data-component="counter"` | Mounts a component (server‑rendered, then hydrated). See §12. |
| `data-slot` | `<div data-slot="header">…</div>` | Fills a named `<slot name="header">` of a component (see §8). |
| Directive | Syntax | What it does |
| ----------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-scope` | `data-scope="count: 0, name: 'x'"` | Declares reactive state on a subtree. The compiler emits this automatically when a page/component has state. A binding is owned by its **nearest** `data-scope` ancestor (nesting is safe). |
| `data-on-<event>` | `data-on-click="count++"` | Event handler (the compiled form of `@event`). |
| `data-text` | `data-text="count * 2"` | `textContent` follows the expression. Emitted by state interpolation; you can also hand‑write it. |
| `data-show` | `data-show="open"` | Toggles `display` on truthiness. **Hand‑authored** (no `{}` sugar). |
| `data-for` | `data-for="item in items"`, optionally `key item.id` or `data-key="item.id"` | Repeats the element per list item. A stable key preserves DOM identity during reorder; unkeyed loops retain legacy full rerendering. Inside, item/index locals work in bindings and handlers. **Hand-authored.** |
| `data-component` | `data-component="counter"` | Mounts a component (server‑rendered, then hydrated). See §12. |
| `data-slot` | `<div data-slot="header">…</div>` | Fills a named `<slot name="header">` of a component (see §8). |
Example — a reactive list you write by hand:
@@ -327,7 +327,7 @@ view {
<div data-scope="items: [{t:'a'},{t:'b'}], open: true">
<button @click="open = !open">toggle</button>
<ul data-show="open">
<li data-for="i in items" data-text="i.t"></li>
<li data-for="i in items key i.id" data-text="i.t"></li>
</ul>
</div>
}
docs/TEST-CHECKLIST-0.3.md
+102
View File
@@ -0,0 +1,102 @@
# WRNexusJS 0.3 — One-by-One Test Checklist
Use this checklist on a clean branch before publishing. Run the global gates first, then test the numbered capabilities in order. Keep one of the three existing applications on its current release so you can compare output and behavior during the upgrade.
## Global release gates
```bash
bun install
bun run verify:0.3
bun run typecheck
bun run lint
bun run test
bun run format:check
bun run build
```
Expected: every command exits with code 0. The build must create `dist/build-report.json`.
For the VS Code extension:
```bash
cd editors/vscode
bun run check
bun run package
```
Expected: editor tests and validation pass, `src/compiler.cjs` is rebuilt from the 0.3 compiler, and a 0.3.0 VSIX is produced.
## Existing application upgrade safety
Run this separately in each existing application:
```bash
wrnexus update . --version=0.3.0 --dry-run
wrnexus update . --version=0.3.0
bun run format
bun run check
bun run build
wrnexus doctor .
wrnexus config . --explain
wrnexus analyze .
```
Verify before committing:
1. `.wrnexus/update-backups/` contains the original `app/` directory and project configuration.
2. `.wrnexus/migrations/0.3.0.json` lists only files that were actually normalized.
3. Dynamic attributes use quoted expressions, for example `items='{items}'`.
4. Existing `data-for`, `{#each}`, component mounts, pages, layouts, APIs, middleware, gateway routes, and authentication flows still work.
5. The package marker is updated only after installation, checks, and build succeed.
## 40 capability tests
| # | Capability | Test | Expected result |
| --: | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 1 | Language specification | Open `docs/WRN-LANGUAGE-SPEC-1.0.md`; compile each root member shown there. | Compiler and editor accept the same syntax. |
| 2 | Shared parser/AST | Import `parse` from both `@wrnexus/syntax` and `@wrnexus/compiler`. | Equivalent ASTs; old compiler imports continue working. |
| 3 | Compile/runtime separation | Build a static page with no state/events. | Page sends no reactive runtime unless another feature requires it. |
| 4 | Fine-grained reactivity | Change one signal used by one binding while another signal remains unchanged. | Only dependent renderers run; `batch`, `computed`, and `effect` behave predictably. |
| 5 | Deterministic hydration | SSR a stateful component, then hydrate it. Test keyed reorder with `data-for="item in items key item.id"`. | No mismatch; keyed DOM nodes retain identity and focus on reorder. |
| 6 | Partial hydration | Test `hydrate = "load"`, `idle`, `visible`, `interaction`, `media:...`, and `none`. | Each component hydrates only under its selected condition. |
| 7 | Server-only execution | Set `runtime = "server"` on a static component, then add a browser event deliberately. | Static version ships no client scope; interactive server-only version reports a compile diagnostic. |
| 8 | Data loading | Define a loader, action, request-local `dedupe`, cache metadata, and invalidation tags. | Loader/action types are inferred and duplicate request work runs once. |
| 9 | Streaming SSR | Return an async iterable body with delayed chunks. | Shell/head arrive first and later chunks complete valid HTML. |
| 10 | Routing | Create route groups, `[id?]`, `[[id]]`, `[...slug]`, and `[[...slug]]`. | Groups do not affect URLs; optional/catch-all params match and conflicts are reported. |
| 11 | Middleware | Add global middleware plus tracing and tenancy middleware. | Execution order is deterministic and context values reach the route. |
| 12 | Typed API/RPC | Define an endpoint with input/output schemas and call it through `createRpcClient`. | Invalid input returns a structured error; valid output is typed. |
| 13 | Security defaults | Test CSP, CSRF, secure cookies, CORS, body/upload limits, and a raw HTML boundary. | Unsafe requests/content are rejected and security headers are present. |
| 14 | DevToolbar | Open a page containing missing alt text, low contrast, oversized image, bad SEO, and runtime diagnostic. | Toolbar groups issues by panel and shows source/actionable detail. |
| 15 | Optimization reports | Build and run `wrnexus analyze .`. | Report shows assets, route sizes, measurements, diagnostics, and budget status. |
| 16 | Error messages | Add a malformed prop, invalid runtime, and duplicate symbol. | Error contains stable code, file, line/column, code frame, and hint. |
| 17 | Editor/LSP behavior | Test completion, hover/diagnostics, go-to-definition, formatting, snippets, and multiline props. | Editor behavior matches compiler syntax with no false unknown-member errors. |
| 18 | Schemas/validation | Submit invalid and valid data through existing form/API validation and a typed endpoint schema. | Client/server errors agree and valid types are inferred. |
| 19 | Authentication | Test session login/logout, protected middleware, OAuth/passkey integrations used by your apps, and route security metadata. | Existing SSO flows remain unchanged and protected routes reject anonymous users. |
| 20 | Multi-tenancy | Configure subdomain, domain, and path tenancy separately. | `ctx.tenant` resolves correctly and tenant-scoped operations reject missing tenancy. |
| 21 | Jobs/cron/workflows | Queue priority jobs, duplicate idempotency keys, retries, cancellation, concurrency, workflow steps, and cron aliases. | Priority/order/retries are deterministic; duplicates do not create extra queued work. |
| 22 | Realtime | Connect an authenticated room, publish through the existing bus/Redis bridge, disconnect, and reconnect. | Authorization, delivery, cleanup, and horizontal bridge behavior remain correct. |
| 23 | Plugins | Register pre/normal/post plugins with `before`/`after`, AST/code transforms, diagnostics, server and build hooks. | Order is deterministic; duplicates/cycles fail with stable errors. |
| 24 | Infrastructure adapters | Run the same built app through the existing Bun and Node/fetch adapter paths; test configured deployment adapter metadata. | Request/response semantics and build report remain consistent. |
| 25 | Build caching/HMR | Change CSS, a leaf component, a shared component, server code, and route structure separately. | Only affected work is rebuilt; structural changes trigger the correct reload level. |
| 26 | Compatibility/migrations | Upgrade a copied legacy app twice. | First run changes only required files; second run is source-idempotent; backup/report exist. |
| 27 | Testing | Run the full package suite and the three upgraded app suites. | All old regressions plus new 0.3 tests pass. |
| 28 | Performance budgets | Set deliberately small HTML/JS/CSS/image budgets, then realistic budgets. | Build warns/fails according to policy, then passes with realistic limits. |
| 29 | Observability | Enable tracing and `serverTiming`; make a request containing nested spans. | Trace records include duration/status/attributes and response has `Server-Timing`. |
| 30 | Component architecture | Render primitives, behavior components, layouts, and product components in light/dark/responsive states. | Props/events/slots/accessibility remain consistent and app overrides still win. |
| 31 | Design tokens | Audit `--wire-*` usage and switch themes. | Components use semantic tokens and no required token is undefined. |
| 32 | Accessibility | Compile missing-alt markup and run toolbar keyboard/focus/ARIA checks. | Compile-time and runtime accessibility findings appear without duplicates or false positives. |
| 33 | Motion/transitions | Exercise existing lifecycle/animation behavior with reduced-motion enabled and disabled. | Motion respects user preference and teardown does not leak listeners/timers. |
| 34 | Documentation | Follow the language, architecture, upgrade, and this checklist from a clean clone. | Commands/examples match actual APIs and produce the documented result. |
| 35 | AI-friendly metadata | Inspect language spec exports, structured diagnostics, component metadata, route manifest, and build report. | Tools can consume JSON/typed metadata without parsing human logs. |
| 36 | Feature flags | Resolve boolean/function flags for two users/tenants and across async work. | Context does not leak and experimental features stay disabled by default. |
| 37 | Public APIs | Search applications/plugins for imports containing `/src/` or undocumented internals. | Consumers use only exported package entry points. |
| 38 | Configuration | Layer defaults, profile, environment, project config, and route overrides; run `config --explain`. | Final value and its source are clear; invalid settings report paths. |
| 39 | Gateway | Test host/path routing, forward auth with app + path, WebSockets, timeouts, headers, and development/production origins. | Existing domains work; internal service resolution avoids hardcoded production URLs. |
| 40 | Release gates | Run `verify:0.3`, full checks, app upgrades, builds, editor package, and release prepare. | Version topology, migration uniqueness, lockfile, docs, tests, and artifacts all pass before publish. |
## Recommended rollout
1. Upgrade a disposable copy of the least complex application.
2. Compare generated HTML, browser JavaScript, routes, gateway behavior, and screenshots against its current production version.
3. Upgrade the second and third applications only after the first passes this checklist.
4. Publish 0.3.0 as a prerelease first if the three applications exercise materially different subsystems.
docs/UPGRADE-0.3.md
+144
View File
@@ -0,0 +1,144 @@
# 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.
docs/WRN-LANGUAGE-SPEC-1.0.md
+189
View File
@@ -0,0 +1,189 @@
# WRN Language Specification 1.0
This document is the canonical public contract for `.wrn` files in WRNexusJS 0.3.x.
The executable source of truth is `@wrnexus/syntax`; the compiler re-exports its
parser and AST for compatibility.
## Compatibility promise
WRNexusJS 0.3 keeps all previously supported declarations, including:
- `page`, `component`, and `layout` roots
- `layout = "..."`, `types`, `props`, `state`, `view`, `seo`, and `style`
- `functions`, `lifecycle`, and `watch`
- `api`, `ssr`, `client`, and `realtime`
- `data-for`, `{#each}`, conditions, interpolations, events, and `class:*`
New syntax is additive. Existing projects do not need to adopt it immediately.
Dynamic attribute expressions should be single-quoted so braces remain unambiguous:
```wrn
<FeatureList items='{items}' primaryAction='{{ label: "Open" }}' />
```
The 0.3 updater only rewrites simple, unambiguous `prop={expression}` values. Nested
brace expressions are left unchanged and reported for manual review.
## File structure
A file may begin with TypeScript imports and must contain one root declaration:
```wrn
import { appUrl } from "@wrnexus/helpers";
page Home {
view {
<main>Home</main>
}
}
```
Root names are JavaScript identifiers. The valid root kinds are `page`, `component`,
and `layout`.
## Execution declarations
```wrn
runtime = "universal"
hydrate = "visible"
```
Runtime targets:
- `server`: never emits an interactive browser scope
- `client`: intended for browser execution
- `universal`: server-rendered and optionally hydrated
Hydration strategies:
- `load`
- `idle`
- `visible`
- `interaction`
- `none`
- `media:<media-query>`
`client = "..."` remains an alias for a hydration declaration. The existing
`client { ... }` mode block remains valid.
## Props and state
```wrn
props {
title: string
count: number = 0
enabled: boolean = false
}
state open: boolean = false
```
A prop without an initializer is required. State always requires an initializer.
Typed initializers are validated when their literal type can be determined.
## Computed values and effects
```wrn
computed {
total = price * quantity
label = `${quantity} items`
}
effect {
document.title = label
}
```
Computed values are dependency-tracked and cached. Effects rerun after a batched
reactive update when a referenced state or computed value changes.
## Data loading and actions
```wrn
load server {
return await repository.list(ctx.tenant?.id)
}
load client {
return await fetch("/api/live").then((response) => response.json())
}
action save(input) {
return await repository.save(input)
}
```
Server and client loaders are exported separately by the compiler. Named actions
are exported individually and through `__wrnexusActions` for framework adapters.
## Security metadata
```wrn
security {
auth = "required"
csrf = "true"
roles = "admin,editor"
rateLimit = "strict"
}
```
The compiler exports this metadata as `__wrnexusSecurity`. Runtime middleware or
plugins can enforce organization-specific policy. Metadata does not replace global
security headers or API validation.
## View syntax
```wrn
view {
<button
type="button"
class:opacity-50='loading'
@click='save()'
>
{loading ? "Saving..." : title}
</button>
}
```
Supported view features include:
- HTML and component tags
- escaped `{expression}` interpolation
- event attributes such as `@click`, `@window:scroll`, and `@document:click`
- conditional `class:*` attributes
- `data-show`
- `data-for="item, index in items"`, optionally keyed with `key item.id` or `data-key="item.id"`
- `{#if}`, `{:else if}`, `{:else}`, and `{/if}`
- `{#each items as item, index key item.id}`, optional keys, and optional `{:empty}` branches
- comments and scoped styles
Output is escaped by default. Explicit raw HTML APIs must be treated as security
boundaries.
## Stable diagnostics
Canonical diagnostics use stable identifiers such as:
- `WRN-PARSE-001`
- `WRN-PARSE-MEMBER`
- `WRN-PROP-INITIALIZER`
- `WRN-SYMBOL-DUPLICATE`
- `WRN-HYDRATE-STRATEGY`
- `WRN-RUNTIME-TARGET`
- `WRN-RUNTIME-SERVER-INTERACTIVE`
- `WRN-A11Y-001`
Compiler, doctor, build, and future language-server integrations should consume
`@wrnexus/syntax` diagnostics rather than implementing independent parsers.
## AST ownership
The canonical packages are:
```text
@wrnexus/syntax lexer, parser, AST, specification, diagnostics
@wrnexus/compiler code generation and compatibility re-exports
```
Direct imports from compiler internals are deprecated. Public imports from
`@wrnexus/compiler` continue to work in 0.3.x.