@homepages/template-kit 0.1.0 → 0.2.0

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.

package/docs/rules/serializable-island-props.md

@@ -0,0 +1,146 @@
+---
+purpose: The template-kit/serializable-island-props authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, server-vs-client.md, ../islands.md, no-client-runtime-in-server.md]
+updated: 2026-07-14
+---
+# template-kit/serializable-island-props
+
+> Props handed to an island must be JSON-serializable. This rule is about what a file
+> *hands to* an island, so it has **no island exemption** — it runs everywhere.
+
+## Rule
+
+The rule looks at every JSX element whose component was imported from a file that is a
+real `"use client"` module on disk. On those elements — and only those — it reports any
+prop value it can statically see to be un-JSON-able:
+
+- **a literal function** — an arrow or a `function` expression (`onSelect={() => …}`);
+- **`new Anything()`** — `new Date()`, `new Map()`, `new Set()`, `new URL(…)`,
+  `new RegExp(…)`, `new YourClass()`. Everything except `new Object()` and `new Array()`,
+  which are plain and cross fine;
+- **a bigint literal** — `10n`;
+- **`NaN` and `Infinity`** — JSON has neither.
+
+It recurses into object and array literals, and names the exact path it found:
+`props.nested.deep.cb`, `props.units[0].created`.
+
+Carve-outs:
+
+- **A getter or setter in an object literal is skipped.** An accessor reads a value back
+  out; it never receives one across the boundary.
+- **A value handed over as a plain identifier is invisible.** `onPick={pick}` reports
+  nothing — the rule cannot see what `pick` is. That case is deliberately left to the
+  runtime check, which throws on it. The lint catches what it can see, early; the runtime
+  catches the rest.
+- **This rule stops at the island boundary — the preset does not.**
+  `<UnitTable onSelect={() => {}} />` is not reported *by this rule*, because
+  `UnitTable` is not an island and no prop crosses a serialization boundary. But inside
+  a server-rendered Renderer, that same line is still reported — by
+  [`no-client-runtime-in-server`](no-client-runtime-in-server.md), which bans any
+  `on*` JSX prop carrying a function on a non-island target, because the handler is
+  dropped from the published HTML regardless of what it's attached to. Moving a
+  handler off an island and onto an ordinary component doesn't clear the violation —
+  it trades this rule's error for that one.
+
+## Reason
+
+**Props are JSON on the wire.** An island is server-rendered inline with the page, and
+then its props are emitted next to it as a JSON script tag, which the browser parses back
+before hydrating. So a prop is not passed to the island — a *JSON round-trip of* the prop
+is.
+
+A function does not survive that trip. Neither does a `Date` (it becomes a string), a
+`Map` (it becomes `{}`), or `NaN` (it becomes `null`). The runtime refuses rather than
+shipping a corrupted prop: it throws `IslandPropsError`, naming the path. This rule says
+the same thing in your editor, in the same words, before the render ever runs.
+
+## Fix
+
+**Pass data, not behavior.** An island owns its own handlers, so it does not need yours.
+A `Date`/`Map`/`Set`/`RegExp` crosses as its plain-JSON equivalent — an ISO string, an
+array of entries — which you reconstruct inside the island. For `NaN`/`Infinity`, pass a
+finite number, or encode the sentinel as a string prop the island parses.
+
+That reconstruction step assumes the value is backed by real data. A `Date` built from a
+literal — `new Date(2020, 0, 1)`, with no slot behind it — has no reason to be a `Date`
+object on the server at all: write the ISO string (or just the year, or whatever the
+island actually needs) as a plain literal prop, and skip the round-trip entirely.
+
+### Before
+
+```tsx
+// sections/floorplan/Renderer.tsx
+import { Section } from "@homepages/template-kit";
+
+import UnitFilter from "./UnitFilter.js";
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <UnitFilter
+        units={slots.units}
+        onSelect={(id: string) => console.log(id)}
+        created={new Date()}
+      />
+    </Section>
+  );
+}
+```
+
+### After
+
+The handler moves inside the island, where it belongs. The date crosses as an ISO string
+and is rebuilt on the other side.
+
+```tsx
+// sections/floorplan/Renderer.tsx
+import { Section } from "@homepages/template-kit";
+
+import UnitFilter from "./UnitFilter.js";
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <UnitFilter units={slots.units} createdIso={slots.listed_at} />
+    </Section>
+  );
+}
+```
+
+```tsx
+// sections/floorplan/UnitFilter.tsx
+"use client";
+
+import { useState } from "react";
+
+type Unit = { id: string; label: string };
+
+export default function UnitFilter({ units, createdIso }: { units: Unit[]; createdIso: string }) {
+  const [selected, setSelected] = useState<string | null>(null);
+  const created = new Date(createdIso); // reconstructed inside the island
+  return (
+    <div>
+      <p>Listed {created.getFullYear()}</p>
+      <ul>
+        {units.map((u) => (
+          <li key={u.id}>
+            <button onClick={() => setSelected(u.id)}>{u.label}</button>
+          </li>
+        ))}
+      </ul>
+      {selected !== null && <p>Selected {selected}</p>}
+    </div>
+  );
+}
+```
+
+## See also
+
+- [Islands: props must be JSON-serializable](../islands.md#props-must-be-json-serializable) —
+  the full allowed/rejected table and the runtime error.
+- [Server vs client](server-vs-client.md) — how a file is scoped.
+- [`no-client-runtime-in-server`](no-client-runtime-in-server.md) — the rule that reports
+  an event-handler prop on a non-island target, since this one doesn't.

package/docs/rules/server-vs-client.md

@@ -0,0 +1,105 @@
+---
+purpose: The one concept the server-rendering rules assume — how a file is scoped server or client, and which rules stop at that boundary.
+status: living
+related: [INDEX.md, ../islands.md, ../eslint.md]
+updated: 2026-07-14
+---
+# Server vs client
+
+Several rules ban something "in server-rendered code" and say an island is exempt.
+This page is what "server-rendered" and "island" mean, once, so the rule pages do not
+each re-derive it.
+
+## Scoping is per file, by the directive
+
+A file is a **client module** if and only if its own directive prologue says
+`"use client"`. Nothing else decides it — not what it imports, not what imports *it*,
+not the directory it sits in, not a build transform.
+
+The consequence surprises people: **the same code fails in one file and passes in the
+file next to it.**
+
+```tsx
+// sections/hero/Renderer.tsx — no directive → server-rendered
+export function Renderer() {
+  return <p>{new Date().getFullYear()}</p>; // template-kit/no-nondeterminism
+}
+```
+
+```tsx
+// sections/hero/Clock.tsx — directive → island
+"use client";
+
+export default function Clock() {
+  return <p>{new Date().getFullYear()}</p>; // fine
+}
+```
+
+Importing an island from a server file does **not** make the server file an island. It
+also does not make the island a server file. Each is scoped on its own.
+
+## The prologue
+
+The directive prologue is the run of **leading string-literal statements**. Comments and
+blank lines do not end it; **any other statement does**.
+
+```tsx
+"use strict";
+"use client"; // still in the prologue → this file IS an island
+```
+
+```tsx
+const x = 1;
+"use client"; // real code ended the prologue → this is NOT a directive, and NOT an island
+```
+
+The second file is the trap. It looks like an island, it is not one, and every
+server-rendering rule still applies to it. If you meant it to be an island, the
+directive must be the first statement in the file.
+
+## What each side must be
+
+**A server-rendered file** (no directive) runs in the publisher and in the editor, and
+must be a **pure function of its props**: same props in, byte-identical HTML out. No
+clock, no randomness, no effects, no state, no event handlers, no network, no browser
+globals. It has none of those things available, and the two renders must agree.
+
+**An island** (with the directive) is server-rendered inline with the rest of the page
+and then **hydrated** in the browser as its own React root. Effects, state, event
+handlers, and inline `style` are all legal there — that is what an island is for. Its
+props cross the server→browser boundary as JSON, which is the one new constraint it
+takes on (see [`serializable-island-props`](serializable-island-props.md)).
+
+Interactivity is never banned. It is **relocated**: out of the server-rendered file, into
+a `"use client"` component in the same section folder, rendered from the Renderer like
+any other component.
+
+## Exactly three rules exempt islands
+
+| Rule | Exempt on a `"use client"` file? |
+|---|---|
+| [`no-nondeterminism`](no-nondeterminism.md) | **yes** — installs no visitors on an island |
+| [`no-client-runtime-in-server`](no-client-runtime-in-server.md) | **yes** |
+| [`no-inline-style`](no-inline-style.md) | **yes** |
+| every other rule | **no** — it runs on island files too |
+
+`no-hex` deliberately does **not** exempt islands. The three exemptions above are all
+server-render concerns, and an island runs in the browser. A palette is not a render-path
+concern: **the hydration boundary is not a palette boundary.** A section carries no
+palette of its own in either render path, so `"use client"` plus
+`style={{ color: "#ff0000" }}` passes `no-inline-style` and still fails
+[`no-hex`](no-hex.md).
+
+## The one rule scoped by filename
+
+[`no-client-directive-in-contract`](no-client-directive-in-contract.md) is governed by
+this boundary but is **not** scoped by the directive — it is scoped by **file glob**. It
+runs on a section's four contract files (`Renderer.tsx`, `schema.ts`, `fill-spec.ts`,
+`fixtures.ts`) and says those files may never carry the directive at all. They are the
+platform's interface to the section and are read outside a browser; making one an island
+would take the section's server-rendered HTML with it.
+
+## See also
+
+- [Islands](../islands.md) — writing one, its props contract, and its editor options.
+- [Rule index](INDEX.md) — every rule id, in both venues.

package/docs/rules/sidebar-order.md

@@ -0,0 +1,109 @@
+---
+purpose: The template-kit/sidebar-order 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/sidebar-order
+
+> The editor sidebar's cards are ordered by the **schema**. The page is ordered by your
+> **JSX**. They must agree — and when they don't, the schema is what moves.
+
+## Rule
+
+The editor renders one sidebar card per group (and one per ungrouped slot), in the order
+the schema declares them. This check server-renders the section's baseline fixture, reads
+the **first-appearance order of the slot markers** in the resulting HTML, and asserts that
+it matches the schema's declaration order.
+
+Three carve-outs, each of which looks like a bug if you don't know about it:
+
+- **A slot rendered more than once counts at its first marker.** An address shown in a
+  header and again in a footer is ordered by the header.
+- **Order *within* a group is not checked, and neither is contiguity.** A group's members
+  may appear in any order on the page, and other slots may sit between them. Responsive
+  layouts legitimately do both, and the sidebar collapses the group into one card anyway.
+- **A slot declared but never rendered is excluded.** It has no position on the page, so it
+  cannot contradict one.
+
+## Reason
+
+Two files describe the same section in two different orders, and only one of them is
+visible to the person editing. The failure mode is drift: you reorder the markup — move the
+eyebrow above the headline, promote the price — the schema keeps its original order, and
+the sidebar quietly stops matching the page.
+
+Nothing breaks. The section renders, the slots fill, and every card still works. The user
+just finds that the second card edits the first thing they see, and stops trusting the
+panel. This check makes that drift impossible to ship rather than merely unlikely.
+
+## Fix
+
+**Reorder the schema, not the page.** The page's visual order is the truth — it is what the
+user is looking at — so bring `schema.ts` to it: reorder the `slots` keys, and, if you have
+groups, the `meta.groups` entries, so declaration order matches the page's top-to-bottom
+order.
+
+### Before
+
+The schema declares `headline` first, the page renders `eyebrow` first:
+
+```ts
+// sections/hero/schema.ts — template-kit/sidebar-order
+import type { SectionProps, SectionSchemaShape } from "@homepages/template-kit";
+
+export const schema = {
+  meta: { displayName: "Hero" },
+  slots: {
+    headline: { type: "text", size: "medium", required: true, editable_by_user: true },
+    eyebrow: { type: "text", size: "short", required: false, editable_by_user: true },
+    price: { type: "text", size: "short", required: false, editable_by_user: true },
+  },
+} as const satisfies SectionSchemaShape;
+
+export type Props = SectionProps<typeof schema>;
+```
+
+```tsx
+// sections/hero/Renderer.tsx — the page, top to bottom: eyebrow, headline, price
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="eyebrow" textLeaf><p>{slots.eyebrow}</p></Slot>
+      <Slot id="headline" as="h1" textLeaf><span>{slots.headline}</span></Slot>
+      <Slot id="price" textLeaf><p>{slots.price}</p></Slot>
+    </Section>
+  );
+}
+```
+
+### After
+
+The Renderer is untouched. The schema moves:
+
+```ts
+// sections/hero/schema.ts
+import type { SectionProps, SectionSchemaShape } from "@homepages/template-kit";
+
+export const schema = {
+  meta: { displayName: "Hero" },
+  slots: {
+    eyebrow: { type: "text", size: "short", required: false, editable_by_user: true },
+    headline: { type: "text", size: "medium", required: true, editable_by_user: true },
+    price: { type: "text", size: "short", required: false, editable_by_user: true },
+  },
+} as const satisfies SectionSchemaShape;
+
+export type Props = SectionProps<typeof schema>;
+```
+
+## See also
+
+- [The schema system](../schema-system.md#grouping-slots-into-one-editor-card) — `meta.groups`,
+  whose entry order is the other half of the sidebar's card order.
+- [`missing-slot-marker`](missing-slot-marker.md) — the markers this check reads to
+  establish the page's order.