page wrnexuscsr {
  seo {
    title = "@wrnexus/csr"
    description = "Reactive, navigation, and realtime browser runtimes."
  }

  view {
    <div class="docs-shell">
      <SkipLink label="Skip to content" href="#main" class="docs-skip-link" />
      <header class="topbar">
        <a class="brand" href="/"><span>W</span> WRNexusJS</a>
        <nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
        <div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.3.2</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
      </header>
      <div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
      <main class="portal-main docs-layout">
      <article id="main" class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/csr</span></nav><section class="doc-intro"><span class="eyebrow">Frontend · Package reference</span><h1>@wrnexus/csr</h1><p>Reactive, navigation, and realtime browser runtimes.</p><div class="doc-meta"><span>v0.3.2</span><span>Private registry</span><span>Frontend</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/csr@0.3.2</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><blockquote>The browser-side client runtime for WRNexusJS — generic, self-contained JS that hydrates server-rendered pages with reactivity, client-side navigation, and realtime rooms.</blockquote>
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
<h3 id="overview">Overview</h3>
<p><code>@wrnexus/csr</code> holds the three client runtimes that WRNexusJS serves to the browser. Components are authored as <code>.wrn</code> files and rendered on the <strong>server</strong>; this package provides the single, generic runtime that <strong>hydrates</strong> that HTML in the browser — there are no per-component browser bundles. Each runtime is exported as a plain-JS string (no build step, no imports) intended to be served verbatim from a well-known URL:</p>
<ul>
<li><strong>reactive</strong> at <code>/__wrnexus/reactive.js</code> — reactive directives (<code>data-scope</code>, <code>data-text</code>, <code>data-for</code>, …)</li>
<li><strong>nav</strong> at <code>/__wrnexus/nav.js</code> — SPA-style client navigation with graceful fallback</li>
<li><strong>realtime</strong> at <code>/__wrnexus/realtime.js</code> — WebSocket &quot;rooms&quot;, declarative or programmatic</li>
</ul>
<p>The package itself runs on the server (it just returns strings); the strings it returns run in the browser. A dev/prod server (see <code>@wrnexus/core</code>) is responsible for actually serving them.</p>
<pre data-language="bash"><code>bun add @wrnexus/csr</code></pre>
<blockquote>Private package — the machine must be authenticated to the <code>wrnexus</code> npm org</blockquote>
<blockquote>(a read token in <code>~/.npmrc</code>). Requires <strong>Bun</strong> (Node is not supported).</blockquote>
<h3 id="api">API</h3>
<p>All exports come from the package root (<code>@wrnexus/csr</code>). The runtime source is delivered as strings, so the &quot;API&quot; on the server side is small; the real surface is the browser directives/globals each string installs.</p>
<h4 id="runtime-strings">Runtime strings</h4>
<div class="table-wrap"><table>
<thead><tr><th>Export</th><th>Type</th><th>Served at</th><th>Contents</th></tr></thead>
<tbody><tr><td><code>REACTIVE_RUNTIME</code></td><td><code>string</code></td><td><code>/__wrnexus/reactive.js</code></td><td>Reactive directive runtime</td></tr><tr><td><code>NAV_RUNTIME</code></td><td><code>string</code></td><td><code>/__wrnexus/nav.js</code></td><td>Client-side navigation runtime</td></tr><tr><td><code>REALTIME_RUNTIME</code></td><td><code>string</code></td><td><code>/__wrnexus/realtime.js</code></td><td>Realtime rooms runtime</td></tr></tbody></table></div>
<h4 id="accessor-functions">Accessor functions</h4>
<p>Convenience getters that return the same strings.</p>
<pre data-language="ts"><code>getReactiveRuntime(): string   // → REACTIVE_RUNTIME
getNavRuntime(): string        // → NAV_RUNTIME
getRealtimeRuntime(): string   // → REALTIME_RUNTIME</code></pre>
<h4 id="browser-reactive-directives">Browser: reactive directives</h4>
<p>Applied to any subtree containing <code>data-scope</code>. Expressions are parsed by a tiny eval-free evaluator, so a strict CSP with no <code>unsafe-eval</code> works.</p>
<div class="table-wrap"><table>
<thead><tr><th>Directive</th><th>Purpose</th></tr></thead>
<tbody><tr><td><code>data-scope=&quot;count: 0, name: 'x'&quot;</code></td><td>Declare reactive state on a subtree</td></tr><tr><td><code>data-on-&lt;event&gt;=&quot;count++&quot;</code></td><td>Run a statement in scope on a DOM event</td></tr><tr><td><code>data-text=&quot;expr&quot;</code></td><td>Bind an element's <code>textContent</code> to an expression</td></tr><tr><td><code>data-show=&quot;expr&quot;</code></td><td>Toggle visibility (<code>display</code>) on truthiness</td></tr><tr><td><code>data-for=&quot;item in list&quot;</code> (opt. index and <code>key item.id</code>)</td><td>Per-item rendering; stable keys preserve DOM identity during reorder</td></tr><tr><td><code>data-key=&quot;item.id&quot;</code></td><td>Alternative key declaration for <code>data-for</code> templates</td></tr><tr><td><code>&#123;&#123;expr&#125;&#125;</code> or <code>&#123;expr&#125;</code></td><td>Interpolation inside text nodes and attribute values</td></tr><tr><td><code>data-wrnexus-csr=&quot;id&quot;</code></td><td>Target for a generated CSR fetch binding (fetches <code>/__wrnexus/csr?...</code>)</td></tr></tbody></table></div>
<p>Supported expression features: literals, identifiers, member access (<code>a.b</code>, <code>a[b]</code>), function/method calls, arrays, objects, arithmetic, comparison, equality, logical (<code>&amp;&amp; ||</code>), unary (<code>! - +</code>), and ternary. Statements support <code>++</code>/<code>--</code>, assignment operators (<code>= += -= *= /= %=</code>), and bare expression/method calls. Rendering is dependency-tracked: a signal change only re-runs the renderers that actually read it.</p>
<p>Browser globals installed: <code>window.__wrnexusHydrateScopes(root)</code> and <code>window.__wrnexusHydrateCsrFetches(root)</code> — both idempotent, so re-running after a DOM swap or HMR morph is safe. Both run automatically on <code>DOMContentLoaded</code>.</p>
<h4 id="browser-navigation">Browser: navigation</h4>
<p>Intercepts same-origin <code>&lt;a&gt;</code> clicks, fetches the target page, and swaps the <code>#app</code> container in place (via <code>importNode</code> — not <code>innerHTML</code> — so it works under a Trusted-Types CSP), updating history, title, and scroll, then re-hydrates. Cross-origin links, modified clicks, <code>download</code>/<code>data-no-nav</code>/<code>rel=&quot;external&quot;</code>/<code>target</code> links, non-HTML responses, or a missing <code>#app</code> fall back to a full browser navigation.</p>
<ul>
<li>Programmatic navigation: <code>window.__wrnexusNavigate(url)</code></li>
<li>Emits a <code>wrnexus:navigated</code> <code>CustomEvent</code> (<code>detail.url</code>) after each swap</li>
<li>Sends <code>x-wrnexus-nav: 1</code> on fetches so the server can return the page fragment</li>
<li>Appends any <code>/__wrnexus/*</code> runtime scripts the incoming page needs but the current document lacks</li>
</ul>
<h4 id="browser-realtime-rooms">Browser: realtime rooms</h4>
<p>Connects to <code>/realtime/&lt;name&gt;</code> over WebSocket (<code>ws</code>/<code>wss</code> chosen from <code>location.protocol</code>). Two usage modes.</p>
<p>Programmatic API via <code>window.wire</code>:</p>
<pre data-language="ts"><code>wire.room(name): Room          // open (or reuse) a room connection
wire.bindRooms(root?)          // (re)bind declarative [data-room] containers

interface Room &#123;
  name: string;
  send(obj: object | string): Room;         // JSON-stringifies objects; queues until open
  on(type: string, cb): Room;               // filter by msg.type; &quot;*&quot; or a fn = all messages
  on(cb): Room;
  close(): Room;
&#125;</code></pre>
<p>Internal lifecycle messages are emitted to listeners as <code>&#123; type &#125;</code>: <code>__open</code>, <code>__close</code>, <code>__error</code>, and <code>__raw</code> (non-JSON frames, with <code>data</code>). Reconnect uses exponential backoff capped at 5s; queued sends flush on reconnect.</p>
<p>Declarative binding (zero JS) on a <code>data-room=&quot;&lt;name&gt;&quot;</code> container:</p>
<div class="table-wrap"><table>
<thead><tr><th>Attribute</th><th>On</th><th>Purpose</th></tr></thead>
<tbody><tr><td><code>data-room=&quot;&lt;name&gt;&quot;</code></td><td>container</td><td>Connect to room <code>&lt;name&gt;</code></td></tr><tr><td><code>data-room-user=&quot;&lt;id&gt;&quot;</code></td><td>container</td><td>Identify the connection (<code>?user=&lt;id&gt;</code>)</td></tr><tr><td><code>data-room-log</code></td><td>element</td><td>Where incoming messages are appended</td></tr><tr><td><code>&lt;template data-room-item=&quot;&lt;type&gt;&quot;&gt;</code></td><td>template</td><td>Row template for messages of that <code>type</code> (empty = fallback)</td></tr><tr><td><code>%field%</code></td><td>inside template</td><td>Placeholder filled from the message field (text/attr only, HTML-escaped)</td></tr><tr><td><code>data-room-status</code></td><td>element</td><td>Reflects connection state text (<code>connected</code>/<code>disconnected</code>/<code>error</code>)</td></tr><tr><td><code>data-room-status-class</code></td><td>status element</td><td>Base class; a state variant (<code>is-connected</code>, …) is appended</td></tr><tr><td><code>&lt;form data-room-send&gt;</code></td><td>form</td><td>Submits named fields as a JSON message</td></tr><tr><td><code>data-room-reset</code></td><td>form field</td><td>Clears that field after send</td></tr></tbody></table></div>
<p>Rebinds on <code>wrnexus:navigated</code> and closes rooms whose container has left the page.</p>
<h3 id="usage">Usage</h3>
<p>Server side — serve the runtime strings from your router (example with <code>Bun.serve</code>):</p>
<pre data-language="ts"><code>import &#123; getReactiveRuntime, getNavRuntime, getRealtimeRuntime &#125; from &quot;@wrnexus/csr&quot;;

const routes: Record&lt;string, string&gt; = &#123;
  &quot;/__wrnexus/reactive.js&quot;: getReactiveRuntime(),
  &quot;/__wrnexus/nav.js&quot;: getNavRuntime(),
  &quot;/__wrnexus/realtime.js&quot;: getRealtimeRuntime(),
&#125;;

Bun.serve(&#123;
  fetch(req) &#123;
    const body = routes[new URL(req.url).pathname];
    if (body) &#123;
      return new Response(body, &#123;
        headers: &#123; &quot;content-type&quot;: &quot;text/javascript; charset=utf-8&quot; &#125;,
      &#125;);
    &#125;
    return new Response(&quot;Not found&quot;, &#123; status: 404 &#125;);
  &#125;,
&#125;);</code></pre>
<p>Browser side — server-rendered HTML that the reactive runtime hydrates:</p>
<pre data-language="html"><code>&lt;div data-scope=&quot;count: 0, showPassword: false&quot;&gt;
  &lt;button data-on-click=&quot;count++&quot;&gt;+1&lt;/button&gt;
  &lt;span data-text=&quot;count&quot;&gt;&lt;/span&gt;
  &lt;p&gt;Total: &#123;&#123;count&#125;&#125;&lt;/p&gt;
  &lt;input type=&quot;&#123;showPassword ? 'text' : 'password'&#125;&quot; /&gt;
  &lt;button
    data-on-click=&quot;showPassword = !showPassword&quot;
    aria-label=&quot;&#123;showPassword ? 'Hide password' : 'Show password'&#125;&quot;
  &gt;
    Toggle password
  &lt;/button&gt;
&lt;/div&gt;
&lt;script src=&quot;/__wrnexus/reactive.js&quot;&gt;&lt;/script&gt;</code></pre>
<p>State interpolation in ordinary attributes is reactive. The compiler keeps the initial SSR value and emits an internal binding so attributes such as <code>type</code>, <code>aria-label</code>, <code>aria-pressed</code>, <code>class</code>, and <code>href</code> update after state changes.</p>
<p>A realtime chat, fully declarative:</p>
<pre data-language="html"><code>&lt;div data-room=&quot;lobby&quot; data-room-user=&quot;ada&quot;&gt;
  &lt;div data-room-status&gt;&lt;/div&gt;
  &lt;ul data-room-log&gt;&lt;/ul&gt;
  &lt;template data-room-item=&quot;chat&quot;&gt;&lt;li&gt;%user%: %text%&lt;/li&gt;&lt;/template&gt;
  &lt;form data-room-send&gt;
    &lt;input name=&quot;text&quot; data-room-reset /&gt;
    &lt;input type=&quot;hidden&quot; name=&quot;type&quot; value=&quot;chat&quot; /&gt;
    &lt;button&gt;Send&lt;/button&gt;
  &lt;/form&gt;
&lt;/div&gt;
&lt;script src=&quot;/__wrnexus/realtime.js&quot;&gt;&lt;/script&gt;</code></pre>
<p>Or drive a room from code:</p>
<pre data-language="ts"><code>const room = wire.room(&quot;lobby&quot;);
room.on(&quot;chat&quot;, (msg) =&gt; console.log(msg.user, msg.text));
room.send(&#123; type: &quot;chat&quot;, user: &quot;ada&quot;, text: &quot;hi&quot; &#125;);</code></pre>
<h3 id="requirements-notes">Requirements / Notes</h3>
<ul>
<li><strong>Bun-only</strong> on the server (the package integrates with Bun-based WRNexusJS servers); the emitted strings are plain browser JS with no dependencies.</li>
<li>Browser runtimes are <strong>self-contained</strong> (no imports, no build step) and <strong>idempotent</strong>, so re-hydration after navigation or HMR is safe.</li>
<li>Designed for a <strong>strict CSP</strong>: the reactive expression evaluator avoids <code>eval</code>/<code>new Function</code> (no <code>unsafe-eval</code>), and DOM swaps use <code>importNode</code>/attribute writes rather than <code>innerHTML</code> (Trusted-Types friendly).</li>
<li>Peer packages: rendered <code>.wrn</code> components and the serving layer come from <code>@wrnexus/core</code> (the sole dependency); pages are rendered by the WRNexusJS dev/prod server.</li>
</ul></section><section id="api" class="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</p><pre data-language="typescript"><code>/**
 * Browser reactive runtime (Point 2: reactive directives).
 *
 * Served verbatim at `/__wrnexus/reactive.js` for any page that contains a
 * `data-scope`. It is plain browser JS (no build step) and self-contained: it
 * inlines a tiny `signal()` so it has no imports to resolve.
 *
 * Supported directives (this is exactly what the `.wrn` compiler emits):
 *   data-scope=&quot;count: 0, name: 'x'&quot;   declare reactive state on a subtree
 *   data-on-&lt;event&gt;=&quot;count++&quot;          run a statement in scope on an event
 *   data-text=&quot;expr&quot;                   element textContent follows an expression
 *   data-wrn-loop-locals=&quot;base64-json&quot;   preserves SSR &#123;#each&#125; item/index values
 *   data-wrnexus-csr=&quot;id&quot;                 target for generated CSR fetch bindings
 *   &#123;&#123;expr&#125;&#125; or &#123;expr&#125;                 interpolation inside text nodes
 *
 * Expressions are evaluated by a tiny parser instead of `eval`/`new Function`,
 * so production can use a strong CSP without `unsafe-eval`.
 */
declare const REACTIVE_RUNTIME: string;

/**
 * Client-side navigation runtime, served at `/__wrnexus/nav.js`.
 *
 * Progressive enhancement over normal links: intercepts same-origin `&lt;a&gt;`
 * clicks, fetches the target page's HTML, swaps the `#app` container in place,
 * updates history/title/scroll, ensures any framework runtimes the new page
 * needs are present, and re-hydrates.
 *
 * Before replacing the current page, component lifecycle behaviors are
 * explicitly disposed. This ensures `unmount` hooks and watcher cleanups run
 * before the old DOM is removed.
 *
 * Programmatic navigation is exposed as:
 *
 *   window.__wrnexusNavigate(url)
 */
declare const NAV_RUNTIME: string;

/**
 * Client realtime runtime, served at `/__wrnexus/realtime.js`.
 *
 * Two ways to use it — no hand-written WebSocket code either way:
 *
 * 1. Declarative (zero JS). Put `data-room=&quot;&lt;name&gt;&quot;` on a container; the runtime
 *    connects, appends incoming messages to `[data-room-log]` using a
 *    `&lt;template data-room-item=&quot;&lt;type&gt;&quot;&gt;` (fields via `%field%`, HTML-escaped),
 *    reflects connection state on `[data-room-status]`, and sends a
 *    `&lt;form data-room-send&gt;`'s named fields as JSON on submit (fields marked
 *    `data-room-reset` clear after send). Optional `data-room-user` identifies
 *    the connection.
 *
 * 2. Programmatic: `const room = wire.room(&quot;chat&quot;); room.on(&quot;chat&quot;, fn);
 *    room.send(&#123; type: &quot;chat&quot;, text &#125;)`. Handles connect, JSON, reconnect.
 *
 * Rebinds on `wrnexus:navigated` (client-side nav) and closes rooms whose
 * container has left the page.
 */
declare const REALTIME_RUNTIME: string;

/**
 * @wrnexus/csr — the browser reactive runtime.
 *
 * Components are `.wrn` files rendered on the SERVER (see @wrnexus/dev-server)
 * and hydrated in the browser by this single, generic runtime — served once at
 * `/__wrnexus/reactive.js` for any page that contains a `data-scope`. There are
 * no per-component browser bundles: SSR stays cleanly separated from CSR.
 */

/** The reactive runtime served at `/__wrnexus/reactive.js` (plain browser JS). */
declare function getReactiveRuntime(): string;
/** The client-side navigation runtime served at `/__wrnexus/nav.js`. */
declare function getNavRuntime(): string;
/** The realtime client runtime served at `/__wrnexus/realtime.js`. */
declare function getRealtimeRuntime(): string;

export &#123; NAV_RUNTIME, REACTIVE_RUNTIME, REALTIME_RUNTIME, getNavRuntime, getReactiveRuntime, getRealtimeRuntime &#125;;
</code></pre></section><section id="examples" class="examples"><h2>Examples</h2><p>Copy-ready examples from the installed package documentation.</p><div class="example-grid"><article class="example-card"><h3>Server side — serve the runtime strings from your router (example with Bun.serve)</h3><pre data-language="ts"><code>import &#123; getReactiveRuntime, getNavRuntime, getRealtimeRuntime &#125; from &quot;@wrnexus/csr&quot;;

const routes: Record&lt;string, string&gt; = &#123;
  &quot;/__wrnexus/reactive.js&quot;: getReactiveRuntime(),
  &quot;/__wrnexus/nav.js&quot;: getNavRuntime(),
  &quot;/__wrnexus/realtime.js&quot;: getRealtimeRuntime(),
&#125;;

Bun.serve(&#123;
  fetch(req) &#123;
    const body = routes[new URL(req.url).pathname];
    if (body) &#123;
      return new Response(body, &#123;
        headers: &#123; &quot;content-type&quot;: &quot;text/javascript; charset=utf-8&quot; &#125;,
      &#125;);
    &#125;
    return new Response(&quot;Not found&quot;, &#123; status: 404 &#125;);
  &#125;,
&#125;);</code></pre></article><article class="example-card"><h3>Browser side — server-rendered HTML that the reactive runtime hydrates</h3><pre data-language="html"><code>&lt;div data-scope=&quot;count: 0, showPassword: false&quot;&gt;
  &lt;button data-on-click=&quot;count++&quot;&gt;+1&lt;/button&gt;
  &lt;span data-text=&quot;count&quot;&gt;&lt;/span&gt;
  &lt;p&gt;Total: &#123;&#123;count&#125;&#125;&lt;/p&gt;
  &lt;input type=&quot;&#123;showPassword ? 'text' : 'password'&#125;&quot; /&gt;
  &lt;button
    data-on-click=&quot;showPassword = !showPassword&quot;
    aria-label=&quot;&#123;showPassword ? 'Hide password' : 'Show password'&#125;&quot;
  &gt;
    Toggle password
  &lt;/button&gt;
&lt;/div&gt;
&lt;script src=&quot;/__wrnexus/reactive.js&quot;&gt;&lt;/script&gt;</code></pre></article><article class="example-card"><h3>A realtime chat, fully declarative</h3><pre data-language="html"><code>&lt;div data-room=&quot;lobby&quot; data-room-user=&quot;ada&quot;&gt;
  &lt;div data-room-status&gt;&lt;/div&gt;
  &lt;ul data-room-log&gt;&lt;/ul&gt;
  &lt;template data-room-item=&quot;chat&quot;&gt;&lt;li&gt;%user%: %text%&lt;/li&gt;&lt;/template&gt;
  &lt;form data-room-send&gt;
    &lt;input name=&quot;text&quot; data-room-reset /&gt;
    &lt;input type=&quot;hidden&quot; name=&quot;type&quot; value=&quot;chat&quot; /&gt;
    &lt;button&gt;Send&lt;/button&gt;
  &lt;/form&gt;
&lt;/div&gt;
&lt;script src=&quot;/__wrnexus/realtime.js&quot;&gt;&lt;/script&gt;</code></pre></article><article class="example-card"><h3>Or drive a room from code</h3><pre data-language="ts"><code>const room = wire.room(&quot;lobby&quot;);
room.on(&quot;chat&quot;, (msg) =&gt; console.log(msg.user, msg.text));
room.send(&#123; type: &quot;chat&quot;, user: &quot;ada&quot;, text: &quot;hi&quot; &#125;);</code></pre></article></div></section></article>
      <aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-4" href="#runtime-strings">Runtime strings</a><a class="toc-level-4" href="#accessor-functions">Accessor functions</a><a class="toc-level-4" href="#browser-reactive-directives">Browser: reactive directives</a><a class="toc-level-4" href="#browser-navigation">Browser: navigation</a><a class="toc-level-4" href="#browser-realtime-rooms">Browser: realtime rooms</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
    </main>
      <footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.3.2</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
      <BackToTop />
    </div>
  }
}
