@homepages/template-kit 0.3.0 → 0.4.1

package/docs/rules/size-island-bundle.md

@@ -0,0 +1,123 @@
+---
+purpose: The template-kit/size-island-bundle authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-renderer-bundle.md, size-section-css.md, server-vs-client.md]
+updated: 2026-07-15
+---
+# template-kit/size-island-bundle
+
+> Each island's browser bundle must be **≤ 50 KB gzip**. The budget is not
+> author-overridable, and it applies per island, not per section.
+
+## Rule
+
+An island — a component whose file opens with the `"use client"` directive (see
+[Server vs client](server-vs-client.md)) — ships to the browser as its own bundle,
+separate from the section's server-rendered HTML. Each island is bundled with esbuild
+and minified, with **React treated as external** (the page's runtime chunk supplies it
+once, shared by every island on the page, and is not counted against any one of them).
+The gzipped result must be **50 KB or less**.
+
+A section can have more than one island. The budget is checked **per island**: a section
+with three islands each at 40 KB passes; a section with one island at 60 KB fails, even
+though the same section's other files are small.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A template workspace cannot raise it, and there is no per-island
+exemption.
+
+## Reason
+
+An island is the part of the page that has to work on a phone before the visitor does
+anything — a carousel, a filter, a form. Every one of its bytes is downloaded, parsed,
+and executed on the client, on top of whatever the page's shared runtime already costs.
+Unlike the section's server-rendered markup, which the browser only has to paint, an
+island's code has to run.
+
+The number is set to be generous, so it does not fight ordinary authoring — a real
+interactive widget fits comfortably inside it. You hit the budget when something
+**runaway** gets pulled into the client bundle:
+
+- **a whole UI or icon library imported for one component**, which drags every export
+  into the bundle so the island can use a handful of them;
+- **a heavy dependency that belongs on the server**, ported into the island because it
+  was easiest to reach for where the code was being written, not because the browser
+  needs it.
+
+That is the shape of essentially every violation: not an island that grew, but a single
+import that was more expensive than it looked.
+
+## Fix
+
+Find the import that is not paying for itself, or narrow what ships to the browser at
+all.
+
+- **Import named symbols, never a namespace.** `import { ArrowRight } from "…"` is
+  tree-shakeable; `import * as Icons from "…"` is not — a namespace object has to contain
+  everything, so nothing can be dropped.
+- **Prefer the package's narrow entry** if it offers one, instead of its default
+  "everything" bundle.
+- **Move what doesn't need to be interactive out of the island.** If only a small part of
+  a component actually needs client-side behavior — an expand/collapse toggle inside an
+  otherwise static block — split the interactive part into its own small island and leave
+  the rest server-rendered. Server-rendered markup costs nothing against this budget.
+- **Hand-write the residue.** If you use one function out of a large utility package, copy
+  the function instead of importing the package for it.
+
+### Before
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import * as Icons from "lucide-react"; // ← the whole set: every icon, in this island's bundle
+import { useState } from "react";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  const [index, setIndex] = useState(0);
+  return (
+    <div>
+      <img src={slides[index]?.url} alt="" />
+      <button onClick={() => setIndex((i) => (i - 1 + slides.length) % slides.length)}>
+        <Icons.ChevronLeft aria-hidden />
+      </button>
+      <button onClick={() => setIndex((i) => (i + 1) % slides.length)}>
+        <Icons.ChevronRight aria-hidden />
+      </button>
+    </div>
+  );
+}
+```
+
+### After
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import { ChevronLeft, ChevronRight } from "lucide-react"; // ← two icons, and the bundler can drop the rest
+import { useState } from "react";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  const [index, setIndex] = useState(0);
+  return (
+    <div>
+      <img src={slides[index]?.url} alt="" />
+      <button onClick={() => setIndex((i) => (i - 1 + slides.length) % slides.length)}>
+        <ChevronLeft aria-hidden />
+      </button>
+      <button onClick={() => setIndex((i) => (i + 1) % slides.length)}>
+        <ChevronRight aria-hidden />
+      </button>
+    </div>
+  );
+}
+```
+
+## See also
+
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the same budget on the section's
+  server-rendered bundle.
+- [`size-section-css`](size-section-css.md) — the same budget on the section's stylesheet.
+- [Server vs client](server-vs-client.md) — what makes a file an island in the first
+  place.

package/docs/rules/size-section-css.md

@@ -1,8 +1,8 @@
 ---
 purpose: The template-kit/size-section-css authoring rule — what it enforces, why, and how to fix it.
 status: living
-related: [INDEX.md, size-renderer-bundle.md, ../theme-and-css.md]
-updated: 2026-07-14
+related: [INDEX.md, size-renderer-bundle.md, size-assets.md, ../theme-and-css.md]
+updated: 2026-07-15
 ---
 # template-kit/size-section-css
 
@@ -16,7 +16,7 @@ everything that lands in the layer:
 
 - the section's hand-written CSS, and
 - **every package stylesheet its module graph imports** — the `import "swiper/css"` in a
-  component, an island, or a marked enhancer.
+  component or an island.
 
 The budget is **visible in `template-kit check`'s configuration and is not
 author-overridable**. A workspace cannot raise it, and there is no per-section exemption.
@@ -29,14 +29,15 @@ CSS blocks the first paint.
 
 "Including package CSS" is not a technicality; it is the failure this rule exists to catch.
 Your own stylesheet is almost never the problem — it is a few kilobytes of overrides. The
-package's is. And the reason it is invisible to you is the mechanism: a package stylesheet's
-`url()` references — its icon sprites, its webfont — are **inlined as `data:` URIs** into the
-compiled stylesheet. A 300 KB font file arrives in your published CSS without you ever
-having seen a 300 KB file. Nothing in your source looks large. Nothing in the package's
-`dist` listing looks alarming. The compiled layer is 400 KB.
+package's is. A one-line `import "some-ui/dist.css"` can drag in thousands of rules for
+components you never render — resets, theme variants, every widget's styles — and they all
+land in your compiled layer. Nothing in your source looks large; the compiled layer is
+400 KB.
 
 So the number this check reports is frequently the first time anyone finds out what a
-one-line CSS import actually cost.
+one-line CSS import actually cost. (What this budget does **not** count is asset bytes: a
+`url()`-referenced webfont or icon file resolves to a cached URL and is weighed separately —
+see [`size-assets`](size-assets.md).)
 
 ## Fix
 
@@ -45,10 +46,11 @@ Three moves, in order of how often they work:
 1. **Import the slimmest entry the package offers.** Most CSS-shipping packages have a core
    stylesheet plus opt-in modules, *and* a fat "everything" bundle that is the one you get
    from copying the quickstart. Take the core, plus only the modules you use.
-2. **Cut the webfont.** If the package's stylesheet drags in a font for its icons, and you
-   are using three of those icons, replace them with inline SVG — or with a family the
-   template's theme already declares in `fonts` (`--tr-font-<name>`), which costs nothing
-   because it is already loaded.
+2. **Drop the icon font.** If the package's stylesheet declares an icon font and you use
+   three of its glyphs, replace them with inline SVG — or with a family the template's theme
+   already declares in `fonts` (`--tr-font-<name>`), which costs nothing because it is
+   already loaded. (The font *file* is weighed under [`size-assets`](size-assets.md), but its
+   `@font-face` rules and every `.icon-*` class still land in this layer.)
 3. **Drop the package and hand-write the residue.** If you use one component from a large
    widget library, its stylesheet is paying for components you never render.
 
@@ -83,12 +85,15 @@ export default function Carousel({ slides }: { slides: { id: string; url: string
 ```
 
 The arrows and dots that came from the bundle's icon font are drawn as inline SVG in the
-component instead, so nothing pulls a webfont into the layer.
+component instead, so the layer no longer carries that font's `@font-face` and icon-class
+rules (and the font file no longer counts against [`size-assets`](size-assets.md) either).
 
 ## See also
 
 - [`size-renderer-bundle`](size-renderer-bundle.md) — the same budget on the section's
   JavaScript.
+- [`size-assets`](size-assets.md) — the separate budget on the static asset *files*
+  (fonts, images) a stylesheet or component references.
 - [`no-bare-css-import`](no-bare-css-import.md) — why a package's stylesheet is imported from
   code and never `@import`ed from CSS.
 - [Theme and CSS](../theme-and-css.md) — the fonts and tokens the page already loads, which

package/docs/schema-system.md

@@ -1,8 +1,8 @@
 ---
 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
+related: [primitives.md, theme-and-css.md, vocabulary.md]
+updated: 2026-07-16
 ---
 # The schema system
 
@@ -32,22 +32,17 @@ from. Without it, `SectionProps` cannot tell a required slot from an optional on
 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;
+import { direct, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
 
 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 },
+    hero_image: { type: "image", required: true, produced_by: "hero_image_assign", crop: { mode: "locked", aspect: 16 / 9 } },
+    headline: { type: "text", size: "medium", required: true, source: direct("address") },
+    blurb: { type: "text", size: "long", required: true, produced_by: "blurb_text" },
   },
   options: {
-    align: { type: "enum", values: ["left", "center"], default: "left" },
+    align: { type: "enum", values: ["left", "center"], default: "center" },
   },
 } as const satisfies SectionSchemaShape;
 
@@ -65,14 +60,20 @@ binds it to a computed transform. Both take names from a **closed vocabulary**,
 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
+source: direct("address")   // ✅
+source: direct("addresss")  // ✗ 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.
+The vocabulary is the kit's, not yours. Adding to it is a kit release, not a
+change you can make in a template. See [the closed vocabulary](vocabulary.md)
+for the sets and when to pick each; your editor autocompletes the exact fields.
+
+A `select` slot binds the same way as any other type — here fact-bound rather
+than AI-produced, with `values` declaring the closed set the fact resolves to:
+
+```ts
+listing_status: { type: "select", required: false, source: direct("listing_intent"), values: ["for_sale", "for_rent"] },
+```
 
 ### Grouping slots into one editor card
 
@@ -104,7 +105,6 @@ 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}>
@@ -153,12 +153,12 @@ export const fillSpec = {
   decisions: [
     { id: "hero_image_assign", type: "image-assign", produces: ["hero_image"], tag_query: "category:exterior" },
     {
-      id: "headline_text",
+      id: "blurb_text",
       type: "text-block",
-      produces: ["headline"],
-      length_cap: 60,
-      structure: "single_sentence",
-      voice_prompt: "Confident premium-listing voice. Title Case.",
+      produces: ["blurb"],
+      length_cap: 400,
+      structure: "paragraph",
+      voice_prompt: "Warm, concrete paragraph a buyer would want to read.",
     },
   ],
 } as const satisfies FillSpecShape;
@@ -177,14 +177,14 @@ 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",
+      headline: "101 Queensway, Jamaica Plain, MA 02130",
       hero_image: { photo_id: "p1", url: "https://example.com/a.jpg", alt: "Front elevation" },
+      blurb: "A bright corner home moments from the Emerald Necklace.",
     },
-    options: { align: "left" },
+    options: { align: "center" },
   },
   states: {
-    centered: { label: "Centered", options: { align: "center" } },
+    left: { label: "Left-aligned", options: { align: "left" } },
   },
 };
 

package/docs/theme-and-css.md

@@ -177,8 +177,8 @@ never write an import to make either happen:
    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
+   `Renderer.tsx`'s module graph — every component and island it imports — 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.

package/docs/vocabulary.md

@@ -0,0 +1,98 @@
+---
+purpose: The closed authoring vocabulary — slot types, direct() sources, derived() transforms, with selection semantics.
+status: living
+related: [schema-system.md]
+updated: 2026-07-15
+---
+# The closed authoring vocabulary
+
+Three closed sets. A slot's `type` picks its runtime value shape; a slot's
+`source` (`direct()` or `derived()`) picks which fact or computation fills it.
+This page is a selection reference — *which one to pick* — not a restatement
+of their field shapes.
+
+## Slot types
+
+| type | runtime value shape | pick it when |
+|---|---|---|
+| `text` | `string` (`string \| null` if optional) | one editable line/paragraph (`size` short\|medium\|long) |
+| `number` | `number` (`number \| null` if optional) | a numeric fact with formatting |
+| `select` | `string` (`string \| null` if optional) | a closed set of choices the user picks from |
+| `image` | `ImageValue` (`ImageValue \| null` if optional) | one framed photo (add `crop`/`frame`) |
+| `image_collection` | `ImageCollectionValue` | a gallery of framed photos |
+| `list` | `string[]` for a `text` element, `unknown[]` otherwise | a flat list of scalar items |
+| `poi_list` | `PoiRow[]` | neighborhood points of interest |
+| `url` | `string` (`string \| null` if optional) | a link the user edits in a URL field |
+| `object_list` | `Record<string, unknown>[]` | repeating, independently-editable multi-field items |
+
+The full per-type field shapes live in your editor's autocomplete and
+[schema-system.md](schema-system.md) — this page is only *which to pick*.
+
+## `direct()` sources
+
+The property facts a slot binds verbatim. A bad name is a compile error at
+the `direct(...)` call site.
+
+**Property facts** (resolve once per property):
+- `address` — the full formatted address
+- `listing_intent` — for-sale vs. for-rent state
+- `status` — the listing status, free text as shown on the listing (e.g. "For Sale")
+- `property_type` — the property type (`single_family` \| `condo_townhome` \| `multi_family` \| `investment`)
+- `year_built` — the year the property was built
+- `lot_size` — the lot size, pre-formatted text
+
+**Per-unit facts** (resolve against the current/single unit row):
+- `unit_label` — the unit's display label (e.g. "Unit 3B")
+- `beds` — bedroom count for this unit
+- `baths` — bathroom count for this unit
+- `sqft` — square footage for this unit
+- `price` — this unit's price, pre-formatted text
+- `notes` — free-text notes on this unit
+
+**List sources** (bind the whole array verbatim — pick these for `object_list`
+slots that repeat over every row):
+- `units` — every unit row on the property
+- `contacts` — every contact attached to the section
+
+**Per-contact fields** (resolve against the attached contact):
+- `name` — the contact's display name
+- `title` — the contact's job title/role
+- `bio` — the contact's bio copy
+- `email` — the contact's email address
+- `phone` — the contact's phone number
+- `website` — the contact's website URL
+- `instagram` — the contact's Instagram handle/URL
+- `linkedin` — the contact's LinkedIn handle/URL
+- `x` — the contact's X (Twitter) handle/URL
+- `facebook` — the contact's Facebook handle/URL
+
+**Contact images** (bind only to `image` slots):
+- `headshot` — the contact's headshot photo
+- `logo_dark` — the contact's logo, dark-background variant
+- `logo_light` — the contact's logo, light-background variant
+
+## `derived()` transforms
+
+Computed values, grouped by family. A bad name is a compile error at the
+`derived(...)` call site.
+
+| transform | what it computes |
+|---|---|
+| `units.bedsPrimary` | beds of the primary (lowest-position) unit |
+| `units.bathsPrimary` | baths of the primary unit |
+| `units.sqftPrimary` | sqft of the primary unit |
+| `units.pricePrimary` | price of the primary unit, pre-formatted text |
+| `units.bedsRange` | formatted beds range across all units (e.g. "2–4"), collapsing to one value when uniform |
+| `units.priceStart` | the lowest numeric unit price; falls back to the first non-numeric price (e.g. "Sold") when none is numeric |
+| `units.bedsMin` | the minimum beds across all units, formatted |
+| `units.bedsMax` | the maximum beds across all units, formatted |
+| `units.bathsMin` | the minimum baths across all units, formatted |
+| `units.bathsMax` | the maximum baths across all units, formatted |
+| `units.sqftMax` | the maximum sqft across all units, formatted |
+| `address.line1` | the property address's street line |
+| `address.line2` | the property address's city/state/zip line |
+| `contact_address.line1` | a contact's address street line |
+| `contact_address.line2` | a contact's address city/state/zip line |
+| `clock.currentYear` | the current year (e.g. for a copyright line) |
+| `coordinate.lat` | latitude, split from the property's geocode |
+| `coordinate.lng` | longitude, split from the property's geocode |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
   "license": "UNLICENSED",
   "type": "module",
@@ -41,6 +41,10 @@
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.js"
     },
+    "./ssr": {
+      "types": "./dist/ssr.d.ts",
+      "default": "./dist/ssr.js"
+    },
     "./eslint": {
       "types": "./dist/eslint.d.ts",
       "default": "./dist/eslint.js"
@@ -55,7 +59,7 @@
   ],
   "scripts": {
     "prepack": "npm run build",
-    "build": "tsdown",
+    "build": "tsdown && node scripts/build-dev-client.mjs && node scripts/build-cli-assets.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "pretest": "node test/link-fixture-workspace.mjs",
@@ -75,12 +79,15 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@changesets/cli": "^2.29.8",
     "@eslint/js": "^9.39.4",
+    "@playwright/test": "^1.60.0",
     "@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",
     "@typescript-eslint/parser": "^8.60.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "chokidar": "^4.0.1",
     "esbuild": "^0.28.1",
     "eslint": "^9.39.4",
     "jsdom": "^26.1.0",
@@ -91,9 +98,11 @@
     "tsdown": "0.22.7",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "typescript-eslint": "^8.60.1"
+    "typescript-eslint": "^8.60.1",
+    "vite": "^6.0.5"
   },
   "dependencies": {
+    "magic-string": "^0.30.21",
     "zod": "^4.4.3"
   }
 }

package/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "noEmit": true
   },
-  "exclude": ["node_modules", "dist", ".tmp-consumer", "test/fixtures"]
+  "exclude": ["node_modules", "dist", ".tmp-consumer", "test/fixtures", "create-homepages-workspace"]
 }