@homepages/template-kit 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @homepages/template-kit
 
+## 0.4.0
+
+### Minor Changes
+
+- 94d6458: `template-kit dev`: a full-template published page at `/template/<t>`, scope-aware
+  `/api/screenshot` (section or whole template, with `width`), and a new `/api/inspect`
+  endpoint returning per-slot fill-state (filled / empty / missing + a render
+  cross-check), resolved props, and the null-corpus. Retires `/api/structure-summary`
+  (its outline is now `/api/inspect?format=text`).
+- 47dbbc6: Section-folder static assets are now first-class. `check`'s `bundle-binary-asset` rule
+  flags only an _unreferenced_ binary in a section folder; an asset imported in a component
+  (`import crest from "./assets/crest.svg"` → `<Image src={crest} …>`) or `url()`-referenced
+  from a section stylesheet is allowed. A `declare module "*.svg"` (and the other supported
+  asset extensions) type shim ships so component imports of assets typecheck.
+- 9a3e0e1: Adds a read-only canvas mirror to `template-kit dev`, at `/canvas/<template>`. It frames
+  the **whole template** — every section instance, stacked in one scroll container, exactly
+  as the deliverable renders — in an iframe and paints a hover/select overlay on top: click
+  an editable slot to select it (a gold ring), hover to preview it (a blue ring);
+  non-editable regions select their enclosing section instead. Selection is scoped per
+  section instance, so the same slot name in two sections resolves independently. The
+  overlay is purely visual — it never alters the rendered markup. A mode toggle switches to
+  a clean published render of the full template with no overlay, and the current view —
+  template, mode, and the selected instance/slot — is captured in the URL, so a canvas link
+  reloads and shares exactly what you see.
+
+  The `dev` server gains `GET /api/template-schema?template=<t>`, returning each section
+  instance's editability map (per slot: its type and whether it is user-editable) for the
+  whole template, so a tool can tell which slots are selectable without re-parsing the
+  section schemas. (The per-section `/api/render` response also still carries its own
+  `slotSchema` map.)
+
+- 7f68570: Canvas mirror: exercise slots interactively. Selecting an editable slot opens a
+  side panel with a JSON editor for its value; applying a change re-renders that
+  section instance live. A per-instance fixture picker drives different content —
+  including the empty/missing states from the section's fixture corpus — without
+  editing fixture files.
+- 5a8dcd4: Adds the `dev` command: `template-kit dev [template] [--port <n>]`. A local preview
+  server for a workspace's templates — it renders every section against its fixtures
+  server-side, with the template's theme and compiled Tailwind utilities, exactly the way
+  the platform does. A browser UI gives you a picker (template → section → fixture) and a
+  grid contact sheet of every fixture at each breakpoint, including empty and null states;
+  each section also has a standalone preview at `/sections/<template>/<section>/<fixture>`.
+  Editing a section reloads open previews; editing a theme hot-swaps its stylesheet.
+
+  Endpoints render a section without a browser, for an agent verifying its work from a
+  terminal: `/api/inspect` (a low-context per-slot fill-state view as JSON, with
+  `?format=text` for the rendered outline) and `/api/screenshot` (a full-page PNG). Like
+  `check`, `dev` runs your
+  toolchain — Vite and Tailwind resolved from your workspace, not shipped by the kit:
+
+  ```bash
+  npm i -D vite @vitejs/plugin-react tailwindcss @tailwindcss/cli
+  npm i -D @playwright/test   # optional, for /api/screenshot
+  ```
+
+- 13c3132: Add `template-kit pack <template>` — the per-template submission zip (template
+  source + workspace lockfile + a stamped `pack-manifest.json`), which refuses on a
+  failing `check`, an active link overlay, a missing lockfile, or local-protocol
+  deps. Add the internal `link`/`unlink`/`status` overlay for developing the kit
+  against a real consumer without publishing.
+- bcf6fbb: `@homepages/template-kit/ssr` now also exports `wrapClientModuleSource` (the `"use
+client"` → `IslandMarker` codemod), `findSectionIslands` (recursive `"use client"`
+  component discovery under a section directory), and `islandTransformEsbuildPlugin`
+  (an esbuild `onLoad` plugin that applies the same codemod across a build graph, keyed
+  `islandKey(sectionKey, <file-basename>)`). All three are the same primitives
+  `template-kit dev`'s Vite plugin already used internally, now exposed so a build-time
+  consumer — the publish renderer bundle's esbuild pass, or a native-import loader hook —
+  can wrap island modules identically without duplicating the codemod. `esbuild` stays a
+  devDependency of the kit; `islandTransformEsbuildPlugin` imports its `Plugin` type only.
+- b76f822: Add the node-only `@homepages/template-kit/ssr` subpath: the shared section SSR helper (`loadSectionBundle`, `renderSectionHtml`) that renders a section + fixture to the exact HTML the publisher emits, plus island detection (`isClientComponentFile`, `hasClientDirective`) and key derivation (`islandKey`) for a section's `"use client"` components.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -6,10 +6,26 @@ contract primitives, the theme system, and the `template-kit` CLI.
 **Status: 0.0.x.** The **schema system** (the section authoring contract and the closed
 vocabulary it validates against), the **contract primitives**, and the **theme system**
 are complete — a section is authorable end to end against the kit. The `template-kit`
-CLI's `check` and `theme` commands are implemented — see
-[Checking a workspace](#checking-a-workspace) and
-[Generating a theme](#generating-a-theme) below; its other commands arrive with the
-surfaces they drive.
+CLI's `check`, `theme`, `dev`, and `pack` commands are implemented — see
+[Checking a workspace](#checking-a-workspace), [Generating a theme](#generating-a-theme),
+and [Previewing a workspace](#previewing-a-workspace) below — and `new` / `new-section`
+scaffold a template or a section into a workspace (see [docs/new.md](docs/new.md)).
+
+## Quick start
+
+The fastest way to start is the workspace scaffolder — it creates a workspace with a
+working starter template and the full toolchain already wired:
+
+```bash
+npm create homepages-workspace <name>
+cd <name>
+npm install
+npm run dev        # preview the starter; the island hydrates
+```
+
+Add more templates with `npx template-kit new <template>` and sections with
+`npx template-kit new-section <template>/<section>` — see [docs/new.md](docs/new.md).
+Prefer to wire a workspace by hand? See **Install** below.
 
 ## Install
 
@@ -119,6 +135,25 @@ Tailwind entry imports. The output is generated: don't hand-edit it, and re-run
 command whenever `theme.ts` changes. Full contract:
 **[docs/theme-and-css.md](docs/theme-and-css.md#generating-themecss)**.
 
+## Previewing a workspace
+
+```bash
+template-kit dev              # serve every template in the workspace
+template-kit dev <template>   # preselect one template in the picker
+template-kit dev --port 4000  # choose the port (default 5180)
+```
+
+`dev` starts a local server that renders every section against its fixtures the same way
+the platform does — with your template's theme and compiled Tailwind — and reloads as you
+edit. A browser UI gives you a picker and a grid contact sheet across breakpoints; each
+section also has a standalone page, and so does the whole template at
+`/template/<template>`. Three endpoints let an agent verify a render from a terminal:
+`/api/inspect` (per-slot fill-state as JSON), `/api/render` (the full structured render
+payload), and `/api/screenshot` (a full-page PNG, section or whole template). Like
+`check`, it runs **your** toolchain — Vite and Tailwind resolved from your workspace,
+installed with `npm i -D vite @vitejs/plugin-react tailwindcss @tailwindcss/cli` — not
+shipped by the kit. Full contract: **[docs/dev.md](docs/dev.md)**.
+
 ## Checking a workspace
 
 ```bash

package/dist/asset-modules.d.ts

@@ -0,0 +1,81 @@
+//#region src/asset-modules.d.ts
+declare module "*.svg" {
+  const src: string;
+  export default src;
+}
+declare module "*.png" {
+  const src: string;
+  export default src;
+}
+declare module "*.jpg" {
+  const src: string;
+  export default src;
+}
+declare module "*.jpeg" {
+  const src: string;
+  export default src;
+}
+declare module "*.gif" {
+  const src: string;
+  export default src;
+}
+declare module "*.webp" {
+  const src: string;
+  export default src;
+}
+declare module "*.avif" {
+  const src: string;
+  export default src;
+}
+declare module "*.ico" {
+  const src: string;
+  export default src;
+}
+declare module "*.woff" {
+  const src: string;
+  export default src;
+}
+declare module "*.woff2" {
+  const src: string;
+  export default src;
+}
+declare module "*.ttf" {
+  const src: string;
+  export default src;
+}
+declare module "*.otf" {
+  const src: string;
+  export default src;
+}
+declare module "*.eot" {
+  const src: string;
+  export default src;
+}
+declare module "*.mp4" {
+  const src: string;
+  export default src;
+}
+declare module "*.webm" {
+  const src: string;
+  export default src;
+}
+declare module "*.mov" {
+  const src: string;
+  export default src;
+}
+declare module "*.mp3" {
+  const src: string;
+  export default src;
+}
+declare module "*.wav" {
+  const src: string;
+  export default src;
+}
+declare module "*.pdf" {
+  const src: string;
+  export default src;
+}
+declare module "*.zip" {
+  const src: string;
+  export default src;
+}

package/dist/cli/check/config.js

@@ -4,7 +4,11 @@ const CHECK_CONFIG = {
 		/** Gzipped bytes of a section's renderer bundle, React excluded. */
 		rendererBundleGzip: 50 * 1024,
 		/** Gzipped bytes of a section's stylesheet, including CSS pulled in from packages. */
-		sectionCssGzip: 50 * 1024
+		sectionCssGzip: 50 * 1024,
+		/** Gzipped bytes of a section's largest island (browser) bundle, React excluded. */
+		islandBundleGzip: 50 * 1024,
+		/** Raw bytes of a section's static assets (svg/images/fonts). RAW, not gzip — images/fonts are already compressed. */
+		assets: 250 * 1024
 	},
 	audit: { 
 	/** A vulnerability at or above this severity fails the check. */

package/dist/cli/check/css.js

@@ -28,18 +28,30 @@ async function sectionCssFiles(dir) {
 	const rest = found.filter((f) => f !== own).sort();
 	return (existsSync(own) ? [own] : []).concat(rest);
 }
-const CSS_ASSET_LOADERS = {
-	".svg": "dataurl",
-	".png": "dataurl",
-	".jpg": "dataurl",
-	".jpeg": "dataurl",
-	".gif": "dataurl",
-	".webp": "dataurl",
-	".woff": "dataurl",
-	".woff2": "dataurl",
-	".ttf": "dataurl",
-	".eot": "dataurl"
+const ASSET_LOADERS = {
+	".svg": "file",
+	".png": "file",
+	".jpg": "file",
+	".jpeg": "file",
+	".gif": "file",
+	".webp": "file",
+	".avif": "file",
+	".ico": "file",
+	".woff": "file",
+	".woff2": "file",
+	".ttf": "file",
+	".otf": "file",
+	".eot": "file",
+	".mp4": "file",
+	".webm": "file",
+	".mov": "file",
+	".mp3": "file",
+	".wav": "file",
+	".pdf": "file",
+	".zip": "file"
 };
+const ASSET_PUBLIC_PATH = "/section-assets";
+const ASSET_NAMES = "[name]-[hash]";
 /**
 * A section's third-party package CSS — discovered by the bundler, not
 * declared. An author writes `import "swiper/css"` in Renderer.tsx exactly
@@ -75,7 +87,9 @@ async function compileSectionPackageCss(workspaceRoot, sectionDir) {
 			"react-dom",
 			"react/jsx-runtime"
 		],
-		loader: { ...CSS_ASSET_LOADERS },
+		loader: { ...ASSET_LOADERS },
+		publicPath: ASSET_PUBLIC_PATH,
+		assetNames: ASSET_NAMES,
 		absWorkingDir: workspaceRoot,
 		logLevel: "silent"
 	})).outputFiles?.find((f) => f.path.endsWith(".css"));
@@ -114,4 +128,4 @@ function findImportLine(css) {
 }
 
 //#endregion
-export { CSS_ASSET_LOADERS, compileSectionPackageCss, findImportLine, sectionCssFiles };
+export { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH, compileSectionPackageCss, findImportLine, sectionCssFiles };

package/dist/cli/check/loader.js

@@ -1,4 +1,5 @@
 import { loadEsbuild } from "./resolve-tool.js";
+import { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH } from "./css.js";
 import { join, relative } from "node:path";
 import { createHash } from "node:crypto";
 import { mkdir, rm, stat } from "node:fs/promises";
@@ -121,6 +122,9 @@ async function buildAndLoad(section, outdir, workspaceRoot) {
 		jsx: "automatic",
 		logLevel: "silent",
 		plugins: [cssStub],
+		loader: { ...ASSET_LOADERS },
+		publicPath: ASSET_PUBLIC_PATH,
+		assetNames: ASSET_NAMES,
 		absWorkingDir: workspaceRoot
 	});
 	const load = async (source, emitted) => {

package/dist/cli/check/section-assets.js

@@ -0,0 +1,58 @@
+import { loadEsbuild } from "./resolve-tool.js";
+import { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH, sectionCssFiles } from "./css.js";
+import { isUnder } from "./paths.js";
+import { extname, join, resolve } from "node:path";
+
+//#region src/cli/check/section-assets.ts
+const ASSET_EXTS = new Set(Object.keys(ASSET_LOADERS));
+async function referencedSectionAssets(workspaceRoot, section) {
+	const { build } = await loadEsbuild(workspaceRoot);
+	const referenced = /* @__PURE__ */ new Set();
+	const collect = (inputs) => {
+		for (const key of Object.keys(inputs ?? {})) {
+			const abs = resolve(workspaceRoot, key);
+			if (ASSET_EXTS.has(extname(abs).toLowerCase()) && isUnder(section.dir, abs)) referenced.add(abs);
+		}
+	};
+	collect((await build({
+		entryPoints: [join(section.dir, "Renderer.tsx")],
+		bundle: true,
+		write: false,
+		metafile: true,
+		format: "esm",
+		platform: "browser",
+		jsx: "automatic",
+		outdir: "dist",
+		external: [
+			"react",
+			"react-dom",
+			"react-dom/server",
+			"react/jsx-runtime",
+			"react/jsx-dev-runtime"
+		],
+		loader: { ...ASSET_LOADERS },
+		publicPath: ASSET_PUBLIC_PATH,
+		assetNames: ASSET_NAMES,
+		absWorkingDir: workspaceRoot,
+		logLevel: "silent"
+	})).metafile?.inputs);
+	for (const cssFile of await sectionCssFiles(section.dir)) collect((await build({
+		entryPoints: [cssFile],
+		bundle: true,
+		write: false,
+		metafile: true,
+		outdir: "dist",
+		loader: {
+			".css": "css",
+			...ASSET_LOADERS
+		},
+		publicPath: ASSET_PUBLIC_PATH,
+		assetNames: ASSET_NAMES,
+		absWorkingDir: workspaceRoot,
+		logLevel: "silent"
+	})).metafile?.inputs);
+	return referenced;
+}
+
+//#endregion
+export { referencedSectionAssets };

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

@@ -1,8 +1,9 @@
 import { loadEsbuild } from "../resolve-tool.js";
+import { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH, compileSectionPackageCss, sectionCssFiles } from "../css.js";
 import { CHECK_CONFIG } from "../config.js";
-import { compileSectionPackageCss, sectionCssFiles } from "../css.js";
+import { findSectionIslands } from "../../../islands/discover.js";
 import { existsSync } from "node:fs";
-import { join, relative } from "node:path";
+import { basename, join, relative } from "node:path";
 import { readFile } from "node:fs/promises";
 import { gzipSync } from "node:zlib";
 
@@ -104,10 +105,10 @@ async function measureRendererBundle(workspaceRoot, section) {
 /**
 * 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.
+* code pulls in (`compileSectionPackageCss`). A package's `url()`-referenced
+* fonts and icons no longer inline into this text — they resolve to
+* `/section-assets/` references (see css.ts), and their bytes are measured
+* separately by `measureAssetBytes`, the `size-assets` dimension below.
 */
 async function measureSectionCss(workspaceRoot, section) {
 	const ownFiles = await sectionCssFiles(section.dir);
@@ -115,6 +116,101 @@ async function measureSectionCss(workspaceRoot, section) {
 	const packageCss = await compileSectionPackageCss(workspaceRoot, section.dir);
 	return gzipSync(Buffer.from(`${own}\n${packageCss}`)).byteLength;
 }
+/**
+* Raw bytes of a section's static assets — the fourth size dimension. Fonts and
+* images are already compressed, so this is RAW bytes, not gzip. Two esbuild
+* passes with the file loader capture every asset the published section emits:
+*   1. Renderer.tsx (bundled) — assets imported in JS AND assets url()-referenced
+*      by the package CSS the renderer pulls in.
+*   2. each hand-written stylesheet — its @font-face / url() assets (the author's
+*      own styles.css is read raw by the CSS budget, never bundled, so its assets
+*      surface only here).
+* Deduped by emitted (content-hashed) filename, so an asset referenced twice or
+* from both a stylesheet and JS is counted once.
+*/
+async function measureAssetBytes(workspaceRoot, section) {
+	const { build } = await loadEsbuild(workspaceRoot);
+	const byName = /* @__PURE__ */ new Map();
+	const collect = (outputFiles) => {
+		for (const f of outputFiles) {
+			if (/\.(?:js|css|map)$/i.test(f.path)) continue;
+			byName.set(basename(f.path), f.contents.byteLength);
+		}
+	};
+	collect((await build({
+		entryPoints: [join(section.dir, "Renderer.tsx")],
+		bundle: true,
+		write: false,
+		format: "esm",
+		platform: "browser",
+		jsx: "automatic",
+		outdir: "dist",
+		external: [
+			"react",
+			"react-dom",
+			"react-dom/server",
+			"react/jsx-runtime",
+			"react/jsx-dev-runtime"
+		],
+		loader: { ...ASSET_LOADERS },
+		publicPath: "/section-assets",
+		assetNames: "[name]-[hash]",
+		absWorkingDir: workspaceRoot,
+		logLevel: "silent"
+	})).outputFiles ?? []);
+	for (const cssFile of await sectionCssFiles(section.dir)) collect((await build({
+		entryPoints: [cssFile],
+		bundle: true,
+		write: false,
+		outdir: "dist",
+		loader: {
+			".css": "css",
+			...ASSET_LOADERS
+		},
+		publicPath: "/section-assets",
+		assetNames: "[name]-[hash]",
+		absWorkingDir: workspaceRoot,
+		logLevel: "silent"
+	})).outputFiles ?? []);
+	return [...byName.values()].reduce((sum, n) => sum + n, 0);
+}
+/**
+* Gzipped bytes of a section's largest island (browser) bundle. Each "use client"
+* component is bundled as its own browser entry, React external (the runtime chunk
+* provides it), everything else bundled — the shape ci/static-assets.ts uploads.
+* Returns 0 for a section with no islands. Uses `sizeStub` (React-only external),
+* NOT the loader's cssStub — see the file header.
+*/
+async function measureIslandBundle(workspaceRoot, section) {
+	const islands = await findSectionIslands(section.dir);
+	if (islands.length === 0) return 0;
+	const { build } = await loadEsbuild(workspaceRoot);
+	let max = 0;
+	for (const entry of islands) {
+		const js = (await build({
+			entryPoints: [entry],
+			bundle: true,
+			minify: true,
+			format: "esm",
+			platform: "browser",
+			jsx: "automatic",
+			write: false,
+			outfile: "island.js",
+			external: [
+				"react",
+				"react-dom",
+				"react-dom/client",
+				"react/jsx-runtime",
+				"react/jsx-dev-runtime"
+			],
+			plugins: [sizeStub],
+			absWorkingDir: workspaceRoot,
+			logLevel: "silent"
+		})).outputFiles.find((f) => f.path.endsWith(".js"));
+		if (js) max = Math.max(max, gzipSync(js.contents).byteLength);
+	}
+	return max;
+}
 function kb(bytes) {
 	const value = bytes / 1024;
 	return `${Number.isInteger(value) ? value.toString() : value.toFixed(1)} KB`;
@@ -128,9 +224,13 @@ async function sizeStage(workspaceRoot, template) {
 	for (const section of template.sections) {
 		let rendererBytes;
 		let cssBytes;
+		let islandBytes;
+		let assetBytes;
 		try {
 			rendererBytes = await measureRendererBundle(workspaceRoot, section);
 			cssBytes = await measureSectionCss(workspaceRoot, section);
+			islandBytes = await measureIslandBundle(workspaceRoot, section);
+			assetBytes = await measureAssetBytes(workspaceRoot, section);
 		} catch {
 			continue;
 		}
@@ -148,11 +248,27 @@ async function sizeStage(workspaceRoot, template) {
 			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."
+			fix: "Trim the stylesheet. Pulling in a package's full 'everything' CSS bundle when you use a few of its modules is the usual cause — import only the modules you use. (A url()-referenced font or icon set is measured separately, under size-assets.)"
+		});
+		if (islandBytes > CHECK_CONFIG.size.islandBundleGzip) diagnostics.push({
+			ruleId: "template-kit/size-island-bundle",
+			template: template.key,
+			section: section.name,
+			file: `templates/${template.key}/sections/${section.name}`,
+			message: `an island bundle is ${kb(islandBytes)} gzip — over the ${kb(CHECK_CONFIG.size.islandBundleGzip)} budget`,
+			fix: "Trim what the client component pulls in. A whole UI/icon library imported for one widget is the usual cause — import only what you use, or split the island."
+		});
+		if (assetBytes > CHECK_CONFIG.size.assets) diagnostics.push({
+			ruleId: "template-kit/size-assets",
+			template: template.key,
+			section: section.name,
+			file: `templates/${template.key}/sections/${section.name}`,
+			message: `static assets are ${kb(assetBytes)} — over the ${kb(CHECK_CONFIG.size.assets)} budget`,
+			fix: "Shrink or subset the asset (a full font family or an unoptimized image is the usual cause), or drop assets the section does not use."
 		});
 	}
 	return diagnostics;
 }
 
 //#endregion
-export { measureRendererBundle, measureSectionCss, sizeStage };
+export { measureAssetBytes, measureIslandBundle, measureRendererBundle, measureSectionCss, sizeStage };

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

@@ -1,32 +1,12 @@
+import { ASSET_LOADERS, findImportLine, sectionCssFiles } from "../css.js";
 import { CONTRACT_FILES, loadSection } from "../loader.js";
 import { flattenLayout } from "../../../schema/rows.js";
-import { findImportLine, sectionCssFiles } from "../css.js";
+import { referencedSectionAssets } from "../section-assets.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"
-]);
+const ASSET_EXTENSIONS = new Set(Object.keys(ASSET_LOADERS));
 async function isBinaryFile(file) {
 	return (await readFile(file)).subarray(0, 4096).includes(0);
 }
@@ -75,17 +55,35 @@ async function checkBundleAnatomy(workspaceRoot, template, section) {
 			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)) {
+	return out;
+}
+/** A section-folder file that is an asset by extension or by a NUL-byte sniff. */
+async function sectionAssetFiles(dir) {
+	const out = [];
+	for (const abs of await bundleFiles(dir)) if (ASSET_EXTENSIONS.has(extname(abs).toLowerCase()) || await isBinaryFile(abs)) out.push(abs);
+	return out;
+}
+async function checkOrphanAssets(workspaceRoot, template, section) {
+	const candidates = await sectionAssetFiles(section.dir);
+	if (candidates.length === 0) return [];
+	let referenced;
+	try {
+		referenced = await referencedSectionAssets(workspaceRoot, section);
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const abs of candidates) {
+		if (referenced.has(abs)) continue;
 		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."
+			message: `Static asset \`${rel}\` sits in the section folder but nothing references it.`,
+			fix: "Reference it (import it in Renderer.tsx, or url() it from the section's CSS), or delete it. An unreferenced binary bloats the section's content hash and is never served."
 		});
 	}
 	return out;
@@ -186,6 +184,7 @@ async function treeStage(workspaceRoot, template) {
 	const diagnostics = [];
 	for (const section of template.sections) {
 		diagnostics.push(...await checkBundleAnatomy(workspaceRoot, template, section));
+		diagnostics.push(...await checkOrphanAssets(workspaceRoot, template, section));
 		let loaded;
 		try {
 			loaded = await loadSection(workspaceRoot, section);