@homepages/template-kit 0.1.0 → 0.2.0

package/docs/rules/INDEX.md

@@ -0,0 +1,58 @@
+---
+purpose: Router for the rule corpus — every template-kit/<id> an author can hit, and the page that explains it.
+status: living
+related: [server-vs-client.md, ../eslint.md, ../INDEX.md]
+updated: 2026-07-14
+---
+# Rules
+
+Every authoring rule the kit enforces is printed under one namespace, `template-kit/<id>`,
+and resolves to exactly one page here: `docs/rules/<id>.md`.
+
+**One namespace, two venues.** Some rules are properties of **one file** (a `Date.now()`
+in a Renderer) and are enforced by the ESLint preset. Others are properties of the
+**tree** (a slot declared in `schema.ts` but never marked in the JSX, a stylesheet, a
+dependency, a byte budget) and cannot be expressed one file at a time; those are enforced
+by `template-kit check`. You never need to know which engine produced a violation — only
+the id, which names its page either way.
+
+Read [server vs client](server-vs-client.md) first if you are here for any rule that
+mentions "server-rendered code" or an island. It is the one concept those rules assume,
+and it is explained there rather than on each of them.
+
+| Rule | Venue | What it enforces |
+|---|---|---|
+| [`no-nondeterminism`](no-nondeterminism.md) | eslint | No clock or randomness reads in server-rendered code. |
+| [`no-client-runtime-in-server`](no-client-runtime-in-server.md) | eslint | No effects, state, event handlers, network, or browser globals in server-rendered code. |
+| [`serializable-island-props`](serializable-island-props.md) | eslint | Props handed to an island must be JSON-serializable. |
+| [`no-client-directive-in-contract`](no-client-directive-in-contract.md) | eslint | No "use client" in a section's four contract files. |
+| [`props-from-schema`](props-from-schema.md) | eslint | A Renderer's Props type must be derived from schema.ts, not hand-written. |
+| [`no-inline-style`](no-inline-style.md) | eslint | No inline style= in server-rendered JSX. Islands are exempt. |
+| [`no-raw-element`](no-raw-element.md) | eslint | No raw `<section>` or `<img>` — use `<Section>` and `<Image>`. |
+| [`image-bare-needs-reason`](image-bare-needs-reason.md) | eslint | `<Image bare>` needs a `// bare:` comment saying why it skips the frame. |
+| [`slot-marker-literal`](slot-marker-literal.md) | eslint | A slot-marker key must be a string literal, not an expression. |
+| [`no-hex`](no-hex.md) | eslint | No hard-coded colours. Islands are NOT exempt. |
+| [`no-css-import-from-render-path`](no-css-import-from-render-path.md) | eslint | No relative/absolute .css import from a section's render path — a package's is the sanctioned channel. |
+| [`bundle-incomplete`](bundle-incomplete.md) | check | A section folder is missing one of its four required files. |
+| [`missing-slot-marker`](missing-slot-marker.md) | check | An editable slot in schema.ts has no marker in the section's JSX. |
+| [`slot-group-marker`](slot-group-marker.md) | check | A group with two or more members has no `<SlotGroup>` wrapper. |
+| [`css-reason`](css-reason.md) | check | A hand-written CSS file must open with a `css-reason:` comment. |
+| [`no-bare-css-import`](no-bare-css-import.md) | check | No @import in hand-written CSS — the browser drops it silently. |
+| [`unlayered-fence`](unlayered-fence.md) | check | An `/* unlayered: */` escape hatch must be balanced and give a reason. |
+| [`sidebar-order`](sidebar-order.md) | check | Schema slot order must match the order the page renders them in. |
+| [`typecheck`](typecheck.md) | check | The template must compile under TypeScript. |
+| [`determinism-drift`](determinism-drift.md) | check | Rendering the same fixture twice must produce byte-identical HTML. |
+| [`render-invariant`](render-invariant.md) | check | Rendered output must carry no [object Object], bare null/undefined/NaN leaf, or src-less `<img>`. |
+| [`lockfile-missing`](lockfile-missing.md) | check | The workspace has no package-lock.json. |
+| [`lockfile-stale`](lockfile-stale.md) | check | The lockfile does not satisfy package.json — an `npm ci` would fail. |
+| [`single-react`](single-react.md) | check | The installed tree carries more than one copy of react or react-dom. |
+| [`audit-severity`](audit-severity.md) | check | A dependency carries a high or critical security advisory. |
+| [`license-denied`](license-denied.md) | check | A production dependency's license is not on the allowlist. |
+| [`size-renderer-bundle`](size-renderer-bundle.md) | check | A section's renderer bundle exceeds its byte budget. |
+| [`size-section-css`](size-section-css.md) | check | A section's compiled CSS exceeds its byte budget. |
+
+## See also
+
+- [Server vs client](server-vs-client.md) — how a file is scoped, and which rules stop at
+  the hydration boundary.
+- [ESLint preset](../eslint.md) — setting the preset up in a template workspace.

package/docs/rules/audit-severity.md

@@ -0,0 +1,91 @@
+---
+purpose: The template-kit/audit-severity authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, license-denied.md]
+updated: 2026-07-14
+---
+# template-kit/audit-severity
+
+> A dependency with a **high** or **critical** advisory fails. Low and moderate pass, on
+> purpose. There is no way to suppress it.
+
+## Rule
+
+`npm audit` runs over your workspace, and a violation is reported for each advisory at
+severity **high** or **critical**.
+
+**Low and moderate advisories are a deliberate pass.** They are not "not yet enforced" —
+they are not enforced. Nobody will ask you to clear them.
+
+**There is no suppression mechanism.** No inline waiver, no ignore file, no severity
+override. If you are looking for the flag, there isn't one, and that is the design.
+
+## Reason
+
+The kit lets you reach for third-party packages — a carousel, a map SDK, a date formatter —
+because a section that has to hand-write everything is a section nobody finishes. The
+consequence is that your dependency tree ships to a published page we host for a customer,
+so the supply chain is part of the submission.
+
+This gate is the **floor**, not a review. Cutting at high/critical is what keeps it a floor:
+a rule that fired on every transitive moderate would be a rule everyone learned to route
+around, and the exception would swallow the check. Two severities, no exceptions, and a
+clear answer to "can I ship this."
+
+## Fix
+
+In order of preference:
+
+1. **`npm audit fix`** — resolves most advisories by moving a transitive dependency inside
+   its existing range.
+2. **Upgrade the offending package.** If the fix is in a new major, `npm audit fix --force`
+   will take it, but read what it changes first.
+3. **Drop the package.** An advisory with no fix available is a package with no fix
+   available. Replace it, or hand-write the part of it you actually use.
+
+Then re-run `npm audit` and commit the lockfile.
+
+### Before
+
+```text
+$ npm audit
+# npm audit report
+
+marked  <4.0.10
+Severity: high
+Inefficient Regular Expression Complexity in marked
+fix available via `npm audit fix --force`
+
+1 high severity vulnerability
+```
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "marked": "^3.0.8"
+  }
+}
+```
+
+### After
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "marked": "^14.1.2"
+  }
+}
+```
+
+```text
+$ npm audit
+found 0 vulnerabilities
+```
+
+## See also
+
+- [`license-denied`](license-denied.md) — the other supply-chain gate on your production
+  dependencies.
+- [`lockfile-stale`](lockfile-stale.md) — commit the lockfile the fix regenerated.

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/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.