@ozsarman/clarityjs 0.6.0

package/src/ssr.js

@@ -0,0 +1,621 @@
+/**
+ * Clarity.js — Server-Side Rendering
+ *
+ * Provides renderToString() and renderToStaticHTML() for server environments.
+ * Components run inside a lightweight fake DOM; effects flush synchronously.
+ * The result is an HTML string plus serialised signal state for client hydration.
+ *
+ * Quick start:
+ *
+ *   import { compile }         from '@ozsarman/clarityjs';
+ *   import { renderToString }  from '@ozsarman/clarityjs/ssr';
+ *
+ *   // 1. Compile the .clarity source with runtimePath pointing to ssr-runtime.js
+ *   const { code } = compile(src, { runtimePath: './ssr-runtime.js' });
+ *
+ *   // 2. Import the compiled component (or pass the function directly)
+ *   const { MyComponent } = await import('./MyComponent.server.js');
+ *
+ *   // 3. Render
+ *   const { html, state } = renderToString(MyComponent, { title: 'Hello' });
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+// ─── HTML helpers ─────────────────────────────────────────────────────────────
+
+const _ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+export function escapeHTML(s)  { return String(s ?? '').replace(/[&<>"']/g, c => _ESC[c]); }
+export function escapeAttr(s)  { return String(s ?? '').replace(/[&<>"']/g, c => _ESC[c]); }
+
+const VOID_ELEMENTS = new Set([
+  'area','base','br','col','embed','hr','img','input',
+  'link','meta','param','source','track','wbr',
+]);
+const BOOLEAN_ATTRS = new Set([
+  'checked','disabled','readonly','required','multiple',
+  'selected','autofocus','autoplay','controls','hidden',
+  'loop','muted','open','defer','async',
+]);
+
+// ─── SSR Style proxy ──────────────────────────────────────────────────────────
+// Mirrors the browser CSSStyleDeclaration enough for generated code.
+
+class SSRStyle {
+  #props = {};
+  #owner;
+  constructor(owner) { this.#owner = owner; }
+  get cssText() {
+    return Object.entries(this.#props).map(([k, v]) => `${k}:${v}`).join(';');
+  }
+  set cssText(v) {
+    this.#props = {};
+    if (!v) return;
+    for (const part of String(v).split(';')) {
+      const idx = part.indexOf(':');
+      if (idx < 0) continue;
+      const key = part.slice(0, idx).trim();
+      const val = part.slice(idx + 1).trim();
+      if (key) this.#props[key] = val;
+    }
+    this.#owner._syncStyle();
+  }
+  setProperty(k, v) { this.#props[k] = v; this.#owner._syncStyle(); }
+  removeProperty(k) { delete this.#props[k]; this.#owner._syncStyle(); }
+}
+
+// ─── SSR Node classes ─────────────────────────────────────────────────────────
+
+class SSRTextNode {
+  nodeType = 3;
+  _parent  = null;
+  #text;
+  constructor(text) { this.#text = String(text ?? ''); }
+  get parentNode()     { return this._parent; }
+  get textContent()    { return this.#text; }
+  set textContent(v)   { this.#text = String(v ?? ''); }
+  get data()           { return this.#text; }
+  set data(v)          { this.#text = String(v ?? ''); }
+  toHTML()             { return escapeHTML(this.#text); }
+}
+
+class SSRComment {
+  nodeType  = 8;
+  _parent   = null;
+  #text;
+  constructor(text) { this.#text = String(text ?? ''); }
+  get parentNode()  { return this._parent; }
+  get textContent() { return ''; }
+  toHTML()          { return `<!--${this.#text}-->`; }
+}
+
+class SSRFragment {
+  nodeType  = 11;
+  _parent   = null;
+  _children = [];
+
+  appendChild(child) {
+    if (!child) return child;
+    if (child instanceof SSRFragment) {
+      for (const c of [...child._children]) this.appendChild(c);
+      return child;
+    }
+    child._parent = this;
+    this._children.push(child);
+    return child;
+  }
+  insertBefore(newNode, refNode) {
+    if (!refNode) return this.appendChild(newNode);
+    const idx = this._children.indexOf(refNode);
+    if (idx >= 0) {
+      newNode._parent = this;
+      this._children.splice(idx, 0, newNode);
+    } else {
+      this.appendChild(newNode);
+    }
+    return newNode;
+  }
+  removeChild(child) {
+    const idx = this._children.indexOf(child);
+    if (idx >= 0) { this._children.splice(idx, 1); child._parent = null; }
+    return child;
+  }
+  get textContent() { return this._children.map(c => c.textContent ?? '').join(''); }
+  toHTML() { return this._children.map(c => c.toHTML?.() ?? '').join(''); }
+}
+
+export class SSRElement {
+  nodeType = 1;
+  _parent  = null;
+  #tag;
+  #attrs   = new Map();
+  #children = [];
+  #style;
+  // Storage for AI contract — collected during renderToString
+  __clarity_ai__      = null;
+  __clarity_cleanup__ = null;
+  __clarity_mount__   = null;
+
+  constructor(tag) {
+    this.#tag   = String(tag).toLowerCase();
+    this.#style = new SSRStyle(this);
+  }
+
+  // ── Hierarchy ──────────────────────────────────────────────────────────────
+
+  get tagName()  { return this.#tag.toUpperCase(); }
+  get parentNode() { return this._parent; }
+  get firstChild() { return this.#children[0] ?? null; }
+  get lastChild()  { return this.#children[this.#children.length - 1] ?? null; }
+  get childNodes() { return [...this.#children]; }
+  // Getter for children (non-comment non-text)
+  get children() { return this.#children.filter(c => c.nodeType === 1); }
+
+  appendChild(child) {
+    if (!child) return child;
+    if (child instanceof SSRFragment) {
+      for (const c of [...child._children]) this.appendChild(c);
+      return child;
+    }
+    if (child._parent) child._parent.removeChild(child);
+    child._parent = this;
+    this.#children.push(child);
+    return child;
+  }
+
+  insertBefore(newNode, refNode) {
+    if (!refNode) return this.appendChild(newNode);
+    if (newNode instanceof SSRFragment) {
+      for (const c of [...newNode._children]) this.insertBefore(c, refNode);
+      return newNode;
+    }
+    if (newNode._parent) newNode._parent.removeChild(newNode);
+    const idx = this.#children.indexOf(refNode);
+    if (idx >= 0) {
+      newNode._parent = this;
+      this.#children.splice(idx, 0, newNode);
+    } else {
+      this.appendChild(newNode);
+    }
+    return newNode;
+  }
+
+  removeChild(child) {
+    const idx = this.#children.indexOf(child);
+    if (idx >= 0) { this.#children.splice(idx, 1); child._parent = null; }
+    return child;
+  }
+
+  replaceChild(newChild, oldChild) {
+    const idx = this.#children.indexOf(oldChild);
+    if (idx >= 0) {
+      if (newChild._parent) newChild._parent.removeChild(newChild);
+      newChild._parent   = this;
+      oldChild._parent   = null;
+      this.#children[idx] = newChild;
+    }
+    return oldChild;
+  }
+
+  contains(node) {
+    let n = node;
+    while (n) { if (n === this) return true; n = n._parent; }
+    return false;
+  }
+
+  // ── Attributes ─────────────────────────────────────────────────────────────
+
+  setAttribute(k, v)   { this.#attrs.set(String(k), v); }
+  removeAttribute(k)   { this.#attrs.delete(String(k)); }
+  hasAttribute(k)      { return this.#attrs.has(String(k)); }
+  getAttribute(k)      { return this.#attrs.get(String(k)) ?? null; }
+
+  // Common property shortcuts generated by Clarity codegen
+  get className()  { return this.getAttribute('class') ?? ''; }
+  set className(v) { this.setAttribute('class', v ?? ''); }
+  get id()         { return this.getAttribute('id') ?? ''; }
+  set id(v)        { this.setAttribute('id', String(v)); }
+  get href()       { return this.getAttribute('href') ?? ''; }
+  set href(v)      { this.setAttribute('href', String(v)); }
+  get src()        { return this.getAttribute('src') ?? ''; }
+  set src(v)       { this.setAttribute('src', String(v)); }
+  get value()      { return this.getAttribute('value') ?? ''; }
+  set value(v)     { this.setAttribute('value', String(v ?? '')); }
+  get checked()    { return this.hasAttribute('checked'); }
+  set checked(v)   { v ? this.setAttribute('checked', '') : this.removeAttribute('checked'); }
+  get disabled()   { return this.hasAttribute('disabled'); }
+  set disabled(v)  { v ? this.setAttribute('disabled', '') : this.removeAttribute('disabled'); }
+
+  // ── Style ──────────────────────────────────────────────────────────────────
+
+  get style() { return this.#style; }
+  _syncStyle() {
+    const css = this.#style.cssText;
+    if (css) this.#attrs.set('style', css);
+    else this.#attrs.delete('style');
+  }
+
+  // ── Text content ───────────────────────────────────────────────────────────
+
+  get textContent() { return this.#children.map(c => c.textContent ?? '').join(''); }
+  set textContent(v) {
+    this.#children = [];
+    const s = String(v ?? '');
+    if (s !== '') {
+      const t = new SSRTextNode(s);
+      t._parent = this;
+      this.#children.push(t);
+    }
+  }
+
+  get innerHTML() { return this.#children.map(c => c.toHTML?.() ?? '').join(''); }
+  set innerHTML(v) {
+    // Very naive — just treat as raw HTML text in an SSR text node
+    this.#children = [];
+    if (v) {
+      // Wrap in a raw node that doesn't escape
+      const raw = { nodeType: 3, textContent: v, _parent: this, toHTML: () => String(v) };
+      this.#children.push(raw);
+    }
+  }
+
+  // ── Events (no-ops in SSR) ─────────────────────────────────────────────────
+
+  addEventListener()    {}
+  removeEventListener() {}
+  dispatchEvent()       { return true; }
+
+  // ── querySelector (used by some runtime helpers) ───────────────────────────
+
+  querySelector()    { return null; }
+  querySelectorAll() { return []; }
+
+  // ── Serialisation ──────────────────────────────────────────────────────────
+
+  toHTML() {
+    const parts = [];
+    for (const [k, v] of this.#attrs) {
+      if (v === false || v === null || v === undefined) continue;
+      if (v === true || (typeof v === 'string' && v === '' && BOOLEAN_ATTRS.has(k))) {
+        parts.push(k);
+      } else if (BOOLEAN_ATTRS.has(k) && v) {
+        parts.push(k);
+      } else {
+        parts.push(`${k}="${escapeAttr(v)}"`);
+      }
+    }
+    const attrStr = parts.length ? ' ' + parts.join(' ') : '';
+    if (VOID_ELEMENTS.has(this.#tag)) return `<${this.#tag}${attrStr}>`;
+    const inner = this.#children.map(c => c.toHTML?.() ?? escapeHTML(String(c))).join('');
+    return `<${this.#tag}${attrStr}>${inner}</${this.#tag}>`;
+  }
+}
+
+// ─── SSR document factory ─────────────────────────────────────────────────────
+
+function createSSRDocument() {
+  const body = new SSRElement('body');
+  const head = new SSRElement('head');
+  return {
+    body,
+    head,
+    createElement:           (tag)  => new SSRElement(tag),
+    createElementNS:         (_ns, tag) => new SSRElement(tag),
+    createTextNode:          (text) => new SSRTextNode(text),
+    createComment:           (text) => new SSRComment(text),
+    createDocumentFragment:  ()     => new SSRFragment(),
+    getElementById:          ()     => null,
+    querySelector:           ()     => null,
+    querySelectorAll:        ()     => [],
+    addEventListener:        ()     => {},
+    removeEventListener:     ()     => {},
+    // For portal support — return body so portals render inline
+    _portals: [],
+  };
+}
+
+// ─── renderToString ───────────────────────────────────────────────────────────
+
+/**
+ * Renders a Clarity component to an HTML string on the server.
+ *
+ * The component function is called inside a sandboxed environment where:
+ *   • `document` is replaced with a lightweight SSR fake DOM
+ *   • `queueMicrotask` is stubbed to run tasks synchronously after the
+ *     component returns (ensures <when> and <list> effects flush correctly)
+ *   • `window` is stubbed to avoid ReferenceErrors
+ *
+ * @param {Function} componentFn  Compiled Clarity component function
+ * @param {object}   [props={}]   Props to pass to the component
+ * @returns {{ html: string, state: object, aiContracts: object[] }}
+ */
+export function renderToString(componentFn, props = {}) {
+  // ── Save globals ────────────────────────────────────────────────────────────
+  const _globals = _saveGlobals();
+
+  // ── Set up SSR environment ──────────────────────────────────────────────────
+  const ssrDoc      = createSSRDocument();
+  const taskQueue   = [];
+  const aiContracts = [];
+
+  globalThis.document       = ssrDoc;
+  globalThis.window         = globalThis.window ?? {};
+  globalThis.queueMicrotask = (fn) => taskQueue.push(fn);
+
+  // Minimal CSS.supports stub (used by some style helpers)
+  if (!globalThis.CSS) globalThis.CSS = { supports: () => false };
+
+  let rootNode;
+  try {
+    // ── Run the component ────────────────────────────────────────────────────
+    rootNode = componentFn(props);
+
+    // ── Flush deferred microtasks (when / list effects) ──────────────────────
+    // Tasks can enqueue further tasks (nested when / list), so we loop until empty.
+    let safety = 0;
+    while (taskQueue.length > 0 && safety++ < 10_000) {
+      taskQueue.shift()();
+    }
+    if (safety >= 10_000) {
+      console.warn('[Clarity SSR] Possible infinite loop in queueMicrotask tasks — bailed out.');
+    }
+
+    // ── Collect AI contracts ─────────────────────────────────────────────────
+    _collectAIContracts(rootNode, aiContracts);
+    // Also collect from portals
+    for (const p of ssrDoc._portals) _collectAIContracts(p, aiContracts);
+
+    // ── Serialize ────────────────────────────────────────────────────────────
+    let html;
+    if (rootNode instanceof SSRElement || rootNode instanceof SSRFragment) {
+      html = rootNode.toHTML();
+    } else if (rootNode == null) {
+      html = '';
+    } else {
+      html = String(rootNode);
+    }
+
+    // Portals append after root
+    const portalHTML = ssrDoc._portals.map(p => p.toHTML?.() ?? '').join('');
+
+    // ── Snapshot state via AI contracts ──────────────────────────────────────
+    const state = {};
+    for (const contract of aiContracts) {
+      try {
+        state[contract.component] = contract.snapshot();
+      } catch {
+        // snapshot might fail if component has no readable fields
+      }
+    }
+
+    return {
+      html: html + portalHTML,
+      state,
+      aiContracts,
+    };
+
+  } finally {
+    _restoreGlobals(_globals);
+  }
+}
+
+/**
+ * Async variant of renderToString for components that have a `server { }` block.
+ *
+ * Calls `componentFn.__clarity_server__(props, ctx)` to fetch data, then passes
+ * the result as `__ssr` into the component so signals are seeded with server data.
+ *
+ * @param {Function} componentFn  Compiled Clarity component function (with __clarity_server__)
+ * @param {object}   [props={}]   Props to pass to the component
+ * @param {object}   [ctx={}]     Server context (request, auth, etc.) forwarded to the loader
+ * @returns {Promise<{ html: string, state: object, aiContracts: object[] }>}
+ */
+export async function renderToStringAsync(componentFn, props = {}, ctx = {}) {
+  let ssrData = {};
+  if (typeof componentFn.__clarity_server__ === 'function') {
+    ssrData = await componentFn.__clarity_server__(props, ctx);
+  }
+  // Merge __ssr into props so the component's destructuring picks it up
+  return renderToString(componentFn, { ...props, __ssr: ssrData });
+}
+
+/**
+ * Like renderToString but wraps the output in a full HTML document shell.
+ *
+ * @param {Function} componentFn
+ * @param {object}   [options={}]
+ * @param {object}   [options.props={}]     Props for the component
+ * @param {string}   [options.title='']     <title> tag content
+ * @param {string}   [options.lang='en']    <html lang> attribute
+ * @param {string}   [options.clientScript] Path to client-side JS bundle
+ * @param {string}   [options.styles]       Inline CSS to inject
+ * @returns {string}  Complete HTML document
+ */
+export function renderToDocument(componentFn, {
+  props       = {},
+  title       = '',
+  lang        = 'en',
+  clientScript = null,
+  styles      = null,
+} = {}) {
+  const { html, state } = renderToString(componentFn, props);
+  const stateScript = Object.keys(state).length > 0
+    ? `<script>window.__CLARITY_DATA__=${JSON.stringify(state)};</script>`
+    : '';
+  const clientTag = clientScript
+    ? `<script type="module" src="${escapeAttr(clientScript)}"></script>`
+    : '';
+  const styleTag = styles
+    ? `<style>${styles}</style>`
+    : '';
+  return [
+    `<!DOCTYPE html>`,
+    `<html lang="${escapeAttr(lang)}">`,
+    `<head>`,
+    `<meta charset="utf-8">`,
+    `<meta name="viewport" content="width=device-width,initial-scale=1">`,
+    title ? `<title>${escapeHTML(title)}</title>` : '',
+    styleTag,
+    `</head>`,
+    `<body>`,
+    `<div id="app">${html}</div>`,
+    stateScript,
+    clientTag,
+    `</body>`,
+    `</html>`,
+  ].filter(Boolean).join('\n');
+}
+
+// ─── renderToStream ───────────────────────────────────────────────────────────
+
+/**
+ * Streams a full HTML document to a Node.js Writable (or Web ReadableStream).
+ *
+ * The shell (head + opening body) is flushed immediately so the browser can
+ * start downloading assets.  The component HTML follows as a second chunk,
+ * then the closing tags.  This gives the "streaming SSR" behaviour of
+ * Next.js App Router / React 18 without a virtual DOM.
+ *
+ * Node.js usage (Express):
+ *
+ *   import { renderToStream } from '@ozsarman/clarityjs/ssr';
+ *   app.get('/', async (req, res) => {
+ *     res.setHeader('Content-Type', 'text/html; charset=utf-8');
+ *     res.setHeader('Transfer-Encoding', 'chunked');
+ *     const stream = renderToStream(App, { props: { user: req.user }, title: 'Home' });
+ *     stream.pipe(res);
+ *   });
+ *
+ * Web Streams usage (Cloudflare Workers / Deno / Bun):
+ *
+ *   const stream = renderToStream(App, { webStream: true });
+ *   return new Response(stream, { headers: { 'Content-Type': 'text/html' } });
+ *
+ * @param {Function} componentFn
+ * @param {object}   [options={}]
+ * @param {object}   [options.props={}]         Props for the component
+ * @param {string}   [options.title='']         <title> tag
+ * @param {string}   [options.lang='en']        <html lang>
+ * @param {string}   [options.clientScript]     Path to client bundle
+ * @param {string}   [options.styles]           Inline CSS
+ * @param {boolean}  [options.webStream=false]  Return a Web ReadableStream
+ * @returns {import('node:stream').Readable | ReadableStream}
+ */
+export function renderToStream(componentFn, {
+  props        = {},
+  title        = '',
+  lang         = 'en',
+  clientScript = null,
+  styles       = null,
+  webStream    = false,
+} = {}) {
+  // Build shell synchronously — send immediately so browser fetches assets
+  const styleTag  = styles       ? `<style>${styles}</style>` : '';
+  const clientTag = clientScript
+    ? `<script type="module" src="${escapeAttr(clientScript)}"></script>`
+    : '';
+
+  const shell = [
+    `<!DOCTYPE html>`,
+    `<html lang="${escapeAttr(lang)}">`,
+    `<head>`,
+    `<meta charset="utf-8">`,
+    `<meta name="viewport" content="width=device-width,initial-scale=1">`,
+    title ? `<title>${escapeHTML(title)}</title>` : '',
+    styleTag,
+    `</head>`,
+    `<body>`,
+    `<div id="app">`,
+  ].filter(Boolean).join('\n');
+
+  // Render component — synchronous (effects flushed inside renderToString)
+  const { html, state } = renderToString(componentFn, props);
+
+  const stateScript = Object.keys(state).length > 0
+    ? `<script>window.__CLARITY_DATA__=${JSON.stringify(state)};</script>`
+    : '';
+
+  const tail = [
+    `</div>`,
+    stateScript,
+    clientTag,
+    `</body>`,
+    `</html>`,
+  ].filter(Boolean).join('\n');
+
+  if (webStream) {
+    // Web Streams API (Workers, Deno, Bun)
+    return new ReadableStream({
+      start(controller) {
+        const enc = new TextEncoder();
+        controller.enqueue(enc.encode(shell));
+        controller.enqueue(enc.encode(html));
+        controller.enqueue(enc.encode(tail));
+        controller.close();
+      },
+    });
+  }
+
+  // Node.js Readable stream — works with .pipe(res)
+  // Dynamic import avoids bundling 'node:stream' in browser builds
+  const { Readable } = await_import_stream();
+
+  const chunks = [shell, html, tail];
+  let   _idx   = 0;
+
+  return new Readable({
+    read() {
+      if (_idx < chunks.length) {
+        this.push(chunks[_idx++], 'utf8');
+      } else {
+        this.push(null); // EOF
+      }
+    },
+  });
+}
+
+/**
+ * @internal — lazy-loads node:stream so the module stays browser-compatible.
+ * In environments where node:stream is unavailable, use the webStream option.
+ */
+function await_import_stream() {
+  // This is called at runtime (not at module parse time), so bundlers that
+  // tree-shake import() won't inline it in browser builds.
+  try {
+    // Node 18+ supports native require() in ESM via createRequire, but the
+    // simplest approach is to use a dynamic import wrapped in eval() so that
+    // browser bundlers never see it.
+    return eval('import("node:stream")');
+  } catch {
+    throw new Error(
+      '[Clarity renderToStream] node:stream is not available in this environment. ' +
+      'Pass { webStream: true } to use the Web Streams API instead.'
+    );
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function _collectAIContracts(node, out) {
+  if (!node) return;
+  if (node.__clarity_ai__) out.push(node.__clarity_ai__);
+  const children = node._children ?? node.childNodes ?? [];
+  for (const child of children) {
+    if (child && typeof child === 'object') _collectAIContracts(child, out);
+  }
+}
+
+const _GLOBAL_KEYS = ['document', 'window', 'queueMicrotask', 'CSS'];
+
+function _saveGlobals() {
+  const saved = {};
+  for (const k of _GLOBAL_KEYS) saved[k] = globalThis[k];
+  return saved;
+}
+
+function _restoreGlobals(saved) {
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete globalThis[k];
+    else globalThis[k] = v;
+  }
+}