@homepages/template-kit 0.3.0 → 0.4.0

package/docs/recipes/interactive-island.md

@@ -0,0 +1,100 @@
+---
+purpose: Make part of a section interactive with a client-hydrated island.
+status: living
+related: [../islands.md, ../rules/server-vs-client.md, ../rules/serializable-island-props.md]
+updated: 2026-07-15
+---
+# Make part of a section interactive
+
+## Goal
+
+Make part of a section interactive.
+
+## The delta
+
+Starting from the starter's `hero` section, add a `"use client"` file next to the
+four contract files, matching the shape of the starter's own island,
+`ExpandableText.tsx`: the directive as the file's first statement, a default-exported
+function typed against plain props, and `useState` for the interactive part.
+
+```tsx
+// sections/hero/ContactReveal.tsx — a new island, same shape as ExpandableText
+"use client";
+
+import { type ReactNode, useState } from "react";
+
+import type { IslandEditorOptions } from "@homepages/template-kit";
+
+export default function ContactReveal({
+  hiddenLabel,
+  revealedValue,
+}: {
+  hiddenLabel: string;
+  revealedValue: string;
+}): ReactNode {
+  const [revealed, setRevealed] = useState(false);
+  return revealed ? (
+    <p className="text-base font-medium text-ink">{revealedValue}</p>
+  ) : (
+    <button
+      type="button"
+      className="font-medium text-accent underline"
+      onClick={() => setRevealed(true)}
+    >
+      {hiddenLabel}
+    </button>
+  );
+}
+
+// Optional, as on ExpandableText: hydrate live in the editor canvas too.
+export const editor: IslandEditorOptions = {
+  live: true,
+};
+```
+
+Render it from `Renderer.tsx` like any other component:
+
+```tsx
+// Renderer.tsx
+import ContactReveal from "./ContactReveal";
+// …
+<ContactReveal hiddenLabel="Show phone number" revealedValue="(555) 010-2020" />
+```
+
+If the island renders a schema slot's own content — the way the starter's `blurb`
+slot renders through `ExpandableText` — wrap it in `<Slot id="…">` with the matching
+schema id, exactly as `Renderer.tsx` already does:
+
+```tsx
+<Slot id="blurb">
+  <ExpandableText text={slots.blurb} collapsedChars={140} moreLabel="Read more" />
+</Slot>
+```
+
+A standalone island with no bound slot — like `ContactReveal` above — needs no
+`<Slot>` wrapper; `<Slot>` marks an editable slot's DOM for the editor, not
+"this is interactive."
+
+Props crossing into an island must be JSON-serializable — strings, numbers,
+booleans, and plain arrays/objects only, never a function, a `Date`, or a class
+instance; the island owns its own event handlers instead of receiving one. This is
+the only mechanism for interactivity in a section: a Renderer stays a pure function
+of its props, and any state, effect, or event handler moves into a `"use client"`
+island like the one above.
+
+## Commands
+
+None — this is a pure content edit. No CLI command beyond the author loop below.
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop).
+
+## See also
+
+- [Islands](../islands.md) — writing one, its props contract, editor options, and
+  the DOM contract a published page hydrates.
+- [Server vs client](../rules/server-vs-client.md) — how a file is scoped server or
+  client, and the three rules an island is exempt from.
+- [`serializable-island-props`](../rules/serializable-island-props.md) — the rule
+  that catches a non-serializable prop before the render ever throws.

package/docs/recipes/organize-section-folder.md

@@ -0,0 +1,72 @@
+---
+purpose: Structure a section's files beyond the four reserved contract files.
+status: living
+related: [../new.md, ../islands.md, ../pack.md, ../rules/bundle-binary-asset.md]
+updated: 2026-07-16
+---
+# Organize a section's files beyond the four reserved
+
+## Goal
+
+Structure a section beyond the four files.
+
+## The delta
+
+Starting from the starter's `hero` section, add a `components/` folder and pull a
+piece of markup out into its own module — the same shape as the starter's own
+`components/Feature.tsx`, which the starter's `Renderer.tsx` already imports and
+renders.
+
+```tsx
+// sections/hero/components/Feature.tsx
+import type { ReactNode } from "react";
+
+export function Feature({ label, value }: { label: string; value: string }): ReactNode {
+  return (
+    <div className="rounded-lg border border-ink/10 p-4">
+      <div className="text-sm text-ink/60">{label}</div>
+      <div className="text-lg font-semibold text-ink">{value}</div>
+    </div>
+  );
+}
+```
+
+```tsx
+// Renderer.tsx
+import { Feature } from "./components/Feature";
+// …
+<Feature label="Status" value="For sale" />
+```
+
+Exactly four files are reserved, and only at the section folder's root:
+`schema.ts`, `fill-spec.ts`, `fixtures.ts`, `Renderer.tsx`. Everything else in the
+folder is yours — `components/`, `hooks/`, `utils/`, stylesheets, any nesting, any
+number of support modules, and `"use client"` islands. A binary asset (an image, a
+font, an archive) may live under an `assets/` folder too, but only if something in
+the section references it — see
+[`bundle-binary-asset`](../rules/bundle-binary-asset.md) for the rule and what an
+unreferenced one costs you.
+
+Every file under `templates/<template>/` — not only the four reserved files — feeds
+`pack`'s content hash of the template tree, stamped into `pack-manifest.json`.
+Editing a component, a util, or even a comment inside a section folder changes that
+hash on the next `pack`, exactly as editing `Renderer.tsx` would.
+
+## Commands
+
+None — this is a pure content edit. No CLI command beyond the author loop below.
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop).
+
+## See also
+
+- [Adding templates and sections](../new.md) — `template-kit new` scaffolds a
+  starter section that already includes a `components/` folder and an island.
+- [Islands](../islands.md) — a `"use client"` file is one more kind of file the
+  section folder is free to hold.
+- [`template-kit pack`](../pack.md) — what produces the content hash and what it
+  refuses to pack.
+- [`bundle-binary-asset`](../rules/bundle-binary-asset.md) — when a binary file
+  in the folder must be referenced, and what happens if it isn't.

package/docs/recipes/prepare-submission.md

@@ -0,0 +1,55 @@
+---
+purpose: Package a template for submission.
+status: living
+related: [../pack.md, ../check.md]
+updated: 2026-07-15
+---
+# Prepare a submission
+
+## Goal
+
+Package a template for submission.
+
+## The delta
+
+Get the template to a green `check`, then pack it:
+
+```bash
+template-kit check <template>
+template-kit pack <template>
+```
+
+`pack` will not produce a zip until `check <template>` passes — it re-runs
+the same gate itself, and a failing `check` reports every problem in one
+pass, not one at a time, so a manual `check` first is just a faster feedback
+loop, not a separate requirement.
+A passing `pack` writes `<template>.zip` at the workspace root: the
+template's source, `pack-manifest.json` (the kit version, a content hash,
+and the `check` flag), and the workspace's `package.json` /
+`package-lock.json` so the build reproduces with `npm ci`.
+
+`pack` refuses to write a zip when:
+
+- `check <template>` is not green — fix the reported problems first.
+- the workspace has no `package-lock.json` — run `npm install` and commit it.
+- a dependency uses a local `file:`/`link:` protocol — depend on a published
+  version instead.
+
+Each refusal prints the cause; fix it and run `pack` again.
+
+## Commands
+
+```bash
+template-kit check <template>
+template-kit pack <template>
+```
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop) — `pack`
+refuses to build the zip until `check` is green, so a clean loop is the gate.
+
+## See also
+
+- [Pack](../pack.md) — what the zip contains and the full refusal list.
+- [Check](../check.md) — the gate `pack` runs before it will produce a zip.

package/docs/recipes/second-template.md

@@ -0,0 +1,49 @@
+---
+purpose: Add another template to the workspace.
+status: living
+related: [../new.md, ../check.md]
+updated: 2026-07-15
+---
+# Add a second template
+
+## Goal
+
+Add another template to the workspace.
+
+## The delta
+
+```bash
+template-kit new <name>
+```
+
+`new` creates `templates/<name>/` as a working starter template — the same
+starter shape a fresh workspace ships (a text slot, an image slot, a
+fact-bound slot, an option, fixtures, a fill spec, a `components/` folder, a
+`"use client"` island, `theme.ts`/`theme.css`, `manifest.json`) — and it
+already passes `check` as-is. Edit its sections from there.
+
+A template is a plain folder under `templates/`. Adding one does not
+duplicate anything: every template in the workspace shares the same kit
+version, the same root `package.json`/lockfile, and the same
+`tsconfig.json`/ESLint config. There is nothing per-template to configure
+beyond the folder itself.
+
+`new` refuses to overwrite an existing `templates/<name>/` folder.
+
+## Commands
+
+```bash
+template-kit new <name>
+template-kit check <name>
+```
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop) — a freshly
+created template is check-clean before you change a line.
+
+## See also
+
+- [Adding templates and sections](../new.md) — the full command, including
+  `new-section` for adding a section within a template.
+- [Check](../check.md) — the gate every template (new or edited) must pass.

package/docs/recipes/select-slot.md

@@ -0,0 +1,59 @@
+---
+purpose: Give the user a closed set of choices — an editable content slot, distinct from a behavioral enum option.
+status: living
+related: [../vocabulary.md, ../schema-system.md]
+updated: 2026-07-15
+---
+# A select slot — a closed set of choices
+
+## Goal
+
+Give the user a closed set of choices — an editable content slot, distinct from
+a behavioral `enum` option.
+
+## The delta
+
+A `select` slot still needs a `source` or a `produced_by`, exactly like every
+other slot type — `values` alone only declares the closed set the editor's
+dropdown offers. The cleanest no-AI fill for a closed set is usually a
+`direct()` fact that already resolves to one of a closed set of strings:
+
+```ts
+// schema.ts — add a select slot, seeded from a closed-vocabulary fact
+property_type: {
+  type: "select",
+  editable_by_user: true,
+  required: false,
+  values: ["single_family", "condo_townhome", "multi_family", "investment"],
+  source: direct("property_type"),
+  display_name: "Property type",
+},
+```
+
+```tsx
+// Renderer.tsx — read it like any other text-shaped slot
+<Slot id="property_type" textLeaf>
+  <span>{slots.property_type}</span>
+</Slot>
+```
+
+`slots.property_type` is `string | null` (required is `false`). The general
+`source`/`produced_by` contract still applies to a `select` slot, but no
+fill-spec decision type constrains its output to the closed `values` set —
+so `source: direct(...)` (a fact that already resolves within the set) is
+the reliable way to fill one.
+
+## Commands
+
+None — this is a pure content edit. No CLI command beyond the author loop below.
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop).
+
+## See also
+
+- [The closed vocabulary](../vocabulary.md#slot-types) — the slot-type table, including
+  where `select` sits next to `text`/`number`/etc.
+- [The schema system](../schema-system.md) — the full `schema.ts` contract, including
+  `direct()`/`derived()` binding.

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