@homepages/template-kit 0.5.1 → 0.6.0-dev-20260717012648

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @homepages/template-kit
 
+## 0.6.0-dev-20260717012648
+
+### Minor Changes
+
+- 30458a9: Fixture facts now carry the canonical address shape.
+
+  `PropertyFacts["address"]` is an object (`display`, `street`, `street_no_type`, `city`,
+  `state`, `postal`, optional `unit`) instead of a string, and `address_lines` is removed.
+  Fill-specs seed from address sub-parts such as `${facts.address.street_no_type}` and
+  `${facts.address.city}`, which no scenario previously exposed — so fixtures had to
+  hand-derive them, and a fixture could not state what a correct fill-spec would produce.
+
+  Migration: a slot bound straight to `facts.address` must become `facts.address.display` —
+  otherwise the slot receives an object and React throws `Objects are not valid as a React
+child`. Read any other sub-part off `facts.address` directly. For address LINES, use
+  `propertyMetrics(s).addressLine1` / `.addressLine2` — they derive from the sub-parts the
+  way the publishing pipeline does, so they need no change at the call site.
+
+  Two values move, both in the `for-rent-condo` scenario, which carries `unit: "Unit 4"`:
+  `facts.address.display` is `"845 Pearl Street, Unit 4, Denver, CO 80203"` (the string it
+  replaces read `"845 Pearl Street, Denver, CO 80203"`), and the derivation folds the unit
+  into line 1, so `propertyMetrics(forRentCondo).addressLine1` is `"845 Pearl Street, Unit
+4"` (was `"845 Pearl Street"`). Snapshots over that scenario will show both diffs.
+  `addressLine2` is unchanged, and in `luxury-multi-unit` and `sparse-single-family`
+  `display` holds exactly the text the string did.
+
+  Also: the fixture-vs-canonical facts check now treats `videos` as an iterable array
+  field, not a scalar — matching how the rest of the fill pipeline already reads it. If
+  you write a fill-spec against `videos`, expect array semantics.
+
+### Patch Changes
+
+- b0688c5: `check` now reports when a local kit overlay is active, naming the overlaid version and the version your workspace actually pins. Being overlaid while you develop is correct, so the report never affects the result — but a passing run under an overlay does not reflect your declared kit version, and that is worth seeing before you merge.
+
+## 0.5.2
+
 ## 0.5.1
 
 ## 0.5.0

package/dist/cli/check/diagnostics.js

@@ -9,6 +9,11 @@ function formatOne(d) {
 }
 function formatHuman(report) {
 	const parts = [];
+	if (report.linkedKit !== void 0) {
+		const { kitVersion, linkedFrom, pin } = report.linkedKit;
+		parts.push(`⚠ linked kit ${kitVersion} from ${linkedFrom} — your pin is ${pin}.\n`);
+		parts.push("  This result does not reflect your pin. Run `template-kit unlink` before merging.\n");
+	}
 	for (const [key, t] of Object.entries(report.templates)) {
 		if (t.ok) {
 			parts.push(`✓ ${key}\n`);

package/dist/cli/check/index.js

@@ -1,4 +1,5 @@
 import { KIT_VERSION } from "../../index.js";
+import { readLinkMarker } from "../link/overlay.js";
 import { formatHuman, toJson } from "./diagnostics.js";
 import { loadEsbuild } from "./resolve-tool.js";
 import { resetLoadCache } from "./loader.js";
@@ -9,7 +10,7 @@ import { sizeStage } from "./stages/size.js";
 import { treeStage } from "./stages/tree.js";
 import { typecheckStage } from "./stages/typecheck.js";
 import { validateStage } from "./stages/validate/index.js";
-import { findWorkspaceRoot, selectTemplates, templateFromCwd } from "./workspace.js";
+import { declaredKitPin, findWorkspaceRoot, selectTemplates, templateFromCwd } from "./workspace.js";
 import { parseArgs } from "node:util";
 
 //#region src/cli/check/index.ts
@@ -71,9 +72,15 @@ async function runCheck(argv, cwd) {
 		ok: workspaceDiagnostics.length === 0,
 		diagnostics: workspaceDiagnostics
 	};
+	const marker = await readLinkMarker(root);
 	const report = {
 		ok: workspace.ok && Object.values(templates).every((t) => t.ok),
 		kitVersion: KIT_VERSION,
+		...marker === void 0 ? {} : { linkedKit: {
+			linkedFrom: marker.linkedFrom,
+			kitVersion: marker.kitVersion,
+			pin: await declaredKitPin(root)
+		} },
 		templates,
 		workspace
 	};

package/dist/cli/check/loader.js

@@ -1,8 +1,8 @@
 import { loadEsbuild } from "./resolve-tool.js";
 import { ASSET_LOADERS, ASSET_NAMES, ASSET_PUBLIC_PATH } from "./css.js";
 import { join, relative } from "node:path";
-import { createHash } from "node:crypto";
 import { mkdir, rm, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
 
 //#region src/cli/check/loader.ts

package/dist/cli/check/stages/validate/facts.js

@@ -2,6 +2,7 @@
 const FACTS_ARRAY_FIELDS = /* @__PURE__ */ new Set([
 	"units",
 	"photos",
+	"videos",
 	"floor_plans",
 	"pois",
 	"contacts"

package/dist/cli/check/workspace.js

@@ -1,5 +1,5 @@
 import { dirname, join, resolve } from "node:path";
-import { readdir, stat } from "node:fs/promises";
+import { readFile, readdir, stat } from "node:fs/promises";
 
 //#region src/cli/check/workspace.ts
 const isDir = async (p) => {
@@ -26,6 +26,19 @@ async function findWorkspaceRoot(from) {
 		dir = parent;
 	}
 }
+/**
+* The kit version the workspace DECLARES in package.json — deliberately not what is
+* installed. The link overlay never touches package.json, so declared-vs-installed is
+* precisely the gap the check warning exists to surface.
+*/
+async function declaredKitPin(root) {
+	try {
+		const raw = await readFile(join(root, "package.json"), "utf8");
+		return JSON.parse(raw).dependencies?.["@homepages/template-kit"] ?? "unknown";
+	} catch {
+		return "unknown";
+	}
+}
 async function discoverTemplates(root) {
 	const templatesDir = join(root, "templates");
 	const entries = await readdir(templatesDir, { withFileTypes: true });
@@ -83,4 +96,4 @@ function templateFromCwd(root, cwd) {
 }
 
 //#endregion
-export { discoverTemplates, findWorkspaceRoot, selectTemplates, templateFromCwd };
+export { declaredKitPin, discoverTemplates, findWorkspaceRoot, selectTemplates, templateFromCwd };

package/dist/cli/link/index.js

@@ -1,5 +1,5 @@
-import { findWorkspaceRoot } from "../check/workspace.js";
 import { KIT_PKG_SUBPATH, findKitRoot, overlayKit, readLinkMarker } from "./overlay.js";
+import { findWorkspaceRoot } from "../check/workspace.js";
 import { join } from "node:path";
 import { parseArgs, promisify } from "node:util";
 import { readFile } from "node:fs/promises";

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

@@ -11,7 +11,7 @@ const heroImage = luxuryMultiUnit.photos[19]!; // exterior facade shot
 const fixtures: FixtureModule = {
   base: {
     slots: {
-      headline: luxuryMultiUnit.facts.address,
+      headline: luxuryMultiUnit.facts.address.display,
       hero_image: {
         photo_id: heroImage.id,
         url: heroImage.url,

package/dist/cli/pack/collect.js

@@ -1,6 +1,6 @@
 import { join, relative, sep } from "node:path";
-import { createHash } from "node:crypto";
 import { readFile, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
 
 //#region src/cli/pack/collect.ts
 const toPosix = (p) => p.split(sep).join("/");

package/dist/cli/theme/load-theme.js

@@ -1,7 +1,7 @@
 import { loadEsbuild } from "../check/resolve-tool.js";
 import { join } from "node:path";
-import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
 
 //#region src/cli/theme/load-theme.ts

package/dist/fixtures/helpers.js

@@ -22,10 +22,23 @@ function poisByCategory(s) {
 	for (const poi of s.pois) out[poi.category].push(poi);
 	return out;
 }
+function addressLineParts(a) {
+	const street = a.street.trim();
+	const unit = (a.unit ?? "").trim();
+	const city = a.city.trim();
+	const state = a.state.trim();
+	const postal = a.postal.trim();
+	const streetLine = unit && street ? `${street}, ${unit}` : street;
+	const cityStateZip = [city, [state, postal].filter(Boolean).join(" ")].filter(Boolean).join(", ");
+	return {
+		line1: streetLine.length > 0 ? streetLine : null,
+		line2: cityStateZip.length > 0 ? cityStateZip : null
+	};
+}
 function propertyMetrics(s) {
 	const units = s.facts.units;
-	const lines = s.facts.address_lines ?? [s.facts.address, ""];
 	const primary = [...units].sort((a, b) => a.position - b.position)[0] ?? null;
+	const lines = addressLineParts(s.facts.address);
 	const fmt = (name) => {
 		const v = TRANSFORMS[name].impl({ units });
 		return v == null ? null : String(v);
@@ -41,8 +54,8 @@ function propertyMetrics(s) {
 		bathsMax: fmt("units.bathsMax"),
 		sqftMax: fmt("units.sqftMax"),
 		priceStart: fmt("units.priceStart"),
-		addressLine1: lines[0] ?? "",
-		addressLine2: lines[1] ?? ""
+		addressLine1: lines.line1 ?? "",
+		addressLine2: lines.line2 ?? ""
 	};
 }
 

package/dist/fixtures/sample-property.js

@@ -792,8 +792,14 @@ const sampleAmenities = [
 	}
 ];
 const sampleProperty = {
-	address: "101 Queensway, Jamaica Plain, MA 02130",
-	address_lines: ["101 Queensway", "Jamaica Plain, MA 02130"],
+	address: {
+		display: "101 Queensway, Jamaica Plain, MA 02130",
+		street: "101 Queensway",
+		street_no_type: "101 Queensway",
+		city: "Jamaica Plain",
+		state: "MA",
+		postal: "02130"
+	},
 	coordinates: {
 		lat: 42.31,
 		lng: -71.11

package/dist/fixtures/scenarios/for-rent-condo.js

@@ -314,8 +314,15 @@ const contacts = [{
 	}
 }];
 const facts = {
-	address: "845 Pearl Street, Denver, CO 80203",
-	address_lines: ["845 Pearl Street", "Denver, CO 80203"],
+	address: {
+		display: "845 Pearl Street, Unit 4, Denver, CO 80203",
+		street: "845 Pearl Street",
+		street_no_type: "845 Pearl",
+		unit: "Unit 4",
+		city: "Denver",
+		state: "CO",
+		postal: "80203"
+	},
 	coordinates: {
 		lat: 39.7273,
 		lng: -104.9808

package/dist/fixtures/scenarios/sparse-single-family.js

@@ -183,8 +183,14 @@ const contacts = [{
 	}
 }];
 const facts = {
-	address: "212 Tuscan Road, Maplewood, NJ 07040",
-	address_lines: ["212 Tuscan Road", "Maplewood, NJ 07040"],
+	address: {
+		display: "212 Tuscan Road, Maplewood, NJ 07040",
+		street: "212 Tuscan Road",
+		street_no_type: "212 Tuscan",
+		city: "Maplewood",
+		state: "NJ",
+		postal: "07040"
+	},
 	coordinates: {
 		lat: 40.7315,
 		lng: -74.2739

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.5.1";
+var version = "0.6.0-dev-20260717012648";
 
 //#endregion
 export { version };

package/dist/schema/property-facts.d.ts

@@ -26,9 +26,18 @@ type UnitRow = {
   position: number;
   floor_plans: FloorplanAssignment[];
 };
+type Address = {
+  display: string;
+  street: string;
+  street_no_type: string;
+  city: string;
+  state: string;
+  postal: string;
+  /** Address Line 2 (apt/suite/unit, e.g. "Unit 4B"); absent when none. */
+  unit?: string;
+};
 type PropertyFacts = {
-  address: string;
-  address_lines?: string[];
+  address: Address;
   lat?: number | null;
   lon?: number | null;
   coordinates?: Coordinates | null;
@@ -41,4 +50,4 @@ type PropertyFacts = {
   contacts?: Array<Record<string, unknown>>;
 };
 //#endregion
-export { Coordinates, FloorplanAssignment, PropertyFacts, UnitRow };
+export { Address, Coordinates, FloorplanAssignment, PropertyFacts, UnitRow };

package/dist/schema/runtime-values.d.ts

@@ -1,5 +1,5 @@
 import { ResponsiveImage } from "../contracts/image-descriptor.js";
-import { Coordinates, FloorplanAssignment, PropertyFacts, UnitRow } from "./property-facts.js";
+import { Address, Coordinates, FloorplanAssignment, PropertyFacts, UnitRow } from "./property-facts.js";
 import { VerificationWidth } from "../design-system/breakpoints.js";
 //#region src/schema/runtime-values.d.ts
 type FrameConfig = {

package/guide/recipes/fixture-states.md

@@ -67,7 +67,7 @@ const sparse = scenarios.sparseSingleFamily;
 const fixtures: FixtureModule = {
   base: {
     slots: {
-      headline: luxury.facts.address,
+      headline: luxury.facts.address.display,
       summary: "A 12-unit mansard Victorian moments from the Emerald Necklace.",
     },
     options: { align: "center" },
@@ -75,7 +75,7 @@ const fixtures: FixtureModule = {
   states: {
     sparse: {
       slots: {
-        headline: sparse.facts.address,
+        headline: sparse.facts.address.display,
         summary:
           "A classic center-hall colonial with an updated kitchen and original " +
           "hardwood floors throughout.",

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

@@ -46,7 +46,7 @@ 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` |
+| direct (a fact) | read it off the scenario — `s.facts.address.display`, `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 |
 

package/guide/schema-system.md

@@ -229,7 +229,7 @@ export default fixtures;
 ### Build on a scenario, not on lorem ipsum
 
 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
+property-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:
 
@@ -260,7 +260,7 @@ rule says where to find it, keyed to the same `source` / `produced_by` a slot de
 
 | 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` |
+| direct (a fact) | read it off the scenario — `s.facts.address.display`, `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 |
 
@@ -292,6 +292,34 @@ a sibling "brand" object — read them off `primaryContact(s).fields` or `s.cont
 See [Pick a scenario](recipes/pick-a-scenario.md) for the full picker and helper
 cheat-sheet.
 
+### What a scenario is, and is not
+
+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 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
+  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
+  fill-spec that reads or iterates `facts.contacts` has a real counterpart in every
+  scenario.
+- `facts.address` is the exception: it mirrors the real address contract field for field
+  (`display`, `street`, `street_no_type`, `city`, `state`, `postal`, and an optional
+  `unit`). A fill-spec that seeds from `${facts.address.city}` has a real counterpart in
+  every scenario. Note `street_no_type` drops the street-type suffix — "845 Pearl" for
+  "845 Pearl Street" — so never seed one from the other.
+
+Address lines are **derived, never stored**: use `propertyMetrics(s).addressLine1` /
+`addressLine2`, which compose the sub-parts exactly as the publishing pipeline does. Don't
+hand-assemble or split them — a fixture must state the value the real pipeline bakes.
+
 ## Variants — rendering differently based on the facts
 
 A variant axis picks a case from the property's facts, before any content is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.5.1",
+  "version": "0.6.0-dev-20260717012648",
   "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
   "license": "UNLICENSED",
   "type": "module",