@homepages/template-kit 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -1,14 +1,30 @@
-//#region src/kit-smoke.d.ts
-/**
- * Boundary probe, not authoring surface. Its only job is to make the package
- * boundary testable: React stays a peer, types resolve, and Tailwind's
- * cross-package @source scan reaches this file's compiled output.
- * Removed when the real contract primitives land.
- */
-declare function KitSmoke({ label }: {
-  label: string;
-}): import("react").JSX.Element;
-//#endregion
+import { ResponsiveImage, ResponsiveSource } from "./contracts/image-descriptor.js";
+import { Coordinates, FloorplanAssignment, PropertyFacts, UnitRow } from "./schema/property-facts.js";
+import { COLLECTIONS, CONTENT_SLOT_TYPES, CollectionField, CollectionIdKey, CollectionOwnership, ContentSlotType, DECISION_TYPES, DERIVED_INPUT_FIELDS, DecisionType, DerivedInputName, FORMATTER_NAMES, FormatterName, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, RefSlotType, ReferralField, ReferralImageField, SLOT_TYPES, SOURCE_FIELDS, SlotType, SourceFieldContainer, SourceFieldDescriptor, SourceFieldName, SourceFieldValueType, WritebackTarget, collectionForSlot } from "./contracts/slot-catalog.js";
+import { AddressParts, TRANSFORMS, TRANSFORM_NAMES, TransformDescriptor, TransformFn, TransformInput, TransformName, TransformUnit } from "./contracts/transforms.js";
+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 { SectionNav } from "./schema/section-nav.js";
+import { OptionValue, SectionProps, SlotValue } from "./schema/section-props.js";
+import { derived, direct } from "./schema/source.js";
+import { OptionDef, SectionMeta, SectionMetaShape, SectionSchema, SectionSchemaResolved, SectionSchemaShape, SlotGroupDef, SlotGroupDefShape } from "./schema/section-schema.js";
+import { Decision, FillSpec, FillSpecShape } from "./schema/fill-spec.js";
+import { FixtureModule, FixtureModuleShape, FixtureOverride, ResolvedFixture, buildFixtureSet, buildInvariantFixtures } from "./schema/fixture-schema.js";
+import { TemplateManifest, TemplateManifestShape } from "./schema/manifest.js";
+import "./schema/index.js";
+import { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, IslandComponent, IslandEditorOptions, IslandModule, IslandProps, IslandPropsError, ShieldMode, deserializeIslandProps, islandId, serializeIslandProps } from "./islands/contract.js";
+import { IslandMarker, IslandMarkerProps } from "./islands/marker.js";
+import { Image } from "./primitives/Image.js";
+import { PicturePlan, PictureSourceSpec } from "./primitives/picture-sources.js";
+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 "./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 { COLOR_ROLE_VARS, ColorRole, FONT_ROLE_VARS, LAYOUT_VARS, RADIUS_VARS, SHADOW_VARS, TYPE_STEP_VARS, TokenTheme, TokenThemeSchema, compileThemeToCss } from "./design-system/theme.js";
 //#region src/index.d.ts
 /**
  * The published version of this kit.
@@ -21,4 +37,4 @@ declare function KitSmoke({ label }: {
  */
 declare const KIT_VERSION: string;
 //#endregion
-export { KIT_VERSION, KitSmoke };
+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, COLOR_ROLE_VARS, CONTENT_SLOT_TYPES, type CollectionField, type CollectionIdKey, type CollectionOwnership, type ColorRole, ContentSlot, type ContentSlotType, type Coordinates, DECISION_TYPES, DERIVED_INPUT_FIELDS, Decision, type DecisionType, type DerivedInputName, FONT_ROLE_VARS, 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, LAYOUT_VARS, OptionDef, type OptionValue, type PicturePlan, type PictureSourceSpec, type PoiRow, type PropertyFacts, RADIUS_VARS, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, type RefSlotType, type ReferralField, type ReferralImageField, type ResolvedFixture, type ResponsiveImage, type ResponsiveSource, SHADOW_VARS, 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, TYPE_STEP_VARS, TemplateManifest, type TemplateManifestShape, 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 };

package/dist/index.js

@@ -1,3 +1,35 @@
-import { n as KitSmoke, t as KIT_VERSION } from "./src-dZr5N30y.js";
+import { version } from "./package.js";
+import { COLLECTIONS, CONTENT_SLOT_TYPES, DECISION_TYPES, DERIVED_INPUT_FIELDS, FORMATTER_NAMES, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, SLOT_TYPES, SOURCE_FIELDS, collectionForSlot } from "./contracts/slot-catalog.js";
+import { ContentSlot, SLOT_TYPE_DESCRIPTORS, SlotDef, defaultForSlotType, slotDefTypes } from "./schema/slot-types.js";
+import { derived, direct } from "./schema/source.js";
+import { OptionDef, SectionMeta, SectionSchema, SlotGroupDef } from "./schema/section-schema.js";
+import { makeResolveVariants } from "./schema/resolve-variants.js";
+import { Decision, FillSpec } from "./schema/fill-spec.js";
+import { FixtureModuleShape, buildFixtureSet, buildInvariantFixtures } from "./schema/fixture-schema.js";
+import { TemplateManifest } from "./schema/manifest.js";
+import { TRANSFORMS, TRANSFORM_NAMES } from "./contracts/transforms.js";
+import { VERIFICATION_WIDTHS } from "./design-system/breakpoints.js";
+import { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, IslandPropsError, deserializeIslandProps, islandId, serializeIslandProps } from "./islands/contract.js";
+import { IslandMarker } from "./islands/marker.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 { Image } from "./primitives/Image.js";
+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 { COLOR_ROLE_VARS, FONT_ROLE_VARS, LAYOUT_VARS, RADIUS_VARS, SHADOW_VARS, TYPE_STEP_VARS, TokenThemeSchema, compileThemeToCss } from "./design-system/theme.js";
 
-export { KIT_VERSION, KitSmoke };
+//#region src/index.ts
+/**
+* The published version of this kit.
+*
+* Read from package.json and inlined at build time, so it cannot drift: changesets
+* owns package.json's version, and a hardcoded constant here would have to be
+* hand-edited on every release — on a branch changesets force-pushes, which would
+* silently discard the edit. `dist/cli.js --version` is asserted against
+* package.json to prove the inlining actually happened.
+*/
+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, COLOR_ROLE_VARS, CONTENT_SLOT_TYPES, ContentSlot, DECISION_TYPES, DERIVED_INPUT_FIELDS, Decision, FONT_ROLE_VARS, FORMATTER_NAMES, FillSpec, FixtureModuleShape, ISLAND_ELEMENT, Image, IslandMarker, IslandPropsError, KIT_VERSION, LAYOUT_VARS, OptionDef, RADIUS_VARS, REFERRAL_FIELDS, REFERRAL_IMAGE_FIELDS, REF_SLOT_TYPES, SHADOW_VARS, SLOT_TYPES, SLOT_TYPE_DESCRIPTORS, SOURCE_FIELDS, Section, SectionMeta, SectionSchema, Slot, SlotDef, SlotGroup, SlotGroupDef, SlotItem, TRANSFORMS, TRANSFORM_NAMES, TYPE_STEP_VARS, TemplateManifest, TokenThemeSchema, VERIFICATION_WIDTHS, buildFixtureSet, buildInvariantFixtures, collectionForSlot, compileThemeToCss, defaultForSlotType, derived, deserializeIslandProps, direct, islandId, makeResolveVariants, serializeIslandProps, slotDefTypes };

package/dist/island-runtime.d.ts

@@ -0,0 +1,30 @@
+import { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, IslandComponent, IslandEditorOptions, IslandModule, IslandProps, IslandPropsError, ShieldMode, deserializeIslandProps, islandId, serializeIslandProps } from "./islands/contract.js";
+//#region src/islands/runtime.d.ts
+/** What the loader knows about one island once its module has loaded. */
+interface IslandContext {
+  id: string;
+  key: string;
+  element: HTMLElement;
+  editor?: IslandEditorOptions;
+}
+type IslandHandle = IslandContext;
+interface HydrateIslandsOptions {
+  /** Where to look for markers. Default: the whole document. */
+  root?: ParentNode;
+  /** Resolve an island key to its module. The host owns this map (the build generates it). */
+  load: (islandKey: string) => Promise<IslandModule>;
+  /** Decide whether to hydrate, once the module (and so its editor options) is known. */
+  shouldHydrate?: (ctx: IslandContext) => boolean;
+  /** Merge `editor.props` over the server-rendered props (editor canvas only). */
+  applyEditorProps?: boolean;
+  /** A failed island is reported here; its neighbors still hydrate. */
+  onError?: (error: unknown, ctx: IslandContext) => void;
+}
+declare function hydrateIslands(options: HydrateIslandsOptions): Promise<IslandHandle[]>;
+/**
+ * Unmount every island hydrated under `root`. Synchronous, so the editor can call it
+ * immediately before replacing a section's innerHTML.
+ */
+declare function unmountIslands(root?: ParentNode): void;
+//#endregion
+export { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, HydrateIslandsOptions, ISLAND_ELEMENT, IslandComponent, IslandContext, IslandEditorOptions, IslandHandle, IslandModule, IslandProps, IslandPropsError, ShieldMode, deserializeIslandProps, hydrateIslands, islandId, serializeIslandProps, unmountIslands };

package/dist/island-runtime.js

@@ -0,0 +1,73 @@
+import { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, IslandPropsError, deserializeIslandProps, islandId, serializeIslandProps } from "./islands/contract.js";
+
+//#region src/islands/runtime.ts
+const roots = /* @__PURE__ */ new WeakMap();
+async function hydrateIslands(options) {
+	const root = options.root ?? document;
+	const markers = Array.from(root.querySelectorAll(`[${ATTR_ISLAND_KEY}]`)).filter((element) => !roots.has(element));
+	if (markers.length === 0) return [];
+	const payloads = /* @__PURE__ */ new Map();
+	const duplicateIds = /* @__PURE__ */ new Set();
+	for (const script of root.querySelectorAll(`script[${ATTR_ISLAND_PROPS}]`)) {
+		const id = script.getAttribute(ATTR_ISLAND_PROPS);
+		if (id === null) continue;
+		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 handles = [];
+	for (const element of markers) {
+		const key = element.getAttribute("data-tr-island") ?? "";
+		const id = element.getAttribute("data-tr-island-id") ?? "";
+		const ctx = {
+			id,
+			key,
+			element
+		};
+		try {
+			if (duplicateIds.has(id)) throw new Error(`island "${id}" (${key}) shares its id with another ${ATTR_ISLAND_PROPS} payload — refusing to hydrate either instance rather than guess whose props belong to which marker`);
+			const payload = payloads.get(id);
+			if (payload === void 0) throw new Error(`island "${id}" (${key}) has no ${ATTR_ISLAND_PROPS} payload`);
+			const props = deserializeIslandProps(payload);
+			const module = await options.load(key);
+			ctx.editor = module.editor;
+			if (options.shouldHydrate && !options.shouldHydrate(ctx)) continue;
+			if (roots.has(element)) continue;
+			if (!element.isConnected) continue;
+			const reactRoot = hydrateRoot(element, createElement(module.default, props), {
+				onUncaughtError: (renderError) => {
+					options.onError?.(renderError, ctx);
+				},
+				onCaughtError: (renderError) => {
+					options.onError?.(renderError, ctx);
+				}
+			});
+			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);
+		}
+	}
+	return handles;
+}
+/**
+* Unmount every island hydrated under `root`. Synchronous, so the editor can call it
+* immediately before replacing a section's innerHTML.
+*/
+function unmountIslands(root = document) {
+	const self = root instanceof Element && root.matches(`[${"data-tr-island"}]`) ? [root] : [];
+	for (const element of [...self, ...root.querySelectorAll(`[${ATTR_ISLAND_KEY}]`)]) {
+		const reactRoot = roots.get(element);
+		if (!reactRoot) continue;
+		roots.delete(element);
+		reactRoot.unmount();
+	}
+}
+
+//#endregion
+export { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, IslandPropsError, deserializeIslandProps, hydrateIslands, islandId, serializeIslandProps, unmountIslands };

package/dist/islands/contract.d.ts

@@ -0,0 +1,56 @@
+import { ComponentType } from "react";
+//#region src/islands/contract.d.ts
+/** The custom element wrapping an island's server-rendered output. Layout-invisible (`display:contents`). */
+declare const ISLAND_ELEMENT = "tr-island";
+/** Island key on the marker: `<section-key>:<ComponentName>`, e.g. `spw-essential/floorplan:UnitFilter`. */
+declare const ATTR_ISLAND_KEY = "data-tr-island";
+/** Island id on the marker: unique in the document, stable across re-renders of the same island. */
+declare const ATTR_ISLAND_ID = "data-tr-island-id";
+/** On the JSON `<script>` sibling; its value is the island id of the marker the props belong to. */
+declare const ATTR_ISLAND_PROPS = "data-tr-island-props";
+/** Props handed from a server-rendered Renderer to a client component. Strictly JSON-serializable. */
+type IslandProps = Record<string, unknown>;
+/** How the editor sizes the transparent selection shield over a live island. */
+type ShieldMode = "fill-self" | "fill-parent";
+/** Optional `export const editor` on a client component: how it behaves inside the editor canvas. */
+interface IslandEditorOptions {
+  /** Hydrate this island in the editor canvas (behind the editor's selection gate). */
+  live?: boolean;
+  /** Shield placement. Default "fill-parent". */
+  shieldMode?: ShieldMode;
+  /** Which element(s) inside the island the shield covers. Omit → the whole island. Runs in the browser. */
+  liveSurface?: (root: HTMLElement) => HTMLElement[];
+  /** Editor-only props, merged over the server-rendered props (e.g. an accordion's single-open canvas mirror). */
+  props?: IslandProps;
+}
+/**
+ * A client component's own prop type is the author's business — island props are
+ * validated at runtime (serializeIslandProps), not through this alias, and a
+ * narrower type here would reject every real component through parameter
+ * contravariance.
+ */
+type IslandComponent = ComponentType<any>;
+/** The shape a `"use client"` module must have: a default-exported component, optionally `editor`. */
+interface IslandModule {
+  default: IslandComponent;
+  editor?: IslandEditorOptions;
+}
+/** A prop that cannot cross the server→browser boundary, or a payload that cannot be read back. */
+declare class IslandPropsError extends Error {
+  name: string;
+}
+/**
+ * Compose an island id. `scope` is the emitter's per-section-instance identity —
+ * without it, two instances of one section on a page collide.
+ */
+declare function islandId(scope: string, islandKey: string, ordinal: number): string;
+/**
+ * Validate + encode island props for the `<script type="application/json">` payload.
+ * Throws IslandPropsError naming the offending path. Every `<` is emitted as its
+ * unicode escape so a string value containing a closing script tag cannot break out.
+ */
+declare function serializeIslandProps(props: IslandProps): string;
+/** Read a props payload back. Throws IslandPropsError on anything that is not a JSON object. */
+declare function deserializeIslandProps(payload: string): IslandProps;
+//#endregion
+export { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, IslandComponent, IslandEditorOptions, IslandModule, IslandProps, IslandPropsError, ShieldMode, deserializeIslandProps, islandId, serializeIslandProps };

package/dist/islands/contract.js

@@ -0,0 +1,71 @@
+//#region src/islands/contract.ts
+/** The custom element wrapping an island's server-rendered output. Layout-invisible (`display:contents`). */
+const ISLAND_ELEMENT = "tr-island";
+/** Island key on the marker: `<section-key>:<ComponentName>`, e.g. `spw-essential/floorplan:UnitFilter`. */
+const ATTR_ISLAND_KEY = "data-tr-island";
+/** Island id on the marker: unique in the document, stable across re-renders of the same island. */
+const ATTR_ISLAND_ID = "data-tr-island-id";
+/** On the JSON `<script>` sibling; its value is the island id of the marker the props belong to. */
+const ATTR_ISLAND_PROPS = "data-tr-island-props";
+/** A prop that cannot cross the server→browser boundary, or a payload that cannot be read back. */
+var IslandPropsError = class extends Error {
+	name = "IslandPropsError";
+};
+/**
+* Compose an island id. `scope` is the emitter's per-section-instance identity —
+* without it, two instances of one section on a page collide.
+*/
+function islandId(scope, islandKey, ordinal) {
+	return `${scope}~${islandKey}#${ordinal}`;
+}
+const JSON_TYPES = /* @__PURE__ */ new Set([
+	"string",
+	"number",
+	"boolean",
+	"undefined"
+]);
+function assertSerializable(value, path) {
+	if (value === null) return;
+	const type = typeof value;
+	if (JSON_TYPES.has(type)) {
+		if (type === "number" && !Number.isFinite(value)) throw new IslandPropsError(`${path} is ${String(value)} — island props must be JSON-serializable, and JSON has no NaN or Infinity`);
+		return;
+	}
+	if (type !== "object") throw new IslandPropsError(`${path} is a ${type} — island props must be JSON-serializable (string, number, boolean, null, plain object, array)`);
+	if (Array.isArray(value)) {
+		value.forEach((entry, i) => {
+			assertSerializable(entry, `${path}[${i}]`);
+		});
+		return;
+	}
+	const proto = Object.getPrototypeOf(value);
+	if (proto !== Object.prototype && proto !== null) {
+		const ctor = value.constructor?.name ?? "class instance";
+		throw new IslandPropsError(`${path} is a ${ctor} — island props must be JSON-serializable (plain objects and arrays only)`);
+	}
+	for (const [key, entry] of Object.entries(value)) assertSerializable(entry, `${path}.${key}`);
+}
+/**
+* Validate + encode island props for the `<script type="application/json">` payload.
+* Throws IslandPropsError naming the offending path. Every `<` is emitted as its
+* unicode escape so a string value containing a closing script tag cannot break out.
+*/
+function serializeIslandProps(props) {
+	if (props === null || typeof props !== "object" || Array.isArray(props)) throw new IslandPropsError("props must be a plain object, not an array or a bare value");
+	assertSerializable(props, "props");
+	return JSON.stringify(props).replace(/</g, "\\u003c");
+}
+/** Read a props payload back. Throws IslandPropsError on anything that is not a JSON object. */
+function deserializeIslandProps(payload) {
+	let parsed;
+	try {
+		parsed = JSON.parse(payload);
+	} catch (cause) {
+		throw new IslandPropsError(`island props payload is not valid JSON: ${String(cause)}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new IslandPropsError("island props payload must be a JSON object");
+	return parsed;
+}
+
+//#endregion
+export { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, IslandPropsError, deserializeIslandProps, islandId, serializeIslandProps };

package/dist/islands/marker.d.ts

@@ -0,0 +1,16 @@
+import { IslandProps } from "./contract.js";
+import { ReactNode } from "react";
+//#region src/islands/marker.d.ts
+interface IslandMarkerProps {
+  /** `<section-key>:<ComponentName>` — the key the browser loader resolves the module by. */
+  islandKey: string;
+  /** Unique in the document, stable across re-renders of this island. Compose with `islandId()`. */
+  islandId: string;
+  /** Strictly JSON-serializable. A bad prop throws IslandPropsError here, at render time. */
+  props: IslandProps;
+  /** The client component, server-rendered. */
+  children: ReactNode;
+}
+declare function IslandMarker({ islandKey, islandId, props, children }: IslandMarkerProps): ReactNode;
+//#endregion
+export { IslandMarker, IslandMarkerProps };

package/dist/islands/marker.js

@@ -0,0 +1,18 @@
+import { ATTR_ISLAND_ID, ATTR_ISLAND_KEY, ATTR_ISLAND_PROPS, ISLAND_ELEMENT, serializeIslandProps } from "./contract.js";
+import { Fragment, createElement } from "react";
+
+//#region src/islands/marker.tsx
+function IslandMarker({ islandKey, islandId, props, children }) {
+	return createElement(Fragment, null, createElement(ISLAND_ELEMENT, {
+		style: { display: "contents" },
+		[ATTR_ISLAND_KEY]: islandKey,
+		[ATTR_ISLAND_ID]: islandId
+	}, children), createElement("script", {
+		type: "application/json",
+		[ATTR_ISLAND_PROPS]: islandId,
+		dangerouslySetInnerHTML: { __html: serializeIslandProps(props) }
+	}));
+}
+
+//#endregion
+export { IslandMarker };

package/dist/package.js

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

package/dist/primitives/Image.d.ts

@@ -0,0 +1,49 @@
+import { ResponsiveImage } from "../contracts/image-descriptor.js";
+import { ImgHTMLAttributes, ReactNode } from "react";
+//#region src/primitives/Image.d.ts
+type Props = Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt"> & {
+  /** Image URL. Null/empty in framed mode renders a fallback rect; in bare mode an empty <img>. */
+  src: string | null | undefined;
+  /** Required alt text. Empty string for decorative images. */
+  alt: string;
+  /** CSS aspect-ratio reserved on the framed wrapper; survives missing `src`. */
+  aspectRatio?: string;
+  /** Slot binding — emits `data-slot-id` on the wrapper for the editor click resolver. */
+  slotId?: string;
+  /** Escape hatch — a bare <img>, no wrapper. Requires a `// bare:` reason comment at the call site. */
+  bare?: boolean;
+  /** Legacy single-URL mobile crop (no responsive descriptor). Composes with `mobileBreakpoint`. */
+  srcMobile?: string | null;
+  /** Desktop↔mobile switch width (px); the `<picture>` mobile source uses `max-width: breakpoint − 1`. */
+  mobileBreakpoint?: number;
+  /** Desktop responsive descriptor (ImageValue.responsive). Absent ⇒ today's single <img src>. */
+  responsive?: ResponsiveImage | null;
+  /** Mobile-crop descriptor (ImageValue.mobile.responsive); composes with `mobileBreakpoint`. */
+  responsiveMobile?: ResponsiveImage | null;
+  /** Slot `sizes` (e.g. "(min-width:1024px) 1200px, 100vw"); applied to every srcset candidate. */
+  sizes?: string;
+  /** Per-section srcset ceiling (px). Rungs wider than this are dropped (≥1 always kept). */
+  maxRungWidth?: number;
+};
+/**
+ * Image — the defensive image primitive. Sections never write a raw `<img>`.
+ *
+ * **Framed mode** (default): a wrapper div carries the `data-slot-id` marker, holds
+ * the optional aspect-ratio box, renders a neutral fallback rect when `src` is empty,
+ * and absolutely-positions the inner `<img>` with `object-cover`. Cropping is handled
+ * upstream — the platform delivers a pre-cropped asset — so the image is simply
+ * centered here.
+ *
+ * **Bare mode** (`bare`): a single `<img>`, no wrapper. For chrome images whose parent
+ * already establishes the layout box (a logo with `object-contain`; a slide inside its
+ * own aspect-ratio parent). An escape hatch — it forfeits the empty-state box.
+ *
+ * **Responsive:** given a `responsive` descriptor, the `<img>` is wrapped in `<picture>`
+ * with per-format AVIF/WebP `<source srcset>` — plus a media-gated mobile crop when
+ * `responsiveMobile` is set — and carries `sizes` and intrinsic `width`/`height`. With
+ * 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;
+//#endregion
+export { Image };

package/dist/primitives/Image.js

@@ -0,0 +1,95 @@
+import { ATTR_SLOT_ID } from "../contracts/markers.js";
+import { buildPictureSources } from "./picture-sources.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/primitives/Image.tsx
+/**
+* Image — the defensive image primitive. Sections never write a raw `<img>`.
+*
+* **Framed mode** (default): a wrapper div carries the `data-slot-id` marker, holds
+* the optional aspect-ratio box, renders a neutral fallback rect when `src` is empty,
+* and absolutely-positions the inner `<img>` with `object-cover`. Cropping is handled
+* upstream — the platform delivers a pre-cropped asset — so the image is simply
+* centered here.
+*
+* **Bare mode** (`bare`): a single `<img>`, no wrapper. For chrome images whose parent
+* already establishes the layout box (a logo with `object-contain`; a slide inside its
+* own aspect-ratio parent). An escape hatch — it forfeits the empty-state box.
+*
+* **Responsive:** given a `responsive` descriptor, the `<img>` is wrapped in `<picture>`
+* with per-format AVIF/WebP `<source srcset>` — plus a media-gated mobile crop when
+* `responsiveMobile` is set — and carries `sizes` and intrinsic `width`/`height`. With
+* no descriptor it degrades to a plain single `<img src>`. All `<picture>` planning
+* lives in `buildPictureSources`.
+*/
+function Image({ src, alt, aspectRatio, slotId, bare, srcMobile, mobileBreakpoint, responsive, responsiveMobile, sizes, maxRungWidth, className, loading, style, ...rest }) {
+	const plan = responsive ? buildPictureSources({
+		responsive,
+		responsiveMobile,
+		sizes,
+		maxRungWidth,
+		mobileBreakpoint
+	}) : null;
+	const hasResponsive = Boolean(plan && (plan.imgSrcSet || plan.sources.length > 0));
+	const usePicture = Boolean(src && srcMobile && mobileBreakpoint) && !hasResponsive;
+	const mobileMedia = mobileBreakpoint ? `(max-width: ${mobileBreakpoint - 1}px)` : void 0;
+	const responsiveImgAttrs = hasResponsive ? {
+		srcSet: plan.imgSrcSet,
+		sizes: plan.imgSizes,
+		width: plan.width,
+		height: plan.height
+	} : {};
+	function wrap(imgEl) {
+		if (hasResponsive && plan.sources.length > 0) return /* @__PURE__ */ jsxs("picture", { children: [plan.sources.map((s, i) => /* @__PURE__ */ jsx("source", {
+			type: s.type,
+			media: s.media,
+			srcSet: s.srcSet,
+			sizes: s.sizes
+		}, i)), imgEl] });
+		if (usePicture) return /* @__PURE__ */ jsxs("picture", { children: [/* @__PURE__ */ jsx("source", {
+			media: mobileMedia,
+			srcSet: srcMobile ?? void 0
+		}), imgEl] });
+		return imgEl;
+	}
+	if (bare) {
+		const cls = ["w-full", className].filter(Boolean).join(" ");
+		return wrap(/* @__PURE__ */ jsx("img", {
+			src: src ?? "",
+			alt,
+			loading: loading ?? "lazy",
+			className: cls,
+			style,
+			...rest,
+			...responsiveImgAttrs
+		}));
+	}
+	const containerCls = ["tr-image-frame relative block w-full overflow-hidden bg-surface-alt", 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
+	});
+	const img = /* @__PURE__ */ jsx("img", {
+		src,
+		alt,
+		loading: loading ?? "lazy",
+		decoding: "async",
+		className: "absolute inset-0 h-full w-full object-cover",
+		...rest,
+		...responsiveImgAttrs
+	});
+	return /* @__PURE__ */ jsx("div", {
+		className: containerCls,
+		style: containerStyle,
+		...slotAttrs,
+		children: wrap(img)
+	});
+}
+
+//#endregion
+export { Image };

package/dist/primitives/Section.d.ts

@@ -0,0 +1,22 @@
+import { HTMLAttributes, ReactNode } from "react";
+//#region src/primitives/Section.d.ts
+type Props = HTMLAttributes<HTMLElement> & {
+  as?: "section" | "div" | "article" | "header" | "footer" | "aside";
+  children: ReactNode;
+};
+/**
+ * The section root. Every section renderer roots at exactly one `<Section>`.
+ *
+ * Full-bleed by contract: 100% width with zero padding and margin (`.tr-section`,
+ * from the kit's base stylesheet), so consecutive sections butt edge-to-edge and a
+ * page composes as a vertical stack with no framework-injected whitespace. Vertical
+ * separation is the section's own job — a background, padding on a child element —
+ * never padding on this root, which would re-introduce gaps between sections and
+ * shrink the section's full-bleed background.
+ *
+ * When content needs a centered, max-width well, write it as JSX on a child:
+ * `w-full max-w-[var(--tr-container-max)] mx-auto px-[var(--tr-container-pad)]`.
+ */
+declare function Section({ as, children, className, ...rest }: Props): import("react").JSX.Element;
+//#endregion
+export { Section };

package/dist/primitives/Section.js

@@ -0,0 +1,26 @@
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/Section.tsx
+/**
+* The section root. Every section renderer roots at exactly one `<Section>`.
+*
+* Full-bleed by contract: 100% width with zero padding and margin (`.tr-section`,
+* from the kit's base stylesheet), so consecutive sections butt edge-to-edge and a
+* page composes as a vertical stack with no framework-injected whitespace. Vertical
+* separation is the section's own job — a background, padding on a child element —
+* never padding on this root, which would re-introduce gaps between sections and
+* shrink the section's full-bleed background.
+*
+* When content needs a centered, max-width well, write it as JSX on a child:
+* `w-full max-w-[var(--tr-container-max)] mx-auto px-[var(--tr-container-pad)]`.
+*/
+function Section({ as = "section", children, className, ...rest }) {
+	return /* @__PURE__ */ jsx(as, {
+		className: ["tr-section", className].filter(Boolean).join(" "),
+		...rest,
+		children
+	});
+}
+
+//#endregion
+export { Section };

package/dist/primitives/Slot.d.ts

@@ -0,0 +1,50 @@
+import { ElementType, HTMLAttributes, ReactNode } from "react";
+//#region src/primitives/Slot.d.ts
+type SlotProps = HTMLAttributes<HTMLElement> & {
+  /**
+   * Slot id from the section schema. Emitted as `data-slot-id` on the
+   * rendered element so the editor's click resolver can target the slot.
+   */
+  id: string;
+  /**
+   * Element to render. Defaults to `"div"`. Override when the slot's
+   * surrounding semantic role needs something else (`address`, `span`,
+   * `nav`, …).
+   */
+  as?: ElementType;
+  /**
+   * For a `text` slot rendered as a single leaf: applies `data-slot-text-leaf`
+   * to the immediate child element via `cloneElement`, so the editor's
+   * optimistic patcher can write `textContent` on every keystroke. Without it
+   * the canvas only updates once the server re-renders, and typing feels laggy.
+   *
+   * A slot with several text-bearing elements (a multi-line address, one leaf
+   * per line) marks its leaves manually inside this wrapper — `textLeaf` only
+   * handles the common single-child case.
+   *
+   * When `textLeaf` is true but the child isn't a single element (raw text, a
+   * fragment, several children), this prop is a no-op and the slot still emits
+   * its outer `data-slot-id`.
+   */
+  textLeaf?: boolean;
+  /**
+   * Optional. The wrapper still emits its `data-slot-id` when empty — which is
+   * what makes the empty-shell fallback (fill produced nothing) still selectable.
+   */
+  children?: ReactNode;
+};
+/**
+ * Slot — the canonical wrapper for an editable slot's DOM boundary.
+ *
+ * Wrap each editable slot's outer DOM in `<Slot id="…">`. It emits `data-slot-id`,
+ * which is how the editor resolves a click in the preview back to the slot the user
+ * meant. A slot with no marker in the DOM cannot be selected or edited.
+ *
+ * A primitive with a natural single root for its slot type takes a `slotId` prop and
+ * emits the marker on its own root instead — `<Image slotId="hero_image">` needs no
+ * `<Slot>` wrapper. `<Slot>` is for everything else: text slots, source-bound scalars
+ * rendered as raw spans, and any slot whose markup is a hand-assembled composition.
+ */
+declare function Slot({ id, as, textLeaf, children, ...rest }: SlotProps): ReactNode;
+//#endregion
+export { Slot };