@homepages/template-kit 0.2.0 → 0.4.0

package/dist/cli/dev/build-css.js

@@ -0,0 +1,91 @@
+import { compileThemeToCss } from "../../design-system/theme.js";
+import { loadEsbuild } from "../check/resolve-tool.js";
+import { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH, sectionCssFiles } from "../check/css.js";
+import { runTailwind } from "./tailwind.js";
+import { basename, join, relative } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+//#region src/cli/dev/build-css.ts
+/**
+* The Tailwind entry owns `@import "tailwindcss"` exactly once; `source(none)`
+* disables auto content-detection so only the enumerated section @sources are
+* scanned; the kit's styles.css brings the token preamble and opts its own
+* primitives back in. Every path is emitted relative to `entryDir` (where the
+* entry is written) so it resolves from that location.
+*/
+function buildTailwindEntry(entryDir, sectionDirs) {
+	const rel = (target) => {
+		const path = relative(entryDir, target);
+		return path.startsWith(".") ? path : `./${path}`;
+	};
+	return [
+		`@import "tailwindcss" source(none);`,
+		`@import "@homepages/template-kit/styles.css";`,
+		...sectionDirs.map((d) => `@source "${rel(d)}/**/*.tsx";`),
+		""
+	].join("\n");
+}
+async function compileUtilities(root, sectionDirs) {
+	const cacheDir = join(root, ".tk-dev-cache");
+	await mkdir(cacheDir, { recursive: true });
+	const input = join(cacheDir, "tw-entry.css");
+	const output = join(cacheDir, "tw-out.css");
+	await writeFile(input, buildTailwindEntry(cacheDir, sectionDirs), "utf8");
+	await runTailwind(root, {
+		input,
+		output
+	});
+	return readFile(output, "utf8");
+}
+/**
+* Bundle every section's hand-written CSS through esbuild's `file` loader, so
+* each `url()` asset ref is rewritten to `/section-assets/<name>-<hash>.<ext>`
+* (production's form) and the referenced bytes are captured. CSS files are
+* concatenated in `sectionCssFiles` order (styles.css first). Assets are keyed
+* by emitted filename, which is content-hashed — so the same asset referenced
+* from two sections dedupes to one entry.
+*/
+async function compileSectionHandCss(root, sectionDirs) {
+	const { build } = await loadEsbuild(root);
+	const assets = /* @__PURE__ */ new Map();
+	const parts = [];
+	for (const dir of sectionDirs) for (const cssFile of await sectionCssFiles(dir)) {
+		const result = await build({
+			entryPoints: [cssFile],
+			bundle: true,
+			write: false,
+			outdir: "dist",
+			loader: {
+				".css": "css",
+				...ASSET_LOADERS
+			},
+			publicPath: ASSET_PUBLIC_PATH,
+			assetNames: ASSET_NAMES,
+			absWorkingDir: root,
+			logLevel: "silent"
+		});
+		for (const file of result.outputFiles ?? []) if (file.path.endsWith(".css")) parts.push(file.text);
+		else assets.set(basename(file.path), file.contents);
+	}
+	return {
+		css: parts.join("\n"),
+		assets
+	};
+}
+/** theme :root/@theme custom props, the compiled Tailwind utilities, then each
+* section's hand-CSS with its `url()` asset refs rewritten to servable paths. */
+async function assembleTemplateCss(root, theme, sectionDirs) {
+	const utilities = await compileUtilities(root, sectionDirs);
+	const sections = await compileSectionHandCss(root, sectionDirs);
+	return {
+		css: [
+			compileThemeToCss(theme),
+			utilities,
+			sections.css
+		].filter(Boolean).join("\n"),
+		assets: sections.assets
+	};
+}
+
+//#endregion
+export { assembleTemplateCss, buildTailwindEntry };

package/dist/cli/dev/catalog.js

@@ -0,0 +1,35 @@
+import { VERIFICATION_WIDTHS } from "../../design-system/breakpoints.js";
+import { loadSectionBundle } from "../../ssr.js";
+import { discoverSections } from "./discover.js";
+import { join } from "node:path";
+
+//#region src/cli/dev/catalog.ts
+async function buildCatalog(vite, workspace) {
+	const load = (dir, file) => vite.ssrLoadModule(join(dir, file));
+	const templates = [];
+	for (const template of workspace.templates) {
+		const sections = [];
+		for (const section of await discoverSections(template.dir)) try {
+			const { invariantFixtures } = await loadSectionBundle(section.dir, load);
+			sections.push({
+				key: section.name,
+				fixtures: invariantFixtures.map((f) => ({
+					id: f.id,
+					label: f.label
+				}))
+			});
+		} catch {}
+		templates.push({
+			key: template.key,
+			sections
+		});
+	}
+	return {
+		templates,
+		breakpoints: [...VERIFICATION_WIDTHS],
+		defaultTemplate: workspace.cwdTemplate
+	};
+}
+
+//#endregion
+export { buildCatalog };

package/dist/cli/dev/compose-template.js

@@ -0,0 +1,38 @@
+import { ATTR_SECTION_INSTANCE_ID } from "../../contracts/markers.js";
+import { buildSectionIslandMap } from "./island-map.js";
+import { resolveManifestInstances } from "./manifest-instances.js";
+import { renderSection } from "./render-section.js";
+import { wrapSectionHtml } from "./section-page.js";
+
+//#region src/cli/dev/compose-template.ts
+function escapeAttr(value) {
+	return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function wrapInstance(instanceId, label, html) {
+	return `<div ${ATTR_SECTION_INSTANCE_ID}="${escapeAttr(instanceId)}" data-section-label="${escapeAttr(label)}">${html}</div>`;
+}
+async function composeTemplatePage(vite, args) {
+	const { workspace, template, islandBootstrapUrl, canvas = false } = args;
+	const instances = await resolveManifestInstances(template);
+	const bodies = [];
+	const islands = {};
+	for (const inst of instances) {
+		const { html } = await renderSection(vite, {
+			sectionDir: inst.sectionDir,
+			fixture: inst.fixture,
+			override: Object.keys(inst.options).length > 0 ? { options: inst.options } : void 0
+		});
+		bodies.push(canvas ? wrapInstance(inst.instanceId, inst.section, html) : html);
+		Object.assign(islands, await buildSectionIslandMap(workspace.root, workspace.templatesDir, inst.sectionDir));
+	}
+	return wrapSectionHtml({
+		sectionHtml: bodies.join("\n"),
+		cssRev: "0",
+		template: template.key,
+		islands,
+		bootstrapUrl: islandBootstrapUrl
+	});
+}
+
+//#endregion
+export { composeTemplatePage };

package/dist/cli/dev/content-override.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+//#region src/cli/dev/content-override.ts
+const MAX_URL_OVERRIDE_BYTES = 16 * 1024;
+const ContentOverrideSchema = z.object({
+	slots: z.record(z.string(), z.unknown()).optional(),
+	options: z.record(z.string(), z.unknown()).optional(),
+	nav: z.object({
+		selfAnchor: z.string().optional(),
+		anchors: z.record(z.string(), z.unknown()).optional()
+	}).strict().optional(),
+	variants: z.record(z.string(), z.string()).optional()
+}).strict();
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+* Merge `patch` onto `base`: plain objects recurse key-by-key; anything else
+* (scalar, array, or `null`) replaces. Keys absent from `patch` keep the `base`
+* value. Pure — never mutates its inputs.
+*/
+function deepMerge(base, patch) {
+	if (!isPlainObject(base) || !isPlainObject(patch)) return patch;
+	const out = { ...base };
+	for (const [k, v] of Object.entries(patch)) out[k] = k in base ? deepMerge(base[k], v) : v;
+	return out;
+}
+/** Deep-merge an override onto resolved props. `undefined` returns `base` as-is. */
+function applyContentOverride(base, override) {
+	if (!override) return base;
+	return {
+		slots: deepMerge(base.slots, override.slots ?? {}),
+		options: deepMerge(base.options, override.options ?? {}),
+		nav: deepMerge(base.nav, override.nav ?? {}),
+		variants: deepMerge(base.variants, override.variants ?? {})
+	};
+}
+/** Validate untrusted input into a `ContentOverride`. `undefined`/absent → `undefined`. */
+function parseContentOverride(input) {
+	if (input === void 0 || input === null) return void 0;
+	return ContentOverrideSchema.parse(input);
+}
+/** Decode a base64 `?overrides=` URL param, enforce the URL ceiling, and validate. */
+function decodeUrlOverride(raw) {
+	if (!raw) return void 0;
+	const text = Buffer.from(raw, "base64").toString("utf8");
+	if (Buffer.byteLength(text, "utf8") > 16384) throw new Error(`overrides payload exceeds ${MAX_URL_OVERRIDE_BYTES} bytes`);
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch (err) {
+		throw new Error(`invalid overrides payload: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return parseContentOverride(json);
+}
+
+//#endregion
+export { MAX_URL_OVERRIDE_BYTES, applyContentOverride, decodeUrlOverride, deepMerge, parseContentOverride };

package/dist/cli/dev/discover.js

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readdir } from "node:fs/promises";
+
+//#region src/cli/dev/discover.ts
+const REQUIRED_SECTION_FILES = [
+	"Renderer.tsx",
+	"schema.ts",
+	"fill-spec.ts",
+	"fixtures.ts"
+];
+/**
+* Every subdirectory of `<templateDir>/sections` that carries all four contract
+* files, sorted by name. A folder missing any of the four is not a section and
+* is skipped (not an error — it may be a work in progress).
+*/
+async function discoverSections(templateDir) {
+	const sectionsDir = join(templateDir, "sections");
+	if (!existsSync(sectionsDir)) return [];
+	const entries = await readdir(sectionsDir, { withFileTypes: true });
+	const out = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const dir = join(sectionsDir, entry.name);
+		if (REQUIRED_SECTION_FILES.every((file) => existsSync(join(dir, file)))) out.push({
+			name: entry.name,
+			dir
+		});
+	}
+	out.sort((a, b) => a.name.localeCompare(b.name));
+	return out;
+}
+
+//#endregion
+export { REQUIRED_SECTION_FILES, discoverSections };

package/dist/cli/dev/fill-state.js

@@ -0,0 +1,75 @@
+//#region src/cli/dev/fill-state.ts
+const LIST_TYPES = /* @__PURE__ */ new Set([
+	"list",
+	"poi_list",
+	"image_collection",
+	"object_list"
+]);
+/** Whether a resolved slot value carries real content for its type. */
+function slotHasContent(value, type) {
+	if (value === null || value === void 0) return false;
+	if (LIST_TYPES.has(type)) return Array.isArray(value) && value.length > 0;
+	if (type === "image") return typeof value === "object" && Boolean(value.url);
+	if (typeof value === "string") return value.trim().length > 0;
+	return true;
+}
+/** Every `data-slot-id` in the rendered tree. */
+function collectRenderedSlotIds(root) {
+	const ids = /* @__PURE__ */ new Set();
+	const walk = (node) => {
+		if (node.slotId) ids.add(node.slotId);
+		node.children.forEach(walk);
+	};
+	walk(root);
+	return ids;
+}
+/**
+* Best-effort line number (1-based) of each `<slotId>:` declaration inside the
+* `slots:` block of a section's schema.ts source. A slot not located is omitted.
+*/
+function schemaSlotLines(source, slotIds) {
+	const lines = source.split("\n");
+	const slotsAt = lines.findIndex((l) => /(^|\s)slots\s*:/.test(l));
+	const out = {};
+	if (slotsAt < 0) return out;
+	for (const id of slotIds) {
+		const re = new RegExp(`^\\s*${id}\\s*:`);
+		const idx = lines.findIndex((l, i) => i > slotsAt && re.test(l));
+		if (idx >= 0) out[id] = idx + 1;
+	}
+	return out;
+}
+function truncate(s, n = 80) {
+	return s.length > n ? s.slice(0, n) + "…" : s;
+}
+function valuePreview(value, type) {
+	if (LIST_TYPES.has(type)) return Array.isArray(value) ? `[${value.length} items]` : void 0;
+	if (type === "image") {
+		const url = value?.url;
+		return url ? `image:${truncate(url)}` : void 0;
+	}
+	if (typeof value === "string") return truncate(value);
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+}
+function computeSlotFills(args) {
+	const { declaredSlots, resolvedSlots, renderedSlotIds, slotLines } = args;
+	return Object.entries(declaredSlots).map(([id, def]) => {
+		const required = def.required ?? false;
+		const has = slotHasContent(resolvedSlots[id], def.type);
+		const fillState = has ? "filled" : required ? "missing" : "empty";
+		const preview = has ? valuePreview(resolvedSlots[id], def.type) : void 0;
+		const line = slotLines[id];
+		return {
+			id,
+			type: def.type,
+			required,
+			fillState,
+			rendered: renderedSlotIds.has(id),
+			...preview !== void 0 ? { value: preview } : {},
+			at: line ? `schema.ts:${line}` : "schema.ts"
+		};
+	});
+}
+
+//#endregion
+export { collectRenderedSlotIds, computeSlotFills, schemaSlotLines, slotHasContent };

package/dist/cli/dev/index.js

@@ -0,0 +1,32 @@
+import { startDevServer } from "./server.js";
+
+//#region src/cli/dev/index.ts
+const DEFAULT_PORT = 5180;
+async function runDev(argv, cwd) {
+	const server = await startDevServer({
+		cwd,
+		port: parsePort(argv) ?? DEFAULT_PORT
+	});
+	process.stdout.write(`template-kit dev — ${server.workspace.templates.length} template(s) at ${server.url}\n`);
+	for (const template of server.workspace.templates) process.stdout.write(`  ${template.key}: ${server.url}/sections/${template.key}/<section>/<fixture>\n`);
+	await new Promise((resolve) => {
+		const stop = () => {
+			server.close().then(resolve);
+		};
+		process.once("SIGINT", stop);
+		process.once("SIGTERM", stop);
+	});
+	return 0;
+}
+function parsePort(argv) {
+	const i = argv.indexOf("--port");
+	if (i >= 0) {
+		const raw = argv[i + 1];
+		const n = raw !== void 0 ? Number(raw) : NaN;
+		if (Number.isInteger(n) && n > 0) return n;
+	}
+	return null;
+}
+
+//#endregion
+export { runDev };

package/dist/cli/dev/inspect.js

@@ -0,0 +1,38 @@
+import { renderSection } from "./render-section.js";
+import { collectRenderedSlotIds, computeSlotFills, schemaSlotLines } from "./fill-state.js";
+import { summarizeHtml } from "./structure-summary.js";
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+
+//#region src/cli/dev/inspect.ts
+async function inspectSection(vite, args) {
+	const result = await renderSection(vite, {
+		sectionDir: args.sectionDir,
+		fixture: args.fixture,
+		override: args.override
+	});
+	const { tree, text } = summarizeHtml(result.html);
+	const schemaSource = await readFile(join(args.sectionDir, "schema.ts"), "utf8");
+	const slots = computeSlotFills({
+		declaredSlots: result.schemaSlots,
+		resolvedSlots: result.resolvedProps.slots,
+		renderedSlotIds: collectRenderedSlotIds(tree),
+		slotLines: schemaSlotLines(schemaSource, Object.keys(result.schemaSlots))
+	});
+	return {
+		target: {
+			template: args.template,
+			section: args.section,
+			fixture: args.fixture,
+			schemaFile: `sections/${args.section}/schema.ts`
+		},
+		slots,
+		options: result.resolvedProps.options,
+		variants: result.resolvedProps.variants,
+		nullCorpus: result.nullCorpus,
+		...args.withOutline ? { outline: text } : {}
+	};
+}
+
+//#endregion
+export { inspectSection };

package/dist/cli/dev/island-bootstrap.js

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+
+//#region src/cli/dev/island-bootstrap.ts
+const CACHE_DIR = ".tk-dev-cache";
+const BOOTSTRAP_FILE = "island-bootstrap.js";
+const BOOTSTRAP_SOURCE = `import { hydrateIslands } from "@homepages/template-kit/island-runtime";
+
+const modules = import.meta.glob("/templates/**/*.{tsx,jsx}");
+const map = window.__TR_ISLAND_MAP || {};
+
+hydrateIslands({
+  load: (key) => {
+    const url = map[key];
+    const importer = url ? modules[url] : undefined;
+    if (!importer) return Promise.reject(new Error("template-kit dev: no island module for " + key));
+    return importer();
+  },
+  onError: (error, ctx) => {
+    console.error("template-kit dev: island failed to hydrate:", ctx.key, error);
+  },
+});
+`;
+/**
+* Write the shared bootstrap into the workspace cache dir and return the URL the
+* page loads it from. It lives under the root so Vite serves + transforms it (the
+* bare `island-runtime` import and the glob), reached via Vite's `/@fs/` prefix.
+*/
+async function writeIslandBootstrap(root) {
+	const dir = join(root, CACHE_DIR);
+	await mkdir(dir, { recursive: true });
+	const abs = join(dir, BOOTSTRAP_FILE);
+	await writeFile(abs, BOOTSTRAP_SOURCE, "utf8");
+	return `/@fs/${abs}`;
+}
+
+//#endregion
+export { writeIslandBootstrap };

package/dist/cli/dev/island-map.js

@@ -0,0 +1,35 @@
+import { islandKey } from "../../islands/detect.js";
+import { findSectionIslands } from "../../islands/discover.js";
+import { basename, extname, relative, sep } from "node:path";
+
+//#region src/cli/dev/island-map.ts
+/**
+* Derive an island key from a client component's absolute path, relative to the
+* workspace's `templates/` dir: `<templateFolder>/<section>:<ComponentName>`.
+* A component name is the file basename. Returns null for a path that is not a
+* `templates/<folder>/sections/<section>/…` component.
+*/
+function islandKeyForFile(templatesDir, absFile) {
+	const rel = relative(templatesDir, absFile);
+	if (rel.startsWith("..")) return null;
+	const parts = rel.split(sep);
+	if (parts.length < 4 || parts[1] !== "sections") return null;
+	return islandKey(`${parts[0]}/${parts[2]}`, basename(absFile, extname(absFile)));
+}
+/**
+* The map the browser bootstrap reads: island key → the module's root-relative
+* URL (what Vite serves it at, and what `import.meta.glob("/templates/**")` keys
+* it by). Empty when the section has no islands.
+*/
+async function buildSectionIslandMap(root, templatesDir, sectionDir) {
+	const map = {};
+	for (const file of await findSectionIslands(sectionDir)) {
+		const key = islandKeyForFile(templatesDir, file);
+		if (!key) continue;
+		map[key] = "/" + relative(root, file).split(sep).join("/");
+	}
+	return map;
+}
+
+//#endregion
+export { buildSectionIslandMap, islandKeyForFile };

package/dist/cli/dev/island-transform.js

@@ -0,0 +1,31 @@
+import { wrapClientModuleMagic } from "../../islands/wrap.js";
+import { islandKeyForFile } from "./island-map.js";
+import { extname, join, sep } from "node:path";
+
+//#region src/cli/dev/island-transform.ts
+const COMPONENT_EXTS = /* @__PURE__ */ new Set([".tsx", ".jsx"]);
+function islandTransformPlugin(opts) {
+	const templatesDir = join(opts.root, "templates");
+	const templatesPrefix = templatesDir + sep;
+	return {
+		name: "template-kit:island-transform",
+		enforce: "pre",
+		transform(code, id, options) {
+			if (!options?.ssr) return null;
+			const file = id.split("?", 1)[0] ?? id;
+			if (!file.startsWith(templatesPrefix)) return null;
+			if (!COMPONENT_EXTS.has(extname(file))) return null;
+			const key = islandKeyForFile(templatesDir, file);
+			if (!key) return null;
+			const s = wrapClientModuleMagic(code, key);
+			if (s === null) return null;
+			return {
+				code: s.toString(),
+				map: s.generateMap({ hires: true })
+			};
+		}
+	};
+}
+
+//#endregion
+export { islandTransformPlugin };

package/dist/cli/dev/manifest-instances.js

@@ -0,0 +1,31 @@
+import { TemplateManifest } from "../../schema/manifest.js";
+import { discoverSections } from "./discover.js";
+import { readFile } from "node:fs/promises";
+
+//#region src/cli/dev/manifest-instances.ts
+function selectManifestInstances(sections, manifestSections) {
+	const out = [];
+	for (const inst of manifestSections) {
+		const info = sections.find((s) => s.name === inst.section);
+		if (!info) continue;
+		out.push({
+			instanceId: inst.instance_id,
+			section: inst.section,
+			sectionDir: info.dir,
+			fixture: "typical",
+			options: inst.options
+		});
+	}
+	return out;
+}
+async function resolveManifestInstances(template) {
+	const manifest = TemplateManifest.parse(JSON.parse(await readFile(template.manifestPath, "utf8")));
+	return selectManifestInstances(await discoverSections(template.dir), manifest.sections);
+}
+/** The single manifest instance with this id, or null (author WIP / unknown id). */
+async function findManifestInstance(template, instanceId) {
+	return (await resolveManifestInstances(template)).find((i) => i.instanceId === instanceId) ?? null;
+}
+
+//#endregion
+export { findManifestInstance, resolveManifestInstances, selectManifestInstances };

package/dist/cli/dev/render-section.js

@@ -0,0 +1,24 @@
+import { loadSectionBundle, renderSectionHtml } from "../../ssr.js";
+import { applyContentOverride } from "./content-override.js";
+import { projectSlotSchema } from "./slot-schema.js";
+import { join } from "node:path";
+
+//#region src/cli/dev/render-section.ts
+async function renderSection(vite, req) {
+	const load = (dir, file) => vite.ssrLoadModule(join(dir, file));
+	const { Renderer, invariantFixtures, schemaSlots } = await loadSectionBundle(req.sectionDir, load);
+	const fx = invariantFixtures.find((f) => f.id === req.fixture);
+	if (!fx) throw new Error(`fixture "${req.fixture}" not found (have: ${invariantFixtures.map((r) => r.id).join(", ")})`);
+	const props = applyContentOverride(fx.props, req.override);
+	return {
+		html: renderSectionHtml(Renderer, props),
+		resolvedProps: props,
+		fixtureLabel: fx.label,
+		slotSchema: projectSlotSchema(schemaSlots),
+		schemaSlots,
+		nullCorpus: invariantFixtures.filter((f) => f.id.startsWith("null_")).map((f) => f.id)
+	};
+}
+
+//#endregion
+export { renderSection };

package/dist/cli/dev/screenshot-target.js

@@ -0,0 +1,24 @@
+//#region src/cli/dev/screenshot-target.ts
+function resolveScreenshotPath(t) {
+	if (!t.template) return {
+		ok: false,
+		error: "screenshot requires a template"
+	};
+	const hasSection = Boolean(t.section);
+	if (hasSection !== Boolean(t.fixture)) return {
+		ok: false,
+		error: "provide section and fixture together for a section screenshot, or neither for a full-template screenshot"
+	};
+	const enc = encodeURIComponent;
+	if (hasSection) return {
+		ok: true,
+		path: `/sections/${enc(t.template)}/${enc(t.section)}/${enc(t.fixture)}`
+	};
+	return {
+		ok: true,
+		path: `/template/${enc(t.template)}`
+	};
+}
+
+//#endregion
+export { resolveScreenshotPath };

package/dist/cli/dev/section-page.js

@@ -0,0 +1,54 @@
+//#region src/cli/dev/section-page.ts
+function wrapSectionHtml(opts) {
+	const t = encodeURIComponent(opts.template);
+	const v = encodeURIComponent(opts.cssRev);
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Section Preview</title>
+    <link rel="stylesheet" href="/runtime/base.css?v=${v}" />
+    <link rel="stylesheet" href="/runtime/template.css?template=${t}&v=${v}" />
+    <style>html, body { margin: 0; padding: 0; background: #fff; }</style>
+  </head>
+  <body>
+    <div id="section-host">${opts.sectionHtml}</div>${islandBootstrap(opts.islands, opts.bootstrapUrl)}
+    <script>${HMR_CLIENT_JS}<\/script>
+  </body>
+</html>`;
+}
+function islandBootstrap(islands, bootstrapUrl) {
+	if (Object.keys(islands).length === 0) return "";
+	const mapJson = JSON.stringify(islands).replace(/</g, "\\u003c");
+	return `
+    ${REACT_REFRESH_PREAMBLE}
+    <script>window.__TR_ISLAND_MAP = ${mapJson};<\/script>
+    <script type="module" src="${bootstrapUrl}"><\/script>`;
+}
+const REACT_REFRESH_PREAMBLE = `<script type="module">
+      import RefreshRuntime from "/@react-refresh";
+      RefreshRuntime.injectIntoGlobalHook(window);
+      window.$RefreshReg$ = () => {};
+      window.$RefreshSig$ = () => (type) => type;
+      window.__vite_plugin_react_preamble_installed__ = true;
+    <\/script>`;
+const HMR_CLIENT_JS = `
+(function () {
+  try {
+    var src = new EventSource("/__hmr");
+    src.addEventListener("section:changed", function () { window.location.reload(); });
+    src.addEventListener("tailwind:changed", function () {
+      var link = document.querySelector('link[href*="/runtime/template.css"]');
+      if (link) {
+        var href = link.getAttribute("href");
+        var base = href.split("&v=")[0];
+        link.setAttribute("href", base + "&v=" + Date.now());
+      }
+    });
+  } catch (e) { /* dev-only; ignore */ }
+})();
+`.trim();
+
+//#endregion
+export { wrapSectionHtml };