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

release: WRNexusJS 0.4.0

Browse Source
This commit is contained in:
Clintchiz
2026-07-27 12:42:18 +05:30
parent 8b728a3e5d
commit 30e5721e84
250 changed files with 10065 additions and 3923 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE-0.4.md
+68
View File
@@ -0,0 +1,68 @@
# WRNexusJS 0.4 architecture
## Goals
WRNexusJS 0.4 keeps the existing SSR-first model while making advanced systems installable without application-owned copies or manual wiring. The framework remains conservative: HTML is rendered on the server, the reactive runtime loads only for reactive pages, and package browser code loads only when its component or markup declares a runtime requirement.
## Request and render path
1. The CLI or development server loads `wrnexus.config.*`.
2. `@wrnexus/plugin` discovers explicit plugins and installed package manifests.
3. Contributions are normalized and validated for duplicate IDs, paths, routes, and migrations.
4. The router combines application and package components/routes/middleware.
5. `.wrn` sources compile through plugin AST/code transforms.
6. SSR renders page and component HTML.
7. Rendered `data-wrnexus-runtime` markers are matched against registered client runtimes.
8. Only referenced runtime scripts are added to the response.
9. CSR navigation loads newly required runtime chunks, calls `mount`, and calls `unmount` before replacing old page content.
## Package contribution model
A package can contribute:
- component directories
- client runtimes
- static or generated assets
- stylesheet entries and Tailwind scan sources
- page, API, and realtime routes
- middleware
- database migrations
- DevToolbar panels
- compiler diagnostics and transforms
- build and server lifecycle hooks
Contributions are declared by a package plugin or by the `wrnexus` field in `package.json`.
## Client runtime rules
A runtime has a stable ID, source entry, loading policy, module/classic format, and singleton policy. Development serves it from `/__wrnexus/assets/`; TypeScript runtime entries are browser-bundled on demand. Production builds emit content-hashed immutable runtime chunks and store their paths in the static server manifest.
Runtime code should register:
```js
window.__wrnexusRuntimes = window.__wrnexusRuntimes || {};
window.__wrnexusRuntimes.example = {
mount(root) {},
unmount(root) {},
};
```
Mount and unmount must be idempotent. Event listeners, observers, audio, timers, and provider widgets must be cleaned up during unmount.
## Package assets and styles
Package assets use validated framework paths and receive correct MIME and `nosniff` headers. Production stores package assets in content-addressed files while preserving their declared public URLs; immutable caching remains opt-in. Package component directories and style sources are automatically added to application stylesheet processing, so apps do not need manual Tailwind `@source` entries for installed systems.
Production stylesheet processing fails closed by default. A Tailwind/PostCSS failure cannot silently ship unprocessed CSS unless the application explicitly selects fallback behavior.
## Package migrations
Packages can register inline SQL, a SQL file, or an ordered directory. Migration names are namespaced by package migration ID and may target the default or a named database. Development applies application and package migrations through the same migration table. Production copies both into the build output.
## Development experience
The development server watches application and workspace package component/runtime/style sources. Package `.wrn` changes invalidate both compiled modules and the stylesheet cache. `wrnexus inspect` exposes packages, plugins, routes, assets, runtimes, styles, migrations, and build reports. DevToolbar receives a platform snapshot and package panels.
## Compatibility
The 0.4 migration removes legacy CAPTCHA script tags, archives manually copied runtime files instead of deleting them, and leaves user-authored application code intact. Existing explicit plugins continue to work and take precedence over automatically discovered plugins with the same name.
docs/IMAGE-STYLES.md
+20 -20
View File
@@ -6,26 +6,26 @@ The self-hosted and managed engines support 18 concrete renderers plus `random`.
## Concrete styles
| Style | Main effect | Suggested use |
| --- | --- | --- |
| `classic` | Dots, crossing lines, glyph jitter | General default pool |
| `collision` | Overlapping coloured glyphs and bars | Medium or hard challenges |
| `snow` | Dense snow-like speckles | Medium challenges |
| `corrosion` | Eroded glyph patches and rust-like noise | Medium or hard challenges |
| `spiderweb` | Connected web lines and nodes | Medium challenges |
| `cross-shadow` | Multi-colour offset shadows | Medium challenges |
| `split` | Horizontally shifted image bands | Medium or hard challenges |
| `split2` | Vertically shifted image strips | Medium or hard challenges |
| `cut` | Slashed and interrupted character strokes | Medium challenges |
| `darts` | Radial lines and target rings | Medium challenges |
| `distortion` | Two-axis sinusoidal distortion | Medium or hard challenges |
| `stitch` | Dashed seams and cross stitches | Easy or medium challenges |
| `striped` | Diagonal and horizontal stripes | Easy or medium challenges |
| `wave` | Strong wave transformation | Medium or hard challenges |
| `grid-noise` | Grid lines and translucent cells | Easy or medium challenges |
| `scribble` | Random-walk line scribbles | Medium challenges |
| `pixel` | Pixel blocks and shifted regions | Medium challenges |
| `broken-lines` | Missing stroke segments and fragments | Medium or hard challenges |
| Style | Main effect | Suggested use |
| -------------- | ----------------------------------------- | ------------------------- |
| `classic` | Dots, crossing lines, glyph jitter | General default pool |
| `collision` | Overlapping coloured glyphs and bars | Medium or hard challenges |
| `snow` | Dense snow-like speckles | Medium challenges |
| `corrosion` | Eroded glyph patches and rust-like noise | Medium or hard challenges |
| `spiderweb` | Connected web lines and nodes | Medium challenges |
| `cross-shadow` | Multi-colour offset shadows | Medium challenges |
| `split` | Horizontally shifted image bands | Medium or hard challenges |
| `split2` | Vertically shifted image strips | Medium or hard challenges |
| `cut` | Slashed and interrupted character strokes | Medium challenges |
| `darts` | Radial lines and target rings | Medium challenges |
| `distortion` | Two-axis sinusoidal distortion | Medium or hard challenges |
| `stitch` | Dashed seams and cross stitches | Easy or medium challenges |
| `striped` | Diagonal and horizontal stripes | Easy or medium challenges |
| `wave` | Strong wave transformation | Medium or hard challenges |
| `grid-noise` | Grid lines and translucent cells | Easy or medium challenges |
| `scribble` | Random-walk line scribbles | Medium challenges |
| `pixel` | Pixel blocks and shifted regions | Medium challenges |
| `broken-lines` | Missing stroke segments and fragments | Medium or hard challenges |
## Random pool
docs/PACKAGE-RUNTIMES-0.4.md
+94
View File
@@ -0,0 +1,94 @@
# Package runtimes and automatic assets
## User experience
Installing an advanced package should be enough:
```bash
bun add @wrnexus/captcha
```
Then use its component:
```wrn
<Captcha type="number" action="signup" />
```
The user does not copy JavaScript, add a public asset, add a script tag, or duplicate the component.
## Declaring a package plugin
```json
{
"name": "@example/maps",
"wrnexus": {
"plugin": {
"plugin": "./src/plugin.ts",
"export": "default",
"factory": true
}
}
}
```
```ts
import { definePlugin } from "@wrnexus/plugin";
export default function mapsPlugin() {
return definePlugin({
name: "@example/maps",
componentDirs: [new URL("../components", import.meta.url).pathname],
clientRuntimes: [
{
id: "maps",
entry: new URL("../client/maps.ts", import.meta.url).pathname,
type: "module",
load: "defer",
singleton: true,
},
],
styleSources: [
{
id: "maps-components",
source: new URL("../components", import.meta.url).pathname,
},
],
});
}
```
The rendered component declares:
```html
<div data-wrnexus-runtime="maps"></div>
```
## Development behavior
- Runtime URL defaults to `/__wrnexus/assets/maps.js`.
- JavaScript files can be served directly.
- TypeScript/TSX entries are bundled for the browser.
- MIME type is JavaScript and `X-Content-Type-Options: nosniff` is set.
- Assets use `no-cache` during development.
- Workspace package sources participate in HMR.
## Production behavior
- Runtime entries are browser-bundled and minified when required.
- The emitted filename includes a SHA-256 content hash.
- The asset is served with an immutable cache policy.
- The final HTML includes the runtime only when its marker appears.
- Multiple instances inject one script.
- Build reports list plugins, runtime chunks, assets, component directories, routes, and migrations.
## CSR navigation
Before replacing `#app`, WRNexusJS calls package `unmount` hooks for runtimes used by the current content. It imports script attributes from the fetched document, loads missing chunks once, then calls `mount` for the new page.
## Security requirements
- Runtime and asset IDs are validated.
- Duplicate IDs and public paths fail startup/build.
- Local package asset paths cannot contain traversal segments.
- Production builds do not rely on application public-directory copies.
- Secrets must remain server-side; browser runtimes receive only public configuration and one-use response tokens.
docs/PACKAGE-UPGRADES-0.4.md
+38
View File
@@ -0,0 +1,38 @@
# Existing package upgrades in 0.4
All 30 packages are aligned to version 0.4.0.
| Package | Added or strengthened capability |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| `@wrnexus/syntax` | syntax version/features, source ranges, diagnostic summaries |
| `@wrnexus/compiler` | compilation cache and dependency graph |
| `@wrnexus/reactive` | watch, async resources, cleanup scopes |
| `@wrnexus/core` | service container, lifecycle, health checks, Problem Details, request IDs, idempotency |
| `@wrnexus/router` | named routes, manifests, reverse URL generation |
| `@wrnexus/ssr` | structured/deduplicated scripts and streaming document output |
| `@wrnexus/csr` | package runtime loading plus mount/unmount lifecycle during navigation |
| `@wrnexus/plugin` | automatic discovery and package components/runtimes/assets/styles/routes/middleware/migrations |
| `@wrnexus/dev-server` | virtual package assets, TypeScript runtime bundling, package HMR, migration integration |
| `@wrnexus/cli` | package-aware builds, inspect commands, system generator, 0.4 migration |
| `@wrnexus/dev-toolbar` | package panels and platform snapshots |
| `@wrnexus/styles` | package scan sources/entries, token and contrast audits, fail-closed production processing |
| `@wrnexus/test` | request/context helpers, JSON/problem assertions, deferred/wait utilities, cookie jar |
| `@wrnexus/db` | ordered migration lists, cursor pagination, optimistic updates, tenant/soft-delete helpers |
| `@wrnexus/queue` | pluggable durable store, leases, priorities, retries, dead letters |
| `@wrnexus/pubsub` | resilient delivery wrapper and expiring presence channels |
| `@wrnexus/uploader` | filename isolation, content inspection, checksums, policies, signed file tokens |
| `@wrnexus/encryption` | versioned encrypted payloads and rotatable keyrings |
| `@wrnexus/jwt` | key-ID signing, verification keyrings, safe decoding |
| `@wrnexus/oauth` | state/PKCE storage, refresh, OIDC discovery, safe return URLs |
| `@wrnexus/authz` | explainable authorization decisions, owner policies, compositions, filtering |
| `@wrnexus/captcha` | package-managed component/runtime, advanced challenges, page gates, audio, image styles |
| `@wrnexus/validation` | async cross-field refinements, async request parsing, OpenAPI conversion |
| `@wrnexus/i18n` | fallback chains, coverage reporting, locale formatters, plural message formatting |
| `@wrnexus/ui` | component metadata access and reference audits |
| `@wrnexus/helpers` | retry/backoff, abortable sleep, timeout, stable JSON, safe parsing |
| `@wrnexus/tracking` | sampled/batched telemetry pipeline and sink abstraction |
| `@wrnexus/ai` | provider-neutral client, fallback providers, usage metadata |
| `@wrnexus/mobile` | deep links, offline task queue, environment detection |
| `@wrnexus/native` | capability manifests, target inspection, permission manager |
These additions preserve existing public APIs. New advanced modules are exported from each package root.
docs/TEST-CHECKLIST-0.4.md
+57
View File
@@ -0,0 +1,57 @@
# WRNexusJS 0.4 test checklist
## Automated
Run from the repository root:
```bash
bun install
bun run verify:0.4
bun run validate:0.4
```
`validate:0.4` performs:
1. structural release verification;
2. TypeScript checking;
3. ESLint;
4. all package tests;
5. Prettier verification;
6. 0.4 integration tests;
7. basic application tests and production build;
8. component showcase generation, tests, and build;
9. CAPTCHA showcase tests and build;
10. managed CAPTCHA service tests.
## Package runtime
- Package absent and marker absent: no runtime script.
- Package installed but component unused: no runtime script.
- One or many components used: one runtime script.
- Script has correct MIME and `nosniff` headers.
- TypeScript runtime entries compile in development.
- Production runtime filename is content hashed.
- CSR navigation to a runtime page loads and mounts it.
- Navigation away calls unmount and removes listeners/timers.
- Runtime and asset public-path collisions fail clearly.
## CAPTCHA
- No application public copy of `captcha.js` exists.
- No manual script tag exists.
- Number, alphabet, alphanumeric, calculation, audio, image, and not-robot modes work.
- Compact, normal, and big layouts work at mobile and desktop widths.
- Listen can be hidden or shown.
- Disturbance values 25–75 affect image difficulty.
- All image styles and random pools render.
- Protected page grants and redirects after verification.
- Validated form rejects invalid fields and unverified CAPTCHA.
- Tokens expire, are single use, and are action/host bound.
## Migration
- Updating an old app creates a backup.
- Legacy CAPTCHA script tags are removed once.
- Legacy runtime files are archived, not silently lost.
- Re-running the migration is idempotent.
- Existing deployed apps continue to build.
docs/UPGRADE-0.4.md
+54
View File
@@ -0,0 +1,54 @@
# Upgrade to WRNexusJS 0.4.0
## Recommended upgrade
```bash
bun add -D @wrnexus/cli@0.4.0
bun x wrnexus update . --version=0.4.0
```
For this monorepo source bundle:
```bash
bun install
bun run verify:0.4
bun run validate:0.4
```
## CAPTCHA migration
Before 0.4, CAPTCHA integrations could contain copied files such as:
- `public/assets/wrnexus/captcha.js`
- `public/__wrnexus/captcha.js`
- a manually copied `Captcha.wrn`
- an application-authored `<script src="...captcha.js">`
The 0.4 updater:
1. removes known legacy CAPTCHA script tags from `.wrn` files;
2. archives public runtime copies under `.wrnexus/legacy-assets/0.4.0/`;
3. preserves customized files in the backup created before migration;
4. records the migration at `.wrnexus/migrations/0.4.0.json`.
After updating, keep `@wrnexus/captcha` in application dependencies and use `<Captcha />`. Its component and browser runtime are discovered automatically.
## Package authors
Add a `wrnexus.plugin` package manifest or manifest contributions. Ensure IDs are stable and globally unique. Client runtime code must expose idempotent `mount` and `unmount` functions. Use package migrations for schema required by the package instead of asking applications to copy migration files.
## Compatibility checks
Run:
```bash
wrnexus doctor .
wrnexus inspect packages .
wrnexus inspect plugins .
wrnexus inspect runtimes .
wrnexus inspect assets .
wrnexus inspect routes .
wrnexus inspect migrations .
```
Production style processing now fails the build when the configured processor fails. Install the application’s Tailwind/PostCSS dependencies before building.