@homepages/template-kit 0.0.1 → 0.2.0

package/docs/rules/lockfile-stale.md

@@ -0,0 +1,88 @@
+---
+purpose: The template-kit/lockfile-stale authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, lockfile-missing.md]
+updated: 2026-07-14
+---
+# template-kit/lockfile-stale
+
+> The lockfile must satisfy `package.json`. If `npm ci` would fail, this fails first — on
+> your machine, where you can still do something about it.
+
+## Rule
+
+`package-lock.json` must be consistent with `package.json`: every dependency the manifest
+asks for is present in the lockfile, at a version its range accepts.
+
+Like [`lockfile-missing`](lockfile-missing.md), this is a property of the **workspace**, not
+of any one template, and is reported once.
+
+## Reason
+
+Your submission is installed with **`npm ci`**, which does not resolve versions — it
+installs exactly what the lockfile pins, and **aborts** if the lockfile and the manifest
+disagree. A lockfile that cannot reproduce the tree is not a slightly-out-of-date
+convenience file; it is an install that does not happen.
+
+Checking it here means you see it now. Otherwise the first thing to notice is the install
+on our side, and the first thing you hear is that your submission was rejected.
+
+There are two ways authors get here, and both are ordinary:
+
+- **Hand-editing a version in `package.json`** — bumping `^11.0.0` to `^12.0.0` in the
+  editor and never running an install.
+- **Merging a branch** and keeping only one side of the lockfile — resolving the conflict by
+  taking `package.json` from one branch and `package-lock.json` from the other. The two now
+  describe different trees.
+
+## Fix
+
+Run `npm install` — it resyncs the lockfile to the manifest — and commit the result. Do not
+hand-edit `package-lock.json`; regenerate it. If you got here from a merge conflict, take
+`package.json` first, then let `npm install` rebuild the lockfile from it.
+
+### Before
+
+`package.json` asks for Swiper 12; the lockfile still pins 11.
+
+```jsonc
+// package.json — hand-edited
+{
+  "dependencies": {
+    "swiper": "^12.0.0"
+  }
+}
+```
+
+```jsonc
+// package-lock.json — never regenerated
+{
+  "packages": {
+    "node_modules/swiper": { "version": "11.2.10" }
+  }
+}
+```
+
+`npm ci`: `Invalid: lock file's swiper@11.2.10 does not satisfy swiper@^12.0.0`.
+
+### After
+
+```bash
+npm install            # resolves ^12.0.0 and rewrites package-lock.json
+git add package.json package-lock.json
+```
+
+```jsonc
+// package-lock.json — back in sync
+{
+  "packages": {
+    "node_modules/swiper": { "version": "12.0.4" }
+  }
+}
+```
+
+## See also
+
+- [`lockfile-missing`](lockfile-missing.md) — there is no lockfile at all.
+- [`single-react`](single-react.md) — the other property of the installed tree the platform
+  checks before it builds your page.

package/docs/rules/missing-slot-marker.md

@@ -0,0 +1,140 @@
+---
+purpose: The template-kit/missing-slot-marker 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/missing-slot-marker
+
+> Every slot declared `editable_by_user: true` must be **marked** in the section's JSX.
+> An unmarked slot still fills and still renders — it just cannot be clicked.
+
+## Rule
+
+For each slot in `schema.ts` with `editable_by_user: true`, the section's JSX must carry a
+marker whose key is that slot id, written as a **string literal**. Any of these counts:
+
+| Marker | Example |
+|---|---|
+| `<Slot id>` | `<Slot id="headline" textLeaf>` |
+| `slotId` on a primitive that emits its own marker | `<Image slotId="hero_image" …>` |
+| a raw `data-slot-id` attribute | `<div data-slot-id="headline">` |
+
+The scan covers **every `.tsx` in the section folder**, not only `Renderer.tsx` — a marker
+inside a section-local component satisfies it. Test files are excluded.
+
+Carve-outs:
+
+- **A slot that is not `editable_by_user` needs no marker.** It cannot be selected in the
+  editor, so there is nothing to mark. (`editable_by_user` defaults to `false`.)
+- **A computed key does not satisfy the rule.** `<Slot id={fooKey}>` or an id produced
+  inside a `.map()` is not a literal, so the check cannot resolve it — and
+  [`slot-marker-literal`](slot-marker-literal.md) reports it separately. A `.map()`-generated
+  key therefore fails both at once.
+
+The practical corollary of the two above: when you hoist markup into a section-local
+helper, **do not pass the slot key through it as a prop**. `<Field slotKey="headline">`
+wrapping an inner `<Slot id={slotKey}>` erases the literal from the source entirely, and
+the slot reads as unmarked. Keep the literal `<Slot id="…">` where the slot is rendered
+and move only the data layer and leaf presentation out.
+
+## Reason
+
+The markers are the only thing connecting the pixels a user clicks to the schema key
+behind them. The editor's click resolver walks up from the clicked node looking for a
+`data-slot-id`; a slot that emits none is invisible to it.
+
+Nothing throws. The slot is filled by AI, it renders its content on the published page,
+and it looks completely correct — right up until a user clicks it in the editor and
+selects nothing. That is the whole failure: **fillable but not editable**, discovered by a
+customer rather than by you.
+
+## Fix
+
+Wrap the slot's outer DOM in `<Slot id="…">` — add `textLeaf` for a single-leaf text slot
+so the editor can write to it on each keystroke. An image slot needs no wrapper: give
+`<Image>` its `slotId` and it emits the marker itself.
+
+A raw `data-slot-id` attribute is not a lesser fallback — for the marker itself, it's
+identical to what `<Slot>` renders: `<Slot as="p" id="…">` emits exactly `<p
+data-slot-id="…">`, nothing more. The one thing `<Slot textLeaf>` adds is
+`data-slot-text-leaf` on the child, wired automatically, so the editor can patch text on
+every keystroke instead of waiting for the next server render. So default to `<Slot>` for
+the convenience — it's one prop instead of hand-wiring a second attribute — but writing
+`data-slot-id` directly on markup you're already hand-assembling is a legitimate, idiomatic
+fix, not a technicality; reach for it freely when you don't need `textLeaf`.
+
+If the slot genuinely is not meant to be edited, say so in the schema rather than leaving
+the check unsatisfied: `editable_by_user: false`.
+
+### Before
+
+```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, editable_by_user: true },
+    eyebrow: { 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 — template-kit/missing-slot-marker: eyebrow
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <p className="text-ink-mute">{slots.eyebrow}</p>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+### After
+
+```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="eyebrow" textLeaf>
+        <p className="text-ink-mute">{slots.eyebrow}</p>
+      </Slot>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+If `eyebrow` was never meant to be editable, the other legitimate fix is in the schema —
+and then no marker is needed:
+
+```ts
+eyebrow: { type: "text", size: "short", required: false, editable_by_user: false },
+```
+
+## See also
+
+- [Contract primitives](../primitives.md#the-marker-contract) — every marker attribute and
+  which primitive emits it.
+- [`slot-marker-literal`](slot-marker-literal.md) — why the key must be a literal for this
+  check to see it at all.
+- [`slot-group-marker`](slot-group-marker.md) — the same idea for a group of slots.

package/docs/rules/no-bare-css-import.md

@@ -0,0 +1,128 @@
+---
+purpose: The template-kit/no-bare-css-import 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/no-bare-css-import
+
+> No `@import` in hand-written CSS. **Not even a package's** — the browser drops it
+> silently, and the styles simply never ship.
+
+## Rule
+
+A hand-written stylesheet may not contain a top-level `@import`. That means the
+stylesheets the CSS build collects out of your section and template folders — a section's
+`styles.css`, any other `.css` in a section folder, and a template's own hand-written
+stylesheet.
+
+**There is no carve-out for a package specifier.** `@import "swiper/css";` is exactly as
+illegal here as `@import "./tokens.css";`. Both are reported, at the 1-based line of the
+first offender.
+
+The scan is comment-aware, so an `@import` written *about* rather than *as* code is prose
+and passes:
+
+```css
+/* css-reason: … */
+/* Never @import here — see template-kit/no-bare-css-import. */   ← fine, it's a comment
+```
+
+**Your Tailwind entry is not one of these files.** The file that carries
+`@import "tailwindcss";` and `@import "@homepages/template-kit/styles.css";` is a Tailwind
+entry: it is compiled by Tailwind, its `@import`s are resolved at build time, and it is
+never wrapped in a cascade layer. It is not hand-written section or template CSS, and this
+rule does not reach it.
+
+## Reason
+
+Every hand-CSS file the build collects is **concatenated into a cascade layer**:
+
+```css
+@layer sections {
+  /* your styles.css, pasted in here */
+}
+```
+
+That is how a section's CSS lands in the layer order (`theme, base, components, sections,
+template, utilities`) instead of fighting Tailwind's utilities for specificity.
+
+**`@import` is invalid inside a `@layer` block.** And CSS's error handling for an invalid
+at-rule is not an error — it is a shrug. The browser drops the statement and parses on.
+Nothing throws. Nothing warns. Your build succeeds, your preview looks *plausible* because
+the package's own styling is missing in a way you have learned to read as "unstyled yet",
+and the published page ships without the rules you imported. This is the quietest failure
+in the whole kit: the only signal is that the styles are not there.
+
+## Fix
+
+Delete the `@import`.
+
+**A package's stylesheet is reached from the code that needs it**, not from CSS. Write
+`import "swiper/css";` in the component, island, or enhancer that renders the thing — the
+CSS build bundles your `Renderer.tsx` and every marked enhancer, transitively, precisely to
+harvest those imports, and it compiles what they pull in into **this section's cascade
+layer**. Package CSS goes in first and your own hand-CSS second, so at equal specificity
+your rules win.
+
+Two things authors get wrong immediately after:
+
+- **Bare specifiers only.** A CSS import that resolves outside `node_modules` is an error,
+  not a fallback. Your own stylesheets are discovered by filename — importing one from code
+  would ship it twice. See
+  [`no-css-import-from-render-path`](no-css-import-from-render-path.md).
+- **Importing is not installing.** `import "swiper/css"` does not add `swiper` to your
+  `package.json`. Add the dependency, or the install that builds your submission has nothing
+  to resolve.
+
+### Before
+
+```css
+/* sections/gallery/styles.css */
+/* css-reason: styles the slide DOM the Swiper enhancer builds at runtime. */
+@import "swiper/css";              /* template-kit/no-bare-css-import — silently dropped */
+
+.tr-gallery .swiper-pagination-bullet-active {
+  background: var(--tr-color-primary);
+}
+```
+
+The pagination override ships. Swiper's own layout CSS does not — and no error says so.
+
+### After
+
+The `@import` is gone from the stylesheet:
+
+```css
+/* sections/gallery/styles.css */
+/* css-reason: overrides the Swiper pagination DOM the enhancer builds at runtime —
+   those nodes carry the library's own classes, which Tailwind's scanner never sees. */
+.tr-gallery .swiper-pagination-bullet-active {
+  background: var(--tr-color-primary);
+}
+```
+
+…and the package's CSS is imported from the module that needs it, which is what routes it
+into this section's layer:
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+import "swiper/css"; // ← the sanctioned channel: the CSS build harvests this import
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  // …
+}
+```
+
+## See also
+
+- [`no-css-import-from-render-path`](no-css-import-from-render-path.md) — the other half of
+  this mental model. Hand-written CSS: no `@import`s at all, package or otherwise. Render
+  path: no *local* CSS imports, but a package's bare specifier is exactly right. An author
+  who reads only one of the two pages will be confused by the other.
+- [`css-reason`](css-reason.md) — the comment every hand-written stylesheet opens with.
+- [Theme and CSS](../theme-and-css.md) — the cascade-layer order, and the one file that
+  legitimately does `@import "tailwindcss"`.

package/docs/rules/no-client-directive-in-contract.md

@@ -0,0 +1,111 @@
+---
+purpose: The template-kit/no-client-directive-in-contract authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, server-vs-client.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/no-client-directive-in-contract
+
+> A section's four contract files may never carry `"use client"`. This is the one rule
+> scoped by **filename**, not by the directive.
+
+## Rule
+
+The rule runs only on a section's four contract files — `Renderer.tsx`, `schema.ts`,
+`fill-spec.ts`, `fixtures.ts` — matched by glob. On one of those files, a `"use client"`
+string in the **directive prologue** is reported.
+
+The prologue is the run of leading string-literal statements (see
+[server vs client](server-vs-client.md)). Three consequences worth knowing:
+
+- **`"use strict"; "use client";` reports.** A second directive is still in the prologue.
+- **`const x = 1;` above `"use client"` does not report** — real code ended the prologue,
+  so that string is not a directive. This is a trap, not a loophole: the file is also
+  **not an island**, and every server-rendering rule still applies to it. It is a dead
+  string.
+- **`foo("use client")` is not a directive** — it is a call argument, and is ignored.
+
+Any other file in the section folder may carry the directive freely. That is exactly
+where interactivity belongs.
+
+## Reason
+
+The four contract files are the platform's interface to a section. They are read by the
+publisher, the editor, and the fill pipeline — **none of which is a browser**.
+`schema.ts` is loaded to learn what slots exist; `fill-spec.ts` to learn how AI fills
+them; `fixtures.ts` to render a preview; `Renderer.tsx` to produce the section's HTML.
+
+Marking one `"use client"` would make the whole section an island — and take the
+section's server-rendered HTML with it. The section would ship as an empty shell that
+only appears once JavaScript has run, which is precisely what a published property page
+must never do.
+
+## Fix
+
+Put the interactive part in its **own** `"use client"` component in the section folder,
+and render it from the Renderer. The contract file stays server-only; the island next to
+it does the browser work.
+
+### Before
+
+```tsx
+// sections/gallery/Renderer.tsx
+"use client";
+
+import { useState } from "react";
+
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Section>
+      <button onClick={() => setOpen(true)}>Open gallery</button>
+      {open && <p>{slots.headline}</p>}
+    </Section>
+  );
+}
+```
+
+### After
+
+```tsx
+// sections/gallery/Lightbox.tsx
+"use client";
+
+import { useState } from "react";
+
+export default function Lightbox({ headline }: { headline: string }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div>
+      <button onClick={() => setOpen(true)}>Open gallery</button>
+      {open && <p>{headline}</p>}
+    </div>
+  );
+}
+```
+
+```tsx
+// sections/gallery/Renderer.tsx — no directive; server-rendered again
+import { Section } from "@homepages/template-kit";
+
+import Lightbox from "./Lightbox.js";
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Lightbox headline={slots.headline} />
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [Server vs client](server-vs-client.md) — the directive, the prologue, and what an
+  island may do.
+- [Schema system](../schema-system.md) — what each of the four contract files is for.

package/docs/rules/no-client-runtime-in-server.md

@@ -0,0 +1,143 @@
+---
+purpose: The template-kit/no-client-runtime-in-server authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, server-vs-client.md, ../islands.md, serializable-island-props.md]
+updated: 2026-07-14
+---
+# template-kit/no-client-runtime-in-server
+
+> No effects, state, event handlers, network, or browser globals in server-rendered code.
+> Interactivity is not banned — it is **relocated** into an island. Islands are exempt.
+
+## Rule
+
+Whether a file is server-rendered or an island is decided per file, by the `"use client"`
+directive — see [server vs client](server-vs-client.md). On an island this rule installs
+no visitors at all.
+
+In a server-rendered file it reports three things:
+
+- **React hooks that only mean something in the browser** — `useEffect`,
+  `useLayoutEffect`, `useState`, `useReducer`, `useRef`, `useSyncExternalStore`,
+  `useImperativeHandle` — called bare (`useState(…)`) or namespace-qualified
+  (`React.useEffect(…)`).
+- **Browser globals read as a value** — `fetch`, `XMLHttpRequest`, `window`, `document`,
+  `localStorage`, `sessionStorage`, `navigator`. "Read as a value" is exact: the SSR-guard
+  idiom `typeof window !== "undefined"` **is** reported, while `cfg.window` (a property)
+  and `{ window: 1 }` (an object key) are not.
+- **Event-handler props** — any JSX prop matching `on[A-Z]…` whose value is an expression:
+  `onClick={…}`, `onChange={…}`, `onPointerMove={…}`.
+
+Carve-outs:
+
+- **Your own definitions are yours.** A name that resolves to a real local declaration —
+  `function fetch() {}`, your own `useRef` helper — is not the global or React's hook, and
+  is left alone.
+- **`onSurface={1}` and `onIcon={<Icon />}` are not handlers.** A prop whose value is
+  plainly a literal or a JSX element is not reported.
+- **A handler on an island is not reported here.** If the element's component resolves to
+  a real `"use client"` file on disk, this rule stays quiet:
+  [`serializable-island-props`](serializable-island-props.md) already speaks for that
+  prop, and "move it into a client component" would be nonsense advice for something that
+  already is one.
+
+## Reason
+
+A server-rendered file is run once, to a string of HTML, in a process that is not a
+browser. There is no `window` to read and no DOM to mutate; an effect never fires, and
+`useState` has no second render to give you. An event handler is worse than useless: it
+is a function, and a function cannot be serialized into HTML, so **it is silently dropped
+from the published page**. The button ships. The click does nothing. Nothing errors.
+
+So a Renderer must be a **pure function of its props**. Interactivity is not something the
+kit forbids — it is something the kit gives a specific home: a `"use client"` island,
+which is hydrated in the browser and is exempt from every one of these bans.
+
+## Fix
+
+Move the interactive markup into a `"use client"` component in the section folder, and
+render it from the Renderer with plain data props. The Renderer keeps the static markup
+and passes the island what it needs to do its job; the island owns the state and the
+handlers.
+
+### Before
+
+```tsx
+// sections/floorplan/Renderer.tsx
+import { useState } from "react";
+
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  const [beds, setBeds] = useState<number | null>(null);
+  const shown = beds === null ? slots.units : slots.units.filter((u) => u.beds === beds);
+  return (
+    <Section>
+      <button onClick={() => setBeds(2)}>2 beds</button>
+      <ul>
+        {shown.map((u) => (
+          <li key={u.id}>{u.label}</li>
+        ))}
+      </ul>
+    </Section>
+  );
+}
+```
+
+### After
+
+The state and the handler move into an island. Its props are plain data — see
+[`serializable-island-props`](serializable-island-props.md).
+
+```tsx
+// sections/floorplan/UnitFilter.tsx
+"use client";
+
+import { useState } from "react";
+
+type Unit = { id: string; label: string; beds: number };
+
+export default function UnitFilter({ units }: { units: Unit[] }) {
+  const [beds, setBeds] = useState<number | null>(null);
+  const shown = beds === null ? units : units.filter((u) => u.beds === beds);
+  return (
+    <div>
+      <button onClick={() => setBeds(2)}>2 beds</button>
+      <ul>
+        {shown.map((u) => (
+          <li key={u.id}>{u.label}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+```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} />
+    </Section>
+  );
+}
+```
+
+The import carries the **emitted** extension (`./UnitFilter.js`) while the file on disk is
+`UnitFilter.tsx` — that is TypeScript's ESM convention, and it is what the kit's rules
+resolve against.
+
+## See also
+
+- [Server vs client](server-vs-client.md) — how a file is scoped, and what an island may do.
+- [Islands](../islands.md) — writing one, its props contract, and its editor options.
+- [`serializable-island-props`](serializable-island-props.md) — the rule that instead
+  reports a function-valued prop when the target *is* an island.