@homepages/template-kit 0.0.1 → 0.2.0

package/docs/rules/unlayered-fence.md

@@ -0,0 +1,113 @@
+---
+purpose: The template-kit/unlayered-fence 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/unlayered-fence
+
+> **This is not "you forgot to layer your CSS."** Everything is layered by default — the
+> build does it for you. This rule governs the *escape hatch* from layering: an
+> `/* unlayered: … */` fence must give a reason and must be closed.
+
+## Rule
+
+Your hand-written CSS is wrapped in a cascade layer by the build. You do not write
+`@layer` yourself, and there is nothing to forget.
+
+The **fence** opts a run of rules *out* of that wrapping, hoisting them above every layer:
+
+```css
+/* unlayered: <reason> */
+…rules that must beat every layer…
+/* endunlayered */
+```
+
+Two things are checked, both under this id:
+
+1. **Every opener carries a non-empty reason.** A bare `/* unlayered: */` is a violation.
+2. **Openers and closers balance.** An unterminated fence is a violation — it would swallow
+   the whole rest of the file out of the layer, which is never what anyone meant.
+
+## Reason
+
+Cascade layers have one rule that decides everything here: **an unlayered rule beats a
+layered one, regardless of specificity.** Not "usually" — always. That is what layers are
+for, and it is why the platform layers your CSS: inside the layer order (`theme, base,
+components, sections, template, utilities`) a Tailwind utility can always override a
+section's stylesheet, and a section's stylesheet can never leak past its layer to beat
+someone else's utility.
+
+So the hatch exists for exactly one situation: **a third-party library injects an unlayered
+rule into the document at runtime** — a map SDK writing a `<style>` element when it mounts,
+say — and that rule beats your layered override no matter how specific you make it. The
+only thing that can beat it is a rule that is also unlayered. Nothing else qualifies. If
+your rule merely needs to beat *your own* CSS, or a Tailwind utility, it belongs in a layer
+and you are reaching for the wrong tool.
+
+Which is why the reason is mandatory. A fence with no reason is a rule that outranks every
+layer on the page for reasons the next author cannot reconstruct — they cannot tell whether
+it is load-bearing or whether someone was fighting a specificity problem with a hammer. And
+an unbalanced fence silently promotes every rule below it, so a stylesheet that behaved
+yesterday starts beating the utilities that were supposed to override it.
+
+## Fix
+
+Close every fence with `/* endunlayered */`, and give every opener a reason that **names the
+runtime-injected rule it has to beat**. A short phrase is enough — it only has to be
+non-empty and specific about which rule it's beating, not a full sentence. If it does not
+have to beat one, delete the fence: layered is the default, and the default is right.
+
+The Before/After below both open with a `/* css-reason: … */` comment. That line has
+nothing to do with fencing — it satisfies a separate rule, [`css-reason`](css-reason.md),
+which every hand-written stylesheet must open with. It's shown here because real section
+CSS carries both; this rule's own grammar starts at `/* unlayered: */`.
+
+### Before
+
+```css
+/* css-reason: overrides the map SDK's injected control chrome. */
+
+/* unlayered: */
+.maplibregl-ctrl-group button {
+  background: var(--tr-color-surface);
+  border-radius: var(--tr-radius-sm);
+}
+
+.tr-map-legend {
+  padding: 0.5rem;
+}
+```
+
+Two violations at once: the reason is empty, and the fence is never closed — so
+`.tr-map-legend` is hoisted out of the layer too, where it now outranks every utility a
+future author might try to override it with.
+
+### After
+
+```css
+/* css-reason: overrides the map SDK's control chrome — the SDK builds those nodes after
+   hydration, so Tailwind's scanner never sees a class to compile. */
+
+/* unlayered: the map SDK injects its control styles as an unlayered <style> element at
+   runtime; a layered rule cannot beat it at any specificity. */
+.maplibregl-ctrl-group button {
+  background: var(--tr-color-surface);
+  border-radius: var(--tr-radius-sm);
+}
+/* endunlayered */
+
+/* Our own DOM — layered, like everything else. */
+.tr-map-legend {
+  padding: 0.5rem;
+}
+```
+
+The fence now wraps exactly the rules that need to escape, and `.tr-map-legend` is back in
+the layer where a utility can still override it.
+
+## See also
+
+- [Theme and CSS](../theme-and-css.md) — the layer order, and why utilities come last.
+- [`css-reason`](css-reason.md) — the comment every hand-written stylesheet opens with; the
+  fence reason is the same discipline, one level in.

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,225 @@
+---
+purpose: The kit's two CSS entries, how a section's own CSS reaches the page, the TokenTheme a template supplies, and the breakpoint ladder.
+status: living
+related: [primitives.md, schema-system.md, eslint.md, rules/INDEX.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 gaps Tailwind's preflight leaves, 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 three reset gaps Tailwind's preflight leaves, `.tr-section`, and the 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.
+
+## How a section's CSS reaches the page
+
+A section's compiled CSS layer is assembled from two sources, both automatic — you
+never write an import to make either happen:
+
+1. **Hand-written CSS, collected by path.** Every `.css` file inside the section's
+   folder — `styles.css` and any other stylesheet nested under it — is picked up by
+   walking the folder, wherever it sits, and concatenated into `@layer sections`. A
+   template's own hand-written stylesheet is collected the same way, into
+   `@layer template`.
+2. **Package CSS, harvested from the render path.** The build also bundles
+   `Renderer.tsx`'s module graph — and any component that carries `export const
+   enhancer` — and pulls in whatever `.css` those imports resolve to. A bare specifier
+   (`import "swiper/css";`) resolves into `node_modules` and lands in the same
+   `@layer sections`; that is the sanctioned way for a third-party package's
+   stylesheet to reach the page.
+
+Two constraints follow directly, and both are enforced by lint:
+
+- **Don't re-import your own stylesheet.** It is already collected by path —
+  importing it again from a `.ts`/`.tsx` file only double-emits it, and can smuggle a
+  stray `@layer` statement into a nested layer.
+  See [`no-css-import-from-render-path`](rules/no-css-import-from-render-path.md).
+- **`@import` never works inside hand-written CSS, package or local.** An `@import`
+  landing inside `@layer sections` / `@layer template` is invalid CSS, and the
+  browser drops it silently rather than erroring — the package's styling is simply
+  missing from the published page. Reach a package's stylesheet from code instead.
+  See [`no-bare-css-import`](rules/no-bare-css-import.md).
+
+## The page's stylesheets
+
+A published page loads, in order:
+
+1. **`base.css`** — layer order, the reset gaps, `.tr-section`, motion tokens.
+2. **Your compiled theme CSS** — the `:root` block that defines the `--tr-*` values
+   *and* the `body` block that applies them (font-family, color, background, size),
+   both produced by `compileThemeToCss`.
+3. **Your compiled Tailwind bundle** — `@import "tailwindcss"` + `styles.css` + your
+   section markup's utilities.
+
+The layer order `base.css` declares is:
+
+```css
+@layer theme, base, components, sections, template, utilities;
+```
+
+Utilities come last, so a Tailwind utility always beats the reset's element defaults.
+
+### base.css requires a Tailwind entry
+
+`base.css` does **not** ship a reset. Your entry's `@import "tailwindcss"` brings
+Tailwind's preflight, and preflight is the reset — box-sizing, margins, list-style, the
+button and anchor resets. `base.css` carries only the three declarations preflight does
+not make: `font-smoothing`, `button { cursor: pointer }` (Tailwind v4 leaves buttons at
+`cursor: default`), and `svg { max-width: 100% }` (preflight caps only `img` and
+`video`).
+
+Ship `base.css` without a Tailwind entry on the page and you get an unreset page.
+
+`base.css` references **no theme token**. Your fonts and colors reach the document
+through `compileThemeToCss`, which emits both the `:root` block that defines your tokens
+and the `body` block that applies them. Nothing global is opinionated about your brand.
+
+## `TokenTheme` — your template's values
+
+A template's `theme.ts` exports a `TokenTheme`. `compileThemeToCss` turns it into the
+`:root { --tr-*: … }` block that defines your tokens **and** the `body` block that
+applies them (font-family, color, background, size) to the document — together, the
+CSS the template's 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.2.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
+  }
+}