@homepages/template-kit 0.8.1-dev-20260718224903 → 0.9.0-dev-20260719224319

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

@@ -2,7 +2,7 @@
 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
+updated: 2026-07-19
 ---
 # Pick a scenario for a fixture
 
@@ -59,7 +59,6 @@ nothing about the layout it's supposed to preview.
 ```ts
 import {
   contactCards,
-  mkResponsive,
   poisByCategory,
   primaryContact,
   propertyMetrics,
@@ -75,7 +74,6 @@ const s = scenarios.luxuryMultiUnit;
 | `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
@@ -90,10 +88,20 @@ 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
+`PropertyFacts`). A contact's org name and logos (`logo_light_id`/`logo_dark_id`) live
+on `ContactFixture["fields"]`, not on a sibling "brand" object — read them off
 `primaryContact(s).fields` or `s.contacts`.
 
+### Media comes off the scenario as an id
+
+Every media reference in a scenario is an **asset id**, the same thing a saved page
+holds — `s.photos[n].id`, `primaryContact(s).fields.headshot_id` / `.logo_light_id` /
+`.logo_dark_id`, `s.media.video_id`, and a floor plan ref's `id`. Put the id in the
+fixture and stop there: the url, the `alt` fallback, and the responsive ladder are
+attached for you when the fixture loads. Never state a url in a fixture.
+(`s.media.tour_3d_url` is the one exception — a 3D tour is a third-party embed with no
+asset behind it.)
+
 ### Add a scenario-driven state
 
 A `states` entry designed to look different against a sparser property sources from a

package/guide/rules/INDEX.md

@@ -2,7 +2,7 @@
 purpose: Router for the rule corpus — every template-kit/<id> an author can hit, and the page that explains it.
 status: living
 related: [server-vs-client.md, ../eslint.md, ../check.md, ../INDEX.md]
-updated: 2026-07-17
+updated: 2026-07-19
 ---
 # Rules
 
@@ -10,7 +10,8 @@ Every authoring rule the kit enforces is printed under one namespace, `template-
 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
+in a Renderer) and are enforced by the [ESLint preset](../eslint.md), which ships as its
+own package, `@homepages/eslint-plugin-template`. Others are properties of the
 **tree** (a slot declared in `schema.ts` but never marked in the JSX, a stylesheet, a
 dependency, a byte budget) and cannot be expressed one file at a time; those are enforced
 by [`template-kit check`](../check.md). You never need to know which engine produced a

package/guide/schema-system.md

@@ -2,7 +2,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, recipes/pick-a-scenario.md]
-updated: 2026-07-17
+updated: 2026-07-19
 ---
 # The schema system
 
@@ -229,12 +229,16 @@ headline, an empty list).
 
 ```ts
 import type { FixtureModule } from "@homepages/template-kit";
+import { scenarios } from "@homepages/template-kit/fixtures";
 
 const fixtures: FixtureModule = {
   base: {
     slots: {
       headline: "101 Queensway, Jamaica Plain, MA 02130",
-      hero_image: { photo_id: "p1", url: "https://example.com/a.jpg", alt: "Front elevation" },
+      // An image slot states the asset id a real page holds — never a URL. The
+      // preview server resolves it to a url, an alt fallback, and a responsive
+      // ladder, exactly as the platform does when the page is published.
+      hero_image: { photo_id: scenarios.luxuryMultiUnit.photos[19]!.id, alt: "Front elevation" },
       blurb: "A bright corner home moments from the Emerald Necklace.",
     },
     options: { align: "center" },
@@ -255,7 +259,7 @@ contacts, the cases that actually break a layout. Pick the one whose breadth mat
 state you're exercising:
 
 ```ts
-import { scenarios, primaryContact, poisByCategory, propertyMetrics, contactCards, mkResponsive }
+import { scenarios, primaryContact, poisByCategory, propertyMetrics, contactCards }
   from "@homepages/template-kit/fixtures";
 
 const s = scenarios.luxuryMultiUnit; // or sparseSingleFamily / forRentCondo
@@ -298,7 +302,6 @@ wants, without re-typing the scenario's data:
 | `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
@@ -307,8 +310,29 @@ 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`.
+org name and logos (`logo_light_id`/`logo_dark_id`) live on `ContactFixture["fields"]`,
+not on a sibling "brand" object — read them off `primaryContact(s).fields` or
+`s.contacts`.
+
+### Media is stated by id, never by URL
+
+A fixture's job is to state what a **saved page** holds, and a saved page holds an
+asset id — the platform turns that id into a served URL at render time. So a fixture
+does the same: give an image slot a `photo_id` (a video slot a `video_id`), and the
+url, the `alt` fallback, and the responsive ladder are attached for you when the
+fixture loads, in the preview server and in `check` alike. A fixture that states a
+URL is exercising a path real content never takes.
+
+The ids to use are the scenario's own: `s.photos[n].id` for a photo,
+`primaryContact(s).fields.headshot_id` / `.logo_light_id` / `.logo_dark_id` for a
+contact's images, `s.media.video_id` for the hosted video. `s.media.tour_3d_url`
+stays a URL on purpose — a 3D tour is a third-party embed the platform does not host,
+so there is no asset to name. Floor plan refs
+(`s.facts.units[*].floor_plans`) likewise carry only `id`/`floor_label`/`position`;
+their `url`, `alt`, and `responsive` are optional and appear only after resolution.
+
+An id that names nothing resolves to an empty image, which previews as an empty slot
+rather than an error — so take the ids off the scenario rather than typing them.
 
 See [Pick a scenario](recipes/pick-a-scenario.md) for the full picker and helper
 cheat-sheet.
@@ -318,14 +342,14 @@ cheat-sheet.
 A scenario is the **fixture view** of a property, not the fact bundle the AI-fill pipeline
 reads. The difference matters when you write a `fill-spec.ts`:
 
-- Scenarios carry values that only exist *after* fill and render — `UnitRow.description`
-  and `features` are AI-written copy; a floor plan's `url` and `alt` are attached when the
-  image is served. Nothing upstream produces these; they are here so your renderer has
-  something real to draw.
+- Scenarios carry values that only exist *after* fill — `UnitRow.description` and
+  `features` are AI-written copy. Nothing upstream produces these; they are here so your
+  renderer has something real to draw.
 - Scenarios hoist some facts **out** of `facts` and onto the scenario itself, in the shapes
   a renderer wants: `photos` → `s.photos` (`PhotoFixture[]`), `pois` → `s.pois`
-  (`PoiFixture[]`), and the fact bundle's `tours` → `s.media` — a single `MediaFixture`
-  **object** (`video_url`, `tour_3d_url`), not an array. Floor plans hoist too, but onto
+  (`PoiFixture[]`), and the fact bundle's hosted videos and `tours` → `s.media` — a
+  single `MediaFixture` **object**, not an array: `video_id` names one hosted video
+  asset, `tour_3d_url` the third-party embed link. Floor plans hoist too, but onto
   each unit: `s.facts.units[*].floor_plans` (`FloorplanAssignment[]`).
 - `contacts` is **duplicated, not hoisted**. `s.contacts` holds the render-shaped
   `ContactFixture[]` your renderer draws, and `facts.contacts` still exists as well — so a

package/guide/upgrading.md

@@ -1,8 +1,8 @@
 ---
 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
+related: [check.md, pack.md, overview.md, eslint.md]
+updated: 2026-07-19
 ---
 # Upgrading the kit
 
@@ -43,6 +43,20 @@ npm run check
 CHANGELOG in the package (`node_modules/@homepages/template-kit/CHANGELOG.md`) for
 what changed and why.
 
+## The lint preset upgrades separately
+
+`@homepages/eslint-plugin-template` is its own package with its own version line,
+so the kit's number tells you nothing about it and `npm update
+@homepages/template-kit` never moves it. Update it the same way, on its own:
+
+```bash
+npm update @homepages/eslint-plugin-template
+```
+
+It declares the kit as a **peer dependency**, so its range says which kit line it
+supports. If `npm install` reports a peer conflict after a kit minor, the preset is
+the package to bump — not the kit to hold back.
+
 ## How long you have
 
 Submissions are accepted against the current kit line **and the one before it**.
@@ -59,3 +73,5 @@ message.
 npm ls @homepages/template-kit    # what you have installed
 npm view @homepages/template-kit version   # the current release
 ```
+
+The same two commands work for `@homepages/eslint-plugin-template`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.8.1-dev-20260718224903",
+  "version": "0.9.0-dev-20260719224319",
   "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
   "license": "UNLICENSED",
   "type": "module",
@@ -46,9 +46,13 @@
       "types": "./dist/ssr.d.ts",
       "default": "./dist/ssr.js"
     },
-    "./eslint": {
-      "types": "./dist/eslint.d.ts",
-      "default": "./dist/eslint.js"
+    "./rules": {
+      "types": "./dist/rules.d.ts",
+      "default": "./dist/rules.js"
+    },
+    "./canvas-core": {
+      "types": "./dist/canvas-core.d.ts",
+      "default": "./dist/canvas-core.js"
     },
     "./styles.css": "./dist/styles.css",
     "./base.css": "./dist/base.css",

package/tsconfig.json

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