@homepages/template-kit 0.8.0 → 0.8.1-dev-20260718224903

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @homepages/template-kit
 
+## 0.8.1-dev-20260718224903
+
+### Patch Changes
+
+- f3f6d70: `template-kit check` no longer fails on a tsconfig `paths` alias (e.g.
+  `"@/platform/*": ["../platform/*"]`) or on a section whose contract files
+  share a module large enough for esbuild to code-split. Previously the
+  loader's css-stub plugin decided "external vs. bundle" from the specifier's
+  own text, so a `paths`-resolved alias got re-emitted as a literal bare
+  import Node couldn't resolve; separately, the loader's build applied
+  `publicPath` to code-split `chunk-*.js` cross-imports the same way it does
+  to real asset files, producing an import path Node couldn't resolve either.
+  Both are now decided from the actual resolved file, and `publicPath` is no
+  longer set on the loader's build.
+- 1c2c2db: `template-kit dev`'s preview server no longer 500s on `/runtime/base.css`.
+  The route resolved the file at a path the build never emits to
+  (`dist/css/base.css`; the build copies it flat to `dist/base.css`), so every
+  section rendered unstyled — Tailwind-derived colors and layout were silently
+  missing everywhere, only arbitrary-value element geometry survived. The
+  route now checks the built (flat) path first and falls back to the source
+  (`src/css/`) layout, so it resolves correctly both from an installed kit and
+  when running the CLI unbuilt via `tsx` during kit development.
+- 989d23e: `template-kit dev` gains an optional `--diagnostics-cmd` flag: point it at any
+  command that prints `{"violations": [...]}` JSON for a `--template`/`--section`
+  pair, and the standalone section preview
+  (`/sections/<template>/<section>/<fixture>`) shows a dismissible banner when it
+  reports violations. Unset by default — no behavior change for a workspace that
+  doesn't configure it.
+- e1d5792: `template-kit dev`'s preview server now compiles a template's theme-color
+  Tailwind utilities (`bg-primary`, `text-ink`, `bg-background`, etc.) instead
+  of silently dropping them. `assembleTemplateCss` used to concatenate the
+  compiled theme (`compileThemeToCss`, the `@theme inline` alias layer plus
+  its `:root` custom props) onto Tailwind's CLI output _after_ the CLI had
+  already run, so the theme's color tokens were never part of the build graph
+  Tailwind scanned — `@theme` outside that graph is inert, and silently so, so
+  any utility built on a template color never got generated. No error, no
+  warning: every section rendered with correct layout but default
+  black-on-white text and backgrounds. The theme partial is now written to the
+  dev cache and `@import`ed into the Tailwind entry ahead of the section
+  `@source` scans, mirroring how the registry's own publish pipeline
+  (`ci/build-css.ts`) has always assembled it. `fontFaces` is still prepended
+  to the final bundle separately, since a nested `@import url(...)` doesn't
+  hoist out of an imported partial.
+- 1c4c7dd: Island hydration is now nesting-safe: `hydrateIslands` skips any island marker
+  nested inside another marker, so an island can render another island without the
+  child being hydrated twice (once by its parent root, once independently). Enables
+  interactive islands (accordion, card-slider, carousel) to wrap existing leaf
+  islands (expandable-text) on published pages.
+- ff1d6de: `template-kit dev`'s canvas mirror now shows the Islands inspector panel for a
+  section-level selection, not just a slot selection. A `fill-parent`/`fill-self`
+  island with no owning slot of its own only ever gets its shield dropped by a
+  section-level click, so the panel previously could show it as `shielded` but
+  never `interactive`. Existing slot-selection behavior (edit panel + Islands
+  list) is unchanged.
+- 41d0e88: `template-kit dev` now honors a workspace's tsconfig `paths` when resolving
+  imports, the same way `check` already does via esbuild's native tsconfig
+  lookup. Previously the dev server's Vite instance had no `paths` awareness at
+  all, so a workspace mapping (e.g. `"@/lib/*": ["../lib/*"]`) that made `check`
+  pass left `dev` 500ing with `Cannot find module`. A workspace with no `paths`
+  mapping is unaffected.
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/cli/check/loader.js

@@ -1,5 +1,5 @@
 import { loadEsbuild } from "./resolve-tool.js";
-import { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH } from "./css.js";
+import { ASSET_LOADERS, ASSET_NAMES } from "./css.js";
 import { join, relative } from "node:path";
 import { mkdir, rm, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
@@ -45,6 +45,7 @@ var MissingSectionExport = class extends Error {
 	}
 };
 const RESOLVING = Symbol("css-stub:resolving");
+const isUnderNodeModules = (path) => path.split(/[/\\]/).includes("node_modules");
 const cssStub = {
 	name: "css-stub",
 	setup(b) {
@@ -61,10 +62,13 @@ const cssStub = {
 				path: resolved.path,
 				namespace: "css-stub"
 			};
-			if (!args.path.startsWith(".") && !args.path.startsWith("/")) return {
-				path: args.path,
-				external: true
-			};
+			if (!args.path.startsWith(".") && !args.path.startsWith("/")) {
+				if (resolved.errors.length > 0 || isUnderNodeModules(resolved.path)) return {
+					path: args.path,
+					external: true
+				};
+				return null;
+			}
 			return null;
 		});
 		b.onLoad({
@@ -123,7 +127,6 @@ async function buildAndLoad(section, outdir, workspaceRoot) {
 		logLevel: "silent",
 		plugins: [cssStub],
 		loader: { ...ASSET_LOADERS },
-		publicPath: ASSET_PUBLIC_PATH,
 		assetNames: ASSET_NAMES,
 		absWorkingDir: workspaceRoot
 	});

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

@@ -13,7 +13,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 * 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) {
+function buildTailwindEntry(entryDir, sectionDirs, themePartialPath) {
 	const rel = (target) => {
 		const path = relative(entryDir, target);
 		return path.startsWith(".") ? path : `./${path}`;
@@ -21,16 +21,22 @@ function buildTailwindEntry(entryDir, sectionDirs) {
 	return [
 		`@import "tailwindcss" source(none);`,
 		`@import "@homepages/template-kit/styles.css";`,
+		`@import "${rel(themePartialPath)}";`,
 		...sectionDirs.map((d) => `@source "${rel(d)}/**/*.tsx";`),
 		""
 	].join("\n");
 }
-async function compileUtilities(root, sectionDirs) {
+async function compileUtilities(root, theme, sectionDirs) {
 	const cacheDir = join(root, ".tk-dev-cache");
 	await mkdir(cacheDir, { recursive: true });
 	const input = join(cacheDir, "tw-entry.css");
+	const themePath = join(cacheDir, "tw-theme.css");
 	const output = join(cacheDir, "tw-out.css");
-	await writeFile(input, buildTailwindEntry(cacheDir, sectionDirs), "utf8");
+	await writeFile(themePath, compileThemeToCss({
+		...theme,
+		fontFaces: void 0
+	}), "utf8");
+	await writeFile(input, buildTailwindEntry(cacheDir, sectionDirs, themePath), "utf8");
 	await runTailwind(root, {
 		input,
 		output
@@ -75,11 +81,11 @@ async function compileSectionHandCss(root, sectionDirs) {
 /** 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 utilities = await compileUtilities(root, theme, sectionDirs);
 	const sections = await compileSectionHandCss(root, sectionDirs);
 	return {
 		css: [
-			compileThemeToCss(theme),
+			theme.fontFaces,
 			utilities,
 			sections.css
 		].filter(Boolean).join("\n"),

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

@@ -12,7 +12,7 @@ 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 { workspace, template, islandBootstrapUrl, canvasIslandBootstrapUrl, canvas = false } = args;
 	const instances = await resolveManifestInstances(template);
 	const bodies = [];
 	const islands = {};
@@ -29,8 +29,9 @@ async function composeTemplatePage(vite, args) {
 		sectionHtml: bodies.join("\n"),
 		cssRev: "0",
 		template: template.key,
+		section: "",
 		islands,
-		bootstrapUrl: islandBootstrapUrl
+		bootstrapUrl: canvas ? canvasIslandBootstrapUrl : islandBootstrapUrl
 	});
 }
 

package/dist/cli/dev/diagnostics.js

@@ -0,0 +1,68 @@
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+
+//#region src/cli/dev/diagnostics.ts
+const exec = promisify(execFile);
+const MAX_BUFFER = 1024 * 1024;
+const TIMEOUT_MS = 15e3;
+async function runDiagnostics(cmd, args) {
+	if (cmd === null) return { available: false };
+	const parts = cmd.trim().split(/\s+/);
+	const program = parts[0];
+	if (!program) return { available: false };
+	const baseArgs = parts.slice(1);
+	let stdout;
+	try {
+		stdout = (await exec(program, [
+			...baseArgs,
+			"--template",
+			args.template,
+			"--section",
+			args.section
+		], {
+			maxBuffer: MAX_BUFFER,
+			timeout: TIMEOUT_MS
+		})).stdout;
+	} catch (err) {
+		return {
+			available: true,
+			error: err instanceof Error ? err.message : String(err)
+		};
+	}
+	return parseViolations(stdout);
+}
+function parseViolations(stdout) {
+	let parsed;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch {
+		return {
+			available: true,
+			error: `diagnostics command did not print valid JSON: ${stdout.slice(0, 200)}`
+		};
+	}
+	const body = parsed;
+	if (typeof parsed !== "object" || parsed === null || !Array.isArray(body.violations)) return {
+		available: true,
+		error: `diagnostics command JSON is missing a "violations" array`
+	};
+	const violations = [];
+	for (const raw of body.violations) {
+		if (typeof raw !== "object" || raw === null) continue;
+		const v = raw;
+		if (typeof v.rule !== "string" || typeof v.message !== "string") continue;
+		violations.push({
+			rule: v.rule,
+			message: v.message,
+			...typeof v.file === "string" ? { file: v.file } : {},
+			...typeof v.line === "number" ? { line: v.line } : {}
+		});
+	}
+	return {
+		available: true,
+		violations
+	};
+}
+
+//#endregion
+export { runDiagnostics };

package/dist/cli/dev/index.js

@@ -3,12 +3,16 @@ import { startDevServer } from "./server.js";
 //#region src/cli/dev/index.ts
 const DEFAULT_PORT = 5180;
 async function runDev(argv, cwd) {
+	const port = parsePort(argv) ?? DEFAULT_PORT;
+	const diagnosticsCmd = parseDiagnosticsCmd(argv);
 	const server = await startDevServer({
 		cwd,
-		port: parsePort(argv) ?? DEFAULT_PORT
+		port,
+		diagnosticsCmd
 	});
 	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`);
+	if (diagnosticsCmd) process.stdout.write(`  diagnostics: ${diagnosticsCmd}\n`);
 	await new Promise((resolve) => {
 		const stop = () => {
 			server.close().then(resolve);
@@ -27,6 +31,12 @@ function parsePort(argv) {
 	}
 	return null;
 }
+function parseDiagnosticsCmd(argv) {
+	const i = argv.indexOf("--diagnostics-cmd");
+	if (i < 0) return null;
+	const value = argv[i + 1];
+	return typeof value === "string" ? value : null;
+}
 
 //#endregion
-export { runDev };
+export { parseDiagnosticsCmd, runDev };

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

@@ -0,0 +1,172 @@
+import { join } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+
+//#region src/cli/dev/island-canvas-bootstrap.ts
+const CACHE_DIR = ".tk-dev-cache";
+const BOOTSTRAP_FILE = "island-canvas-bootstrap.js";
+const BOOTSTRAP_SOURCE = `import { hydrateIslands, unmountIslands } from "@homepages/template-kit/island-runtime";
+import { createElement, useLayoutEffect } from "react";
+
+const SHIELD_CLASS = "tr-canvas-shield";
+const LIVE_ATTR = "data-tr-live";
+
+const modules = import.meta.glob("/templates/**/*.{tsx,jsx}");
+const map = window.__TR_ISLAND_MAP || {};
+
+// Per-island hydration-commit signal, keyed by the \`editor\` object THIS load()
+// call clones for that island — never by island key. A section rendering N of
+// one island calls load() N times; keying by key would let the last call's
+// commit gate every handle, un-shielding N-1 of them before their own root has
+// actually committed.
+const commitOf = new WeakMap();
+
+// Wrap the loaded default export so it reports its own hydration commit.
+// Renders no DOM of its own (the tree still matches the SSR markup exactly),
+// and useLayoutEffect fires after the commit but before paint, so the canvas
+// never shows an unshielded frame.
+function withCommitSignal(component, signalCommit) {
+  return function IslandCommitSignal(props) {
+    useLayoutEffect(signalCommit, []);
+    return createElement(component, props);
+  };
+}
+
+async function 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));
+  const mod = await importer();
+
+  let signalCommit;
+  const committed = new Promise((resolve) => { signalCommit = resolve; });
+  const editor = mod.editor ? { ...mod.editor } : undefined;
+  if (editor) commitOf.set(editor, { committed, signalCommit });
+
+  return { ...mod, editor, default: withCommitSignal(mod.default, signalCommit) };
+}
+
+function makeShield(doc) {
+  const shield = doc.createElement("div");
+  shield.className = SHIELD_CLASS;
+  shield.setAttribute("aria-hidden", "true");
+  return shield;
+}
+
+// "fill-self": surface made position:relative, shield appended as its last
+// child (unit cards). "fill-parent": shield is a sibling after the surface
+// (map canvas, slider viewport). Idempotent in both modes.
+function installShield(surface, mode) {
+  const doc = surface.ownerDocument;
+  if (mode === "fill-self") {
+    const pos = doc.defaultView ? doc.defaultView.getComputedStyle(surface).position : "";
+    if (!pos || pos === "static") surface.style.position = "relative";
+    if (Array.from(surface.children).some((c) => c.classList.contains(SHIELD_CLASS))) return;
+    surface.appendChild(makeShield(doc));
+    return;
+  }
+  const next = surface.nextElementSibling;
+  if (next && next.classList.contains(SHIELD_CLASS)) return;
+  surface.insertAdjacentElement("afterend", makeShield(doc));
+}
+
+function shieldHandle(handle) {
+  const editor = handle.editor;
+  if (!editor || !editor.live) return;
+  const surfaces = editor.liveSurface ? editor.liveSurface(handle.element) : [handle.element];
+  const mode = editor.shieldMode || "fill-parent";
+  for (const surface of surfaces) installShield(surface, mode);
+  // Stamped for island-inspect.ts's read-only panel — not read by any hydration logic.
+  handle.element.setAttribute("data-tr-island-live", "true");
+  handle.element.setAttribute("data-tr-shield-mode", mode);
+}
+
+// Every TOP-LEVEL island marker under root, excluding nested ones (a marker
+// inside another marker is hydrated by its parent island's own React root —
+// see hydrateIslands' own filter in island-runtime; this mirrors it so the
+// inspector never double-reports or mis-marks a nested child).
+function topLevelMarkers(root) {
+  return Array.from(root.querySelectorAll("[data-tr-island]")).filter(
+    (el) => !el.parentElement || !el.parentElement.closest("[data-tr-island]"),
+  );
+}
+
+let styleInstalled = false;
+function ensureShieldStyle() {
+  if (styleInstalled || document.getElementById("tr-canvas-shield-style")) return;
+  styleInstalled = true;
+  const style = document.createElement("style");
+  style.id = "tr-canvas-shield-style";
+  style.textContent =
+    "." + SHIELD_CLASS + "{position:absolute;inset:0;z-index:1;cursor:pointer;background:transparent;}" +
+    "[" + LIVE_ATTR + "] ." + SHIELD_CLASS + "{display:none;}";
+  document.head.appendChild(style);
+}
+
+// Hydrate every live island under \`root\`, install its shield(s), and mark every
+// top-level island (live or not) with data-tr-island-live for the inspector.
+async function hydrateRoot(root) {
+  ensureShieldStyle();
+  const before = new Set(topLevelMarkers(root));
+
+  const handles = await hydrateIslands({
+    root,
+    load,
+    shouldHydrate: (ctx) => (ctx.editor ? ctx.editor.live === true : false),
+    applyEditorProps: true,
+    onError: (error, ctx) => {
+      console.error("template-kit dev: canvas island failed to hydrate:", ctx.key, error);
+      // Settle its commit: a failed island never signals one, and the wait
+      // below must not stall the rest of this root's shields on it.
+      if (ctx.editor) { const c = commitOf.get(ctx.editor); if (c) c.signalCommit(); }
+    },
+  });
+
+  // hydrateRoot (React's) flushes on a scheduler task, so hydrateIslands
+  // returns before React has committed. Shielding here would mutate a
+  // not-yet-hydrated tree: in fill-self mode the shield lands INSIDE a
+  // React-owned surface, and React then discards the whole SSR tree and
+  // client-renders, wiping shield and inline position both. Waiting on the
+  // real commit — not a task-turn guess — is what makes the mutation stick.
+  await Promise.all(
+    handles
+      .map((h) => (h.editor ? commitOf.get(h.editor) : undefined))
+      .filter((c) => c !== undefined)
+      .map((c) => c.committed),
+  );
+
+  for (const handle of handles) {
+    shieldHandle(handle);
+    before.delete(handle.element);
+  }
+  // Whatever's left in \`before\` is a top-level island that did not pass
+  // shouldHydrate (editor.live !== true, or no editor at all) — static by its
+  // own contract; mark it so for the inspector.
+  for (const el of before) el.setAttribute("data-tr-island-live", "false");
+
+  return handles;
+}
+
+function unmountRoot(root) {
+  unmountIslands(root);
+  root.querySelectorAll("." + SHIELD_CLASS).forEach((s) => s.remove());
+}
+
+window.__trCanvasIslands = { hydrateRoot, unmountRoot };
+void hydrateRoot(document.body);
+`;
+/**
+* Write the shared canvas bootstrap into the workspace cache dir and return
+* the URL the canvas page loads it from. Same mechanics as
+* writeIslandBootstrap: lives under the root so Vite serves + transforms it,
+* reached via Vite's `/@fs/` prefix.
+*/
+async function writeIslandCanvasBootstrap(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 { writeIslandCanvasBootstrap };

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

@@ -1,6 +1,7 @@
 //#region src/cli/dev/section-page.ts
 function wrapSectionHtml(opts) {
 	const t = encodeURIComponent(opts.template);
+	const s = encodeURIComponent(opts.section);
 	const v = encodeURIComponent(opts.cssRev);
 	return `<!doctype html>
 <html lang="en">
@@ -14,10 +15,15 @@ function wrapSectionHtml(opts) {
   </head>
   <body>
     <div id="section-host">${opts.sectionHtml}</div>${islandBootstrap(opts.islands, opts.bootstrapUrl)}
-    <script>${HMR_CLIENT_JS}<\/script>
+    <script>${HMR_CLIENT_JS}<\/script>${diagnosticsBanner(opts.section, t, s)}
   </body>
 </html>`;
 }
+function diagnosticsBanner(section, template, encodedSection) {
+	if (section === "") return "";
+	return `
+    <script>${diagnosticsClientJs(template, encodedSection)}<\/script>`;
+}
 function islandBootstrap(islands, bootstrapUrl) {
 	if (Object.keys(islands).length === 0) return "";
 	const mapJson = JSON.stringify(islands).replace(/</g, "\\u003c");
@@ -49,6 +55,37 @@ const HMR_CLIENT_JS = `
   } catch (e) { /* dev-only; ignore */ }
 })();
 `.trim();
+function diagnosticsClientJs(template, section) {
+	return `
+(function () {
+  function render(violations) {
+    var banner = document.createElement("div");
+    banner.setAttribute("data-diagnostics-banner", "");
+    banner.style.cssText = "position:sticky;top:0;z-index:9999;background:#fee2e2;color:#7f1d1d;" +
+      "font:13px/1.4 monospace;padding:8px 12px;border-bottom:1px solid #fca5a5;";
+    var dismiss = document.createElement("button");
+    dismiss.textContent = "dismiss";
+    dismiss.style.cssText = "float:right;cursor:pointer;";
+    dismiss.onclick = function () { banner.remove(); };
+    var text = document.createElement("pre");
+    text.style.cssText = "margin:0;white-space:pre-wrap;";
+    text.textContent = violations.map(function (v) {
+      var loc = v.file ? " (" + v.file + (v.line ? ":" + v.line : "") + ")" : "";
+      return "[" + v.rule + "] " + v.message + loc;
+    }).join("\\n");
+    banner.appendChild(dismiss);
+    banner.appendChild(text);
+    document.body.insertBefore(banner, document.body.firstChild);
+  }
+  fetch("/api/diagnostics?template=${template}&section=${section}")
+    .then(function (r) { return r.json(); })
+    .then(function (body) {
+      if (body.available && body.violations && body.violations.length > 0) render(body.violations);
+    })
+    .catch(function () { /* dev-only; ignore */ });
+})();
+`.trim();
+}
 
 //#endregion
 export { wrapSectionHtml };

package/dist/cli/dev/server.js

@@ -11,10 +11,12 @@ import { projectSlotSchema } from "./slot-schema.js";
 import { renderSection } from "./render-section.js";
 import { wrapSectionHtml } from "./section-page.js";
 import { composeTemplatePage } from "./compose-template.js";
+import { runDiagnostics } from "./diagnostics.js";
 import { collectRenderedSlotIds, computeSlotFills } from "./fill-state.js";
 import { summarizeHtml } from "./structure-summary.js";
 import { inspectSection } from "./inspect.js";
 import { writeIslandBootstrap } from "./island-bootstrap.js";
+import { writeIslandCanvasBootstrap } from "./island-canvas-bootstrap.js";
 import { resolveScreenshotPath } from "./screenshot-target.js";
 import { createDevViteServer } from "./vite-server.js";
 import { resolveWorkspace } from "./workspace.js";
@@ -25,7 +27,9 @@ import { fileURLToPath } from "node:url";
 import { createServer } from "node:http";
 
 //#region src/cli/dev/server.ts
-const BASE_CSS_PATH = fileURLToPath(new URL("../../css/base.css", import.meta.url));
+const BASE_CSS_PATH_BUILT = fileURLToPath(new URL("../../base.css", import.meta.url));
+const BASE_CSS_PATH_SOURCE = fileURLToPath(new URL("../../css/base.css", import.meta.url));
+const BASE_CSS_PATH = existsSync(BASE_CSS_PATH_BUILT) ? BASE_CSS_PATH_BUILT : BASE_CSS_PATH_SOURCE;
 const DEV_CLIENT_DIR = join(findPackageRoot(fileURLToPath(import.meta.url)), "dist", "dev-client");
 const ASSET_MIME = {
 	".js": "text/javascript; charset=utf-8",
@@ -64,6 +68,7 @@ async function startDevServer(opts) {
 	const cssCache = /* @__PURE__ */ new Map();
 	const sectionAssets = /* @__PURE__ */ new Map();
 	const islandBootstrapUrl = await writeIslandBootstrap(workspace.root);
+	const canvasIslandBootstrapUrl = await writeIslandCanvasBootstrap(workspace.root);
 	vite.watcher.on("change", () => {
 		vite.moduleGraph.invalidateAll();
 		cssCache.clear();
@@ -77,7 +82,9 @@ async function startDevServer(opts) {
 		port: opts.port,
 		cssCache,
 		sectionAssets,
-		islandBootstrapUrl
+		islandBootstrapUrl,
+		canvasIslandBootstrapUrl,
+		diagnosticsCmd: opts.diagnosticsCmd ?? null
 	};
 	const server = createServer((req, res) => {
 		handle(req, res, ctx).catch((err) => {
@@ -115,6 +122,7 @@ async function handle(req, res, ctx) {
 	if (path.startsWith("/section-assets/")) return sendSectionAsset(ctx, path, res);
 	if (path === "/__hmr") return ctx.hmr.attach(res);
 	if (path === "/api/inspect") return sendInspect(ctx, url, res);
+	if (path === "/api/diagnostics") return sendDiagnostics(ctx, url, res);
 	if (path === "/api/screenshot") return sendScreenshot(ctx, url, res);
 	if (path === "/api/render") return sendRenderPayload(ctx, url, req, res);
 	if (path === "/api/template-schema") return sendTemplateSchema(ctx, url, res);
@@ -154,6 +162,7 @@ async function sendTemplatePage(ctx, templateKey, canvas, res) {
 		workspace: ctx.workspace,
 		template,
 		islandBootstrapUrl: ctx.islandBootstrapUrl,
+		canvasIslandBootstrapUrl: ctx.canvasIslandBootstrapUrl,
 		canvas
 	}));
 }
@@ -208,6 +217,7 @@ async function renderSectionPage(ctx, match, overrides) {
 		sectionHtml: html,
 		cssRev: "0",
 		template: match.template,
+		section: match.section,
 		islands,
 		bootstrapUrl: ctx.islandBootstrapUrl
 	});
@@ -236,6 +246,20 @@ async function sendInspect(ctx, url, res) {
 		withOutline: url.searchParams.get("format") === "text"
 	}));
 }
+async function sendDiagnostics(ctx, url, res) {
+	const template = url.searchParams.get("template");
+	const section = url.searchParams.get("section");
+	if (!template || !section) {
+		res.statusCode = 400;
+		res.setHeader("content-type", "text/plain");
+		res.end("diagnostics requires template and section query params");
+		return;
+	}
+	sendJson(res, await runDiagnostics(ctx.diagnosticsCmd, {
+		template,
+		section
+	}));
+}
 const MAX_POST_OVERRIDE_BYTES = 1024 * 1024;
 async function readJsonBody(req, maxBytes) {
 	const chunks = [];