@homepages/template-kit 0.0.1 → 0.2.0

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.

package/docs/rules/license-denied.md

@@ -0,0 +1,106 @@
+---
+purpose: The template-kit/license-denied authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, audit-severity.md]
+updated: 2026-07-14
+---
+# template-kit/license-denied
+
+> Every package in your **production** tree must carry a license from a fixed allowlist.
+> There is no per-package override.
+
+## Rule
+
+Each package in the production dependency tree must declare a license on this list:
+
+| Allowed |
+|---|
+| `MIT` |
+| `ISC` |
+| `Apache-2.0` |
+| `BSD-2-Clause` |
+| `BSD-3-Clause` |
+| `0BSD` |
+| `Unlicense` |
+| `CC0-1.0` |
+
+Two cases people expect to slide through, and neither does:
+
+- **`SEE LICENSE IN <file>` is a denial**, not a pass. The check cannot read the file, so
+  it cannot clear the terms.
+- **A missing `license` field is a denial**, not a pass. An unlicensed package is not a
+  permissive one — by default, no rights are granted at all.
+
+**Scope: the production tree only.** `devDependencies` are not evaluated — your bundler,
+your test runner, and your formatter do not ship to anyone.
+
+**There is no per-package override.** No allowlist entry you can add, no waiver comment. By
+design.
+
+## Reason
+
+Your template's production dependencies are compiled into a page we host, and serve, on
+behalf of a paying customer. Their license terms become terms we are shipping under. A
+license we cannot clear in advance is a license we cannot ship — so the check is a
+gate rather than a warning, and the list is the set we have already cleared.
+
+## Fix
+
+**Replace the package** with an equivalent whose license is on the list. That is the only
+fix, and for the overwhelming majority of what a section needs there is an MIT or Apache-2.0
+alternative.
+
+One legitimate adjacent fix: if the package is genuinely **build-time only** — it never
+reaches the published bundle — then it belongs in `devDependencies` anyway, and
+`devDependencies` are not evaluated. Be honest about this. If your published page imports
+it, it is a production dependency no matter which stanza it is listed under, and moving it
+is a bug in your `package.json` rather than a fix.
+
+### Before
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "fancy-charts": "^3.2.0"      // "license": "GPL-3.0-only"  → denied
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}
+```
+
+### After
+
+```jsonc
+// package.json
+{
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "lightweight-charts": "^4.2.0"   // "license": "Apache-2.0" → allowed
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}
+```
+
+```bash
+npm uninstall fancy-charts
+npm install lightweight-charts
+```
+
+Confirm what a package declares before you commit to it:
+
+```bash
+npm view <package> license
+```
+
+## See also
+
+- [`audit-severity`](audit-severity.md) — the other gate on the packages you ship.
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the third: what those packages cost the
+  page in bytes.

package/docs/rules/lockfile-missing.md

@@ -0,0 +1,68 @@
+---
+purpose: The template-kit/lockfile-missing authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, lockfile-stale.md]
+updated: 2026-07-14
+---
+# template-kit/lockfile-missing
+
+> Your workspace must have a committed `package-lock.json`. Without one, your submission
+> cannot be installed at all.
+
+## Rule
+
+There must be a `package-lock.json` at the **workspace root**.
+
+This is checked once per run, not once per template. A workspace has one `package.json` and
+one lockfile, however many templates and sections live inside it — so this violation is
+reported once and fixed once.
+
+A `yarn.lock` or a `pnpm-lock.yaml` does not satisfy it. The install is `npm ci`, and
+`npm ci` reads `package-lock.json`.
+
+## Reason
+
+The platform installs your submission with **`npm ci`** — the reproducible install, which
+takes the tree the lockfile pins and does not resolve anything itself. It requires a
+lockfile, and refuses to run without one.
+
+That is the whole point of the requirement: the tree that is built, bundled, audited, and
+published is byte-for-byte the tree you tested against. No lockfile, no reproducible tree,
+no build — and "works on my machine" would otherwise be the only thing standing behind a
+page a customer is paying for.
+
+## Fix
+
+Run `npm install` and **commit the lockfile**. If it is being ignored, stop ignoring it —
+that is the single most common cause of this violation, and the ignore rule is almost always
+inherited from a template `.gitignore` that was written for an application, not a package.
+
+### Before
+
+```gitignore
+# .gitignore
+node_modules/
+dist/
+package-lock.json      ← the lockfile never gets committed
+```
+
+`npm ci` on the checked-out submission: `The 'npm ci' command can only install with an
+existing package-lock.json`.
+
+### After
+
+```gitignore
+# .gitignore
+node_modules/
+dist/
+```
+
+```bash
+npm install            # regenerates package-lock.json from package.json
+git add package-lock.json
+```
+
+## See also
+
+- [`lockfile-stale`](lockfile-stale.md) — the lockfile exists but no longer reproduces the
+  tree `package.json` asks for.