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

package/dist/media/pack.d.ts

@@ -0,0 +1,49 @@
+//#region src/media/pack.d.ts
+/** The four library kinds the editor's media picker lists. */
+type MediaKind = "photo" | "plan" | "library" | "video";
+type MediaAsset = {
+  id: string;
+  kind: MediaKind;
+  name: string;
+  caption: string;
+  tags: Record<string, string>;
+  /** Pack-relative path to the source bytes. */
+  file: string;
+  /** True intrinsic dimensions of `file`. Absent for vector assets. */
+  width?: number;
+  height?: number;
+  /** `video` only. */
+  poster?: string;
+  duration_ms?: number;
+};
+/**
+ * URL prefix every resolved media URL carries. Root-relative so a section page at
+ * any depth resolves it identically, and so the dev server can mount the pack under
+ * one known path. Kept in sync with the dev server's static mount.
+ */
+declare const DEV_MEDIA_URL_PREFIX = "/__dev-media/";
+/** The pack entry for an asset id, or null when the id names nothing in the pack. */
+declare function getMediaAsset(id: string): MediaAsset | null;
+/**
+ * Every asset the pack ships, in manifest order.
+ *
+ * Exposes the asset list and NOT the whole manifest on purpose. The manifest's
+ * `sets` are generated FROM the scenario ownership a consumer derives out of the
+ * kit fixtures, so a consumer that read `sets` back to compute ownership would be
+ * checking its own output.
+ */
+declare function listMediaAssets(): MediaAsset[];
+/**
+ * Inverse of `mediaUrl` — the pack-relative path a served URL names, or null when
+ * the URL is not a pack URL. Lets a consumer (render-invariants) check a rendered
+ * `src` back against the manifest.
+ */
+declare function packRelativeFromUrl(url: string): string | null;
+/**
+ * Whether a pack-relative path names real bytes in the pack. Pair with
+ * `packRelativeFromUrl` to check a rendered `src`/`srcset` back against the
+ * manifest — asserting a media URL RESOLVES rather than merely being non-empty.
+ */
+declare function mediaPackHasFile(packRelative: string): boolean;
+//#endregion
+export { DEV_MEDIA_URL_PREFIX, MediaAsset, MediaKind, getMediaAsset, listMediaAssets, mediaPackHasFile, packRelativeFromUrl };

package/dist/media/pack.js

@@ -0,0 +1,69 @@
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+
+//#region src/media/pack.ts
+/**
+* URL prefix every resolved media URL carries. Root-relative so a section page at
+* any depth resolves it identically, and so the dev server can mount the pack under
+* one known path. Kept in sync with the dev server's static mount.
+*/
+const DEV_MEDIA_URL_PREFIX = "/__dev-media/";
+const MANIFEST_CANDIDATES = ["../manifest.json", "../../../dev-media/manifest.json"];
+function loadManifest() {
+	for (const candidate of MANIFEST_CANDIDATES) {
+		const path = fileURLToPath(new URL(candidate, import.meta.url));
+		if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
+	}
+	throw new Error("dev media manifest not found — expected it beside the kit build (dist/manifest.json) or in the workspace sibling (packages/dev-media/manifest.json)");
+}
+let cached = null;
+/** The pack index. Parsed once per process. */
+function mediaManifest() {
+	cached ??= loadManifest();
+	return cached;
+}
+let byId = null;
+/** The pack entry for an asset id, or null when the id names nothing in the pack. */
+function getMediaAsset(id) {
+	byId ??= new Map(mediaManifest().assets.map((asset) => [asset.id, asset]));
+	return byId.get(id) ?? null;
+}
+/**
+* Every asset the pack ships, in manifest order.
+*
+* Exposes the asset list and NOT the whole manifest on purpose. The manifest's
+* `sets` are generated FROM the scenario ownership a consumer derives out of the
+* kit fixtures, so a consumer that read `sets` back to compute ownership would be
+* checking its own output.
+*/
+function listMediaAssets() {
+	return mediaManifest().assets;
+}
+/**
+* The served URL for a pack-relative reference (an asset's `file` or `poster`).
+* This is the ONLY place the pack's on-disk layout becomes a URL.
+*/
+function mediaUrl(packRelative) {
+	return `${DEV_MEDIA_URL_PREFIX}${packRelative}`;
+}
+/**
+* Inverse of `mediaUrl` — the pack-relative path a served URL names, or null when
+* the URL is not a pack URL. Lets a consumer (render-invariants) check a rendered
+* `src` back against the manifest.
+*/
+function packRelativeFromUrl(url) {
+	return url.startsWith("/__dev-media/") ? url.slice(13) : null;
+}
+let files = null;
+/**
+* Whether a pack-relative path names real bytes in the pack. Pair with
+* `packRelativeFromUrl` to check a rendered `src`/`srcset` back against the
+* manifest — asserting a media URL RESOLVES rather than merely being non-empty.
+*/
+function mediaPackHasFile(packRelative) {
+	files ??= new Set(mediaManifest().assets.flatMap((asset) => asset.poster ? [asset.file, asset.poster] : [asset.file]));
+	return files.has(packRelative);
+}
+
+//#endregion
+export { DEV_MEDIA_URL_PREFIX, getMediaAsset, listMediaAssets, mediaManifest, mediaPackHasFile, mediaUrl, packRelativeFromUrl };

package/dist/media/resolve-fixture-media.js

@@ -0,0 +1,73 @@
+import { getMediaAsset } from "./pack.js";
+import { resolveFloorplan, resolveImageValue, resolveVideoValue } from "./resolve-media.js";
+
+//#region src/media/resolve-fixture-media.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasStringKey(value, key) {
+	return typeof value[key] === "string";
+}
+function resolveValue(value, key) {
+	if (Array.isArray(value)) {
+		const entries = value;
+		if (key === "floor_plans") return entries.map((entry) => isPlainObject(entry) && typeof entry.id === "string" ? resolveFloorplan(entry) : entry);
+		return entries.map((entry) => resolveValue(entry, null));
+	}
+	if (!isPlainObject(value)) return value;
+	if (hasStringKey(value, "video_id")) return resolveVideoValue(value);
+	if (hasStringKey(value, "photo_id") || hasStringKey(value, "asset_id")) return resolveImageValue(value);
+	return Object.fromEntries(Object.entries(value).map(([childKey, childValue]) => [childKey, resolveValue(childValue, childKey)]));
+}
+/**
+* Resolve every media reference in a fixture's props against the dev media pack,
+* returning a new props object. Props with no media pass through unchanged in
+* value, though the object identity is not preserved.
+*/
+function resolveFixtureMedia(props) {
+	return resolveValue(props, null);
+}
+/**
+* `resolveFixtureMedia` over a built fixture set — the form every node-only caller
+* (the SSR loader, `template-kit check`) actually needs.
+*/
+function resolveFixtureSetMedia(fixtures) {
+	return fixtures.map((fixture) => ({
+		...fixture,
+		props: resolveFixtureMedia(fixture.props)
+	}));
+}
+function collectUnresolved(value, key, out) {
+	if (Array.isArray(value)) {
+		for (const entry of value) if (key === "floor_plans" && isPlainObject(entry) && typeof entry.id === "string") {
+			if (entry.id && !getMediaAsset(entry.id)) out.set(entry.id, "floor_plans[].id");
+		} else collectUnresolved(entry, null, out);
+		return;
+	}
+	if (!isPlainObject(value)) return;
+	for (const field of [
+		"photo_id",
+		"asset_id",
+		"video_id"
+	]) {
+		const id = value[field];
+		if (typeof id === "string" && id && !getMediaAsset(id)) out.set(id, field);
+	}
+	for (const [childKey, childValue] of Object.entries(value)) collectUnresolved(childValue, childKey, out);
+}
+/**
+* Every media asset id a fixture states that the pack does not carry. Run over
+* PRE-resolution props — after resolution the id is gone, replaced by the empty
+* default.
+*/
+function findUnresolvedMedia(props) {
+	const found = /* @__PURE__ */ new Map();
+	collectUnresolved(props, null, found);
+	return [...found].map(([id, field]) => ({
+		field,
+		id
+	}));
+}
+
+//#endregion
+export { findUnresolvedMedia, resolveFixtureMedia, resolveFixtureSetMedia };

package/dist/media/resolve-media.js

@@ -0,0 +1,195 @@
+import { getMediaAsset, mediaUrl } from "./pack.js";
+
+//#region src/media/resolve-media.ts
+const EMPTY_IMAGE = {
+	photo_id: "",
+	url: "",
+	alt: ""
+};
+const EMPTY_VIDEO = {
+	video_id: "",
+	url: "",
+	poster: "",
+	alt: ""
+};
+const RUNG_WIDTHS = [
+	320,
+	640,
+	960,
+	1200,
+	1600,
+	2048
+];
+const MIME_BY_EXTENSION = {
+	avif: "image/avif",
+	jpeg: "image/jpeg",
+	jpg: "image/jpeg",
+	png: "image/png",
+	webp: "image/webp"
+};
+function mimeFor(file) {
+	return MIME_BY_EXTENSION[file.split(".").pop()?.toLowerCase() ?? ""] ?? null;
+}
+/**
+* The responsive descriptor for a pack asset, or null when the asset cannot carry
+* one (a vector, or a raster whose intrinsic dimensions the manifest omits).
+*
+* TWO DELIBERATE DIVERGENCES FROM PRODUCTION, both recorded in the design record:
+*
+*  1. Every rung points at the SAME source file. Production pre-encodes one file per
+*     rung; generating those here would put `sharp` — a platform-specific native
+*     binary — into every agency install and make output vary by encoder version.
+*     The manifest still declares each asset's TRUE dimensions, so layout and
+*     authoring behave exactly as in production; only transferred bytes differ.
+*  2. One source, carrying the file's REAL mime type, where production emits an
+*     avif/webp/jpeg triple. Claiming `image/avif` over PNG bytes would not be a
+*     harmless fiction — the browser would select that source and fail to decode it.
+*/
+function responsiveFor(asset) {
+	const type = mimeFor(asset.file);
+	if (!type || !asset.width || !asset.height) return null;
+	const url = mediaUrl(asset.file);
+	const widths = RUNG_WIDTHS.filter((w) => w <= asset.width);
+	if (widths.length === 0) widths.push(asset.width);
+	return {
+		sources: [{
+			type,
+			srcset: widths.map((w) => `${url} ${w}w`).join(", ")
+		}],
+		width: asset.width,
+		height: asset.height
+	};
+}
+function clamp01(n) {
+	return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+function normalizeRect(v) {
+	const nx = typeof v.nx === "number" ? v.nx : 0;
+	const ny = typeof v.ny === "number" ? v.ny : 0;
+	const nw = typeof v.nw === "number" ? v.nw : 1;
+	const nh = typeof v.nh === "number" ? v.nh : 1;
+	if (![
+		nx,
+		ny,
+		nw,
+		nh
+	].every(Number.isFinite)) return null;
+	const r = {
+		nx: clamp01(nx),
+		ny: clamp01(ny),
+		nw: clamp01(nw),
+		nh: clamp01(nh)
+	};
+	if (r.nx === 0 && r.ny === 0 && r.nw === 1 && r.nh === 1) return null;
+	return r;
+}
+/**
+* Resolve one image-slot value against the pack.
+*
+* `null` passes through as `null`, so an optional image slot stays null and the
+* renderer skips it. Every other miss — an unknown id, an object with neither id
+* nor url — degrades to the empty default rather than throwing: image resolution
+* must degrade soft, and the empty `url` is what makes a dead id VISIBLE to
+* render-invariants instead of silently plausible.
+*/
+function resolveImageValue(value) {
+	if (value === null) return null;
+	if (typeof value !== "object") return { ...EMPTY_IMAGE };
+	const v = value;
+	const rect = v.rect && typeof v.rect === "object" ? normalizeRect(v.rect) : null;
+	const ar = typeof v.ar === "number" ? v.ar : null;
+	const cropKey = typeof v.crop_key === "string" && v.crop_key.length > 0 ? v.crop_key : null;
+	const photoId = typeof v.photo_id === "string" && v.photo_id ? v.photo_id : typeof v.asset_id === "string" && v.asset_id ? v.asset_id : "";
+	let base;
+	let cropKeyForAttach;
+	let source;
+	if (cropKey && photoId) {
+		source = getMediaAsset(cropKey);
+		if (!source) return { ...EMPTY_IMAGE };
+		base = {
+			photo_id: photoId,
+			url: mediaUrl(source.file),
+			alt: source.caption
+		};
+		cropKeyForAttach = cropKey;
+	} else if (photoId) {
+		source = getMediaAsset(photoId);
+		if (!source) return { ...EMPTY_IMAGE };
+		base = {
+			photo_id: photoId,
+			url: mediaUrl(source.file),
+			alt: source.caption
+		};
+		cropKeyForAttach = null;
+	} else if (typeof v.url === "string" && v.url.length > 0) {
+		base = {
+			photo_id: "",
+			url: v.url,
+			alt: typeof v.alt === "string" ? v.alt : ""
+		};
+		cropKeyForAttach = null;
+		source = null;
+	} else return { ...EMPTY_IMAGE };
+	if (rect) base.rect = rect;
+	if (ar) base.ar = ar;
+	if (cropKeyForAttach) base.crop_key = cropKeyForAttach;
+	const responsive = source ? responsiveFor(source) : null;
+	if (responsive) base.responsive = responsive;
+	return base;
+}
+/**
+* Attach the render-time fields to one floorplan ref. A saved plan ref carries only
+* id/upload_id/floor_label/position; url, alt, and the responsive descriptor appear
+* only after resolution. An unknown id yields an empty url — the same visible miss
+* an unknown image id produces.
+*/
+function resolveFloorplan(ref) {
+	const asset = getMediaAsset(ref.id);
+	if (!asset) return {
+		...ref,
+		url: "",
+		alt: ""
+	};
+	const responsive = responsiveFor(asset);
+	return {
+		...ref,
+		url: mediaUrl(asset.file),
+		alt: asset.caption,
+		...responsive ? { responsive } : {}
+	};
+}
+/**
+* Resolve one video-slot value against the pack. There is exactly one progressive
+* rendition per video, so there is no ladder and no mobile variant; the poster is
+* always present because the transcode derives one.
+*/
+function resolveVideoValue(value) {
+	if (value === null) return null;
+	if (typeof value !== "object") return { ...EMPTY_VIDEO };
+	const v = value;
+	const videoId = typeof v.video_id === "string" && v.video_id ? v.video_id : typeof v.asset_id === "string" && v.asset_id ? v.asset_id : "";
+	if (!videoId) {
+		if (typeof v.url === "string" && v.url.length > 0) return {
+			video_id: "",
+			url: v.url,
+			poster: typeof v.poster === "string" ? v.poster : "",
+			alt: typeof v.alt === "string" ? v.alt : ""
+		};
+		return { ...EMPTY_VIDEO };
+	}
+	const asset = getMediaAsset(videoId);
+	if (!asset) return { ...EMPTY_VIDEO };
+	return {
+		video_id: videoId,
+		url: mediaUrl(asset.file),
+		poster: asset.poster ? mediaUrl(asset.poster) : "",
+		alt: asset.caption,
+		...asset.width && asset.height ? {
+			width: asset.width,
+			height: asset.height
+		} : {}
+	};
+}
+
+//#endregion
+export { resolveFloorplan, resolveImageValue, resolveVideoValue };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.8.1-dev-20260718224903";
+var version = "0.9.0-dev-20260719224319";
 
 //#endregion
 export { version };

package/dist/rules.d.ts

@@ -0,0 +1,176 @@
+//#region src/rules/registry.d.ts
+type RuleVenue = "eslint" | "check";
+interface RuleEntry {
+  /** Bare id — "no-hex". Never the qualified "template-kit/no-hex". */
+  id: string;
+  /** Which engine emits it. */
+  venue: RuleVenue;
+  /** One line, for the docs index. */
+  summary: string;
+}
+declare const RULE_IDS: readonly [{
+  readonly id: "no-nondeterminism";
+  readonly venue: "eslint";
+  readonly summary: "No clock or randomness reads in server-rendered code.";
+}, {
+  readonly id: "no-client-runtime-in-server";
+  readonly venue: "eslint";
+  readonly summary: "No effects, state, event handlers, network, or browser globals in server-rendered code.";
+}, {
+  readonly id: "serializable-island-props";
+  readonly venue: "eslint";
+  readonly summary: "Props handed to an island must be JSON-serializable.";
+}, {
+  readonly id: "require-island-editor";
+  readonly venue: "eslint";
+  readonly summary: "Every island must declare whether it is live in the editor canvas.";
+}, {
+  readonly id: "no-client-directive-in-contract";
+  readonly venue: "eslint";
+  readonly summary: "No \"use client\" in a section's four contract files.";
+}, {
+  readonly id: "props-from-schema";
+  readonly venue: "eslint";
+  readonly summary: "A Renderer's Props type must be derived from schema.ts, not hand-written.";
+}, {
+  readonly id: "no-inline-style";
+  readonly venue: "eslint";
+  readonly summary: "No inline style= in server-rendered JSX. Islands are exempt.";
+}, {
+  readonly id: "no-raw-element";
+  readonly venue: "eslint";
+  readonly summary: "No raw `<section>`, `<img>` or `<video>` — use `<Section>`, `<Image>` and `<Video>`.";
+}, {
+  readonly id: "image-bare-needs-reason";
+  readonly venue: "eslint";
+  readonly summary: "`<Image bare>` needs a `// bare:` comment saying why it skips the frame.";
+}, {
+  readonly id: "slot-marker-literal";
+  readonly venue: "eslint";
+  readonly summary: "A slot-marker key must be a string literal, not an expression.";
+}, {
+  readonly id: "no-hex";
+  readonly venue: "eslint";
+  readonly summary: "No hard-coded colours — the one legal colour function is a `color-mix()` over theme-derived arguments. Islands are NOT exempt.";
+}, {
+  readonly id: "no-css-import-from-render-path";
+  readonly venue: "eslint";
+  readonly summary: "No relative/absolute .css import from a section's render path — a package's is the sanctioned channel.";
+}, {
+  readonly id: "bundle-incomplete";
+  readonly venue: "check";
+  readonly summary: "A section folder is missing one of its four required files.";
+}, {
+  readonly id: "bundle-binary-asset";
+  readonly venue: "check";
+  readonly summary: "An unreferenced binary asset sits in a section folder.";
+}, {
+  readonly id: "schema-invalid";
+  readonly venue: "check";
+  readonly summary: "A section's schema.ts or fill-spec.ts fails a contract assertion, or cannot be loaded.";
+}, {
+  readonly id: "fixtures-invalid";
+  readonly venue: "check";
+  readonly summary: "A section's fixtures.ts does not satisfy the fixture-module shape.";
+}, {
+  readonly id: "manifest-invalid";
+  readonly venue: "check";
+  readonly summary: "A template's manifest.json is missing, unparseable, or violates the manifest contract.";
+}, {
+  readonly id: "missing-slot-marker";
+  readonly venue: "check";
+  readonly summary: "An editable slot in schema.ts has no marker in the section's JSX.";
+}, {
+  readonly id: "slot-group-marker";
+  readonly venue: "check";
+  readonly summary: "A group with two or more members has no `<SlotGroup>` wrapper.";
+}, {
+  readonly id: "css-reason";
+  readonly venue: "check";
+  readonly summary: "A hand-written CSS file must open with a `css-reason:` comment.";
+}, {
+  readonly id: "no-bare-css-import";
+  readonly venue: "check";
+  readonly summary: "No @import in hand-written CSS — the browser drops it silently.";
+}, {
+  readonly id: "unlayered-fence";
+  readonly venue: "check";
+  readonly summary: "An `/* unlayered: */` escape hatch must be balanced and give a reason.";
+}, {
+  readonly id: "sidebar-order";
+  readonly venue: "check";
+  readonly summary: "Schema slot order must match the order the page renders them in.";
+}, {
+  readonly id: "typecheck";
+  readonly venue: "check";
+  readonly summary: "The template must compile under TypeScript.";
+}, {
+  readonly id: "parse-error";
+  readonly venue: "check";
+  readonly summary: "A file could not be parsed at all — a syntax error, not a rule violation.";
+}, {
+  readonly id: "determinism-drift";
+  readonly venue: "check";
+  readonly summary: "Rendering the same fixture twice must produce byte-identical HTML.";
+}, {
+  readonly id: "render-invariant";
+  readonly venue: "check";
+  readonly summary: "Rendered output must carry no [object Object], bare null/undefined/NaN leaf, or src-less `<img>`.";
+}, {
+  readonly id: "lockfile-missing";
+  readonly venue: "check";
+  readonly summary: "The workspace has no package-lock.json.";
+}, {
+  readonly id: "lockfile-stale";
+  readonly venue: "check";
+  readonly summary: "The lockfile does not satisfy package.json — an `npm ci` would fail.";
+}, {
+  readonly id: "single-react";
+  readonly venue: "check";
+  readonly summary: "The installed tree carries more than one copy of react or react-dom.";
+}, {
+  readonly id: "audit-severity";
+  readonly venue: "check";
+  readonly summary: "A dependency carries a high or critical security advisory.";
+}, {
+  readonly id: "license-denied";
+  readonly venue: "check";
+  readonly summary: "A production dependency's license is not on the allowlist.";
+}, {
+  readonly id: "size-renderer-bundle";
+  readonly venue: "check";
+  readonly summary: "A section's renderer bundle exceeds its byte budget.";
+}, {
+  readonly id: "size-section-css";
+  readonly venue: "check";
+  readonly summary: "A section's compiled CSS exceeds its byte budget.";
+}, {
+  readonly id: "size-island-bundle";
+  readonly venue: "check";
+  readonly summary: "A section's island (browser) bundle exceeds its byte budget.";
+}, {
+  readonly id: "size-assets";
+  readonly venue: "check";
+  readonly summary: "A section's static assets exceed their byte budget.";
+}, {
+  readonly id: "no-templates";
+  readonly venue: "check";
+  readonly summary: "The workspace has no template to check at all.";
+}];
+type RuleId = (typeof RULE_IDS)[number]["id"];
+/** The namespace every id is printed under, in both venues. */
+declare const RULE_NAMESPACE = "template-kit";
+/** `no-hex` → `template-kit/no-hex`. */
+declare function qualify(id: RuleId): string;
+/**
+ * `no-hex` → `guide/rules/no-hex.md`.
+ *
+ * Package-relative on purpose: the caller decides what to resolve it against. A
+ * printer prefixes the resolved package root so an author sees a path they can open
+ * with no network (`node_modules/@homepages/template-kit/guide/rules/no-hex.md`);
+ * ESLint's `meta.docs.url` uses it as-is. This module never touches the filesystem —
+ * the ESLint preset imports it.
+ */
+declare function docsPathForRule(id: RuleId): string;
+//#endregion
+export { RULE_IDS, RULE_NAMESPACE, RuleEntry, RuleId, RuleVenue, docsPathForRule, qualify };