@homepages/template-kit 0.1.0 → 0.3.0

package/docs/rules/license-denied.md

@@ -0,0 +1,114 @@
+---
+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-15
+---
+# 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.** "Production tree" means exactly what
+`npm ci --omit=dev` installs. `devDependencies` are not evaluated — your bundler, your
+test runner, and your formatter do not ship to anyone.
+
+**An optional peer you have anyway counts.** If a production package declares an
+optional `peerDependency` and your workspace has that package for any reason (even as a
+`devDependency`), npm resolves the peer and keeps it in the `--omit=dev` install — so it
+is in the production tree and its license is checked, transitively. An optional peer you
+do **not** have is never installed and is not evaluated. Run `npm ci --omit=dev` and look
+at the resulting `node_modules` if you want the exact set the check sees.
+
+**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.

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/manifest-invalid.md

@@ -0,0 +1,99 @@
+---
+purpose: The template-kit/manifest-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, schema-invalid.md, no-templates.md]
+updated: 2026-07-14
+---
+# template-kit/manifest-invalid
+
+> `manifest.json` is the one file that says which sections make a page, and in what
+> order. Every check on it lands under this id.
+
+## Rule
+
+A template folder (`templates/<key>/`) must have a `manifest.json` at its root, and that
+file must:
+
+- **exist** — a template folder with none at all reports this once, naming the missing
+  file;
+- **parse as JSON, and satisfy the manifest shape** — `key`, `name`, `deliverable_type`,
+  and an ordered `sections` array of section instances (`section`, `instance_id`,
+  `options`, `locked`, `required`, `reorderable`);
+- **agree with its own folder** — the manifest's `key` must match the template folder
+  name it lives in;
+- **reference real sections** — every `sections[].section` must resolve to a section this
+  workspace actually has;
+- **override only what's real and overridable** — an instance's `options` may only name an
+  option the target section declares, only when that option is not
+  `template_overridable: false`, and only with a value that actually differs from the
+  section's own default;
+- **satisfy the whole-composition nav contract** — the cross-section rules that need the
+  full, resolved section set rather than any one section in isolation.
+
+Every violation collects into the same run; a manifest with several wrong references
+reports all of them together.
+
+## Reason
+
+A section's own four files describe that section in isolation — they say nothing about
+which page it appears on, in what order, or which of its options a specific template has
+chosen to lock in. `manifest.json` is where that composition is declared, and it is the
+only place a downstream consumer (the publisher, the fill pipeline, the editor) can go to
+learn a template's actual shape. A manifest that references a section that doesn't exist,
+or restates a default as if it were an override, is a template whose real composition
+nobody can trust the manifest to describe.
+
+## Fix
+
+Read the message: it names the template, the section instance, and what's wrong.
+Missing entirely, add one. Otherwise, fix the field the message points at.
+
+### Before
+
+```text
+templates/acme-modern/
+  manifest.json
+  sections/
+    hero/
+```
+
+```json
+// templates/acme-modern/manifest.json
+{
+  "key": "acme-classic",
+  "name": "Acme Classic",
+  "deliverable_type": "single_property_website",
+  "sections": [
+    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true, "reorderable": false }
+  ],
+  "reconcile": []
+}
+```
+
+```text
+Template "acme-modern": manifest key "acme-classic" does not match the template folder name "acme-modern".
+```
+
+### After
+
+```json
+// templates/acme-modern/manifest.json
+{
+  "key": "acme-modern",
+  "name": "Acme Modern",
+  "deliverable_type": "single_property_website",
+  "sections": [
+    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true, "reorderable": false }
+  ],
+  "reconcile": []
+}
+```
+
+## See also
+
+- [The schema system](../schema-system.md#manifestjson--composing-sections-into-a-template) —
+  what a manifest declares and the type it's validated against.
+- [`schema-invalid`](schema-invalid.md) — the same kind of cross-reference check, one
+  level down, on a single section's own contract files.
+- [`no-templates`](no-templates.md) — reported instead when the workspace has no
+  `templates/<key>/` folder to check at all.

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"`.