@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/render/modules/render/application/usecases/stream-page.ts

@@ -0,0 +1,159 @@
+/**
+ * Stream Page Use Case
+ * Produce a streaming document Response for one request — document head
+ * flushes first, app markup streams into the mount point, then the tail
+ */
+
+import {
+	createDocumentModel,
+	hydrationScriptTag,
+	renderAssetTags,
+	renderHeadHtml,
+} from "#render/modules/render/domain";
+import type { ServerRendererPort } from "#render/modules/render/ports";
+import type { Renderable, RenderOptions } from "#render/types";
+
+export interface StreamPageInput {
+	renderable: Renderable;
+	options?: RenderOptions;
+	headTags?: string[];
+	/** Head HTML collected after the render pass (e.g. HeadProvider sink) */
+	collectHead?: () => string;
+	title?: string;
+	lang?: string;
+	/** Client entry script url emitted at the end of body */
+	entry?: string;
+	headers?: HeadersInit;
+	/** Response status — number, or lazy getter read after the render pass */
+	status?: number | (() => number);
+	/** CSP nonce applied to the hydration script */
+	nonce?: string;
+}
+
+const encoder = new TextEncoder();
+
+/**
+ * Inject a raw HTML fragment right before </head> while streaming.
+ * Used to publish hydration data once it is known.
+ */
+export const injectBeforeHeadClose = (
+	stream: ReadableStream<Uint8Array>,
+	fragment: string,
+): ReadableStream<Uint8Array> => {
+	let injected = false;
+	const marker = "</head>";
+
+	return stream.pipeThrough(
+		new TransformStream<Uint8Array, Uint8Array>({
+			transform(chunk, controller) {
+				if (injected) {
+					controller.enqueue(chunk);
+					return;
+				}
+				const text = new TextDecoder().decode(chunk);
+				const index = text.indexOf(marker);
+				if (index === -1) {
+					controller.enqueue(chunk);
+					return;
+				}
+				injected = true;
+				controller.enqueue(
+					encoder.encode(text.slice(0, index) + fragment + text.slice(index)),
+				);
+			},
+		}),
+	);
+};
+
+/**
+ * Render a Solid tree into a streaming text/html Response with a full
+ * document shell: head prefix → app stream → document suffix.
+ */
+export const streamPage = (
+	renderer: ServerRendererPort,
+	input: StreamPageInput,
+): Response => {
+	const context = input.options?.context;
+	const hydration = context?.hydration ?? { loaders: {}, stores: {} };
+
+	// Render pass runs synchronously — head tags collect before prefix flush
+	const appStream = renderer.renderToStream(input.renderable);
+
+	const headFromContext = context?.head?.renderToString();
+	const collected = input.collectHead?.();
+	const model = createDocumentModel({
+		lang: input.lang,
+		title: input.title,
+		headTags: [
+			...(input.headTags ?? []),
+			...(collected ? [collected] : []),
+			...(headFromContext ? [headFromContext] : []),
+		],
+		assets: { entry: input.entry },
+	});
+	const prefix = [
+		"<!doctype html>",
+		`<html lang="${model.lang}">`,
+		`<head>${renderHeadHtml(model)}${hydrationScriptTag(hydration, input.nonce)}</head>`,
+		'<body><div id="app">',
+	].join("");
+	const suffix = `</div>${renderAssetTags(model)}</body></html>`;
+
+	const stream = new ReadableStream<Uint8Array>({
+		async start(controller) {
+			controller.enqueue(encoder.encode(prefix));
+			const reader = appStream.getReader();
+			try {
+				for (;;) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					controller.enqueue(value);
+				}
+			} finally {
+				reader.releaseLock();
+			}
+			// Deferred loader values — stream a resolve script per key as
+			// each promise settles, before the document closes
+			const deferred = (
+				hydration as {
+					__deferred?: Map<string, Promise<unknown>>;
+				}
+			).__deferred;
+			if (deferred?.size) {
+				controller.enqueue(encoder.encode("</div>"));
+				// lane priority — "low" deferreds stream last
+				const keys = [...deferred.entries()]
+					.sort(
+						(a, b) =>
+							((a[1] as { lane?: string }).lane === "low" ? 1 : 0) -
+							((b[1] as { lane?: string }).lane === "low" ? 1 : 0),
+					)
+					.map(([k]) => k);
+				for (const key of keys) {
+					const promise = deferred.get(key) as Promise<unknown>;
+					const value = await promise.catch(() => null);
+					controller.enqueue(
+						encoder.encode(
+							`<script>window.__sfDeferResolve(${JSON.stringify(key)},${JSON.stringify(
+								value,
+							).replace(/</g, "\\u003c")})</script>`,
+						),
+					);
+				}
+				controller.enqueue(encoder.encode("</body></html>"));
+			} else {
+				controller.enqueue(encoder.encode(suffix));
+			}
+			controller.close();
+		},
+	});
+
+	const headers = new Headers(input.headers);
+	if (!headers.has("Content-Type")) {
+		headers.set("Content-Type", "text/html; charset=utf-8");
+	}
+
+	const status =
+		typeof input.status === "function" ? input.status() : (input.status ?? 200);
+	return new Response(stream, { status, headers });
+};

package/src/render/modules/render/domain/index.ts

@@ -0,0 +1,3 @@
+export * from "./models";
+export * from "./operations";
+export * from "./validators";

package/src/render/modules/render/domain/models/context.ts

@@ -0,0 +1,34 @@
+/**
+ * Render Context Model
+ * Carries per-request state through the SSR pipeline
+ */
+
+import type { HydrationPayload, RenderMode } from "#render/types";
+
+export interface RenderContextModel {
+	mode: RenderMode;
+	request?: Request;
+	hydration: HydrationPayload;
+	headTags: string[];
+	/** Middleware → render state bag */
+	state: Record<string, unknown>;
+	assets: {
+		css: string[];
+		js: string[];
+		preload: string[];
+		entry?: string;
+	};
+}
+
+export const createRenderContext = (
+	mode: RenderMode = "ssr",
+	request?: Request,
+	state: Record<string, unknown> = {},
+): RenderContextModel => ({
+	mode,
+	request,
+	headTags: [],
+	hydration: { loaders: {}, stores: {} },
+	state,
+	assets: { css: [], js: [], preload: [] },
+});

package/src/render/modules/render/domain/models/document.ts

@@ -0,0 +1,26 @@
+/**
+ * Document Model
+ * Represents the HTML document shell produced by SSR
+ */
+
+import type { DocumentAssets } from "#render/types";
+
+export interface DocumentModel {
+	lang: string;
+	title?: string;
+	headTags: string[];
+	assets: DocumentAssets;
+	hydrationScript?: string;
+	bodyAttributes?: Record<string, string>;
+}
+
+export const createDocumentModel = (
+	partial: Partial<DocumentModel> = {},
+): DocumentModel => ({
+	lang: partial.lang ?? "en",
+	headTags: partial.headTags ?? [],
+	assets: partial.assets ?? {},
+	title: partial.title,
+	hydrationScript: partial.hydrationScript,
+	bodyAttributes: partial.bodyAttributes,
+});

package/src/render/modules/render/domain/models/index.ts

@@ -0,0 +1,2 @@
+export * from "./context";
+export * from "./document";

package/src/render/modules/render/domain/operations/document.ts

@@ -0,0 +1,58 @@
+/**
+ * Document Operations
+ * Pure functions that turn a DocumentModel into HTML fragments
+ */
+
+import type { DocumentModel } from "#render/modules/render/domain/models";
+
+const escapeAttr = (value: string): string =>
+	value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+
+export const renderAttributes = (attrs: Record<string, string> = {}): string =>
+	Object.entries(attrs)
+		.map(([key, value]) => `${key}="${escapeAttr(value)}"`)
+		.join(" ");
+
+/**
+ * Render head-side asset tags — modulepreload hints and stylesheets
+ */
+export const renderHeadAssetTags = (model: DocumentModel): string => {
+	const tags: string[] = [];
+	for (const href of model.assets.preload ?? []) {
+		tags.push(`<link rel="modulepreload" href="${escapeAttr(href)}">`);
+	}
+	for (const href of model.assets.css ?? []) {
+		tags.push(`<link rel="stylesheet" href="${escapeAttr(href)}">`);
+	}
+	return tags.join("");
+};
+
+/**
+ * Render body-side asset tags — the client entry and extra js scripts,
+ * emitted at the end of <body>
+ */
+export const renderAssetTags = (model: DocumentModel): string => {
+	const tags: string[] = [];
+	if (model.assets.entry) {
+		tags.push(
+			`<script type="module" src="${escapeAttr(model.assets.entry)}" async></script>`,
+		);
+	}
+	for (const src of model.assets.js ?? []) {
+		tags.push(`<script type="module" src="${escapeAttr(src)}" async></script>`);
+	}
+	return tags.join("");
+};
+
+/**
+ * Render the complete <head> inner HTML from a document model
+ */
+export const renderHeadHtml = (model: DocumentModel): string => {
+	const parts: string[] = ['<meta charset="utf-8">'];
+	if (model.title) {
+		parts.push(`<title>${escapeAttr(model.title)}</title>`);
+	}
+	parts.push(...model.headTags);
+	parts.push(renderHeadAssetTags(model));
+	return parts.join("");
+};

package/src/render/modules/render/domain/operations/hydration.ts

@@ -0,0 +1,58 @@
+/**
+ * Hydration Operations
+ * Serialize and deserialize the hydration payload embedded in SSR HTML
+ */
+
+import type { HydrationPayload } from "#render/types";
+
+export const HYDRATION_GLOBAL = "__SOLID_DATA__";
+
+const escapeScript = (value: string): string =>
+	value.replace(/</g, "\\u003c").replace(/-->/g, "--\\>");
+
+export const serializeHydration = (payload: HydrationPayload): string =>
+	escapeScript(JSON.stringify(payload));
+
+export const deserializeHydration = (raw: string): HydrationPayload =>
+	JSON.parse(raw) as HydrationPayload;
+
+/**
+ * Inline script tag that publishes the payload to the client —
+ * also seeds `self._$HY` so Solid's streaming resource scripts
+ * (`_$HY.r[...]`) can run before the client runtime loads
+ */
+export const hydrationScriptTag = (
+	payload: HydrationPayload,
+	nonce?: string,
+): string => {
+	const attr = nonce ? ` nonce="${nonce}"` : "";
+	return (
+		`<script${attr}>self._$HY=self._$HY||{r:{},e:{}};` +
+		"window.__sfDeferV=window.__sfDeferV||{};" +
+		"window.__sfDeferQ=window.__sfDeferQ||{};" +
+		"window.__sfDeferResolve=function(k,v){" +
+		"window.__sfDeferV[k]=v;" +
+		"(window.__sfDeferQ[k]||[]).forEach(function(r){r(v)});" +
+		"delete window.__sfDeferQ[k];};" +
+		"window.__sfDeferWait=function(k){" +
+		"return k in window.__sfDeferV" +
+		"?Promise.resolve(window.__sfDeferV[k])" +
+		":new Promise(function(r){" +
+		"(window.__sfDeferQ[k]=window.__sfDeferQ[k]||[]).push(r)});};" +
+		`window.${HYDRATION_GLOBAL}=${serializeHydration(payload)};</script>`
+	);
+};
+
+/**
+ * Read the payload on the client; returns an empty payload when absent
+ */
+export const readHydrationPayload = (): HydrationPayload => {
+	if (typeof window === "undefined") {
+		return { loaders: {}, stores: {} };
+	}
+	const data = (window as unknown as Record<string, unknown>)[HYDRATION_GLOBAL];
+	if (!data || typeof data !== "object") {
+		return { loaders: {}, stores: {} };
+	}
+	return data as HydrationPayload;
+};

package/src/render/modules/render/domain/operations/index.ts

@@ -0,0 +1,3 @@
+export * from "./document";
+export * from "./hydration";
+export * from "./rsc";

package/src/render/modules/render/domain/operations/rsc.ts

@@ -0,0 +1,53 @@
+/**
+ * RSC-lite wire — a serializable component tree where server
+ * components ship rendered HTML and client components ship
+ * `{type:"ref", name, props}` markers (hydrated via the island
+ * registry). No custom jsx runtime — boundaries are explicit:
+ *
+ *   const tree = await rscTree(async () => ({
+ *     header: <ServerComponent name="h"><Nav/></ServerComponent>,
+ *     counter: <CounterIsland props={{start: 0}} />,
+ *   }));
+ *   // → JSON-safe; on the client: mountRsc(tree, target)
+ */
+
+import type { JSX } from "solid-js";
+import { renderToString } from "solid-js/web";
+
+export interface RscNode {
+	/** "html" = pre-rendered markup; "ref" = client island ref */
+	type: "html" | "ref";
+	html?: string;
+	name?: string;
+	props?: Record<string, unknown>;
+}
+
+export type RscTree = Record<string, RscNode>;
+
+/** Server: build a tree — each value renders to html, islands pass through */
+export const rscTree = async (
+	build: () => Record<string, JSX.Element>,
+): Promise<RscTree> => {
+	const out: RscTree = {};
+	for (const [key, node] of Object.entries(build())) {
+		out[key] = {
+			type: "html",
+			html: await renderToString(() => node),
+		};
+	}
+	return out;
+};
+
+/** Mark a subtree as a client-island ref — registry name + props only */
+export const rscRef = (
+	name: string,
+	props: Record<string, unknown> = {},
+): RscNode => ({ type: "ref", name, props });
+
+/** Client/server: materialize a tree node into DOM-ready html string */
+export const rscNodeToHtml = (node: RscNode): string =>
+	node.type === "html"
+		? (node.html ?? "")
+		: `<div data-solid-island="${node.name}" data-props='${JSON.stringify(
+				node.props ?? {},
+			).replaceAll("'", "&#39;")}'></div>`;

package/src/render/modules/render/domain/validators/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Render Validators
+ */
+
+import type { HydrationPayload } from "#render/types";
+
+export const isHydrationPayload = (value: unknown): value is HydrationPayload =>
+	typeof value === "object" &&
+	value !== null &&
+	"loaders" in value &&
+	"stores" in value;

package/src/render/modules/render/index.ts

@@ -0,0 +1,3 @@
+export * from "./application";
+export * from "./domain";
+export * from "./ports";

package/src/render/modules/render/ports/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Render Ports
+ * Abstractions over the concrete Solid renderer so the domain stays pure
+ */
+
+import type { JSX } from "solid-js";
+import type { Renderable } from "#render/types";
+
+export interface ServerRendererPort {
+	renderToString(renderable: Renderable): Promise<string>;
+	renderToStream(renderable: Renderable): ReadableStream<Uint8Array>;
+}
+
+export interface ClientHydratorPort {
+	hydrate(renderable: Renderable, element: Element): () => void;
+	mount(renderable: () => JSX.Element, element: Element): () => void;
+}

package/src/render/presentation/ClientComponent.tsx

@@ -0,0 +1,42 @@
+/**
+ * <ClientComponent> — typed client-island boundary
+ * The counterpart to <ServerComponent>: children hydrate as an island
+ * (their JS ships to the browser) while props are serialized into the
+ * island marker — typed so only JSON-serializable props cross:
+ *
+ *   const Counter = defineClientComponent<{ start: number }>(
+ *     "counter",
+ *     (props) => { const [n, setN] = createSignal(props.start); ... }
+ *   );
+ */
+
+import type { Component, JSX } from "solid-js";
+import { Island, registerIsland } from "./Island";
+
+/** Props that can cross the island boundary — JSON-serializable only */
+export type SerializableProps = Record<
+	string,
+	string | number | boolean | null | object | undefined
+>;
+
+export interface ClientComponentProps<P extends SerializableProps> {
+	/** Props serialized into the island marker for hydration */
+	props: P;
+}
+
+/**
+ * Define a typed client island — registers the component under `name`
+ * and returns a boundary component; hydration is done by
+ * hydrateIslands() which reads the serialized props
+ */
+export const defineClientComponent = <P extends SerializableProps>(
+	name: string,
+	component: Component<P>,
+): Component<ClientComponentProps<P>> => {
+	registerIsland(name, component as Component<Record<string, unknown>>);
+	return (boundary: ClientComponentProps<P>): JSX.Element => (
+		<Island name={name} props={boundary.props}>
+			{component(boundary.props)}
+		</Island>
+	);
+};

package/src/render/presentation/Document.tsx

@@ -0,0 +1,45 @@
+/**
+ * Document Component
+ * Full HTML document shell rendered around the app during SSR
+ */
+
+import { For, type JSX } from "solid-js";
+import { HydrationScript } from "solid-js/web";
+import type { DocumentAssets } from "#render/types";
+
+export interface DocumentProps {
+	lang?: string;
+	title?: string;
+	head?: JSX.Element;
+	assets?: DocumentAssets;
+	hydrationScript?: string;
+	bodyAttributes?: Record<string, string>;
+	children?: JSX.Element;
+}
+
+export const Document = (props: DocumentProps): JSX.Element => {
+	return (
+		<html lang={props.lang ?? "en"}>
+			<head>
+				<meta charset="utf-8" />
+				<meta name="viewport" content="width=device-width, initial-scale=1" />
+				{props.title ? <title>{props.title}</title> : null}
+				{props.head}
+				<HydrationScript />
+				{props.hydrationScript ? (
+					// oxlint-disable-next-line no-inner-html
+					<script innerHTML={props.hydrationScript} />
+				) : null}
+			</head>
+			<body {...props.bodyAttributes}>
+				<div id="app">{props.children}</div>
+				<For each={props.assets?.css ?? []}>
+					{(href) => <link rel="stylesheet" href={href} />}
+				</For>
+				<For each={props.assets?.js ?? []}>
+					{(src) => <script type="module" src={src} async />}
+				</For>
+			</body>
+		</html>
+	);
+};

package/src/render/presentation/Island.tsx

@@ -0,0 +1,146 @@
+/**
+ * Island Component
+ * Selective hydration boundary — SSR renders full markup, the client
+ * hydrates each island independently via hydrateIslands()
+ */
+
+import type { Component, JSX } from "solid-js";
+import { onCleanup, onMount } from "solid-js";
+import { hydrate, isServer } from "solid-js/web";
+
+export interface IslandProps {
+	name: string;
+	props?: Record<string, unknown>;
+	children?: JSX.Element;
+	/**
+	 * Deferred render — SSR emits `fallback`, the client fetches the
+	 * island fragment from `/_island/<name>` and hydrates it
+	 */
+	defer?: boolean;
+	/** Placeholder while a deferred island loads */
+	fallback?: JSX.Element;
+}
+
+const registry = new Map<string, Component<Record<string, unknown>>>();
+
+export const registerIsland = (
+	name: string,
+	component: Component<Record<string, unknown>>,
+): void => {
+	registry.set(name, component);
+	// Remote island bundles register here too so cross-origin
+	// <RemoteIsland hydrate> can resolve them
+	if (typeof window !== "undefined") {
+		window.__sfIslands = { ...window.__sfIslands, [name]: component };
+	}
+};
+
+/** Registry lookup — used by the `/_island` remote endpoint */
+export const getIsland = (
+	name: string,
+): Component<Record<string, unknown>> | undefined => registry.get(name);
+
+/**
+ * SSR: renders children inside a marker element carrying serialized props.
+ * Client: markers are hydrated independently by hydrateIslands().
+ */
+export const Island = (props: IslandProps): JSX.Element => {
+	if (props.defer) {
+		if (isServer) {
+			return (
+				<div
+					data-solid-island-defer={props.name}
+					data-props={JSON.stringify(props.props ?? {})}
+				>
+					{props.fallback}
+				</div>
+			);
+		}
+		let host: HTMLDivElement | undefined;
+		let disposers: Array<() => void> = [];
+		onCleanup(() => {
+			for (const dispose of disposers) dispose();
+		});
+		onMount(() => {
+			const load = async () => {
+				const q = new URLSearchParams(
+					Object.entries(props.props ?? {}).map(([k, v]) => [k, String(v)]),
+				);
+				const res = await fetch(
+					`/_island/${props.name}${q.size ? `?${q}` : ""}`,
+				);
+				if (!host) return;
+				host.innerHTML = await res.text();
+				const comp = lookupIsland(props.name);
+				if (comp) {
+					try {
+						disposers = [
+							hydrate(() => comp(props.props ?? {}), host as HTMLElement),
+						];
+					} catch {
+						// fragment lacked hydration markers — client render instead
+						host.innerHTML = "";
+						disposers = [
+							hydrate(() => comp(props.props ?? {}), host as HTMLElement),
+						];
+					}
+				}
+			};
+			void load();
+		});
+		return (
+			<div ref={host} data-solid-island-defer={props.name}>
+				{props.fallback}
+			</div>
+		);
+	}
+	if (isServer) {
+		return (
+			<div
+				data-solid-island={props.name}
+				data-props={JSON.stringify(props.props ?? {})}
+			>
+				{props.children}
+			</div>
+		);
+	}
+	return <>{props.children}</>;
+};
+
+declare global {
+	interface Window {
+		/** Remote bundles expose their island components here */
+		__sfIslands?: Record<string, Component<Record<string, unknown>>>;
+	}
+}
+
+const lookupIsland = (
+	name: string,
+): Component<Record<string, unknown>> | undefined =>
+	registry.get(name) ??
+	(typeof window !== "undefined" ? window.__sfIslands?.[name] : undefined);
+
+/**
+ * Scan the document for island markers and hydrate each registered island.
+ * Unregistered islands are skipped so partial hydration stays safe.
+ */
+export const hydrateIslands = (
+	root: ParentNode = document,
+): Array<() => void> => {
+	const disposers: Array<() => void> = [];
+	const markers = root.querySelectorAll("[data-solid-island]");
+
+	for (const marker of markers) {
+		const name = marker.getAttribute("data-solid-island") ?? "";
+		const component = lookupIsland(name);
+		if (!component) continue;
+
+		const raw = marker.getAttribute("data-props") ?? "{}";
+		const islandProps = JSON.parse(raw) as Record<string, unknown>;
+		disposers.push(
+			hydrate(() => component(islandProps), marker as HTMLElement),
+		);
+	}
+
+	return disposers;
+};