npm - @homepages/template-kit - Versions diffs - 0.3.0 → 0.4.1 - Mend

@homepages/template-kit 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (109) hide show

package/CHANGELOG.md +84 -0
package/README.md +39 -4
package/dist/asset-modules.d.ts +81 -0
package/dist/cli/check/config.js +5 -1
package/dist/cli/check/css.js +27 -13
package/dist/cli/check/loader.js +4 -0
package/dist/cli/check/section-assets.js +58 -0
package/dist/cli/check/stages/size.js +124 -8
package/dist/cli/check/stages/tree.js +26 -27
package/dist/cli/dev/build-css.js +91 -0
package/dist/cli/dev/catalog.js +35 -0
package/dist/cli/dev/compose-template.js +38 -0
package/dist/cli/dev/content-override.js +58 -0
package/dist/cli/dev/discover.js +35 -0
package/dist/cli/dev/fill-state.js +75 -0
package/dist/cli/dev/index.js +32 -0
package/dist/cli/dev/inspect.js +38 -0
package/dist/cli/dev/island-bootstrap.js +38 -0
package/dist/cli/dev/island-map.js +35 -0
package/dist/cli/dev/island-transform.js +31 -0
package/dist/cli/dev/manifest-instances.js +31 -0
package/dist/cli/dev/render-section.js +24 -0
package/dist/cli/dev/screenshot-target.js +24 -0
package/dist/cli/dev/section-page.js +54 -0
package/dist/cli/dev/server.js +480 -0
package/dist/cli/dev/slot-schema.js +12 -0
package/dist/cli/dev/structure-summary.js +118 -0
package/dist/cli/dev/tailwind.js +32 -0
package/dist/cli/dev/vite-server.js +33 -0
package/dist/cli/dev/workspace.js +63 -0
package/dist/cli/link/index.js +74 -0
package/dist/cli/link/overlay.js +59 -0
package/dist/cli/link/watch.js +25 -0
package/dist/cli/new/emit.js +48 -0
package/dist/cli/new/index.js +69 -0
package/dist/cli/new/scaffold/section/_Renderer.tsx +20 -0
package/dist/cli/new/scaffold/section/_fill-spec.ts +18 -0
package/dist/cli/new/scaffold/section/_fixtures.ts +13 -0
package/dist/cli/new/scaffold/section/_schema.ts +24 -0
package/dist/cli/new/scaffold/template/_manifest.json +9 -0
package/dist/cli/new/scaffold/template/sections/hero/ExpandableText.tsx +45 -0
package/dist/cli/new/scaffold/template/sections/hero/Renderer.tsx +40 -0
package/dist/cli/new/scaffold/template/sections/hero/components/Feature.tsx +14 -0
package/dist/cli/new/scaffold/template/sections/hero/fill-spec.ts +29 -0
package/dist/cli/new/scaffold/template/sections/hero/fixtures.ts +41 -0
package/dist/cli/new/scaffold/template/sections/hero/schema.ts +60 -0
package/dist/cli/new/scaffold/template/theme.css +24 -0
package/dist/cli/new/scaffold/template/theme.ts +27 -0
package/dist/cli/new/scaffold-assets.js +20 -0
package/dist/cli/pack/collect.js +44 -0
package/dist/cli/pack/guards.js +57 -0
package/dist/cli/pack/index.js +66 -0
package/dist/cli/pack/manifest.js +15 -0
package/dist/cli/pack/zip.js +86 -0
package/dist/cli.js +80 -14
package/dist/dev-client/assets/index-DfEfrp6P.css +1 -0
package/dist/dev-client/assets/index-bpMP0b0W.js +50 -0
package/dist/dev-client/index.html +13 -0
package/dist/eslint/is-client-file.d.ts +4 -0
package/dist/index.d.ts +1 -0
package/dist/islands/detect.d.ts +16 -0
package/dist/islands/detect.js +22 -0
package/dist/islands/discover.d.ts +5 -0
package/dist/islands/discover.js +19 -0
package/dist/islands/esbuild-plugin.d.ts +13 -0
package/dist/islands/esbuild-plugin.js +39 -0
package/dist/islands/wrap.d.ts +12 -0
package/dist/islands/wrap.js +48 -0
package/dist/package.js +1 -1
package/dist/ssr.d.ts +31 -0
package/dist/ssr.js +46 -0
package/docs/INDEX.md +9 -1
package/docs/assets.md +128 -0
package/docs/check.md +6 -3
package/docs/dev.md +187 -0
package/docs/islands.md +5 -2
package/docs/llms.txt +41 -3
package/docs/new.md +27 -0
package/docs/overview.md +57 -0
package/docs/pack.md +46 -0
package/docs/primitives.md +5 -6
package/docs/quickstart.md +102 -0
package/docs/recipes/INDEX.md +27 -0
package/docs/recipes/bind-property-fact.md +58 -0
package/docs/recipes/collection-slot.md +100 -0
package/docs/recipes/fill-spec-decision.md +66 -0
package/docs/recipes/fixture-states.md +68 -0
package/docs/recipes/image-slot-crop.md +98 -0
package/docs/recipes/interactive-island.md +100 -0
package/docs/recipes/organize-section-folder.md +72 -0
package/docs/recipes/prepare-submission.md +55 -0
package/docs/recipes/second-template.md +49 -0
package/docs/recipes/select-slot.md +59 -0
package/docs/recipes/static-asset.md +103 -0
package/docs/recipes/third-party-package.md +90 -0
package/docs/rules/INDEX.md +4 -2
package/docs/rules/bundle-binary-asset.md +33 -52
package/docs/rules/bundle-incomplete.md +2 -2
package/docs/rules/css-reason.md +3 -3
package/docs/rules/no-bare-css-import.md +8 -8
package/docs/rules/no-css-import-from-render-path.md +7 -8
package/docs/rules/size-assets.md +88 -0
package/docs/rules/size-island-bundle.md +123 -0
package/docs/rules/size-section-css.md +19 -14
package/docs/schema-system.md +28 -28
package/docs/theme-and-css.md +2 -2
package/docs/vocabulary.md +98 -0
package/package.json +12 -3
package/tsconfig.json +1 -1

package/dist/dev-client/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>template-kit dev</title>
+    <script type="module" crossorigin src="/dev-client/assets/index-bpMP0b0W.js"></script>
+    <link rel="stylesheet" crossorigin href="/dev-client/assets/index-DfEfrp6P.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/eslint/is-client-file.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+//#region src/eslint/is-client-file.d.ts
+declare function hasClientDirective(text: string): boolean;
+//#endregion
+export { hasClientDirective };

package/dist/index.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import { ResponsiveImage, ResponsiveSource } from "./contracts/image-descriptor.js";
 import { Coordinates, FloorplanAssignment, PropertyFacts, UnitRow } from "./schema/property-facts.js";
+import "./asset-modules.js";
 import { COLLECTIONS, CONTENT_SLOT_TYPES, CollectionField, CollectionIdKey, CollectionOwnership, ContentSlotType, DECISION_TYPES, DERIVED_INPUT_FIELDS, DecisionType, DerivedInputName, FORMATTER_NAMES, FormatterName, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, RefSlotType, ReferralField, ReferralImageField, SLOT_TYPES, SOURCE_FIELDS, SlotType, SourceFieldContainer, SourceFieldDescriptor, SourceFieldName, SourceFieldValueType, WritebackTarget, collectionForSlot } from "./contracts/slot-catalog.js";
 import { AddressParts, TRANSFORMS, TRANSFORM_NAMES, TransformDescriptor, TransformFn, TransformInput, TransformName, TransformUnit } from "./contracts/transforms.js";
 import { VariantSelectorFn, VariantsMeta, makeResolveVariants } from "./schema/resolve-variants.js";

package/dist/islands/detect.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import { hasClientDirective } from "../eslint/is-client-file.js";
+//#region src/islands/detect.d.ts
+/**
+ * True iff `file` is a client component — an on-disk source file whose directive
+ * prologue is `"use client"`. Returns false for an unreadable or absent path.
+ */
+declare function isClientComponentFile(file: string): boolean;
+/**
+ * Compose an island key: `<sectionKey>:<componentName>` (e.g.
+ * `spw-essential/floorplan:UnitFilter`). The key is what a marker in the DOM
+ * carries and what the browser loader resolves the client module by, so the
+ * emitter and the loader must derive it identically.
+ */
+declare function islandKey(sectionKey: string, componentName: string): string;
+//#endregion
+export { hasClientDirective, isClientComponentFile, islandKey };

package/dist/islands/detect.js ADDED Viewed

@@ -0,0 +1,22 @@
+import { hasClientDirective, isClientFile } from "../eslint/is-client-file.js";
+//#region src/islands/detect.ts
+/**
+* True iff `file` is a client component — an on-disk source file whose directive
+* prologue is `"use client"`. Returns false for an unreadable or absent path.
+*/
+function isClientComponentFile(file) {
+	return isClientFile(file);
+}
+/**
+* Compose an island key: `<sectionKey>:<componentName>` (e.g.
+* `spw-essential/floorplan:UnitFilter`). The key is what a marker in the DOM
+* carries and what the browser loader resolves the client module by, so the
+* emitter and the loader must derive it identically.
+*/
+function islandKey(sectionKey, componentName) {
+	return `${sectionKey}:${componentName}`;
+}
+//#endregion
+export { hasClientDirective, isClientComponentFile, islandKey };

package/dist/islands/discover.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+//#region src/islands/discover.d.ts
+/** Every `"use client"` component file anywhere under a section directory (recursive). */
+declare function findSectionIslands(sectionDir: string): Promise<string[]>;
+//#endregion
+export { findSectionIslands };

package/dist/islands/discover.js ADDED Viewed

@@ -0,0 +1,19 @@
+import { isClientComponentFile } from "./detect.js";
+import { extname, join } from "node:path";
+import { readdir } from "node:fs/promises";
+//#region src/islands/discover.ts
+const COMPONENT_EXTS = /* @__PURE__ */ new Set([".tsx", ".jsx"]);
+/** Every `"use client"` component file anywhere under a section directory (recursive). */
+async function findSectionIslands(sectionDir) {
+	const out = [];
+	for (const entry of await readdir(sectionDir, { withFileTypes: true })) {
+		const full = join(sectionDir, entry.name);
+		if (entry.isDirectory()) out.push(...await findSectionIslands(full));
+		else if (COMPONENT_EXTS.has(extname(entry.name)) && isClientComponentFile(full)) out.push(full);
+	}
+	return out;
+}
+//#endregion
+export { findSectionIslands };

package/dist/islands/esbuild-plugin.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import { Plugin } from "esbuild";
+//#region src/islands/esbuild-plugin.d.ts
+/**
+ * Wrap every `"use client"` `.tsx`/`.jsx` in the build graph so it renders through
+ * `IslandMarker`, keyed `islandKey(sectionKey, <file-basename>)`. `sectionKey` is
+ * fixed per bundle (one section per renderer build). Non-client modules and other
+ * extensions fall through to esbuild untouched.
+ */
+declare function islandTransformEsbuildPlugin(opts: {
+  sectionKey: string;
+}): Plugin;
+//#endregion
+export { islandTransformEsbuildPlugin };

package/dist/islands/esbuild-plugin.js ADDED Viewed

@@ -0,0 +1,39 @@
+import { islandKey } from "./detect.js";
+import { wrapClientModuleSource } from "./wrap.js";
+import { basename, extname } from "node:path";
+import { readFile } from "node:fs/promises";
+//#region src/islands/esbuild-plugin.ts
+const LOADER = {
+	".tsx": "tsx",
+	".jsx": "jsx"
+};
+/**
+* Wrap every `"use client"` `.tsx`/`.jsx` in the build graph so it renders through
+* `IslandMarker`, keyed `islandKey(sectionKey, <file-basename>)`. `sectionKey` is
+* fixed per bundle (one section per renderer build). Non-client modules and other
+* extensions fall through to esbuild untouched.
+*/
+function islandTransformEsbuildPlugin(opts) {
+	return {
+		name: "template-kit:island-transform-esbuild",
+		setup(b) {
+			b.onLoad({ filter: /\.(tsx|jsx)$/ }, async (args) => {
+				const code = await readFile(args.path, "utf8");
+				const wrapped = wrapClientModuleSource(code, islandKey(opts.sectionKey, basename(args.path, extname(args.path))));
+				const ext = extname(args.path);
+				if (wrapped === null) return {
+					contents: code,
+					loader: LOADER[ext]
+				};
+				return {
+					contents: wrapped,
+					loader: LOADER[ext]
+				};
+			});
+		}
+	};
+}
+//#endregion
+export { islandTransformEsbuildPlugin };

package/dist/islands/wrap.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import MagicString from "magic-string";
+//#region src/islands/wrap.d.ts
+/**
+ * Rewrite a client module's source so its default export renders through
+ * `IslandMarker` with `islandKey`. Returns null when `code` is not a client
+ * component (`hasClientDirective` false) or has no default export — the caller
+ * then leaves the module untouched. The rebound original is `__trIslandReal`;
+ * it still flows through the consumer's JSX/TS transform unchanged.
+ */
+declare function wrapClientModuleSource(code: string, islandKey: string): string | null;
+//#endregion
+export { wrapClientModuleSource };

package/dist/islands/wrap.js ADDED Viewed

@@ -0,0 +1,48 @@
+import { hasClientDirective } from "../eslint/is-client-file.js";
+import MagicString from "magic-string";
+//#region src/islands/wrap.ts
+const DEFAULT_EXPORT = /export\s+default\s+/;
+/**
+* The codemod as a `MagicString`, so a caller (the Vite plugin) can emit a
+* hi-res sourcemap alongside the rewritten code. Returns null on the same terms
+* as `wrapClientModuleSource` — a non-client module or one with no default
+* export. The rebound original is `__trIslandReal`; it still flows through the
+* consumer's JSX/TS transform unchanged.
+*/
+function wrapClientModuleMagic(code, islandKey) {
+	if (!hasClientDirective(code)) return null;
+	if (!DEFAULT_EXPORT.test(code)) return null;
+	const s = new MagicString(code);
+	s.replace(DEFAULT_EXPORT, "const __trIslandReal = ");
+	s.append(wrapperSource(islandKey));
+	return s;
+}
+/**
+* Rewrite a client module's source so its default export renders through
+* `IslandMarker` with `islandKey`. Returns null when `code` is not a client
+* component (`hasClientDirective` false) or has no default export — the caller
+* then leaves the module untouched. The rebound original is `__trIslandReal`;
+* it still flows through the consumer's JSX/TS transform unchanged.
+*/
+function wrapClientModuleSource(code, islandKey) {
+	return wrapClientModuleMagic(code, islandKey)?.toString() ?? null;
+}
+function wrapperSource(islandKey) {
+	return `
+;
+import { createElement as __trCreateElement, useId as __trUseId } from "react";
+import { IslandMarker as __TrIslandMarker } from "@homepages/template-kit";
+export default function __trIslandWrapper(__trProps) {
+  const __trIslandId = __trUseId();
+  return __trCreateElement(
+    __TrIslandMarker,
+    { islandKey: ${JSON.stringify(islandKey)}, islandId: __trIslandId, props: __trProps },
+    __trCreateElement(__trIslandReal, __trProps),
+  );
+}
+`;
+}
+//#endregion
+export { wrapClientModuleMagic, wrapClientModuleSource };

package/dist/package.js CHANGED Viewed

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.3.0";
+var version = "0.4.1";
 //#endregion
 export { version };

package/dist/ssr.d.ts ADDED Viewed

@@ -0,0 +1,31 @@
+import { ResolvedFixture } from "./schema/fixture-schema.js";
+import "./schema/index.js";
+import { hasClientDirective } from "./eslint/is-client-file.js";
+import { isClientComponentFile, islandKey } from "./islands/detect.js";
+import { wrapClientModuleSource } from "./islands/wrap.js";
+import { findSectionIslands } from "./islands/discover.js";
+import { islandTransformEsbuildPlugin } from "./islands/esbuild-plugin.js";
+import { ComponentType } from "react";
+//#region src/ssr/index.d.ts
+type LoadedSection = {
+  Renderer: ComponentType<Record<string, unknown>>;
+  snapshotFixtures: ResolvedFixture[];
+  invariantFixtures: ResolvedFixture[];
+  schemaSlots: Record<string, {
+    type: string;
+    editable_by_user?: boolean;
+    required?: boolean;
+  }>;
+};
+type SectionModuleLoader = (dir: string, file: string) => Promise<unknown>;
+declare const nativeSectionLoader: SectionModuleLoader;
+/**
+ * Load a bundle's Renderer plus its resolved snapshot and invariant fixture
+ * sets from the bundle directory `dir`. `load` resolves each of the four
+ * contract files; it defaults to native dynamic import.
+ */
+declare function loadSectionBundle(dir: string, load?: SectionModuleLoader): Promise<LoadedSection>;
+/** Render a resolved fixture's props to static markup — the byte-for-byte page render. */
+declare function renderSectionHtml(renderer: ComponentType<Record<string, unknown>>, props: Record<string, unknown>): string;
+//#endregion
+export { LoadedSection, SectionModuleLoader, findSectionIslands, hasClientDirective, isClientComponentFile, islandKey, islandTransformEsbuildPlugin, loadSectionBundle, nativeSectionLoader, renderSectionHtml, wrapClientModuleSource };

package/dist/ssr.js ADDED Viewed

@@ -0,0 +1,46 @@
+import { FixtureModuleShape, buildFixtureSet, buildInvariantFixtures } from "./schema/fixture-schema.js";
+import { hasClientDirective } from "./eslint/is-client-file.js";
+import { isClientComponentFile, islandKey } from "./islands/detect.js";
+import { findSectionIslands } from "./islands/discover.js";
+import { wrapClientModuleSource } from "./islands/wrap.js";
+import { islandTransformEsbuildPlugin } from "./islands/esbuild-plugin.js";
+import { createElement } from "react";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { renderToStaticMarkup } from "react-dom/server";
+//#region src/ssr/index.ts
+const nativeSectionLoader = (dir, file) => import(pathToFileURL(join(dir, file)).href);
+/**
+* Load a bundle's Renderer plus its resolved snapshot and invariant fixture
+* sets from the bundle directory `dir`. `load` resolves each of the four
+* contract files; it defaults to native dynamic import.
+*/
+async function loadSectionBundle(dir, load = nativeSectionLoader) {
+	const rendererMod = await load(dir, "Renderer.tsx");
+	const fixturesMod = await load(dir, "fixtures.ts");
+	const schemaMod = await load(dir, "schema.ts");
+	const parsed = FixtureModuleShape.parse(fixturesMod.default);
+	const selfAnchor = schemaMod.schema.meta?.anchor ?? basename(dir);
+	return {
+		Renderer: rendererMod.default,
+		snapshotFixtures: buildFixtureSet({
+			schema: schemaMod.schema,
+			module: parsed,
+			selfAnchor
+		}),
+		invariantFixtures: buildInvariantFixtures({
+			schema: schemaMod.schema,
+			module: parsed,
+			selfAnchor
+		}),
+		schemaSlots: schemaMod.schema.slots
+	};
+}
+/** Render a resolved fixture's props to static markup — the byte-for-byte page render. */
+function renderSectionHtml(renderer, props) {
+	return renderToStaticMarkup(createElement(renderer, props));
+}
+//#endregion
+export { findSectionIslands, hasClientDirective, isClientComponentFile, islandKey, islandTransformEsbuildPlugin, loadSectionBundle, nativeSectionLoader, renderSectionHtml, wrapClientModuleSource };

package/docs/INDEX.md CHANGED Viewed

@@ -2,7 +2,7 @@
 purpose: Router for the docs corpus that ships inside the @homepages/template-kit npm package.
 status: living
 related: []
-updated: 2026-07-15
+updated: 2026-07-16
 ---
 # template-kit docs — router
@@ -13,11 +13,19 @@ detail.
 | Doc | What it covers | Read when you're touching... |
 |---|---|---|
+| `quickstart.md` | The cold-start tutorial: create a workspace, preview the starter's `hero` section, read its four files, make one edit, and check it — owns the author-loop anchor every recipe links to | your first section, end to end |
+| `overview.md` | The one-page mental model: workspace → templates → sections, the four reserved files, and the server-vs-client mapping | orienting yourself before your first section |
 | `llms.txt` | Machine-readable index of this corpus for an agent working inside an installed kit | orienting an agent in a consuming workspace |
 | `schema-system.md` | The section authoring contract: `schema.ts` / `fill-spec.ts` / `fixtures.ts` / `Renderer.tsx`, `SectionProps` inference, the closed source/transform vocabulary, and the golden property fixtures | authoring or changing any section |
+| `vocabulary.md` | The closed authoring vocabulary — the 9 slot types, the `direct()` source fields, and the `derived()` transforms, with selection semantics | choosing which slot type / source / transform to use |
 | `primitives.md` | The five contract primitives (`Section`, `Slot`, `SlotItem`, `SlotGroup`, `Image`) and the marker attributes they emit | writing a section's markup |
+| `assets.md` | Static assets (svg/images/fonts): where they live (template level or a section folder, if referenced), referencing them from a section's CSS with `url()`/`@font-face` or importing them into a component, and the asset-vs-content-image distinction | shipping a logo, texture, icon, or brand font with a template |
 | `theme-and-css.md` | The two CSS entries, the one-Tailwind-import rule, `TokenTheme` (your own token names → your own Tailwind utilities), the `template-kit theme` command that generates `theme.css` from `theme.ts`, the breakpoint ladder, and the opt-in `content-visibility` recipe for long, image-heavy pages | a template's theme, its CSS entry, or a long page with a live map or full-screen overlay |
 | `islands.md` | Interactivity: `"use client"` components, the serializable-props rule, editor options, the loader | anything interactive in a section |
 | `eslint.md` | The `@homepages/template-kit/eslint` preset: the two-line config, the ESLint + parser install it expects, and its glob scope | wiring up lint in a template workspace |
 | `check.md` | The `template-kit check` CLI command: the toolchain it resolves from your workspace, its stages, `--all`/`--json`, output shape, and exit code | running `check` locally or wiring it into CI |
+| `dev.md` | The `template-kit dev` CLI command: the local preview server, its home launcher and two tool cards (full template viewer, canvas mirror), the canvas mirror's selection overlay and per-slot edit panel, live reload, the content-override protocol, and the render/inspect/screenshot endpoints | previewing sections as you author them |
+| `new.md` | The `template-kit new` / `new-section` CLI commands: scaffolding a new template with a working starter section, or adding a bare section to an existing template | adding a template or a section to a workspace |
+| `pack.md` | The `template-kit pack` CLI command: builds a template's submission zip — template source, the workspace lockfile, and a stamped `pack-manifest.json`; refuses on a failing `check`, a missing lockfile, or a local-protocol dependency | packaging a template for submission |
 | `rules/` | One page per rule-id (`template-kit/*`), across both venues — the id printed by a lint or `check` failure resolves here. `rules/INDEX.md` routes them; `rules/server-vs-client.md` is the concept the server-rendering rules assume | any lint or `check` failure |
+| `recipes/` | Task recipes: how do I add a slot, bind a fact, add an island, package a template… Each is a minimal delta from the starter's `hero` section, ending in the author loop. `recipes/INDEX.md` routes them by task | doing something specific and not sure which file to touch |

package/docs/assets.md ADDED Viewed

@@ -0,0 +1,128 @@
+---
+purpose: Authoring static assets (svg, images, fonts) at the template level or in a section folder, and how they differ from content images.
+status: living
+related: [INDEX.md, primitives.md, theme-and-css.md, rules/size-assets.md, rules/bundle-binary-asset.md, rules/no-raw-element.md]
+updated: 2026-07-16
+---
+# Static assets
+A **static asset** is a file that is part of the template itself — a logo, a
+background texture, an icon, a brand webfont. It is authored once, is the
+**same for every deliverable** rendered from the template, and is referenced
+either from your CSS or from a component.
+## Where an asset lives
+An asset lives in one of two places:
+- **Template level** — e.g. `templates/<template>/assets/` — shared across every
+  section in the template. Reference it from a section's CSS with a `../../assets/…`
+  path (below).
+- **Section folder** — e.g. `sections/<section>/assets/` — local to that one
+  section. A section-folder asset must be *referenced*: imported in `Renderer.tsx`
+  or `url()`-referenced from one of the section's CSS files. An unreferenced binary
+  in a section folder is flagged by [`bundle-binary-asset`](rules/bundle-binary-asset.md) —
+  it has no build meaning and can never be served.
+Keep a logo, texture, or font that several sections share in the template-level
+folder; keep one that only a single section uses alongside that section.
+## Supported files
+```
+.svg .png .jpg .jpeg .gif .webp .avif .ico    images
+.woff .woff2 .ttf .otf .eot                   fonts
+.mp4 .webm .mov .mp3 .wav                      audio / video
+.pdf .zip                                      documents
+```
+## Referencing an asset — from CSS with `url()`
+Reference a template-level asset from a section's `styles.css` with `url()` —
+a `@font-face` `src` or a `background-image` resolves to the asset's built URL,
+identical in the `template-kit dev` preview, in the editor, and on the published
+page. Hand-CSS opens with a `css-reason:` comment (see
+[`css-reason`](rules/css-reason.md)):
+```css
+/* css-reason: brand webfont + crest watermark, both template assets */
+@font-face {
+  font-family: "Brand Serif";
+  src: url("../../assets/fonts/brand.woff2") format("woff2");
+  font-display: swap;
+}
+.hero-crest {
+  background-image: url("../../assets/crest.svg");
+}
+```
+The `../../assets/…` path climbs out of the section folder to the template-level
+`assets/` directory. A font you declare here is available to the whole section.
+If the family you want is one the template's theme already loads, reference that
+instead — see [Theme and CSS](theme-and-css.md); a font the page already has
+costs nothing to reuse.
+A **section-folder** asset is referenced the same way, with a section-relative
+path instead — no climbing out of the folder:
+```css
+/* css-reason: hero watermark, local to this section */
+.hero-crest {
+  background-image: url("./assets/crest.svg");
+}
+```
+## Referencing an asset — from a component with `import`
+An asset you render as an element — a logo, a crest — can be imported in the component and
+handed to the `Image` primitive, whose `src` accepts a URL string:
+```tsx
+import { Image } from "@homepages/template-kit";
+import crest from "./assets/crest.svg";
+export default function Renderer() {
+  return <Image src={crest} alt="" />;
+}
+```
+The import resolves to the asset's built `/section-assets/…` URL — the same URL in the
+`dev` preview, the editor, and the published page. The kit ships an ambient TypeScript
+declaration that types every supported asset import as that URL string, so the import
+typechecks with no per-workspace setup. Use `alt=""` for a purely decorative
+asset. (Never a raw `<img>` — `Image` carries the responsive/fallback contract; a raw
+`<img>` is rejected by [`no-raw-element`](rules/no-raw-element.md).)
+## Which to use
+- CSS decoration (backgrounds, `@font-face`, masks) → `url()`.
+- An asset rendered as an element → `import` + `<Image>`.
+- A tiny glyph or icon → inline `<svg>` markup — no file at all.
+## Assets vs. content images
+These are two different things; keep them apart.
+- A **static asset** is authored template decoration — a logo, a texture, a brand
+  font. It ships inside the template, is the same on every deliverable, and you
+  reference it from your CSS with `url()` or by importing it into a component (above).
+- A **content image** is the property's own content — listing photos, floor
+  plans, a headshot. It differs on every deliverable and flows through the
+  section's slots via the [`Image`](primitives.md) descriptor, never as a file in
+  your template. Declare an image slot in your schema and render it with the
+  `Image` primitive; the platform supplies the actual photo per deliverable.
+Rule of thumb: if the picture is the same for every home the template ever
+renders, it's an asset — place it at the template level or in the section folder
+and reference it from CSS or a component `import`. If it changes with the
+property, it's content — give it a slot. Never hard-code a listing photo as an
+asset.
+## Keep them lean
+Every asset a section pulls in counts toward its asset budget — see
+[`size-assets`](rules/size-assets.md). Fonts and images are already compressed, so
+the budget is raw bytes: subset a webfont to the weights and characters you use,
+export images at the size they render, and drop anything a section doesn't
+actually reference.

package/docs/check.md CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 purpose: The `template-kit check` command — what it runs, its flags, its output shape, and its exit code.
 status: living
-related: [INDEX.md, rules/INDEX.md, eslint.md, theme-and-css.md]
+related: [INDEX.md, rules/INDEX.md, eslint.md, theme-and-css.md, dev.md]
 updated: 2026-07-15
 ---
 # template-kit check
@@ -62,8 +62,9 @@ one class of fix at a time:
    stray `[object Object]`, a bare `null`/`undefined`/`NaN` leaf, a `src`-less `<img>` —
    plus, for the `typical` fixture, that the editor's sidebar order matches the page's
    real render order.
-6. **size** — every section's renderer bundle and compiled stylesheet, gzipped, against a
-   fixed byte budget.
+6. **size** — every section's renderer bundle, compiled stylesheet, and largest island
+   (browser) bundle, gzipped, against a fixed byte budget; and its static assets
+   (svg/images/fonts), budgeted by raw bytes since they are already compressed.
 **The dependency gates** run once per invocation, never once per template — they are
 properties of the workspace's one lockfile and installed tree, not of any one template:
@@ -119,3 +120,5 @@ submission.
   each, Rule / Reason / Fix.
 - [ESLint preset](eslint.md) — the one-file-at-a-time half of the same rule set, run
   directly by your editor, not only through `check`.
+- [Dev](dev.md) — the other workspace command: preview sections in a browser as you
+  author, before running `check` as the acceptance gate.