@homepages/template-kit 0.1.0 → 0.3.0

package/dist/cli/check/stages/lint.js

@@ -0,0 +1,46 @@
+import { resolveFromWorkspace } from "../resolve-tool.js";
+import { sectionOf } from "../paths.js";
+import { relativizePaths } from "../relativize.js";
+import { join, relative } from "node:path";
+
+//#region src/cli/check/stages/lint.ts
+const PARSE_ERROR_RULE_ID = "template-kit/parse-error";
+const FIX_HINTS = {
+	"template-kit/no-nondeterminism": "Remove the clock or randomness read from server-rendered code, or move this logic into an island (a file marked use client).",
+	"template-kit/no-client-runtime-in-server": "Move this into an island (mark the file use client) or drop the browser-only API — a Renderer must be a pure function of its props.",
+	"template-kit/serializable-island-props": "Pass only JSON-serializable values to an island: no functions, Date/Map/Set instances, bigints, NaN, or Infinity.",
+	"template-kit/no-inline-style": "Replace the style prop with a Tailwind class or a design-system token. Inline style bypasses the cascade and responsive prefixes.",
+	"template-kit/no-raw-element": "Use the contract-bearing primitive instead of the raw element: Section for section, Image for img.",
+	"template-kit/image-bare-needs-reason": "Add a bare: comment above the Image explaining why the frame is skipped, or remove the bare prop.",
+	"template-kit/slot-marker-literal": "Give the marker's id a string literal, not an expression, so the slot-marker completeness check can read it statically.",
+	"template-kit/no-hex": "Use a design-system color token instead of a hex literal or CSS color function.",
+	"template-kit/no-css-import-from-render-path": "Delete the relative CSS import. The file's own CSS is already collected by path; use a bare package specifier for a third-party stylesheet.",
+	"template-kit/props-from-schema": "Derive Props from SectionProps<typeof schema> instead of hand-writing the type.",
+	"template-kit/no-client-directive-in-contract": "Remove the use client directive from this contract file. schema.ts, fill-spec.ts, fixtures.ts and Renderer.tsx are read outside the browser."
+};
+async function lintStage(workspaceRoot, template) {
+	const { ESLint } = await resolveFromWorkspace(workspaceRoot, "eslint");
+	const results = await new ESLint({
+		cwd: workspaceRoot,
+		errorOnUnmatchedPattern: false
+	}).lintFiles([join(template.dir, "**/*.{ts,tsx}")]);
+	const out = [];
+	for (const result of results) for (const message of result.messages) {
+		if (message.severity !== 2) continue;
+		const ruleId = message.ruleId ?? PARSE_ERROR_RULE_ID;
+		const text = relativizePaths(message.message, workspaceRoot);
+		out.push({
+			ruleId,
+			template: template.key,
+			section: sectionOf(template, result.filePath),
+			file: relative(workspaceRoot, result.filePath),
+			line: message.line,
+			message: text,
+			fix: FIX_HINTS[ruleId] ?? text
+		});
+	}
+	return out;
+}
+
+//#endregion
+export { lintStage };

package/dist/cli/check/stages/render.js

@@ -0,0 +1,101 @@
+import { FixtureModuleShape, buildInvariantFixtures } from "../../../schema/fixture-schema.js";
+import { loadSection } from "../loader.js";
+import { flattenLayout } from "../../../schema/rows.js";
+import { checkRenderInvariants } from "../render-invariants.js";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+//#region src/cli/check/stages/render.ts
+function renderSectionHtml(renderer, props) {
+	return renderToStaticMarkup(createElement(renderer, props));
+}
+const SLOT_ID_RE = /data-slot-id="([^"]*)"/g;
+function renderSlotOrder(html) {
+	const seen = /* @__PURE__ */ new Set();
+	const order = [];
+	for (const match of html.matchAll(SLOT_ID_RE)) {
+		const id = match[1];
+		if (seen.has(id)) continue;
+		seen.add(id);
+		order.push(id);
+	}
+	return order;
+}
+function checkSidebarOrder(sectionKey, schema, html) {
+	const out = [];
+	const groupOf = /* @__PURE__ */ new Map();
+	for (const group of schema.meta?.groups ?? []) for (const member of flattenLayout(group.members)) groupOf.set(member, group.id);
+	const cardOf = (slotId) => groupOf.get(slotId) ?? slotId;
+	const slotOrder = renderSlotOrder(html);
+	const renderCardOrder = [];
+	for (const slotId of slotOrder) {
+		const card = cardOf(slotId);
+		if (!renderCardOrder.includes(card)) renderCardOrder.push(card);
+	}
+	const presentCards = new Set(renderCardOrder);
+	const schemaCardOrder = [];
+	for (const slotId of Object.keys(schema.slots)) {
+		const card = cardOf(slotId);
+		if (!presentCards.has(card)) continue;
+		if (!schemaCardOrder.includes(card)) schemaCardOrder.push(card);
+	}
+	if (JSON.stringify(schemaCardOrder) !== JSON.stringify(renderCardOrder)) out.push({
+		section: sectionKey,
+		rule: "sidebar-order",
+		message: `Sidebar card order (schema slot declaration order) does not match page render order.\n  schema: [${schemaCardOrder.join(", ")}]\n  render: [${renderCardOrder.join(", ")}]`
+	});
+	return out;
+}
+async function renderStage(workspaceRoot, template) {
+	const diagnostics = [];
+	for (const section of template.sections) {
+		const file = `templates/${template.key}/sections/${section.name}/Renderer.tsx`;
+		let loaded;
+		let fixtures;
+		try {
+			loaded = await loadSection(workspaceRoot, section);
+			fixtures = buildInvariantFixtures({
+				schema: loaded.schema,
+				module: FixtureModuleShape.parse(loaded.fixtures),
+				selfAnchor: section.name
+			});
+		} catch {
+			continue;
+		}
+		for (const fixture of fixtures) {
+			const props = fixture.props;
+			const first = renderSectionHtml(loaded.Renderer, props);
+			if (first !== renderSectionHtml(loaded.Renderer, props)) {
+				diagnostics.push({
+					ruleId: "template-kit/determinism-drift",
+					template: template.key,
+					section: section.name,
+					file,
+					message: `fixture "${fixture.id}" rendered differently twice from the same props`,
+					fix: "Something in the render path is nondeterministic — a clock, a random, or an unstable iteration order. Server-rendered code must be a pure function of its props."
+				});
+				continue;
+			}
+			for (const violation of checkRenderInvariants(first)) diagnostics.push({
+				ruleId: "template-kit/render-invariant",
+				template: template.key,
+				section: section.name,
+				file,
+				message: `fixture "${fixture.id}": ${violation.detail}`,
+				fix: violation.rule === "broken-image" ? "Render a placeholder, or nothing, when an image slot is empty — never an <img> with no src." : "A value reached the page without a formatter. Format it, or render nothing when it is absent."
+			});
+			if (fixture.id === "typical") for (const violation of checkSidebarOrder(section.name, loaded.schema, first)) diagnostics.push({
+				ruleId: "template-kit/sidebar-order",
+				template: template.key,
+				section: section.name,
+				file: `templates/${template.key}/sections/${section.name}/schema.ts`,
+				message: violation.message,
+				fix: "The editor lists slots in schema declaration order. Reorder the schema, or the markup, so the two agree."
+			});
+		}
+	}
+	return diagnostics;
+}
+
+//#endregion
+export { checkSidebarOrder, renderSectionHtml, renderStage };

package/dist/cli/check/stages/size.js

@@ -0,0 +1,158 @@
+import { loadEsbuild } from "../resolve-tool.js";
+import { CHECK_CONFIG } from "../config.js";
+import { compileSectionPackageCss, sectionCssFiles } from "../css.js";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { readFile } from "node:fs/promises";
+import { gzipSync } from "node:zlib";
+
+//#region src/cli/check/stages/size.ts
+const RESOLVING = Symbol("size-stub:resolving");
+/**
+* A CSS-only stub, local to this file and NOT `loader.ts`'s `cssStub`: that
+* plugin marks *every* bare specifier external (right for evaluating a
+* section — it must resolve the workspace's real React and real kit
+* primitives, not a second copy), which is exactly wrong for measurement,
+* where an npm package's bundled weight is the entire point of the gate.
+* Only CSS is stubbed here; everything else is left to the `build()` call's
+* own `external` option (see `measureRendererBundle`) plus esbuild's default
+* bundling.
+*
+* Detects a CSS import by resolving the specifier and inspecting the
+* *resolved path's* extension — not by pattern-matching the specifier text.
+* A CSS-only package need not say so in its specifier (`@fontsource/inter`
+* has no `.css` suffix and no `css` path segment; `swiper/css` has no `.css`
+* suffix either), so only real resolution tells the two apart. `pluginData`
+* is the standard recursion guard for `build.resolve()` re-entering this same
+* hook (esbuild docs' own example for this pattern) — mirrors `loader.ts`'s
+* `cssStub`, which learned this the hard way.
+*/
+const sizeStub = {
+	name: "size-stub",
+	setup(b) {
+		b.onResolve({ filter: /.*/ }, async (args) => {
+			if (args.pluginData === RESOLVING) return null;
+			const resolved = await b.resolve(args.path, {
+				importer: args.importer,
+				namespace: args.namespace,
+				resolveDir: args.resolveDir,
+				kind: args.kind,
+				pluginData: RESOLVING
+			});
+			if (resolved.errors.length === 0 && resolved.path !== "" && resolved.path.endsWith(".css")) return {
+				path: resolved.path,
+				namespace: "size-stub"
+			};
+			return null;
+		});
+		b.onLoad({
+			filter: /.*/,
+			namespace: "size-stub"
+		}, () => ({
+			contents: "",
+			loader: "js"
+		}));
+	}
+};
+/**
+* Gzipped bytes of a section's renderer bundle, its own code *and every npm
+* package it imports* — the published bundle's actual shape. React alone is
+* excluded: it is a peer the platform supplies at render time, never bundled
+* into a section. Everything else, including `@homepages/template-kit`
+* itself (its primitives are ordinary React components that ship inside the
+* section bundle, not a peer), is bundled and counted — that is the entire
+* point of this budget. esbuilds `Renderer.tsx` alone (not the other three
+* contract files — schema, fill-spec and fixtures never reach the browser).
+*
+* `external` is deliberately the five React entry points a section can
+* actually reach, not `packages: "external"`: the latter would externalize
+* every bare specifier — including the icon library or schema library this
+* gate exists to catch — reproducing the exact bug this function fixes. Do
+* not "simplify" this back to `packages: "external"`.
+*
+* `platform: "browser"`, not `"neutral"`: `neutral` defaults `mainFields` to
+* `[]`, which cannot resolve a CommonJS-only package's `main` field — and
+* real sections import such packages (an icon library, for instance). With
+* `neutral` the measurement simply fails for those sections; `browser`'s
+* default `mainFields` resolves them.
+*/
+async function measureRendererBundle(workspaceRoot, section) {
+	const { build } = await loadEsbuild(workspaceRoot);
+	const js = (await build({
+		entryPoints: [join(section.dir, "Renderer.tsx")],
+		bundle: true,
+		minify: true,
+		format: "esm",
+		platform: "browser",
+		jsx: "automatic",
+		write: false,
+		outfile: "renderer.js",
+		external: [
+			"react",
+			"react-dom",
+			"react-dom/server",
+			"react/jsx-runtime",
+			"react/jsx-dev-runtime"
+		],
+		plugins: [sizeStub],
+		absWorkingDir: workspaceRoot,
+		logLevel: "silent"
+	})).outputFiles.find((f) => f.path.endsWith(".js"));
+	if (!js) throw new Error(`esbuild produced no JS output for ${section.dir}`);
+	return gzipSync(js.contents).byteLength;
+}
+/**
+* Gzipped bytes of a section's stylesheet: its hand-written CSS
+* (`sectionCssFiles`, published order) concatenated with the package CSS its
+* code pulls in (`compileSectionPackageCss`). The package-CSS half is the
+* point of this budget — a package's `url()`-referenced fonts and icons
+* inline as `data:` URIs (see css.ts), so a package shipping a 300 KB font
+* shows up here as CSS bytes, and this is the guard against exactly that.
+*/
+async function measureSectionCss(workspaceRoot, section) {
+	const ownFiles = await sectionCssFiles(section.dir);
+	const own = (await Promise.all(ownFiles.map((f) => readFile(f, "utf8")))).join("\n");
+	const packageCss = await compileSectionPackageCss(workspaceRoot, section.dir);
+	return gzipSync(Buffer.from(`${own}\n${packageCss}`)).byteLength;
+}
+function kb(bytes) {
+	const value = bytes / 1024;
+	return `${Number.isInteger(value) ? value.toString() : value.toFixed(1)} KB`;
+}
+function cssDiagnosticFile(workspaceRoot, section) {
+	const stylesCss = join(section.dir, "styles.css");
+	return relative(workspaceRoot, existsSync(stylesCss) ? stylesCss : section.dir);
+}
+async function sizeStage(workspaceRoot, template) {
+	const diagnostics = [];
+	for (const section of template.sections) {
+		let rendererBytes;
+		let cssBytes;
+		try {
+			rendererBytes = await measureRendererBundle(workspaceRoot, section);
+			cssBytes = await measureSectionCss(workspaceRoot, section);
+		} catch {
+			continue;
+		}
+		if (rendererBytes > CHECK_CONFIG.size.rendererBundleGzip) diagnostics.push({
+			ruleId: "template-kit/size-renderer-bundle",
+			template: template.key,
+			section: section.name,
+			file: `templates/${template.key}/sections/${section.name}/Renderer.tsx`,
+			message: `renderer bundle is ${kb(rendererBytes)} gzip — over the ${kb(CHECK_CONFIG.size.rendererBundleGzip)} budget`,
+			fix: "Trim what the renderer pulls in. A whole icon library imported for two icons is the usual cause — import only the icons you use, or inline them as SVG."
+		});
+		if (cssBytes > CHECK_CONFIG.size.sectionCssGzip) diagnostics.push({
+			ruleId: "template-kit/size-section-css",
+			template: template.key,
+			section: section.name,
+			file: cssDiagnosticFile(workspaceRoot, section),
+			message: `section stylesheet is ${kb(cssBytes)} gzip — over the ${kb(CHECK_CONFIG.size.sectionCssGzip)} budget`,
+			fix: "Trim the stylesheet. A package that ships a large font or icon set inlines those bytes into your stylesheet — import only what you use."
+		});
+	}
+	return diagnostics;
+}
+
+//#endregion
+export { measureRendererBundle, measureSectionCss, sizeStage };

package/dist/cli/check/stages/tree.js

@@ -0,0 +1,207 @@
+import { CONTRACT_FILES, loadSection } from "../loader.js";
+import { flattenLayout } from "../../../schema/rows.js";
+import { findImportLine, sectionCssFiles } from "../css.js";
+import { extname, join, relative } from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+
+//#region src/cli/check/stages/tree.ts
+const ASSET_EXTENSIONS = /* @__PURE__ */ new Set([
+	".svg",
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".avif",
+	".ico",
+	".woff",
+	".woff2",
+	".ttf",
+	".otf",
+	".eot",
+	".mp4",
+	".webm",
+	".mov",
+	".mp3",
+	".wav",
+	".pdf",
+	".zip"
+]);
+async function isBinaryFile(file) {
+	return (await readFile(file)).subarray(0, 4096).includes(0);
+}
+/** Every authored file in the bundle, recursive. `snapshots/` and `node_modules/` are skipped — generated or foreign, never authored. */
+async function bundleFiles(dir) {
+	const out = [];
+	for (const entry of await readdir(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name === "snapshots" || entry.name === "node_modules") continue;
+			out.push(...await bundleFiles(full));
+		} else if (entry.isFile()) out.push(full);
+	}
+	return out.sort();
+}
+/**
+* The bundle's authored JSX surface: every `.tsx` except tests. An author may
+* put markup anywhere in the folder (components/, hooks/, …), so the marker
+* rules scan all of these, not just Renderer.tsx. Tests are excluded
+* deliberately — a test's expected-markup assertion must not satisfy a slot
+* marker, and fixtures legitimately write raw markup.
+*/
+async function bundleJsxFiles(dir) {
+	return (await bundleFiles(dir)).filter((f) => f.endsWith(".tsx") && !/\.test\.tsx$/.test(f));
+}
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const CSS_REASON = /css-reason:/;
+function opensWithCssReason(text) {
+	const lead = text.match(/^\s*\/\*([\s\S]*?)\*\//);
+	return lead != null && CSS_REASON.test(lead[1] ?? "");
+}
+async function checkBundleAnatomy(workspaceRoot, template, section) {
+	const out = [];
+	const entries = await readdir(section.dir, { withFileTypes: true });
+	for (const f of CONTRACT_FILES) {
+		if (entries.some((entry) => entry.isFile() && entry.name === f)) continue;
+		out.push({
+			ruleId: "template-kit/bundle-incomplete",
+			template: template.key,
+			section: section.name,
+			file: relative(workspaceRoot, join(section.dir, f)),
+			line: 1,
+			message: `Section "${section.name}" is missing the required contract file \`${f}\`.`,
+			fix: "Every section needs Renderer.tsx, schema.ts, fill-spec.ts and fixtures.ts. Add the missing file."
+		});
+	}
+	for (const abs of await bundleFiles(section.dir)) {
+		const rel = relative(workspaceRoot, abs);
+		if (!ASSET_EXTENSIONS.has(extname(abs).toLowerCase()) && !await isBinaryFile(abs)) continue;
+		out.push({
+			ruleId: "template-kit/bundle-binary-asset",
+			template: template.key,
+			section: section.name,
+			file: rel,
+			line: 1,
+			message: `Static asset \`${rel}\` has no build meaning in a section bundle yet.`,
+			fix: "Binary assets are not supported in a section folder yet. Inline the graphic as SVG markup."
+		});
+	}
+	return out;
+}
+function asSchema(loaded) {
+	return typeof loaded.schema === "object" && loaded.schema !== null ? loaded.schema : {};
+}
+function checkSlotMarkers(workspaceRoot, template, section, loaded, jsxFiles) {
+	const slots = asSchema(loaded).slots ?? {};
+	const out = [];
+	const rendererFile = relative(workspaceRoot, join(section.dir, "Renderer.tsx"));
+	for (const [slot, spec] of Object.entries(slots)) {
+		if (spec.editable_by_user === false) continue;
+		const re = new RegExp(`(<Slot\\s+(?:[^>]*\\s+)?id|data-slot-id|slotId)\\s*=\\s*["']${escapeRegExp(slot)}["']`);
+		if (jsxFiles.some((f) => re.test(f.text))) continue;
+		out.push({
+			ruleId: "template-kit/missing-slot-marker",
+			template: template.key,
+			section: section.name,
+			file: rendererFile,
+			message: `Slot "${slot}" (editable_by_user: true) declared in schema.ts has no matching \`data-slot-id="${slot}"\` or \`slotId="${slot}"\` marker anywhere in the bundle.`,
+			fix: `Mark the slot in Renderer.tsx: <Slot id="${slot}">. The id must be a string literal.`
+		});
+	}
+	return out;
+}
+function checkSlotGroupMarkers(workspaceRoot, template, section, loaded, jsxFiles) {
+	const groups = asSchema(loaded).meta?.groups ?? [];
+	const out = [];
+	const rendererFile = relative(workspaceRoot, join(section.dir, "Renderer.tsx"));
+	for (const group of groups) {
+		if (flattenLayout(group.members).length < 2) continue;
+		const re = new RegExp(`<SlotGroup\\s+(?:[^>]*\\s+)?id\\s*=\\s*["']${escapeRegExp(group.id)}["']`);
+		if (jsxFiles.some((f) => re.test(f.text))) continue;
+		out.push({
+			ruleId: "template-kit/slot-group-marker",
+			template: template.key,
+			section: section.name,
+			file: rendererFile,
+			message: `Group "${group.id}" in schema.ts has no matching <SlotGroup id="${group.id}"> anywhere in the bundle.`,
+			fix: `Wrap the group's slots in <SlotGroup id="${group.id}"> so the editor can present them together.`
+		});
+	}
+	return out;
+}
+async function checkSectionCss(workspaceRoot, template, section) {
+	const out = [];
+	for (const cssFile of await sectionCssFiles(section.dir)) {
+		const rel = relative(workspaceRoot, cssFile);
+		const text = await readFile(cssFile, "utf8");
+		if (!opensWithCssReason(text)) out.push({
+			ruleId: "template-kit/css-reason",
+			template: template.key,
+			section: section.name,
+			file: rel,
+			line: 1,
+			message: `${rel} must open with a \`css-reason:\` comment justifying the hand-CSS.`,
+			fix: "Open the file with a comment saying why it exists: /* css-reason: … */"
+		});
+		for (const m of text.matchAll(/\/\*\s*unlayered:\s*([^*]*)\*\//g)) {
+			if ((m[1] ?? "").trim() !== "") continue;
+			out.push({
+				ruleId: "template-kit/unlayered-fence",
+				template: template.key,
+				section: section.name,
+				file: rel,
+				line: text.slice(0, m.index).split("\n").length,
+				message: `${rel}: an \`/* unlayered: */\` fence must state why it escapes the cascade layers.`,
+				fix: "Give the fence a reason (/* unlayered: … */) and close it with /* endunlayered */."
+			});
+		}
+		const opens = (text.match(/\/\*\s*unlayered:\s*[^*]*\*\//g) ?? []).length;
+		const closes = (text.match(/\/\*\s*endunlayered\s*\*\//g) ?? []).length;
+		if (opens !== closes) out.push({
+			ruleId: "template-kit/unlayered-fence",
+			template: template.key,
+			section: section.name,
+			file: rel,
+			line: 1,
+			message: `${rel}: each \`/* unlayered: <reason> */\` needs a matching \`/* endunlayered */\` (found ${String(opens)} open, ${String(closes)} close).`,
+			fix: "Give the fence a reason (/* unlayered: … */) and close it with /* endunlayered */."
+		});
+		const importLine = findImportLine(text);
+		if (importLine !== void 0) out.push({
+			ruleId: "template-kit/no-bare-css-import",
+			template: template.key,
+			section: section.name,
+			file: rel,
+			line: importLine,
+			message: `${rel}:${String(importLine)} — @import is not allowed in hand-CSS; the browser drops it silently and the rules never reach the page.`,
+			fix: "Import package CSS from the code that needs it: import \"swiper/css\" in Renderer.tsx, and the build routes it into this layer for you."
+		});
+	}
+	return out;
+}
+/** The tree-level rules for one template: every static, cross-file section-folder invariant ESLint cannot express. */
+async function treeStage(workspaceRoot, template) {
+	const diagnostics = [];
+	for (const section of template.sections) {
+		diagnostics.push(...await checkBundleAnatomy(workspaceRoot, template, section));
+		let loaded;
+		try {
+			loaded = await loadSection(workspaceRoot, section);
+		} catch {
+			loaded = void 0;
+		}
+		const jsxPaths = await bundleJsxFiles(section.dir);
+		if (loaded !== void 0 && jsxPaths.length > 0) {
+			const jsxFiles = await Promise.all(jsxPaths.map(async (abs) => ({ text: await readFile(abs, "utf8") })));
+			diagnostics.push(...checkSlotMarkers(workspaceRoot, template, section, loaded, jsxFiles));
+			diagnostics.push(...checkSlotGroupMarkers(workspaceRoot, template, section, loaded, jsxFiles));
+		}
+		diagnostics.push(...await checkSectionCss(workspaceRoot, template, section));
+	}
+	return diagnostics;
+}
+
+//#endregion
+export { treeStage };

package/dist/cli/check/stages/typecheck.js

@@ -0,0 +1,46 @@
+import { resolveFromWorkspace } from "../resolve-tool.js";
+import { isUnder, sectionOf } from "../paths.js";
+import { relativizePaths } from "../relativize.js";
+import { join, relative } from "node:path";
+
+//#region src/cli/check/stages/typecheck.ts
+const CONFIG_FIX_HINT = "Fix tsconfig.json. It must extend the kit preset: \"extends\": \"@homepages/template-kit/tsconfig\".";
+async function typecheckStage(workspaceRoot, template) {
+	const ts = await resolveFromWorkspace(workspaceRoot, "typescript");
+	const configPath = join(workspaceRoot, "tsconfig.json");
+	const configFile = ts.readConfigFile(configPath, (file) => ts.sys.readFile(file));
+	if (configFile.error) throw new Error(`could not read ${configPath}: ${ts.flattenDiagnosticMessageText(configFile.error.messageText, " ")}`);
+	const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, workspaceRoot);
+	const out = [];
+	for (const configError of parsed.errors) out.push({
+		ruleId: "template-kit/typecheck",
+		template: template.key,
+		file: relative(workspaceRoot, configPath),
+		message: relativizePaths(ts.flattenDiagnosticMessageText(configError.messageText, " "), workspaceRoot),
+		fix: CONFIG_FIX_HINT
+	});
+	const program = ts.createProgram({
+		rootNames: parsed.fileNames,
+		options: parsed.options,
+		configFileParsingDiagnostics: parsed.errors
+	});
+	const tsDiagnostics = [...program.getSyntacticDiagnostics(), ...program.getSemanticDiagnostics()];
+	for (const diagnostic of tsDiagnostics) {
+		if (!diagnostic.file) continue;
+		const fileName = diagnostic.file.fileName;
+		if (!isUnder(template.dir, fileName)) continue;
+		out.push({
+			ruleId: "template-kit/typecheck",
+			template: template.key,
+			section: sectionOf(template, fileName),
+			file: relative(workspaceRoot, fileName),
+			line: diagnostic.start === void 0 ? void 0 : ts.getLineAndCharacterOfPosition(diagnostic.file, diagnostic.start).line + 1,
+			message: relativizePaths(ts.flattenDiagnosticMessageText(diagnostic.messageText, " "), workspaceRoot),
+			fix: "Fix the type error. Section props are derived from schema.ts — never hand-written."
+		});
+	}
+	return out;
+}
+
+//#endregion
+export { typecheckStage };

package/dist/cli/check/stages/validate/catalog-exhaustiveness.js

@@ -0,0 +1,18 @@
+import { SLOT_TYPES } from "../../../../contracts/slot-catalog.js";
+import { SlotDef } from "../../../../schema/slot-types.js";
+
+//#region src/cli/check/stages/validate/catalog-exhaustiveness.ts
+function assertCatalogExhaustiveness() {
+	const unionTypes = /* @__PURE__ */ new Set();
+	const union = SlotDef._def.getter?.() ?? SlotDef;
+	for (const option of union.options) {
+		const typeSchema = option.shape.type;
+		unionTypes.add(typeSchema.value);
+	}
+	const catalog = new Set(SLOT_TYPES);
+	for (const t of catalog) if (!unionTypes.has(t)) throw new Error(`slot-catalog SLOT_TYPES has "${t}" but section-schema SlotDef has no matching Zod variant.`);
+	for (const t of unionTypes) if (!catalog.has(t)) throw new Error(`section-schema SlotDef has a "${t}" variant not in slot-catalog SLOT_TYPES.`);
+}
+
+//#endregion
+export { assertCatalogExhaustiveness };

package/dist/cli/check/stages/validate/facts.js

@@ -0,0 +1,18 @@
+//#region src/cli/check/stages/validate/facts.ts
+const FACTS_ARRAY_FIELDS = /* @__PURE__ */ new Set([
+	"units",
+	"photos",
+	"floor_plans",
+	"pois",
+	"contacts"
+]);
+const FACTS_READABLE = /* @__PURE__ */ new Set([
+	"extras",
+	"tours",
+	"floor_plans",
+	"photos",
+	"pois"
+]);
+
+//#endregion
+export { FACTS_ARRAY_FIELDS, FACTS_READABLE };

package/dist/cli/check/stages/validate/formatter-contract.js

@@ -0,0 +1,14 @@
+import { FORMATTER_NAMES } from "../../../../contracts/slot-catalog.js";
+
+//#region src/cli/check/stages/validate/formatter-contract.ts
+function assertFormatterContract(schema) {
+	for (const [name, slot] of Object.entries(schema.slots)) {
+		const fmt = slot.format;
+		if (fmt == null) continue;
+		const fn = typeof fmt === "string" ? fmt : fmt.fn;
+		if (typeof fn !== "string" || !FORMATTER_NAMES.includes(fn)) throw new Error(`${schema.key}.${name}: unknown formatter "${String(fn)}" (allowed: ${FORMATTER_NAMES.join(", ")})`);
+	}
+}
+
+//#endregion
+export { assertFormatterContract };

package/dist/cli/check/stages/validate/group-contract.js

@@ -0,0 +1,21 @@
+import { flattenLayout } from "../../../../schema/rows.js";
+
+//#region src/cli/check/stages/validate/group-contract.ts
+function assertGroupContract(schema, sectionKey) {
+	const groups = schema.groups;
+	if (!groups || groups.length === 0) return;
+	const seenIds = /* @__PURE__ */ new Set();
+	const seenSlots = /* @__PURE__ */ new Set();
+	for (const group of groups) {
+		if (seenIds.has(group.id)) throw new Error(`Section "${sectionKey}": duplicate group id "${group.id}".`);
+		seenIds.add(group.id);
+		for (const member of flattenLayout(group.members)) {
+			if (!(member in schema.slots)) throw new Error(`Section "${sectionKey}": group "${group.id}" names unknown slot "${member}".`);
+			if (seenSlots.has(member)) throw new Error(`Section "${sectionKey}": slot "${member}" appears in more than one group.`);
+			seenSlots.add(member);
+		}
+	}
+}
+
+//#endregion
+export { assertGroupContract };