vue-ssr-lite 0.0.3

package/engine/SsrEngine.js

@@ -0,0 +1,139 @@
+// SsrEngine — the framework-agnostic SSR request handler.
+//
+// The engine is deliberately independent of the standalone Node server: it
+// accepts a plain request description and returns a plain response
+// description, so it can be mounted into an existing Node server, Express or
+// similar frameworks, tests, serverless functions, or any environment that
+// can supply `loadTemplate` and `loadRenderModule` implementations. The
+// standalone server in ../server is one (default) host for this engine.
+
+import {
+	injectSsrDocument,
+	renderHeadTags,
+	renderStateScript,
+} from './SsrEngineHtml.js'
+import { selectSsrCookieHeader } from './SsrEngineHostPolicy.js'
+
+export const SSR_HTML_SECURITY_HEADERS = Object.freeze({
+	'referrer-policy': 'strict-origin-when-cross-origin',
+	'x-content-type-options': 'nosniff',
+	'x-frame-options': 'SAMEORIGIN',
+})
+
+/**
+ * Create an SSR request handler.
+ *
+ * options:
+ * - loadTemplate(requestUrl): Promise<string> — marker-carrying HTML template
+ *   (already transformed for the current mode).
+ * - loadRenderModule(): Promise<module> — module exposing the render function.
+ * - renderExport: name of the render export (default 'render').
+ * - config: optional serializable public config forwarded to the render and
+ *   serialized for the browser. Omit it entirely when the app needs none.
+ * - globals: { configKey, stateKey } — serialized global names.
+ * - headAttribute: attribute marking server-rendered head tags.
+ * - defaultHead: raw HTML string injected when the render yields no head
+ *   payload (consumer-owned fallback; empty by default).
+ * - cookieAllowlist / cookieDenylist: cookie-name filtering before SSR.
+ * - renderTimeoutMs: hard budget for one render (default 10000).
+ * - nonce(request): optional per-request CSP nonce provider.
+ */
+export const createSsrRequestHandler = (options) => {
+	const {
+		loadTemplate,
+		loadRenderModule,
+		renderExport = 'render',
+		config,
+		globals = {},
+		headAttribute = 'data-ssr-head',
+		defaultHead = '',
+		cookieAllowlist = [],
+		cookieDenylist = [],
+		renderTimeoutMs = 10_000,
+		nonce,
+	} = options
+
+	if (typeof loadTemplate !== 'function' || typeof loadRenderModule !== 'function') {
+		throw new Error(
+			'createSsrRequestHandler requires loadTemplate and loadRenderModule functions.',
+		)
+	}
+
+	/**
+	 * Handle one SSR request.
+	 *
+	 * request: { url (path + search + hash), host, protocol, cookieHeader }
+	 * Returns: { statusCode, headers, html } — or throws; the host layer owns
+	 * error presentation.
+	 */
+	const handle = async (request) => {
+		const { url = '/', host, protocol = 'http', cookieHeader } = request
+		const module = await loadRenderModule()
+		const render = module[renderExport]
+		if (typeof render !== 'function') {
+			throw new Error(
+				`The SSR module does not export a "${renderExport}" function.`,
+			)
+		}
+
+		const cookie = selectSsrCookieHeader(cookieHeader, cookieAllowlist, cookieDenylist)
+		const renderRequest = {
+			url: `${protocol}://${host}${url}`,
+			host,
+			cookie,
+			config,
+		}
+
+		let timeoutHandle
+		const rendered = await Promise.race([
+			render(renderRequest),
+			new Promise((_resolve, reject) => {
+				timeoutHandle = setTimeout(
+					() => reject(new Error(`SSR render exceeded ${renderTimeoutMs}ms.`)),
+					renderTimeoutMs,
+				)
+				if (typeof timeoutHandle === 'object') timeoutHandle.unref?.()
+			}),
+		]).finally(() => clearTimeout(timeoutHandle))
+
+		if (rendered.redirect) {
+			return {
+				statusCode: rendered.statusCode >= 300 && rendered.statusCode < 400
+					? rendered.statusCode
+					: 302,
+				headers: { location: rendered.redirect, 'cache-control': 'no-store' },
+				html: '',
+			}
+		}
+
+		const template = await loadTemplate(url)
+		const requestNonce = typeof nonce === 'function' ? nonce(request) : undefined
+		const headHtml = renderHeadTags(rendered.head, headAttribute) || defaultHead
+		// Server-level config wins; otherwise the definition-resolved config
+		// reported by the render is serialized, so simple consumers configure
+		// everything in their single application definition.
+		const serializedConfig = config ?? rendered.config
+		const html = injectSsrDocument(template, {
+			head: headHtml,
+			html: rendered.html,
+			teleports: rendered.teleports ?? '',
+			state: renderStateScript(
+				{ config: serializedConfig, state: rendered.state },
+				{ ...globals, nonce: requestNonce },
+			),
+		})
+
+		return {
+			statusCode: rendered.statusCode ?? 200,
+			headers: {
+				'content-type': 'text/html; charset=utf-8',
+				'cache-control': 'private, no-store',
+				vary: 'Host, X-Forwarded-Host',
+				...SSR_HTML_SECURITY_HEADERS,
+			},
+			html,
+		}
+	}
+
+	return { handle }
+}

package/engine/SsrEngineHostPolicy.js

@@ -0,0 +1,132 @@
+// SsrEngineHostPolicy — host normalization and forwarded-header trust policy.
+//
+// Ported from the proven ERP host runtime. Forwarded headers are only ever
+// honored under an explicit trust flag; hosts are validated for length,
+// control characters, credentials, paths, ports, IPv6 brackets, case, and
+// trailing dots. Product classification (which host serves which entry) is a
+// consumer concern layered on top of these primitives.
+
+const firstHeaderValue = (value) =>
+	String(Array.isArray(value) ? value[0] : value || '')
+		.split(',', 1)[0]
+		.trim()
+
+export const normalizeSsrHost = (host) => {
+	const raw = firstHeaderValue(host)
+	if (
+		!raw ||
+		raw.length > 512 ||
+		/[\u0000-\u0020\u007f]/.test(raw) ||
+		/[\\/@?#]/.test(raw)
+	) {
+		return ''
+	}
+
+	try {
+		const authority =
+			raw.includes(':') && raw.split(':').length > 2 && !raw.startsWith('[')
+				? `[${raw}]`
+				: raw
+		const parsed = new URL(`http://${authority}`)
+		if (
+			parsed.username ||
+			parsed.password ||
+			parsed.pathname !== '/' ||
+			parsed.search ||
+			parsed.hash
+		) {
+			return ''
+		}
+		const hostname = parsed.hostname.toLowerCase().replace(/\.$/, '')
+		if (!hostname) return ''
+		const bracketedHostname =
+			hostname.includes(':') && !hostname.startsWith('[')
+				? `[${hostname}]`
+				: hostname
+		return `${bracketedHostname}${parsed.port ? `:${parsed.port}` : ''}`
+	} catch {
+		return ''
+	}
+}
+
+export const stripSsrHostPort = (host) => {
+	const value = normalizeSsrHost(host)
+	if (!value) return ''
+	if (value.startsWith('[')) {
+		const end = value.indexOf(']')
+		return end >= 0 ? value.slice(1, end) : ''
+	}
+	return value.replace(/:\d+$/, '').replace(/\.$/, '')
+}
+
+/** Normalize an exact host or a safe leading-wildcard pattern (`*.domain`). */
+export const normalizeSsrHostPattern = (host) => {
+	const value = String(host || '').trim()
+	if (!value.startsWith('*.')) return normalizeSsrHost(value)
+	const baseDomain = stripSsrHostPort(value.slice(2))
+	if (!baseDomain || baseDomain.includes(':')) return ''
+	return `*.${baseDomain}`
+}
+
+/** True when `hostname` (no port) matches any exact or wildcard pattern. */
+export const matchesSsrHostPatterns = (hostname, patterns) => {
+	const host = stripSsrHostPort(hostname)
+	if (!host) return false
+	for (const candidate of patterns || []) {
+		const pattern = normalizeSsrHostPattern(candidate)
+		if (!pattern) continue
+		if (pattern.startsWith('*.')) {
+			if (host.endsWith(`.${pattern.slice(2)}`)) return true
+		} else if (stripSsrHostPort(pattern) === host) {
+			return true
+		}
+	}
+	return false
+}
+
+export const resolveSsrForwardedHost = (
+	forwardedHost,
+	host,
+	trustForwardedHeaders = false,
+) =>
+	normalizeSsrHost(
+		trustForwardedHeaders ? firstHeaderValue(forwardedHost) || host : host,
+	)
+
+export const resolveSsrForwardedProtocol = (
+	forwardedProtocol,
+	fallbackProtocol = 'http',
+	trustForwardedHeaders = false,
+) => {
+	const fallback = fallbackProtocol === 'https' ? 'https' : 'http'
+	if (!trustForwardedHeaders) return fallback
+	const protocol = firstHeaderValue(forwardedProtocol).toLowerCase()
+	return protocol === 'https' || protocol === 'http' ? protocol : fallback
+}
+
+/**
+ * Filter a Cookie header down to an allowlist of cookie names, with an
+ * optional denylist that always wins. Returns undefined when nothing remains,
+ * so downstream data layers never see unapproved cookies.
+ */
+export const selectSsrCookieHeader = (cookieHeader, allowlist, denylist) => {
+	const allowed = new Set(
+		(allowlist || [])
+			.map((name) => String(name).trim())
+			.filter((name) => /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name)),
+	)
+	const denied = new Set((denylist || []).map((name) => String(name).trim()))
+	for (const name of denied) allowed.delete(name)
+	if (!cookieHeader || allowed.size === 0) return undefined
+	const selected = String(cookieHeader)
+		.split(';')
+		.map((part) => part.trim())
+		.filter(Boolean)
+		.filter((part) => {
+			const separator = part.indexOf('=')
+			if (separator <= 0) return false
+			const name = part.slice(0, separator).trim()
+			return allowed.has(name) && !denied.has(name)
+		})
+	return selected.length > 0 ? selected.join('; ') : undefined
+}

package/engine/SsrEngineHtml.js

@@ -0,0 +1,166 @@
+// SsrEngineHtml — package-owned HTML document primitives.
+//
+// These are invariants, not configuration: escaping rules, XSS-safe state
+// serialization, marker names, and head-tag rendering order are identical in
+// development and production and identical across consumers. The head payload
+// contract and tag order are byte-compatible with the audited ERP renderer so
+// the ERP migration cannot change its SEO output.
+
+export const SSR_MARKERS = Object.freeze({
+	head: '<!--app-head-->',
+	html: '<!--app-html-->',
+	state: '<!--app-state-->',
+	teleports: '<!--app-teleports-->',
+})
+
+export const escapeHtml = (value) =>
+	String(value ?? '')
+		.replaceAll('&', '&amp;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;')
+		.replaceAll("'", '&#39;')
+
+export const escapeXml = (value) =>
+	String(value ?? '')
+		.replaceAll('&', '&amp;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;')
+		.replaceAll("'", '&apos;')
+
+/** XSS-safe JSON serialization for inline <script> payloads. */
+export const serializeState = (value) =>
+	JSON.stringify(value)
+		.replaceAll('<', '\\u003c')
+		.replaceAll('\u2028', '\\u2028')
+		.replaceAll('\u2029', '\\u2029')
+
+/**
+ * Render a head payload into escaped tags.
+ *
+ * Payload contract (all fields optional): title, description, keywords,
+ * robots, ogTitle, ogDescription, ogImage, ogImageAlt, ogUrl, ogType,
+ * ogSiteName, ogLocale, twitterCard, twitterTitle, twitterDescription,
+ * twitterImage, twitterImageAlt, twitterSite, twitterCreator, canonicalUrl,
+ * favicon, jsonLd (array of objects).
+ *
+ * Every rendered tag carries `attribute` so the browser runtime can remove
+ * server-rendered tags before the client SEO layer takes over.
+ */
+export const renderHeadTags = (payload, attribute = 'data-ssr-head') => {
+	if (!payload) return ''
+	const tags = []
+	if (payload.title) {
+		tags.push(`<title ${attribute}>${escapeHtml(payload.title)}</title>`)
+	}
+	const meta = [
+		['name', 'description', payload.description],
+		['name', 'keywords', payload.keywords],
+		['name', 'robots', payload.robots],
+		['property', 'og:title', payload.ogTitle],
+		['property', 'og:description', payload.ogDescription],
+		['property', 'og:image', payload.ogImage],
+		['property', 'og:image:alt', payload.ogImageAlt],
+		['property', 'og:url', payload.ogUrl],
+		['property', 'og:type', payload.ogType],
+		['property', 'og:site_name', payload.ogSiteName],
+		['property', 'og:locale', payload.ogLocale],
+		['name', 'twitter:card', payload.twitterCard],
+		['name', 'twitter:title', payload.twitterTitle],
+		['name', 'twitter:description', payload.twitterDescription],
+		['name', 'twitter:image', payload.twitterImage],
+		['name', 'twitter:image:alt', payload.twitterImageAlt],
+		['name', 'twitter:site', payload.twitterSite],
+		['name', 'twitter:creator', payload.twitterCreator],
+	]
+	for (const [attributeName, name, content] of meta) {
+		if (content != null && content !== '') {
+			tags.push(
+				`<meta ${attribute} ${attributeName}="${escapeHtml(name)}" content="${escapeHtml(content)}">`,
+			)
+		}
+	}
+	if (payload.canonicalUrl) {
+		tags.push(
+			`<link ${attribute} rel="canonical" href="${escapeHtml(payload.canonicalUrl)}">`,
+		)
+	}
+	if (payload.favicon) {
+		tags.push(`<link ${attribute} rel="icon" href="${escapeHtml(payload.favicon)}">`)
+	}
+	for (const block of payload.jsonLd || []) {
+		const json = JSON.stringify(block).replaceAll('<', '\\u003c')
+		tags.push(`<script ${attribute} type="application/ld+json">${json}</script>`)
+	}
+	return tags.join('')
+}
+
+/**
+ * Render the state script exposing serialized public config and hydration
+ * state on package-owned (or consumer-overridden) globals. Emits nothing when
+ * both parts are empty. `nonce` supports strict Content Security Policies.
+ */
+export const renderStateScript = (
+	{ config, state },
+	{ configKey = '__SSR_CONFIG__', stateKey = '__SSR_STATE__', nonce } = {},
+) => {
+	const parts = []
+	if (config != null && Object.keys(config).length > 0) {
+		parts.push(`window.${configKey}=${serializeState(config)}`)
+	}
+	if (state != null) {
+		parts.push(`window.${stateKey}=${serializeState(state)}`)
+	}
+	if (parts.length === 0) return ''
+	const nonceAttribute = nonce ? ` nonce="${escapeHtml(nonce)}"` : ''
+	return `<script${nonceAttribute}>${parts.join(';')}</script>`
+}
+
+/** Inject rendered fragments into a marker-carrying HTML template. */
+export const injectSsrDocument = (template, { head = '', html = '', state = '', teleports = '' }) =>
+	template
+		.replace(SSR_MARKERS.head, head)
+		.replace(SSR_MARKERS.teleports, teleports)
+		.replace(SSR_MARKERS.html, html)
+		.replace(SSR_MARKERS.state, state)
+
+/**
+ * Guarantee the four SSR markers exist in a template so consumers never learn
+ * marker names. Existing markers are left untouched; missing ones are added:
+ * head before </head>, teleports after <body>, html inside the mount element,
+ * state before </body>.
+ */
+export const ensureSsrMarkers = (template, { mountSelector = '#app' } = {}) => {
+	let html = String(template)
+	if (!html.includes(SSR_MARKERS.head)) {
+		html = html.replace(/<\/head>/i, `${SSR_MARKERS.head}\n</head>`)
+	}
+	if (!html.includes(SSR_MARKERS.teleports)) {
+		html = html.replace(/<body([^>]*)>/i, `<body$1>${SSR_MARKERS.teleports}`)
+	}
+	if (!html.includes(SSR_MARKERS.html)) {
+		const id = mountSelector.startsWith('#') ? mountSelector.slice(1) : mountSelector
+		const mountPattern = new RegExp(`(<div[^>]*id=["']${id}["'][^>]*>)(</div>)`, 'i')
+		html = html.replace(mountPattern, `$1${SSR_MARKERS.html}$2`)
+	}
+	if (!html.includes(SSR_MARKERS.state)) {
+		html = html.replace(/<\/body>/i, `${SSR_MARKERS.state}\n</body>`)
+	}
+	return html
+}
+
+/** Generic accessible error markup used by fallback shells (overridable upstream). */
+export const renderErrorMarkup = (title, message) => `
+<main id="main-content" style="min-height:70vh;display:grid;place-items:center;padding:2rem;text-align:center;font-family:system-ui,sans-serif" tabindex="-1">
+	<div><h1>${escapeHtml(title)}</h1><p>${escapeHtml(message)}</p><p><a href="/">Return home</a></p></div>
+</main>`
+
+/** Sitemap primitives shared by consumers that serve SEO XML from the server. */
+export const renderSitemapUrlSet = (urls) => {
+	const uniqueUrls = [...new Set(urls)]
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${uniqueUrls.map((url) => `\n  <url><loc>${escapeXml(url)}</loc></url>`).join('')}\n</urlset>\n`
+}
+
+export const renderSitemapIndex = (urls) =>
+	`<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls.map((url) => `\n  <sitemap><loc>${escapeXml(url)}</loc></sitemap>`).join('')}\n</sitemapindex>\n`

package/engine/index.d.ts

@@ -0,0 +1,86 @@
+import type { SsrHeadPayload } from '../index'
+
+export declare const SSR_MARKERS: Readonly<{
+	head: string
+	html: string
+	state: string
+	teleports: string
+}>
+export declare const SSR_HTML_SECURITY_HEADERS: Readonly<Record<string, string>>
+
+export declare const escapeHtml: (value: unknown) => string
+export declare const escapeXml: (value: unknown) => string
+export declare const serializeState: (value: unknown) => string
+export declare const renderHeadTags: (
+	payload: SsrHeadPayload | null | undefined,
+	attribute?: string,
+) => string
+export declare const renderStateScript: (
+	parts: { config?: Record<string, unknown> | null; state?: unknown },
+	options?: { configKey?: string; stateKey?: string; nonce?: string },
+) => string
+export declare const injectSsrDocument: (
+	template: string,
+	fragments: { head?: string; html?: string; state?: string; teleports?: string },
+) => string
+export declare const ensureSsrMarkers: (
+	template: string,
+	options?: { mountSelector?: string },
+) => string
+export declare const renderErrorMarkup: (title: string, message: string) => string
+export declare const renderSitemapUrlSet: (urls: string[]) => string
+export declare const renderSitemapIndex: (urls: string[]) => string
+
+export declare const normalizeSsrHost: (host: unknown) => string
+export declare const stripSsrHostPort: (host: unknown) => string
+export declare const normalizeSsrHostPattern: (host: unknown) => string
+export declare const matchesSsrHostPatterns: (
+	hostname: unknown,
+	patterns: ReadonlyArray<string> | undefined,
+) => boolean
+export declare const resolveSsrForwardedHost: (
+	forwardedHost: unknown,
+	host: unknown,
+	trustForwardedHeaders?: boolean,
+) => string
+export declare const resolveSsrForwardedProtocol: (
+	forwardedProtocol: unknown,
+	fallbackProtocol?: string,
+	trustForwardedHeaders?: boolean,
+) => 'http' | 'https'
+export declare const selectSsrCookieHeader: (
+	cookieHeader: unknown,
+	allowlist?: ReadonlyArray<string>,
+	denylist?: ReadonlyArray<string>,
+) => string | undefined
+
+export interface SsrEngineRequest {
+	url?: string
+	host: string
+	protocol?: 'http' | 'https'
+	cookieHeader?: string
+}
+
+export interface SsrEngineResponse {
+	statusCode: number
+	headers: Record<string, string>
+	html: string
+}
+
+export interface SsrEngineOptions {
+	loadTemplate: (requestUrl?: string) => Promise<string> | string
+	loadRenderModule: () => Promise<Record<string, unknown>>
+	renderExport?: string
+	config?: Record<string, unknown>
+	globals?: { configKey?: string; stateKey?: string }
+	headAttribute?: string
+	defaultHead?: string
+	cookieAllowlist?: string[]
+	cookieDenylist?: string[]
+	renderTimeoutMs?: number
+	nonce?: (request: SsrEngineRequest) => string | undefined
+}
+
+export declare const createSsrRequestHandler: (options: SsrEngineOptions) => {
+	handle: (request: SsrEngineRequest) => Promise<SsrEngineResponse>
+}

package/engine/index.js

@@ -0,0 +1,26 @@
+export {
+	SSR_MARKERS,
+	escapeHtml,
+	escapeXml,
+	serializeState,
+	renderHeadTags,
+	renderStateScript,
+	injectSsrDocument,
+	ensureSsrMarkers,
+	renderErrorMarkup,
+	renderSitemapUrlSet,
+	renderSitemapIndex,
+} from './SsrEngineHtml.js'
+export {
+	normalizeSsrHost,
+	stripSsrHostPort,
+	normalizeSsrHostPattern,
+	matchesSsrHostPatterns,
+	resolveSsrForwardedHost,
+	resolveSsrForwardedProtocol,
+	selectSsrCookieHeader,
+} from './SsrEngineHostPolicy.js'
+export {
+	createSsrRequestHandler,
+	SSR_HTML_SECURITY_HEADERS,
+} from './SsrEngine.js'

package/index.d.ts

@@ -0,0 +1,104 @@
+import type { App, Component, InjectionKey, Ref } from 'vue'
+import type { Router, RouteRecordRaw, RouterScrollBehavior } from 'vue-router'
+import type { ApolloClient, ApolloLink, DefaultOptions, InMemoryCacheConfig, NormalizedCacheObject } from '@apollo/client/core'
+
+export interface SsrRequestContext<
+	TConfig extends Record<string, unknown> = Record<string, unknown>,
+	TState extends Record<string, unknown> = Record<string, unknown>,
+> {
+	url: URL
+	host: string
+	/** Allowlist-filtered Cookie header. Server only; undefined in the browser. */
+	cookie?: string
+	config: TConfig
+	state: TState
+	head: Ref<SsrHeadPayload | null>
+	response: { statusCode: number; redirect: string | null }
+	server: boolean
+	/** Present when the definition declares an Apollo integration. */
+	apollo?: ApolloClient<NormalizedCacheObject>
+}
+
+export interface SsrHeadPayload {
+	title?: string
+	description?: string
+	keywords?: string
+	robots?: string
+	ogTitle?: string
+	ogDescription?: string
+	ogImage?: string
+	ogImageAlt?: string
+	ogUrl?: string
+	ogType?: string
+	ogSiteName?: string
+	ogLocale?: string
+	twitterCard?: string
+	twitterTitle?: string
+	twitterDescription?: string
+	twitterImage?: string
+	twitterImageAlt?: string
+	twitterSite?: string
+	twitterCreator?: string
+	canonicalUrl?: string
+	favicon?: string
+	jsonLd?: Array<Record<string, unknown>>
+}
+
+export interface SsrApolloDefinition {
+	endpoint?: string | ((config: Record<string, unknown>) => string)
+	endpoints?: Record<string, string | ((config: Record<string, unknown>) => string)>
+	timeoutMs?: number | ((config: Record<string, unknown>) => number)
+	headers?:
+		| Record<string, string>
+		| ((environment: { server: boolean }) => Record<string, string>)
+	links?:
+		| ApolloLink[]
+		| ((environment: {
+				server: boolean
+				context: SsrRequestContext
+		  }) => ApolloLink[])
+	cacheConfig?: InMemoryCacheConfig
+	ssrForceFetchDelay?: number
+	defaultOptions?: DefaultOptions
+	install?: (
+		app: App,
+		clients: Record<string, ApolloClient<NormalizedCacheObject>>,
+		context: SsrRequestContext,
+	) => void
+}
+
+export interface SsrSetupEnvironment {
+	app: App
+	router: Router | null
+	context: SsrRequestContext
+	apollo: ApolloClient<NormalizedCacheObject> | null
+	apolloClients: Record<string, ApolloClient<NormalizedCacheObject>> | null
+	server: boolean
+}
+
+export interface SsrAppDefinition {
+	root: Component
+	routes?: RouteRecordRaw[]
+	router?: (environment: {
+		server: boolean
+		context: SsrRequestContext
+	}) => Router | Promise<Router>
+	scrollBehavior?: RouterScrollBehavior
+	apollo?: SsrApolloDefinition
+	config?: Record<string, unknown> | (() => Record<string, unknown>)
+	head?: SsrHeadPayload
+	setup?: (environment: SsrSetupEnvironment) => void | Promise<void>
+	hydration?: {
+		configKey?: string
+		stateKey?: string
+		headAttribute?: string
+		mountSelector?: string
+	}
+}
+
+export declare const SSR_CONTEXT_KEY: InjectionKey<SsrRequestContext>
+export declare const useSsrContext: <
+	TConfig extends Record<string, unknown> = Record<string, unknown>,
+	TState extends Record<string, unknown> = Record<string, unknown>,
+>() => SsrRequestContext<TConfig, TState>
+export declare const defineSsrApp: (definition: SsrAppDefinition) => SsrAppDefinition

package/index.js

@@ -0,0 +1,40 @@
+// vue-ssr-lite — public application-definition entry (isomorphic, tiny).
+//
+// A consumer's entire SSR integration is one application definition created
+// with defineSsrApp. The same definition drives the generated server entry
+// (render) and the generated client entry (hydration), so server and browser
+// can never drift.
+
+export { SSR_CONTEXT_KEY, useSsrContext } from './runtime/SsrRuntimeContext.js'
+
+/**
+ * Declare an SSR application.
+ *
+ * definition:
+ * - root (required): the root Vue component of the public application.
+ * - routes: optional route records; when present the package creates a
+ *   router (memory history on the server, web history in the browser).
+ * - router: optional async factory ({ server, context }) => Router for apps
+ *   that build their router dynamically (advanced alternative to routes).
+ * - scrollBehavior: optional router scroll behavior (used with routes).
+ * - apollo: optional Apollo integration — endpoint or endpoints (values may
+ *   be functions of the public config), timeoutMs, headers, links,
+ *   cacheConfig, ssrForceFetchDelay, defaultOptions, and an optional
+ *   install(app, clients, context) hook for library-specific provides.
+ * - config: optional serializable public configuration (object or factory).
+ *   Serialized for the browser only when non-empty.
+ * - head: optional default head payload used when no page sets one.
+ * - setup: optional ({ app, router, context, apollo, apolloClients, server })
+ *   hook for plugin installation and application provides.
+ * - hydration: optional overrides for global names, head attribute, and
+ *   mount selector (compatibility tier; normal consumers never set these).
+ */
+export const defineSsrApp = (definition) => {
+	if (!definition || typeof definition !== 'object') {
+		throw new Error('defineSsrApp requires a definition object.')
+	}
+	if (!definition.root) {
+		throw new Error('defineSsrApp requires a root component.')
+	}
+	return definition
+}