@homepages/template-kit 0.0.0 → 0.1.0

package/docs/eslint.md

@@ -0,0 +1,90 @@
+---
+purpose: The authoring-lint preset shipped at `@homepages/template-kit/eslint` — setup, scope, and the eleven rule ids.
+status: living
+related: [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 below |
+| `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 — not by an import graph or a build transform. A file carrying the
+directive is an island: it hydrates in the browser, so effects, state, event
+handlers, and inline `style` are legal there and the corresponding rules exempt
+it. A rule that does not exempt islands says so explicitly below.
+
+## The rules
+
+Rules that are properties of one file live here. Rules that are properties of the
+**tree** — a missing contract file, a slot declared in `schema.ts` but unmarked in
+`Renderer.tsx`, a CSS rule — cannot be expressed one-file-at-a-time; they belong to
+`template-kit check` (not yet built) under the same `template-kit/<id>` namespace.
+One namespace, two venues.
+
+### Server-rendered code
+
+| Rule | What it bans |
+|---|---|
+| `no-nondeterminism` | Clock/randomness reads (`Date.now()`, `new Date()` with no args, `Math.random()`, `crypto.randomUUID()`/`getRandomValues()`, `performance.now()`) — the publisher and the editor must render byte-identical HTML. Exempt inside an island. |
+| `no-client-runtime-in-server` | Effects, state hooks, event handlers, and browser globals (`fetch`, `window`, `document`, …) — a Renderer must be a pure function of its props. Exempt inside an island. |
+| `no-inline-style` | The `style=` JSX prop — it bypasses the cascade and Tailwind's responsive prefixes. Exempt inside an island. |
+| `no-raw-element` | Raw `<section>`/`<img>` — each has a contract-bearing primitive (`Section`/`Image`) that must be used instead. |
+| `image-bare-needs-reason` | `<Image bare>` with no `// bare: <reason>` comment justifying the skipped frame. |
+| `no-css-import-from-render-path` | A `.css` import anywhere in a section's render path — the SSR graph drops it silently. Import CSS from the section's own `styles.css` instead. |
+
+### Islands
+
+| Rule | What it checks |
+|---|---|
+| `serializable-island-props` | A statically-visible prop passed to an island (a literal function, `new Date()`/`Map`/`Set`/etc., a bigint literal, `NaN`/`Infinity`) that cannot cross the server→browser JSON boundary. It is the static twin of the runtime check — see [islands.md](islands.md#props-must-be-json-serializable). |
+
+### Universal — no island exemption
+
+| Rule | What it bans |
+|---|---|
+| `no-hex` | Hex color literals and CSS color functions (`oklch`/`oklab`/`rgb`/`rgba`/`hsl`/`hsla`/`color-mix`) in a color context (a Tailwind color-utility bracket, an arbitrary-property color declaration, or an inline `style` value). Token discipline is universal — see [theme-and-css.md](theme-and-css.md#color-roles). |
+
+Deliberate asymmetry: `no-inline-style` exempts islands, `no-hex` does not — the
+hydration boundary is not a palette boundary. A section carries no palette of its
+own in either render path.
+
+### Markers and schema
+
+| Rule | What it checks |
+|---|---|
+| `slot-marker-literal` | A slot-key-bearing marker (`<Slot id>`, `<SlotGroup id>`, `slotId`, `data-slot-id`, `data-slot-group`) must carry a string-literal key, not an expression — the slot-marker completeness check (`template-kit check`) reads these keys statically. `SlotItem` is exempt: its prop is `index: number`, an array position, so there is no schema key to cross-check. |
+| `props-from-schema` | A `Renderer.tsx`'s exported `Props` type must come from `SectionProps<typeof schema>`. A hand-written `Props` shadows that inference and drifts. |
+| `no-client-directive-in-contract` | `"use client"` in a section's four contract files (`Renderer.tsx`, `schema.ts`, `fill-spec.ts`, `fixtures.ts`) — the platform reads them outside a browser; marking one an island takes the section's server-rendered HTML with it. |

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,37 @@
 > 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; `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 covering the eleven `template-kit/*` authoring rules — determinism, the
+  server/island boundary, serializable island props, the marker and schema contracts,
+  and token discipline.

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.