orga-build 0.9.0 → 0.10.0

package/lib/config.d.ts

@@ -9,15 +9,13 @@ export function loadConfig(...files: string[]): Promise<{
 export type Config = {
     outDir: string;
     root: string;
-    preBuild: string[];
-    postBuild: string[];
     /**
      * - Array of Vite plugins
      */
     vitePlugins: import("vite").PluginOption[];
     containerClass: string[] | string;
     /**
-     * - Global stylesheet URLs injected in dev SSR and imported by client entry
+     * - Global stylesheet URLs linked from the HTML shell
      */
     styles?: string[];
     /**
@@ -28,5 +26,9 @@ export type Config = {
      * - Glob patterns for files to exclude from content scanning
      */
     exclude?: string[];
+    /**
+     * - Absolute URL the site is served from, e.g. `https://example.com`
+     */
+    site?: string | undefined;
 };
 //# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["config.js"],"names":[],"mappings":"AA6BA;;;GAGG;AACH,qCAHW,MAAM,EAAE,GACN,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAiD5D;;YA3Ea,MAAM;UACN,MAAM;cACN,MAAM,EAAE;eACR,MAAM,EAAE;;;;iBACR,OAAO,MAAM,EAAE,YAAY,EAAE;oBAC7B,MAAM,EAAE,GAAC,MAAM;;;;aACf,MAAM,EAAE;;;;oBACR,OAAO,SAAS,EAAE,aAAa;;;;cAC/B,MAAM,EAAE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["config.js"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,qCAHW,MAAM,EAAE,GACN,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CA4C5D;;YAnEa,MAAM;UACN,MAAM;;;;iBACN,OAAO,MAAM,EAAE,YAAY,EAAE;oBAC7B,MAAM,EAAE,GAAC,MAAM;;;;aACf,MAAM,EAAE;;;;oBACR,OAAO,SAAS,EAAE,aAAa;;;;cAC/B,MAAM,EAAE;;;;WACR,MAAM,GAAG,SAAS"}

package/lib/config.js

@@ -5,21 +5,18 @@ import path from 'node:path'
  * @typedef {Object} Config
  * @property {string} outDir
  * @property {string} root
- * @property {string[]} preBuild
- * @property {string[]} postBuild
  * @property {import('vite').PluginOption[]} vitePlugins - Array of Vite plugins
  * @property {string[]|string} containerClass
- * @property {string[]} [styles] - Global stylesheet URLs injected in dev SSR and imported by client entry
+ * @property {string[]} [styles] - Global stylesheet URLs linked from the HTML shell
  * @property {import('unified').PluggableList} [rehypePlugins] - Extra rehype plugins appended to orga-build defaults
  * @property {string[]} [exclude] - Glob patterns for files to exclude from content scanning
+ * @property {string | undefined} [site] - Absolute URL the site is served from, e.g. `https://example.com`
  */
 
 /** @type {Config} */
 const defaultConfig = {
 	outDir: '.out',
 	root: '.',
-	preBuild: [],
-	postBuild: [],
 	vitePlugins: [],
 	containerClass: [],
 	styles: [],
@@ -53,17 +50,12 @@ export async function loadConfig(...files) {
 			continue
 		}
 
-		try {
-			const module = await import(filePath)
-			// Support both default export (recommended) and named exports
-			const config = module.default || module
-			result = { ...defaultConfig, ...config }
-			configPath = filePath
-			break
-		} catch (err) {
-			// Config file exists but has errors
-			console.error(`Error loading config from ${file}:`, err)
-		}
+		// A broken config file fails the command rather than falling back to defaults.
+		const module = await import(filePath)
+		// Support both default export (recommended) and named exports
+		result = { ...defaultConfig, ...(module.default || module) }
+		configPath = filePath
+		break
 	}
 
 	result.root = resolveConfigPath(result.root)

package/lib/content.d.ts

@@ -8,6 +8,12 @@ declare module 'orga-build:content' {
 		data: Record<string, unknown>
 	}
 
+	/**
+	 * The configured `site` (absolute URL, no trailing slash), or `undefined`.
+	 * A page's absolute URL is `site + page.slug`.
+	 */
+	export const site: string | undefined
+
 	/**
 	 * Get all content entries matching a path pattern
 	 * @param path - Optional path prefix to filter by (e.g., 'writing', 'content/writing/2025')

package/lib/dev-ssr.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Serves pages and endpoints in dev, rendering each request on the server
+ * (matching Astro/SvelteKit behaviour):
+ * - Endpoint routes are answered from their `GET`/`HEAD` handlers
+ * - Pages are SSR-rendered through the `ssr` environment's module runner, so
+ *   edits are picked up without restarting
+ * - Unknown routes fall through to Vite, which answers 404 like the build
+ * - Only GET/HEAD requests that accept HTML are rendered; assets pass through
+ *
+ * @param {string | undefined} site - Absolute site URL, passed to endpoints
+ * @returns {import('vite').Plugin}
+ */
+export function devSsrPlugin(site: string | undefined): import("vite").Plugin;
+//# sourceMappingURL=dev-ssr.d.ts.map

package/lib/dev-ssr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-ssr.d.ts","sourceRoot":"","sources":["dev-ssr.js"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH,mCAHW,MAAM,GAAG,SAAS,GAChB,OAAO,MAAM,EAAE,MAAM,CAqHjC"}

package/lib/dev-ssr.js

@@ -0,0 +1,137 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isCSSRequest, isRunnableDevEnvironment, normalizePath } from 'vite'
+import { resolveEndpointResponse } from './endpoint.js'
+import { readIndexHtml, renderPageHtml } from './html.js'
+import { islandRuntimeId } from './vite.js'
+
+const ssrEntry = fileURLToPath(new URL('./ssr.jsx', import.meta.url))
+
+/**
+ * Serves pages and endpoints in dev, rendering each request on the server
+ * (matching Astro/SvelteKit behaviour):
+ * - Endpoint routes are answered from their `GET`/`HEAD` handlers
+ * - Pages are SSR-rendered through the `ssr` environment's module runner, so
+ *   edits are picked up without restarting
+ * - Unknown routes fall through to Vite, which answers 404 like the build
+ * - Only GET/HEAD requests that accept HTML are rendered; assets pass through
+ *
+ * @param {string | undefined} site - Absolute site URL, passed to endpoints
+ * @returns {import('vite').Plugin}
+ */
+export function devSsrPlugin(site) {
+	return {
+		name: 'orga-build:dev-ssr',
+		// Run before other plugins' middlewares (e.g. Cloudflare) so HTML
+		// navigation requests are not answered with a 404 first.
+		enforce: 'pre',
+
+		configureServer(server) {
+			const ssr = server.environments.ssr
+			if (!isRunnableDevEnvironment(ssr)) {
+				server.config.logger.warn(
+					'[orga-build] the "ssr" environment is not runnable in this process; dev SSR is disabled'
+				)
+				return
+			}
+
+			// The browser imports islands straight from source, served by Vite
+			// under its `base`. The shell's own URLs are rebased by Vite in
+			// `transformIndexHtml`; these are injected afterwards.
+			const { root, base } = server.config
+			/** @param {string} src */
+			const islandUrl = (src) =>
+				// Outside the root (`..`, or another drive on Windows): Vite's /@fs/ form.
+				src.startsWith('..') || path.isAbsolute(src)
+					? `${base}@fs/${normalizePath(path.resolve(root, src)).replace(/^\//, '')}`
+					: base + src
+			const islandScript = base + islandRuntimeId.slice(1)
+			// CSS imported by server-rendered code never reaches the browser's
+			// module graph: link each file, which Vite serves as plain CSS.
+			const styles = () =>
+				[...ssr.moduleGraph.idToModuleMap.keys()]
+					.filter(
+						(id) => isCSSRequest(id) && path.isAbsolute(id) && !id.includes('?')
+					)
+					.map((id) => islandUrl(normalizePath(path.relative(root, id))))
+
+			server.middlewares.use(async (req, res, next) => {
+				if (req.method !== 'GET' && req.method !== 'HEAD') {
+					return next()
+				}
+
+				// This runs before Vite's own middlewares, so `base` is still in the URL.
+				const url = req.url || '/'
+				const requestPath = url.split('?')[0]
+				if (!requestPath.startsWith(base)) return next()
+				// Directory-style URLs (`/docs/`) are the same page as `/docs`.
+				const pathname = requestPath
+					.slice(base.length - 1)
+					.replace(/(.)\/+$/, '$1')
+
+				try {
+					// The runner follows the module graph, so stale modules are never served.
+					const { render, pages, endpoints } = await ssr.runner.import(ssrEntry)
+
+					// Endpoint routes are handled first and bypass HTML rendering.
+					const endpointModule = endpoints?.[pathname]
+					if (endpointModule) {
+						const ctx = {
+							url: new URL(url, `http://${req.headers.host || 'localhost'}`),
+							params: {},
+							mode: /** @type {'dev'} */ ('dev'),
+							route: { route: pathname },
+							site
+						}
+						const response = await resolveEndpointResponse(
+							endpointModule,
+							ctx,
+							req.method
+						)
+						res.statusCode = response.status
+						response.headers.forEach((headerValue, headerName) => {
+							res.setHeader(headerName, headerValue)
+						})
+						if (req.method === 'HEAD') {
+							res.end()
+							return
+						}
+						res.end(Buffer.from(await response.arrayBuffer()))
+						return
+					}
+
+					// Only handle browser-like navigation requests.
+					// Don't match generic */* accepts to avoid hijacking API requests.
+					const accept = req.headers.accept || ''
+					if (!accept.includes('text/html')) {
+						return next()
+					}
+
+					// Don't intercept asset requests (files with extensions)
+					if (pathname !== '/' && /\.\w+$/.test(pathname)) {
+						return next()
+					}
+
+					if (!pages[pathname]) return next()
+
+					const template = await server.transformIndexHtml(
+						url,
+						await readIndexHtml(server.config.root)
+					)
+					const html = renderPageHtml(template, {
+						content: render(pathname, islandUrl),
+						page: pages[pathname],
+						islandScript,
+						styles: styles()
+					})
+
+					res.statusCode = 200
+					res.setHeader('Content-Type', 'text/html')
+					res.end(html)
+				} catch (e) {
+					next(e)
+				}
+			})
+		}
+	}
+}

package/lib/endpoint.d.ts

@@ -4,6 +4,7 @@
  * @property {Record<string, string>} params
  * @property {'dev' | 'build'} mode
  * @property {{ route: string }} route
+ * @property {string | undefined} site - The configured `site`, without a trailing slash
  */
 /**
  * @param {Record<string, any>} endpointModule
@@ -19,5 +20,9 @@ export type EndpointContext = {
     route: {
         route: string;
     };
+    /**
+     * - The configured `site`, without a trailing slash
+     */
+    site: string | undefined;
 };
 //# sourceMappingURL=endpoint.d.ts.map

package/lib/endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["endpoint.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,wDALW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OACnB,eAAe,WACf,MAAM,GACJ,OAAO,CAAC,QAAQ,CAAC,CAoC7B;;SA9Ca,GAAG;YACH,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;UACtB,KAAK,GAAG,OAAO;WACf;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE"}
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["endpoint.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,wDALW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OACnB,eAAe,WACf,MAAM,GACJ,OAAO,CAAC,QAAQ,CAAC,CAoC7B;;SA/Ca,GAAG;YACH,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;UACtB,KAAK,GAAG,OAAO;WACf;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;;;;UACjB,MAAM,GAAG,SAAS"}

package/lib/endpoint.js

@@ -4,6 +4,7 @@
  * @property {Record<string, string>} params
  * @property {'dev' | 'build'} mode
  * @property {{ route: string }} route
+ * @property {string | undefined} site - The configured `site`, without a trailing slash
  */
 
 /**

package/lib/files.d.ts

@@ -3,10 +3,12 @@
  * @param {object} [options]
  * @param {string} [options.outDir] - Output directory to exclude from file discovery
  * @param {string[]} [options.exclude] - Additional glob patterns to exclude from file discovery
+ * @param {boolean} [options.drafts] - Include pages marked `#+draft:` (for previews in dev)
  */
-export function setup(dir: string, { outDir, exclude }?: {
+export function setup(dir: string, { outDir, exclude, drafts }?: {
     outDir?: string | undefined;
     exclude?: string[] | undefined;
+    drafts?: boolean | undefined;
 }): {
     pages: (() => Promise<Record<string, Page>>) & {
         invalidate: () => void;
@@ -33,11 +35,14 @@ export function setup(dir: string, { outDir, exclude }?: {
  */
 export function getSlugFromContentFilePath(contentFilePath: string): string;
 export type Page = {
+    /**
+     *   Path to the page data file
+     */
     dataPath: string;
     /**
-     * Path to the page data file
+     *   Metadata: an org page's keywords, or a TSX/JSX page's literal named exports
      */
-    title?: string;
+    data: Record<string, unknown>;
 };
 export type EndpointRoute = {
     route: string;

package/lib/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["files.js"],"names":[],"mappings":"AAoFA;;;;;GAKG;AACH,2BALW,MAAM,wBAEd;IAAyB,MAAM;IACJ,OAAO;CACpC;;0BA6LqD,IAAI;;iBApB7C,MAAM;;0BAoBmC,IAAI;;sBAd7C,MAAM;;0BAcmC,IAAI;;;0BAAJ,IAAI;;;0BAAJ,IAAI;;;EATzD;AA8BD;;;GAGG;AACH,4DAFW,MAAM,UAoBhB;;cA1Ta,MAAM;;;;YACN,MAAM;;;WAMN,MAAM;cACN,MAAM;;;QAKN,MAAM;UACN,MAAM;UACN,MAAM;cACN,MAAM;SACN,KAAK,GAAG,KAAK,GAAG,KAAK;UACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["files.js"],"names":[],"mappings":"AAsFA;;;;;;GAMG;AACH,2BANW,MAAM,gCAEd;IAAyB,MAAM;IACJ,OAAO;IACR,MAAM;CAClC;;0BA8QqD,IAAI;;iBAlH7C,MAAM;;0BAkHmC,IAAI;;sBA5G7C,MAAM;;0BA4GmC,IAAI;;;0BAAJ,IAAI;;;0BAAJ,IAAI;;;EAvGzD;AA4HD;;;GAGG;AACH,4DAFW,MAAM,UAoBhB;;;;;cA7Ya,MAAM;;;;UAEN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;WAMvB,MAAM;cACN,MAAM;;;QAKN,MAAM;UACN,MAAM;UACN,MAAM;cACN,MAAM;SACN,KAAK,GAAG,KAAK,GAAG,KAAK;UACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}

package/lib/files.js

@@ -2,12 +2,14 @@ import { readFile } from 'node:fs/promises'
 import path from 'node:path'
 import { globby } from 'globby'
 import { getSettings } from 'orga'
+import { parseSync } from 'vite'
 
 /**
  * @typedef {Object} Page
  * @property {string} dataPath
- * @property {string} [title]
  *   Path to the page data file
+ * @property {Record<string, unknown>} data
+ *   Metadata: an org page's keywords, or a TSX/JSX page's literal named exports
  */
 
 /**
@@ -87,8 +89,9 @@ function getContentId(slug) {
  * @param {object} [options]
  * @param {string} [options.outDir] - Output directory to exclude from file discovery
  * @param {string[]} [options.exclude] - Additional glob patterns to exclude from file discovery
+ * @param {boolean} [options.drafts] - Include pages marked `#+draft:` (for previews in dev)
  */
-export function setup(dir, { outDir, exclude = [] } = {}) {
+export function setup(dir, { outDir, exclude = [], drafts = false } = {}) {
 	const outDirRelative = outDir ? path.relative(dir, outDir) : null
 	// Only exclude outDir if it's inside the root (not an external path like ../out)
 	const outDirExclude =
@@ -125,7 +128,10 @@ export function setup(dir, { outDir, exclude = [] } = {}) {
 
 			if (pageSlug) {
 				assertUniqueRoute(routeOwners, pageSlug, 'page', absolutePath)
-				pages[pageSlug] = { dataPath: absolutePath }
+				const data = await readMetadata(absolutePath)
+				if (drafts || !isDraft(data)) {
+					pages[pageSlug] = { dataPath: absolutePath, data }
+				}
 			}
 
 			if (endpointRoute) {
@@ -207,29 +213,13 @@ export function setup(dir, { outDir, exclude = [] } = {}) {
 			// Derive id from the slug (last segment or 'index')
 			const id = getContentId(slug)
 
-			/** @type {Record<string, unknown>} */
-			let data = {}
-
-			// Extract metadata from .org files
-			if (ext === 'org') {
-				try {
-					const content = await readFile(filePath, 'utf-8')
-					data = getSettings(content)
-				} catch (/** @type {any} */ error) {
-					console.warn(
-						`Failed to read metadata from ${filePath}:`,
-						error?.message || error
-					)
-				}
-			}
-
 			entries.push({
 				id,
 				slug,
 				path: derivedPath,
 				filePath,
 				ext,
-				data
+				data: pageData.data
 			})
 		}
 
@@ -269,6 +259,100 @@ export function setup(dir, { outDir, exclude = [] } = {}) {
 	}
 }
 
+/**
+ * Read a page's metadata: an org file's keywords, or the named exports of a
+ * TSX/JSX page whose values are literals (`export const title = 'Hi'`).
+ * @param {string} filePath
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function readMetadata(filePath) {
+	try {
+		const text = await readFile(filePath, 'utf-8')
+		return filePath.endsWith('.org')
+			? getSettings(text)
+			: readLiteralExports(filePath, text)
+	} catch (/** @type {any} */ error) {
+		console.warn(
+			`Failed to read metadata from ${filePath}:`,
+			error?.message || error
+		)
+		return {}
+	}
+}
+
+/**
+ * Named exports whose values can be read without running the module. Others
+ * are skipped; Vite reports syntax errors when it builds the page.
+ * @param {string} filePath
+ * @param {string} text
+ */
+function readLiteralExports(filePath, text) {
+	const { program, errors } = parseSync(filePath, text)
+	/** @type {Record<string, unknown>} */
+	const data = {}
+	if (errors.length) return data
+	for (const node of program.body) {
+		if (
+			node.type !== 'ExportNamedDeclaration' ||
+			node.declaration?.type !== 'VariableDeclaration'
+		) {
+			continue
+		}
+		for (const { id, init } of node.declaration.declarations) {
+			if (id.type !== 'Identifier' || !init) continue
+			const value = literalValue(init)
+			if (value !== notLiteral) data[id.name] = value
+		}
+	}
+	return data
+}
+
+const notLiteral = Symbol('notLiteral')
+
+/**
+ * The value of a literal expression: a string, number (signed too), boolean
+ * or `null`, a template without placeholders, or an array of those.
+ * @param {any} node
+ * @returns {unknown}
+ */
+function literalValue(node) {
+	switch (node.type) {
+		case 'Literal':
+			// Regexes and bigints have no JSON form.
+			return node.regex || node.bigint ? notLiteral : node.value
+		case 'TemplateLiteral':
+			return node.expressions.length ? notLiteral : node.quasis[0].value.cooked
+		case 'TSAsExpression':
+		case 'TSSatisfiesExpression':
+			return literalValue(node.expression)
+		case 'UnaryExpression': {
+			const value = literalValue(node.argument)
+			if (typeof value !== 'number') return notLiteral
+			return node.operator === '-'
+				? -value
+				: node.operator === '+'
+					? value
+					: notLiteral
+		}
+		case 'ArrayExpression': {
+			const values = node.elements.map((/** @type {any} */ element) =>
+				element ? literalValue(element) : notLiteral
+			)
+			return values.includes(notLiteral) ? notLiteral : values
+		}
+		default:
+			return notLiteral
+	}
+}
+
+/**
+ * Whether a page is marked `#+draft: t` (or `true`, `yes`).
+ * @param {Record<string, unknown>} data
+ */
+function isDraft(data) {
+	return /^(t|true|yes)$/i.test(String(data.draft ?? '').trim())
+}
+
 /**
  * Creates a cached version of an async function that will only execute once
  * and return the cached result on subsequent calls. The returned function

package/lib/fs.d.ts

@@ -9,11 +9,6 @@ export function resolvePath(rootPath: string): string;
  * @returns {Promise<boolean>}
  */
 export function exists(path: string): Promise<boolean>;
-/**
- * @param {string} dir
- * @returns {Promise<void>}
- */
-export function emptyDir(dir: string): Promise<void>;
 /**
  * @param {string} path
  */

package/lib/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["fs.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,sCAHW,MAAM,GACJ,MAAM,CAclB;AAED;;;GAGG;AACH,6BAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAS5B;AAED;;;GAGG;AACH,8BAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAczB;AAED;;GAEG;AACH,gCAFW,MAAM,iBAUhB;AAED;;;GAGG;AACH,0BAHW,MAAM,QACN,MAAM,iBAKhB"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["fs.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,sCAHW,MAAM,GACJ,MAAM,CAclB;AAED;;;GAGG;AACH,6BAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAS5B;AAED;;GAEG;AACH,gCAFW,MAAM,iBAUhB;AAED;;;GAGG;AACH,0BAHW,MAAM,QACN,MAAM,iBAKhB"}

package/lib/fs.js

@@ -33,24 +33,6 @@ export async function exists(path) {
 	}
 }
 
-/**
- * @param {string} dir
- * @returns {Promise<void>}
- */
-export async function emptyDir(dir) {
-	/** @type {string[]} */
-	let items = []
-	try {
-		items = await fs.readdir(dir)
-	} catch {
-		await fs.mkdir(dir, { recursive: true })
-	}
-
-	await Promise.all(
-		items.map((item) => fs.rm(`${dir}/${item}`, { recursive: true }))
-	)
-}
-
 /**
  * @param {string} path
  */

package/lib/html.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Read the HTML shell: the user's `index.html` in the Vite root, or the
+ * default one shipped with orga-build.
+ *
+ * @param {string} root - Vite root
+ */
+export function readIndexHtml(root: string): Promise<string>;
+/**
+ * Makes `<root>/index.html` always loadable, falling back to the default shell,
+ * so Vite can use it as the client build entry. Vite then bundles its scripts
+ * and stylesheets and injects the hashed asset tags itself.
+ *
+ * Global styles are added as `<link>` tags, which Vite serves (with HMR) in
+ * dev and bundles in build.
+ *
+ * @param {string[]} [styles]
+ * @returns {import('vite').Plugin}
+ */
+export function htmlShellPlugin(styles?: string[]): import("vite").Plugin;
+/**
+ * Fill a processed HTML shell with a server-rendered page. The island runtime
+ * is only linked when the page has an island, so other pages ship no script.
+ *
+ * @param {string} template - HTML shell, already transformed by Vite
+ * @param {Object} options
+ * @param {string | undefined} options.content - Rendered page markup
+ * @param {Record<string, unknown> | undefined} options.page - Page module exports, used for `%orga.*%` placeholders
+ * @param {string | undefined} [options.islandScript] - URL of the island runtime
+ * @param {string[]} [options.styles] - URLs of stylesheets imported by server-rendered code
+ */
+export function renderPageHtml(template: string, { content, page, islandScript, styles }: {
+    content: string | undefined;
+    page: Record<string, unknown> | undefined;
+    islandScript?: string | undefined;
+    styles?: string[] | undefined;
+}): string;
+//# sourceMappingURL=html.d.ts.map

package/lib/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["html.js"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,oCAFW,MAAM,mBAMhB;AAED;;;;;;;;;;GAUG;AACH,yCAHW,MAAM,EAAE,GACN,OAAO,MAAM,EAAE,MAAM,CAqCjC;AAED;;;;;;;;;;GAUG;AACH,yCAPW,MAAM,2CAEd;IAAoC,OAAO,EAAnC,MAAM,GAAG,SAAS;IAC2B,IAAI,EAAjD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IACN,YAAY,GAAzC,MAAM,GAAG,SAAS;IACC,MAAM;CACnC,UAsBA"}

package/lib/html.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { exists } from './fs.js'
+import { escapeHtml } from './util.js'
+
+const defaultIndexHtml = fileURLToPath(new URL('./index.html', import.meta.url))
+
+/**
+ * Read the HTML shell: the user's `index.html` in the Vite root, or the
+ * default one shipped with orga-build.
+ *
+ * @param {string} root - Vite root
+ */
+export async function readIndexHtml(root) {
+	const userIndexHtml = path.join(root, 'index.html')
+	const file = (await exists(userIndexHtml)) ? userIndexHtml : defaultIndexHtml
+	return fs.readFile(file, 'utf-8')
+}
+
+/**
+ * Makes `<root>/index.html` always loadable, falling back to the default shell,
+ * so Vite can use it as the client build entry. Vite then bundles its scripts
+ * and stylesheets and injects the hashed asset tags itself.
+ *
+ * Global styles are added as `<link>` tags, which Vite serves (with HMR) in
+ * dev and bundles in build.
+ *
+ * @param {string[]} [styles]
+ * @returns {import('vite').Plugin}
+ */
+export function htmlShellPlugin(styles = []) {
+	/** @type {string} */
+	let root
+	/** @type {string} */
+	let indexHtmlPath
+
+	return {
+		name: 'orga-build:html-shell',
+		enforce: 'pre',
+		configResolved(config) {
+			root = config.root
+			indexHtmlPath = path.join(root, 'index.html')
+		},
+		resolveId(id, importer) {
+			// Build entries arrive relative to the root, without an importer.
+			if (!importer && path.resolve(root, id) === indexHtmlPath) {
+				return indexHtmlPath
+			}
+		},
+		async load(id) {
+			if (id === indexHtmlPath) {
+				return readIndexHtml(root)
+			}
+		},
+		transformIndexHtml: {
+			order: 'pre',
+			handler() {
+				return [...new Set(styles)].map((href) => ({
+					tag: 'link',
+					attrs: { rel: 'stylesheet', href },
+					injectTo: 'head'
+				}))
+			}
+		}
+	}
+}
+
+/**
+ * Fill a processed HTML shell with a server-rendered page. The island runtime
+ * is only linked when the page has an island, so other pages ship no script.
+ *
+ * @param {string} template - HTML shell, already transformed by Vite
+ * @param {Object} options
+ * @param {string | undefined} options.content - Rendered page markup
+ * @param {Record<string, unknown> | undefined} options.page - Page module exports, used for `%orga.*%` placeholders
+ * @param {string | undefined} [options.islandScript] - URL of the island runtime
+ * @param {string[]} [options.styles] - URLs of stylesheets imported by server-rendered code
+ */
+export function renderPageHtml(
+	template,
+	{ content, page, islandScript, styles = [] }
+) {
+	let html = template
+	// Unknown routes render nothing (`undefined`); a page may render ''.
+	if (content !== undefined) {
+		html = html.replace(
+			'<div id="root"></div>',
+			`<div id="root">${content}</div>`
+		)
+		const head = styles.map((href) => `<link rel="stylesheet" href="${href}">`)
+		if (islandScript && content.includes('<orga-island')) {
+			head.push(`<script type="module" src="${islandScript}"></script>`)
+		}
+		if (head.length) html = html.replace(/<\/head>/i, `${head.join('')}$&`)
+	}
+	// Unknown routes have no page: their placeholders resolve to empty strings.
+	return html.replace(/%orga\.(\w+)%/g, (_, key) =>
+		escapeHtml(String(page?.[key] ?? ''))
+	)
+}