@homepages/template-kit 0.0.1 → 0.2.0

package/docs/eslint.md

@@ -0,0 +1,55 @@
+---
+purpose: The authoring-lint preset shipped at `@homepages/template-kit/eslint` — setup and scope. Per-rule reference lives in `rules/`.
+status: living
+related: [INDEX.md, rules/INDEX.md, islands.md, theme-and-css.md, primitives.md]
+updated: 2026-07-14
+---
+# ESLint preset
+
+`@homepages/template-kit/eslint` is a flat-config ESLint preset carrying every
+authoring rule the kit enforces one file at a time, under the `template-kit/*`
+rule namespace.
+
+## Setup
+
+```js
+// eslint.config.mjs
+import kit from "@homepages/template-kit/eslint";
+export default kit;
+```
+
+That is the whole setup — no plugin registration, no parser wiring, no tsconfig.
+The preset ships its own parser (`@typescript-eslint/parser`, a real `dependency`
+of the kit, not a devDependency) and sets `languageOptions` itself, so `npm i -D
+eslint` plus the three lines above is a complete consumer config.
+
+The preset is **syntactic only** — it never sets `parserOptions.project` or
+`projectService`. Nothing it enforces requires type information, which is what
+keeps setup to zero extra config; a consumer's own `tsconfig.json` is never
+consulted.
+
+## Scope
+
+The preset is consumed **once at a workspace root** and lints every section
+nested under `templates/**`; there are no per-template config files. It ships
+three config entries, matched by glob rather than by directory depth:
+
+| Entry | Files | Rules |
+|---|---|---|
+| `template-kit/authoring` | `**/*.ts`, `**/*.tsx` | the nine file-scoped rules — see [`rules/`](rules/INDEX.md) |
+| `template-kit/contract-files` | `**/Renderer.tsx`, `**/schema.ts`, `**/fill-spec.ts`, `**/fixtures.ts` | `no-client-directive-in-contract` |
+| `template-kit/renderer` | `**/Renderer.tsx` | `props-from-schema` |
+
+Server-vs-client scoping is decided **per file**, by the `"use client"` directive
+prologue — see [server vs client](rules/server-vs-client.md) for what that means
+and exactly which rules stop at that boundary.
+
+## The rules
+
+Every rule the preset enforces — what it bans, why, and a before/after fix — is
+documented once, per id, in [`rules/`](rules/INDEX.md). Rules scoped to a single
+file are enforced here, by this preset; rules scoped to the **tree** — a missing
+contract file, a slot declared in `schema.ts` but unmarked in `Renderer.tsx`, a CSS
+budget — cannot be expressed one-file-at-a-time and belong to `template-kit check`
+under the same `template-kit/<id>` namespace. One namespace, two venues: the id
+printed by either failure resolves to exactly one page.

package/docs/islands.md

@@ -0,0 +1,150 @@
+---
+purpose: How interactivity works in a template — client components ("islands"), their props contract, and their editor options.
+status: living
+related: [INDEX.md, eslint.md]
+updated: 2026-07-14
+---
+
+# Islands: interactivity in a template
+
+A section's `Renderer.tsx` is server-rendered and ships no JavaScript. When part of
+a section needs to be interactive — a filter, a slider, a lightbox — you write an
+ordinary React component in the section folder and mark it `"use client"`. It is
+server-rendered with the rest of the page, then **hydrated** in the browser as its
+own React root. That component is an *island*.
+
+If a page contains no islands, it loads no React and no island code — every page
+still ships the small island loader (a few KB, gzipped), but that loader only ever
+reaches React through a dynamic import it takes when an island is actually on the page.
+
+## Writing one
+
+```tsx
+// sections/floorplan/UnitFilter.tsx
+"use client";
+
+import { useState } from "react";
+
+export default function UnitFilter({ units }: { units: { id: string; beds: number }[] }) {
+  const [beds, setBeds] = useState<number | null>(null);
+  const shown = beds === null ? units : units.filter((u) => u.beds === beds);
+  return ( /* … */ );
+}
+```
+
+Use it from the Renderer like any other component. The build wraps it in an island
+marker and hydrates it on the published page:
+
+```tsx
+import UnitFilter from "./UnitFilter.js";
+
+export function Renderer({ units }: Props) {
+  return <UnitFilter units={units} />;
+}
+```
+
+Rules:
+
+- **The component is default-exported.** One island per `"use client"` file.
+- **Effects, state, event handlers, and browser APIs are all fine** inside an island —
+  it runs in the browser. They are *not* fine in a Renderer, which must stay a pure
+  function of its props.
+- **Third-party client libraries are fine** inside an island (a slider, a map SDK).
+
+## Props must be JSON-serializable
+
+Everything the Renderer passes to an island crosses a server→browser boundary as JSON:
+
+| Allowed | Rejected |
+|---|---|
+| `string`, `number` (finite), `boolean`, `null` | functions, including event handlers |
+| plain objects, arrays, nested combinations of the above | `Date`, `Map`, `Set`, `BigInt`, symbols, class instances |
+| `undefined` values, per JSON: an object property is dropped, an array entry becomes `null` | `NaN`, `Infinity` |
+
+A rejected prop fails the render, naming the path:
+
+```
+IslandPropsError: props.units[0].created is a Date — island props must be
+JSON-serializable (plain objects and arrays only)
+```
+
+Pass an ISO string and parse it inside the island. Pass data, not callbacks — an
+island owns its own handlers.
+
+The `template-kit/serializable-island-props` [lint rule](eslint.md#islands) catches a
+statically-visible violation (a literal arrow function, `new Date()`, a bigint literal,
+`NaN`/`Infinity`) in your editor, before the render ever throws — a value assembled at
+runtime and handed over as an identifier is invisible to the rule and stays this
+runtime check's job.
+
+## Editor options
+
+Templates are edited in a canvas where the section is re-rendered on every keystroke.
+An island can declare how it behaves there:
+
+```tsx
+"use client";
+import type { IslandEditorOptions } from "@homepages/template-kit";
+
+export default function Accordion({ items, singleOpen }: Props) { /* … */ }
+
+export const editor: IslandEditorOptions = {
+  live: true,                            // hydrate in the editor canvas (default: false)
+  shieldMode: "fill-parent",             // how the editor sizes its selection shield
+  liveSurface: (root) => [...root.querySelectorAll(".accordion")], // shield only these
+  props: { singleOpen: true },           // editor-only props, merged over the real ones
+};
+```
+
+Omit `editor` entirely and the island simply renders as static markup in the editor —
+which is the right choice for most islands.
+
+## The DOM contract
+
+Rarely needed while authoring, but this is what the build emits, and what a host
+hydrates:
+
+```html
+<tr-island style="display:contents" data-tr-island="<key>" data-tr-island-id="<id>">
+  …server-rendered output…
+</tr-island>
+<script type="application/json" data-tr-island-props="<id>">{"units":[…]}</script>
+```
+
+The marker is layout-invisible (`display:contents`), so an island can sit directly
+inside a grid or flex container without adding a box.
+
+## Hosting islands yourself
+
+`@homepages/template-kit/island-runtime` is the loader. It is not something a template
+author calls — it is what a page (or the editor) calls to bring islands to life:
+
+```ts
+import { hydrateIslands, unmountIslands } from "@homepages/template-kit/island-runtime";
+
+await hydrateIslands({ load: (key) => ISLANDS[key]() });  // ISLANDS: the build's island map
+unmountIslands(sectionEl);  // before replacing sectionEl's HTML
+```
+
+Each island is an independent React root: one island's state, re-renders, and errors
+never touch another's. Hydration is idempotent, so calling `hydrateIslands` again after
+injecting new markup is safe.
+
+## Talking to HomePages from an island
+
+`@homepages/template-kit/browser` carries the helpers a published page needs to reach the
+HomePages ingest endpoints — reading the site's embedded config and signing requests:
+
+```ts
+import { readSiteConfig, signedIngestHeaders } from "@homepages/template-kit/browser";
+
+const config = readSiteConfig();
+if (config) {
+  const body = JSON.stringify({ name, email });
+  await fetch(`${config.ingestBase}/leads/ingest`, {
+    method: "POST",
+    headers: await signedIngestHeaders(config, body),
+    body,
+  });
+}
+```

package/docs/llms.txt

@@ -4,10 +4,40 @@
 > inside the npm package so an agent can read it locally, versioned in lockstep
 > with the code it describes.
 
-Status: 0.0.x package skeleton. The authoring corpus (task recipes, rule-id
-reference, vocabulary) arrives with the surface it documents: the schema system,
-the contract primitives and theme tokens, and the `check` command's rule-ids.
+Status: 0.0.x. The schema system, the contract primitives, and the theme tokens are
+complete — a section is authorable end to end against the kit. The `template-kit`
+CLI's commands arrive with the surfaces they drive.
+
+Everything an author writes a section against is imported from the package root —
+`@homepages/template-kit`, no subpath imports. The two CSS entries
+(`./styles.css`, `./base.css`) are the deliberate exception.
 
 ## Docs
 
+- [Schema system](schema-system.md): the section authoring contract. A section is
+  four files — `schema.ts` (slots + options + `meta.groups`), `fill-spec.ts` (how AI
+  fills them), `fixtures.ts` (preview content, built on the kit's golden property
+  dataset), `Renderer.tsx` (markup, with props DERIVED from the schema via
+  `SectionProps<typeof schema>`). Covers the `as const satisfies` requirement, binding
+  slots to property facts with `direct()`/`derived()` over a closed vocabulary, and
+  fact-driven variants.
+- [Contract primitives](primitives.md): the only five components the kit ships —
+  `Section` (full-bleed section root), `Slot` (`data-slot-id`), `SlotItem` (per-item
+  handle in an `object_list` / `image_collection`), `SlotGroup` (`data-slot-group`),
+  and `Image` (responsive `<picture>`, empty-state box). Plus the marker-attribute
+  contract (`ATTR_SLOT_ID`, `ATTR_SLOT_ITEM`, …). Presentation is the template's own JSX.
+- [Theme and CSS](theme-and-css.md): the two CSS entries and how they load; import
+  Tailwind exactly once; `base.css` ships no reset of its own — it requires the
+  preflight your Tailwind entry brings; `TokenTheme` + `compileThemeToCss`; the breakpoint ladder
+  (base 350, `bp390` `bp425` `bp512` `md` `lg` `bp1440` `bp1920`); the opt-in
+  `content-visibility` recipe for long, image-heavy pages, and why it requires a
+  full-screen overlay to be appended to `document.body` rather than rendered inside
+  the section.
 - [README](../README.md): install, exports, and the release flow.
+- [Islands](islands.md): interactivity — client components, the serializable-props contract, editor options, and the browser loader.
+- [ESLint preset](eslint.md): `@homepages/template-kit/eslint`, the zero-config flat-config
+  preset — setup and its three-entry glob scope. Per-rule reference lives in `rules/`.
+- [Rules](rules/INDEX.md): every rule-id a lint or `check` failure can print, under the
+  `template-kit/<id>` namespace, one page each at `docs/rules/<id>.md` — Rule / Reason /
+  Fix / Before→After. **The loop:** see an id in a failure → read `docs/rules/<id>.md` →
+  fix. Nothing else to search for; the id is the filename.

package/docs/primitives.md

@@ -0,0 +1,214 @@
+---
+purpose: The five contract primitives a section renderer must use, and the marker attributes they emit.
+status: living
+related: [schema-system.md, theme-and-css.md, eslint.md]
+updated: 2026-07-14
+---
+# Contract primitives
+
+Everything here is imported from the package root:
+
+```tsx
+import { Image, Section, Slot, SlotGroup, SlotItem } from "@homepages/template-kit";
+```
+
+The kit ships **five components, and nothing else**. That is deliberate: a primitive
+earns its place only by emitting something the platform breaks without — the section
+box model, the editor's marker attributes, the responsive-image machinery.
+Presentation is yours. Headings, links, layout wells, icons, lists, cards: write them
+as JSX in your section, or reach for a package.
+
+| Primitive | Emits | Required when |
+|---|---|---|
+| `Section` | `class="tr-section"` on the section root | always — every renderer roots at exactly one |
+| `Slot` | `data-slot-id` (+ optional `data-slot-text-leaf`) | around every editable slot's outer DOM |
+| `SlotItem` | `data-slot-item` | around each item of an `object_list` / `image_collection` slot |
+| `SlotGroup` | `data-slot-group` | around the members of a group declared in `meta.groups` |
+| `Image` | `<picture>` / `srcset` / the empty-state box | every image — sections never write a raw `<img>` |
+
+A slot with no marker in the DOM **cannot be selected or edited**. The markers are the
+only thing connecting the pixels a user clicks to the schema key behind them.
+
+## `Section` — the section root
+
+```tsx
+export default function Hero({ slots, nav }: Props) {
+  return (
+    <Section id={nav.selfAnchor} className="bg-surface py-16">
+      …
+    </Section>
+  );
+}
+```
+
+Renders `<section class="tr-section">` and merges any `className` you pass. `as` picks
+a different element from `section | div | article | header | footer | aside`.
+
+`.tr-section` (from [`base.css`](theme-and-css.md)) is **full-bleed by contract**: 100%
+width, zero padding, zero margin, so consecutive sections butt edge-to-edge and a page
+composes as a vertical stack with no framework-injected whitespace. Vertical separation
+is the section's own job — a background and padding on this root or a child, never a
+margin that would re-open gaps between sections.
+
+A centered, max-width well is plain JSX on a child:
+
+```tsx
+<div className="w-full max-w-[var(--tr-container-max)] mx-auto px-[var(--tr-container-pad)]">
+```
+
+## `Slot` — the editable-slot boundary
+
+```tsx
+<Slot id="headline" as="h1" textLeaf className="text-4xl">
+  <span>{slots.headline}</span>
+</Slot>
+```
+
+| Prop | Meaning |
+|---|---|
+| `id` | The slot key from `schema.ts`, written as a string literal. Emitted as `data-slot-id`. |
+| `as` | Element to render. Default `"div"`. |
+| `textLeaf` | For a single-leaf `text` slot: marks the immediate child element with `data-slot-text-leaf`. |
+| …rest | Any HTML attribute — `className`, `style`, ARIA, `data-*`. |
+
+`textLeaf` is what lets the editor write `textContent` on the leaf on every keystroke
+(the optimistic path). It only handles the **single element child** case: with raw text,
+a fragment, or several children it is a silent no-op — the outer `data-slot-id` still
+lands, the editor just skips the optimistic update and converges on the next render. A
+multi-leaf slot (an address with one leaf per line) marks its leaves itself.
+
+`Slot` still emits its marker when it has no children. That is what keeps an unfilled
+slot selectable, so a user can click the empty shell and type into it.
+
+Not every slot needs a `<Slot>` wrapper: a primitive with a natural single root for its
+slot type takes a `slotId` prop and emits the marker itself — `<Image slotId="hero_image">`
+needs no wrapper. `<Slot>` is for everything else.
+
+## `SlotItem` — the per-item handle in a collection
+
+A collection slot (`object_list`, `image_collection`) needs **both** markers: `<Slot>`
+marks the whole array, `<SlotItem>` marks one row of it.
+
+```tsx
+<Slot id="amenities">
+  {slots.amenities.map((item, i) => (
+    <SlotItem key={item.id} index={i} as="li" className="border-b">
+      <h3>{item.label}</h3>
+    </SlotItem>
+  ))}
+</Slot>
+```
+
+The editor resolves the slot from the ancestor `data-slot-id`, then the specific item
+from the nearest `data-slot-item`. Without `SlotItem` a collection is editable only as a
+whole — no per-item selection, no per-item image cropping, no per-item live surfaces.
+
+`index` **must** be the item's zero-based position in the slot's array as rendered. The
+editor writes edits back by that index, so an index that doesn't match its position edits
+the wrong row. `index` is an array position, not a schema key, so unlike `Slot`'s and
+`SlotGroup`'s `id` it is exempt from the [`template-kit/slot-marker-literal`](eslint.md#markers-and-schema)
+lint rule.
+
+## `SlotGroup` — slots edited as one unit
+
+Grouping is authored in two places that must agree.
+
+`schema.ts` declares the group in `meta.groups`, which collapses its members into one
+card in the editor sidebar:
+
+```ts
+meta: {
+  displayName: "Contact",
+  groups: [
+    { id: "agent", label: "Agent", members: ["agent_name", ["agent_email", "agent_phone"]] },
+  ],
+},
+```
+
+`Renderer.tsx` wraps the members' shared container, which makes the canvas outline and
+select them as the single unit matching that one card:
+
+```tsx
+<SlotGroup id="agent" className="flex flex-col gap-2">
+  <Slot id="agent_name" textLeaf><h3>{slots.agent_name}</h3></Slot>
+  <Slot id="agent_email" textLeaf><span>{slots.agent_email}</span></Slot>
+  <Slot id="agent_phone" textLeaf><span>{slots.agent_phone}</span></Slot>
+</SlotGroup>
+```
+
+The primitive's `id` **must equal** the group's `id` in `meta.groups`. `SlotGroup` must
+be an **ancestor** of every member's `data-slot-id` element — the editor walks up with
+`closest("[data-slot-group]")`, so a marker that isn't an ancestor is never found.
+
+## `Image` — the defensive image primitive
+
+Sections never write a raw `<img>`. `Image` owns the responsive `<picture>`, the
+empty-state box, and the layout box that survives a missing source.
+
+```tsx
+<Image
+  slotId="hero_image"
+  src={slots.hero_image.url}
+  alt={slots.hero_image.alt}
+  responsive={slots.hero_image.responsive}
+  sizes="(min-width: 1024px) 1200px, 100vw"
+  aspectRatio="5 / 3"
+/>
+```
+
+| Prop | Meaning |
+|---|---|
+| `src` | Image URL. Required prop; `null`/empty is a supported state, not a bug. |
+| `alt` | Required. Empty string for a decorative image. |
+| `slotId` | Emits `data-slot-id` on the wrapper — an image slot needs no `<Slot>` around it. |
+| `aspectRatio` | CSS `aspect-ratio` reserved on the wrapper. Survives a missing `src`. |
+| `responsive` | The platform's `ResponsiveImage` descriptor (`ImageValue.responsive`). |
+| `responsiveMobile` | Mobile-crop descriptor (`ImageValue.mobile.responsive`); needs `mobileBreakpoint`. |
+| `mobileBreakpoint` | Desktop↔mobile switch width in px. The mobile `<source>` gets `max-width: breakpoint − 1`. |
+| `sizes` | The slot's `sizes` attribute, applied to every srcset candidate. |
+| `maxRungWidth` | Per-section srcset ceiling in px. Wider rungs are dropped (the smallest is always kept). |
+| `bare` | Escape hatch: a single `<img>`, no wrapper. |
+
+**Framed (the default).** A wrapper `div` carries the slot marker, holds the aspect-ratio
+box, and absolutely-positions the inner `<img>` with `object-cover`. Cropping happens
+upstream — the platform delivers a pre-cropped asset — so the image is simply centered.
+When `src` is empty the wrapper renders alone as a neutral `role="img"` rect, keeping the
+layout box and the slot selectable. **That deterministic empty state is the reason the
+frame exists**, so pass `aspectRatio` rather than sizing the image from its own content.
+
+**Responsive.** Given a `responsive` descriptor the `<img>` is wrapped in `<picture>` with
+per-format AVIF/WebP `<source srcset>` (the base raster stays on the `<img>`), plus a
+media-gated mobile crop when `responsiveMobile` + `mobileBreakpoint` are set, and carries
+`sizes` and intrinsic `width`/`height`. With no descriptor it degrades to a plain single
+`<img src>` — no `srcset`, no `<picture>`.
+
+**Bare.** `bare` renders one `<img class="w-full">` with no wrapper, for chrome images
+whose parent already establishes the layout box (a logo you want `object-contain`, a slide
+inside its own aspect-ratio parent). It deliberately sets no `object-fit`, so an
+`object-contain` you pass isn't fighting a built-in `object-cover`. It forfeits the
+empty-state box — reach for it only when the parent guarantees the box.
+
+## The marker contract
+
+The primitives are the sanctioned way to produce these attributes. The constants are
+exported so a section's own browser-side code can query the DOM without hardcoding a
+magic string.
+
+| Constant | Attribute | On |
+|---|---|---|
+| `ATTR_SLOT_ID` | `data-slot-id` | the `Slot` wrapper / `Image`'s framed wrapper |
+| `ATTR_SLOT_TEXT_LEAF` | `data-slot-text-leaf` | the text leaf inside a text slot |
+| `ATTR_SLOT_ITEM` | `data-slot-item` | one item of a collection slot |
+| `ATTR_SLOT_GROUP` | `data-slot-group` | the container wrapping a group's members |
+| `ATTR_SECTION_INSTANCE_ID` | `data-section-instance-id` | the section root — **written by the platform**, not by a primitive |
+| `ATTR_TR_ENHANCE` | `data-tr-enhance` | opt-in hook telling an enhancer to attach to this element |
+
+Changing what an attribute means is a platform contract break, so these names are stable
+across a major version of the kit.
+
+## Renderers stay pure
+
+Renderers are pure functions of props: no fetches, no globals, no `useEffect` for data,
+no `Date.now()` / `Math.random()`. They are rendered to static markup by the publisher
+and re-mounted constantly by the editor. Interactivity that needs the browser attaches
+through `data-tr-enhance`, not through render-time side effects.

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.