@homepages/template-kit 0.1.0 → 0.3.0

package/docs/rules/schema-invalid.md

@@ -0,0 +1,96 @@
+---
+purpose: The template-kit/schema-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, fixtures-invalid.md, manifest-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/schema-invalid
+
+> `schema.ts` and `fill-spec.ts` are a matched pair. This is every check that makes sure
+> they actually agree.
+
+## Rule
+
+A section's `schema.ts` and `fill-spec.ts` must, together:
+
+- **parse** — each is `as const satisfies` its shape (`SectionSchemaShape`,
+  `FillSpecShape`); a value that doesn't satisfy it fails here with the parse error;
+- **cross-reference correctly** — every `fill-spec.ts` decision produces a slot that
+  actually exists in `schema.ts`, every `reads` entry names a real, author-declarable
+  facts key, every option's `affects_decisions`/`affects_slots` names a real decision or
+  slot;
+- **satisfy the closed per-type contracts** — an `object_list` slot's `item_order`
+  covers every field, a `select` slot's cases match its transform, a group's members are
+  slots that exist, and the rest of the per-slot-type rules the schema system documents.
+
+One violation is one diagnostic; a section with several wrong things reports all of them
+in the same run, not one per fix.
+
+This is the id you also see when a section **cannot be built or parsed at all** — a
+syntax error in `schema.ts`, a missing export, an import that doesn't resolve. The
+message in that case is the underlying build error, relocated to the file it points at.
+
+## Reason
+
+`fill-spec.ts` is not free-standing — every decision it declares exists to fill a slot
+`schema.ts` declared, and every fact it reads must be one the platform actually exposes.
+A decision that produces a slot no schema declares, or reads a fact that doesn't exist,
+is not a style problem: the fill pipeline would either drop the output on the floor or
+crash trying to read a fact key that isn't there. Catching the mismatch here, at author
+time, is the difference between a red check and a listing that silently fails to fill.
+
+## Fix
+
+Read the message: it names the section, the decision or slot in question, and what's
+wrong with it. Fix whichever side is actually stale — the schema, or the fill-spec.
+
+### Before
+
+```ts
+// sections/facts/schema.ts
+export const schema = {
+  meta: { displayName: "Facts" },
+  slots: {
+    year_built: { type: "text", required: false, produced_by: "year_built_text" },
+  },
+  options: {},
+} as const satisfies SectionSchemaShape;
+```
+
+```ts
+// sections/facts/fill-spec.ts
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    { id: "year_built_text", type: "text-block", produces: ["year_built_summary"], length_cap: 20 },
+    //                                                       ^ typo — schema.ts declares "year_built"
+  ],
+} as const satisfies FillSpecShape;
+```
+
+```text
+Section "facts": fill-spec decision "year_built_text" produces unknown slot "year_built_summary".
+```
+
+### After
+
+```ts
+// sections/facts/fill-spec.ts
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    { id: "year_built_text", type: "text-block", produces: ["year_built"], length_cap: 20 },
+  ],
+} as const satisfies FillSpecShape;
+```
+
+## See also
+
+- [The schema system](../schema-system.md) — the full authoring contract for `schema.ts`
+  and `fill-spec.ts`.
+- [`fixtures-invalid`](fixtures-invalid.md) — the sibling gate on the third contract
+  file, `fixtures.ts`.
+- [`manifest-invalid`](manifest-invalid.md) — the same kind of cross-reference check, one
+  level up, on a template composing several sections.
+- [`bundle-incomplete`](bundle-incomplete.md) — reported instead of this id when a
+  contract file is missing outright, rather than present and wrong.

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.

package/docs/rules/single-react.md

@@ -0,0 +1,97 @@
+---
+purpose: The template-kit/single-react authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../islands.md]
+updated: 2026-07-14
+---
+# template-kit/single-react
+
+> Exactly one copy of `react` and one of `react-dom` in the installed tree. A second copy
+> breaks hydration **only in production** — never in your preview.
+
+## Rule
+
+The installed tree may contain **one** `react` and **one** `react-dom`. A nested duplicate
+anywhere under `node_modules` is a violation, whoever pulled it in.
+
+React is a **peer** dependency of the kit, not a bundled one: the kit ships against the
+React your workspace installs. So do your islands, and so does every React package you add.
+They all have to be the same React.
+
+## Reason
+
+React's hooks are not self-contained. `useState` does not hold your state — it dispatches
+through a **module-level** dispatcher that the currently-rendering React sets. Two copies of
+React on a page means two dispatchers, and an island rendered by one while hydrated by the
+other reads a dispatcher that is null or foreign. Hydration throws (`Invalid hook call` is
+the usual spelling), the island never comes alive, and whatever it was — the filter, the
+carousel, the lightbox — is inert on the page.
+
+**What makes this the worst kind of bug is where it shows up.** Islands are hydrated on the
+**published page**. In the editor, an island renders as static markup unless it opts into
+`live: true`, so it is never hydrated and the two Reacts never meet. Your preview is
+perfect. Your submission builds. The section is dead on the customer's site, and nowhere
+else.
+
+## Fix
+
+Get the tree back to one copy:
+
+1. **`npm dedupe`** — if the versions are compatible, npm hoists them to a single copy and
+   you are done.
+2. **Align your own range.** The kit's peer range is `react@^19` / `react-dom@^19`; if your
+   `package.json` pins something older, npm has no choice but to install two.
+3. **Deal with the package that pinned its own.** A dependency that depends on a React
+   *version range your React does not satisfy* will always get its own nested copy. Widen
+   its range if it has a newer release, or replace the package. There is no way to make two
+   Reacts coexist.
+
+Confirm with `npm ls react react-dom` — one entry each, no `deduped`-less nested copies.
+
+### Before
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "legacy-carousel": "^2.1.0"     // depends on react@^18
+  }
+}
+```
+
+```text
+$ npm ls react
+template-workspace
+├─┬ legacy-carousel@2.1.0
+│ └── react@18.3.1            ← a second React, nested
+└── react@19.1.0
+```
+
+### After
+
+`legacy-carousel` is replaced with a package whose peer range accepts React 19:
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "swiper": "^12.0.0"
+  }
+}
+```
+
+```text
+$ npm ls react
+template-workspace
+└── react@19.1.0
+```
+
+## See also
+
+- [Islands](../islands.md) — what gets hydrated on the published page, and what does not get
+  hydrated in the editor.
+- [`lockfile-stale`](lockfile-stale.md) — the other check that reads your installed tree.

package/docs/rules/size-renderer-bundle.md

@@ -0,0 +1,109 @@
+---
+purpose: The template-kit/size-renderer-bundle authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-section-css.md]
+updated: 2026-07-14
+---
+# template-kit/size-renderer-bundle
+
+> A section's renderer bundle must be **≤ 50 KB gzip**. The budget is not
+> author-overridable.
+
+## Rule
+
+Each section's renderer is bundled with esbuild and minified, with **React treated as
+external** (it is a peer, shared by the whole page, and is not counted against any one
+section). The gzipped result must be **50 KB or less**.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A template workspace cannot raise it, and there is no per-section
+exemption. If you go looking for the flag, this is the answer: there isn't one.
+
+## Reason
+
+The output is a real page for a real buyer, standing in a driveway on a phone. Bytes are the
+one cost the section cannot delegate.
+
+The number is set to be generous — roughly **twice** the largest section shipping today — so
+it does not fight ordinary authoring. You will not hit it by writing a rich section. You hit
+it when something **runaway** gets pulled in:
+
+- **a barrel import of an icon set**, which drags every icon into the bundle so you can use
+  three;
+- **a package that brings a font, a locale table, or a polyfill along with it**, none of
+  which you asked for.
+
+That is the shape of essentially every violation: not a section that grew, but a single
+import that was more expensive than it looked.
+
+## Fix
+
+Find the import that is not paying for itself.
+
+- **Import named symbols, never a namespace.** `import { ArrowRight } from "…"` is
+  tree-shakeable; `import * as Icons from "…"` is not — a namespace object has to contain
+  everything, so nothing can be dropped.
+- **Prefer the package's narrow entry** if it offers one.
+- **Hand-write the residue.** If you use one function out of a large utility package, copy
+  the function.
+
+**Do not try to hoist code out of the section to dodge the budget.** Each template owns its
+own presentation code; there is no shared library above a section to hoist it into, and the
+bytes would still land on the same page.
+
+### Before
+
+```tsx
+// sections/amenities/Renderer.tsx
+import { Section, Slot, SlotItem } from "@homepages/template-kit";
+import * as Icons from "lucide-react"; // ← the whole set: every icon, in the bundle
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="amenities">
+        {slots.amenities.map((item, i) => (
+          <SlotItem key={typeof item.id === "string" ? item.id : i} index={i} as="li">
+            <Icons.Check aria-hidden />
+            <h3>{typeof item.label === "string" ? item.label : null}</h3>
+          </SlotItem>
+        ))}
+      </Slot>
+    </Section>
+  );
+}
+```
+
+### After
+
+```tsx
+// sections/amenities/Renderer.tsx
+import { Section, Slot, SlotItem } from "@homepages/template-kit";
+import { Check } from "lucide-react"; // ← one icon, and the bundler can drop the rest
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="amenities">
+        {slots.amenities.map((item, i) => (
+          <SlotItem key={typeof item.id === "string" ? item.id : i} index={i} as="li">
+            <Check aria-hidden />
+            <h3>{typeof item.label === "string" ? item.label : null}</h3>
+          </SlotItem>
+        ))}
+      </Slot>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [`size-section-css`](size-section-css.md) — the same budget on the other half of what the
+  section ships.
+- [`license-denied`](license-denied.md) — the other reason to look hard at a dependency
+  before you take it.