@homepages/template-kit 0.3.0 → 0.4.1

package/docs/recipes/collection-slot.md

@@ -0,0 +1,100 @@
+---
+purpose: Add a repeating list whose items the editor selects and edits one at a time.
+status: living
+related: [../primitives.md, ../vocabulary.md, ../schema-system.md, bind-property-fact.md]
+updated: 2026-07-16
+---
+# A collection slot — a repeating, per-item list
+
+## Goal
+
+Add a repeating list — a unit table, agent cards, a feature list, a gallery —
+whose items the editor selects and edits one at a time.
+
+## The delta
+
+Starting from the starter's `hero` section, add an `object_list` slot: a row of
+nested `item` slots that repeats. Bind the whole array to a list fact with
+`direct("units")` (a unit table) — the array is baked from the property, so it
+needs no `fill-spec.ts` decision, exactly like a fact-bound scalar
+([bind-property-fact.md](bind-property-fact.md)). Each item field binds to a
+per-row fact with its own `direct(...)`.
+
+```ts
+// schema.ts — a repeating list of units, after the `blurb` slot
+units: {
+  type: "object_list",
+  source: direct("units"),
+  editable_by_user: true,
+  required: true,
+  source_title_field: "unit_label",
+  display_name: "Units",
+  item: {
+    unit_label: { type: "text", size: "short", editable_by_user: true, display_name: "Unit", source: direct("unit_label") },
+    beds: { type: "number", editable_by_user: true, display_name: "Beds", source: direct("beds") },
+    baths: { type: "number", editable_by_user: true, display_name: "Baths", source: direct("baths") },
+    sqft: { type: "number", editable_by_user: true, display_name: "Sqft", source: direct("sqft") },
+    price: { type: "text", size: "short", format: "currency", editable_by_user: true, display_name: "Price", source: direct("price") },
+  },
+},
+```
+
+```tsx
+// Renderer.tsx — <Slot> marks the whole array, <SlotItem> marks each row
+import { Image, Section, Slot, SlotItem } from "@homepages/template-kit";
+
+// SectionProps types an object_list as Record<string, unknown>[], so narrow
+// each row to your item shape at the map site.
+type UnitRow = { unit_label: string; beds: number; baths: number; sqft: number; price: string };
+
+<Slot id="units" as="ul" className="mt-4 flex w-full flex-col divide-y">
+  {(slots.units as UnitRow[]).map((unit, i) => (
+    <SlotItem key={unit.unit_label} index={i} as="li" className="flex justify-between py-2">
+      <span>{unit.unit_label}</span>
+      <span>{unit.beds} bd · {unit.baths} ba · {unit.sqft} sqft · {unit.price}</span>
+    </SlotItem>
+  ))}
+</Slot>
+```
+
+```ts
+// fixtures.ts — supply the array from the golden property
+import { allPhotos, mkResponsive, sampleProperty } from "@homepages/template-kit/fixtures";
+// ...in base.slots:
+units: sampleProperty.units,
+```
+
+Two contracts to know before you widen this:
+
+- **`direct()` binds only a registry collection** — `units` or `contacts` (the
+  [List sources](../vocabulary.md#direct-sources)). For any other repeating data,
+  drop the `source` and give the slot a `produced_by` decision instead (see the
+  [fill-spec decision types](../schema-system.md#fill-spects--how-ai-fills-the-slots)).
+- **An `item` needs more than one field, or a non-scalar one** — a lone scalar
+  field is rejected; use a `list` slot for a flat list of scalars.
+
+`object_list` is one of four collection types. A gallery of framed photos is an
+`image_collection`, a flat scalar list is a `list`, neighborhood points are a
+`poi_list` — same `<SlotItem>` render pattern, different value shape. See
+[the slot types](../vocabulary.md#slot-types) for which to pick.
+
+## 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
+
+- [Contract primitives](../primitives.md#slotitem--the-per-item-handle-in-a-collection) —
+  the `SlotItem` / `SlotGroup` contract: both markers a collection needs, and why
+  `index` must be the row's array position.
+- [The closed vocabulary](../vocabulary.md#slot-types) — every collection slot type
+  (`object_list` / `image_collection` / `poi_list` / `list`) and the `direct()` List sources.
+- [The schema system](../schema-system.md#fill-spects--how-ai-fills-the-slots) — the
+  `produced_by` decision types (`structured-list`, `list-extract`, `image-collection`)
+  for a collection AI fills instead of binding to a fact.
+- [Bind a slot to a property fact](bind-property-fact.md) — the `direct()` pattern this
+  extends from a scalar to a whole array.

package/docs/recipes/fill-spec-decision.md

@@ -0,0 +1,66 @@
+---
+purpose: Have AI write a slot's content.
+status: living
+related: [../schema-system.md]
+updated: 2026-07-15
+---
+# Have AI write a slot's content
+
+## Goal
+
+Have AI write a slot's content.
+
+## The delta
+
+Add a `decisions` entry to `fill-spec.ts` and point the slot's `produced_by`
+at its `id` — the same pattern the starter's `blurb` slot already uses. The
+`text-block` type is the common case: it fills a `text` slot with generated
+prose.
+
+```ts
+// fill-spec.ts — a text-block decision, same shape as the starter's blurb_text
+{
+  id: "summary_text",
+  type: "text-block",
+  produces: ["summary"],
+  length_cap: 200,
+  // `structure` enum is single_sentence | paragraph | bullet_list.
+  structure: "paragraph",
+  perspective: "third",
+  voice_prompt: "Write a warm, concrete paragraph a buyer would want to read.",
+  content_prompt: "Summarize the property's standout feature in 1–2 sentences.",
+},
+```
+
+```ts
+// schema.ts — the slot names the decision by id
+summary: {
+  type: "text",
+  size: "long",
+  editable_by_user: true,
+  required: true,
+  produced_by: "summary_text",
+  display_name: "Summary",
+},
+```
+
+`text-block` is one of several decision types — the others include
+`image-assign`, `image-collection`, `text-seed`, `list-extract`, and
+`structured-list`, each producing a differently-shaped slot value. This
+recipe covers the common text case; see [the schema
+system](../schema-system.md#fill-spects--how-ai-fills-the-slots) for the
+full decision-type contract before reaching for one of the others.
+
+## 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 schema system](../schema-system.md#fill-spects--how-ai-fills-the-slots) —
+  the full `fill-spec.ts` contract, every decision type, and how `produces`
+  maps back to `produced_by`.

package/docs/recipes/fixture-states.md

@@ -0,0 +1,68 @@
+---
+purpose: Preview a section's structural edge cases.
+status: living
+related: [../schema-system.md, ../dev.md]
+updated: 2026-07-15
+---
+# Preview a section's structural edge cases
+
+## Goal
+
+Preview a section's structural edge cases.
+
+## The delta
+
+Add entries under `states` in `fixtures.ts` — each one overrides part of
+`base`, the same pattern the starter's `left` and `long-blurb` states use.
+A `states` entry is for a DESIGNED scenario, not raw coverage: nullability
+and empty-slot coverage (every optional slot rendered empty) is derived
+automatically from `schema.ts`, so a fixture state is for a case the
+section renders *differently* — a content-length branch, an option branch,
+or several overrides combined.
+
+```ts
+// fixtures.ts — a content-length case and an option-branch case
+const fixtures: FixtureModule = {
+  base: {
+    slots: {
+      headline: "101 Queensway, Jamaica Plain, MA 02130",
+      summary: "A bright corner home moments from the Emerald Necklace.",
+    },
+    options: { align: "center" },
+  },
+  states: {
+    // Content-length branch: exercises a long value's wrap/expand behavior.
+    "long-summary": {
+      slots: {
+        summary:
+          "A bright corner home moments from the Emerald Necklace, with a " +
+          "chef's kitchen, three sun-filled bedrooms, off-street parking, and " +
+          "a landscaped yard that backs onto a quiet dead-end street.",
+      },
+    },
+    // Option branch: exercises the layout under the other enum value.
+    left: { options: { align: "left" } },
+  },
+};
+```
+
+Each `states` key names a scenario; its value overrides `slots` and/or
+`options` on top of `base` — omit either key to inherit `base`'s value
+unchanged. Each state is a selectable fixture in the dev preview, so every one
+you add is there to render and review alongside `base`.
+
+## 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 schema system](../schema-system.md#fixturests--content-for-local-preview) —
+  the `fixtures.ts` contract: `base`, `states`, and the golden-property
+  fixture exports.
+- [`template-kit dev`](../dev.md) — the preview server that renders each
+  fixture state across the breakpoint ladder.

package/docs/recipes/image-slot-crop.md

@@ -0,0 +1,98 @@
+---
+purpose: Add an image slot the editor crops to a fixed ratio.
+status: living
+related: [../schema-system.md, ../primitives.md, ../rules/image-bare-needs-reason.md]
+updated: 2026-07-15
+---
+# Image slot with a locked crop
+
+## Goal
+
+Add an image slot the editor crops to a fixed ratio.
+
+## The delta
+
+Starting from the starter's `hero` section, add a second `image` slot shaped
+like `hero_image` — a `crop` config, an `image-assign` decision, an `<Image>`
+in the Renderer, and a fixture value.
+
+```ts
+// schema.ts — a second image slot, same shape as hero_image, own aspect
+interior_image: {
+  type: "image",
+  editable_by_user: true,
+  required: true,
+  produced_by: "interior_image_assign",
+  display_name: "Interior image",
+  crop: { mode: "locked", aspect: 4 / 3, aspectLabel: "4:3" },
+},
+```
+
+```ts
+// fill-spec.ts — the decision producing it
+{
+  id: "interior_image_assign",
+  type: "image-assign",
+  produces: ["interior_image"],
+  tag_query: "category:interior",
+  selection_prompt: "Pick a bright, decluttered interior shot.",
+},
+```
+
+```tsx
+// Renderer.tsx — copy the starter's <Image> usage for hero_image
+<Image
+  slotId="interior_image"
+  src={slots.interior_image.url}
+  responsive={slots.interior_image.responsive}
+  alt={slots.interior_image.alt}
+  className="w-full"
+/>
+```
+
+```ts
+// fixtures.ts — a photo + a matching mkResponsive() height
+const interiorImage = allPhotos[3]!;
+// ...
+interior_image: {
+  photo_id: interiorImage.id,
+  url: interiorImage.url,
+  alt: interiorImage.alt,
+  // Height set to a 4:3 ratio to match the slot's locked crop.
+  responsive: mkResponsive(interiorImage.url, 1600, 1200),
+},
+```
+
+An image slot supports two independent geometry configs — use one, not both, per
+slot:
+
+- **`crop`** — steers the editor's cropper only: `mode: "locked"` fixes an
+  `aspect` (w/h) and shows the `aspectLabel` pill; `mode: "free"` lets the user
+  resize any edge. This is what the recipe above uses.
+- **`frame`** — a per-breakpoint aspect (`desktop`/`mobile`, switching at a
+  declared `breakpoint`) that is the single source of truth for BOTH the
+  cropper's target ratio and the Renderer's own layout box (imported as a
+  shared constant on both sides — see [schema-system.md](../schema-system.md)).
+  Reach for `frame` instead of `crop` when the section's markup itself needs
+  to know the ratio (e.g. to size a wrapper), not just the editor.
+
+Either way, framing is baked into the served asset — the Renderer never
+applies an aspect ratio to the pixels itself; it only reads `url`, `alt`,
+`responsive` (and `mobile`) off the slot's `ImageValue`.
+
+## 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 schema system](../schema-system.md) — `ImageValue`, the fields a Renderer reads
+  vs. only carries, and `frame`.
+- [Contract primitives](../primitives.md#image--the-defensive-image-primitive) — the
+  `Image` primitive's full prop table.
+- [`image-bare-needs-reason`](../rules/image-bare-needs-reason.md) — the rule that fires
+  if you reach for `<Image bare>` instead of the framed default this recipe uses.

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.