@homepages/template-kit 0.9.0-dev-20260719205406 → 0.9.0

package/guide/recipes/image-slot-crop.md

@@ -2,7 +2,7 @@
 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, pick-a-scenario.md]
-updated: 2026-07-16
+updated: 2026-07-19
 ---
 # Image slot with a locked crop
 
@@ -51,20 +51,20 @@ interior_image: {
 ```
 
 ```ts
-// fixtures.ts — a photo + a matching mkResponsive() height
-import { mkResponsive, scenarios } from "@homepages/template-kit/fixtures";
+// fixtures.ts — the photo's asset id, exactly as a saved page states it
+import { scenarios } from "@homepages/template-kit/fixtures";
 
 const interiorImage = scenarios.luxuryMultiUnit.photos[3]!;
 // ...
 interior_image: {
   photo_id: interiorImage.id,
-  url: interiorImage.url,
   alt: interiorImage.alt,
-  // Height set to a 4:3 ratio to match the slot's locked crop.
-  responsive: mkResponsive(interiorImage.url, 1600, 1200),
 },
 ```
 
+The `url` and the responsive ladder the Renderer reads are attached when the fixture
+loads — see [Media is stated by id](../schema-system.md#media-is-stated-by-id-never-by-url).
+
 An image slot supports two independent geometry configs — use one, not both, per
 slot:
 

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/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

@@ -43,19 +43,21 @@ npm run check
 CHANGELOG in the package (`node_modules/@homepages/template-kit/CHANGELOG.md`) for
 what changed and why.
 
-## The lint preset upgrades separately
+## The CLI and the lint preset upgrade 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:
+`@homepages/template-cli` (which provides the `template-kit` command) and
+`@homepages/eslint-plugin-template` (the lint preset) are each their own package on
+their own version line, so the kit's number tells you nothing about them and `npm
+update @homepages/template-kit` never moves them. Update each on its own:
 
 ```bash
+npm update @homepages/template-cli
 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.
+Both declare the kit as a **peer dependency**, so each one's range says which kit
+line it supports. If `npm install` reports a peer conflict after a kit minor, the
+package to bump is the one reporting it — not the kit to hold back.
 
 ## How long you have
 
@@ -74,4 +76,6 @@ 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`.
+The same two commands work for `@homepages/template-cli` and
+`@homepages/eslint-plugin-template`. `template-kit --version` prints the pair the
+command is actually running as `<cli> (kit <kit>)`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.9.0-dev-20260719205406",
-  "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
+  "version": "0.9.0",
+  "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the design-system CSS layer.",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -22,9 +22,6 @@
     "tsconfig.base.json",
     "CHANGELOG.md"
   ],
-  "bin": {
-    "template-kit": "dist/cli.js"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -50,10 +47,6 @@
       "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",
     "./tsconfig": "./tsconfig.base.json",
@@ -64,10 +57,9 @@
   ],
   "scripts": {
     "prepack": "npm run build",
-    "build": "tsdown && node scripts/build-dev-client.mjs && node scripts/build-cli-assets.mjs",
+    "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
-    "pretest": "node test/link-fixture-workspace.mjs",
     "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",
@@ -81,15 +73,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@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",
@@ -100,8 +89,7 @@
     "tsdown": "0.22.7",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "typescript-eslint": "^8.60.1",
-    "vite": "^6.0.5"
+    "typescript-eslint": "^8.60.1"
   },
   "dependencies": {
     "magic-string": "^0.30.21",

package/dist/canvas-core/chrome-css.d.ts

@@ -1,24 +0,0 @@
-import { MarkerAttrs } from "./types.js";
-//#region src/canvas-core/chrome-css.d.ts
-/**
- * Custom properties the chrome CSS reads but deliberately does not declare —
- * the host must set them on the iframe document's root element. This is the
- * host's obligation, not a suggestion: an adapter that skips one leaves the
- * declared inline fallback in force, which renders plausibly and silently
- * wrong rather than failing.
- *
- * - `--we-panel-w`: the floating panel's measured width, mirrored onto the
- *   iframe root so the page card's right padding clears it. Unset, the card
- *   lays out against the 436px base-width fallback and drifts out of alignment
- *   whenever the real panel is any other width.
- * - `--we-content`: the host's interior scaling unit, mirrored in so hidden-tab
- *   chrome scales with the rest of the UI. Unset, it pins to the 1px fallback
- *   and the tabs stay laptop-sized while every surrounding surface scales.
- *
- * Anything added here must actually be read by the kernel; the token test
- * fails on a stale entry.
- */
-declare const HOST_INJECTED_PROPERTIES: readonly ["--we-panel-w", "--we-content"];
-declare function buildChromeCss(markers: MarkerAttrs): string;
-//#endregion
-export { HOST_INJECTED_PROPERTIES, buildChromeCss };