@db3.ai/app 0.1.0-beta.1

package/dist/ssr/contracts/SsrRenderResult.d.ts

@@ -0,0 +1,21 @@
+import type { DocumentHead } from './DocumentHead.js';
+import type { SsrState } from './SsrRenderContext.js';
+/** 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/dist/ssr/contracts/SsrRenderResult.js

@@ -0,0 +1 @@
+export {};

package/dist/ssr/contracts/SsrRenderer.d.ts

@@ -0,0 +1,9 @@
+import type { SsrRenderContext, SsrState } from './SsrRenderContext.js';
+import type { SsrRenderResult } from './SsrRenderResult.js';
+/**
+ * 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/dist/ssr/contracts/SsrRenderer.js

@@ -0,0 +1 @@
+export {};

package/dist/ssr/contracts/SsrRequest.d.ts

@@ -0,0 +1,16 @@
+/** 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/dist/ssr/contracts/SsrRequest.js

@@ -0,0 +1 @@
+export {};

package/dist/ssr/contracts/index.d.ts

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

package/dist/ssr/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/ssr/createSsrRenderContext.d.ts

@@ -0,0 +1,9 @@
+import type { SsrRenderContext, SsrRequest, SsrState } from './contracts/index.js';
+/**
+ * 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 declare function createSsrRenderContext<TState extends object = SsrState>(request: SsrRequest, state?: TState): SsrRenderContext<TState>;

package/dist/ssr/createSsrRenderContext.js

@@ -0,0 +1,20 @@
+/**
+ * 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(request, state = {}) {
+    return {
+        request,
+        status: 200,
+        head: {
+            meta: [],
+            link: [],
+            script: [],
+        },
+        state,
+        modules: new Set(),
+    };
+}

package/dist/ssr/fastify/contracts/FastifySsrOptions.d.ts

@@ -0,0 +1,21 @@
+import type { SsrRenderer, SsrRequest, SsrState } from '../../contracts/index.js';
+/** 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/dist/ssr/fastify/contracts/FastifySsrOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/ssr/fastify/contracts/index.d.ts

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

package/dist/ssr/fastify/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/ssr/fastify/fastifySsr.d.ts

@@ -0,0 +1,25 @@
+import type { FastifyPluginAsync } from 'fastify';
+import type { SsrState } from '../contracts/index.js';
+import type { FastifySsrOptions } from './contracts/index.js';
+/**
+ * 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 declare function fastifySsr<TState extends object = SsrState>(options: FastifySsrOptions<TState>): FastifyPluginAsync;

package/dist/ssr/fastify/fastifySsr.js

@@ -0,0 +1,89 @@
+import { createSsrRenderContext, renderSsrDocument } from '../index.js';
+/**
+ * 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(options) {
+    return async function platformFastifySsr(server) {
+        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(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) {
+    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, request) {
+    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, headers) {
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        reply.header(name, value);
+    }
+}

package/dist/ssr/fastify/index.d.ts

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

package/dist/ssr/fastify/index.js

@@ -0,0 +1 @@
+export { fastifySsr } from './fastifySsr.js';

package/dist/ssr/index.d.ts

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

package/dist/ssr/index.js

@@ -0,0 +1,5 @@
+export { SSR_APP_MARKER, SSR_HEAD_MARKER, SSR_STATE_MARKER, } from './constants.js';
+export { createSsrRenderContext } from './createSsrRenderContext.js';
+export { renderDocumentHead } from './renderDocumentHead.js';
+export { renderSsrDocument } from './renderSsrDocument.js';
+export { serializeSsrState } from './serializeSsrState.js';

package/dist/ssr/renderDocumentHead.d.ts

@@ -0,0 +1,8 @@
+import type { DocumentHead } from './contracts/index.js';
+/**
+ * Renders collected head metadata into HTML tags.
+ *
+ * @param head - Request-owned document metadata.
+ * @returns Escaped HTML ready for the document head marker.
+ */
+export declare function renderDocumentHead(head: DocumentHead): string;

package/dist/ssr/renderDocumentHead.js

@@ -0,0 +1,62 @@
+/**
+ * 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) {
+    const tags = [];
+    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 = {}) {
+    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) {
+    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) {
+    return value
+        .replace(/<\/script/gi, '<\\/script')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}

package/dist/ssr/renderSsrDocument.d.ts

@@ -0,0 +1,14 @@
+import type { SsrRenderContext, SsrRenderResult } from './contracts/index.js';
+/**
+ * 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 declare function renderSsrDocument<TState extends object>(template: string, context: SsrRenderContext<TState>, result: SsrRenderResult<TState>): string;

package/dist/ssr/renderSsrDocument.js

@@ -0,0 +1,28 @@
+import { SSR_APP_MARKER, SSR_HEAD_MARKER, SSR_STATE_MARKER } from './constants.js';
+import { renderDocumentHead } from './renderDocumentHead.js';
+import { serializeSsrState } from './serializeSsrState.js';
+/**
+ * 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(template, context, result) {
+    if (!template.includes(SSR_APP_MARKER)) {
+        throw new Error(`SSR template must contain ${SSR_APP_MARKER}.`);
+    }
+    const values = {
+        [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/dist/ssr/serializeSsrState.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function serializeSsrState(state: unknown): string;

package/dist/ssr/serializeSsrState.js

@@ -0,0 +1,18 @@
+/**
+ * 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) {
+    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/dist/ssr/vite/contracts/ViteSsrOptions.d.ts

@@ -0,0 +1,45 @@
+import type { SsrRenderer, SsrState } from '../../contracts/index.js';
+/** 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/dist/ssr/vite/contracts/ViteSsrOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/ssr/vite/contracts/index.d.ts

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

package/dist/ssr/vite/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/ssr/vite/fastifyViteSsr.d.ts

@@ -0,0 +1,24 @@
+import type { FastifyPluginAsync } from 'fastify';
+import type { SsrState } from '../contracts/index.js';
+import type { FastifyViteSsrOptions } from './contracts/index.js';
+/**
+ * Creates a Fastify plugin that owns Vite development and production SSR.
+ *
+ * The adapter loads application code through Vite in development, immutable
+ * build artifacts in production, optional static assets, and route-specific
+ * manifest links. Vue, routing and page data remain application concerns.
+ *
+ * @param options - Vite application paths and explicit SSR route ownership.
+ * @returns Fastify plugin ready to register on a web-delivery process.
+ *
+ * @example
+ * await server.register(fastifyViteSsr({
+ * 	root: import.meta.dirname,
+ * 	routes: ['/blog', '/blog/*'],
+ * 	staticAssets: {
+ * 		prefix: '/site-assets/',
+ * 		directory: 'dist/client/site-assets',
+ * 	},
+ * }));
+ */
+export declare function fastifyViteSsr<TState extends object = SsrState>(options: FastifyViteSsrOptions<TState>): FastifyPluginAsync;