@db3.ai/app 0.1.0-beta.1

package/src/ssr/contracts/SsrRenderResult.ts

@@ -0,0 +1,23 @@
+import type { DocumentHead } from './DocumentHead';
+import type { SsrState } from './SsrRenderContext';
+
+/** Header value accepted from an application SSR render result. */
+export type SsrResponseHeaderValue = string | number | string[];
+
+/**
+ * Application-owned output produced for one server-side render request.
+ *
+ * Optional values override their equivalents collected on the render context.
+ */
+export interface SsrRenderResult<TState extends object = SsrState> {
+	/** Rendered application markup inserted into the HTML document shell. */
+	appHtml: string;
+	/** Optional HTTP status override, such as 404 for a rendered not-found page. */
+	status?: number;
+	/** Optional document head override. */
+	head?: DocumentHead;
+	/** Optional client hydration state override. */
+	state?: TState;
+	/** Additional response headers such as Location or cache policy. */
+	headers?: Record<string, SsrResponseHeaderValue>;
+}

package/src/ssr/contracts/SsrRenderer.ts

@@ -0,0 +1,12 @@
+import type { SsrRenderContext, SsrState } from './SsrRenderContext';
+import type { SsrRenderResult } from './SsrRenderResult';
+
+/**
+ * Application server entry capable of rendering a matched URL.
+ *
+ * The application owns Vue, its router, data loading and component lifecycle.
+ * The framework owns the stable request, document and HTTP response boundary.
+ */
+export type SsrRenderer<TState extends object = SsrState> = (
+	context: SsrRenderContext<TState>,
+) => SsrRenderResult<TState> | Promise<SsrRenderResult<TState>>;

package/src/ssr/contracts/SsrRequest.ts

@@ -0,0 +1,17 @@
+/** Header values exposed to a transport-neutral SSR renderer. */
+export type SsrRequestHeaderValue = string | string[] | undefined;
+
+/**
+ * HTTP request data available to the application SSR entry point.
+ *
+ * The request target remains relative so query strings and encoded path data
+ * are preserved exactly as received by the HTTP adapter.
+ */
+export interface SsrRequest {
+	/** Uppercase HTTP method used for the render request. */
+	method: string;
+	/** Relative request target, including its query string. */
+	url: string;
+	/** Incoming headers copied from the concrete HTTP transport. */
+	headers: Readonly<Record<string, SsrRequestHeaderValue>>;
+}

package/src/ssr/contracts/index.ts

@@ -0,0 +1,19 @@
+export type {
+	DocumentHead,
+	DocumentHeadAttributes,
+	DocumentHeadAttributeValue,
+	DocumentHeadScript,
+} from './DocumentHead';
+export type {
+	SsrRequest,
+	SsrRequestHeaderValue,
+} from './SsrRequest';
+export type {
+	SsrRenderContext,
+	SsrState,
+} from './SsrRenderContext';
+export type {
+	SsrRenderResult,
+	SsrResponseHeaderValue,
+} from './SsrRenderResult';
+export type { SsrRenderer } from './SsrRenderer';

package/src/ssr/createSsrRenderContext.ts

@@ -0,0 +1,25 @@
+import type { SsrRenderContext, SsrRequest, SsrState } from './contracts';
+
+/**
+ * Creates isolated mutable state for one server-side render request.
+ *
+ * @param request - Transport-neutral incoming request.
+ * @param state - Optional initial hydration state owned by this request.
+ * @returns A fresh render context that is safe to mutate during rendering.
+ */
+export function createSsrRenderContext<TState extends object = SsrState>(
+	request: SsrRequest,
+	state: TState = {} as TState,
+): SsrRenderContext<TState> {
+	return {
+		request,
+		status: 200,
+		head: {
+			meta: [],
+			link: [],
+			script: [],
+		},
+		state,
+		modules: new Set(),
+	};
+}

package/src/ssr/examples/createPublicPageServer.ts

@@ -0,0 +1,32 @@
+import Fastify, { type FastifyInstance } from 'fastify';
+import { SSR_APP_MARKER, SSR_HEAD_MARKER, SSR_STATE_MARKER } from '@db3.ai/app/ssr';
+import { fastifySsr } from '@db3.ai/app/ssr/fastify';
+
+/**
+ * Creates a public HTML route with isolated metadata and escaped JSON state.
+ *
+ * The literal body is trusted application markup. Request input goes only into
+ * the escaped head/state serializers, never raw HTML. This non-hydrating lab
+ * has no Vue dependency; an application may hydrate the same state separately.
+ * @returns Server owned and closed by the caller, without a listening socket.
+ */
+export async function createPublicPageServer(): Promise<FastifyInstance> {
+	const server = Fastify({ logger: false });
+	const template = `<!doctype html><html lang="en"><head><meta charset="utf-8">${SSR_HEAD_MARKER}</head><body>${SSR_APP_MARKER}<script id="page-state" type="application/json">${SSR_STATE_MARKER}</script></body></html>`;
+	server.get('/api/health', async () => ({ ok: true }));
+	await server.register(fastifySsr({
+		template,
+		routes: ['/hello', '/broken'],
+		/** Collects state on the request-owned context and returns trusted markup. */
+		async render(context) {
+			const url = new URL(context.request.url, 'https://notes.example.test');
+			if (url.pathname === '/broken') throw new Error('Controlled private render failure');
+			const name = (url.searchParams.get('name') || 'Developer').slice(0, 200);
+			context.state.name = name;
+			context.head.title = `Hello ${name}`;
+			await Promise.resolve();
+			return { appHtml: '<main><h1>Your app is running</h1><p>Literal $& stays literal.</p></main>', headers: { 'Cache-Control': 'private, no-store' } };
+		},
+	}));
+	return server;
+}

package/src/ssr/examples/runPublicPages.ts

@@ -0,0 +1,25 @@
+import { pathToFileURL } from 'node:url';
+import { createPublicPageServer } from './createPublicPageServer';
+
+/** Extracts this lab's JSON script contents without evaluating executable code. */
+export function pageState(html: string): { name: string } {
+	const match = html.match(/<script id="page-state" type="application\/json">([\s\S]*?)<\/script>/);
+	if (!match) throw new Error('Missing page-state JSON.');
+	return JSON.parse(match[1]!);
+}
+
+/** Runs real SSR requests, safe state, isolated concurrent renders and error recovery. */
+export async function runPublicPages() {
+	const server = await createPublicPageServer();
+	try {
+		const [ada, grace] = await Promise.all([server.inject('/hello?name=Ada'), server.inject('/hello?name=Grace')]);
+		const unsafe = '</script><script>alert(1)</script>$&';
+		const escaped = await server.inject(`/hello?name=${encodeURIComponent(unsafe)}`);
+		const broken = await server.inject('/broken');
+		const recovered = await server.inject('/hello');
+		const missingApi = await server.inject('/api/missing');
+		return { status: ada.statusCode, isolated: pageState(ada.body).name === 'Ada' && pageState(grace.body).name === 'Grace', safeState: pageState(escaped.body).name === unsafe && !escaped.body.includes('</script><script>alert(1)'), literalMarkup: ada.body.includes('Literal $& stays literal.'), failure: broken.statusCode, privateError: broken.body === 'Internal Server Error', recovered: recovered.statusCode, missingApi: missingApi.statusCode };
+	} finally { await server.close(); }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runPublicPages(), null, 2));

package/src/ssr/fastify/contracts/FastifySsrOptions.ts

@@ -0,0 +1,24 @@
+import type { SsrRenderer, SsrRequest, SsrState } from '../../contracts';
+
+/** Loads the current application document template for a render request. */
+export type SsrTemplateLoader = (request: SsrRequest) => string | Promise<string>;
+
+/** Determines whether the Fastify SSR fallback owns an incoming URL. */
+export type SsrRequestMatcher = (request: SsrRequest) => boolean | Promise<boolean>;
+
+/**
+ * Configuration for the optional Fastify SSR adapter.
+ *
+ * Applications own their renderer and template. The adapter owns request
+ * conversion, response headers, status handling and the private error boundary.
+ */
+export interface FastifySsrOptions<TState extends object = SsrState> {
+	/** Application server entry used to render matching requests. */
+	render: SsrRenderer<TState>;
+	/** HTML shell or loader used for every matching request. */
+	template: string | SsrTemplateLoader;
+	/** Explicit Fastify page routes owned by this renderer. */
+	routes?: readonly string[];
+	/** Optional ownership check for excluding API or SPA paths. */
+	shouldRender?: SsrRequestMatcher;
+}

package/src/ssr/fastify/contracts/index.ts

@@ -0,0 +1,5 @@
+export type {
+	FastifySsrOptions,
+	SsrRequestMatcher,
+	SsrTemplateLoader,
+} from './FastifySsrOptions';

package/src/ssr/fastify/fastifySsr.ts

@@ -0,0 +1,110 @@
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+
+import { createSsrRenderContext, renderSsrDocument } from '..';
+import type { SsrRequest, SsrResponseHeaderValue, SsrState } from '../contracts';
+import type { FastifySsrOptions } from './contracts';
+
+/**
+ * Creates an encapsulated Fastify plugin that renders unmatched page requests.
+ *
+ * Concrete API routes registered on the same Fastify instance remain more
+ * specific than the wildcard page route. `shouldRender` can preserve a JSON
+ * not-found boundary for reserved prefixes such as `/api`.
+ *
+ * @param options - Application renderer, document template and route ownership.
+ * @returns Fastify plugin ready to register on an application server.
+ *
+ * @example
+ * await server.register(fastifySsr({
+ * 	template,
+ * 	render: renderPage,
+ * 	routes: ['/blog', '/blog/*'],
+ * 	shouldRender: (request) => {
+ * 		const path = request.url.split('?')[0];
+ * 		return path !== '/api' && !path.startsWith('/api/');
+ * 	},
+ * });
+ */
+export function fastifySsr<TState extends object = SsrState>(
+	options: FastifySsrOptions<TState>,
+): FastifyPluginAsync {
+	return async function platformFastifySsr(server): Promise<void> {
+		const routes = options.routes?.length ? options.routes : ['/*'];
+
+		for (const route of routes) {
+			server.get(route, async (request, reply) => {
+				const ssrRequest = toSsrRequest(request);
+
+				try {
+					if (options.shouldRender && !await options.shouldRender(ssrRequest)) {
+						return reply.callNotFound();
+					}
+
+					const context = createSsrRenderContext<TState>(ssrRequest);
+					const [template, result] = await Promise.all([
+						loadTemplate(options.template, ssrRequest),
+						options.render(context),
+					]);
+					const document = renderSsrDocument(template, context, result);
+
+					applyHeaders(reply, result.headers);
+
+					return reply
+						.status(result.status ?? context.status)
+						.type('text/html; charset=utf-8')
+						.send(document);
+				} catch (error) {
+					request.log.error({ err: error }, 'Server-side render failed.');
+
+					return reply
+						.status(500)
+						.type('text/plain; charset=utf-8')
+						.send('Internal Server Error');
+				}
+			});
+		}
+	};
+}
+
+/**
+ * Converts Fastify request state into the transport-neutral renderer contract.
+ *
+ * @param request - Matched Fastify request.
+ * @returns Request data safe to pass into an application server entry.
+ */
+function toSsrRequest(request: FastifyRequest): SsrRequest {
+	return {
+		method: request.method,
+		url: request.url,
+		headers: { ...request.headers },
+	};
+}
+
+/**
+ * Resolves a static or request-loaded document template.
+ *
+ * @param template - Static template or development-aware loader.
+ * @param request - Current transport-neutral render request.
+ * @returns HTML document template for the request.
+ */
+function loadTemplate(
+	template: FastifySsrOptions['template'],
+	request: SsrRequest,
+): string | Promise<string> {
+	return typeof template === 'function' ? template(request) : template;
+}
+
+/**
+ * Applies application-owned response headers to a Fastify reply.
+ *
+ * @param reply - Active Fastify reply.
+ * @param headers - Optional headers returned by the renderer.
+ */
+function applyHeaders(
+	reply: FastifyReply,
+	headers: Record<string, SsrResponseHeaderValue> | undefined,
+): void {
+	for (const [name, value] of Object.entries(headers ?? {})) {
+		reply.header(name, value);
+	}
+}

package/src/ssr/fastify/index.ts

@@ -0,0 +1,2 @@
+export { fastifySsr } from './fastifySsr';
+export type * from './contracts';

package/src/ssr/index.ts

@@ -0,0 +1,10 @@
+export {
+	SSR_APP_MARKER,
+	SSR_HEAD_MARKER,
+	SSR_STATE_MARKER,
+} from './constants';
+export { createSsrRenderContext } from './createSsrRenderContext';
+export { renderDocumentHead } from './renderDocumentHead';
+export { renderSsrDocument } from './renderSsrDocument';
+export { serializeSsrState } from './serializeSsrState';
+export type * from './contracts';

package/src/ssr/renderDocumentHead.ts

@@ -0,0 +1,72 @@
+import type { DocumentHead, DocumentHeadAttributes } from './contracts';
+
+/**
+ * Renders collected head metadata into HTML tags.
+ *
+ * @param head - Request-owned document metadata.
+ * @returns Escaped HTML ready for the document head marker.
+ */
+export function renderDocumentHead(head: DocumentHead): string {
+	const tags: string[] = [];
+
+	if (head.title) {
+		tags.push(`<title>${escapeHtml(head.title)}</title>`);
+	}
+
+	for (const attributes of head.meta) {
+		tags.push(`<meta${renderAttributes(attributes)}>`);
+	}
+
+	for (const attributes of head.link) {
+		tags.push(`<link${renderAttributes(attributes)}>`);
+	}
+
+	for (const script of head.script) {
+		tags.push(`<script${renderAttributes(script.attributes)}>${escapeScriptContent(script.content ?? '')}</script>`);
+	}
+
+	return tags.join('\n');
+}
+
+/**
+ * Renders defined tag attributes with HTML-safe values.
+ *
+ * @param attributes - Attribute names and values for one head element.
+ * @returns Leading-space-prefixed HTML attributes.
+ */
+function renderAttributes(attributes: DocumentHeadAttributes = {}): string {
+	return Object.entries(attributes)
+		.filter(([, value]) => value !== undefined && value !== null && value !== false)
+		.map(([name, value]) => value === true
+			? ` ${name}`
+			: ` ${name}="${escapeHtml(String(value))}"`)
+		.join('');
+}
+
+/**
+ * Escapes a value for an HTML text or quoted-attribute context.
+ *
+ * @param value - Untrusted text value.
+ * @returns HTML-safe text.
+ */
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;');
+}
+
+/**
+ * Prevents trusted inline content from closing its containing script element.
+ *
+ * @param value - Trusted inline script or JSON-LD content.
+ * @returns Script content safe from premature element termination.
+ */
+function escapeScriptContent(value: string): string {
+	return value
+		.replace(/<\/script/gi, '<\\/script')
+		.replace(/\u2028/g, '\\u2028')
+		.replace(/\u2029/g, '\\u2029');
+}

package/src/ssr/renderSsrDocument.ts

@@ -0,0 +1,35 @@
+import { SSR_APP_MARKER, SSR_HEAD_MARKER, SSR_STATE_MARKER } from './constants';
+import type { SsrRenderContext, SsrRenderResult } from './contracts';
+import { renderDocumentHead } from './renderDocumentHead';
+import { serializeSsrState } from './serializeSsrState';
+
+/**
+ * Assembles a complete HTML document from an application render result.
+ *
+ * The application marker is required because omitting rendered content would
+ * silently turn a server-rendered page into an empty client-only shell. Head and
+ * state markers are optional for deliberately non-hydrated documents.
+ *
+ * @param template - Application-owned HTML document shell.
+ * @param context - Request-owned metadata collected during rendering.
+ * @param result - Application markup and optional response overrides.
+ * @returns Complete HTML document ready for the HTTP response.
+ */
+export function renderSsrDocument<TState extends object>(
+	template: string,
+	context: SsrRenderContext<TState>,
+	result: SsrRenderResult<TState>,
+): string {
+	if (!template.includes(SSR_APP_MARKER)) {
+		throw new Error(`SSR template must contain ${SSR_APP_MARKER}.`);
+	}
+
+	const values: Record<string, string> = {
+		[SSR_HEAD_MARKER]: renderDocumentHead(result.head ?? context.head),
+		[SSR_APP_MARKER]: result.appHtml,
+		[SSR_STATE_MARKER]: serializeSsrState(result.state ?? context.state),
+	};
+	// Replace template markers once. Callback values keep $&/$`/$' literal and
+	// prevent marker-like content in rendered HTML from becoming template input.
+	return template.replace(/<!--platform-ssr-(?:head|app|state)-->/g, marker => values[marker]!);
+}

package/src/ssr/serializeSsrState.ts

@@ -0,0 +1,19 @@
+/**
+ * Serialises hydration state without allowing it to terminate an inline script.
+ *
+ * The output is suitable for an `application/json` script element. Applications
+ * should parse the element's text content instead of evaluating JavaScript.
+ *
+ * @param state - JSON-compatible state produced by the application renderer.
+ * @returns Safely escaped JSON text.
+ */
+export function serializeSsrState(state: unknown): string {
+	const json = JSON.stringify(state) ?? 'null';
+
+	return json
+		.replace(/</g, '\\u003c')
+		.replace(/>/g, '\\u003e')
+		.replace(/&/g, '\\u0026')
+		.replace(/\u2028/g, '\\u2028')
+		.replace(/\u2029/g, '\\u2029');
+}

package/src/ssr/vite/contracts/ViteSsrOptions.ts

@@ -0,0 +1,52 @@
+import type { SsrRenderer, SsrState } from '../../contracts';
+
+/** Runtime mode used to select Vite development or production integration. */
+export type ViteSsrMode = 'development' | 'production';
+
+/** Production client assets served directly by the SSR web process. */
+export interface ViteSsrStaticAssets {
+	/** URL prefix reserved for built client assets. */
+	prefix: string;
+	/** Build directory containing the files exposed below the prefix. */
+	directory: string;
+}
+
+/**
+ * Configuration for a first-class Vite SSR application hosted by Fastify.
+ *
+ * Paths may be absolute or relative to `root`. The adapter owns Vite's
+ * development middleware and immutable production build loading while the
+ * application owns the renderer exported by its server entry.
+ */
+export interface FastifyViteSsrOptions<TState extends object = SsrState> {
+	/** Absolute application root containing Vite configuration and source files. */
+	root: string;
+	/** Explicit public page routes rendered by this SSR application. */
+	routes: readonly string[];
+	/** Runtime mode, defaulting from `NODE_ENV`. */
+	mode?: ViteSsrMode;
+	/** Optional Vite config file used by this isolated SSR build in development. */
+	viteConfigFile?: string;
+	/** Source HTML template transformed by Vite during development. */
+	template?: string;
+	/** Vite development server-entry module id. */
+	developmentEntry?: string;
+	/** Production client build directory containing the transformed template. */
+	clientOutDir?: string;
+	/** Production server bundle exporting the application renderer. */
+	serverEntry?: string;
+	/** Production Vite SSR manifest, or false when the app has no client graph. */
+	manifest?: string | false;
+	/** Named server-entry export implementing the framework renderer contract. */
+	renderExport?: string;
+	/** Whether JavaScript files observed through the SSR manifest are preloaded. */
+	preloadJavaScript?: boolean;
+	/** Optional production client asset directory and public prefix. */
+	staticAssets?: ViteSsrStaticAssets;
+}
+
+/** Server-entry namespace containing a framework-compatible renderer export. */
+export type ViteSsrServerModule<TState extends object = SsrState> = Record<
+	string,
+	SsrRenderer<TState> | unknown
+>;

package/src/ssr/vite/contracts/index.ts

@@ -0,0 +1,6 @@
+export type {
+	FastifyViteSsrOptions,
+	ViteSsrMode,
+	ViteSsrServerModule,
+	ViteSsrStaticAssets,
+} from './ViteSsrOptions';