@homepages/template-kit 0.1.0 → 0.3.0

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

@@ -0,0 +1,102 @@
+---
+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
+---
+# template-kit/bundle-binary-asset
+
+> A section folder holds code, not static files. A binary asset dropped into it has no
+> build meaning yet.
+
+## 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:
+
+- **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.
+
+## 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.
+
+## 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.
+
+### Before
+
+```text
+sections/hero/
+  Renderer.tsx
+  schema.ts
+  fill-spec.ts
+  fixtures.ts
+  assets/
+    arrow.svg          ← binary asset in the bundle
+```
+
+```tsx
+// sections/hero/Renderer.tsx
+import arrowUrl from "./assets/arrow.svg";
+
+export function Renderer() {
+  return <img src={arrowUrl} alt="" className="h-4 w-4" />;
+}
+```
+
+### After
+
+```text
+sections/hero/
+  Renderer.tsx
+  schema.ts
+  fill-spec.ts
+  fixtures.ts
+  components/
+    ScrollArrow.tsx     ← markup, not a binary file
+```
+
+```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.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.

package/docs/rules/bundle-incomplete.md

@@ -0,0 +1,117 @@
+---
+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
+---
+# template-kit/bundle-incomplete
+
+> A section folder is **yours**. Its only structural requirement is that four contract
+> files exist at its root.
+
+## Rule
+
+A section folder must contain these four, **as files, at the folder root**:
+
+| File | Declares |
+|---|---|
+| `schema.ts` | the slots and options the section has |
+| `fill-spec.ts` | how AI fills those slots |
+| `fixtures.ts` | sample content for local preview |
+| `Renderer.tsx` | the markup |
+
+Each missing file is one violation, so a folder holding only a `Renderer.tsx` reports
+three times.
+
+Two near-misses do **not** satisfy it:
+
+- a **directory** named `schema.ts/` — the check wants a file;
+- a file at `components/schema.ts` — the four are looked for at the folder root, not
+  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
+opinion about them, and neither does the rest of the kit.
+
+## Reason
+
+The four files are the platform's entire interface to a section. The publisher reads
+`schema.ts` to know what the section contains, the fill pipeline reads `fill-spec.ts` to
+fill it, preview reads `fixtures.ts`, and `Renderer.tsx` is the markup. A folder missing
+one of them cannot be loaded as a section.
+
+That freedom has one non-obvious consequence, worth knowing before it surprises you:
+**every file in the folder is part of the section's identity.** The content hash covers
+the whole folder, not just the four — so editing a helper, a util, or even a comment
+produces a new section version on the next publish, exactly as editing `Renderer.tsx`
+would.
+
+## Fix
+
+Create the missing file at the folder root. A section that fills nothing still needs a
+`fill-spec.ts`; a section with no designed states still needs a `fixtures.ts`. Declaring
+"nothing to fill" is a declaration.
+
+### Before
+
+```text
+sections/hero/
+  Renderer.tsx
+  schema.ts
+  components/
+    Headline.tsx
+```
+
+Two violations: `fill-spec.ts` and `fixtures.ts` are missing. `components/` is not one of
+them — it was never a problem.
+
+### After
+
+```text
+sections/hero/
+  Renderer.tsx
+  schema.ts
+  fill-spec.ts        ← added
+  fixtures.ts         ← added
+  components/
+    Headline.tsx
+```
+
+```ts
+// sections/hero/fill-spec.ts
+import type { FillSpecShape } from "@homepages/template-kit";
+
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    {
+      id: "headline_text",
+      type: "text-block",
+      produces: ["headline"],
+      length_cap: 60,
+      structure: "single_sentence",
+      voice_prompt: "Confident premium-listing voice. Title Case.",
+    },
+  ],
+} as const satisfies FillSpecShape;
+```
+
+```ts
+// sections/hero/fixtures.ts
+import type { FixtureModule } from "@homepages/template-kit";
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: { headline: "A mansard Victorian in the heart of Jamaica Plain" },
+  },
+};
+
+export default fixtures;
+```
+
+## See also
+
+- [The schema system](../schema-system.md) — what each of the four files declares, and
+  the types they satisfy.
+- [`missing-slot-marker`](missing-slot-marker.md) — the check that runs once the four
+  exist: every editable slot in `schema.ts` has a marker in the JSX.

package/docs/rules/css-reason.md

@@ -0,0 +1,94 @@
+---
+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
+---
+# template-kit/css-reason
+
+> Hand-written CSS is the escape hatch from Tailwind, so every stylesheet must **open**
+> with a comment saying what it escapes for.
+
+## Rule
+
+Every hand-written `.css` file — a section's `styles.css`, any other `.css` in a section
+folder, and the template's own `styles.css` — must **begin** with a block comment
+containing the token `css-reason:`.
+
+Three ways to get this wrong:
+
+- **The comment is not first.** The token must be in the file's *leading* comment.
+  Mentioning `css-reason:` further down, after a rule, does not pass.
+- **The comment is a `//` line.** `//` does not open a comment in CSS. It is not a comment
+  at all — it is a parse error waiting to happen, and it does not satisfy this check.
+- **The file is in a subdirectory and you assumed it was exempt.** CSS is collected **by
+  path, not by import**: the build walks the whole section folder. A stylesheet at
+  `sections/map/styles/markers.css` is gated — and published — exactly like `styles.css`.
+
+The token is all that is checked, but the sentence after it is the point. Write it for the
+next author.
+
+## Reason
+
+Tailwind is the default, and it is the default for a reason: a utility class is scoped to
+the element it sits on, participates in the cascade layers the platform already orders,
+and cannot leak into another section on the same page. Hand-written CSS gives all of that
+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
+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.
+
+We cannot cheaply prove that a given rule is *inexpressible* as a utility — so the check
+enforces the half of the bar that is checkable: **you have to say which un-scannable DOM
+you are styling.** A stylesheet that cannot name one is almost always a stylesheet whose
+rules should have been utility classes, and a reasonless file leaves the next author
+unable to tell the difference.
+
+## Fix
+
+Make the first thing in the file a block comment that names the DOM Tailwind cannot see.
+If you find you cannot name one, that is the answer: delete the CSS and use utility
+classes on the markup.
+
+### Before
+
+```css
+/* sections/neighborhood-map/styles.css */
+.tr-map-marker {
+  display: grid;
+  place-items: center;
+  border-radius: var(--tr-radius-full);
+  background: var(--tr-color-primary);
+}
+```
+
+### After
+
+```css
+/* css-reason: styles the marker DOM the neighborhood-map enhancer 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 {
+  display: grid;
+  place-items: center;
+  border-radius: var(--tr-radius-full);
+  background: var(--tr-color-primary);
+}
+```
+
+And the case where the fix is not a comment at all — this rule *is* expressible as
+utilities, so the stylesheet goes away and the classes move onto the element:
+
+```tsx
+<div className="grid place-items-center rounded-full bg-primary" />
+```
+
+## See also
+
+- [Theme and CSS](../theme-and-css.md) — the token namespace utilities compile from, and
+  the layer order hand-CSS lands in.
+- [`no-bare-css-import`](no-bare-css-import.md) — the other constraint on a hand-written
+  stylesheet: no `@import`, ever.
+- [`unlayered-fence`](unlayered-fence.md) — the escape hatch *within* the escape hatch.

package/docs/rules/determinism-drift.md

@@ -0,0 +1,112 @@
+---
+purpose: The template-kit/determinism-drift authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, server-vs-client.md]
+updated: 2026-07-14
+---
+# template-kit/determinism-drift
+
+> The same fixture, rendered twice, must produce **byte-identical** HTML. This is the
+> runtime back-stop to `no-nondeterminism` — it catches what a linter cannot see.
+
+## Rule
+
+Every fixture in the section's invariant corpus is server-rendered **twice**, and the two
+outputs are compared byte for byte. Any difference is a violation.
+
+The corpus is broader than the fixtures you wrote:
+
+- your **`base`** fixture;
+- each of your **`states`** fixtures;
+- one **synthesized** fixture per **optional** slot, with that slot set to its empty value
+  (`null` for a scalar or an image, `[]` for a list).
+
+You do not declare that last set. Nullability coverage is derived from the schema — from
+`(type, required)` — so a nullable branch cannot be forgotten by forgetting to write a
+fixture for it.
+
+## Reason
+
+[`no-nondeterminism`](no-nondeterminism.md) bans the clock and randomness **in your code**.
+A linter reads one file at a time and can only report on what it can see, so it stops at
+your source. This check runs the render.
+
+That gap is where the real bugs live, and they arrive **through a package**. A helper that
+mints a fresh id per call. A library that iterates a hash and hands back a different order
+each time. Nothing in your Renderer looks nondeterministic — you never wrote `Math.random()`
+— but the output moves.
+
+It matters because the publisher and the editor **both** render the section and must agree.
+Byte-identical output is what makes a section's HTML content-addressable: the same content
+must hash to the same page. A section whose HTML changes on every render re-publishes
+forever and never converges.
+
+## Fix
+
+If the nondeterminism is your own: compute the value at **fill time** and pass it in as a
+slot value, or move the markup into a `"use client"` island — an island renders in the
+browser after hydration, and its output is nobody's content hash.
+
+If the nondeterminism came from a package: replace it, or give it a deterministic input.
+An id generator gets a stable id derived from props. A collection gets sorted before you
+map it.
+
+### Before
+
+```tsx
+// sections/facts/Renderer.tsx
+import { Section, Slot } from "@homepages/template-kit";
+import { nanoid } from "nanoid";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots, nav }: Props) {
+  const descriptionId = nanoid(); // ← a new id on every render; the HTML differs each time
+
+  return (
+    <Section id={nav.selfAnchor}>
+      <Slot id="headline" as="h1" textLeaf>
+        <span aria-describedby={descriptionId}>{slots.headline}</span>
+      </Slot>
+      <p id={descriptionId}>{slots.summary}</p>
+    </Section>
+  );
+}
+```
+
+Nothing here reads the clock or a random source, so no lint rule fires. The section still
+renders differently every single time.
+
+### After
+
+The id is derived from something the section was **given**, so it is the same on every
+render:
+
+```tsx
+// sections/facts/Renderer.tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots, nav }: Props) {
+  const descriptionId = `${nav.selfAnchor}-summary`;
+
+  return (
+    <Section id={nav.selfAnchor}>
+      <Slot id="headline" as="h1" textLeaf>
+        <span aria-describedby={descriptionId}>{slots.headline}</span>
+      </Slot>
+      <p id={descriptionId}>{slots.summary}</p>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [`no-nondeterminism`](no-nondeterminism.md) — the same ban, enforced in your editor, on the
+  code a linter can see.
+- [Server vs client](server-vs-client.md) — why a server-rendered file must be a pure
+  function of its props, and why an island is not.
+- [`render-invariant`](render-invariant.md) — the other check that runs over this same
+  fixture corpus.

package/docs/rules/fixtures-invalid.md

@@ -0,0 +1,96 @@
+---
+purpose: The template-kit/fixtures-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, schema-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/fixtures-invalid
+
+> `fixtures.ts` is the one contract file nothing else parses for you. This is that parse.
+
+## Rule
+
+The default export of `fixtures.ts` must satisfy the fixture-module shape:
+
+```ts
+{
+  base: {
+    slots: { /* every required slot, with a valid value */ },
+    options: { /* optional */ },
+    anchors: { /* optional */ },
+    variants: { /* optional */ },
+  },
+  option_matrix: [ /* optional: { label?, options } entries */ ],
+  states: { /* optional: named scenario → { label?, slots?, options?, anchors?, variants? } */ },
+}
+```
+
+`base` is required and must be an object holding a `slots` record — every other key is
+optional. Each violation names the exact path inside the module that's wrong (`"base"`,
+`"base.slots"`, `"states.empty-address"`, …) and what shape was expected there instead.
+
+## Reason
+
+`schema.ts` and `fill-spec.ts` are both Zod-parsed on the way into every other check, so a
+malformed one is caught immediately. `fixtures.ts` used to be the exception: nothing
+touched it until the render stage read it directly, so a wrong shape there surfaced as a
+raw crash mid-render, blamed on whatever line happened to dereference the missing field —
+never on the fixture that was actually wrong.
+
+This gate exists to move that failure to where the mistake was made, with a message about
+the fixture module instead of a stack trace from three files away.
+
+## Fix
+
+Read the message's path — it points at the exact key that's wrong — and bring that key's
+shape in line with what's documented above.
+
+### Before
+
+```ts
+// sections/hero/fixtures.ts
+import type { FixtureModule } from "@homepages/template-kit";
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: { headline: "A mansard Victorian in the heart of Jamaica Plain" },
+  },
+  states: {
+    "no-photo": { slots: { hero_image: null }, label: 12 },
+    //                                                 ^ label must be a string
+  },
+};
+
+export default fixtures;
+```
+
+```text
+Section "hero": fixtures.ts — "states.no-photo.label": Expected string, received number.
+```
+
+### After
+
+```ts
+// sections/hero/fixtures.ts
+import type { FixtureModule } from "@homepages/template-kit";
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: { headline: "A mansard Victorian in the heart of Jamaica Plain" },
+  },
+  states: {
+    "no-photo": { slots: { hero_image: null }, label: "No hero photo" },
+  },
+};
+
+export default fixtures;
+```
+
+## See also
+
+- [The schema system](../schema-system.md) — `fixtures.ts`'s place among the section's
+  four contract files.
+- [`schema-invalid`](schema-invalid.md) — the sibling gate on `schema.ts` and
+  `fill-spec.ts`.
+- [`bundle-incomplete`](bundle-incomplete.md) — reported instead of this id when
+  `fixtures.ts` is missing outright, rather than present and wrong.

package/docs/rules/image-bare-needs-reason.md

@@ -0,0 +1,117 @@
+---
+purpose: The template-kit/image-bare-needs-reason authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../primitives.md]
+updated: 2026-07-14
+---
+# template-kit/image-bare-needs-reason
+
+> `<Image bare>` needs a `// bare: <reason>` comment above it. **A reason cannot be spent
+> twice** — one comment documents exactly one element.
+
+## Rule
+
+Every `<Image bare …>` must have a qualifying reason comment. A comment qualifies when
+all three hold:
+
+1. **It contains `bare:`** — e.g. `// bare: the logo is chrome; the parent already sizes it.`
+2. **It sits strictly above the element, within 5 lines.** Above, not beside and not below.
+3. **It has not already been spent** on an earlier `<Image bare>`.
+
+Both comment forms count — a `//` line comment and a `{/* … */}` JSX comment. The rule
+reads the raw comment stream rather than hopping up the AST, so proximity survives
+arbitrary wrapping: a container `<div>`, a `.map()` callback, a parenthesized `return`, an
+assignment to a `const`. If it *looks* directly above the element, it counts.
+
+**The surprising part: a reason cannot be spent twice.** One comment above a row of
+sibling bare logos documents only the **first** of them; the second still reports. Each
+bare image is its own decision, so each gets its own sentence. (A comment written *between*
+two bare images is fine for the second — it starts after the first element ends.)
+
+## Reason
+
+Framed is `<Image>`'s default, and the frame is load-bearing: a wrapper `div` that holds
+the aspect-ratio box, carries the slot marker, and renders a neutral fallback rect when
+`src` is empty.
+
+`bare` drops all of it — one `<img>`, no wrapper. So a bare image with no source is
+**nothing at all**: the layout collapses, and whatever sat below it jumps up the page. A
+missing image is a supported state on this platform (a thin listing simply has no photo),
+so "the source is always there" is an assumption, not a fact.
+
+`bare` is still the right call sometimes — a logo whose parent already establishes the
+box, a slide inside its own aspect-ratio parent. The rule does not ban it; it makes you
+**say why the parent guarantees the box**, so the next author (or the next agent) can
+tell whether the frame is safe to restore.
+
+## Fix
+
+Put a `// bare: <reason>` comment immediately above the element. A reason is legitimate in
+either of two ways: it can name what **guarantees the layout box** without `<Image>`'s
+frame (a parent that already establishes the size, a slide inside its own aspect-ratio
+container) — or it can name something about the **image's own content** that makes the
+frame the wrong choice, such as a transparent PNG that framing would letterbox. If
+neither holds, drop `bare` and let `<Image>` frame it.
+
+### Before
+
+```tsx
+import { Image, Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="h-12 w-32">
+        <Image bare src={slots.brand_logo.url} alt={slots.brand_logo.alt} className="object-contain" />
+      </div>
+    </Section>
+  );
+}
+```
+
+### After
+
+```tsx
+import { Image, Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="h-12 w-32">
+        {/* bare: the logo is chrome; the parent already sizes it. */}
+        <Image bare src={slots.brand_logo.url} alt={slots.brand_logo.alt} className="object-contain" />
+      </div>
+    </Section>
+  );
+}
+```
+
+Two bare images need two comments — the first one's reason is spent:
+
+```tsx
+<div className="flex gap-4">
+  {/* bare: the primary logo is chrome; the row sizes it. */}
+  <Image bare src={slots.logo_a.url} alt={slots.logo_a.alt} className="h-8 object-contain" />
+  {/* bare: the partner logo is chrome; the row sizes it. */}
+  <Image bare src={slots.logo_b.url} alt={slots.logo_b.alt} className="h-8 object-contain" />
+</div>
+```
+
+A content-based reason is written the same way — only the sentence changes, because it's
+justifying a different thing (the image, not the layout around it):
+
+```tsx
+{/* bare: a transparent PNG badge; Image's frame would letterbox its transparent
+   padding against the section background. */}
+<Image bare src={slots.certification_badge.url} alt={slots.certification_badge.alt} className="h-10" />
+```
+
+## See also
+
+- [Contract primitives: `Image`](../primitives.md#image--the-defensive-image-primitive) —
+  framed vs bare, and what the frame does for you.
+- [`no-raw-element`](no-raw-element.md) — why `<img>` goes through `<Image>` at all.