page wrnexusssr {
  seo {
    title = "@wrnexus/ssr"
    description = "Secure HTML document rendering and SEO metadata."
  }

  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/ssr</span></nav><section class="doc-intro"><span class="eyebrow">Runtime · Package reference</span><h1>@wrnexus/ssr</h1><p>Secure HTML document rendering and SEO metadata.</p><div class="doc-meta"><span>v0.3.2</span><span>Private registry</span><span>Runtime</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/ssr@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>Server-side rendering: wraps a page's HTML body in a complete HTML document with a metadata-driven <code>&lt;head&gt;</code>.</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>Pages in WRNexusJS return an HTML string for the body. <code>@wrnexus/ssr</code> takes that body and produces a full HTML document — building the <code>&lt;head&gt;</code> from page metadata and global SEO defaults, resolving canonical/Open Graph/Twitter tags, and injecting module preloads and <code>&lt;script type=&quot;module&quot;&gt;</code> tags. It is deliberately server-only: nothing in this package touches the DOM or ships to the browser, keeping server code genuinely server-only. Reach for it on the server when turning a rendered page body into a response document.</p>
<pre data-language="bash"><code>bun add @wrnexus/ssr</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>The package has a single export.</p>
<h4 id="renderdocument-opts-renderoptions-string"><code>renderDocument(opts: RenderOptions): string</code></h4>
<p>Renders a complete HTML document as a string, beginning with <code>&lt;!doctype html&gt;</code>. All metadata is HTML-escaped (via <code>escapeHtml</code> from <code>@wrnexus/core</code>), so a malicious title or description cannot break out of its element or attribute. The body is placed inside <code>&lt;div id=&quot;app&quot;&gt;</code>.</p>
<h4 id="renderoptions"><code>RenderOptions</code></h4>
<div class="table-wrap"><table>
<thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
<tbody><tr><td><code>meta</code></td><td><code>PageMeta</code></td><td>Page metadata for the document head (required).</td></tr><tr><td><code>body</code></td><td><code>string</code></td><td>Rendered HTML for the body, placed inside <code>#app</code> (required).</td></tr><tr><td><code>seo</code></td><td><code>SeoConfig</code></td><td>Global SEO defaults, typically from <code>wrnexus.config.ts</code>.</td></tr><tr><td><code>url</code></td><td><code>URL</code></td><td>Current request URL, used to resolve canonical/Open Graph URLs.</td></tr><tr><td><code>scripts</code></td><td><code>string[]</code></td><td>URLs of <code>&lt;script type=&quot;module&quot;&gt;</code> tags to load (e.g. per-island chunks or the reactive runtime). Each also gets a <code>&lt;link rel=&quot;modulepreload&quot;&gt;</code>.</td></tr><tr><td><code>defaultTitle</code></td><td><code>string</code></td><td>Default document title used when <code>meta.title</code> is absent.</td></tr><tr><td><code>extraHead</code></td><td><code>string</code></td><td>Raw HTML injected at the end of <code>&lt;head&gt;</code> (trusted, framework-controlled — not escaped).</td></tr><tr><td><code>extraBody</code></td><td><code>string</code></td><td>Raw HTML injected at the end of <code>&lt;body&gt;</code> (trusted, framework-controlled — not escaped).</td></tr><tr><td><code>htmlAttrs</code></td><td><code>string</code></td><td>Attributes for the <code>&lt;html&gt;</code> element, e.g. <code> data-theme=&quot;dark&quot;</code> (trusted).</td></tr></tbody></table></div>
<p><code>PageMeta</code> and <code>SeoConfig</code> come from <code>@wrnexus/core</code>. <code>PageMeta</code> is an alias of <code>SeoConfig</code>, whose fields are all optional:</p>
<pre data-language="ts"><code>type SeoConfig = &#123;
  title?: string;
  titleTemplate?: string; // e.g. &quot;%s — My Site&quot;; %s is replaced with the page title
  description?: string;
  canonical?: string;
  canonicalBase?: string; // origin used to absolutize canonical/image URLs
  robots?: string;
  keywords?: string | string[];
  image?: string;
  siteName?: string;
  type?: string; // Open Graph type; defaults to &quot;website&quot;
  locale?: string;
  twitterCard?: string; // defaults to &quot;summary&quot;
  twitterSite?: string;
  themeColor?: string;
&#125;;</code></pre>
<h4 id="metadata-resolution">Metadata resolution</h4>
<p><code>renderDocument</code> merges page metadata (<code>meta</code>) over global defaults (<code>seo</code>), field by field, so per-page values win. Notable behavior:</p>
<ul>
<li><strong>Title</strong>: uses <code>meta.title</code>, else <code>seo.title</code>, else <code>defaultTitle</code>, else <code>&quot;WRNexusJS&quot;</code>. When the page sets its own title and <code>seo.titleTemplate</code> contains <code>%s</code>, the template is applied.</li>
<li><strong>Canonical / image URLs</strong>: resolved against <code>canonicalBase</code> (or the request <code>url</code>'s origin) into absolute URLs when possible.</li>
<li><strong>Keywords</strong>: an array is joined with <code>&quot;, &quot;</code>.</li>
<li><strong>Emitted tags</strong>: <code>&lt;title&gt;</code>, and as applicable <code>description</code>, <code>robots</code>, <code>keywords</code>, <code>theme-color</code>, and <code>canonical</code> link, plus Open Graph (<code>og:title</code>, <code>og:description</code>, <code>og:type</code>, <code>og:url</code>, <code>og:site_name</code>, <code>og:locale</code>, <code>og:image</code>) and Twitter (<code>twitter:card</code>, <code>twitter:title</code>, <code>twitter:description</code>, <code>twitter:image</code>, <code>twitter:site</code>) meta tags. The document always includes <code>charset</code>, <code>viewport</code>, and a <code>/favicon.ico</code> icon link.</li>
</ul>
<h3 id="usage">Usage</h3>
<h4 id="render-an-seo-ready-application-page">Render an SEO-ready application page</h4>
<pre data-language="ts"><code>import &#123; renderDocument &#125; from &quot;@wrnexus/ssr&quot;;

const html = renderDocument(&#123;
  meta: &#123;
    title: &quot;About Us&quot;,
    description: &quot;Learn more about our team.&quot;,
  &#125;,
  seo: &#123;
    titleTemplate: &quot;%s — Acme&quot;,
    siteName: &quot;Acme&quot;,
    canonicalBase: &quot;https://acme.example&quot;,
    twitterSite: &quot;@acme&quot;,
  &#125;,
  url: new URL(&quot;https://acme.example/about&quot;),
  body: &quot;&lt;h1&gt;About Us&lt;/h1&gt;&quot;,
  scripts: [&quot;/_wire/runtime.js&quot;, &quot;/_wire/islands/about.js&quot;],
  htmlAttrs: ' data-theme=&quot;dark&quot;',
&#125;);

return new Response(html, &#123;
  headers: &#123; &quot;content-type&quot;: &quot;text/html; charset=utf-8&quot; &#125;,
&#125;);</code></pre>
<p>The produced document has <code>&lt;title&gt;About Us — Acme&lt;/title&gt;</code>, the SEO/Open Graph/Twitter tags derived from the merged metadata, a <code>modulepreload</code> link and module <code>&lt;script&gt;</code> for each entry in <code>scripts</code>, and the body wrapped in <code>&lt;div id=&quot;app&quot;&gt;</code>.</p>
<h4 id="add-trusted-framework-assets-and-boot-data">Add trusted framework assets and boot data</h4>
<p>Use <code>extraHead</code> and <code>extraBody</code> only for HTML generated by your application or the framework. User-provided values belong in <code>meta</code>, where they are escaped.</p>
<pre data-language="ts"><code>const html = renderDocument(&#123;
  meta: &#123; title: &quot;Dashboard&quot;, robots: &quot;noindex&quot; &#125;,
  body: dashboardHtml,
  url: ctx.url,
  extraHead: '&lt;link rel=&quot;stylesheet&quot; href=&quot;/_wrnexus/admin.css&quot;&gt;',
  extraBody: `&lt;script type=&quot;application/json&quot; id=&quot;boot&quot;&gt;$&#123;JSON.stringify(bootData).replaceAll(&quot;&lt;&quot;, &quot;\\u003c&quot;)&#125;&lt;/script&gt;`,
&#125;);

return new Response(html, &#123; headers: &#123; &quot;content-type&quot;: &quot;text/html; charset=utf-8&quot; &#125; &#125;);</code></pre>
<h3 id="requirements-notes">Requirements / Notes</h3>
<ul>
<li><strong>Server-only.</strong> This module never imports or touches the DOM and is safe to keep out of client bundles.</li>
<li><strong>Depends on [<code>@wrnexus/core</code>](../core)</strong> for <code>escapeHtml</code> and the <code>PageMeta</code> / <code>SeoConfig</code> types.</li>
<li><strong>Bun-only</strong> — like the rest of WRNexusJS, this package targets the Bun runtime (Node is not supported).</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>import &#123; PageMeta, SeoConfig &#125; from '@wrnexus/core';

/**
 * @wrnexus/ssr — server-side rendering.
 *
 * Pages return an HTML string for the body; this module wraps that body in a
 * full document with a `&lt;head&gt;` built from page metadata. It is intentionally
 * isolated from any client runtime: nothing here touches the DOM or ships to
 * the browser, which keeps &quot;server-only code&quot; genuinely server-only.
 */

interface RenderOptions &#123;
    /** Page metadata for the document head. */
    meta: PageMeta;
    /** Global SEO defaults from `wrnexus.config.ts`. */
    seo?: SeoConfig;
    /** Current request URL, used to resolve canonical/Open Graph URLs. */
    url?: URL;
    /** Rendered HTML for the body (placed inside `#app`). */
    body: string;
    /**
     * URLs of `&lt;script type=&quot;module&quot;&gt;` tags to load (e.g. per-island chunks or
     * the reactive runtime). Only the scripts a page actually needs are passed.
     */
    scripts?: string[];
    /** Optional default document title used when meta.title is absent. */
    defaultTitle?: string;
    /** Raw HTML injected at the end of `&lt;head&gt;` (trusted, framework-controlled). */
    extraHead?: string;
    /** Raw HTML injected at the end of `&lt;body&gt;` (trusted, framework-controlled). */
    extraBody?: string;
    /** Attributes for the `&lt;html&gt;` element, e.g. ` data-theme=&quot;dark&quot;` (trusted). */
    htmlAttrs?: string;
&#125;
/**
 * Render a complete HTML document.
 *
 * Metadata is HTML-escaped so a malicious title/description can never break
 * out of its element or attribute.
 */
declare function renderDocument(opts: RenderOptions): string;
interface StreamRenderOptions extends Omit&lt;RenderOptions, &quot;body&quot;&gt; &#123;
    body: string | Promise&lt;string&gt; | AsyncIterable&lt;string&gt;;
&#125;
/**
 * Stream a complete document while preserving the exact head/body contract of
 * `renderDocument`. Async iterables can flush a shell, primary content, and
 * slower fragments without buffering the entire route.
 */
declare function renderDocumentStream(opts: StreamRenderOptions): ReadableStream&lt;Uint8Array&gt;;
declare function streamDocumentResponse(opts: StreamRenderOptions, init?: ResponseInit): Response;

export &#123; type RenderOptions, type StreamRenderOptions, renderDocument, renderDocumentStream, streamDocumentResponse &#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>Render an SEO-ready application page</h3><pre data-language="ts"><code>import &#123; renderDocument &#125; from &quot;@wrnexus/ssr&quot;;

const html = renderDocument(&#123;
  meta: &#123;
    title: &quot;About Us&quot;,
    description: &quot;Learn more about our team.&quot;,
  &#125;,
  seo: &#123;
    titleTemplate: &quot;%s — Acme&quot;,
    siteName: &quot;Acme&quot;,
    canonicalBase: &quot;https://acme.example&quot;,
    twitterSite: &quot;@acme&quot;,
  &#125;,
  url: new URL(&quot;https://acme.example/about&quot;),
  body: &quot;&lt;h1&gt;About Us&lt;/h1&gt;&quot;,
  scripts: [&quot;/_wire/runtime.js&quot;, &quot;/_wire/islands/about.js&quot;],
  htmlAttrs: ' data-theme=&quot;dark&quot;',
&#125;);

return new Response(html, &#123;
  headers: &#123; &quot;content-type&quot;: &quot;text/html; charset=utf-8&quot; &#125;,
&#125;);</code></pre></article><article class="example-card"><h3>Add trusted framework assets and boot data</h3><pre data-language="ts"><code>const html = renderDocument(&#123;
  meta: &#123; title: &quot;Dashboard&quot;, robots: &quot;noindex&quot; &#125;,
  body: dashboardHtml,
  url: ctx.url,
  extraHead: '&lt;link rel=&quot;stylesheet&quot; href=&quot;/_wrnexus/admin.css&quot;&gt;',
  extraBody: `&lt;script type=&quot;application/json&quot; id=&quot;boot&quot;&gt;$&#123;JSON.stringify(bootData).replaceAll(&quot;&lt;&quot;, &quot;\\u003c&quot;)&#125;&lt;/script&gt;`,
&#125;);

return new Response(html, &#123; headers: &#123; &quot;content-type&quot;: &quot;text/html; charset=utf-8&quot; &#125; &#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="#renderdocument-opts-renderoptions-string">renderDocument(opts: RenderOptions): string</a><a class="toc-level-4" href="#renderoptions">RenderOptions</a><a class="toc-level-4" href="#metadata-resolution">Metadata resolution</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#render-an-seo-ready-application-page">Render an SEO-ready application page</a><a class="toc-level-4" href="#add-trusted-framework-assets-and-boot-data">Add trusted framework assets and boot data</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>
  }
}
