orga-build 0.8.0 → 0.10.0

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] ?? ''))
+	)
+}

package/lib/index.html

@@ -7,6 +7,5 @@
 </head>
 <body>
 <div id="root"></div>
-<script type="module" src="/@orga-build/main.js"></script>
 </body>
 </html>

package/lib/island-client.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param {Element} el
+ */
+declare function hydrate(el: Element): Promise<void>;
+//# sourceMappingURL=island-client.d.ts.map

package/lib/island-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"island-client.d.ts","sourceRoot":"","sources":["island-client.js"],"names":[],"mappings":"AAqBA;;GAEG;AACH,6BAFW,OAAO,iBAkBjB"}

package/lib/island-client.js

@@ -0,0 +1,41 @@
+/**
+ * Hydrates every `<orga-island>` on the page: imports the module the server
+ * referenced and mounts React on the server-rendered markup. React itself is
+ * only loaded once an island hydrates, so `client="visible"` islands below the
+ * fold cost nothing until scrolled into view.
+ */
+for (const el of Array.from(document.querySelectorAll('orga-island'))) {
+	// The island has `display: contents` and no box of its own, so visibility
+	// is watched on its children; a text-only island has none and hydrates now.
+	if (el.getAttribute('client') !== 'visible' || !el.children.length) {
+		hydrate(el)
+		continue
+	}
+	const observer = new IntersectionObserver((entries) => {
+		if (!entries.some((entry) => entry.isIntersecting)) return
+		observer.disconnect()
+		hydrate(el)
+	})
+	for (const child of Array.from(el.children)) observer.observe(child)
+}
+
+/**
+ * @param {Element} el
+ */
+async function hydrate(el) {
+	const [{ createElement }, { hydrateRoot }, mod] = await Promise.all([
+		import('react'),
+		import('react-dom/client'),
+		import(
+			/* @vite-ignore */
+			new URL(/** @type {string} */ (el.getAttribute('src')), document.baseURI)
+				.href
+		)
+	])
+	const Component = mod[/** @type {string} */ (el.getAttribute('export'))]
+	const props = JSON.parse(el.getAttribute('props') || '{}')
+	hydrateRoot(el, createElement(Component, props), {
+		// Same prefix the server rendered this island with, so `useId` matches.
+		identifierPrefix: el.getAttribute('prefix') || ''
+	})
+}

package/lib/island.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Islands: a module that starts with React's `'use client'` directive runs in
+ * the browser. In the `ssr` environment each component it exports (named in
+ * PascalCase, or the default export) is wrapped so it renders inside an
+ * `<orga-island>` element (see `island.jsx`); hooks and other exports pass
+ * through. In the browser the client runtime imports the real module and
+ * hydrates it there. Pages without islands ship no JavaScript.
+ *
+ * Islands are discovered while the `ssr` environment is transformed, so the
+ * `client` environment must be built after it: its `buildStart` emits a chunk
+ * per island plus the runtime, and the client manifest maps them to hashed
+ * files for prerendering.
+ *
+ * @returns {import('vite').Plugin}
+ */
+export function islandPlugin(): import("vite").Plugin;
+export const clientRuntime: string;
+//# sourceMappingURL=island.d.ts.map

package/lib/island.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"island.d.ts","sourceRoot":"","sources":["island.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH,gCAFa,OAAO,MAAM,EAAE,MAAM,CAoFjC;AAvGD,mCAEC"}

package/lib/island.js

@@ -0,0 +1,146 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { normalizePath } from 'vite'
+
+const serverEntry = fileURLToPath(new URL('./island.jsx', import.meta.url))
+export const clientRuntime = fileURLToPath(
+	new URL('./island-client.js', import.meta.url)
+)
+const implQuery = '?orga-island'
+const directive = /^(?:\s|\/\/.*|\/\*[\s\S]*?\*\/)*(['"])use client\1/
+
+/**
+ * Islands: a module that starts with React's `'use client'` directive runs in
+ * the browser. In the `ssr` environment each component it exports (named in
+ * PascalCase, or the default export) is wrapped so it renders inside an
+ * `<orga-island>` element (see `island.jsx`); hooks and other exports pass
+ * through. In the browser the client runtime imports the real module and
+ * hydrates it there. Pages without islands ship no JavaScript.
+ *
+ * Islands are discovered while the `ssr` environment is transformed, so the
+ * `client` environment must be built after it: its `buildStart` emits a chunk
+ * per island plus the runtime, and the client manifest maps them to hashed
+ * files for prerendering.
+ *
+ * @returns {import('vite').Plugin}
+ */
+export function islandPlugin() {
+	/** @type {Set<string>} */
+	const islands = new Set()
+	/** @type {string} */
+	let root
+	let ssrBuilt = false
+	let clientBuiltAfterSsr = false
+	/** @type {Set<string>} */
+	const ssrAssets = new Set()
+
+	return {
+		name: 'orga-build:islands',
+
+		api: {
+			/** Whether the client build predates island discovery and lacks them. */
+			get clientIsStale() {
+				return islands.size > 0 && !clientBuiltAfterSsr
+			},
+			/** Files (relative to the SSR outDir) the SSR build emitted as assets. */
+			ssrAssets
+		},
+
+		configResolved(config) {
+			root = config.root
+		},
+
+		transform: {
+			filter: { code: 'use client' },
+			handler(code, id) {
+				if (this.environment.name !== 'ssr' || id.includes(implQuery)) return
+				if (!directive.test(code)) return
+				const src = normalizePath(path.relative(root, id))
+				const ast = this.parse(code)
+				if (ast.body.some((node) => node.type === 'ExportAllDeclaration')) {
+					this.error(`'use client' modules can't use \`export *\``)
+				}
+				const names = exportNames(ast)
+				if (names.some(isComponentName)) islands.add(id)
+				const exports = names.map((name) => {
+					const binding =
+						name === 'default' ? 'export default' : `export const ${name} =`
+					const key = JSON.stringify(name)
+					return isComponentName(name)
+						? `${binding} island(impl[${key}], ${JSON.stringify(src)}, ${key})`
+						: `${binding} impl[${key}]`
+				})
+				return [
+					`import * as impl from ${JSON.stringify(id + implQuery)}`,
+					`import { island } from ${JSON.stringify(serverEntry)}`,
+					...exports
+				].join('\n')
+			}
+		},
+
+		buildEnd() {
+			if (this.environment.name === 'ssr') ssrBuilt = true
+		},
+
+		// Pages live only in the SSR graph, so their images and CSS are emitted
+		// there (see `emitAssets`); remember which files, for prerendering to
+		// copy into the site. Source maps stay behind. `writeBundle` sees the
+		// final bundle, after Vite's CSS plugin has added its file.
+		writeBundle(_options, bundle) {
+			if (this.environment.name !== 'ssr') return
+			ssrAssets.clear()
+			for (const output of Object.values(bundle)) {
+				if (output.type === 'asset' && !output.fileName.endsWith('.map')) {
+					ssrAssets.add(output.fileName)
+				}
+			}
+		},
+
+		buildStart() {
+			if (this.environment.name !== 'client') return
+			clientBuiltAfterSsr = ssrBuilt
+			if (this.environment.mode !== 'build' || !islands.size) return
+			for (const id of [...islands, clientRuntime]) {
+				// Vite drops entry exports in app builds; the runtime needs them.
+				this.emitFile({ type: 'chunk', id, preserveSignature: 'strict' })
+			}
+		}
+	}
+}
+
+/**
+ * Components are PascalCase by convention, as React Fast Refresh assumes.
+ *
+ * @param {string} name
+ */
+function isComponentName(name) {
+	return name === 'default' || /^[A-Z]/.test(name)
+}
+
+/**
+ * Names of a module's exports. Destructured exports are skipped.
+ *
+ * @param {ReturnType<import('vite').Rollup.PluginContext['parse']>} ast
+ */
+function exportNames(ast) {
+	/** @type {string[]} */
+	const names = []
+	for (const node of ast.body) {
+		if (node.type === 'ExportDefaultDeclaration') names.push('default')
+		if (node.type !== 'ExportNamedDeclaration') continue
+		const declaration = node.declaration
+		if (declaration && 'declarations' in declaration) {
+			for (const { id } of declaration.declarations) {
+				if (id.type === 'Identifier') names.push(id.name)
+			}
+		} else if (declaration?.id && 'name' in declaration.id) {
+			names.push(declaration.id.name)
+		}
+		for (const { exported } of node.specifiers) {
+			names.push(
+				exported.type === 'Identifier' ? exported.name : exported.value
+			)
+		}
+	}
+	return names
+}

package/lib/island.jsx

@@ -0,0 +1,108 @@
+import { createContext, useContext } from 'react'
+import { renderToString } from 'react-dom/server'
+
+/** Set while rendering inside an island: nested islands render inline. */
+const InsideIsland = createContext(false)
+
+/** @type {(src: string) => string} */
+let resolveUrl = (src) => src
+let islandCount = 0
+
+/**
+ * Start rendering a page: set how an island's source path (relative to the
+ * Vite root) becomes the URL the browser imports it from, and restart the
+ * per-page island numbering.
+ *
+ * @param {(src: string) => string} fn
+ */
+export function beginPage(fn) {
+	resolveUrl = fn
+	islandCount = 0
+}
+
+/**
+ * Server-side wrapper for a `'use client'` export. Components render inside an
+ * `<orga-island>` that tells the client runtime what to import and hydrate;
+ * other exports pass through unchanged.
+ *
+ * Each island is rendered as its own React tree with its own `identifierPrefix`,
+ * matching how the browser hydrates it, so `useId` values line up.
+ *
+ * Props are serialized as JSON, so functions and `children` can't cross to the
+ * browser. The `client` prop picks when to hydrate: `load` (default) or
+ * `visible`.
+ *
+ * @template T
+ * @param {T} Component
+ * @param {string} src - Source path relative to the Vite root
+ * @param {string} name - Export name
+ * @returns {T}
+ */
+export function island(Component, src, name) {
+	if (isType(Component, 'react.lazy')) {
+		throw new Error(
+			`<${name}> from ${src}: a lazy() component can't be an island because it can't be prerendered, use lazy() inside the island instead`
+		)
+	}
+	if (!isComponent(Component)) return Component
+	const Island = ({ client = 'load', ...props }) => {
+		// An island inside another island is already client code.
+		if (useContext(InsideIsland)) return <Component {...props} />
+		/** @param {string} key */
+		const reject = (key) => {
+			throw new Error(
+				`<${name}> from ${src} is an island: prop "${key}" can't be sent to the browser, pass JSON-serializable props only`
+			)
+		}
+		if ('children' in props) reject('children')
+		const json = JSON.stringify(props, (key, value) =>
+			typeof value === 'function' ? reject(key) : value
+		)
+		const prefix = `island-${islandCount++}-`
+		// Render from the serialized props: the browser sees exactly these.
+		const html = renderToString(
+			<InsideIsland value={true}>
+				<Component {...JSON.parse(json)} />
+			</InsideIsland>,
+			{ identifierPrefix: prefix }
+		)
+		return (
+			<orga-island
+				src={resolveUrl(src)}
+				export={name}
+				props={json}
+				prefix={prefix}
+				client={client}
+				style={{ display: 'contents' }}
+				// biome-ignore lint/security/noDangerouslySetInnerHtml: markup React just rendered for this island
+				dangerouslySetInnerHTML={{ __html: html }}
+			/>
+		)
+	}
+	return /** @type {T} */ (/** @type {unknown} */ (Island))
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} type - A `$$typeof` symbol description, e.g. `react.memo`
+ */
+function isType(value, type) {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		/** @type {any} */ (value).$$typeof === Symbol.for(type)
+	)
+}
+
+/**
+ * `memo()` and `forwardRef()` components are objects, not functions.
+ *
+ * @param {unknown} value
+ */
+function isComponent(value) {
+	return (
+		typeof value === 'function' ||
+		isType(value, 'react.memo') ||
+		isType(value, 'react.forward_ref')
+	)
+}

package/lib/orga.d.ts

@@ -8,5 +8,5 @@ export function setupOrga({ containerClass, root, rehypePlugins }: {
     containerClass: string | string[];
     root: string;
     rehypePlugins?: import("unified").PluggableList | undefined;
-}): import("@orgajs/rollup").Plugin;
+}): (import("vite").Plugin<any> | import("@orgajs/rollup").Plugin)[];
 //# sourceMappingURL=orga.d.ts.map

package/lib/orga.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orga.d.ts","sourceRoot":"","sources":["orga.js"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,mEAJG;IAAiC,cAAc,EAAvC,MAAM,GAAC,MAAM,EAAE;IACC,IAAI,EAApB,MAAM;IACoC,aAAa;CACjE,mCAUA"}
+{"version":3,"file":"orga.d.ts","sourceRoot":"","sources":["orga.js"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,mEAJG;IAAiC,cAAc,EAAvC,MAAM,GAAC,MAAM,EAAE;IACC,IAAI,EAApB,MAAM;IACoC,aAAa;CACjE,oEAsBA"}

package/lib/orga.js

@@ -13,14 +13,26 @@ import { getSlugFromContentFilePath } from './files.js'
  * @param {import('unified').PluggableList} [options.rehypePlugins] - Extra rehype plugins appended to defaults
  */
 export function setupOrga({ containerClass, root, rehypePlugins = [] }) {
-	return _orga({
-		rehypePlugins: [
-			[rehypeWrap, { className: containerClass }],
-			[rewriteOrgFileLinks, { root }],
-			mediaAssets,
-			...rehypePlugins
-		]
-	})
+	/** Vite's `base`, set once the config resolves. */
+	const site = { base: '/' }
+	/** @type {import('vite').Plugin} */
+	const base = {
+		name: 'orga-build:base',
+		configResolved(config) {
+			site.base = config.base
+		}
+	}
+	return [
+		base,
+		_orga({
+			rehypePlugins: [
+				[rehypeWrap, { className: containerClass }],
+				[rewriteOrgFileLinks, { root, site }],
+				mediaAssets,
+				...rehypePlugins
+			]
+		})
+	]
 }
 
 // --- plugins ---
@@ -33,16 +45,19 @@ function mediaAssets() {
 		/** @type {Record<string, string>} */
 		const imports = {}
 		visitParents(tree, [{ tagName: 'img' }, { tagName: 'video' }], (node) => {
-			node.type = 'jsx'
 			const { src, ...rest } = node.properties
 			if (typeof src !== 'string') return
-			if (src.startsWith('http')) return
+			// A scheme (`https:`, `data:`) or `//host` means it isn't a local file.
+			if (/^([a-z][a-z\d+.-]*:|\/\/)/i.test(src)) return
+			node.type = 'jsx'
 			const tagName = node.tagName
 			if (!imports[src]) imports[src] = `asset_${genId()}`
 			const name = imports[src]
 			const attrs = Object.entries(rest)
 				.filter(([, v]) => v !== undefined && v !== false)
-				.map(([k, v]) => (v === true ? k : `${k}='${v}'`))
+				.map(([k, v]) =>
+					v === true ? k : `${k}={${JSON.stringify(String(v))}}`
+				)
 				.join(' ')
 			node.value = `<${tagName} src={${name}}${attrs ? ` ${attrs}` : ''}/>`
 		})
@@ -50,7 +65,7 @@ function mediaAssets() {
 		for (const [src, name] of Object.entries(imports)) {
 			tree.children.unshift({
 				type: 'jsx',
-				value: `import ${name} from '${src}'`,
+				value: `import ${name} from ${JSON.stringify(src)}`,
 				children: []
 			})
 		}
@@ -89,10 +104,13 @@ function rehypeWrap({ className = [] }) {
 }
 
 /**
+ * Point links to `.org` files at their pages, keeping any `#fragment`.
+ *
  * @param {Object} options
  * @param {string} options.root
+ * @param {{ base: string }} options.site
  */
-function rewriteOrgFileLinks({ root }) {
+function rewriteOrgFileLinks({ root, site }) {
 	/**
 	 * @param {any} tree
 	 * @param {import('vfile').VFile} [file]
@@ -104,16 +122,36 @@ function rewriteOrgFileLinks({ root }) {
 		visitParents(tree, { tagName: 'a' }, (node) => {
 			const href = node?.properties?.href
 			if (typeof href !== 'string') return
-			if (!href.endsWith('.org')) return
+			if (/^[a-z][a-z\d+.-]*:/i.test(href)) return
+			const hashIndex = href.indexOf('#')
+			const target = hashIndex === -1 ? href : href.slice(0, hashIndex)
+			const hash = hashIndex === -1 ? '' : href.slice(hashIndex)
+			if (!target.endsWith('.org')) return
 
 			const targetSlug = resolveOrgHrefToContentSlug({
 				root,
 				filePath,
-				href
+				href: target
 			})
 			if (!targetSlug) return
-			node.properties.href = targetSlug
+			node.properties.href = pageUrl(targetSlug) + hash
 		})
+
+		/**
+		 * URL of the page at `slug`. With a relative `base`, it is relative to
+		 * this page's directory, as pages are written to `<slug>/index.html`.
+		 * @param {string} slug
+		 */
+		function pageUrl(slug) {
+			const { base } = site
+			if ((base === './' || base === '') && filePath) {
+				const depth = getSlugFromContentFilePath(path.relative(root, filePath))
+					.split('/')
+					.filter(Boolean).length
+				return (depth ? '../'.repeat(depth) : './') + slug.slice(1)
+			}
+			return base.replace(/\/$/, '') + slug
+		}
 	}
 }
 

package/lib/plugin.d.ts

@@ -1,59 +1,44 @@
 /**
  * @typedef {Object} OrgaBuildPluginOptions
  * @property {string} root - Root directory for content files
- * @property {string | undefined} [outDir] - Output directory (excluded from file discovery)
+ * @property {string | undefined} [outDir] - Output directory (default: Vite's `build.outDir`)
  * @property {string|string[]} [containerClass] - CSS class(es) to wrap rendered content
- * @property {string[]} [styles] - Global stylesheet URLs to import/inject
+ * @property {string[]} [styles] - Global stylesheet URLs to link 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`
  */
 /**
- * Creates the canonical orga-build plugin preset.
- * This is the single composition path used by both dev and build.
+ * Creates the orga-build plugin preset: everything needed for `vite` (dev SSR)
+ * and `vite build` (static site) to work, used by the CLI and usable directly
+ * in a `vite.config.js`.
  *
  * @param {OrgaBuildPluginOptions} options
  * @returns {import('vite').PluginOption[]}
  */
-export function orgaBuildPlugin({ root, outDir, containerClass, styles, rehypePlugins }: OrgaBuildPluginOptions): import("vite").PluginOption[];
+export function orgaBuildPlugin({ root, outDir, containerClass, styles, rehypePlugins, exclude, site }: OrgaBuildPluginOptions): import("vite").PluginOption[];
 /**
  * Creates the full Vite config options for orga-build.
- * Includes plugins, resolve aliases, and other shared config.
  *
- * @param {OrgaBuildPluginOptions & { outDir?: string, vitePlugins?: import('vite').PluginOption[], includeFallbackHtml?: boolean, projectRoot?: string }} options
- * @returns {{ plugins: import('vite').PluginOption[], resolve: { alias: typeof alias } }}
+ * @param {OrgaBuildPluginOptions & { vitePlugins?: import('vite').PluginOption[] }} options
+ * @returns {{ plugins: import('vite').PluginOption[] }}
  */
-export function createOrgaBuildConfig({ root, outDir, containerClass, styles, rehypePlugins, vitePlugins, includeFallbackHtml, projectRoot }: OrgaBuildPluginOptions & {
-    outDir?: string;
+export function createOrgaBuildConfig({ vitePlugins, ...options }: OrgaBuildPluginOptions & {
     vitePlugins?: import("vite").PluginOption[];
-    includeFallbackHtml?: boolean;
-    projectRoot?: string;
 }): {
     plugins: import("vite").PluginOption[];
-    resolve: {
-        alias: typeof alias;
-    };
 };
 /**
- * Creates an HTML serving plugin that handles index.html for dev mode.
- *
- * This plugin performs per-request SSR in dev mode (matching Astro/SvelteKit behaviour):
- * - SSR-renders each page on every request using Vite's server module runner
- * - Injects rendered content and page metadata (%orga.*% placeholders) into the template
- * - Falls back to the shell HTML for unknown routes (client-side router handles 404)
- * - Only handles GET/HEAD requests that accept HTML
- * - Does not intercept asset requests
- *
- * @param {string} projectRoot - Project root directory (where orga.config.js lives)
- * @param {string[]} [styles]
- * @returns {import('vite').Plugin}
+ * Prefix of emitted asset paths in server-rendered markup, replaced per page
+ * while prerendering (see `prerender.js`).
  */
-export function htmlFallbackPlugin(projectRoot: string, styles?: string[]): import("vite").Plugin;
+export const assetUrlMarker: "/@orga-build/asset/";
 /**
- * Alias map for React and wouter to ensure consistent resolution
+ * Alias map for React to ensure a single copy is bundled
  */
 export const alias: {
     react: string;
     'react-dom': string;
-    wouter: string;
 };
 export type OrgaBuildPluginOptions = {
     /**
@@ -61,7 +46,7 @@ export type OrgaBuildPluginOptions = {
      */
     root: string;
     /**
-     * - Output directory (excluded from file discovery)
+     * - Output directory (default: Vite's `build.outDir`)
      */
     outDir?: string | undefined;
     /**
@@ -69,12 +54,20 @@ export type OrgaBuildPluginOptions = {
      */
     containerClass?: string | string[];
     /**
-     * - Global stylesheet URLs to import/inject
+     * - Global stylesheet URLs to link from the HTML shell
      */
     styles?: string[];
     /**
      * - Extra rehype plugins appended to orga-build defaults
      */
     rehypePlugins?: import("unified").PluggableList;
+    /**
+     * - 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=plugin.d.ts.map