@homepages/template-kit 0.3.0 → 0.4.1

package/docs/recipes/static-asset.md

@@ -0,0 +1,103 @@
+---
+purpose: Add a graphic — an icon, a divider, a photo, a font — to a section.
+status: living
+related: [../assets.md, ../check.md, ../rules/bundle-binary-asset.md, image-slot-crop.md, ../theme-and-css.md]
+updated: 2026-07-16
+---
+# Add a static asset (image, icon, font)
+
+## Goal
+
+Add a graphic — an icon, a divider mark, a photo, a custom font — to a section.
+
+## The delta
+
+A binary asset — an image, a font, a video, an archive — may live in a section's own
+`sections/<section>/assets/` folder, but only if the section references it: imported in
+`Renderer.tsx` (`import crest from "./assets/crest.svg"`) or `url()`-referenced from one
+of the section's CSS files. An unreferenced binary in the folder is flagged; see
+[`bundle-binary-asset`](../rules/bundle-binary-asset.md) for the rule and why.
+
+A file shared across sections — a logo, a brand webfont, a texture — lives at the
+**template level** instead, referenced the same way with a `../../assets/…` path. See
+[Static assets](../assets.md) for both paths and the full reference contract. What you
+reach for depends on what the graphic is:
+
+**A vector graphic — an icon, a divider, a decorative mark used only here.** Inline it as
+SVG markup directly in the JSX that draws it. It is text, ships with the rest of your
+component, and needs no file or import at all:
+
+```tsx
+// sections/hero/components/ScrollArrow.tsx
+export function ScrollArrow() {
+  return (
+    <svg viewBox="0 0 16 16" className="h-4 w-4" fill="none" aria-hidden="true">
+      <path d="M8 3v10M3 9l5 4 5-4" stroke="currentColor" strokeWidth="1.5" />
+    </svg>
+  );
+}
+```
+
+```tsx
+// sections/hero/Renderer.tsx
+import { ScrollArrow } from "./components/ScrollArrow";
+// …
+<ScrollArrow />
+```
+
+That markup's bytes ship inside the section's renderer bundle, so they count
+toward the same byte budget as the rest of your JSX — see the size stage in
+[Check](../check.md).
+
+**A raster image or watermark used only in this section.** Add it under
+`sections/<section>/assets/` and import it into the component:
+
+```tsx
+// sections/hero/Renderer.tsx
+import { Image } from "@homepages/template-kit";
+import crest from "./assets/crest.svg";
+
+export default function Renderer() {
+  return <Image src={crest} alt="" />;
+}
+```
+
+Or reference it from the section's CSS with `url()` instead of importing it — see
+[Static assets](../assets.md) for both forms. Either way the file must be referenced:
+an asset nothing imports or `url()`-references is flagged by
+[`bundle-binary-asset`](../rules/bundle-binary-asset.md).
+
+**A photo.** Not a section asset at all — a section never ships a photo file. A
+photo arrives at runtime through an `image` slot: declare it in `schema.ts`,
+produce it with an `image-assign` decision in `fill-spec.ts`, and render it
+through the `<Image>` primitive, which reads `url`, `alt`, and `responsive` off
+the slot's resolved value. See
+[Image slot with a locked crop](image-slot-crop.md) for the full shape.
+
+**A custom font shared across the template.** Declared once, for the whole
+template, in the theme's `fonts` and optional `fontFaces` block. See
+[Theme and CSS](../theme-and-css.md). A font only one section uses can instead
+live in that section's `assets/` folder and be declared with a `@font-face` in
+the section's own CSS — see [Static assets](../assets.md).
+
+## Commands
+
+None — inlining SVG markup and declaring a slot are content edits. No CLI
+command beyond the author loop below.
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop).
+
+## See also
+
+- [Static assets](../assets.md) — the full reference/import contract, template
+  level vs. section folder.
+- [`bundle-binary-asset`](../rules/bundle-binary-asset.md) — the rule that
+  flags an unreferenced binary in a section folder, and the SVG-inlining fix.
+- [Check](../check.md) — the size stage a large inlined SVG or a bloated
+  renderer bundle counts against.
+- [Image slot with a locked crop](image-slot-crop.md) — the real channel for a
+  photo: an `image` slot, an `image-assign` decision, and the `<Image>`
+  primitive.
+- [Theme and CSS](../theme-and-css.md) — where a template's fonts are declared.

package/docs/recipes/third-party-package.md

@@ -0,0 +1,90 @@
+---
+purpose: Use a third-party npm package in a section.
+status: living
+related: [../islands.md, ../pack.md, ../rules/single-react.md, ../rules/no-bare-css-import.md, ../rules/no-css-import-from-render-path.md]
+updated: 2026-07-15
+---
+# Use a third-party npm package in a section
+
+## Goal
+
+Use an npm package in a section.
+
+## The delta
+
+Install the package like any npm dependency:
+
+```bash
+npm i swiper
+```
+
+**Only a published version.** `pack` refuses to produce a submission zip when a
+dependency uses a local `file:`/`link:` protocol — depend on a real published
+version, never a path on your own machine.
+
+**Where you import it from matters.** A client library — a carousel, a map SDK,
+anything that touches `window` or the DOM — is imported inside a `"use client"`
+island, the same as any other browser-only code:
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  // …
+}
+```
+
+A server-side import — one that lands in the Renderer or a plain component it
+imports, not behind `"use client"` — must stay pure and deterministic: no reads
+of the clock, randomness, or the network at render time. A package built for a
+browser runtime (it touches `window`, schedules a timer, generates an id) does
+not belong there; move the usage into an island.
+
+**A package that ships its own stylesheet** is imported by its bare specifier,
+from the module that renders it — the Renderer's import graph (the components
+and islands it imports, transitively) is what the CSS build bundles and
+harvests for the section's stylesheet:
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+import "swiper/css"; // ← the sanctioned channel: a bare specifier reaches this section's layer
+```
+
+A **local** `.css` import from that same render path is a different, banned case
+— see [`no-css-import-from-render-path`](../rules/no-css-import-from-render-path.md)
+for the full distinction between the two, and
+[`no-bare-css-import`](../rules/no-bare-css-import.md) for why a hand-written
+stylesheet can't reach the package's CSS with its own `@import` instead.
+
+## Commands
+
+```bash
+npm i <package>
+```
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop) — a green
+`check` after the install confirms the package resolves, its CSS (if any)
+landed in the section's layer, and the workspace still carries exactly one copy
+of React.
+
+## See also
+
+- [Islands](../islands.md) — writing a `"use client"` island; a third-party
+  client library is fine inside one, never in a Renderer.
+- [`template-kit pack`](../pack.md) — why a `file:`/`link:` dependency blocks a
+  submission.
+- [`single-react`](../rules/single-react.md) — a package that pulls its own
+  copy of React breaks hydration; the installed tree may carry only one.
+- [`no-css-import-from-render-path`](../rules/no-css-import-from-render-path.md) —
+  bare package specifier (legal) vs. a local `.css` import (banned) from a
+  section's render path.
+- [`no-bare-css-import`](../rules/no-bare-css-import.md) — why a hand-written
+  stylesheet can't reach a package's CSS with its own `@import` either.

package/docs/rules/INDEX.md

@@ -2,7 +2,7 @@
 purpose: Router for the rule corpus — every template-kit/<id> an author can hit, and the page that explains it.
 status: living
 related: [server-vs-client.md, ../eslint.md, ../check.md, ../INDEX.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # Rules
 
@@ -34,7 +34,7 @@ and it is explained there rather than on each of them.
 | [`no-hex`](no-hex.md) | eslint | No hard-coded colours — the one legal colour function is a `color-mix()` over theme-derived arguments. Islands are NOT exempt. |
 | [`no-css-import-from-render-path`](no-css-import-from-render-path.md) | eslint | No relative/absolute .css import from a section's render path — a package's is the sanctioned channel. |
 | [`bundle-incomplete`](bundle-incomplete.md) | check | A section folder is missing one of its four required files. |
-| [`bundle-binary-asset`](bundle-binary-asset.md) | check | A binary asset file sits in a section folder — not supported yet. |
+| [`bundle-binary-asset`](bundle-binary-asset.md) | check | An unreferenced binary asset sits in a section folder. |
 | [`schema-invalid`](schema-invalid.md) | check | A section's schema.ts or fill-spec.ts fails a contract assertion, or cannot be loaded. |
 | [`fixtures-invalid`](fixtures-invalid.md) | check | A section's fixtures.ts does not satisfy the fixture-module shape. |
 | [`manifest-invalid`](manifest-invalid.md) | check | A template's manifest.json is missing, unparseable, or violates the manifest contract. |
@@ -55,6 +55,8 @@ and it is explained there rather than on each of them.
 | [`license-denied`](license-denied.md) | check | A production dependency's license is not on the allowlist. |
 | [`size-renderer-bundle`](size-renderer-bundle.md) | check | A section's renderer bundle exceeds its byte budget. |
 | [`size-section-css`](size-section-css.md) | check | A section's compiled CSS exceeds its byte budget. |
+| [`size-island-bundle`](size-island-bundle.md) | check | A section's island (browser) bundle exceeds its byte budget. |
+| [`size-assets`](size-assets.md) | check | A section's static assets exceed their byte budget. |
 | [`no-templates`](no-templates.md) | check | The workspace has no template to check at all. |
 
 ## See also

package/docs/rules/bundle-binary-asset.md

@@ -1,44 +1,43 @@
 ---
 purpose: The template-kit/bundle-binary-asset authoring rule — what it enforces, why, and how to fix it.
 status: living
-related: [INDEX.md, bundle-incomplete.md, ../primitives.md]
-updated: 2026-07-14
+related: [INDEX.md, bundle-incomplete.md, ../primitives.md, ../assets.md]
+updated: 2026-07-16
 ---
 # template-kit/bundle-binary-asset
 
-> A section folder holds code, not static files. A binary asset dropped into it has no
-> build meaning yet.
+> A static asset may live in a section folder — but only if something references it. An
+> unreferenced binary is dead weight and can never be served.
 
 ## Rule
 
-No file inside a section folder may be a binary asset: an image, a font, a video, an
-audio file, an archive, a document. The check looks two ways:
+A binary asset inside a section folder is allowed **only when the section references it** —
+imported in `Renderer.tsx` (`import crest from "./assets/crest.svg"`) or `url()`-referenced
+from one of the section's CSS files. A binary that nothing references is flagged. The check
+looks two ways to find candidates:
 
 - **By extension** — `.svg`, `.png`, `.jpg`/`.jpeg`, `.gif`, `.webp`, `.avif`, `.ico`,
   `.woff`/`.woff2`, `.ttf`, `.otf`, `.eot`, `.mp4`, `.webm`, `.mov`, `.mp3`, `.wav`,
   `.pdf`, `.zip`.
-- **By content** — any other file whose first bytes contain a NUL byte, catching an
-  asset type the extension list doesn't name.
-
-This is scoped to the section folder itself (`Renderer.tsx`, `schema.ts`, `components/`,
-everything under it) — not to the photos a listing supplies. Those arrive at runtime
-through a slot's `src`, never as a file that ships inside your section.
+- **By content** — any other file whose first bytes contain a NUL byte.
 
 ## Reason
 
-A section folder is published as source: its content hash covers every file in it, and
-the platform has no pipeline yet to fingerprint, optimize, or serve a binary file that
-lives alongside your code. A `.png` committed today has no URL tomorrow — there is
-nowhere for it to be requested from.
-
-Everything a section needs to draw — an icon, a divider graphic, a background pattern —
-is expressible as markup instead: an inline `<svg>`, or a shape built from CSS. That
-markup is text, ships with the rest of your JSX, and needs no pipeline at all.
+A referenced asset is first-class: the build content-hashes it to a stable
+`/section-assets/` URL and the publish pipeline uploads it — identical in the `dev`
+preview, the editor, and the published page. An *unreferenced* binary has no such URL: it
+is never emitted or uploaded, yet it still counts toward the section's content hash (its
+identity). So it is pure dead weight — a file that ships nowhere.
 
 ## Fix
 
-Delete the binary file and inline its content as SVG markup — either directly in the
-JSX that used it, or as its own small component if more than one place needs it.
+Either reference the asset, or delete it.
+
+- **Reference it from a component:** `import crest from "./assets/crest.svg"` and render it
+  with the `Image` primitive — `<Image src={crest} alt="…" />`. See [Static assets](../assets.md).
+- **Reference it from CSS:** `background-image: url("./assets/crest.svg")` (or a
+  `@font-face` `src`) in the section's `styles.css`.
+- **Delete it** if it is left over and unused.
 
 ### Before
 
@@ -49,32 +48,25 @@ sections/hero/
   fill-spec.ts
   fixtures.ts
   assets/
-    arrow.svg          ← binary asset in the bundle
+    crest.svg          ← nothing imports or url()-references this file
 ```
 
+### After
+
 ```tsx
 // sections/hero/Renderer.tsx
-import arrowUrl from "./assets/arrow.svg";
+import { Image } from "@homepages/template-kit";
+import crest from "./assets/crest.svg";
 
-export function Renderer() {
-  return <img src={arrowUrl} alt="" className="h-4 w-4" />;
+export default function Renderer() {
+  return <Image src={crest} alt="" />;
 }
 ```
 
-### After
-
-```text
-sections/hero/
-  Renderer.tsx
-  schema.ts
-  fill-spec.ts
-  fixtures.ts
-  components/
-    ScrollArrow.tsx     ← markup, not a binary file
-```
+For a tiny glyph or divider, prefer inline `<svg>` markup over a file at all — it ships with
+your JSX, needs no asset at all, and costs no extra request:
 
 ```tsx
-// sections/hero/components/ScrollArrow.tsx
 export function ScrollArrow() {
   return (
     <svg viewBox="0 0 16 16" className="h-4 w-4" fill="none" aria-hidden="true">
@@ -84,19 +76,8 @@ export function ScrollArrow() {
 }
 ```
 
-```tsx
-// sections/hero/Renderer.tsx
-import { ScrollArrow } from "./components/ScrollArrow.js";
-
-export function Renderer() {
-  return <ScrollArrow />;
-}
-```
-
 ## See also
 
-- [`bundle-incomplete`](bundle-incomplete.md) — the other rule on the folder's contents,
-  checked by the same pass over the section anatomy.
-- [Contract primitives](../primitives.md) — `Image`, the primitive that owns every photo
-  a listing supplies. It reads a `src` at runtime; it is not a way to ship a binary file
-  inside your section.
+- [Static assets](../assets.md) — where an asset may live and how to reference it.
+- [`bundle-incomplete`](bundle-incomplete.md) — the other rule on the folder's contents.
+- [Contract primitives](../primitives.md) — `Image`, which renders an asset URL you import.

package/docs/rules/bundle-incomplete.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/bundle-incomplete authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../schema-system.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/bundle-incomplete
 
@@ -30,7 +30,7 @@ Two near-misses do **not** satisfy it:
   searched for down the tree.
 
 Everything else in the folder is unconstrained. `components/`, `hooks/`, `utils/`, any
-nesting, any number of support modules, islands, stylesheets, enhancers: the check has no
+nesting, any number of support modules, islands, stylesheets: the check has no
 opinion about them, and neither does the rest of the kit.
 
 ## Reason

package/docs/rules/css-reason.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/css-reason authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../theme-and-css.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/css-reason
 
@@ -36,7 +36,7 @@ and cannot leak into another section on the same page. Hand-written CSS gives al
 up.
 
 There is exactly one thing utilities cannot do: style **DOM that Tailwind's scanner never
-sees**. Markup an enhancer builds at runtime has no class in your source for the scanner
+sees**. Markup an island builds at runtime has no class in your source for the scanner
 to find, and a third-party widget's own DOM was never yours to put classes on. Those are
 the cases hand-CSS exists for.
 
@@ -67,7 +67,7 @@ classes on the markup.
 ### After
 
 ```css
-/* css-reason: styles the marker DOM the neighborhood-map enhancer builds at runtime —
+/* css-reason: styles the marker DOM the neighborhood-map island builds at runtime —
    the nodes are created by the map library after hydration, so Tailwind's scanner never
    sees a class to compile. */
 .tr-map-marker {

package/docs/rules/no-bare-css-import.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/no-bare-css-import authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../theme-and-css.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/no-bare-css-import
 
@@ -59,11 +59,11 @@ in the whole kit: the only signal is that the styles are not there.
 Delete the `@import`.
 
 **A package's stylesheet is reached from the code that needs it**, not from CSS. Write
-`import "swiper/css";` in the component, island, or enhancer that renders the thing — the
-CSS build bundles your `Renderer.tsx` and every marked enhancer, transitively, precisely to
-harvest those imports, and it compiles what they pull in into **this section's cascade
-layer**. Package CSS goes in first and your own hand-CSS second, so at equal specificity
-your rules win.
+`import "swiper/css";` in the component or island that renders the thing — the CSS build
+bundles your `Renderer.tsx` and everything it imports, transitively, precisely to harvest
+those imports, and it compiles what they pull in into **this section's cascade layer**.
+Package CSS goes in first and your own hand-CSS second, so at equal specificity your rules
+win.
 
 Two things authors get wrong immediately after:
 
@@ -79,7 +79,7 @@ Two things authors get wrong immediately after:
 
 ```css
 /* sections/gallery/styles.css */
-/* css-reason: styles the slide DOM the Swiper enhancer builds at runtime. */
+/* css-reason: styles the slide DOM the Swiper carousel builds at runtime. */
 @import "swiper/css";              /* template-kit/no-bare-css-import — silently dropped */
 
 .tr-gallery .swiper-pagination-bullet-active {
@@ -95,7 +95,7 @@ The `@import` is gone from the stylesheet:
 
 ```css
 /* sections/gallery/styles.css */
-/* css-reason: overrides the Swiper pagination DOM the enhancer builds at runtime —
+/* css-reason: overrides the Swiper pagination DOM the carousel builds at runtime —
    those nodes carry the library's own classes, which Tailwind's scanner never sees. */
 .tr-gallery .swiper-pagination-bullet-active {
   background: var(--tr-color-primary);

package/docs/rules/no-css-import-from-render-path.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/no-css-import-from-render-path authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../theme-and-css.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/no-css-import-from-render-path
 
@@ -31,8 +31,8 @@ server-rendered inline before it is hydrated.
 ## Reason
 
 The section's CSS build works by **bundling the render path itself** — `Renderer.tsx` and
-any enhancer that carries `export const enhancer` — and harvesting the CSS its imports
-pull in. A bare specifier resolves into `node_modules`, which is exactly what that build
+every module it imports, components and islands alike — and harvesting the CSS those
+imports pull in. A bare specifier resolves into `node_modules`, which is exactly what that build
 looks for: `import "swiper/css";` in `Renderer.tsx` is not a mistake, it is the mechanism.
 
 A **local** stylesheet is a different problem. Every `.css` file that already lives in the
@@ -47,11 +47,10 @@ Delete the import. A local stylesheet already ships — the build picks up every
 in the section folder on its own; importing it again only makes it double-emit.
 
 A package's stylesheet is different: import it **by its bare specifier**, from the module
-that needs it. The build bundles `Renderer.tsx` and every marked enhancer's import graph
-**transitively**, so a bare specifier is equally legal in the Renderer itself, in a marked
-enhancer, or in any component either one imports — not only at the top of the tree. That
-import is how the build finds the stylesheet and routes it into the section's cascade
-layer.
+that needs it. The build bundles `Renderer.tsx`'s import graph **transitively**, so a bare
+specifier is equally legal in the Renderer itself or in any component or island it
+imports — not only at the top of the tree. That import is how the build finds the
+stylesheet and routes it into the section's cascade layer.
 
 ### Before
 

package/docs/rules/size-assets.md

@@ -0,0 +1,88 @@
+---
+purpose: The template-kit/size-assets authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-section-css.md, ../theme-and-css.md]
+updated: 2026-07-15
+---
+# template-kit/size-assets
+
+> A section's static assets — the svg, images, and fonts it imports or `url()`-references —
+> must total **≤ 250 KB raw.** Raw, not gzip: images and fonts are already compressed
+> formats, so gzipping them again buys nothing.
+
+## Rule
+
+A section's static assets are budgeted by **total raw bytes, 250 KB or less**. What is
+measured is every asset the published section actually ships:
+
+- an svg, image, or font `import`ed directly in `Renderer.tsx` (or an island), and
+- an svg, image, or font `url()`-referenced from the section's own CSS or from a
+  package stylesheet its module graph pulls in — including a webfont `@font-face`s.
+
+The same asset referenced twice (from both a stylesheet and a component, say) counts
+once, not twice.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A workspace cannot raise it, and there is no per-section exemption.
+
+## Reason
+
+An svg icon or a product photo a section imports, and a webfont a package's stylesheet
+pulls in, both ship to the same page load as the section's own code and CSS — they are
+not free just because they never appear in a byte-budget an author is used to watching.
+
+Fonts are the sharpest case. A `url()`-referenced webfont used to inline as part of the
+compiled stylesheet, which made a large font look like a CSS problem: trimming your own
+rules never fixed it, because the bytes were never your CSS to begin with. This rule
+separates that weight into its own budget — a font, an icon, or an image is measured as
+what it is, and the stylesheet budget ([`size-section-css`](size-section-css.md)) is left
+to measure only what it actually contains.
+
+## Fix
+
+Two moves, in order of how often they work:
+
+1. **Shrink or subset the asset.** A full variable font family, shipped for three
+   weights actually used, is the usual cause — subset it to the characters and weights
+   the section renders. An unoptimized PNG is the other common case — recompress it, or
+   switch to a format built for the content (`webp`/`avif` for photos, `svg` for icons).
+2. **Drop assets the section does not use.** A copied-in icon set or a leftover preview
+   image that never renders still ships its bytes — delete what the section does not
+   reference.
+
+### Before
+
+```tsx
+// sections/hero/Renderer.tsx
+import "brandfont/css"; // ← ships the package's full variable font family
+
+export default function Renderer() {
+  return <h1 style={{ fontFamily: "BrandFont" }}>Welcome home</h1>;
+}
+```
+
+### After
+
+```tsx
+// sections/hero/Renderer.tsx
+import heroIcon from "./assets/hero-icon.svg"; // ← a small, single-purpose asset
+
+export default function Renderer() {
+  // Uses a font the template's theme already declares (`--tr-font-<name>`),
+  // which costs nothing because it is already loaded — no package font import.
+  return (
+    <h1 className="tr-font-display">
+      <img src={heroIcon} alt="" /> Welcome home
+    </h1>
+  );
+}
+```
+
+## See also
+
+- [`size-section-css`](size-section-css.md) — the stylesheet budget this rule was split
+  out of; a `url()`-referenced font now counts here, not there.
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the same idea applied to the
+  section's JavaScript.
+- [Theme and CSS](../theme-and-css.md) — the fonts and tokens the page already loads,
+  which cost you nothing to reuse.