@homepages/template-kit 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { AddressParts, TRANSFORMS, TRANSFORM_NAMES, TransformDescriptor, Transfo
 import { VariantSelectorFn, VariantsMeta, makeResolveVariants } from "./schema/resolve-variants.js";
 import { ContentSlot, SLOT_TYPE_DESCRIPTORS, Slot as Slot$1, SlotDef, defaultForSlotType, slotDefTypes } from "./schema/slot-types.js";
 import { VERIFICATION_WIDTHS, VerificationWidth } from "./design-system/breakpoints.js";
-import { FrameConfig, ImageCollectionValue, ImageValue, PoiRow } from "./schema/runtime-values.js";
+import { FrameConfig, ImageCollectionValue, ImageValue, PlaybackConfig, PoiRow, VideoCollectionValue, VideoValue } from "./schema/runtime-values.js";
 import { SectionNav } from "./schema/section-nav.js";
 import { OptionValue, SectionProps, SlotValue } from "./schema/section-props.js";
 import { derived, direct } from "./schema/source.js";
@@ -23,6 +23,7 @@ import { Section } from "./primitives/Section.js";
 import { Slot } from "./primitives/Slot.js";
 import { SlotGroup } from "./primitives/SlotGroup.js";
 import { SlotItem } from "./primitives/SlotItem.js";
+import { Video } from "./primitives/Video.js";
 import "./primitives/index.js";
 import { ATTR_SECTION_INSTANCE_ID, ATTR_SLOT_GROUP, ATTR_SLOT_ID, ATTR_SLOT_ITEM, ATTR_SLOT_TEXT_LEAF, ATTR_TR_ENHANCE } from "./contracts/markers.js";
 import { TokenNameSchema, TokenTheme, TokenThemeSchema, compileThemeToCss } from "./design-system/theme.js";
@@ -38,4 +39,4 @@ import { TokenNameSchema, TokenTheme, TokenThemeSchema, compileThemeToCss } from
  */
 declare const KIT_VERSION: string;
 //#endregion
-export { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ATTR_SECTION_INSTANCE_ID, ATTR_SLOT_GROUP, ATTR_SLOT_ID, ATTR_SLOT_ITEM, ATTR_SLOT_TEXT_LEAF, ATTR_TR_ENHANCE, type AddressParts, COLLECTIONS, CONTENT_SLOT_TYPES, type CollectionField, type CollectionIdKey, type CollectionOwnership, ContentSlot, type ContentSlotType, type Coordinates, DECISION_TYPES, DERIVED_INPUT_FIELDS, Decision, type DecisionType, type DerivedInputName, FORMATTER_NAMES, FillSpec, type FillSpecShape, type FixtureModule, FixtureModuleShape, type FixtureOverride, type FloorplanAssignment, type FormatterName, type FrameConfig, ISLAND_ELEMENT, Image, type ImageCollectionValue, type ImageValue, IslandComponent, IslandEditorOptions, IslandMarker, type IslandMarkerProps, IslandModule, IslandProps, IslandPropsError, KIT_VERSION, OptionDef, type OptionValue, type PicturePlan, type PictureSourceSpec, type PoiRow, type PropertyFacts, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, type RefSlotType, type ReferralField, type ReferralImageField, type ResolvedFixture, type ResponsiveImage, type ResponsiveSource, SLOT_TYPES, SLOT_TYPE_DESCRIPTORS, SOURCE_FIELDS, Section, SectionMeta, type SectionMetaShape, type SectionNav, type SectionProps, SectionSchema, type SectionSchemaResolved, type SectionSchemaShape, ShieldMode, Slot, SlotDef, type Slot$1 as SlotDefinition, SlotGroup, SlotGroupDef, type SlotGroupDefShape, SlotItem, type SlotType, type SlotValue, type SourceFieldContainer, type SourceFieldDescriptor, type SourceFieldName, type SourceFieldValueType, TRANSFORMS, TRANSFORM_NAMES, TemplateManifest, type TemplateManifestShape, TokenNameSchema, type TokenTheme, TokenThemeSchema, type TransformDescriptor, type TransformFn, type TransformInput, type TransformName, type TransformUnit, type UnitRow, VERIFICATION_WIDTHS, type VariantSelectorFn, type VariantsMeta, type VerificationWidth, type WritebackTarget, buildFixtureSet, buildInvariantFixtures, collectionForSlot, compileThemeToCss, defaultForSlotType, derived, deserializeIslandProps, direct, islandId, makeResolveVariants, serializeIslandProps, slotDefTypes };
+export { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ATTR_SECTION_INSTANCE_ID, ATTR_SLOT_GROUP, ATTR_SLOT_ID, ATTR_SLOT_ITEM, ATTR_SLOT_TEXT_LEAF, ATTR_TR_ENHANCE, type AddressParts, COLLECTIONS, CONTENT_SLOT_TYPES, type CollectionField, type CollectionIdKey, type CollectionOwnership, ContentSlot, type ContentSlotType, type Coordinates, DECISION_TYPES, DERIVED_INPUT_FIELDS, Decision, type DecisionType, type DerivedInputName, FORMATTER_NAMES, FillSpec, type FillSpecShape, type FixtureModule, FixtureModuleShape, type FixtureOverride, type FloorplanAssignment, type FormatterName, type FrameConfig, ISLAND_ELEMENT, Image, type ImageCollectionValue, type ImageValue, IslandComponent, IslandEditorOptions, IslandMarker, type IslandMarkerProps, IslandModule, IslandProps, IslandPropsError, KIT_VERSION, OptionDef, type OptionValue, type PicturePlan, type PictureSourceSpec, type PlaybackConfig, type PoiRow, type PropertyFacts, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, type RefSlotType, type ReferralField, type ReferralImageField, type ResolvedFixture, type ResponsiveImage, type ResponsiveSource, SLOT_TYPES, SLOT_TYPE_DESCRIPTORS, SOURCE_FIELDS, Section, SectionMeta, type SectionMetaShape, type SectionNav, type SectionProps, SectionSchema, type SectionSchemaResolved, type SectionSchemaShape, ShieldMode, Slot, SlotDef, type Slot$1 as SlotDefinition, SlotGroup, SlotGroupDef, type SlotGroupDefShape, SlotItem, type SlotType, type SlotValue, type SourceFieldContainer, type SourceFieldDescriptor, type SourceFieldName, type SourceFieldValueType, TRANSFORMS, TRANSFORM_NAMES, TemplateManifest, type TemplateManifestShape, TokenNameSchema, type TokenTheme, TokenThemeSchema, type TransformDescriptor, type TransformFn, type TransformInput, type TransformName, type TransformUnit, type UnitRow, VERIFICATION_WIDTHS, type VariantSelectorFn, type VariantsMeta, type VerificationWidth, Video, type VideoCollectionValue, type VideoValue, type WritebackTarget, buildFixtureSet, buildInvariantFixtures, collectionForSlot, compileThemeToCss, defaultForSlotType, derived, deserializeIslandProps, direct, islandId, makeResolveVariants, serializeIslandProps, slotDefTypes };

package/dist/index.js

@@ -17,6 +17,7 @@ import { Section } from "./primitives/Section.js";
 import { Slot } from "./primitives/Slot.js";
 import { SlotGroup } from "./primitives/SlotGroup.js";
 import { SlotItem } from "./primitives/SlotItem.js";
+import { Video } from "./primitives/Video.js";
 import { TokenNameSchema, TokenThemeSchema, compileThemeToCss } from "./design-system/theme.js";
 
 //#region src/index.ts
@@ -32,4 +33,4 @@ import { TokenNameSchema, TokenThemeSchema, compileThemeToCss } from "./design-s
 const KIT_VERSION = version;
 
 //#endregion
-export { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ATTR_SECTION_INSTANCE_ID, ATTR_SLOT_GROUP, ATTR_SLOT_ID, ATTR_SLOT_ITEM, ATTR_SLOT_TEXT_LEAF, ATTR_TR_ENHANCE, COLLECTIONS, CONTENT_SLOT_TYPES, ContentSlot, DECISION_TYPES, DERIVED_INPUT_FIELDS, Decision, FORMATTER_NAMES, FillSpec, FixtureModuleShape, ISLAND_ELEMENT, Image, IslandMarker, IslandPropsError, KIT_VERSION, OptionDef, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, SLOT_TYPES, SLOT_TYPE_DESCRIPTORS, SOURCE_FIELDS, Section, SectionMeta, SectionSchema, Slot, SlotDef, SlotGroup, SlotGroupDef, SlotItem, TRANSFORMS, TRANSFORM_NAMES, TemplateManifest, TokenNameSchema, TokenThemeSchema, VERIFICATION_WIDTHS, buildFixtureSet, buildInvariantFixtures, collectionForSlot, compileThemeToCss, defaultForSlotType, derived, deserializeIslandProps, direct, islandId, makeResolveVariants, serializeIslandProps, slotDefTypes };
+export { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ATTR_SECTION_INSTANCE_ID, ATTR_SLOT_GROUP, ATTR_SLOT_ID, ATTR_SLOT_ITEM, ATTR_SLOT_TEXT_LEAF, ATTR_TR_ENHANCE, COLLECTIONS, CONTENT_SLOT_TYPES, ContentSlot, DECISION_TYPES, DERIVED_INPUT_FIELDS, Decision, FORMATTER_NAMES, FillSpec, FixtureModuleShape, ISLAND_ELEMENT, Image, IslandMarker, IslandPropsError, KIT_VERSION, OptionDef, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, SLOT_TYPES, SLOT_TYPE_DESCRIPTORS, SOURCE_FIELDS, Section, SectionMeta, SectionSchema, Slot, SlotDef, SlotGroup, SlotGroupDef, SlotItem, TRANSFORMS, TRANSFORM_NAMES, TemplateManifest, TokenNameSchema, TokenThemeSchema, VERIFICATION_WIDTHS, Video, buildFixtureSet, buildInvariantFixtures, collectionForSlot, compileThemeToCss, defaultForSlotType, derived, deserializeIslandProps, direct, islandId, makeResolveVariants, serializeIslandProps, slotDefTypes };

package/dist/island-runtime.js

@@ -2,6 +2,19 @@ import { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, Isl
 
 //#region src/islands/runtime.ts
 const roots = /* @__PURE__ */ new WeakMap();
+function createEditorPropsBridge(react) {
+	const { createElement, useLayoutEffect, useState } = react;
+	return function EditorPropsBridge({ component, serverProps, editorProps }) {
+		const [props, setProps] = useState(serverProps);
+		useLayoutEffect(() => {
+			setProps({
+				...serverProps,
+				...editorProps
+			});
+		}, [serverProps, editorProps]);
+		return createElement(component, props);
+	};
+}
 async function hydrateIslands(options) {
 	const root = options.root ?? document;
 	const markers = Array.from(root.querySelectorAll(`[${ATTR_ISLAND_KEY}]`)).filter((element) => !roots.has(element));
@@ -14,7 +27,9 @@ async function hydrateIslands(options) {
 		if (payloads.has(id)) duplicateIds.add(id);
 		payloads.set(id, script.textContent ?? "");
 	}
-	const [{ createElement }, { hydrateRoot }] = await Promise.all([import("react"), import("react-dom/client")]);
+	const [react, { hydrateRoot }] = await Promise.all([import("react"), import("react-dom/client")]);
+	const { createElement } = react;
+	const EditorPropsBridge = createEditorPropsBridge(react);
 	const handles = [];
 	for (const element of markers) {
 		const key = element.getAttribute("data-tr-island") ?? "";
@@ -34,7 +49,12 @@ async function hydrateIslands(options) {
 			if (options.shouldHydrate && !options.shouldHydrate(ctx)) continue;
 			if (roots.has(element)) continue;
 			if (!element.isConnected) continue;
-			const reactRoot = hydrateRoot(element, createElement(module.default, props), {
+			const editorProps = options.applyEditorProps ? module.editor?.props : void 0;
+			const reactRoot = hydrateRoot(element, editorProps ? createElement(EditorPropsBridge, {
+				component: module.default,
+				serverProps: props,
+				editorProps
+			}) : createElement(module.default, props), {
 				onUncaughtError: (renderError) => {
 					options.onError?.(renderError, ctx);
 				},
@@ -43,11 +63,6 @@ async function hydrateIslands(options) {
 				}
 			});
 			roots.set(element, reactRoot);
-			const editorProps = options.applyEditorProps ? module.editor?.props : void 0;
-			if (editorProps) reactRoot.render(createElement(module.default, {
-				...props,
-				...editorProps
-			}));
 			handles.push(ctx);
 		} catch (error) {
 			options.onError?.(error, ctx);

package/dist/islands/wrap.d.ts

@@ -1,3 +1,4 @@
+import MagicString from "magic-string";
 //#region src/islands/wrap.d.ts
 /**
  * Rewrite a client module's source so its default export renders through

package/dist/islands/wrap.js

@@ -1,5 +1,5 @@
 import { hasClientDirective } from "../eslint/is-client-file.js";
-import MagicString from "../node_modules/magic-string/dist/magic-string.es.js";
+import MagicString from "magic-string";
 
 //#region src/islands/wrap.ts
 const DEFAULT_EXPORT = /export\s+default\s+/;

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.4.0";
+var version = "0.5.0";
 
 //#endregion
 export { version };

package/dist/primitives/Image.d.ts

@@ -44,6 +44,6 @@ type Props = Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt"> & {
  * no descriptor it degrades to a plain single `<img src>`. All `<picture>` planning
  * lives in `buildPictureSources`.
  */
-declare function Image({ src, alt, aspectRatio, slotId, bare, srcMobile, mobileBreakpoint, responsive, responsiveMobile, sizes, maxRungWidth, className, loading, style, ...rest }: Props): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+declare function Image({ src, alt, aspectRatio, slotId, bare, srcMobile, mobileBreakpoint, responsive, responsiveMobile, sizes, maxRungWidth, className, loading, style, ...rest }: Props): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
 //#endregion
 export { Image };

package/dist/primitives/Video.d.ts

@@ -0,0 +1,38 @@
+import { PlaybackConfig } from "../schema/runtime-values.js";
+import { VideoHTMLAttributes } from "react";
+//#region src/primitives/Video.d.ts
+type Props = Omit<VideoHTMLAttributes<HTMLVideoElement>, "src" | "poster" | "autoPlay" | "loop" | "muted" | "controls" | "playsInline" | "preload"> & {
+  /** Rendition URL. Null/empty renders the fallback rect — a supported state. */
+  src: string | null | undefined;
+  /** Poster frame URL — the first paint, and the whole render when `src` is empty. */
+  poster?: string | null;
+  /** Required accessible description. Empty string for a purely decorative loop. */
+  alt: string;
+  /** CSS aspect-ratio reserved on the wrapper; survives missing `src`. */
+  aspectRatio?: string;
+  /** Slot binding — emits `data-slot-id` on the wrapper for the editor click resolver. */
+  slotId?: string;
+  /** Author-declared playback (the slot's `playback` field). Absent ⇒ a plain controls player. */
+  playback?: PlaybackConfig | null;
+  /** Intrinsic rendition dimensions (VideoValue.width/height) — reserve the box, avoid a jump. */
+  width?: number;
+  height?: number;
+};
+/**
+ * Video — the hosted-video primitive. Sections never write a raw `<video>`.
+ *
+ * A wrapper div carries the `data-slot-id` marker and the aspect-ratio box, renders the
+ * poster (or a neutral fallback rect) when `src` is empty, and absolutely-positions the
+ * inner `<video>` with `object-cover` — the same framed contract as `<Image>`.
+ *
+ * **Playback is author-declared**, passed through verbatim from the slot's `playback`
+ * config; the primitive does not infer behavior from the asset. `autoplay` requires
+ * `muted` — that invariant is enforced on the schema at `check` time, so a video that
+ * reaches here with `autoplay` is already muted.
+ *
+ * There is no cropping, no editing, and no responsive ladder: one progressive MP4 is
+ * served per video, and the poster is baked upstream.
+ */
+declare function Video({ src, poster, alt, aspectRatio, slotId, playback, width, height, className, ...rest }: Props): import("react").JSX.Element;
+//#endregion
+export { Video };

package/dist/primitives/Video.js

@@ -0,0 +1,63 @@
+import { ATTR_SLOT_ID } from "../contracts/markers.js";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/Video.tsx
+const DEFAULT_PLAYBACK = { controls: true };
+/**
+* Video — the hosted-video primitive. Sections never write a raw `<video>`.
+*
+* A wrapper div carries the `data-slot-id` marker and the aspect-ratio box, renders the
+* poster (or a neutral fallback rect) when `src` is empty, and absolutely-positions the
+* inner `<video>` with `object-cover` — the same framed contract as `<Image>`.
+*
+* **Playback is author-declared**, passed through verbatim from the slot's `playback`
+* config; the primitive does not infer behavior from the asset. `autoplay` requires
+* `muted` — that invariant is enforced on the schema at `check` time, so a video that
+* reaches here with `autoplay` is already muted.
+*
+* There is no cropping, no editing, and no responsive ladder: one progressive MP4 is
+* served per video, and the poster is baked upstream.
+*/
+function Video({ src, poster, alt, aspectRatio, slotId, playback, width, height, className, ...rest }) {
+	const containerCls = ["tr-image-frame relative block w-full overflow-hidden", className].filter(Boolean).join(" ");
+	const containerStyle = aspectRatio ? { aspectRatio } : void 0;
+	const slotAttrs = slotId ? { [ATTR_SLOT_ID]: slotId } : {};
+	if (!src) return /* @__PURE__ */ jsx("div", {
+		className: containerCls,
+		style: containerStyle,
+		role: "img",
+		"aria-label": alt || void 0,
+		...slotAttrs,
+		children: poster ? /* @__PURE__ */ jsx("img", {
+			src: poster,
+			alt: "",
+			loading: "lazy",
+			decoding: "async",
+			className: "absolute inset-0 h-full w-full object-cover"
+		}) : null
+	});
+	const p = playback ?? DEFAULT_PLAYBACK;
+	return /* @__PURE__ */ jsx("div", {
+		className: containerCls,
+		style: containerStyle,
+		...slotAttrs,
+		children: /* @__PURE__ */ jsx("video", {
+			src,
+			poster: poster ?? void 0,
+			"aria-label": alt || void 0,
+			width,
+			height,
+			autoPlay: p.autoplay,
+			loop: p.loop,
+			muted: p.muted,
+			controls: p.controls,
+			playsInline: p.playsinline,
+			preload: p.preload,
+			className: "absolute inset-0 h-full w-full object-cover",
+			...rest
+		})
+	});
+}
+
+//#endregion
+export { Video };

package/dist/primitives/index.d.ts

@@ -4,4 +4,5 @@ import { Section } from "./Section.js";
 import { Slot } from "./Slot.js";
 import { SlotGroup } from "./SlotGroup.js";
 import { SlotItem } from "./SlotItem.js";
-export { Image, type PicturePlan, type PictureSourceSpec, Section, Slot, SlotGroup, SlotItem };
+import { Video } from "./Video.js";
+export { Image, type PicturePlan, type PictureSourceSpec, Section, Slot, SlotGroup, SlotItem, Video };

package/dist/rules/registry.js

@@ -1,15 +1,15 @@
 //#region src/rules/registry.ts
 /**
-* `no-hex` → `docs/rules/no-hex.md`.
+* `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/docs/rules/no-hex.md`);
+* 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.
 */
 function docsPathForRule(id) {
-	return `docs/rules/${id}.md`;
+	return `guide/rules/${id}.md`;
 }
 
 //#endregion

package/dist/schema/index.d.ts

@@ -5,7 +5,7 @@ import { AddressParts, TRANSFORMS, TRANSFORM_NAMES, TransformDescriptor, Transfo
 import { VariantSelectorFn, VariantsMeta, makeResolveVariants } from "./resolve-variants.js";
 import { ContentSlot, SLOT_TYPE_DESCRIPTORS, Slot, SlotDef, defaultForSlotType, slotDefTypes } from "./slot-types.js";
 import { VERIFICATION_WIDTHS, VerificationWidth } from "../design-system/breakpoints.js";
-import { FrameConfig, ImageCollectionValue, ImageValue, PoiRow } from "./runtime-values.js";
+import { FrameConfig, ImageCollectionValue, ImageValue, PlaybackConfig, PoiRow, VideoCollectionValue, VideoValue } from "./runtime-values.js";
 import { SectionNav } from "./section-nav.js";
 import { OptionValue, SectionProps, SlotValue } from "./section-props.js";
 import { derived, direct } from "./source.js";
@@ -13,4 +13,4 @@ import { OptionDef, SectionMeta, SectionMetaShape, SectionSchema, SectionSchemaR
 import { Decision, FillSpec, FillSpecShape } from "./fill-spec.js";
 import { FixtureModule, FixtureModuleShape, FixtureOverride, ResolvedFixture, buildFixtureSet, buildInvariantFixtures } from "./fixture-schema.js";
 import { TemplateManifest, TemplateManifestShape } from "./manifest.js";
-export { type AddressParts, COLLECTIONS, CONTENT_SLOT_TYPES, type CollectionField, type CollectionIdKey, type CollectionOwnership, ContentSlot, type ContentSlotType, type Coordinates, DECISION_TYPES, DERIVED_INPUT_FIELDS, Decision, type DecisionType, type DerivedInputName, FORMATTER_NAMES, FillSpec, type FillSpecShape, type FixtureModule, FixtureModuleShape, type FixtureOverride, type FloorplanAssignment, type FormatterName, type FrameConfig, type ImageCollectionValue, type ImageValue, OptionDef, type OptionValue, type PoiRow, type PropertyFacts, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, type RefSlotType, type ReferralField, type ReferralImageField, type ResolvedFixture, type ResponsiveImage, type ResponsiveSource, SLOT_TYPES, SLOT_TYPE_DESCRIPTORS, SOURCE_FIELDS, SectionMeta, type SectionMetaShape, type SectionNav, type SectionProps, SectionSchema, type SectionSchemaResolved, type SectionSchemaShape, type Slot, SlotDef, SlotGroupDef, type SlotGroupDefShape, type SlotType, type SlotValue, type SourceFieldContainer, type SourceFieldDescriptor, type SourceFieldName, type SourceFieldValueType, TRANSFORMS, TRANSFORM_NAMES, TemplateManifest, type TemplateManifestShape, type TransformDescriptor, type TransformFn, type TransformInput, type TransformName, type TransformUnit, type UnitRow, VERIFICATION_WIDTHS, type VariantSelectorFn, type VariantsMeta, type VerificationWidth, type WritebackTarget, buildFixtureSet, buildInvariantFixtures, collectionForSlot, defaultForSlotType, derived, direct, makeResolveVariants, slotDefTypes };
+export { type AddressParts, COLLECTIONS, CONTENT_SLOT_TYPES, type CollectionField, type CollectionIdKey, type CollectionOwnership, ContentSlot, type ContentSlotType, type Coordinates, DECISION_TYPES, DERIVED_INPUT_FIELDS, Decision, type DecisionType, type DerivedInputName, FORMATTER_NAMES, FillSpec, type FillSpecShape, type FixtureModule, FixtureModuleShape, type FixtureOverride, type FloorplanAssignment, type FormatterName, type FrameConfig, type ImageCollectionValue, type ImageValue, OptionDef, type OptionValue, type PlaybackConfig, type PoiRow, type PropertyFacts, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, type RefSlotType, type ReferralField, type ReferralImageField, type ResolvedFixture, type ResponsiveImage, type ResponsiveSource, SLOT_TYPES, SLOT_TYPE_DESCRIPTORS, SOURCE_FIELDS, SectionMeta, type SectionMetaShape, type SectionNav, type SectionProps, SectionSchema, type SectionSchemaResolved, type SectionSchemaShape, type Slot, SlotDef, SlotGroupDef, type SlotGroupDefShape, type SlotType, type SlotValue, type SourceFieldContainer, type SourceFieldDescriptor, type SourceFieldName, type SourceFieldValueType, TRANSFORMS, TRANSFORM_NAMES, TemplateManifest, type TemplateManifestShape, type TransformDescriptor, type TransformFn, type TransformInput, type TransformName, type TransformUnit, type UnitRow, VERIFICATION_WIDTHS, type VariantSelectorFn, type VariantsMeta, type VerificationWidth, type VideoCollectionValue, type VideoValue, type WritebackTarget, buildFixtureSet, buildInvariantFixtures, collectionForSlot, defaultForSlotType, derived, direct, makeResolveVariants, slotDefTypes };

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

@@ -32,6 +32,25 @@ type ImageValue = {
   responsive?: ResponsiveImage | null;
 };
 type ImageCollectionValue = ImageValue[];
+type PlaybackConfig = {
+  autoplay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  controls?: boolean;
+  playsinline?: boolean;
+  /** Bandwidth lever: "none" for a below-fold video most visitors never reach. */
+  preload?: "none" | "metadata" | "auto";
+};
+type VideoValue = {
+  video_id: string;
+  url: string;
+  /** Poster frame URL — always present; the transcode derives one (D9). */
+  poster: string;
+  alt: string;
+  width?: number;
+  height?: number;
+};
+type VideoCollectionValue = VideoValue[];
 type PoiRow = {
   id: string;
   place_id: string;
@@ -42,4 +61,4 @@ type PoiRow = {
   distance_m: number | null;
 };
 //#endregion
-export { type Coordinates, type FloorplanAssignment, FrameConfig, ImageCollectionValue, ImageValue, PoiRow, type PropertyFacts, type UnitRow };
+export { type Coordinates, type FloorplanAssignment, FrameConfig, ImageCollectionValue, ImageValue, PlaybackConfig, PoiRow, type PropertyFacts, type UnitRow, VideoCollectionValue, VideoValue };

package/dist/schema/section-props.d.ts

@@ -1,4 +1,4 @@
-import { ImageCollectionValue, ImageValue, PoiRow } from "./runtime-values.js";
+import { ImageCollectionValue, ImageValue, PoiRow, VideoCollectionValue, VideoValue } from "./runtime-values.js";
 import { SectionNav } from "./section-nav.js";
 import { SectionSchemaShape } from "./section-schema.js";
 //#region src/schema/section-props.d.ts
@@ -25,6 +25,13 @@ type SlotValue<S> = S extends {
 } ? ImageValue | null : S extends {
   type: "image_collection";
 } ? ImageCollectionValue : S extends {
+  type: "video";
+  required: true;
+} ? VideoValue : S extends {
+  type: "video";
+} ? VideoValue | null : S extends {
+  type: "video_collection";
+} ? VideoCollectionValue : S extends {
   type: "list";
   element: {
     type: "text";

package/dist/schema/section-schema.d.ts

@@ -2,7 +2,7 @@ import { Coordinates, FloorplanAssignment, PropertyFacts, UnitRow } from "./prop
 import { CONTENT_SLOT_TYPES, REFERRAL_FIELDS, REF_SLOT_TYPES, SLOT_TYPES, SlotType } from "../contracts/slot-catalog.js";
 import { VariantSelectorFn } from "./resolve-variants.js";
 import { ContentSlot, Slot, SlotDef, defaultForSlotType } from "./slot-types.js";
-import { FrameConfig, ImageCollectionValue, ImageValue, PoiRow } from "./runtime-values.js";
+import { FrameConfig, ImageCollectionValue, ImageValue, PlaybackConfig, PoiRow, VideoCollectionValue, VideoValue } from "./runtime-values.js";
 import { OptionValue, SectionProps, SlotValue } from "./section-props.js";
 import { derived, direct } from "./source.js";
 import { z } from "zod";
@@ -144,4 +144,4 @@ type SectionSchemaResolved = Omit<z.infer<typeof SectionSchema>, "meta"> & {
   }>;
 };
 //#endregion
-export { CONTENT_SLOT_TYPES, ContentSlot, type Coordinates, type FloorplanAssignment, type FrameConfig, type ImageCollectionValue, type ImageValue, OptionDef, type OptionValue, type PoiRow, type PropertyFacts, REFERRAL_FIELDS, REF_SLOT_TYPES, SLOT_TYPES, SectionMeta, SectionMetaShape, type SectionProps, SectionSchema, SectionSchemaResolved, SectionSchemaShape, type Slot, SlotDef, SlotGroupDef, SlotGroupDefShape, type SlotType, type SlotValue, type UnitRow, defaultForSlotType, derived, direct };
+export { CONTENT_SLOT_TYPES, ContentSlot, type Coordinates, type FloorplanAssignment, type FrameConfig, type ImageCollectionValue, type ImageValue, OptionDef, type OptionValue, type PlaybackConfig, type PoiRow, type PropertyFacts, REFERRAL_FIELDS, REF_SLOT_TYPES, SLOT_TYPES, SectionMeta, SectionMetaShape, type SectionProps, SectionSchema, SectionSchemaResolved, SectionSchemaShape, type Slot, SlotDef, SlotGroupDef, SlotGroupDefShape, type SlotType, type SlotValue, type UnitRow, type VideoCollectionValue, type VideoValue, defaultForSlotType, derived, direct };

package/dist/schema/slot-types.d.ts

@@ -19,6 +19,8 @@ declare const ContentSlot: z.ZodObject<{
     object_list: "object_list";
     poi_list: "poi_list";
     url: "url";
+    video: "video";
+    video_collection: "video_collection";
   }>;
   editable_by_user: z.ZodDefault<z.ZodBoolean>;
   required: z.ZodDefault<z.ZodBoolean>;
@@ -84,6 +86,18 @@ type ImageCollectionSlot = SlotBase & {
   crop?: unknown;
   frame?: unknown;
 };
+type VideoSlot = SlotBase & {
+  type: "video";
+  frame?: unknown;
+  playback?: unknown;
+};
+type VideoCollectionSlot = SlotBase & {
+  type: "video_collection";
+  min?: number;
+  max?: number;
+  frame?: unknown;
+  playback?: unknown;
+};
 type ListSlot = SlotBase & {
   type: "list";
   min?: number;
@@ -107,7 +121,7 @@ type ObjectListSlot = SlotBase & {
   item_order?: string[];
   item_layout?: (string | [string, string])[];
 };
-type Slot = TextSlot | NumberSlot | SelectSlot | ImageSlot | ImageCollectionSlot | ListSlot | PoiListSlot | UrlSlot | ObjectListSlot;
+type Slot = TextSlot | NumberSlot | SelectSlot | ImageSlot | ImageCollectionSlot | VideoSlot | VideoCollectionSlot | ListSlot | PoiListSlot | UrlSlot | ObjectListSlot;
 declare function defaultForSlotType(type: string): unknown;
 //#endregion
 export { ContentSlot, SLOT_TYPE_DESCRIPTORS, Slot, SlotDef, defaultForSlotType, slotDefTypes };

package/dist/schema/slot-types.js

@@ -32,6 +32,18 @@ const frameConfigShape = { frame: z.object({
 		nominal: z.boolean().optional()
 	}).strict().optional()
 }).strict().optional() };
+const playbackConfigShape = { playback: z.object({
+	autoplay: z.boolean().optional(),
+	loop: z.boolean().optional(),
+	muted: z.boolean().optional(),
+	controls: z.boolean().optional(),
+	playsinline: z.boolean().optional(),
+	preload: z.enum([
+		"none",
+		"metadata",
+		"auto"
+	]).optional()
+}).strict().refine((p) => p.autoplay !== true || p.muted === true, { message: "autoplay requires muted (browsers block unmuted autoplay)" }).optional() };
 const slotMetadataShape = {
 	display_name: z.string().optional(),
 	placeholder: z.string().optional(),
@@ -110,6 +122,26 @@ const SLOT_TYPE_DESCRIPTORS = {
 		},
 		default: () => []
 	},
+	video: {
+		shape: {
+			...frameConfigShape,
+			...playbackConfigShape
+		},
+		default: () => ({
+			url: "",
+			poster: "",
+			alt: ""
+		})
+	},
+	video_collection: {
+		shape: {
+			min: z.number().int().nonnegative().optional(),
+			max: z.number().int().positive().optional(),
+			...frameConfigShape,
+			...playbackConfigShape
+		},
+		default: () => []
+	},
 	list: {
 		shape: {
 			min: z.number().int().nonnegative().optional(),
@@ -155,6 +187,8 @@ const SLOT_DEF_MEMBERS = [
 	slotMember("select", SLOT_TYPE_DESCRIPTORS.select.shape),
 	slotMember("image", SLOT_TYPE_DESCRIPTORS.image.shape),
 	slotMember("image_collection", SLOT_TYPE_DESCRIPTORS.image_collection.shape),
+	slotMember("video", SLOT_TYPE_DESCRIPTORS.video.shape),
+	slotMember("video_collection", SLOT_TYPE_DESCRIPTORS.video_collection.shape),
 	slotMember("list", SLOT_TYPE_DESCRIPTORS.list.shape),
 	slotMember("poi_list", SLOT_TYPE_DESCRIPTORS.poi_list.shape),
 	slotMember("url", SLOT_TYPE_DESCRIPTORS.url.shape),

package/dist/schema/synthesize-nullable.js

@@ -5,6 +5,7 @@ const LIST_TYPES = /* @__PURE__ */ new Set([
 	"list",
 	"poi_list",
 	"image_collection",
+	"video_collection",
 	"object_list"
 ]);
 function emptyValueFor(type) {

package/{docs → guide}/INDEX.md

@@ -1,12 +1,12 @@
 ---
-purpose: Router for the docs corpus that ships inside the @homepages/template-kit npm package.
+purpose: Router for the guide corpus that ships inside the @homepages/template-kit npm package.
 status: living
 related: []
 updated: 2026-07-16
 ---
-# template-kit docs — router
+# template-kit guide — router
 
-This tree **ships in the npm tarball** (`docs/` is listed in `package.json`'s
+This tree **ships in the npm tarball** (`guide/` is listed in `package.json`'s
 `files`), so it is written for an outside audience: template authors and their
 LLM agents, reading it from inside `node_modules`. Keep it free of internal-only
 detail.
@@ -16,9 +16,9 @@ detail.
 | `quickstart.md` | The cold-start tutorial: create a workspace, preview the starter's `hero` section, read its four files, make one edit, and check it — owns the author-loop anchor every recipe links to | your first section, end to end |
 | `overview.md` | The one-page mental model: workspace → templates → sections, the four reserved files, and the server-vs-client mapping | orienting yourself before your first section |
 | `llms.txt` | Machine-readable index of this corpus for an agent working inside an installed kit | orienting an agent in a consuming workspace |
-| `schema-system.md` | The section authoring contract: `schema.ts` / `fill-spec.ts` / `fixtures.ts` / `Renderer.tsx`, `SectionProps` inference, the closed source/transform vocabulary, and the golden property fixtures | authoring or changing any section |
-| `vocabulary.md` | The closed authoring vocabulary — the 9 slot types, the `direct()` source fields, and the `derived()` transforms, with selection semantics | choosing which slot type / source / transform to use |
-| `primitives.md` | The five contract primitives (`Section`, `Slot`, `SlotItem`, `SlotGroup`, `Image`) and the marker attributes they emit | writing a section's markup |
+| `schema-system.md` | The section authoring contract: `schema.ts` / `fill-spec.ts` / `fixtures.ts` / `Renderer.tsx`, `SectionProps` inference, the closed source/transform vocabulary, and the scenario API + fill-by-source rule | authoring or changing any section |
+| `vocabulary.md` | The closed authoring vocabulary — the 11 slot types, the `direct()` source fields, and the `derived()` transforms, with selection semantics | choosing which slot type / source / transform to use |
+| `primitives.md` | The six contract primitives (`Section`, `Slot`, `SlotItem`, `SlotGroup`, `Image`, `Video`) and the marker attributes they emit | writing a section's markup |
 | `assets.md` | Static assets (svg/images/fonts): where they live (template level or a section folder, if referenced), referencing them from a section's CSS with `url()`/`@font-face` or importing them into a component, and the asset-vs-content-image distinction | shipping a logo, texture, icon, or brand font with a template |
 | `theme-and-css.md` | The two CSS entries, the one-Tailwind-import rule, `TokenTheme` (your own token names → your own Tailwind utilities), the `template-kit theme` command that generates `theme.css` from `theme.ts`, the breakpoint ladder, and the opt-in `content-visibility` recipe for long, image-heavy pages | a template's theme, its CSS entry, or a long page with a live map or full-screen overlay |
 | `islands.md` | Interactivity: `"use client"` components, the serializable-props rule, editor options, the loader | anything interactive in a section |
@@ -27,5 +27,6 @@ detail.
 | `dev.md` | The `template-kit dev` CLI command: the local preview server, its home launcher and two tool cards (full template viewer, canvas mirror), the canvas mirror's selection overlay and per-slot edit panel, live reload, the content-override protocol, and the render/inspect/screenshot endpoints | previewing sections as you author them |
 | `new.md` | The `template-kit new` / `new-section` CLI commands: scaffolding a new template with a working starter section, or adding a bare section to an existing template | adding a template or a section to a workspace |
 | `pack.md` | The `template-kit pack` CLI command: builds a template's submission zip — template source, the workspace lockfile, and a stamped `pack-manifest.json`; refuses on a failing `check`, a missing lockfile, or a local-protocol dependency | packaging a template for submission |
+| `upgrading.md` | Moving to a new kit version: what a patch vs a minor means while the kit is pre-1.0, why `npm update` cannot cross a minor, and how long the previous line keeps being accepted | a new kit version shipped, or your kit version was refused at submission |
 | `rules/` | One page per rule-id (`template-kit/*`), across both venues — the id printed by a lint or `check` failure resolves here. `rules/INDEX.md` routes them; `rules/server-vs-client.md` is the concept the server-rendering rules assume | any lint or `check` failure |
 | `recipes/` | Task recipes: how do I add a slot, bind a fact, add an island, package a template… Each is a minimal delta from the starter's `hero` section, ending in the author loop. `recipes/INDEX.md` routes them by task | doing something specific and not sure which file to touch |

package/{docs → guide}/check.md

@@ -1,8 +1,8 @@
 ---
 purpose: The `template-kit check` command — what it runs, its flags, its output shape, and its exit code.
 status: living
-related: [INDEX.md, rules/INDEX.md, eslint.md, theme-and-css.md, dev.md]
-updated: 2026-07-15
+related: [INDEX.md, rules/INDEX.md, eslint.md, theme-and-css.md, dev.md, upgrading.md]
+updated: 2026-07-16
 ---
 # template-kit check
 

package/{docs → guide}/islands.md

@@ -2,7 +2,7 @@
 purpose: How interactivity works in a template — client components ("islands"), their props contract, and their editor options.
 status: living
 related: [INDEX.md, eslint.md, dev.md]
-updated: 2026-07-15
+updated: 2026-07-16
 ---
 
 # Islands: interactivity in a template
@@ -99,6 +99,11 @@ export const editor: IslandEditorOptions = {
 };
 ```
 
+`props` merge in as an update immediately after the island hydrates, not as part of its
+first mount — so an island must read them during render. A value read only at mount time
+(a `useState` initializer, an `<input defaultValue>`) sees the real prop, and the
+editor-only override never reaches it.
+
 Omit `editor` entirely and the island simply renders as static markup in the editor —
 which is the right choice for most islands.
 

package/{docs → guide}/llms.txt

@@ -4,7 +4,9 @@
 > inside the npm package so an agent can read it locally, versioned in lockstep
 > with the code it describes.
 
-Status: 0.0.x. The schema system, the contract primitives, and the theme system are
+Status: 0.x — pre-1.0, so a minor is the breaking axis and a patch carries features
+as well as fixes; see [Upgrading](upgrading.md). The schema system, the contract
+primitives, and the theme system are
 complete — a section is authorable end to end against the kit. The `template-kit`
 CLI's `check`, `theme`, `dev`, `pack`, `new`, and `new-section` commands are
 implemented — see [Check](check.md), [Theme and CSS](theme-and-css.md#generating-themecss),
@@ -12,8 +14,10 @@ implemented — see [Check](check.md), [Theme and CSS](theme-and-css.md#generati
 commands arrive with the surfaces they drive.
 
 Everything an author writes a section against is imported from the package root —
-`@homepages/template-kit`, no subpath imports. The two CSS entries
-(`./styles.css`, `./base.css`) are the deliberate exception.
+`@homepages/template-kit`. The exceptions are deliberate: the two CSS entries
+(`./styles.css`, `./base.css`), and `./fixtures` — the golden scenarios, which only
+`fixtures.ts` imports, kept off the root barrel so dev-only sample data can never
+reach a published renderer's import graph.
 
 ## Start here
 
@@ -23,6 +27,16 @@ read [Overview](overview.md). For the closed sets — slot types, `direct()`
 sources, `derived()` transforms — see [Vocabulary](vocabulary.md). When a lint
 or `check` prints a rule id, resolve it at `rules/<id>.md`.
 
+Writing or editing a section's `fixtures.ts`? Fold fixture creation into the same
+edit, by default — don't invent placeholder content. Pick one of the kit's three
+scenarios (`@homepages/template-kit/fixtures`) and fill every slot by its
+fill-spec source: a `direct()` slot reads the fact straight off the scenario, a
+`derived()` slot goes through a helper (`propertyMetrics`, `poisByCategory`,
+`contactCards`, `primaryContact`), and an AI-filled slot gets a short sample
+grounded in the scenario's facts — never lorem ipsum. See
+[Schema system § fixtures.ts](schema-system.md#fixturests--content-for-local-preview)
+and [Pick a scenario](recipes/pick-a-scenario.md).
+
 ## Docs
 
 - [Quickstart](quickstart.md): the cold-start tutorial — create a workspace,
@@ -32,18 +46,19 @@ or `check` prints a rule id, resolve it at `rules/<id>.md`.
   sections, the four reserved files, and the server-vs-client mapping.
 - [Schema system](schema-system.md): the section authoring contract. A section is
   four files — `schema.ts` (slots + options + `meta.groups`), `fill-spec.ts` (how AI
-  fills them), `fixtures.ts` (preview content, built on the kit's golden property
-  dataset), `Renderer.tsx` (markup, with props DERIVED from the schema via
-  `SectionProps<typeof schema>`). Covers the `as const satisfies` requirement, binding
-  slots to property facts with `direct()`/`derived()` over a closed vocabulary, and
-  fact-driven variants.
-- [Vocabulary](vocabulary.md): the closed authoring vocabulary — the 9 slot
+  fills them), `fixtures.ts` (preview content — fill every slot from a scenario, by
+  its fill-spec source), `Renderer.tsx` (markup, with props DERIVED from the schema
+  via `SectionProps<typeof schema>`). Covers the `as const satisfies` requirement,
+  binding slots to property facts with `direct()`/`derived()` over a closed
+  vocabulary, fact-driven variants, and the scenario API + fill-by-source rule.
+- [Vocabulary](vocabulary.md): the closed authoring vocabulary — the 11 slot
   types, the `direct()` source fields, and the `derived()` transforms, with
   selection semantics (which one to pick).
-- [Contract primitives](primitives.md): the only five components the kit ships —
+- [Contract primitives](primitives.md): the only six components the kit ships —
   `Section` (full-bleed section root), `Slot` (`data-slot-id`), `SlotItem` (per-item
-  handle in an `object_list` / `image_collection`), `SlotGroup` (`data-slot-group`),
-  and `Image` (responsive `<picture>`, empty-state box). Plus the marker-attribute
+  handle in an `object_list` / `image_collection` / `video_collection`), `SlotGroup`
+  (`data-slot-group`), `Image` (responsive `<picture>`, empty-state box), and `Video`
+  (poster frame, author-declared playback, empty-state box). Plus the marker-attribute
   contract (`ATTR_SLOT_ID`, `ATTR_SLOT_ITEM`, …). Presentation is the template's own JSX.
 - [Theme and CSS](theme-and-css.md): the two CSS entries and how they load; import
   Tailwind exactly once; `base.css` ships no reset of its own — it requires the
@@ -79,14 +94,19 @@ or `check` prints a rule id, resolve it at `rules/<id>.md`.
   submission zip (the template's source, the workspace lockfile, and a stamped
   `pack-manifest.json`), and the conditions it refuses to pack under: a failing
   `check`, a missing lockfile, or a local `file:`/`link:` dependency.
+- [Upgrading](upgrading.md): taking a new kit version. The kit is pre-1.0, so a
+  patch (0.4.0 → 0.4.1) carries features AND fixes and `npm update` takes it, while
+  a minor (0.4.x → 0.5.0) is breaking and needs an explicit
+  `npm install @homepages/template-kit@^0.5.0` — a 0.x caret never crosses a minor.
+  Submissions are accepted against the current kit line and the one before it.
 - [Adding templates](new.md): the `template-kit new <template>` and
   `template-kit new-section <template>/<section>` CLI commands — scaffolding a new
   template with a working starter section, or adding a bare section (the four
   reserved contract files, no island) to an existing template. Both refuse to
   overwrite an existing folder.
 - [Rules](rules/INDEX.md): every rule-id a lint or `check` failure can print, under the
-  `template-kit/<id>` namespace, one page each at `docs/rules/<id>.md` — Rule / Reason /
-  Fix / Before→After. **The loop:** see an id in a failure → read `docs/rules/<id>.md` →
+  `template-kit/<id>` namespace, one page each at `guide/rules/<id>.md` — Rule / Reason /
+  Fix / Before→After. **The loop:** see an id in a failure → read `guide/rules/<id>.md` →
   fix. Nothing else to search for; the id is the filename.
 - [Recipes](recipes/INDEX.md): task recipes routed by "how do I…" — each one a minimal,
   complete delta from the starter's `hero` section (never a from-scratch file), ending in