@vertz/ui-server 0.2.0

package/dist/dom-shim/index.js

@@ -0,0 +1,332 @@
+// src/dom-shim/ssr-node.ts
+class SSRNode {
+  childNodes = [];
+  parentNode = null;
+  get firstChild() {
+    return this.childNodes[0] ?? null;
+  }
+  get nextSibling() {
+    if (!this.parentNode)
+      return null;
+    const index = this.parentNode.childNodes.indexOf(this);
+    return this.parentNode.childNodes[index + 1] ?? null;
+  }
+  removeChild(child) {
+    const index = this.childNodes.indexOf(child);
+    if (index !== -1) {
+      this.childNodes.splice(index, 1);
+      child.parentNode = null;
+    }
+    return child;
+  }
+  insertBefore(newNode, referenceNode) {
+    if (!referenceNode) {
+      this.childNodes.push(newNode);
+      newNode.parentNode = this;
+    } else {
+      const index = this.childNodes.indexOf(referenceNode);
+      if (index !== -1) {
+        this.childNodes.splice(index, 0, newNode);
+        newNode.parentNode = this;
+      }
+    }
+    return newNode;
+  }
+  replaceChild(newNode, oldNode) {
+    const index = this.childNodes.indexOf(oldNode);
+    if (index !== -1) {
+      this.childNodes[index] = newNode;
+      newNode.parentNode = this;
+      oldNode.parentNode = null;
+    }
+    return oldNode;
+  }
+}
+
+// src/dom-shim/ssr-text-node.ts
+class SSRTextNode extends SSRNode {
+  text;
+  constructor(text) {
+    super();
+    this.text = text;
+  }
+  get data() {
+    return this.text;
+  }
+  set data(value) {
+    this.text = value;
+  }
+}
+
+// src/dom-shim/ssr-fragment.ts
+class SSRDocumentFragment extends SSRNode {
+  children = [];
+  appendChild(child) {
+    if (child instanceof SSRTextNode) {
+      this.children.push(child.text);
+      this.childNodes.push(child);
+      child.parentNode = this;
+    } else if (child instanceof SSRDocumentFragment) {
+      this.children.push(...child.children);
+      this.childNodes.push(...child.childNodes);
+      for (const fragmentChild of child.childNodes) {
+        fragmentChild.parentNode = this;
+      }
+    } else {
+      this.children.push(child);
+      this.childNodes.push(child);
+      child.parentNode = this;
+    }
+  }
+}
+
+// src/dom-shim/ssr-element.ts
+function createStyleProxy(element) {
+  const styles = {};
+  return new Proxy(styles, {
+    set(_target, prop, value) {
+      if (typeof prop === "string") {
+        styles[prop] = value;
+        const pairs = Object.entries(styles).map(([k, v]) => {
+          const key = k.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+          return `${key}: ${v}`;
+        });
+        element.attrs.style = pairs.join("; ");
+      }
+      return true;
+    },
+    get(_target, prop) {
+      if (typeof prop === "string") {
+        return styles[prop] ?? "";
+      }
+      return;
+    }
+  });
+}
+
+class SSRElement extends SSRNode {
+  tag;
+  attrs = {};
+  children = [];
+  _classList = new Set;
+  _textContent = null;
+  _innerHTML = null;
+  style;
+  constructor(tag) {
+    super();
+    this.tag = tag;
+    this.style = createStyleProxy(this);
+  }
+  setAttribute(name, value) {
+    if (name === "class") {
+      this._classList = new Set(value.split(/\s+/).filter(Boolean));
+    }
+    this.attrs[name] = value;
+  }
+  getAttribute(name) {
+    return this.attrs[name] ?? null;
+  }
+  removeAttribute(name) {
+    delete this.attrs[name];
+    if (name === "class") {
+      this._classList.clear();
+    }
+  }
+  appendChild(child) {
+    if (child instanceof SSRTextNode) {
+      this.children.push(child.text);
+      this.childNodes.push(child);
+      child.parentNode = this;
+    } else if (child instanceof SSRDocumentFragment) {
+      for (const fragmentChild of child.childNodes) {
+        if (fragmentChild instanceof SSRTextNode) {
+          this.children.push(fragmentChild.text);
+        } else if (fragmentChild instanceof SSRElement) {
+          this.children.push(fragmentChild);
+        }
+        this.childNodes.push(fragmentChild);
+        fragmentChild.parentNode = this;
+      }
+    } else {
+      this.children.push(child);
+      this.childNodes.push(child);
+      child.parentNode = this;
+    }
+  }
+  removeChild(child) {
+    const result = super.removeChild(child);
+    if (child instanceof SSRTextNode) {
+      const textIndex = this.children.indexOf(child.text);
+      if (textIndex !== -1) {
+        this.children.splice(textIndex, 1);
+      }
+    } else if (child instanceof SSRElement) {
+      const index = this.children.indexOf(child);
+      if (index !== -1) {
+        this.children.splice(index, 1);
+      }
+    }
+    return result;
+  }
+  get classList() {
+    const self = this;
+    return {
+      add(cls) {
+        self._classList.add(cls);
+        self.attrs.class = [...self._classList].join(" ");
+      },
+      remove(cls) {
+        self._classList.delete(cls);
+        const val = [...self._classList].join(" ");
+        if (val) {
+          self.attrs.class = val;
+        } else {
+          delete self.attrs.class;
+        }
+      }
+    };
+  }
+  set className(value) {
+    this._classList = new Set(value.split(/\s+/).filter(Boolean));
+    if (value) {
+      this.attrs.class = value;
+    } else {
+      delete this.attrs.class;
+    }
+  }
+  get className() {
+    return this.attrs.class ?? "";
+  }
+  set textContent(value) {
+    this._textContent = value;
+    this.children = value ? [value] : [];
+    this.childNodes = [];
+  }
+  get textContent() {
+    return this._textContent;
+  }
+  set innerHTML(value) {
+    this._innerHTML = value;
+    this.children = value ? [value] : [];
+    this.childNodes = [];
+  }
+  get innerHTML() {
+    return this._innerHTML ?? "";
+  }
+  addEventListener(_event, _handler) {}
+  removeEventListener(_event, _handler) {}
+  toVNode() {
+    return {
+      tag: this.tag,
+      attrs: { ...this.attrs },
+      children: this.children.map((child) => {
+        if (typeof child === "string")
+          return child;
+        return child.toVNode();
+      })
+    };
+  }
+}
+
+// src/dom-shim/index.ts
+function installDomShim() {
+  const isSSRContext = typeof globalThis.__SSR_URL__ !== "undefined";
+  if (typeof document !== "undefined" && !isSSRContext) {
+    return;
+  }
+  const fakeDocument = {
+    createElement(tag) {
+      return new SSRElement(tag);
+    },
+    createTextNode(text) {
+      return new SSRTextNode(text);
+    },
+    createComment(text) {
+      return new SSRTextNode(`<!-- ${text} -->`);
+    },
+    createDocumentFragment() {
+      return new SSRDocumentFragment;
+    },
+    head: new SSRElement("head"),
+    body: new SSRElement("body")
+  };
+  globalThis.document = fakeDocument;
+  if (typeof window === "undefined") {
+    globalThis.window = {
+      location: { pathname: globalThis.__SSR_URL__ || "/" },
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      history: {
+        pushState: () => {},
+        replaceState: () => {}
+      }
+    };
+  } else {
+    globalThis.window.location = {
+      ...globalThis.window.location || {},
+      pathname: globalThis.__SSR_URL__ || "/"
+    };
+  }
+  globalThis.Node = SSRNode;
+  globalThis.HTMLElement = SSRElement;
+  globalThis.HTMLAnchorElement = SSRElement;
+  globalThis.HTMLDivElement = SSRElement;
+  globalThis.HTMLInputElement = SSRElement;
+  globalThis.HTMLButtonElement = SSRElement;
+  globalThis.HTMLSelectElement = SSRElement;
+  globalThis.HTMLTextAreaElement = SSRElement;
+  globalThis.DocumentFragment = SSRDocumentFragment;
+  globalThis.MouseEvent = class MockMouseEvent {
+  };
+  globalThis.Event = class MockEvent {
+  };
+}
+function removeDomShim() {
+  const globals = [
+    "document",
+    "window",
+    "Node",
+    "HTMLElement",
+    "HTMLAnchorElement",
+    "HTMLDivElement",
+    "HTMLInputElement",
+    "HTMLButtonElement",
+    "HTMLSelectElement",
+    "HTMLTextAreaElement",
+    "DocumentFragment",
+    "MouseEvent",
+    "Event"
+  ];
+  for (const g of globals) {
+    delete globalThis[g];
+  }
+}
+function toVNode(element) {
+  if (element instanceof SSRElement) {
+    return element.toVNode();
+  }
+  if (element instanceof SSRDocumentFragment) {
+    return {
+      tag: "fragment",
+      attrs: {},
+      children: element.children.map((child) => {
+        if (typeof child === "string")
+          return child;
+        return child.toVNode();
+      })
+    };
+  }
+  if (typeof element === "object" && "tag" in element) {
+    return element;
+  }
+  return { tag: "span", attrs: {}, children: [String(element)] };
+}
+export {
+  toVNode,
+  removeDomShim,
+  installDomShim,
+  SSRTextNode,
+  SSRNode,
+  SSRElement,
+  SSRDocumentFragment
+};

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+/** A raw HTML string that bypasses escaping during serialization. */
+interface RawHtml {
+	__raw: true;
+	html: string;
+}
+/** Create a raw HTML string that will not be escaped during serialization. */
+declare function rawHtml(html: string): RawHtml;
+/** Virtual node representing an HTML element for SSR serialization. */
+interface VNode {
+	tag: string;
+	attrs: Record<string, string>;
+	children: (VNode | string | RawHtml)[];
+}
+/** Options for hydration marker generation. */
+interface HydrationOptions {
+	/** Component name for `data-v-id`. */
+	componentName: string;
+	/** Unique key for `data-v-key`. */
+	key: string;
+	/** Serialized props to embed as JSON. */
+	props?: Record<string, unknown>;
+}
+/** Metadata collected by the Head component during rendering. */
+interface HeadEntry {
+	tag: "title" | "meta" | "link";
+	attrs?: Record<string, string>;
+	textContent?: string;
+}
+/** Options for {@link renderToStream}. */
+interface RenderToStreamOptions {
+	/**
+	* CSP nonce to inject on all inline `<script>` tags emitted during SSR.
+	*
+	* When set, every inline script (e.g. Suspense replacement scripts) will
+	* include `nonce="<value>"` so that strict Content-Security-Policy headers
+	* do not block them.
+	*/
+	nonce?: string;
+}
+/** Asset descriptor for script/stylesheet injection. */
+interface AssetDescriptor {
+	type: "script" | "stylesheet";
+	src: string;
+	/** Whether to add `async` attribute (scripts only). */
+	async?: boolean;
+	/** Whether to add `defer` attribute (scripts only). */
+	defer?: boolean;
+}
+/**
+* Render asset descriptors to HTML tags for script/stylesheet injection.
+*
+* - Scripts: `<script src="..." [async] [defer]><\/script>`
+* - Stylesheets: `<link rel="stylesheet" href="...">`
+*/
+declare function renderAssetTags(assets: AssetDescriptor[]): string;
+/**
+* Inline critical CSS as a `<style>` tag.
+*
+* Wraps the provided CSS in `<style>...</style>` for embedding in the HTML head.
+* Escapes any `</style>` sequences in the CSS content to prevent injection.
+*
+* Returns an empty string if the CSS is empty.
+*/
+declare function inlineCriticalCss(css: string): string;
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { InlineConfig, ViteDevServer } from "vite";
+interface DevServerOptions {
+	/**
+	* Path to the SSR entry module (relative to project root).
+	* This module should a `renderToString` function.
+	*/
+	entry: string;
+	/**
+	* Port to listen on.
+	* @default 5173
+	*/
+	port?: number;
+	/**
+	* Host to bind to.
+	* @default '0.0.0.0'
+	*/
+	host?: string;
+	/**
+	* Custom Vite configuration.
+	* Merged with default middleware mode config.
+	*/
+	viteConfig?: InlineConfig;
+	/**
+	* Custom middleware to run before SSR handler.
+	* Useful for API routes, static file serving, etc.
+	*/
+	middleware?: (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+	/**
+	* Skip invalidating modules on each request.
+	* Useful for debugging or performance testing.
+	* @default false
+	*/
+	skipModuleInvalidation?: boolean;
+	/**
+	* Log requests to console.
+	* @default true
+	*/
+	logRequests?: boolean;
+}
+interface DevServer {
+	/**
+	* Start the server and listen on the configured port.
+	*/
+	listen(): Promise<void>;
+	/**
+	* Close the server.
+	*/
+	close(): Promise<void>;
+	/**
+	* The underlying Vite dev server.
+	*/
+	vite: ViteDevServer;
+	/**
+	* The underlying HTTP server.
+	*/
+	httpServer: Server;
+}
+/**
+* Create a Vite SSR development server.
+*/
+declare function createDevServer(options: DevServerOptions): DevServer;
+/**
+* Collector for `<head>` metadata during SSR.
+*
+* Components call `addTitle`, `addMeta`, or `addLink` during render,
+* and the collected entries are serialized into the HTML `<head>` section.
+*/
+declare class HeadCollector {
+	private entries;
+	/** Add a `<title>` entry. */
+	addTitle(text: string): void;
+	/** Add a `<meta>` entry. */
+	addMeta(attrs: Record<string, string>): void;
+	/** Add a `<link>` entry. */
+	addLink(attrs: Record<string, string>): void;
+	/** Get all collected entries. */
+	getEntries(): HeadEntry[];
+	/** Clear all collected entries. */
+	clear(): void;
+}
+/**
+* Render head entries to an HTML string.
+*
+* - `<title>` renders as `<title>text</title>`
+* - `<meta>` and `<link>` render as void elements
+*/
+declare function renderHeadToHtml(entries: HeadEntry[]): string;
+/**
+* Serialize a VNode tree (or plain string) to an HTML string.
+*
+* This is the core serialization function for SSR. It walks the virtual tree
+* recursively and produces an HTML string without requiring a real DOM.
+*
+* - Text content inside `<script>` and `<style>` tags is not escaped.
+* - `RawHtml` values bypass escaping entirely.
+*/
+declare function serializeToHtml(node: VNode | string | RawHtml): string;
+/**
+* Wrap a VNode with hydration markers for interactive components.
+*
+* Adds `data-v-id` and `data-v-key` attributes to the root element,
+* and optionally embeds serialized props as a `<script type="application/json">` child.
+*
+* Returns a new VNode; the original is not mutated.
+*/
+declare function wrapWithHydrationMarkers(node: VNode, options: HydrationOptions): VNode;
+/**
+* Render a VNode tree to a `ReadableStream` of HTML chunks.
+*
+* This is the main SSR entry point. It walks the virtual tree, serializing
+* synchronous content immediately and deferring Suspense boundaries.
+*
+* Suspense boundaries emit:
+* 1. A `<div id="v-slot-N">fallback</div>` placeholder inline
+* 2. A `<template id="v-tmpl-N">resolved</template><script>...<\/script>` chunk
+*    appended after the main content once the async content resolves
+*
+* This enables out-of-order streaming: the browser can paint the fallback
+* immediately and swap in the resolved content when it arrives.
+*/
+declare function renderToStream(tree: VNode | string | RawHtml, options?: RenderToStreamOptions): ReadableStream<Uint8Array>;
+/** Reset the slot counter (for testing). */
+declare function resetSlotCounter(): void;
+/**
+* Create a Suspense slot placeholder.
+*
+* Wraps fallback content in a `<div id="v-slot-N">` so it can later
+* be replaced by the resolved async content via a template chunk.
+*
+* Returns the placeholder VNode and the assigned slot ID.
+*/
+declare function createSlotPlaceholder(fallback: VNode | string): VNode & {
+	_slotId: number;
+};
+/**
+* Encode a string as a UTF-8 Uint8Array chunk.
+*/
+declare function encodeChunk(html: string): Uint8Array;
+/**
+* Convert a ReadableStream of Uint8Array chunks to a single string.
+* Useful for testing SSR output.
+*/
+declare function streamToString(stream: ReadableStream<Uint8Array>): Promise<string>;
+/**
+* Collect all chunks from a ReadableStream as an array of strings.
+* Useful for testing streaming behavior (chunk ordering, etc.).
+*/
+declare function collectStreamChunks(stream: ReadableStream<Uint8Array>): Promise<string[]>;
+/**
+* Create a replacement template chunk for out-of-order streaming.
+*
+* When a Suspense boundary resolves, this function generates the HTML
+* containing:
+* 1. A `<template id="v-tmpl-N">` with the resolved content
+* 2. A `<script>` that replaces the placeholder `<div id="v-slot-N">` with the template content
+*
+* @param slotId - The unique slot ID for this suspense boundary.
+* @param resolvedHtml - The resolved HTML content to insert.
+* @param nonce - Optional CSP nonce to add to the inline script tag.
+*/
+declare function createTemplateChunk(slotId: number, resolvedHtml: string, nonce?: string): string;
+export { wrapWithHydrationMarkers, streamToString, serializeToHtml, resetSlotCounter, renderToStream, renderHeadToHtml, renderAssetTags, rawHtml, inlineCriticalCss, encodeChunk, createTemplateChunk, createSlotPlaceholder, createDevServer, collectStreamChunks, VNode, RenderToStreamOptions, RawHtml, HydrationOptions, HeadEntry, HeadCollector, DevServerOptions, DevServer, AssetDescriptor };