@homepages/template-kit 0.4.0 → 0.5.0

package/{docs → guide}/schema-system.md

@@ -1,7 +1,7 @@
 ---
 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, vocabulary.md]
+related: [primitives.md, theme-and-css.md, vocabulary.md, recipes/pick-a-scenario.md]
 updated: 2026-07-16
 ---
 # The schema system
@@ -12,7 +12,10 @@ Everything here is imported from the package root:
 import { direct, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
 ```
 
-There are no subpath imports for the authoring API — one specifier, on purpose.
+One specifier for everything a section renders from, on purpose. The lone exception is
+`@homepages/template-kit/fixtures`, which `fixtures.ts` imports the golden scenarios from
+— dev-only sample data is kept off the root barrel so it can never reach a published
+renderer's import graph.
 
 A section is **four files in one folder**. Three of them are declarations the
 platform reads; the fourth is your React.
@@ -75,6 +78,38 @@ than AI-produced, with `values` declaring the closed set the fact resolves to:
 listing_status: { type: "select", required: false, source: direct("listing_intent"), values: ["for_sale", "for_rent"] },
 ```
 
+### Video slots
+
+A `video` slot (or a `video_collection`) declares a hosted video the platform serves —
+not a link to a third-party player. It takes the same `frame` as an image, plus a
+`playback` config, and it takes **no `crop`**: a video is selected, never edited, so
+there is no cropper to steer and no re-edit state on the value.
+
+```ts
+hero_loop: {
+  type: "video",
+  frame: { breakpoint: 768, desktop: { aspect: 16 / 9 } },
+  playback: { autoplay: true, muted: true, loop: true, controls: false, preload: "auto" },
+},
+```
+
+Playback is **author-declared per slot** because the platform cannot infer it from the
+asset — a silent hero loop and a narrated walkthrough need opposite behavior. The fields
+are `autoplay`, `loop`, `muted`, `controls`, `playsinline`, and `preload`
+(`"none" | "metadata" | "auto"`); `preload: "none"` is the bandwidth lever for a
+below-fold video most visitors never reach. Omit `playback` entirely and
+[`Video`](primitives.md#video--the-hosted-video-primitive) renders a plain controls
+player.
+
+**`autoplay` requires `muted`.** Every browser blocks unmuted autoplay, so a slot
+declaring one without the other fails `check` rather than shipping a video that silently
+never plays. The type system cannot express the pair, so the `check` failure is the guard.
+
+A `VideoValue` is `{ video_id, url, poster, alt, width?, height? }`. `url` is always a
+single progressive MP4 rendition — there is no `responsive` ladder and no `mobile` variant
+to pass along, unlike an image. Read `url`, `poster`, `alt`, and the intrinsic
+`width`/`height`, and hand them to `Video`.
+
 ### Grouping slots into one editor card
 
 `meta.groups` collapses several slots into a single card in the editor sidebar. Each
@@ -132,7 +167,7 @@ is no framing for a renderer to apply. A slot's `crop` config steers the editor'
 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
+markers, images, videos — comes from the kit's six primitives; everything else is your own
 JSX. See [Contract primitives](primitives.md).
 
 Renderers must be **pure functions of props** — no fetches, no globals, no
@@ -167,7 +202,7 @@ export const fillSpec = {
 ## `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
+`states` adds named states, each overriding part of it — use them for the
 structural cases your section is designed to handle (a missing logo, a long
 headline, an empty list).
 
@@ -191,26 +226,72 @@ const fixtures: FixtureModule = {
 export default fixtures;
 ```
 
-### Build on the golden property, not on lorem ipsum
+### Build on a scenario, 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.
+Preview is only as honest as the data behind it, so the kit ships three complete,
+property-facts-shaped scenarios to build fixtures from — real addresses, unit counts, and
+contacts, the cases that actually break a layout. Pick the one whose breadth matches the
+state you're exercising:
 
 ```ts
-import { allPhotos, sampleProperty, sampleContacts, samplePois, sampleAmenities, mkResponsive } from "@homepages/template-kit";
+import { scenarios, primaryContact, poisByCategory, propertyMetrics, contactCards, mkResponsive }
+  from "@homepages/template-kit/fixtures";
+
+const s = scenarios.luxuryMultiUnit; // or sparseSingleFamily / forRentCondo
 ```
 
-| Export | What it is |
+| Scenario | Breadth |
+|---|---|
+| `luxuryMultiUnit` | 12-unit multi-family, for-sale, 3-agent team, 24 POIs, 20 photos, both logos, video + 3D tour — the breadth ceiling every section's `base` fixture builds on |
+| `sparseSingleFamily` | 1-unit single-family, for-sale, 1 contact, 4 POIs, 5 photos, no logos, no video/tour — the sparse floor a `states` entry exercises |
+| `forRentCondo` | 1-unit condo/townhome, for-rent, 2 contacts, 8 POIs, 10 photos, both logos, video only — the mid case |
+
+`scenarios` is also a `Record<ScenarioKey, Scenario>` for a picker; import a named
+scenario (`luxuryMultiUnit`, `sparseSingleFamily`, `forRentCondo`) directly when you only
+need one. This is a **separate entry**, deliberately not on the root barrel — dev-only
+sample data must never be reachable from a published renderer bundle's import graph.
+
+### Fill every slot from the scenario, by its fill-spec source
+
+A fixture's job is to answer, for every slot, "what would this look like on a real
+property?" — never to invent an answer. The scenario already has one; the fill-by-source
+rule says where to find it, keyed to the same `source` / `produced_by` a slot declares in
+`schema.ts`:
+
+| Slot's fill-spec source | How the fixture fills it |
 |---|---|
-| `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 |
+| direct (a fact) | read it off the scenario — `s.facts.address`, `primaryContact(s).fields.phone` |
+| derived | a helper — `propertyMetrics(s)`, `poisByCategory(s)`, `contactCards(s)` |
+| ai | a short sample fill **grounded in the scenario's facts** — a headline about *this* property, never lorem ipsum or invented facts |
+
+A fixture that gets this wrong is worse than a missing one: a slot bound
+`direct("beds")` whose fixture value doesn't match `s.facts.units[0].beds` teaches
+nothing about the layout it's supposed to preview.
+
+The helper functions project a scenario's raw facts into the shape a fixture usually
+wants, without re-typing the scenario's data:
+
+| Helper | Returns |
+|---|---|
+| `primaryContact(s)` | The scenario's primary contact (`ContactFixture`, position 0 by construction) — throws if the scenario has none |
+| `contactCards(s)` | Every attached contact, in order (`ContactFixture[]`) |
+| `poisByCategory(s)` | The scenario's POIs bucketed by category (`Record<PoiFixture["category"], PoiFixture[]>`) |
+| `propertyMetrics(s)` | Beds/baths/sqft/price off the lowest-position unit, `*Min`/`*Max`/`priceStart` across all units, and `addressLine1`/`addressLine2` |
 | `mkResponsive(url, width, height)` | Synthesizes a deterministic `ResponsiveImage` descriptor so `<Image responsive>` can be previewed and snapshotted |
 
+`propertyMetrics` returns kit fact vocabulary — `addressLine1`/`addressLine2`, never a
+template's own slot names, so the kit never learns what a section calls its slots. Map it
+to your slots at the call site: `address_street: m.addressLine1`.
+
+`s.photos`, `s.pois`, `s.amenities`, `s.contacts`, `s.media`, and `s.facts`
+(the raw `PropertyFacts`) are also readable straight off the scenario for slots that don't
+need a helper's projection — a gallery slot can bind directly to `s.photos`. A contact's
+org name and logos (`logo_light`/`logo_dark`) live on `ContactFixture["fields"]`, not on
+a sibling "brand" object — read them off `primaryContact(s).fields` or `s.contacts`.
+
+See [Pick a scenario](recipes/pick-a-scenario.md) for the full picker and helper
+cheat-sheet.
+
 ## Variants — rendering differently based on the facts
 
 A variant axis picks a case from the property's facts, before any content is

package/{docs → guide}/theme-and-css.md

@@ -2,7 +2,7 @@
 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, check.md]
-updated: 2026-07-15
+updated: 2026-07-16
 ---
 # Theme and CSS
 
@@ -224,7 +224,8 @@ not make: `font-smoothing`, `button { cursor: pointer }` (Tailwind v4 leaves but
 Ship `base.css` without a Tailwind entry on the page and you get an unreset page.
 
 `base.css` references **no design token of yours** — nothing global is opinionated about
-your brand. Its one tintable surface is the `Image` frame's placeholder fill; see
+your brand. Its one tintable surface is the placeholder fill shared by the `Image` and
+`Video` frames — one class, one `--tr-image-frame-bg`, so you retint both at once; see
 [`Image`](primitives.md#image--the-defensive-image-primitive).
 
 ## The breakpoint ladder

package/guide/upgrading.md

@@ -0,0 +1,61 @@
+---
+purpose: How to move a workspace to a new template-kit version, and what each kind of release means for you.
+status: living
+related: [check.md, pack.md, overview.md]
+updated: 2026-07-16
+---
+# Upgrading the kit
+
+Your workspace declares the kit like this:
+
+```json
+"dependencies": {
+  "@homepages/template-kit": "^0.4.0"
+}
+```
+
+The kit is pre-1.0, and at 0.x that caret means **`>=0.4.0 <0.5.0`**. That is
+deliberate: it gives you every safe update automatically and never a breaking one
+without you asking.
+
+## Two kinds of release
+
+**Patch (0.4.0 → 0.4.1) — features and fixes.** While the kit is pre-1.0, both
+land as patches. Your caret already allows them:
+
+```bash
+npm update @homepages/template-kit
+npm run check
+```
+
+**Minor (0.4.x → 0.5.0) — breaking.** At 0.x the minor is the breaking axis, so a
+minor bump means something you author against changed. `npm update` will **not**
+move you: a 0.x caret never crosses a minor. That is the caret doing its job.
+
+To take it, ask for it:
+
+```bash
+npm install @homepages/template-kit@^0.5.0
+npm run check
+```
+
+`check` is your migration list — it reports what the new version rejects. Read the
+CHANGELOG in the package (`node_modules/@homepages/template-kit/CHANGELOG.md`) for
+what changed and why.
+
+## How long you have
+
+Submissions are accepted against the current kit line **and the one before it**.
+So when 0.5.0 ships, a template packed on 0.4.x still submits fine — you have a
+full release cycle to migrate, and you are never blocked mid-template.
+
+Once a third line ships, the oldest drops out: `template-kit pack` still succeeds
+on it, but submitting that pack is refused, with the exact range to set in the
+message.
+
+## Checking where you are
+
+```bash
+npm ls @homepages/template-kit    # what you have installed
+npm view @homepages/template-kit version   # the current release
+```

package/{docs → guide}/vocabulary.md

@@ -2,7 +2,7 @@
 purpose: The closed authoring vocabulary — slot types, direct() sources, derived() transforms, with selection semantics.
 status: living
 related: [schema-system.md]
-updated: 2026-07-15
+updated: 2026-07-16
 ---
 # The closed authoring vocabulary
 
@@ -20,6 +20,8 @@ of their field shapes.
 | `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 |
+| `video` | `VideoValue` (`VideoValue \| null` if optional) | one hosted video (add `frame`/`playback`) |
+| `video_collection` | `VideoCollectionValue` | several hosted videos |
 | `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 |

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
     "node": ">=20.0.0"
   },
+  "workspaces": [
+    ".",
+    "create-homepages-workspace"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/falktravis/template-kit.git"
@@ -16,7 +20,7 @@
   },
   "files": [
     "dist",
-    "docs",
+    "guide",
     "tsconfig.json",
     "tsconfig.base.json",
     "CHANGELOG.md"
@@ -67,7 +71,8 @@
     "lint:pkg": "publint --strict && attw --pack . --profile esm-only --exclude-entrypoints styles.css base.css",
     "verify:consumer": "node scripts/verify-consumer.mjs",
     "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",
+    "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 && npm run check:scaffolder",
+    "check:scaffolder": "npm run typecheck -w create-homepages-workspace && npm run test -w create-homepages-workspace",
     "changeset": "changeset",
     "release": "changeset publish"
   },
@@ -102,6 +107,7 @@
     "vite": "^6.0.5"
   },
   "dependencies": {
+    "magic-string": "^0.30.21",
     "zod": "^4.4.3"
   }
 }

package/dist/node_modules/@jridgewell/sourcemap-codec/dist/sourcemap-codec.js

@@ -1,77 +0,0 @@
-//#region node_modules/@jridgewell/sourcemap-codec/dist/sourcemap-codec.mjs
-var comma = ",".charCodeAt(0);
-var semicolon = ";".charCodeAt(0);
-var chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-var intToChar = /* @__PURE__ */ new Uint8Array(64);
-var charToInt = /* @__PURE__ */ new Uint8Array(128);
-for (let i = 0; i < chars.length; i++) {
-	const c = chars.charCodeAt(i);
-	intToChar[i] = c;
-	charToInt[c] = i;
-}
-function encodeInteger(builder, num, relative) {
-	let delta = num - relative;
-	delta = delta < 0 ? -delta << 1 | 1 : delta << 1;
-	do {
-		let clamped = delta & 31;
-		delta >>>= 5;
-		if (delta > 0) clamped |= 32;
-		builder.write(intToChar[clamped]);
-	} while (delta > 0);
-	return num;
-}
-var bufLength = 1024 * 16;
-var td = typeof TextDecoder !== "undefined" ? /* @__PURE__ */ new TextDecoder() : typeof Buffer !== "undefined" ? { decode(buf) {
-	return Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString();
-} } : { decode(buf) {
-	let out = "";
-	for (let i = 0; i < buf.length; i++) out += String.fromCharCode(buf[i]);
-	return out;
-} };
-var StringWriter = class {
-	constructor() {
-		this.pos = 0;
-		this.out = "";
-		this.buffer = new Uint8Array(bufLength);
-	}
-	write(v) {
-		const { buffer } = this;
-		buffer[this.pos++] = v;
-		if (this.pos === bufLength) {
-			this.out += td.decode(buffer);
-			this.pos = 0;
-		}
-	}
-	flush() {
-		const { buffer, out, pos } = this;
-		return pos > 0 ? out + td.decode(buffer.subarray(0, pos)) : out;
-	}
-};
-function encode(decoded) {
-	const writer = new StringWriter();
-	let sourcesIndex = 0;
-	let sourceLine = 0;
-	let sourceColumn = 0;
-	let namesIndex = 0;
-	for (let i = 0; i < decoded.length; i++) {
-		const line = decoded[i];
-		if (i > 0) writer.write(semicolon);
-		if (line.length === 0) continue;
-		let genColumn = 0;
-		for (let j = 0; j < line.length; j++) {
-			const segment = line[j];
-			if (j > 0) writer.write(comma);
-			genColumn = encodeInteger(writer, segment[0], genColumn);
-			if (segment.length === 1) continue;
-			sourcesIndex = encodeInteger(writer, segment[1], sourcesIndex);
-			sourceLine = encodeInteger(writer, segment[2], sourceLine);
-			sourceColumn = encodeInteger(writer, segment[3], sourceColumn);
-			if (segment.length === 4) continue;
-			namesIndex = encodeInteger(writer, segment[4], namesIndex);
-		}
-	}
-	return writer.flush();
-}
-
-//#endregion
-export { encode };