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

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @homepages/template-kit
 
-## 0.9.0-dev-20260719205406
+## 0.9.0-dev-20260719224319
 
 ### Minor Changes
 
@@ -24,6 +24,37 @@
   `resolveImportedFile`, `resetClientFileCache`) that the plugin's rules consume
   over the peer edge.
 
+- b7bfc96: Fixtures state media asset ids instead of URLs, and the kit resolves them.
+
+  A fixture now states what a saved page actually holds — `{ photo_id, alt }` — and
+  the kit resolves that id to a URL, an `alt`, and a responsive ladder when it loads
+  the fixture. Previously fixtures stated the post-resolution URL plus a synthesized
+  ladder, which exercised a code path real content never takes and left every preview
+  image broken.
+
+  Breaking changes to `@homepages/template-kit/fixtures`:
+
+  - `mkResponsive` is removed. Nothing needs to call it: the ladder is attached during
+    fixture load.
+  - `PhotoFixture.url` is removed; `PhotoFixture.id` now holds a media asset id.
+  - `ContactFixture.fields` replaces `headshot_url`, `logo_light`, and `logo_dark`
+    with `headshot_id`, `logo_light_id`, and `logo_dark_id`.
+  - `MediaFixture.video_url` becomes `video_id`. `tour_3d_url` is unchanged — a 3D
+    tour is a third-party embed, not a media asset.
+  - `FloorplanAssignment.url` and `.alt` are now optional: a fixture states the plan
+    ref, and url/alt/responsive appear only after resolution.
+
+  To migrate a fixture, drop `url` and `responsive` and keep the id:
+
+  ```diff
+    hero_image: {
+      photo_id: photo.id,
+  -   url: photo.url,
+      alt: photo.alt,
+  -   responsive: mkResponsive(photo.url, 2048, 1259),
+    },
+  ```
+
 ### Patch Changes
 
 - 10f53a7: `template-kit dev`'s canvas hover/select ring no longer overflows the page's

package/dist/cli/check/stages/render.js

@@ -1,5 +1,6 @@
 import { FixtureModuleShape, buildInvariantFixtures } from "../../../schema/fixture-schema.js";
 import { loadSection } from "../loader.js";
+import { resolveFixtureSetMedia } from "../../../media/resolve-fixture-media.js";
 import { flattenLayout } from "../../../schema/rows.js";
 import { renderSectionHtml } from "../../../ssr.js";
 import { checkRenderInvariants } from "../render-invariants.js";
@@ -50,11 +51,11 @@ async function renderStage(workspaceRoot, template) {
 		let fixtures;
 		try {
 			loaded = await loadSection(workspaceRoot, section);
-			fixtures = buildInvariantFixtures({
+			fixtures = resolveFixtureSetMedia(buildInvariantFixtures({
 				schema: loaded.schema,
 				module: FixtureModuleShape.parse(loaded.fixtures),
 				selfAnchor: section.name
-			});
+			}));
 		} catch {
 			continue;
 		}

package/dist/cli/check/stages/validate/nav-contract.js

@@ -1,6 +1,7 @@
 import { FixtureModuleShape, buildFixtureSet } from "../../../../schema/fixture-schema.js";
 import { TemplateManifest } from "../../../../schema/manifest.js";
 import { loadSection } from "../../loader.js";
+import { resolveFixtureSetMedia } from "../../../../media/resolve-fixture-media.js";
 import { renderSectionHtml } from "../../../../ssr.js";
 import { resolveSectionRef } from "../../../../schema/resolve-section-ref.js";
 import { materializeSection } from "./orchestrator.js";
@@ -68,11 +69,11 @@ async function assertNavContract(workspaceRoot, template) {
 	let html = "";
 	for (const section of composed) {
 		const { anchor, schema } = materializedByName.get(section.name);
-		const base = buildFixtureSet({
+		const base = resolveFixtureSetMedia(buildFixtureSet({
 			schema,
 			module: FixtureModuleShape.parse(fixturesByName.get(section.name)),
 			selfAnchor: anchor
-		}).find((f) => f.id === "typical");
+		})).find((f) => f.id === "typical");
 		if (!base) throw new Error(`Template "${template.key}": section "${section.name}" has no "typical" base fixture.`);
 		html += renderSectionHtml(rendererByName.get(section.name), {
 			slots: base.props.slots,

package/dist/cli/dev/server.js

@@ -69,11 +69,12 @@ async function startDevServer(opts) {
 	const sectionAssets = /* @__PURE__ */ new Map();
 	const islandBootstrapUrl = await writeIslandBootstrap(workspace.root);
 	const canvasIslandBootstrapUrl = await writeIslandCanvasBootstrap(workspace.root);
-	vite.watcher.on("change", () => {
+	vite.watcher.on("change", (path) => {
 		vite.moduleGraph.invalidateAll();
 		cssCache.clear();
 		sectionAssets.clear();
-		hmr.broadcast("section:changed", "{}");
+		if (path.endsWith(".css")) hmr.broadcast("tailwind:changed", "{}");
+		else hmr.broadcast("section:changed", "{}");
 	});
 	const ctx = {
 		workspace,

package/dist/cli/new/scaffold/template/sections/hero/fixtures.ts

@@ -1,5 +1,5 @@
 import type { FixtureModule } from "@homepages/template-kit";
-import { luxuryMultiUnit, mkResponsive } from "@homepages/template-kit/fixtures";
+import { luxuryMultiUnit } from "@homepages/template-kit/fixtures";
 
 // Base content the section is designed for. Nullability coverage (each optional
 // slot rendered empty) is derived automatically from schema.ts — no fixture
@@ -12,12 +12,12 @@ const fixtures: FixtureModule = {
   base: {
     slots: {
       headline: luxuryMultiUnit.facts.address.display,
+      // State the asset id, exactly as a saved page does — the preview server
+      // resolves it to a URL and a responsive ladder, the same way the API does
+      // when the page is published. A fixture never states a URL.
       hero_image: {
         photo_id: heroImage.id,
-        url: heroImage.url,
         alt: heroImage.alt,
-        // Height set to a 16:9 ratio to match the slot's locked crop.
-        responsive: mkResponsive(heroImage.url, 2048, 1152),
       },
       blurb: "A 12-unit mansard Victorian in Jamaica Plain, moments from the Emerald Necklace.",
     },

package/dist/fixtures/sample-property.d.ts

@@ -1,15 +1,12 @@
-import { ResponsiveImage } from "../contracts/image-descriptor.js";
 //#region src/fixtures/sample-property.d.ts
 type PhotoFixture = {
   id: string;
-  url: string;
   alt: string;
   tags: {
     room?: string;
     category?: string;
   };
 };
-declare function mkResponsive(url: string, width: number, height: number): ResponsiveImage;
 type PoiFixture = {
   id: string;
   category: "restaurant" | "park" | "transit" | "shopping" | "coffee" | "fitness";
@@ -31,14 +28,14 @@ type ContactFixture = {
     display_name: string;
     title: string;
     bio: string;
-    headshot_url: string;
+    headshot_id: string;
     website_url: string;
     email: string;
     phone: string;
     address: string;
     org_name: string;
-    logo_light: string | null;
-    logo_dark: string | null;
+    logo_light_id: string | null;
+    logo_dark_id: string | null;
     socials: Array<{
       platform: "instagram" | "linkedin" | "x" | "facebook";
       url: string;
@@ -54,4 +51,4 @@ type AmenityItem = {
   items: string[];
 };
 //#endregion
-export { AmenityItem, ContactFixture, PhotoFixture, PoiFixture, mkResponsive };
+export { AmenityItem, ContactFixture, PhotoFixture, PoiFixture };

package/dist/fixtures/sample-property.js

@@ -1,9 +1,7 @@
 //#region src/fixtures/sample-property.ts
-const PHOTO_BASE = "https://example.invalid/photos/queensway";
 const galleryPhotos = [
 	{
-		id: "ph_001",
-		url: `${PHOTO_BASE}/01-lobby.jpg`,
+		id: "dev_upl_queensway_01_lobby",
 		alt: "Lobby with terrazzo flooring and chandeliers.",
 		tags: {
 			room: "lobby",
@@ -11,8 +9,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_002",
-		url: `${PHOTO_BASE}/02-gym-a.jpg`,
+		id: "dev_upl_queensway_02_gym_a",
 		alt: "Gym with cardio equipment and floor-to-ceiling mirrors.",
 		tags: {
 			room: "gym",
@@ -20,8 +17,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_003",
-		url: `${PHOTO_BASE}/03-gym-b.jpg`,
+		id: "dev_upl_queensway_03_gym_b",
 		alt: "Gym free-weights area.",
 		tags: {
 			room: "gym",
@@ -29,8 +25,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_004",
-		url: `${PHOTO_BASE}/04-living-a.jpg`,
+		id: "dev_upl_queensway_04_living_a",
 		alt: "Living area with bay windows and original mouldings.",
 		tags: {
 			room: "living",
@@ -38,8 +33,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_005",
-		url: `${PHOTO_BASE}/05-living-b.jpg`,
+		id: "dev_upl_queensway_05_living_b",
 		alt: "Living area facing the fireplace.",
 		tags: {
 			room: "living",
@@ -47,8 +41,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_006",
-		url: `${PHOTO_BASE}/06-kitchen-a.jpg`,
+		id: "dev_upl_queensway_06_kitchen_a",
 		alt: "Kitchen with quartz waterfall island.",
 		tags: {
 			room: "kitchen",
@@ -56,8 +49,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_007",
-		url: `${PHOTO_BASE}/07-kitchen-b.jpg`,
+		id: "dev_upl_queensway_07_kitchen_b",
 		alt: "Kitchen breakfast nook by the window.",
 		tags: {
 			room: "kitchen",
@@ -65,8 +57,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_008",
-		url: `${PHOTO_BASE}/08-dining.jpg`,
+		id: "dev_upl_queensway_08_dining",
 		alt: "Dining area set for six.",
 		tags: {
 			room: "dining",
@@ -74,8 +65,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_009",
-		url: `${PHOTO_BASE}/09-living-c.jpg`,
+		id: "dev_upl_queensway_09_living_c",
 		alt: "Living area with statement art wall.",
 		tags: {
 			room: "living",
@@ -83,8 +73,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_010",
-		url: `${PHOTO_BASE}/10-living-d.jpg`,
+		id: "dev_upl_queensway_10_living_d",
 		alt: "Living area opening onto private terrace.",
 		tags: {
 			room: "living",
@@ -92,8 +81,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_011",
-		url: `${PHOTO_BASE}/11-living-e.jpg`,
+		id: "dev_upl_queensway_11_living_e",
 		alt: "Sunken living area with built-in shelving.",
 		tags: {
 			room: "living",
@@ -101,8 +89,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_012",
-		url: `${PHOTO_BASE}/12-living-f.jpg`,
+		id: "dev_upl_queensway_12_living_f",
 		alt: "Living area corner with reading chair.",
 		tags: {
 			room: "living",
@@ -110,8 +97,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_013",
-		url: `${PHOTO_BASE}/13-master-bedroom.jpg`,
+		id: "dev_upl_queensway_13_master_bedroom",
 		alt: "Primary bedroom with king bed and skylight.",
 		tags: {
 			room: "bedroom",
@@ -119,8 +105,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_014",
-		url: `${PHOTO_BASE}/14-master-bath-a.jpg`,
+		id: "dev_upl_queensway_14_master_bath_a",
 		alt: "Spa-style primary bath with freestanding tub.",
 		tags: {
 			room: "bath",
@@ -128,8 +113,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_015",
-		url: `${PHOTO_BASE}/15-master-bath-b.jpg`,
+		id: "dev_upl_queensway_15_master_bath_b",
 		alt: "Primary bath double vanity and shower.",
 		tags: {
 			room: "bath",
@@ -137,8 +121,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_016",
-		url: `${PHOTO_BASE}/16-common-bath.jpg`,
+		id: "dev_upl_queensway_16_common_bath",
 		alt: "Common bath with marble subway tile.",
 		tags: {
 			room: "bath",
@@ -146,8 +129,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_017",
-		url: `${PHOTO_BASE}/17-entrance.jpg`,
+		id: "dev_upl_queensway_17_entrance",
 		alt: "Entrance foyer with original mosaic floor.",
 		tags: {
 			room: "entry",
@@ -155,8 +137,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_018",
-		url: `${PHOTO_BASE}/18-patio.jpg`,
+		id: "dev_upl_queensway_18_patio",
 		alt: "Patio with built-in seating and planters.",
 		tags: {
 			room: "patio",
@@ -164,8 +145,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_019",
-		url: `${PHOTO_BASE}/19-outdoor-deck.jpg`,
+		id: "dev_upl_queensway_19_outdoor_deck",
 		alt: "Outdoor deck with sunset view.",
 		tags: {
 			room: "deck",
@@ -173,8 +153,7 @@ const galleryPhotos = [
 		}
 	},
 	{
-		id: "ph_020",
-		url: `${PHOTO_BASE}/20-exterior-hero.jpg`,
+		id: "dev_upl_queensway_20_exterior_hero",
 		alt: "Mansard victorian facade at golden hour.",
 		tags: {
 			room: "exterior-front",
@@ -183,56 +162,21 @@ const galleryPhotos = [
 	}
 ];
 const allPhotos = galleryPhotos;
-const RUNG_WIDTHS = [
-	320,
-	640,
-	960,
-	1200,
-	1600,
-	2048
-];
-function mkResponsive(url, width, height) {
-	const widths = RUNG_WIDTHS.filter((w) => w <= width);
-	if (widths.length === 0) widths.push(width);
-	const ladder = (ext) => widths.map((w) => `${url}.${w}.${ext} ${w}w`).join(", ");
-	return {
-		sources: [
-			{
-				type: "image/avif",
-				srcset: ladder("avif")
-			},
-			{
-				type: "image/webp",
-				srcset: ladder("webp")
-			},
-			{
-				type: "image/jpeg",
-				srcset: ladder("jpg")
-			}
-		],
-		width,
-		height
-	};
-}
-const FP_BASE = "https://example.invalid/floorplans/queensway";
-function fp(id, url, alt, floorLabel, position) {
+function fp(id, floorLabel, position) {
 	return {
 		id,
-		url,
-		alt,
 		floor_label: floorLabel,
-		position,
-		responsive: mkResponsive(url, 1024, 1024)
+		position
 	};
 }
-const FLOORPLAN_3BR = (suffix) => [fp(`fp_3br_${suffix}_a`, `${FP_BASE}/3br-${suffix}-l1.png`, "3BR layout — main floor.", "Main Floor", 0), fp(`fp_3br_${suffix}_b`, `${FP_BASE}/3br-${suffix}-l2.png`, "3BR layout — upper floor.", "Upper Floor", 1)];
-const FLOORPLAN_2BR = (suffix) => [fp(`fp_2br_${suffix}_a`, `${FP_BASE}/2br-${suffix}-l1.png`, "2BR layout.", null, 0)];
+const FLOORPLAN_3BR = (suffix) => [fp(`dev_efp_queensway_3br_${suffix}_l1`, "Main Floor", 0), fp(`dev_efp_queensway_3br_${suffix}_l2`, "Upper Floor", 1)];
+const FLOORPLAN_2BR = (suffix) => [fp(`dev_efp_queensway_2br_${suffix}_l1`, null, 0)];
 const FLOORPLAN_4BR = (suffix) => [
-	fp(`fp_4br_${suffix}_a`, `${FP_BASE}/4br-${suffix}-l1.png`, "4BR layout — main floor.", "Main Floor", 0),
-	fp(`fp_4br_${suffix}_b`, `${FP_BASE}/4br-${suffix}-l2.png`, "4BR layout — upper floor.", "Upper Floor", 1),
-	fp(`fp_4br_${suffix}_c`, `${FP_BASE}/4br-${suffix}-l3.png`, "4BR layout — penthouse.", "Penthouse", 2)
+	fp(`dev_efp_queensway_4br_${suffix}_l1`, "Main Floor", 0),
+	fp(`dev_efp_queensway_4br_${suffix}_l2`, "Upper Floor", 1),
+	fp(`dev_efp_queensway_4br_${suffix}_l3`, "Penthouse", 2)
 ];
-const FLOORPLAN_STUDIO = (suffix) => [fp(`fp_studio_${suffix}_a`, `${FP_BASE}/studio-${suffix}-l1.png`, "Studio layout.", null, 0)];
+const FLOORPLAN_STUDIO = (suffix) => [fp(`dev_efp_queensway_studio_${suffix}_l1`, null, 0)];
 function unit(position, unitLabel, beds, baths, sqft, price, notes, description, features, floorPlans) {
 	return {
 		unit_id: `unit_${String(position + 1).padStart(2, "0")}`,
@@ -645,14 +589,14 @@ const sampleContacts = [
 			display_name: "James Donovan",
 			title: "Listing Agent",
 			bio: "James Donovan is a 15-year veteran of the Boston real estate market, specializing in historic multi-family conversions in Jamaica Plain and the South End. He has closed over $400M in residential transactions and is known for white-glove attention to multi-unit listings.",
-			headshot_url: "https://example.invalid/contacts/james-donovan.jpg",
+			headshot_id: "dev_lib_james_donovan",
 			website_url: "https://okane-marketing.example.invalid",
 			email: "info@homepages.io",
 			phone: "(617) 555-1068",
 			address: "677 Centre St, Suite 200, Jamaica Plain, MA 02130",
 			org_name: "Okane Marketing",
-			logo_light: "https://example.invalid/brand/okane-logo-light.svg",
-			logo_dark: "https://example.invalid/brand/okane-logo-dark.svg",
+			logo_light_id: "dev_lib_okane_logo_light",
+			logo_dark_id: "dev_lib_okane_logo_dark",
 			socials: [
 				{
 					platform: "instagram",
@@ -682,14 +626,14 @@ const sampleContacts = [
 			display_name: "Elena Marsh",
 			title: "Buyer's Agent",
 			bio: "Elena Marsh has guided over 120 buyer clients through the Boston multi-family market since joining the team in 2018, with a focus on Jamaica Plain, Roslindale, and West Roxbury first-time and investor purchases. She is a certified condo-conversion specialist and negotiates every offer personally.",
-			headshot_url: "https://example.invalid/contacts/elena-marsh.jpg",
+			headshot_id: "dev_lib_elena_marsh",
 			website_url: "https://okane-marketing.example.invalid",
 			email: "elena@homepages.io",
 			phone: "(617) 555-2214",
 			address: "677 Centre St, Suite 200, Jamaica Plain, MA 02130",
 			org_name: "Okane Marketing",
-			logo_light: "https://example.invalid/brand/okane-logo-light.svg",
-			logo_dark: "https://example.invalid/brand/okane-logo-dark.svg",
+			logo_light_id: "dev_lib_okane_logo_light",
+			logo_dark_id: "dev_lib_okane_logo_dark",
 			socials: [{
 				platform: "instagram",
 				url: "https://instagram.com/elenamarsh.realty/"
@@ -708,14 +652,14 @@ const sampleContacts = [
 			display_name: "Marcus Webb",
 			title: "Director of Sales",
 			bio: "Marcus Webb leads the team's dispositions practice, working with investors and owner-occupants on multi-unit acquisitions and conversions across greater Boston. A former general contractor, he brings a builder's eye to every walkthrough and has overseen more than 60 multi-family closings.",
-			headshot_url: "https://example.invalid/contacts/marcus-webb.jpg",
+			headshot_id: "dev_lib_marcus_webb",
 			website_url: "https://okane-marketing.example.invalid",
 			email: "marcus@homepages.io",
 			phone: "(617) 555-3357",
 			address: "677 Centre St, Suite 200, Jamaica Plain, MA 02130",
 			org_name: "Okane Marketing",
-			logo_light: "https://example.invalid/brand/okane-logo-light.svg",
-			logo_dark: "https://example.invalid/brand/okane-logo-dark.svg",
+			logo_light_id: "dev_lib_okane_logo_light",
+			logo_dark_id: "dev_lib_okane_logo_dark",
 			socials: [{
 				platform: "linkedin",
 				url: "https://linkedin.com/in/marcus-webb-realty/"
@@ -824,10 +768,10 @@ const sampleProperty = {
 		phone: c.fields.phone,
 		address: c.fields.address,
 		website_url: c.fields.website_url,
-		avatar_upload_id: `upload_headshot_${c.library_item_id}`,
+		avatar_upload_id: c.fields.headshot_id,
 		org_name: c.fields.org_name,
-		logo_light_upload_id: c.fields.logo_light ? `upload_logo_light_${c.library_item_id}` : null,
-		logo_dark_upload_id: c.fields.logo_dark ? `upload_logo_dark_${c.library_item_id}` : null,
+		logo_light_upload_id: c.fields.logo_light_id,
+		logo_dark_upload_id: c.fields.logo_dark_id,
 		instagram_url: c.fields.socials.find((s) => s.platform === "instagram")?.url ?? null,
 		linkedin_url: c.fields.socials.find((s) => s.platform === "linkedin")?.url ?? null,
 		x_url: c.fields.socials.find((s) => s.platform === "x")?.url ?? null,
@@ -836,4 +780,4 @@ const sampleProperty = {
 };
 
 //#endregion
-export { allPhotos, mkResponsive, sampleAmenities, sampleContacts, samplePois, sampleProperty };
+export { allPhotos, sampleAmenities, sampleContacts, samplePois, sampleProperty };

package/dist/fixtures/scenario.d.ts

@@ -3,7 +3,7 @@ import { AmenityItem, ContactFixture, PhotoFixture, PoiFixture } from "./sample-
 //#region src/fixtures/scenario.d.ts
 type ScenarioKey = "luxuryMultiUnit" | "sparseSingleFamily" | "forRentCondo";
 type MediaFixture = {
-  video_url: string | null;
+  video_id: string | null;
   tour_3d_url: string | null;
 };
 type Scenario = {