@sigx/server-renderer 0.1.25 → 0.2.0

package/dist/{server-pSrHP504.js → server-Di7tiBy1.js}

@@ -1,20 +1,50 @@
-import { n as internals_exports, r as __commonJSMin } from "./types-CkI_lB93.js";
+import { n as internals_exports, r as __commonJSMin } from "./types-DYlI_C8F.js";
 import { show } from "@sigx/runtime-dom";
 import { Fragment, Text, getCurrentInstance, isComponent, isDirective, signal } from "sigx";
+//#region src/builtin-ssr-directives.ts
+/**
+* Built-in directive SSR support — lazy patching.
+*
+* This module patches `getSSRProps` onto built-in directives (like `show`)
+* at runtime, keeping `@sigx/runtime-dom` free of SSR knowledge.
+*
+* Mirrors Vue 3's `initVShowForSSR()` / `initDirectivesForSSR()` pattern.
+*
+* @internal
+*/
 var _initialized = false;
+/**
+* Patch `getSSRProps` onto the `show` directive for SSR support.
+*
+* Called lazily from `initDirectivesForSSR()` — not at import time,
+* so tree-shaking can eliminate this in client-only builds.
+*/
 function initShowForSSR() {
 	show.getSSRProps = ({ value }) => {
 		if (!value) return { style: { display: "none" } };
 	};
 }
+/**
+* Initialize SSR support for all built-in directives.
+*
+* Must be called before any SSR rendering occurs.
+* Safe to call multiple times — only patches once.
+*/
 function initDirectivesForSSR() {
 	if (_initialized) return;
 	_initialized = true;
 	initShowForSSR();
 }
+//#endregion
+//#region __vite-browser-external
 var require___vite_browser_external = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = {};
 }));
+//#endregion
+//#region src/server/context.ts
+/**
+* Create a new SSR context for rendering
+*/
 function createSSRContext(options = {}) {
 	let componentId = 0;
 	const componentStack = [];
@@ -51,6 +81,19 @@ function createSSRContext(options = {}) {
 		}
 	};
 }
+//#endregion
+//#region src/server/render-core.ts
+/**
+* Core rendering logic for SSR
+*
+* The async generator `renderToChunks` walks a VNode tree and yields HTML strings.
+* Handles text, fragments, host elements, and delegates components to the
+* component renderer.
+*
+* This module is strategy-agnostic. Island-specific logic (signal tracking,
+* hydration directives, async streaming) lives in @sigx/ssr-islands and is
+* injected through the SSRPlugin hooks.
+*/
 var ESCAPE = {
 	"&": "&",
 	"<": "&lt;",
@@ -61,7 +104,9 @@ var ESCAPE = {
 function escapeHtml$1(s) {
 	return s.replace(/[&<>"']/g, (c) => ESCAPE[c]);
 }
+/** Cache for camelCase → kebab-case conversions (same properties repeat across elements) */
 var kebabCache = {};
+/** Void elements that cannot have children — hoisted to module scope as a Set for O(1) lookup */
 var VOID_ELEMENTS = new Set([
 	"area",
 	"base",
@@ -82,6 +127,15 @@ function camelToKebab(str) {
 	if (str.startsWith("--")) return str;
 	return kebabCache[str] ||= str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
 }
+/**
+* Parse a CSS string into a style object.
+*
+* Handles edge cases: parens in values (e.g., `linear-gradient(...)`),
+* CSS comments, and colons in values.
+*
+* Adapted from Vue 3's `parseStringStyle` — battle-tested, split-based,
+* fast in V8.
+*/
 var listDelimiterRE = /;(?![^(]*\))/g;
 var propertyDelimiterRE = /:([^]+)/;
 var styleCommentRE = /\/\*[^]*?\*\//g;
@@ -95,6 +149,12 @@ function parseStringStyle(cssText) {
 	});
 	return ret;
 }
+/**
+* Serialize a style object to a CSS string.
+*
+* Uses for...in + string concat (avoids Object.entries/map/join allocations)
+* and cached kebab-case conversion.
+*/
 function stringifyStyle(style) {
 	let ret = "";
 	for (const key in style) {
@@ -103,11 +163,15 @@ function stringifyStyle(style) {
 	}
 	return ret;
 }
+/**
+* Check if element will render as text content
+*/
 function isTextContent(element) {
 	if (element == null || element === false || element === true) return false;
 	if (typeof element === "string" || typeof element === "number") return true;
 	return element.type === Text;
 }
+/** Check if all children are leaf types (text, number, null, bool, Text vnode) */
 function allChildrenAreLeaves(children) {
 	for (const child of children) {
 		if (child == null || child === false || child === true) continue;
@@ -117,6 +181,11 @@ function allChildrenAreLeaves(children) {
 	}
 	return true;
 }
+/**
+* Merge style values for SSR (element style + directive SSR style).
+* Either value can be an object, string, or undefined.
+* String styles are parsed into objects before merging.
+*/
 function mergeSSRStyles(elementStyle, directiveStyle) {
 	if (!elementStyle) return directiveStyle;
 	if (!directiveStyle) return elementStyle;
@@ -127,6 +196,13 @@ function mergeSSRStyles(elementStyle, directiveStyle) {
 		...b
 	};
 }
+/**
+* Render element to string chunks (generator for streaming)
+* @param element - The JSX element to render
+* @param ctx - The SSR context for tracking state
+* @param parentCtx - The parent component context for provide/inject
+* @param appContext - The app context for app-level provides (from defineApp)
+*/
 async function* renderToChunks(element, ctx, parentCtx = null, appContext = null) {
 	if (element == null || element === false || element === true) return;
 	if (typeof element === "string" || typeof element === "number") {
@@ -345,11 +421,22 @@ async function* renderToChunks(element, ctx, parentCtx = null, appContext = null
 		yield `</${tagName}>`;
 	}
 }
+/**
+* Helper to render a VNode to string (for deferred async content)
+*/
 async function renderVNodeToString(element, ctx, appContext = null) {
 	let result = "";
 	for await (const chunk of renderToChunks(element, ctx, null, appContext)) result += chunk;
 	return result;
 }
+/**
+* Synchronous render-to-string that avoids async generator overhead.
+* Returns null if any async operation is encountered (caller should fall back
+* to the async generator path).
+*
+* For purely synchronous component trees this eliminates thousands of
+* microtask/Promise allocations from the AsyncGenerator protocol.
+*/
 function renderToStringSync(element, ctx, parentCtx, appContext, buf) {
 	if (element == null || element === false || element === true) return true;
 	if (typeof element === "string" || typeof element === "number") {
@@ -528,9 +615,28 @@ function renderToStringSync(element, ctx, parentCtx, appContext, buf) {
 	}
 	return true;
 }
+//#endregion
+//#region src/server/streaming.ts
+/**
+* Core streaming utilities for async SSR
+*
+* Provides the client-side `$SIGX_REPLACE` function and replacement script
+* generation used by core async streaming. These are strategy-agnostic —
+* any async component with `ssr.load()` gets streamed without needing a plugin.
+*
+* Plugins (e.g., islands) can augment replacements via `onAsyncComponentResolved`.
+*/
+/**
+* Escape a JSON string for safe embedding inside <script> tags.
+* Prevents XSS by replacing characters that could break out of the script context.
+*/
 function escapeJsonForScript(json) {
 	return json.replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
 }
+/**
+* Generate the streaming bootstrap script (injected once before any replacements).
+* Defines `window.$SIGX_REPLACE` which swaps async placeholders with rendered HTML.
+*/
 function generateStreamingScript() {
 	return `
 <script>
@@ -548,24 +654,67 @@ window.$SIGX_REPLACE = function(id, html) {
 };
 <\/script>`;
 }
+/**
+* Generate a replacement script for a resolved async component.
+*/
 function generateReplacementScript(id, html, extraScript) {
 	let script = `<script>$SIGX_REPLACE(${id}, ${escapeJsonForScript(JSON.stringify(html))});`;
 	if (extraScript) script += extraScript;
 	script += `<\/script>`;
 	return script;
 }
+//#endregion
+//#region src/head.ts
+/**
+* Head management composable for SSR and client-side.
+*
+* Provides `useHead()` for managing `<head>` elements (title, meta, link, script)
+* from within components. Works during SSR (collects into SSRContext._head) and
+* on the client (updates DOM directly).
+*
+* @example
+* ```tsx
+* import { useHead } from '@sigx/server-renderer/head';
+*
+* function MyPage(ctx) {
+*     useHead({
+*         title: 'My Page',
+*         meta: [
+*             { name: 'description', content: 'A great page' },
+*             { property: 'og:title', content: 'My Page' }
+*         ],
+*         link: [
+*             { rel: 'canonical', href: 'https://example.com/my-page' }
+*         ]
+*     });
+*
+*     return () => <div>Page content</div>;
+* }
+* ```
+*/
 var _ssrHeadConfigs = [];
 var _isSSR = false;
+/**
+* Enable SSR mode for head management.
+* Called by the SSR renderer before rendering starts.
+*/
 function enableSSRHead() {
 	_isSSR = true;
 	_ssrHeadConfigs = [];
 }
+/**
+* Disable SSR mode and return collected configs.
+*/
 function collectSSRHead() {
 	_isSSR = false;
 	const configs = _ssrHeadConfigs;
 	_ssrHeadConfigs = [];
 	return configs;
 }
+/**
+* Render collected head configs to an HTML string.
+* Deduplicates meta tags by name/property and uses the last title.
+*/
 function renderHeadToString(configs) {
 	const parts = [];
 	const seenMeta = /* @__PURE__ */ new Map();
@@ -647,6 +796,14 @@ function applyHeadClient(config) {
 		for (const el of managed) el.remove();
 	};
 }
+/**
+* Manage `<head>` elements from within a component.
+*
+* During SSR, collects head configs for later rendering with `renderHeadToString()`.
+* On the client, updates the DOM directly. Cleans up on component unmount.
+*
+* @param config - Head configuration (title, meta, link, script, etc.)
+*/
 function useHead(config) {
 	if (_isSSR) {
 		_ssrHeadConfigs.push(config);
@@ -662,10 +819,18 @@ function escapeHtml(s) {
 function escapeAttr(s) {
 	return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 }
+//#endregion
+//#region src/ssr.ts
 var import___vite_browser_external = require___vite_browser_external();
+/**
+* Check if the input is an App instance (created via defineApp)
+*/
 function isApp(input) {
 	return input && typeof input === "object" && "_rootComponent" in input && "_context" in input;
 }
+/**
+* Extract the JSX element and optional AppContext from a render input.
+*/
 function extractInput(input) {
 	if (isApp(input)) return {
 		element: input._rootComponent,
@@ -676,6 +841,15 @@ function extractInput(input) {
 		appContext: null
 	};
 }
+/**
+* Yield all async streaming chunks — core-managed and plugin-managed — interleaved
+* so the fastest component streams first regardless of who manages it.
+*
+* Core-managed: ctx._pendingAsync (from render-core when no plugin overrides)
+* Plugin-managed: plugin.server.getStreamingChunks() async generators
+*
+* Both are raced together using a unified promise race loop.
+*/
 async function* streamAllAsyncChunks(ctx, plugins) {
 	const hasCoreAsync = ctx._pendingAsync.length > 0;
 	const pluginGenerators = [];
@@ -752,6 +926,9 @@ async function* streamAllAsyncChunks(ctx, plugins) {
 		if (winner.index < totalCore) resolvedCore.add(winner.index);
 	}
 }
+/**
+* Create an SSR instance with plugin support.
+*/
 function createSSR() {
 	const plugins = [];
 	function makeContext(options) {
@@ -893,20 +1070,80 @@ function createSSR() {
 		}
 	};
 }
+//#endregion
+//#region src/server/render-api.ts
+/** Shared no-plugin instance — created once, reused for all standalone calls. */
 var _defaultSSR = createSSR();
+/**
+* Render JSX element or App to a ReadableStream.
+*
+* Internally delegates to `createSSR().renderStream()`.
+*
+* @example
+* ```tsx
+* // Simple usage with JSX
+* renderToStream(<App />)
+*
+* // With App instance for DI/plugins
+* const app = defineApp(<App />).use(router);
+* renderToStream(app)
+* ```
+*/
 function renderToStream(input, context) {
 	return _defaultSSR.renderStream(input, context);
 }
+/**
+* Render JSX element or App to a Node.js Readable stream.
+*
+* Faster than `renderToStream()` on Node.js because it bypasses WebStream
+* overhead entirely. Recommended for Express, Fastify, H3, and other
+* Node.js HTTP frameworks.
+*
+* @example
+* ```tsx
+* import { renderToNodeStream } from '@sigx/server-renderer/server';
+*
+* const stream = renderToNodeStream(<App />);
+* stream.pipe(res);
+* ```
+*/
 function renderToNodeStream(input, context) {
 	return _defaultSSR.renderNodeStream(input, context);
 }
+/**
+* Render with callbacks for fine-grained streaming control.
+*
+* Internally delegates to `createSSR().renderStreamWithCallbacks()`.
+*
+* @example
+* ```tsx
+* const app = defineApp(<App />).use(router);
+* await renderToStreamWithCallbacks(app, callbacks)
+* ```
+*/
 async function renderToStreamWithCallbacks(input, callbacks, context) {
 	return _defaultSSR.renderStreamWithCallbacks(input, callbacks, context);
 }
+/**
+* Render JSX element or App to string.
+*
+* Internally delegates to `createSSR().render()`.
+*
+* @example
+* ```tsx
+* const html = await renderToString(<App />);
+*
+* const app = defineApp(<App />).use(router);
+* const html = await renderToString(app);
+* ```
+*/
 async function renderToString(input, context) {
 	return _defaultSSR.render(input, context);
 }
+//#endregion
+//#region src/server/index.ts
 initDirectivesForSSR();
+//#endregion
 export { createSSR as a, renderHeadToString as c, generateReplacementScript as d, generateStreamingScript as f, initDirectivesForSSR as h, renderToString as i, useHead as l, createSSRContext as m, renderToStream as n, collectSSRHead as o, renderVNodeToString as p, renderToStreamWithCallbacks as r, enableSSRHead as s, renderToNodeStream as t, escapeJsonForScript as u };
 
-//# sourceMappingURL=server-pSrHP504.js.map
+//# sourceMappingURL=server-Di7tiBy1.js.map