@homepages/template-kit 0.3.0 → 0.4.0

package/docs/pack.md

@@ -0,0 +1,46 @@
+---
+purpose: The `template-kit pack` command — what it produces, what it refuses, and why.
+status: living
+related: [INDEX.md, check.md]
+updated: 2026-07-15
+---
+# template-kit pack
+
+Build a template's submission artifact: a zip of the template's source plus the
+workspace lockfile, validated and stamped.
+
+## Usage
+
+```bash
+template-kit pack <template>
+```
+
+Run it from the workspace root, or from inside a template folder (the template is
+inferred). In a workspace with several templates you must name one — the submission
+unit is a single template.
+
+## What it produces
+
+`<template>.zip` at the workspace root, containing:
+
+- `pack-manifest.json` — the exact kit version the source was validated against, a
+  content hash of the template tree, the pack timestamp, and a `check` flag
+  recording that validation passed.
+- `package.json` and `package-lock.json` from the workspace root, so the build is
+  reproducible with `npm ci`.
+- `templates/<template>/` — the template's source only (sections, manifest, theme,
+  README). No `node_modules`, no build output, no other template.
+
+## What it refuses
+
+`pack` will not produce 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 published versions.
+
+Fix the reported cause and run it again.
+
+## See also
+
+- [Check](check.md) — the gate `pack` runs before it will produce a zip.

package/docs/primitives.md

@@ -2,7 +2,7 @@
 purpose: The five contract primitives a section renderer must use, and the marker attributes they emit.
 status: living
 related: [schema-system.md, theme-and-css.md, eslint.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # Contract primitives
 
@@ -106,8 +106,8 @@ whole — no per-item selection, no per-item image cropping, no per-item live su
 `index` **must** be the item's zero-based position in the slot's array as rendered. The
 editor writes edits back by that index, so an index that doesn't match its position edits
 the wrong row. `index` is an array position, not a schema key, so unlike `Slot`'s and
-`SlotGroup`'s `id` it is exempt from the [`template-kit/slot-marker-literal`](eslint.md#markers-and-schema)
-lint rule.
+`SlotGroup`'s `id` it is exempt from the
+[`template-kit/slot-marker-literal`](rules/slot-marker-literal.md) lint rule.
 
 ## `SlotGroup` — slots edited as one unit
 
@@ -206,7 +206,6 @@ magic string.
 | `ATTR_SLOT_ITEM` | `data-slot-item` | one item of a collection slot |
 | `ATTR_SLOT_GROUP` | `data-slot-group` | the container wrapping a group's members |
 | `ATTR_SECTION_INSTANCE_ID` | `data-section-instance-id` | the section root — **written by the platform**, not by a primitive |
-| `ATTR_TR_ENHANCE` | `data-tr-enhance` | opt-in hook telling an enhancer to attach to this element |
 
 Changing what an attribute means is a platform contract break, so these names are stable
 across a major version of the kit.
@@ -215,5 +214,5 @@ across a major version of the kit.
 
 Renderers are pure functions of props: no fetches, no globals, no `useEffect` for data,
 no `Date.now()` / `Math.random()`. They are rendered to static markup by the publisher
-and re-mounted constantly by the editor. Interactivity that needs the browser attaches
-through `data-tr-enhance`, not through render-time side effects.
+and re-mounted constantly by the editor. Interactivity that needs the browser moves into
+a `"use client"` island (see [Islands](islands.md)), never into render-time side effects.

package/docs/quickstart.md

@@ -0,0 +1,102 @@
+---
+purpose: Zero to a rendered, checked section in under an hour, on the scaffolded starter.
+status: living
+related: [overview.md, dev.md, check.md, schema-system.md]
+updated: 2026-07-15
+---
+# Quickstart
+
+This walks the scaffolded starter template end to end: create a workspace, see
+its one section render, read how it's built, make one edit, and check it. It
+does not re-teach the authoring contract — see [Overview](overview.md) for the
+mental model and [Schema system](schema-system.md) for the four files in
+depth.
+
+## Create your workspace
+
+```bash
+npm create homepages-workspace@latest my-workspace
+```
+
+This stamps a workspace with one template, `starter`, and one section in it,
+`hero` — a working section built on the real contract, not a stub. See
+[Overview](overview.md) for what a workspace, template, and section are.
+
+## See it render
+
+```bash
+cd my-workspace
+npm run dev
+```
+
+This opens the **home launcher** in your browser: from there the **canvas
+mirror** renders the template with `starter`'s `hero` in it, and the
+full-template viewer shows the whole page. See [Dev](dev.md) for the launcher,
+the canvas mirror, and live reload.
+
+If you're an agent (or otherwise browser-less), hit the inspect endpoint
+instead — it returns each slot's fill state and a text outline of the render:
+
+```bash
+curl 'http://localhost:<port>/api/inspect?template=starter&section=hero&fixture=typical&format=text'
+```
+
+`typical` is the starter hero's baseline fixture; it also has `left` and
+`long-blurb` fixtures exercising an option and a content-length branch. See
+[Dev](dev.md#agent-facing-endpoints) for `/api/inspect` and the other
+agent-facing endpoints.
+
+## Read the worked example
+
+Before changing anything, read the four files that make up the starter's
+`hero` section — `templates/starter/sections/hero/`:
+
+- `schema.ts` — the slots (`hero_image`, `headline`, `blurb`) and the `align`
+  option, each comment explaining why it's declared the way it is.
+- `fill-spec.ts` — how AI fills `hero_image` and `blurb`; `headline` needs no
+  decision because it's fact-bound.
+- `fixtures.ts` — the `typical` baseline plus the `left`/`long-blurb` states.
+- `Renderer.tsx` — the markup, including the one interactive part: `blurb`
+  wrapped in a `"use client"` island.
+
+Each file is annotated in place. For the concepts behind them, see
+[Schema system](schema-system.md).
+
+## Make one edit
+
+Open `templates/starter/sections/hero/fixtures.ts` and change the `headline`
+value under `base`:
+
+```diff
+- headline: "101 Queensway, Jamaica Plain, MA 02130",
++ headline: "12 Elm Street, Jamaica Plain, MA 02130",
+```
+
+Save it. If `npm run dev` is running, any open preview of the `hero` section
+reloads with the new headline; re-running the `/api/inspect` call above also
+shows the new value.
+
+## Check it
+
+```bash
+npm run check
+```
+
+```
+✓ starter
+check passed
+```
+
+A green `check` is the acceptance gate — see [Check](check.md) for what its
+six stages verify and what a failure looks like.
+
+## The author loop
+
+Every section, and every change to one, runs the same three-step loop:
+
+1. **Edit** a section's files.
+2. **Preview** the result — `npm run dev` in a browser, or `/api/inspect` from
+   a terminal.
+3. **Check** it — `npm run check` — until it's green.
+
+Every recipe in this corpus ends by running this loop.

package/docs/recipes/INDEX.md

@@ -0,0 +1,27 @@
+---
+purpose: Task router — how do I… → the recipe.
+status: living
+related: []
+updated: 2026-07-16
+---
+# Recipes
+
+Every recipe is a **delta from the starter's `hero` section** — never a
+from-scratch file — ending in the same [author loop](../quickstart.md#the-author-loop)
+as everything else in this corpus: edit, preview, check. Find your task below and
+copy the shapes from its recipe, not from memory.
+
+| How do I… | Recipe |
+|---|---|
+| add an image slot the editor can crop | [`image-slot-crop.md`](image-slot-crop.md) |
+| fill a slot from a property fact without AI | [`bind-property-fact.md`](bind-property-fact.md) |
+| give the user a closed set of choices | [`select-slot.md`](select-slot.md) |
+| add a repeating list the user edits per item (unit table, cards, gallery) | [`collection-slot.md`](collection-slot.md) |
+| have AI write a slot's content | [`fill-spec-decision.md`](fill-spec-decision.md) |
+| preview a section's structural edge cases / states | [`fixture-states.md`](fixture-states.md) |
+| make part of a section interactive (an island) | [`interactive-island.md`](interactive-island.md) |
+| organize a section's files beyond the four reserved | [`organize-section-folder.md`](organize-section-folder.md) |
+| ship a static asset (image/svg/font) with a section | [`static-asset.md`](static-asset.md) |
+| use a third-party npm package in a section | [`third-party-package.md`](third-party-package.md) |
+| add another template to the workspace | [`second-template.md`](second-template.md) |
+| package a template for submission | [`prepare-submission.md`](prepare-submission.md) |

package/docs/recipes/bind-property-fact.md

@@ -0,0 +1,58 @@
+---
+purpose: Fill a slot from a known property fact, no AI.
+status: living
+related: [../vocabulary.md, ../schema-system.md, ../rules/schema-invalid.md]
+updated: 2026-07-15
+---
+# Bind a slot to a property fact
+
+## Goal
+
+Fill a slot from a known property fact, no AI.
+
+## The delta
+
+Give the slot a `source: direct("<field>")` instead of a `produced_by` — the
+same pattern the starter's `headline` already uses
+(`source: direct("address")`). Model it on an AI-produced slot you want to
+make fact-bound instead: swap its `produced_by` for `source`, and drop the
+matching decision from `fill-spec.ts`.
+
+```ts
+// schema.ts — was produced_by: "blurb_text"
+blurb: {
+  type: "text",
+  size: "long",
+  editable_by_user: true,
+  required: true,
+  source: direct("lot_size"),
+  display_name: "Blurb",
+},
+```
+
+Then delete the now-unused `blurb_text` decision from `fill-spec.ts`'s
+`decisions` array — a `direct()`-bound slot needs none; the fact is baked in
+at fill time, and the [`schema-invalid`](../rules/schema-invalid.md) check
+rejects a slot that declares both `source` and `produced_by`.
+
+The same pattern works for any slot type — pick a field whose runtime shape
+matches. For a `number` slot, `source: direct("beds")`; for `text`,
+`source: direct("address")` or any other text-shaped field in
+[the closed vocabulary](../vocabulary.md#direct-sources).
+
+## 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#direct-sources) — every `direct()` field,
+  grouped by what it resolves against.
+- [The schema system](../schema-system.md#binding-a-slot-to-a-property-fact) — the
+  `direct()`/`derived()` contract and why a bad name is a compile error.
+- [`schema-invalid`](../rules/schema-invalid.md) — fires if a slot declares both
+  `source` and `produced_by`, or neither.

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.