@homepages/template-kit 0.0.1 → 0.1.0

package/docs/schema-system.md

@@ -0,0 +1,240 @@
+---
+purpose: The section authoring contract — schema.ts, fill-spec.ts, fixtures.ts, and the closed source/transform vocabulary.
+status: living
+related: [primitives.md, theme-and-css.md]
+updated: 2026-07-14
+---
+# The schema system
+
+Everything here is imported from the package root:
+
+```ts
+import { direct, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
+```
+
+There are no subpath imports for the authoring API — one specifier, on purpose.
+
+A section is **four files in one folder**. Three of them are declarations the
+platform reads; the fourth is your React.
+
+| File | Declares | Key type |
+|---|---|---|
+| `schema.ts` | The slots and options the section has | `SectionSchemaShape` |
+| `fill-spec.ts` | How AI fills those slots | `FillSpecShape` |
+| `fixtures.ts` | Sample content for local preview | `FixtureModule` |
+| `Renderer.tsx` | The markup | `SectionProps<typeof schema>` |
+
+## `schema.ts` — what the section contains
+
+Declare the schema `as const satisfies SectionSchemaShape`. **The `as const` is
+load-bearing**: it preserves the literal types that everything downstream infers
+from. Without it, `SectionProps` cannot tell a required slot from an optional one
+and your renderer props collapse to a useless widened shape.
+
+```ts
+import { direct, type FrameConfig, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
+
+export const HERO_FRAME = {
+  breakpoint: 425,
+  desktop: { aspect: 5 / 3 },
+} as const satisfies FrameConfig;
+
+export const schema = {
+  meta: { displayName: "Hero" },
+  slots: {
+    headline: { type: "text", size: "medium", required: true, produced_by: "headline_text" },
+    listing_status: { type: "select", required: false, source: direct("listing_intent") },
+    hero_image: { type: "image", required: true, produced_by: "hero_image_assign", frame: HERO_FRAME },
+  },
+  options: {
+    align: { type: "enum", values: ["left", "center"], default: "left" },
+  },
+} as const satisfies SectionSchemaShape;
+
+export type Props = SectionProps<typeof schema>;
+```
+
+A **slot** is content: something a user can edit or AI can fill. An **option** is
+behavior: a switch the section reads to render differently. If a user would type
+into it, it is a slot.
+
+### Binding a slot to a property fact
+
+`direct(field)` binds a slot to a known fact about the property; `derived(name)`
+binds it to a computed transform. Both take names from a **closed vocabulary**, so
+a typo is a compile error at the call site — not a runtime surprise:
+
+```ts
+source: direct("listing_intent")   // ✅
+source: direct("listing_intentt")  // ✗ compile error: not a SOURCE_FIELDS key
+```
+
+The vocabulary is the kit's, not yours. Read it off the exported tables —
+`SOURCE_FIELDS` (facts `direct()` accepts), `TRANSFORMS` (`derived()`), and
+`SLOT_TYPE_DESCRIPTORS` (the slot types) — or let your editor autocomplete it.
+Adding to it is a kit release, not a change you can make in a template.
+
+### Grouping slots into one editor card
+
+`meta.groups` collapses several slots into a single card in the editor sidebar. Each
+group declares an `id`, a `label`, and its `members` — a bare slot id is a full-width
+row, a `[a, b]` tuple is one 2-up row:
+
+```ts
+meta: {
+  displayName: "Contact",
+  groups: [
+    { id: "agent", label: "Agent", members: ["agent_name", ["agent_email", "agent_phone"]] },
+  ],
+},
+```
+
+The renderer must match this by wrapping the members in `<SlotGroup id="agent">` — see
+[Contract primitives](primitives.md#slotgroup--slots-edited-as-one-unit).
+
+## `Renderer.tsx` — props derived, never hand-written
+
+Never hand-write your prop type. Derive it, and the schema stays the single
+source of truth:
+
+```tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export default function Hero({ slots, options, nav }: Props) {
+  // headline is `string` — the schema says required: true
+  // listing_status is `string | null` — required: false
+  // options.align is `"left" | "center"` — the enum's declared values
+  return (
+    <Section id={nav.selfAnchor}>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+`SectionProps` reads the schema literal and resolves each slot to its runtime
+value shape: a required `text` becomes `string`, an optional one `string | null`,
+an `image` becomes `ImageValue`, an `image_collection` an array, and so on. A slot
+you did not declare is a compile error to read.
+
+An `ImageValue` splits into fields a renderer **reads** and fields it only **carries**.
+Read `url`, `alt`, `responsive`, and `mobile`, and pass them to
+[`Image`](primitives.md#image--the-defensive-image-primitive). Ignore `rect`, `ar`, and
+`crop_key`: they are the editor's re-edit state (so its cropper can reopen at the last
+crop) and the provenance of the already-cropped `url`. **Framing is baked into the asset
+the platform serves, never applied at render time** — an uncropped image is a centered
+`object-cover` over the original and a cropped one is a pre-cropped derivative, so there
+is no framing for a renderer to apply. A slot's `crop` config steers the editor's cropper,
+not your markup.
+
+The markup a section is *required* to emit — the section root, the editor's slot
+markers, images — comes from the kit's five primitives; everything else is your own
+JSX. See [Contract primitives](primitives.md).
+
+Renderers must be **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.
+
+## `fill-spec.ts` — how AI fills the slots
+
+Each decision `produces` one or more slot names. A slot filled by AI names its
+decision in `produced_by`; a slot bound with `direct()` needs no decision, because
+the fact is baked in at fill time.
+
+```ts
+import type { FillSpecShape } from "@homepages/template-kit";
+
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    { id: "hero_image_assign", type: "image-assign", produces: ["hero_image"], tag_query: "category:exterior" },
+    {
+      id: "headline_text",
+      type: "text-block",
+      produces: ["headline"],
+      length_cap: 60,
+      structure: "single_sentence",
+      voice_prompt: "Confident premium-listing voice. Title Case.",
+    },
+  ],
+} as const satisfies FillSpecShape;
+```
+
+## `fixtures.ts` — content for local preview
+
+`base` is one fully-specified baseline: every required slot, with a real value.
+`states` adds named scenarios that override part of it — use them for the
+structural cases your section is designed to handle (a missing logo, a long
+headline, an empty list).
+
+```ts
+import type { FixtureModule } from "@homepages/template-kit";
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: {
+      headline: "A mansard Victorian in the heart of Jamaica Plain",
+      listing_status: "for_sale",
+      hero_image: { photo_id: "p1", url: "https://example.com/a.jpg", alt: "Front elevation" },
+    },
+    options: { align: "left" },
+  },
+  states: {
+    centered: { label: "Centered", options: { align: "center" } },
+  },
+};
+
+export default fixtures;
+```
+
+### Build on the golden property, not on lorem ipsum
+
+Preview is only as honest as the data behind it, so the kit ships a realistic dataset to
+build fixtures from: a 12-unit building with long unit labels, a reserved unit and a
+missing price — the cases that actually break a layout.
+
+```ts
+import { allPhotos, sampleProperty, sampleContacts, samplePois, sampleAmenities, mkResponsive } from "@homepages/template-kit";
+```
+
+| Export | What it is |
+|---|---|
+| `sampleProperty` | The full `PropertyFacts` bundle — address, units, contacts, coordinates |
+| `allPhotos` | The gallery/hero photo pool (`PhotoFixture[]`) |
+| `sampleContacts` | Attached agent cards (`ContactFixture[]`) |
+| `samplePois` | Neighborhood points of interest with real coordinates (`PoiFixture[]`) |
+| `sampleAmenities` | Curated amenity rows (`AmenityItem[]`) |
+| `sampleHeroSlots` | A ready-made slot bundle for a hero-shaped section |
+| `mkResponsive(url, width, height)` | Synthesizes a deterministic `ResponsiveImage` descriptor so `<Image responsive>` can be previewed and snapshotted |
+
+## Variants — rendering differently based on the facts
+
+A variant axis picks a case from the property's facts, before any content is
+filled. Declare the axis in `meta.variants` with its `cases`, a `default` for when
+facts are missing, and a pure `select` function. Your renderer receives the
+resolved case on `props.variants`.
+
+```ts
+meta: {
+  displayName: "Floorplan",
+  variants: {
+    layout: {
+      cases: ["single", "multi"],
+      default: "single",
+      select: (input) => (input.units.length > 1 ? "multi" : "single"),
+    },
+  },
+},
+```
+
+`select` receives a `TransformInput` and must be **pure** — it runs inside the
+published bundle. A case it returns that is not in `cases` falls back to `default`.
+
+## `manifest.json` — composing sections into a template
+
+The template's `manifest.json` lists the ordered section instances that make up a
+page. It is validated against the exported `TemplateManifest` schema.

package/docs/theme-and-css.md

@@ -0,0 +1,179 @@
+---
+purpose: The kit's two CSS entries, the Tailwind import rule, the TokenTheme a template supplies, and the breakpoint ladder.
+status: living
+related: [primitives.md, schema-system.md, eslint.md]
+updated: 2026-07-14
+---
+# Theme and CSS
+
+The kit owns the **contract**: the Tailwind utility namespace (`text-ink`,
+`bg-surface-alt`, `rounded-md`), the breakpoint ladder, the reset, and the section box
+model. Your template owns the **values** behind that namespace, declared once as a
+`TokenTheme`.
+
+Two CSS entries ship, and they are not interchangeable.
+
+| Entry | What it is | How it loads |
+|---|---|---|
+| `@homepages/template-kit/styles.css` | The Tailwind v4 `@theme inline` alias layer + the breakpoint ladder + `@source` registration of the kit's compiled JS | imported into **your Tailwind entry**, after Tailwind |
+| `@homepages/template-kit/base.css` | Cascade-layer order, the reset, document defaults, `.tr-section`, and the universal spacing / motion tokens | its **own stylesheet** on the page — not part of the Tailwind entry |
+
+## Import Tailwind exactly once
+
+```css
+/* your CSS entry */
+@import "tailwindcss";
+@import "@homepages/template-kit/styles.css";
+```
+
+`styles.css` deliberately does **not** `@import "tailwindcss"` itself. Exactly one
+`@import "tailwindcss"` may exist per build graph — yours. Two double-emit Tailwind's
+preflight reset (`box-sizing` declared twice, several KB of duplicate base layer), and
+nothing errors to tell you.
+
+`styles.css` also carries `@source "./**/*.js"`, which registers the kit's own shipped
+`dist` for Tailwind's class scan. That is how the utility classes baked into the kit's
+primitives (`Image`'s `bg-surface-alt`, `object-cover`, …) reach your compiled CSS; it
+also overrides Tailwind's default exclusion of `node_modules`. You do not need to add a
+`@source` for the kit yourself.
+
+## The page's stylesheets
+
+A published page loads, in order:
+
+1. **`base.css`** — layer order, reset, `.tr-section`, universal tokens.
+2. **Your theme's `:root` block** — the `--tr-*` values, produced by `compileThemeToCss`.
+3. **Your compiled Tailwind bundle** — `@import "tailwindcss"` + `styles.css` + your
+   section markup's utilities.
+
+`base.css` reads `--tr-color-ink`, `--tr-color-background`, `--tr-font-sans`,
+`--tr-text-base` and `--tr-header-height` for the document defaults, so the theme block
+must be present on the page too. The layer order it declares is:
+
+```css
+@layer theme, base, components, sections, template, utilities;
+```
+
+Utilities come last, so a Tailwind utility always beats the reset's element defaults.
+
+## `TokenTheme` — your template's values
+
+A template's `theme.ts` exports a `TokenTheme`. `compileThemeToCss` turns it into the
+`:root { --tr-*: … }` block the template's CSS bundle ships — deterministic (stable key
+order, palette keys sorted), so the same theme always content-hashes identically.
+
+```ts
+import { compileThemeToCss, type TokenTheme } from "@homepages/template-kit";
+
+export const theme: TokenTheme = {
+  colors: { ink: "#111418", background: "#ffffff", /* …every role, see below */ },
+  palette: { "brand-gold": "#c8a248" },        // optional escape hatch
+  fonts: {
+    body: '"Inter", system-ui, sans-serif',
+    heading: '"Canela", Georgia, serif',
+    numeric: '"Inter", system-ui, sans-serif',
+    label: '"Inter", system-ui, sans-serif',
+    fontFaces: '@import url("https://fonts.example/inter.css");', // optional, emitted before :root
+  },
+  type: { xs: "0.75rem", sm: "0.875rem", base: "1rem", /* lg xl 2xl 3xl 4xl 5xl display */ },
+  radii: { sm: "2px", md: "6px", lg: "12px", full: "9999px" },
+  shadows: { sm: "…", md: "…", lg: "…" },
+  layout: { containerMax: "1280px", containerPad: "1.5rem", headerHeight: "72px" },
+};
+
+const css = compileThemeToCss(theme);
+```
+
+`TokenThemeSchema` validates it at runtime; the object is `.strict()`, so an unknown key
+is an error rather than a silently-dead token. Every scale is **complete or invalid** —
+there are no defaults to fall back on.
+
+### Color roles
+
+The role keys are fixed. Each maps 1:1 to a `--tr-color-*` variable, and the Tailwind
+utility is named after **the variable**, not the role key — so `surfaceAlt` is
+`bg-surface-alt`, and `primaryStrong` is `bg-primary-darker`. Read the mapping off the
+exported `COLOR_ROLE_VARS` (and `FONT_ROLE_VARS`, `TYPE_STEP_VARS`, `RADIUS_VARS`,
+`SHADOW_VARS`, `LAYOUT_VARS` for the other scales), or let your editor autocomplete the
+`ColorRole` union:
+
+| Role key | CSS variable | Utility |
+|---|---|---|
+| `ink` `inkSoft` `inkMute` | `--tr-color-ink[-soft|-mute]` | `text-ink`, `text-ink-soft`, `text-ink-mute` |
+| `background` `surface` `surfaceAlt` | `--tr-color-background` / `-surface` / `-surface-alt` | `bg-surface-alt`, … |
+| `border` `borderStrong` | `--tr-color-border[-strong]` | `border-border-strong`, … |
+| `primary` `primaryFg` `primaryStrong` | `--tr-color-primary` / `-primary-fg` / `-primary-darker` | `bg-primary`, `text-primary-fg`, `bg-primary-darker` |
+| `accent` `accentFg` `accentStrong` | `--tr-color-accent` / `-accent-contrast` / `-accent-strong` | `bg-accent`, `text-accent-contrast`, `bg-accent-strong` |
+| `overlay` `overlayStrong` `overlayLight` | `--tr-color-overlay[-strong|-light]` | `bg-overlay`, … |
+| `darkBg` `darkFg` `darkFgMute` `darkBorder` | `--tr-color-footer-bg` / `-footer-fg` / `-footer-fg-mute` / `-footer-divider` | `bg-footer-bg`, `text-footer-fg`, `border-footer-divider`, … |
+
+`palette` is the open escape hatch: each key becomes `--tr-color-<key>`. Sections normally
+use the semantic roles — reach for a brand swatch only when no role honestly fits.
+
+A section carries no palette of its own, in server-rendered code or inside an island —
+the `template-kit/no-hex` [lint rule](eslint.md#universal--no-island-exemption) bans a
+hard-coded hex literal or CSS color function in a color context and does not exempt
+`"use client"` files, unlike most of the preset's other rules.
+
+## The breakpoint ladder
+
+Eight canonical widths. 350 is the mobile-first **base** (no prefix); the other seven are
+named breakpoints:
+
+| Width | Prefix |
+|---|---|
+| 350 | *(base — no prefix)* |
+| 390 | `bp390:` |
+| 425 | `bp425:` |
+| 512 | `bp512:` |
+| 768 | `md:` |
+| 1024 | `lg:` |
+| 1440 | `bp1440:` |
+| 1920 | `bp1920:` |
+
+`md` and `lg` keep Tailwind's own names and values. Tailwind's off-ladder defaults
+(`sm:`, `xl:`, `2xl:`) are reset to `initial` and **do not exist** — a section cannot come
+to depend on a width nobody verifies it at. The same widths are exported as
+`VERIFICATION_WIDTHS`, which is the set your section is screenshotted and verified
+against. A swap-heavy section may still write a raw `@media` query at an off-ladder width.
+
+## Recipe: `content-visibility` on long, image-heavy pages
+
+A page that stacks many image-heavy sections can exhaust the browser's GPU/raster
+memory — enough to make it evict a live WebGL map's layer on scroll, blanking the map.
+`content-visibility: auto` fixes this by letting off-screen sections skip rendering, so
+they stop consuming that memory.
+
+The kit does **not** apply this for you — it has a real cost (below), and only you know
+whether your page needs it. If it does, add the rule to the same CSS entry that does
+`@import "tailwindcss"; @import "@homepages/template-kit/styles.css";` — the third
+stylesheet the page loads:
+
+```css
+@layer template {
+  .tr-root .tr-section:not(header):not(.my-map-section) {
+    content-visibility: auto;
+    contain-intrinsic-size: auto 600px;
+  }
+}
+```
+
+Layer placement matters: inside `@layer template`, a Tailwind utility (`@layer
+utilities`, which comes later in the layer order) can always override this rule on a
+given section. Left unlayered, it would beat every layer instead, including
+utilities. Neither collides today — no Tailwind utility sets `content-visibility` —
+but wrapping it in `@layer template` keeps that guarantee explicit rather than
+accidental.
+
+`.tr-root` is set on `<body>` at publish time and is **absent in the editor**, so the rule
+is published-only — and so are its consequences. You will not see them in preview.
+`contain-intrinsic-size: auto` remembers each section's rendered height, avoiding scroll jank.
+
+**The cost.** `content-visibility` implies `contain: paint`, which **clips descendants to
+the section box**. So:
+
+- A full-screen overlay — a lightbox, a gallery, a modal — must be appended to
+  `document.body`, never rendered inside the section. Inside, it gets clipped.
+- A section that must stay painted while off-screen (a live map), or whose dropdowns
+  escape its box, must be excluded — add its class to the `:not()` list, as
+  `.my-map-section` is above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
   "license": "UNLICENSED",
   "type": "module",
@@ -17,7 +17,9 @@
   "files": [
     "dist",
     "docs",
-    "tsconfig.json"
+    "tsconfig.json",
+    "tsconfig.base.json",
+    "CHANGELOG.md"
   ],
   "bin": {
     "template-kit": "dist/cli.js"
@@ -27,25 +29,40 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./fixtures": {
+      "types": "./dist/fixtures.d.ts",
+      "default": "./dist/fixtures.js"
+    },
+    "./island-runtime": {
+      "types": "./dist/island-runtime.d.ts",
+      "default": "./dist/island-runtime.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
     "./eslint": {
       "types": "./dist/eslint.d.ts",
       "default": "./dist/eslint.js"
     },
     "./styles.css": "./dist/styles.css",
-    "./tsconfig": "./tsconfig.json",
+    "./base.css": "./dist/base.css",
+    "./tsconfig": "./tsconfig.base.json",
     "./package.json": "./package.json"
   },
   "sideEffects": [
     "*.css"
   ],
   "scripts": {
+    "prepack": "npm run build",
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
-    "test": "node --import tsx --test src/*.test.tsx src/cli/*.test.ts",
-    "lint:pkg": "publint --strict && attw --pack . --profile esm-only --exclude-entrypoints styles.css",
+    "test": "node --import tsx --test 'src/**/*.test.ts' 'src/**/*.test.tsx'",
+    "lint:pkg": "publint --strict && attw --pack . --profile esm-only --exclude-entrypoints styles.css base.css",
     "verify:consumer": "node scripts/verify-consumer.mjs",
-    "check": "npm run typecheck && npm run lint && npm run build && npm run test && npm run lint:pkg && npm run verify:consumer",
+    "size:islands": "node scripts/check-island-runtime-size.mjs",
+    "check": "npm run typecheck && npm run lint && npm run build && npm run size:islands && npm run test && npm run lint:pkg && npm run verify:consumer",
     "changeset": "changeset",
     "release": "changeset publish"
   },
@@ -64,10 +81,13 @@
     "@changesets/cli": "^2.29.8",
     "@eslint/js": "^9.39.4",
     "@tailwindcss/cli": "^4.3.0",
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^20.17.10",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "esbuild": "^0.28.1",
     "eslint": "^9.39.4",
+    "jsdom": "^26.1.0",
     "publint": "^0.3.21",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -76,5 +96,9 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.60.1"
+  },
+  "dependencies": {
+    "@typescript-eslint/parser": "^8.60.1",
+    "zod": "^3.23.8"
   }
 }

package/tsconfig.base.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package/tsconfig.json

@@ -1,18 +1,7 @@
 {
+  "extends": "./tsconfig.base.json",
   "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "lib": ["ES2022", "DOM"],
-    "jsx": "react-jsx",
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "isolatedModules": true,
-    "resolveJsonModule": true,
-    "forceConsistentCasingInFileNames": true,
     "noEmit": true
   },
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", ".tmp-consumer"]
 }

package/dist/src-dZr5N30y.js

@@ -1,35 +0,0 @@
-import { jsx } from "react/jsx-runtime";
-
-//#region package.json
-var version = "0.0.1";
-
-//#endregion
-//#region src/kit-smoke.tsx
-/**
-* Boundary probe, not authoring surface. Its only job is to make the package
-* boundary testable: React stays a peer, types resolve, and Tailwind's
-* cross-package @source scan reaches this file's compiled output.
-* Removed when the real contract primitives land.
-*/
-function KitSmoke({ label }) {
-	return /* @__PURE__ */ jsx("span", {
-		className: "bg-kit-smoke uppercase tracking-[0.4275em]",
-		children: label
-	});
-}
-
-//#endregion
-//#region src/index.ts
-/**
-* The published version of this kit.
-*
-* Read from package.json and inlined at build time, so it cannot drift: changesets
-* owns package.json's version, and a hardcoded constant here would have to be
-* hand-edited on every release — on a branch changesets force-pushes, which would
-* silently discard the edit. `dist/cli.js --version` is asserted against
-* package.json to prove the inlining actually happened.
-*/
-const KIT_VERSION = version;
-
-//#endregion
-export { KitSmoke as n, KIT_VERSION as t };