@homepages/template-kit 0.1.0 → 0.3.0

package/docs/rules/no-nondeterminism.md

@@ -0,0 +1,100 @@
+---
+purpose: The template-kit/no-nondeterminism 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/no-nondeterminism
+
+> No clock reads and no randomness in server-rendered code. Islands are exempt.
+
+## Rule
+
+Whether a file is server-rendered or an island is decided per file, by the `"use client"`
+directive — see [server vs client](server-vs-client.md). On an island this rule installs
+no visitors at all.
+
+In a server-rendered file, two shapes are banned:
+
+- **A read of a nondeterministic source**: `Date.now`, `Math.random`,
+  `crypto.randomUUID`, `crypto.getRandomValues`, `performance.now`. The member expression
+  alone is enough — `Date.now` reports even without a call, because handing the function
+  itself somewhere is the same read one hop later.
+- **`new Date()` with no arguments.** That reads the clock.
+
+Two carve-outs:
+
+- **`new Date(props.listed_at)` is fine.** It parses a value the section was *given*,
+  which is perfectly deterministic. Only the zero-argument form reads the clock.
+- **Your own definitions are yours.** If the object name resolves to a real local
+  declaration — `const performance = { now: () => 1 };` — it is not the global, and the
+  rule leaves it alone.
+
+## Reason
+
+The publisher and the editor both run a section's `Renderer`, and they must produce
+**byte-identical HTML** from the same props. A clock read or a random value makes the two
+renders disagree: the section's output is hashed, so a `Date.now()` in the markup means
+the section looks changed on every single render — a fresh version each publish, and an
+editor canvas that never settles.
+
+An island does not have this problem. It runs in the browser, after hydration, and its
+output is nobody's content hash. That is why it is exempt.
+
+## Fix
+
+Compute the value **at fill time** and pass it in as a slot value — that is the right
+route for anything that is content. Reach for an island only when the value is genuinely
+live (a countdown, a "time since listed" that must tick).
+
+### Before
+
+```tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+      <p>© {new Date().getFullYear()} — all rights reserved</p>
+    </Section>
+  );
+}
+```
+
+### After
+
+The year is content, so it becomes a slot the fill pipeline supplies. Declare it in
+`schema.ts`, and the Renderer just renders what it was given:
+
+```tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+      <Slot id="copyright_year" textLeaf>
+        <p>© {slots.copyright_year} — all rights reserved</p>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+If the value must be live in the browser rather than baked at fill time, move that
+markup into a `"use client"` component in the section folder instead, and render it from
+the Renderer — the rule does not run there.
+
+## See also
+
+- [Server vs client](server-vs-client.md) — how a file is scoped, and what an island may do.
+- [Schema system](../schema-system.md) — declaring the slot the value arrives in.

package/docs/rules/no-raw-element.md

@@ -0,0 +1,100 @@
+---
+purpose: The template-kit/no-raw-element authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../primitives.md]
+updated: 2026-07-14
+---
+# template-kit/no-raw-element
+
+> **Exactly two** raw elements are banned: `<section>` and `<img>`. Every other tag is
+> yours.
+
+## Rule
+
+Two tags, and no others:
+
+| Raw tag | Use instead |
+|---|---|
+| `<section>` | `<Section>` |
+| `<img>` | `<Image>` |
+
+That is the entire rule. **`<a>`, `<h1>`–`<h6>`, `<div>`, `<ul>`, `<button>`, `<picture>`,
+`<figure>` — every other element is yours to write.** Presentation is the template's own
+JSX; the kit is not trying to own your markup. If you have concluded "the kit bans raw
+HTML", that is exactly backwards.
+
+There is no island exemption: the two tags are banned in a `"use client"` file too.
+
+## Reason
+
+Each of the two banned tags has a **contract-bearing primitive that must emit it**, and
+writing the raw tag skips the contract.
+
+- **`<Section>`** emits `<section class="tr-section">`, which is full-bleed by contract:
+  100% width, zero padding, zero margin, so consecutive sections butt edge-to-edge and a
+  page composes as a clean vertical stack. A raw `<section>` lacks that class, so the
+  page grows gaps the template never asked for.
+- **`<Image>`** owns the responsive `<picture>` (per-format AVIF/WebP `srcset`, the
+  mobile crop, `sizes`), the aspect-ratio box, and the neutral fallback rect that keeps
+  the layout box when `src` is empty. A raw `<img>` with a null `src` is a collapsed box
+  or a broken-image icon on a real customer's page — and a missing image is a **supported
+  state**, not a bug: it happens whenever a listing is thin. `<Image slotId>` also emits
+  the slot marker itself, so the image stays selectable in the editor.
+
+The two tags are banned because they are the two the platform has to be able to trust.
+Everything else carries no contract, so nothing is gained by policing it.
+
+## Fix
+
+Import the primitive from the package root and use it:
+
+```tsx
+import { Section, Image } from "@homepages/template-kit";
+```
+
+### Before
+
+```tsx
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <section>
+      <h2>{slots.headline}</h2>
+      <img src={slots.hero_image.url ?? ""} alt={slots.hero_image.alt} />
+    </section>
+  );
+}
+```
+
+### After
+
+```tsx
+import { Image, Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <h2>{slots.headline}</h2>
+      <Image
+        slotId="hero_image"
+        src={slots.hero_image.url}
+        alt={slots.hero_image.alt}
+        responsive={slots.hero_image.responsive}
+        aspectRatio="5 / 3"
+      />
+    </Section>
+  );
+}
+```
+
+The `<h2>` stays exactly as it was. `Image` takes `src`/`alt` directly — a `null` or empty
+`src` is a supported state it renders a fallback rect for, so no `?? ""` guard is needed.
+
+## See also
+
+- [Contract primitives](../primitives.md) — all five primitives and the markers they emit.
+- [`image-bare-needs-reason`](image-bare-needs-reason.md) — the escape hatch that drops
+  `<Image>`'s frame, and what it costs.

package/docs/rules/no-templates.md

@@ -0,0 +1,87 @@
+---
+purpose: The template-kit/no-templates authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, manifest-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/no-templates
+
+> A run that gates nothing must never report success. This is what a workspace with no
+> template to check reports instead of a silent pass.
+
+## Rule
+
+`templates/` must hold at least one template folder — for the run you asked for:
+
+- `template-kit check` (no argument, from the workspace root): `templates/` has no
+  folder in it at all.
+- `template-kit check --all`: same — no template folder exists to check.
+- `template-kit check <name>` (or a bare `check` run from inside a template's own
+  folder): that one named template does not exist. (A folder that exists but is
+  missing its `manifest.json` is a different, more specific failure —
+  [`manifest-invalid`](manifest-invalid.md) — because a folder under `templates/` is a
+  template whatever else is wrong with it.)
+
+This is checked once per run, scoped to the workspace, not to any one template.
+
+## Reason
+
+`every()` over an empty set is vacuously true. A `check` run that selected zero templates
+and reported "check passed" would exit 0 having run not one gate — indistinguishable from
+a workspace that passed every rule, when in truth no rule ran at all. Anything that
+re-runs this command on your behalf (an ingest pipeline, a CI step) would accept that
+silence as a clean submission.
+
+Reporting a diagnostic instead means "nothing to check" is a failure your run surfaces,
+not a false green light.
+
+## Fix
+
+Add a template: `templates/<key>/` with a `manifest.json` declaring its section
+composition, and a `sections/` folder holding the sections it composes. If you meant to
+check a specific template and named it wrong, or ran `check` from a folder that isn't a
+template folder, correct the name or your working directory instead.
+
+### Before
+
+```text
+my-workspace/
+  package.json
+  package-lock.json
+  templates/            ← empty
+```
+
+```text
+$ template-kit check
+✗ workspace — 1 problem(s)
+    [template-kit/no-templates] This workspace has no template to check: templates/ holds no template folder.
+    fix: Add a template: templates/<key>/ with a manifest.json declaring its section composition and a sections/ folder holding the sections it composes.
+```
+
+### After
+
+```text
+my-workspace/
+  package.json
+  package-lock.json
+  templates/
+    acme-modern/
+      manifest.json
+      sections/
+        hero/
+          Renderer.tsx
+          schema.ts
+          fill-spec.ts
+          fixtures.ts
+```
+
+```text
+$ template-kit check
+✓ acme-modern
+check passed
+```
+
+## See also
+
+- [`manifest-invalid`](manifest-invalid.md) — the check that takes over once a template
+  folder exists, on whether its `manifest.json` is present and correct.

package/docs/rules/parse-error.md

@@ -0,0 +1,76 @@
+---
+purpose: The template-kit/parse-error authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, typecheck.md]
+updated: 2026-07-14
+---
+# template-kit/parse-error
+
+> A file so broken it never became an AST. Every other rule needs one; this is what's
+> reported when there isn't one to have an opinion about.
+
+## Rule
+
+Every other lint rule runs against a parsed file — an AST it can walk and ask questions
+of. When a `.ts`/`.tsx` file cannot even be parsed (invalid syntax: an unclosed brace, a
+stray token, a JSX tag that never closes), there is no AST for any rule to run against,
+and no rule id of its own to report. This id is what's reported in that one case instead:
+the parser's own message, relocated to the file and line it names.
+
+This is the only diagnostic under this id — it is not a rule you can violate by writing
+working code a particular way, the way `no-hex` or `no-inline-style` are. It exists so
+that "the file didn't parse" is a rule-id and a fix hint, not silence or a raw crash.
+
+## Reason
+
+A stage never aborts the run — an author fixing one file's problem must see every other
+file's problems in the same run, not discover them one release at a time. A parser
+exception is the one case where that promise is hardest to keep: there is genuinely
+nothing else to check about a file that doesn't parse. Reporting it under its own id,
+rather than dropping it or letting it throw, keeps that promise intact.
+
+You may see the **same file** flagged here and under
+[`typecheck`](typecheck.md): the lint stage and the typecheck stage each parse the
+workspace independently, and a syntax error fails both parsers, so both stages report it,
+each in their own words. Fixing the syntax error clears both.
+
+## Fix
+
+Read the message — it is the parser's own error, naming the file and the line. Fix the
+syntax at that location.
+
+### Before
+
+```tsx
+// sections/hero/Renderer.tsx
+export function Renderer() {
+  return (
+    <Section>
+      <h1>{headline}</h1>
+    </Section
+  );
+}
+```
+
+```text
+sections/hero/Renderer.tsx:6
+  Parsing error: '>' expected.
+```
+
+### After
+
+```tsx
+// sections/hero/Renderer.tsx
+export function Renderer() {
+  return (
+    <Section>
+      <h1>{headline}</h1>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [`typecheck`](typecheck.md) — the sibling failure one layer up: a file that parses but
+  does not type-check.

package/docs/rules/props-from-schema.md

@@ -0,0 +1,119 @@
+---
+purpose: The template-kit/props-from-schema 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/props-from-schema
+
+> A Renderer's props type is **derived** from `schema.ts`, never hand-written in the
+> Renderer.
+
+## Rule
+
+The rule runs only on `Renderer.tsx`. It reports an **exported** type alias or interface
+whose name **ends in `Props`** — `Props`, `HeroProps`, `GalleryProps`.
+
+Two consequences of that being the whole test:
+
+- **It does not read the right-hand side.** Even `export type Props = SectionProps<typeof
+  schema>;` reports *if you write it in the Renderer*. The derivation belongs in
+  `schema.ts`; the Renderer **imports** it.
+- **A non-exported local type is invisible** to the rule. An internal
+  `type Row = { id: string };` used to type a helper's parameter is your business, and is
+  not reported.
+
+`import type { Props } from "./schema.js";` is the shape the rule is steering you to, and
+it reports nothing.
+
+## Reason
+
+The schema is the section's single source of truth, and the prop type is **inferred from
+it** — `SectionProps<typeof schema>` reads the schema literal and resolves each slot to
+its runtime value shape: a required `text` becomes `string`, an optional one
+`string | null`, an `image` becomes `ImageValue`, and so on.
+
+A hand-written `Props` shadows that inference, and then **drifts silently**. Add a slot
+to `schema.ts` and forget to render it: with the derived type, reading `slots.subhead` in
+the Renderer is a compile error until the slot exists, and the platform's tooling and
+your renderer agree by construction. With a hand-written `Props`, the Renderer keeps
+compiling happily against the old shape — while the editor, the fill pipeline, and the
+schema all now believe in a slot your markup has never heard of. Nothing fails until a
+user is looking at a page with a missing block in it.
+
+It also forces the editor to reason about a second definition of the same thing.
+
+## Fix
+
+Declare the derived type once in `schema.ts` and import it in the Renderer:
+
+```ts
+export type Props = SectionProps<typeof schema>;
+```
+
+```ts
+import type { Props } from "./schema.js";
+```
+
+### Before
+
+```tsx
+// sections/hero/Renderer.tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+export type Props = {
+  slots: { headline: string };
+};
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+### After
+
+```ts
+// sections/hero/schema.ts
+import type { SectionProps, SectionSchemaShape } from "@homepages/template-kit";
+
+export const schema = {
+  meta: { displayName: "Hero" },
+  slots: {
+    headline: { type: "text", size: "medium", required: true, produced_by: "headline_text" },
+  },
+} as const satisfies SectionSchemaShape;
+
+export type Props = SectionProps<typeof schema>;
+```
+
+```tsx
+// sections/hero/Renderer.tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+The `as const satisfies SectionSchemaShape` is load-bearing: without it the literal types
+are widened away and `SectionProps` can no longer tell a required slot from an optional
+one.
+
+## See also
+
+- [Schema system](../schema-system.md) — the schema literal, `SectionProps` inference,
+  and the four contract files.

package/docs/rules/render-invariant.md

@@ -0,0 +1,165 @@
+---
+purpose: The template-kit/render-invariant authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../primitives.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/render-invariant
+
+> Three things must never reach a published page: `[object Object]`, a bare
+> `null`/`undefined`/`NaN`, and an `<img>` with no source. Every one of them is garbage a
+> real buyer would see.
+
+## Rule
+
+Every section is server-rendered against every fixture in its invariant corpus, and the
+output is checked for three defects:
+
+1. **The text `[object Object]`**, anywhere in the rendered HTML.
+2. **A text leaf that is exactly `null`, `undefined`, or `NaN`.** The match is on the whole
+   leaf, so prose that merely contains the word ("null and void") is safe.
+3. **An `<img>` whose `src` is absent, empty, `"undefined"`, or `"null"`.**
+
+The corpus is your `base` fixture, each of your `states` fixtures, and one **synthesized**
+fixture per optional slot with that slot set to its empty value (`null` for a scalar or an
+image, `[]` for a list) — derived from the schema, not declared by you.
+
+The check is deliberately biased toward **false negatives**: it would rather miss a bug than
+invent one. Everything it reports is a real defect, so there is nothing here to argue with
+or configure around.
+
+## Reason
+
+**Your fixtures are richer than the content a real listing gets filled with.** That is the
+whole story, and almost every violation of this rule is a version of it.
+
+You wrote `fixtures.ts` from a property you had in front of you: twelve units, a year
+built, a hero photo, an agent headshot. The fill engine, on a thin listing, bakes in what
+actually exists — which may be no units array at all, no year, no photo. Your preview looks
+perfect, your states look perfect, and the section still renders `Built undefined` on a
+real customer's page, or throws on `slots.units.map` because `units` is `null`.
+
+This is precisely why the corpus adds the synthesized nullability fixtures. They are
+adversarial inputs, not designed states: they render your section against exactly the thin
+content your own fixtures never showed you.
+
+So the rule to internalize is not "avoid these three strings." It is: **an absent slot is
+routine, not exceptional** — and your markup has to say what happens then.
+
+### Where the three defects actually come from
+
+Worth being precise, because the obvious guesses are wrong. Rendering a nullish slot as a
+**child** is safe: React renders `null` and `undefined` as nothing, so `<p>{slots.year_built}</p>`
+on a thin listing is an empty `<p>`, not the text `undefined`. And a list slot is **never
+`null`** — `list`, `object_list`, `poi_list` and `image_collection` always arrive as an array
+(empty when absent), so `.map` cannot throw and `?? []` buys you nothing.
+
+The defects come from three narrower places:
+
+- **String coercion.** A template literal, `String(x)`, `"" + x`, `.join()`, or **any JSX
+  string attribute** (`alt`, `title`, `aria-label`, `src`) turns `null` into `"null"`, an
+  absent field into `"undefined"`, and an object into `"[object Object]"`. Coercion is what
+  React's own child handling was protecting you from.
+- **Arithmetic on an absent number.** `null * 1.05` is `NaN`, and React renders `NaN` as
+  text.
+- **`<Image bare>` with no source.** Framed `<Image>` emits no `<img>` at all when `src` is
+  empty — it renders its fallback rect. `bare` forfeits that and ships `<img src="">`.
+
+## Fix
+
+- **Never coerce a slot into a string.** Branch on it and render the surrounding text as
+  markup, or guard it before it reaches a template literal or an attribute.
+- **Guard arithmetic** behind a `typeof x === "number"` check.
+- **Format an `object_list` row's fields** — they are typed `unknown`, so pick, check, and
+  format each one; never interpolate the row.
+- **Let framed `<Image>` handle a missing image**, and reach for `bare` only where the source
+  is guaranteed.
+
+### Before
+
+```tsx
+// sections/units/Renderer.tsx
+import { Image, Section, Slot, SlotItem } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      {/* coerced: an absent year_built lands in the heading as the text "null" */}
+      <h2>{`${slots.headline} — built ${slots.year_built}`}</h2>
+
+      <Slot id="units">
+        {slots.units.map((unit, i) => (
+          <SlotItem key={String(unit.id)} index={i} as="li">
+            {/* coerced: a unit with no price renders "2 Bed · undefined" */}
+            <h3>{`${unit.label} · ${unit.price}`}</h3>
+            {/* arithmetic on an absent sqft: NaN, rendered as text */}
+            <p>{Number(unit.sqft) * 1.05} sq ft heated</p>
+          </SlotItem>
+        ))}
+      </Slot>
+
+      {/* bare: the card grid already sizes the thumbnail. */}
+      <Image bare src={slots.floorplan?.url ?? ""} alt="Floor plan" />
+    </Section>
+  );
+}
+```
+
+On the golden property this renders perfectly. On a listing with no year, an unpriced unit,
+and no floor plan it ships `built null`, `2 Bed · undefined`, `NaN sq ft heated`, and
+`<img src="">`.
+
+### After
+
+```tsx
+// sections/units/Renderer.tsx
+import { Image, Section, Slot, SlotItem } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <h2>
+        {slots.headline}
+        {slots.year_built ? ` — built ${slots.year_built}` : null}
+      </h2>
+
+      <Slot id="units">
+        {slots.units.map((unit, i) => (
+          <SlotItem key={typeof unit.id === "string" ? unit.id : i} index={i} as="li">
+            <h3>
+              {typeof unit.label === "string" ? unit.label : null}
+              {typeof unit.price === "number" ? ` · ${unit.price}` : null}
+            </h3>
+            {typeof unit.sqft === "number" ? (
+              <p>{Math.round(unit.sqft * 1.05)} sq ft heated</p>
+            ) : null}
+          </SlotItem>
+        ))}
+      </Slot>
+
+      <Image
+        slotId="floorplan"
+        src={slots.floorplan?.url ?? null}
+        alt={slots.floorplan?.alt ?? ""}
+        aspectRatio="4 / 3"
+      />
+    </Section>
+  );
+}
+```
+
+Every coercion now sits behind a check, and the image is framed: a null `src` renders the
+fallback rect, holding the layout box and keeping the slot selectable instead of shipping a
+source-less `<img>`.
+
+## See also
+
+- [Contract primitives: `Image`](../primitives.md#image--the-defensive-image-primitive) — what
+  the frame does with a missing source, and why `bare` forfeits it.
+- [`typecheck`](typecheck.md) — the same class of bug, caught earlier, for the cases the
+  types can see.
+- [`determinism-drift`](determinism-drift.md) — the other check that runs over this corpus.