@homepages/template-kit 0.4.0 → 0.5.0

package/{docs → guide}/overview.md

@@ -1,8 +1,8 @@
 ---
 purpose: The mental model in one page — workspace, templates, sections, and the server-vs-client mapping.
 status: living
-related: [schema-system.md, islands.md, rules/server-vs-client.md]
-updated: 2026-07-15
+related: [schema-system.md, islands.md, rules/server-vs-client.md, upgrading.md]
+updated: 2026-07-16
 ---
 # Overview
 
@@ -40,8 +40,8 @@ A **slot** is editable content; an **option** is a behavior switch — see
 the distinction and [the closed vocabulary](vocabulary.md) for the types.
 **Fill** is how AI assigns slot values via `fill-spec.ts`'s decisions, covered
 in [schema-system.md](schema-system.md#fill-spects--how-ai-fills-the-slots).
-**Fixtures** are the sample content a section previews against, built on the
-kit's golden property dataset — see
+**Fixtures** are the sample content a section previews against, sourced from the
+kit's golden scenarios by the fill-by-source rule — see
 [schema-system.md](schema-system.md#fixturests--content-for-local-preview).
 
 ## Server vs client — your Next.js instinct, mapped

package/{docs → guide}/pack.md

@@ -1,8 +1,8 @@
 ---
 purpose: The `template-kit pack` command — what it produces, what it refuses, and why.
 status: living
-related: [INDEX.md, check.md]
-updated: 2026-07-15
+related: [INDEX.md, check.md, upgrading.md]
+updated: 2026-07-16
 ---
 # template-kit pack
 

package/{docs → guide}/primitives.md

@@ -1,20 +1,21 @@
 ---
-purpose: The five contract primitives a section renderer must use, and the marker attributes they emit.
+purpose: The six 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-15
+related: [schema-system.md, theme-and-css.md, eslint.md, upgrading.md]
+updated: 2026-07-16
 ---
 # Contract primitives
 
 Everything here is imported from the package root:
 
 ```tsx
-import { Image, Section, Slot, SlotGroup, SlotItem } from "@homepages/template-kit";
+import { Image, Section, Slot, SlotGroup, SlotItem, Video } from "@homepages/template-kit";
 ```
 
-The kit ships **five components, and nothing else**. That is deliberate: a primitive
+The kit ships **six 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.
+box model, the editor's marker attributes, the responsive-image machinery, the
+poster/playback contract for hosted video.
 Presentation is yours. Headings, links, layout wells, icons, lists, cards: write them
 as JSX in your section, or reach for a package.
 
@@ -22,9 +23,10 @@ as JSX in your section, or reach for a package.
 |---|---|---|
 | `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 |
+| `SlotItem` | `data-slot-item` | around each item of an `object_list` / `image_collection` / `video_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>` |
+| `Video` | the poster frame / the playback config / the empty-state box | every video — sections never write a raw `<video>` |
 
 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.
@@ -86,8 +88,8 @@ 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.
+A collection slot (`object_list`, `image_collection`, `video_collection`) needs **both**
+markers: `<Slot>` marks the whole array, `<SlotItem>` marks one row of it.
 
 ```tsx
 <Slot id="amenities">
@@ -193,6 +195,51 @@ 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.
 
+## `Video` — the hosted-video primitive
+
+Sections never write a raw `<video>`. `Video` owns the poster frame, the author-declared
+playback config, and the same layout box that survives a missing source.
+
+```tsx
+<Video
+  slotId="tour_video"
+  src={slots.tour_video.url}
+  poster={slots.tour_video.poster}
+  alt={slots.tour_video.alt}
+  playback={schema.slots.tour_video.playback}
+  aspectRatio="16 / 9"
+/>
+```
+
+| Prop | Meaning |
+|---|---|
+| `src` | The rendition URL. Required prop; `null`/empty is a supported state, not a bug. |
+| `poster` | Poster-frame URL. The first paint, and the entire render while `src` is empty. |
+| `alt` | Required. Empty string for a purely decorative loop. |
+| `slotId` | Emits `data-slot-id` on the wrapper — a video slot needs no `<Slot>` around it. |
+| `aspectRatio` | CSS `aspect-ratio` reserved on the wrapper. Survives a missing `src`. |
+| `playback` | The slot's [`playback` config](schema-system.md#video-slots). Absent ⇒ a plain controls player. |
+| `width` / `height` | Intrinsic rendition dimensions (`VideoValue.width`/`height`) — reserve the box before metadata loads. |
+
+**Framed, always.** There is no `bare` escape hatch: a wrapper `div` carries the slot
+marker and the aspect-ratio box, and absolutely-positions the inner `<video>` with
+`object-cover`. When `src` is empty the wrapper renders the poster alone — or a neutral
+`role="img"` rect if there is no poster — keeping the layout box and the slot selectable.
+Both empty states are routine: an unfilled video slot is a thin listing, and a poster with
+no rendition is what a video still transcoding looks like.
+
+The placeholder fill rides on the same `.tr-image-frame` class `<Image>` uses (from
+[`base.css`](theme-and-css.md#basecss-requires-a-tailwind-entry)) — one neutral rect, one
+`--tr-image-frame-bg` token, so a template retints both frames once.
+
+**Playback is passed through verbatim** — the primitive infers nothing from the asset.
+The config is authored on the slot, not chosen here; see
+[Video slots](schema-system.md#video-slots) for the fields and the `autoplay`-requires-`muted`
+rule.
+
+There is no cropping and no responsive ladder: one progressive MP4 is served per video,
+and the poster is derived upstream.
+
 ## The marker contract
 
 The primitives are the sanctioned way to produce these attributes. The constants are
@@ -201,14 +248,15 @@ magic string.
 
 | Constant | Attribute | On |
 |---|---|---|
-| `ATTR_SLOT_ID` | `data-slot-id` | the `Slot` wrapper / `Image`'s framed wrapper |
+| `ATTR_SLOT_ID` | `data-slot-id` | the `Slot` wrapper / `Image`'s and `Video`'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 |
 
 Changing what an attribute means is a platform contract break, so these names are stable
-across a major version of the kit.
+across patch releases of the kit; a rename is exactly the kind of breaking change that
+ships as a minor bump (see [Upgrading the kit](upgrading.md)).
 
 ## Renderers stay pure
 

package/{docs → guide}/recipes/INDEX.md

@@ -18,6 +18,7 @@ copy the shapes from its recipe, not from memory.
 | give the user a closed set of choices | [`select-slot.md`](select-slot.md) |
 | add a repeating list the user edits per item (unit table, cards, gallery) | [`collection-slot.md`](collection-slot.md) |
 | have AI write a slot's content | [`fill-spec-decision.md`](fill-spec-decision.md) |
+| source a fixture from a real property, not invented values | [`pick-a-scenario.md`](pick-a-scenario.md) |
 | preview a section's structural edge cases / states | [`fixture-states.md`](fixture-states.md) |
 | make part of a section interactive (an island) | [`interactive-island.md`](interactive-island.md) |
 | organize a section's files beyond the four reserved | [`organize-section-folder.md`](organize-section-folder.md) |

package/{docs → guide}/recipes/collection-slot.md

@@ -1,7 +1,7 @@
 ---
 purpose: Add a repeating list whose items the editor selects and edits one at a time.
 status: living
-related: [../primitives.md, ../vocabulary.md, ../schema-system.md, bind-property-fact.md]
+related: [../primitives.md, ../vocabulary.md, ../schema-system.md, bind-property-fact.md, pick-a-scenario.md]
 updated: 2026-07-16
 ---
 # A collection slot — a repeating, per-item list
@@ -58,10 +58,10 @@ type UnitRow = { unit_label: string; beds: number; baths: number; sqft: number;
 ```
 
 ```ts
-// fixtures.ts — supply the array from the golden property
-import { allPhotos, mkResponsive, sampleProperty } from "@homepages/template-kit/fixtures";
+// fixtures.ts — supply the array from a scenario's facts
+import { scenarios } from "@homepages/template-kit/fixtures";
 // ...in base.slots:
-units: sampleProperty.units,
+units: scenarios.luxuryMultiUnit.facts.units,
 ```
 
 Two contracts to know before you widen this:
@@ -73,9 +73,10 @@ Two contracts to know before you widen this:
 - **An `item` needs more than one field, or a non-scalar one** — a lone scalar
   field is rejected; use a `list` slot for a flat list of scalars.
 
-`object_list` is one of four collection types. A gallery of framed photos is an
-`image_collection`, a flat scalar list is a `list`, neighborhood points are a
-`poi_list` — same `<SlotItem>` render pattern, different value shape. See
+`object_list` is one of five collection types. A gallery of framed photos is an
+`image_collection`, several hosted videos are a `video_collection`, a flat scalar list is
+a `list`, neighborhood points are a `poi_list` — same `<SlotItem>` render pattern,
+different value shape. See
 [the slot types](../vocabulary.md#slot-types) for which to pick.
 
 ## Commands
@@ -92,7 +93,8 @@ Verify with [the author loop](../quickstart.md#the-author-loop).
   the `SlotItem` / `SlotGroup` contract: both markers a collection needs, and why
   `index` must be the row's array position.
 - [The closed vocabulary](../vocabulary.md#slot-types) — every collection slot type
-  (`object_list` / `image_collection` / `poi_list` / `list`) and the `direct()` List sources.
+  (`object_list` / `image_collection` / `video_collection` / `poi_list` / `list`) and the
+  `direct()` List sources.
 - [The schema system](../schema-system.md#fill-spects--how-ai-fills-the-slots) — the
   `produced_by` decision types (`structured-list`, `list-extract`, `image-collection`)
   for a collection AI fills instead of binding to a fact.

package/guide/recipes/fixture-states.md

@@ -0,0 +1,109 @@
+---
+purpose: Preview a section's structural edge cases.
+status: living
+related: [../schema-system.md, ../dev.md, pick-a-scenario.md]
+updated: 2026-07-16
+---
+# Preview a section's structural edge cases
+
+## Goal
+
+Preview a section's structural edge cases.
+
+## The delta
+
+Add entries under `states` in `fixtures.ts` — each one overrides part of
+`base`, the same pattern the starter's `left` and `long-blurb` states use.
+A `states` entry is for a DESIGNED case, not raw coverage: nullability
+and empty-slot coverage (every optional slot rendered empty) is derived
+automatically from `schema.ts`, so a fixture state is for a case the
+section renders *differently* — a content-length branch, an option branch,
+or several overrides combined.
+
+```ts
+// fixtures.ts — a content-length case and an option-branch case
+const fixtures: FixtureModule = {
+  base: {
+    slots: {
+      headline: "101 Queensway, Jamaica Plain, MA 02130",
+      summary: "A 12-unit mansard Victorian moments from the Emerald Necklace.",
+    },
+    options: { align: "center" },
+  },
+  states: {
+    // Content-length branch: exercises a long value's wrap/expand behavior.
+    "long-summary": {
+      slots: {
+        summary:
+          "A 12-unit mansard Victorian moments from the Emerald Necklace, with a " +
+          "terrazzo lobby, an on-site gym, quartz kitchens throughout, and a " +
+          "top-floor penthouse with a private rooftop terrace and skyline views.",
+      },
+    },
+    // Option branch: exercises the layout under the other enum value.
+    left: { options: { align: "left" } },
+  },
+};
+```
+
+Each `states` key names a state; its value overrides `slots` and/or
+`options` on top of `base` — omit either key to inherit `base`'s value
+unchanged. Each state is a selectable fixture in the dev preview, so every one
+you add is there to render and review alongside `base`.
+
+### Swap the whole scenario
+
+A state can also be designed to look different against a *sparser property* — fewer
+units, no logo, no video — rather than a content-length or option branch. Source that
+kind of state from a different scenario, not from hand-picked overrides:
+
+```ts
+// fixtures.ts — a `sparse` state sourced from a different scenario
+import { scenarios } from "@homepages/template-kit/fixtures";
+
+const luxury = scenarios.luxuryMultiUnit;
+const sparse = scenarios.sparseSingleFamily;
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: {
+      headline: luxury.facts.address,
+      summary: "A 12-unit mansard Victorian moments from the Emerald Necklace.",
+    },
+    options: { align: "center" },
+  },
+  states: {
+    sparse: {
+      slots: {
+        headline: sparse.facts.address,
+        summary:
+          "A classic center-hall colonial with an updated kitchen and original " +
+          "hardwood floors throughout.",
+      },
+    },
+  },
+};
+```
+
+Fill every slot in a scenario-swapped state the same way you filled `base` — by the
+slot's fill-spec source, never with a placeholder. See
+[the fill-by-source rule](../schema-system.md#fill-every-slot-from-the-scenario-by-its-fill-spec-source)
+and [Pick a scenario](pick-a-scenario.md) for the picker and helper cheat-sheet.
+
+## Commands
+
+None — this is a pure content edit. No CLI command beyond the author loop below.
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop).
+
+## See also
+
+- [The schema system](../schema-system.md#fixturests--content-for-local-preview) —
+  the `fixtures.ts` contract: `base`, `states`, the scenario breadth table, and the
+  fill-by-source rule.
+- [Pick a scenario](pick-a-scenario.md) — the scenario picker and helper cheat-sheet a
+  scenario-swapped state builds on.
+- [`template-kit dev`](../dev.md) — the preview server that renders each
+  fixture state across the breakpoint ladder.

package/{docs → guide}/recipes/image-slot-crop.md

@@ -1,8 +1,8 @@
 ---
 purpose: Add an image slot the editor crops to a fixed ratio.
 status: living
-related: [../schema-system.md, ../primitives.md, ../rules/image-bare-needs-reason.md]
-updated: 2026-07-15
+related: [../schema-system.md, ../primitives.md, ../rules/image-bare-needs-reason.md, pick-a-scenario.md]
+updated: 2026-07-16
 ---
 # Image slot with a locked crop
 
@@ -52,7 +52,9 @@ interior_image: {
 
 ```ts
 // fixtures.ts — a photo + a matching mkResponsive() height
-const interiorImage = allPhotos[3]!;
+import { mkResponsive, scenarios } from "@homepages/template-kit/fixtures";
+
+const interiorImage = scenarios.luxuryMultiUnit.photos[3]!;
 // ...
 interior_image: {
   photo_id: interiorImage.id,

package/guide/recipes/pick-a-scenario.md

@@ -0,0 +1,119 @@
+---
+purpose: Source a fixture's slots from real property data, by the fill-by-source rule.
+status: living
+related: [../schema-system.md, fixture-states.md, ../vocabulary.md]
+updated: 2026-07-16
+---
+# Pick a scenario for a fixture
+
+## Goal
+
+Fill a section's `fixtures.ts` from the kit's golden scenarios instead of inventing
+values, so preview stays honest and every fixture is grounded in a real,
+self-consistent property.
+
+## The delta
+
+### Pick a scenario
+
+Import `scenarios` from the fixtures entry — never the root barrel; dev-only sample
+data must never reach a published renderer bundle's import graph — and pick the one
+whose breadth matches the state you're building:
+
+```ts
+import { scenarios } from "@homepages/template-kit/fixtures";
+
+const luxury = scenarios.luxuryMultiUnit; // 12 units, 3 contacts, both logos, video + 3D tour
+const sparse = scenarios.sparseSingleFamily; // 1 unit, 1 contact, no logos, no media
+const rent = scenarios.forRentCondo; // 1 unit, 2 contacts, both logos, video only
+```
+
+`base` almost always builds on `luxuryMultiUnit` — it's the breadth ceiling, so a
+layout that survives it survives everything smaller. Reach for `sparseSingleFamily`
+or `forRentCondo` for a [`states`](fixture-states.md) entry designed to look
+different against a thinner property.
+
+| Scenario | units | listing_intent | property_type | contacts | pois | photos | contact logos | media |
+|---|---|---|---|---|---|---|---|---|
+| `luxuryMultiUnit` | 12 | for_sale | multi_family | 3 | 24 | 20 | both logos | video + 3D tour |
+| `sparseSingleFamily` | 1 | for_sale | single_family | 1 | 4 | 5 | none (null) | none (null) |
+| `forRentCondo` | 1 | for_rent | condo_townhome | 2 | 8 | 10 | both logos | video only |
+
+### Fill every slot by its fill-spec source
+
+Don't invent a value. Every slot in `schema.ts` already declares how it's filled in
+production — `fixtures.ts` mirrors that:
+
+| Slot's fill-spec source | How the fixture fills it |
+|---|---|
+| 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 cheat-sheet
+
+```ts
+import {
+  contactCards,
+  mkResponsive,
+  poisByCategory,
+  primaryContact,
+  propertyMetrics,
+  scenarios,
+} from "@homepages/template-kit/fixtures";
+
+const s = scenarios.luxuryMultiUnit;
+```
+
+| 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, `bedsMin`/`bedsMax`/`bathsMin`/`bathsMax`/`sqftMax`/`priceStart` across all units, and `addressLine1`/`addressLine2` |
+| `mkResponsive(url, width, height)` | A deterministic `ResponsiveImage` descriptor so `<Image responsive>` can be previewed and snapshotted |
+
+`propertyMetrics` returns kit fact vocabulary — `addressLine1`/`addressLine2`, not 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:
+
+```ts
+const m = propertyMetrics(s);
+// ...in base.slots:
+address_street: m.addressLine1,
+address_locality: m.addressLine2,
+```
+
+Fields the helpers don't cover are readable straight off the scenario: `s.photos`,
+`s.pois`, `s.amenities`, `s.contacts`, `s.media`, and `s.facts` (the raw
+`PropertyFacts`). 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`.
+
+### Add a scenario-driven state
+
+A `states` entry designed to look different against a sparser property sources from a
+different scenario, not from overridden literals — see
+[Preview a section's structural edge cases](fixture-states.md#swap-the-whole-scenario)
+for the full pattern.
+
+## Commands
+
+None — this is a pure content edit. No CLI command beyond the author loop below.
+
+## Verify
+
+Verify with [the author loop](../quickstart.md#the-author-loop).
+
+## See also
+
+- [The schema system](../schema-system.md#fixturests--content-for-local-preview) —
+  the `fixtures.ts` contract, the scenario breadth table, and the fill-by-source rule.
+- [Preview a section's structural edge cases](fixture-states.md) — `states`, including
+  a scenario-swapped state.
+- [The closed vocabulary](../vocabulary.md#direct-sources) — the `direct()` fields a
+  scenario's `facts` supplies.

package/{docs → guide}/rules/INDEX.md

@@ -7,7 +7,7 @@ updated: 2026-07-15
 # Rules
 
 Every authoring rule the kit enforces is printed under one namespace, `template-kit/<id>`,
-and resolves to exactly one page here: `docs/rules/<id>.md`.
+and resolves to exactly one page here: `guide/rules/<id>.md`.
 
 **One namespace, two venues.** Some rules are properties of **one file** (a `Date.now()`
 in a Renderer) and are enforced by the ESLint preset. Others are properties of the
@@ -28,7 +28,7 @@ and it is explained there rather than on each of them.
 | [`no-client-directive-in-contract`](no-client-directive-in-contract.md) | eslint | No "use client" in a section's four contract files. |
 | [`props-from-schema`](props-from-schema.md) | eslint | A Renderer's Props type must be derived from schema.ts, not hand-written. |
 | [`no-inline-style`](no-inline-style.md) | eslint | No inline style= in server-rendered JSX. Islands are exempt. |
-| [`no-raw-element`](no-raw-element.md) | eslint | No raw `<section>` or `<img>` — use `<Section>` and `<Image>`. |
+| [`no-raw-element`](no-raw-element.md) | eslint | No raw `<section>`, `<img>` or `<video>` — use `<Section>`, `<Image>` and `<Video>`. |
 | [`image-bare-needs-reason`](image-bare-needs-reason.md) | eslint | `<Image bare>` needs a `// bare:` comment saying why it skips the frame. |
 | [`slot-marker-literal`](slot-marker-literal.md) | eslint | A slot-marker key must be a string literal, not an expression. |
 | [`no-hex`](no-hex.md) | eslint | No hard-coded colours — the one legal colour function is a `color-mix()` over theme-derived arguments. Islands are NOT exempt. |

package/{docs → guide}/rules/fixtures-invalid.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/fixtures-invalid authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../schema-system.md, schema-invalid.md]
-updated: 2026-07-14
+updated: 2026-07-16
 ---
 # template-kit/fixtures-invalid
 
@@ -21,7 +21,7 @@ The default export of `fixtures.ts` must satisfy the fixture-module shape:
     variants: { /* optional */ },
   },
   option_matrix: [ /* optional: { label?, options } entries */ ],
-  states: { /* optional: named scenario → { label?, slots?, options?, anchors?, variants? } */ },
+  states: { /* optional: named state → { label?, slots?, options?, anchors?, variants? } */ },
 }
 ```
 

package/{docs → guide}/rules/no-raw-element.md

@@ -6,28 +6,29 @@ updated: 2026-07-14
 ---
 # template-kit/no-raw-element
 
-> **Exactly two** raw elements are banned: `<section>` and `<img>`. Every other tag is
-> yours.
+> **Exactly three** raw elements are banned: `<section>`, `<img>` and `<video>`. Every
+> other tag is yours.
 
 ## Rule
 
-Two tags, and no others:
+Three tags, and no others:
 
 | Raw tag | Use instead |
 |---|---|
 | `<section>` | `<Section>` |
 | `<img>` | `<Image>` |
+| `<video>` | `<Video>` |
 
 That is the entire rule. **`<a>`, `<h1>`–`<h6>`, `<div>`, `<ul>`, `<button>`, `<picture>`,
 `<figure>` — every other element is yours to write.** Presentation is the template's own
 JSX; the kit is not trying to own your markup. If you have concluded "the kit bans raw
 HTML", that is exactly backwards.
 
-There is no island exemption: the two tags are banned in a `"use client"` file too.
+There is no island exemption: the three tags are banned in a `"use client"` file too.
 
 ## Reason
 
-Each of the two banned tags has a **contract-bearing primitive that must emit it**, and
+Each of the three banned tags has a **contract-bearing primitive that must emit it**, and
 writing the raw tag skips the contract.
 
 - **`<Section>`** emits `<section class="tr-section">`, which is full-bleed by contract:
@@ -40,9 +41,13 @@ writing the raw tag skips the contract.
   or a broken-image icon on a real customer's page — and a missing image is a **supported
   state**, not a bug: it happens whenever a listing is thin. `<Image slotId>` also emits
   the slot marker itself, so the image stays selectable in the editor.
+- **`<Video>`** owns the poster frame, the author-declared playback config, and the same
+  fallback rect — a video slot may be empty (a thin listing) or still transcoding, and
+  neither may collapse the layout. A raw `<video>` also skips the slot marker, so the
+  video stops being selectable in the editor.
 
-The two tags are banned because they are the two the platform has to be able to trust.
-Everything else carries no contract, so nothing is gained by policing it.
+The three tags are banned because they are the three the platform has to be able to
+trust. Everything else carries no contract, so nothing is gained by policing it.
 
 ## Fix
 
@@ -95,6 +100,6 @@ The `<h2>` stays exactly as it was. `Image` takes `src`/`alt` directly — a `nu
 
 ## See also
 
-- [Contract primitives](../primitives.md) — all five primitives and the markers they emit.
+- [Contract primitives](../primitives.md) — every primitive and the markers they emit.
 - [`image-bare-needs-reason`](image-bare-needs-reason.md) — the escape hatch that drops
   `<Image>`'s frame, and what it costs.

package/{docs → guide}/rules/render-invariant.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/render-invariant authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../primitives.md, ../schema-system.md]
-updated: 2026-07-14
+updated: 2026-07-16
 ---
 # template-kit/render-invariant
 
@@ -51,7 +51,8 @@ routine, not exceptional** — and your markup has to say what happens then.
 Worth being precise, because the obvious guesses are wrong. Rendering a nullish slot as a
 **child** is safe: React renders `null` and `undefined` as nothing, so `<p>{slots.year_built}</p>`
 on a thin listing is an empty `<p>`, not the text `undefined`. And a list slot is **never
-`null`** — `list`, `object_list`, `poi_list` and `image_collection` always arrive as an array
+`null`** — `list`, `object_list`, `poi_list`, `image_collection` and `video_collection`
+always arrive as an array
 (empty when absent), so `.map` cannot throw and `?? []` buys you nothing.
 
 The defects come from three narrower places:
@@ -107,7 +108,7 @@ export function Renderer({ slots }: Props) {
 }
 ```
 
-On the golden property this renders perfectly. On a listing with no year, an unpriced unit,
+On the richest golden scenario this renders perfectly. On a listing with no year, an unpriced unit,
 and no floor plan it ships `built null`, `2 Bed · undefined`, `NaN sq ft heated`, and
 `<img src="">`.