release: WRNexusJS 0.4.0

2026-07-27 12:42:18 +05:30
parent 8b728a3e5d
commit 30e5721e84
250 changed files with 10065 additions and 3923 deletions
@@ -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.