camox 0.46.0 → 0.48.0

package/dist/core/lib/contentType.d.ts

@@ -1,3 +1,4 @@
+import { BlockStructuredData, KnownNodesOnly, RepeatedNodes } from "../structuredData.js";
 import { Collection } from "../createCollection.js";
 import { IconId, IconValue } from "./iconTypes.js";
 import { SystemOrderKey } from "@camox/api-contract";
@@ -61,7 +62,75 @@ export type ContentProxy<TShape extends Record<string, TSchema>> = { [K in keyof
  */
 type SettingCallable<T extends TSchema> = Static<T> extends boolean ? (lines: ConditionalLines) => Conditional : Static<T> extends string ? (value: Static<T>, lines: ConditionalLines) => Conditional : never;
 export type SettingsProxy<TShape extends Record<string, TSchema>> = { [K in keyof TShape & string]: SettingCallable<TShape[K]>; };
-export type ToMarkdownBuilder<TContent extends Record<string, TSchema>, TSettings extends Record<string, TSchema> = Record<string, never>> = (c: ContentProxy<TContent>, s: SettingsProxy<TSettings>) => ReadonlyArray<string | FieldToken | Conditional>;
+/** What a block's or repeatable item's templates receive: proxies of its content and settings. */
+export interface TemplateContext<TContent extends Record<string, TSchema>, TSettings extends Record<string, TSchema> = Record<string, never>> {
+  content: ContentProxy<TContent>;
+  settings: SettingsProxy<TSettings>;
+}
+/** Builds a Markdown template from `{ content, settings }`. */
+export type ToMarkdownBuilder<TContent extends Record<string, TSchema>, TSettings extends Record<string, TSchema> = Record<string, never>> = (context: TemplateContext<TContent, TSettings>) => ReadonlyArray<string | FieldToken | Conditional>;
+/** A collection's String fields as field tokens: what its record templates can name. */
+export type RecordTextProxy<TShape extends Record<string, TSchema>> = { [K in keyof TShape & string as TShape[K] extends {
+  fieldType: "String";
+} ? K : never]: string & FieldToken; };
+/** What a collection's `toTitle` and `toDescription` receive: the record's String fields. */
+export interface RecordTemplateContext<TShape extends Record<string, TSchema>> {
+  content: RecordTextProxy<TShape>;
+}
+/**
+ * Builds a title template from `{ content, settings }`: one line naming a block or repeatable item
+ * until it has a Summary, such as its headline. The API evaluates it on default-locale content.
+ */
+export type ToTitleBuilder<TContent extends Record<string, TSchema>, TSettings extends Record<string, TSchema> = Record<string, never>> = (context: TemplateContext<TContent, TSettings>) => string | FieldToken;
+/**
+ * An image field's token in a Structured Data template, which the API evaluates into an
+ * `ImageObject` with its absolute URL, dimensions and alt text.
+ */
+export type ImageToken = {
+  "@type": "ImageObject";
+  url: string;
+  contentUrl: string;
+};
+/**
+ * A reference's token in a Structured Data template: a link to the record's node, which Camox
+ * adds to the page's graph, or the record's title when its collection has no `toStructuredData`.
+ */
+export type RecordToken = {
+  readonly "@id": string;
+};
+/**
+ * What a field reads as in a Structured Data template. Text, files, links and embeds read as
+ * strings, links and files as absolute URLs. References link their records' nodes, and their
+ * fields read as the record's. Icons, artifacts and lists of files aren't Structured Data.
+ */
+type StructuredDataToken<T extends TSchema> = T extends ReferenceSchema<infer R> ? RecordToken & StructuredDataProxy<R> : T extends ReferenceListSchema<any> ? RecordToken[] : T extends {
+  fieldType: "Artifact";
+} ? never : T extends TArray<TObject<any>> ? RepeatedNodes : T extends TArray<any> ? never : Static<T> extends IconValue ? never : Static<T> extends ImageValue ? ImageToken : Static<T> extends string | LinkValue | FileValue ? string & FieldToken : never;
+/** A block's or repeatable item's fields as a Structured Data template reads them. */
+export type StructuredDataProxy<TShape extends Record<string, TSchema>> = { [K in keyof TShape & string as [StructuredDataToken<TShape[K]>] extends [never] ? never : K]: StructuredDataToken<TShape[K]>; };
+/**
+ * One setting in a Structured Data template: shows a part of the template only while it holds,
+ * typed as the part it shows. A Boolean takes the part; an Enum takes the option it must equal,
+ * then the part. Settings of other shapes aren't conditions.
+ */
+type StructuredDataSettingCallable<T extends TSchema> = Static<T> extends boolean ? <const V>(value: V) => V : Static<T> extends string ? <const V>(equals: Static<T>, value: V) => V : never;
+/** A block's or repeatable item's settings, as its Structured Data template reads them. */
+export type StructuredDataSettingsProxy<TShape extends Record<string, TSchema>> = { [K in keyof TShape & string]: StructuredDataSettingCallable<TShape[K]>; };
+/** What a block's or repeatable item's `toStructuredData` receives. */
+export interface StructuredDataContext<TContent extends Record<string, TSchema>, TSettings extends Record<string, TSchema> = Record<string, never>> {
+  content: StructuredDataProxy<TContent>;
+  settings: StructuredDataSettingsProxy<TSettings>;
+}
+/**
+ * Builds a block's or repeatable item's Structured Data template from `{ content, settings }`:
+ * the nodes it shows. A repeater's token places its items' nodes. The API evaluates the
+ * template on each page's content, and Camox links each node to its page.
+ */
+export type ToStructuredDataBuilder<TContent extends Record<string, TSchema>, TSettings extends Record<string, TSchema>, Nodes extends BlockStructuredData> = (context: StructuredDataContext<TContent, TSettings>) => Nodes & KnownNodesOnly<Nodes>;
+/** What a collection's `toStructuredData` receives: the record's fields as tokens. */
+export interface RecordStructuredDataContext<TShape extends Record<string, TSchema>> {
+  content: StructuredDataProxy<TShape>;
+}
 declare const EmbedURLBrand: unique symbol;
 export type EmbedURL = string & {
   readonly [EmbedURLBrand]: true;
@@ -269,7 +338,7 @@ export interface ContentFieldBuilder {
    * cannot pick, remove or reorder records, and nothing is stored on the block.
    *
    * @example
-   * field.referenceList(customers, { maxItems: 6, toMarkdown: (c) => [c.name] })
+   * field.referenceList(customers, { maxItems: 6, toMarkdown: ({ content }) => [content.name] })
    * field.referenceList(articles, { query: { orderBy: { publishedAt: "desc" }, limit: 3 } })
    */
   referenceList: <T extends Record<string, TSchema>, const L extends number = number>(collection: Collection<T>, options?: {
@@ -295,16 +364,34 @@ export interface ContentFieldBuilder {
    *   minItems: 1,
    *   maxItems: 10,
    *   title: "Items",
-   *   toMarkdown: (c, s) => [`### ${c.title}`, s.highlighted(c.description)],
+   *   toTitle: ({ content }) => content.title,
+   *   toMarkdown: ({ content, settings }) => [
+   *     `### ${content.title}`,
+   *     settings.highlighted(content.description),
+   *   ],
    * })
    */
-  repeater: <T extends Record<string, TSchema>, S extends Record<string, TSchema> = Record<string, never>>(options: {
+  repeater: <T extends Record<string, TSchema>, S extends Record<string, TSchema> = Record<string, never>, N extends BlockStructuredData = BlockStructuredData>(options: {
     content: (field: ContentFieldBuilder) => T & NoInfer<ArtifactDataCheck<T, S>>;
     settings?: (setting: SettingBuilder) => S;
     minItems: number;
     maxItems: number;
     title?: string;
+    /** Names each item until it has a Summary, such as its title. See `ToTitleBuilder`. */
+    toTitle: ToTitleBuilder<T, S>;
     toMarkdown: ToMarkdownBuilder<T, S>;
+    /**
+     * The nodes each item shows, placed wherever the parent's template places the repeater's
+     * token. See `ToStructuredDataBuilder`.
+     *
+     * @example
+     * toStructuredData: ({ content }) => ({
+     *   "@type": "Question",
+     *   name: content.question,
+     *   acceptedAnswer: { "@type": "Answer", text: content.answer },
+     * })
+     */
+    toStructuredData?: ToStructuredDataBuilder<T, S, N>;
   }) => RepeaterField<T, S>;
 }
 /** Content fields that can't be Artifact Data: artifact sources, repeaters and references. */

package/dist/core/lib/contentType.js

@@ -48,10 +48,21 @@ function createContentProxy(shape, prefix = "") {
 		if (typeof prop !== "string") return void 0;
 		const path = prefix ? `${prefix}.${prop}` : prop;
 		const field = shape?.[prop];
-		if (field?.fieldType === "Reference") return createContentProxy(field.referenceSchema.properties, path);
+		if (field?.fieldType === "Reference") return referenceToken(field.referenceSchema.properties, path);
 		return new FieldToken(path);
 	} });
 }
+/**
+* A reference field's token, which names the reference itself, as Structured Data templates
+* link records by it, and whose properties are the tokens of the record's fields.
+*/
+function referenceToken(shape, path) {
+	const fields = createContentProxy(shape, path);
+	return new Proxy(new FieldToken(path), { get(target, prop, receiver) {
+		if (typeof prop !== "string" || prop in target) return Reflect.get(target, prop, receiver);
+		return fields[prop];
+	} });
+}
 function createSettingsProxy(settingsShape, scope) {
 	return new Proxy({}, { get(_target, prop) {
 		if (typeof prop !== "string") return void 0;
@@ -69,12 +80,78 @@ function serializeConditional(cond) {
 	return out;
 }
 function resolveToMarkdown(builder, settingsShape, scope, contentShape) {
-	const entries = builder(createContentProxy(contentShape), createSettingsProxy(settingsShape, scope));
+	const entries = builder({
+		content: createContentProxy(contentShape),
+		settings: createSettingsProxy(settingsShape, scope)
+	});
 	const out = [];
 	for (const entry of entries) if (entry instanceof Conditional) out.push(...serializeConditional(entry));
 	else out.push(entry instanceof FieldToken ? entry.toString() : String(entry));
 	return out;
 }
+/**
+* Runs a collection's record template, such as `toTitle`, into the token template the API fills
+* with each record's plain text. Null when it returns nothing.
+*/
+function resolveRecordTemplate(template, contentShape) {
+	const result = template({ content: createContentProxy(contentShape) });
+	return result === void 0 || result === null || String(result) === "" ? null : String(result);
+}
+/** The one-line title template a `toTitle` builder declares. */
+function resolveToTitle(builder, settingsShape, scope, contentShape) {
+	const content = createContentProxy(contentShape);
+	const settings = createSettingsProxy(settingsShape, scope);
+	return String(builder({
+		content,
+		settings
+	}));
+}
+/** A part of a Structured Data template shown only while a setting holds. */
+var SettingCondition = class {
+	scope;
+	settingName;
+	equals;
+	show;
+	constructor(scope, settingName, equals, show) {
+		this.scope = scope;
+		this.settingName = settingName;
+		this.equals = equals;
+		this.show = show;
+	}
+};
+function createStructuredDataSettingsProxy(settingsShape, scope) {
+	return new Proxy({}, { get(_target, prop) {
+		if (typeof prop !== "string") return void 0;
+		const fieldType = (settingsShape?.[prop])?.fieldType;
+		if (fieldType === "Boolean") return (value) => new SettingCondition(scope, prop, null, value);
+		if (fieldType === "Enum") return (equals, value) => new SettingCondition(scope, prop, equals, value);
+		throw new Error(`toStructuredData settings proxy: "${prop}" is not a Boolean or Enum setting on this ${scope}.`);
+	} });
+}
+/** A template's value as the Definition Set syncs it: JSON, with tokens as `{{field}}`. */
+function serializeTemplate(value) {
+	if (value instanceof FieldToken) return value.toString();
+	if (value instanceof SettingCondition) return {
+		"@camox": "if",
+		setting: `${value.scope === "block" ? "settings" : "itemSettings"}.${value.settingName}`,
+		...value.equals !== null && { equals: value.equals },
+		show: serializeTemplate(value.show)
+	};
+	if (Array.isArray(value)) return value.map(serializeTemplate);
+	if (typeof value === "object" && value !== null) return Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => entry === void 0 ? [] : [[key, serializeTemplate(entry)]]));
+	return value;
+}
+/** The Structured Data template a `toStructuredData` builder declares. */
+function resolveToStructuredData(builder, settingsShape, scope, contentShape) {
+	return serializeTemplate(builder({
+		content: createContentProxy(contentShape),
+		settings: createStructuredDataSettingsProxy(settingsShape, scope)
+	}));
+}
+/** The Structured Data template of each record of a collection, as its builder declares it. */
+function resolveRecordStructuredData(builder, contentShape) {
+	return serializeTemplate(builder({ content: createContentProxy(contentShape) }));
+}
 /** The longest artifact source content writes accept (256 KB). */
 const ARTIFACT_MAX_LENGTH = 262144;
 const IMAGE_PLACEHOLDER = Symbol("camox.imagePlaceholder");
@@ -259,8 +336,7 @@ const contentFieldBuilder = {
 		required: options.required ?? false,
 		title: options.title ?? collection._internal.title,
 		default: null,
-		referenceSchema: collection._internal.contentSchema,
-		labelField: collection._internal.label
+		referenceSchema: collection._internal.contentSchema
 	}),
 	referenceList: (collection, options = {}) => Type.Unsafe({
 		type: "array",
@@ -275,8 +351,7 @@ const contentFieldBuilder = {
 		...options.maxItems === void 0 ? {} : { maxItems: options.maxItems },
 		...options.query === void 0 ? { default: [] } : { query: validateQuery(options.query, collection) },
 		...options.toMarkdown === void 0 ? {} : { toMarkdown: resolveToMarkdown(options.toMarkdown, void 0, "item", collection._internal.contentSchema.properties) },
-		referenceSchema: collection._internal.contentSchema,
-		labelField: collection._internal.label
+		referenceSchema: collection._internal.contentSchema
 	}),
 	repeater: (options) => {
 		if (options.minItems < 1) throw new Error("Repeater requires minItems to be at least 1");
@@ -301,7 +376,9 @@ const contentFieldBuilder = {
 			default: defaultArray,
 			title: options.title,
 			fieldType: "Repeater",
+			toTitle: resolveToTitle(options.toTitle, settings, "item", content),
 			toMarkdown: resolveToMarkdown(options.toMarkdown, settings, "item", content),
+			...options.toStructuredData && { toStructuredData: resolveToStructuredData(options.toStructuredData, settings, "item", content) },
 			itemSettingsSchema,
 			defaultItemSettings: settingsObjectSchema ? collectSchemaDefaults(settingsObjectSchema.properties) : void 0
 		});
@@ -344,4 +421,4 @@ function resolveBlockFields(options) {
 }
 
 //#endregion
-export { ARTIFACT_MAX_LENGTH, Conditional, FieldToken, assertFieldKinds, collectionField, collectionFieldBuilder, contentFieldBuilder, getImagePlaceholderTitle, isImagePlaceholder, resolveBlockFields, resolveToMarkdown, settingBuilder };
+export { ARTIFACT_MAX_LENGTH, Conditional, FieldToken, assertFieldKinds, collectionField, collectionFieldBuilder, contentFieldBuilder, getImagePlaceholderTitle, isImagePlaceholder, resolveBlockFields, resolveRecordStructuredData, resolveRecordTemplate, resolveToMarkdown, resolveToStructuredData, resolveToTitle, settingBuilder };

package/dist/core/lib/recordScope.js

@@ -250,7 +250,7 @@ const ReferenceList = (t0) => {
 * (the second hop), which link nothing further.
 */
 function RecordScope(t0) {
-	const $ = c(14);
+	const $ = c(15);
 	const { record, properties, hop, children } = t0;
 	let t1;
 	if ($[0] !== properties || $[1] !== record.content) {
@@ -265,10 +265,11 @@ function RecordScope(t0) {
 	const value = t1;
 	const t2 = hop === 1 ? record.references : void 0;
 	let t3;
-	if ($[3] !== children || $[4] !== hop || $[5] !== record.id || $[6] !== record.label) {
+	if ($[3] !== children || $[4] !== hop || $[5] !== record.description || $[6] !== record.id || $[7] !== record.title) {
 		t3 = children({
 			id: record.id,
-			label: record.label,
+			title: record.title,
+			description: record.description,
 			Field,
 			Image,
 			File,
@@ -282,30 +283,31 @@ function RecordScope(t0) {
 		});
 		$[3] = children;
 		$[4] = hop;
-		$[5] = record.id;
-		$[6] = record.label;
-		$[7] = t3;
-	} else t3 = $[7];
+		$[5] = record.description;
+		$[6] = record.id;
+		$[7] = record.title;
+		$[8] = t3;
+	} else t3 = $[8];
 	let t4;
-	if ($[8] !== t2 || $[9] !== t3) {
+	if ($[9] !== t2 || $[10] !== t3) {
 		t4 = /* @__PURE__ */ jsx(LinksContext.Provider, {
 			value: t2,
 			children: t3
 		});
-		$[8] = t2;
-		$[9] = t3;
-		$[10] = t4;
-	} else t4 = $[10];
+		$[9] = t2;
+		$[10] = t3;
+		$[11] = t4;
+	} else t4 = $[11];
 	let t5;
-	if ($[11] !== t4 || $[12] !== value) {
+	if ($[12] !== t4 || $[13] !== value) {
 		t5 = /* @__PURE__ */ jsx(RecordContext.Provider, {
 			value,
 			children: t4
 		});
-		$[11] = t4;
-		$[12] = value;
-		$[13] = t5;
-	} else t5 = $[13];
+		$[12] = t4;
+		$[13] = value;
+		$[14] = t5;
+	} else t5 = $[14];
 	return t5;
 }
 function _temp(location) {

package/dist/core/lib/reference.d.ts

@@ -29,7 +29,10 @@ type LinkedRecords<T extends Record<string, TSchema>> = {
 };
 type RecordFields<T extends Record<string, TSchema>> = {
   id: string;
-  label: string;
+  /** The record's title, from its collection's `toTitle`. */
+  title: string;
+  /** The record's description, from its collection's `toDescription`, or null for none. */
+  description: string | null;
   Field: (props: InlineTextStyles & {
     name: TextKeys<T>;
     children: (props: React.HTMLAttributes<HTMLElement> & {
@@ -70,7 +73,8 @@ export type ReferenceContent<T extends TSchema> = T extends ReferenceSchema<infe
 export type ReferenceRecord = {
   id: string;
   collectionId: string;
-  label: string;
+  title: string;
+  description: string | null;
   content: Record<string, unknown>;
   /** When its content last changed, for a record page's record. */
   updatedAt?: number;

package/dist/core/recordItem.js

@@ -1,5 +1,6 @@
 import { resolveToMarkdown } from "./lib/contentType.js";
 import { isLexicalState, lexicalStateToPlainText } from "./lib/lexicalState.js";
+import { recordLink, recordText, templateFields } from "@camox/api-contract";
 
 //#region src/core/recordItem.ts
 /**
@@ -17,6 +18,58 @@ function recordPlainText(collection, content) {
 	for (const [name, field] of Object.entries(properties)) if (field.fieldType === "String") text[name] = fieldPlainText(content[name]);
 	return text;
 }
+/**
+* A record's references as links to their records' nodes: one for a reference, which is absent
+* when it resolves to nothing, and a list for a reference list.
+*/
+function recordLinks(collection, references) {
+	const properties = collection._internal.contentSchema.properties;
+	const links = {};
+	for (const [name, field] of Object.entries(properties)) {
+		const resolved = references?.[name];
+		if (field.fieldType === "ReferenceList") links[name] = (Array.isArray(resolved) ? resolved : []).map(({ id }) => recordLink(id));
+		if (field.fieldType === "Reference" && resolved && !Array.isArray(resolved)) links[name] = recordLink(resolved.id);
+	}
+	return links;
+}
+/** The titles of the records a record references, by record id. */
+function referencedTitles(references) {
+	return Object.fromEntries(Object.values(references ?? {}).flatMap((value) => [value ?? []].flat()).map((record) => [record.id, record.title]));
+}
+/**
+* The record a record page renders, as its layout's context names it, from the record a loader
+* found and when it was published to Live.
+*/
+function recordPageValues(collection, { data: record, published }) {
+	return {
+		title: record.title ?? "",
+		description: record.description ?? void 0,
+		content: {
+			...recordLinks(collection, record.references),
+			...recordPlainText(collection, record.content)
+		},
+		titles: referencedTitles(record.references),
+		...published && { published }
+	};
+}
+/**
+* A record's title and description: its collection's templates filled with its fields' plain
+* text, as the API fills them. For records edited here, before the API names them again.
+*/
+function recordText$1(collection, content) {
+	if (!collection) return {
+		title: "",
+		description: null
+	};
+	return recordText(collection._internal, (name) => fieldPlainText(content[name]));
+}
+/**
+* The first field a collection's title template names, such as `firstName` in
+* `{{firstName}} {{lastName}}`: where a new record's name goes.
+*/
+function titleField(toTitle) {
+	return templateFields(toTitle)[0];
+}
 /** A String field's text, whether it is stored as plain text or rich-text state. */
 function fieldPlainText(value) {
 	if (typeof value !== "string" && !isLexicalState(value)) return "";
@@ -27,8 +80,8 @@ function fieldPlainText(value) {
 * field tokens are left for the API to fill with the live record.
 */
 function recordMarkdownTemplate(collection, toMarkdown) {
-	return resolveToMarkdown((item) => toMarkdown(item), void 0, "item", collection._internal.contentSchema.properties);
+	return resolveToMarkdown(({ content }) => toMarkdown(content), void 0, "item", collection._internal.contentSchema.properties);
 }
 
 //#endregion
-export { asCollectionItem, fieldPlainText, recordMarkdownTemplate, recordPlainText };
+export { asCollectionItem, fieldPlainText, recordMarkdownTemplate, recordPageValues, recordPlainText, recordText$1 as recordText, titleField };

package/dist/core/requestContext.d.ts

@@ -1,4 +1,5 @@
 import { ReferenceRecord } from "./lib/reference.js";
+import { EvaluatedNode, RecordStructuredData } from "@camox/api-contract";
 //#region src/core/requestContext.d.ts
 declare const requestContextBrand: unique symbol;
 /**
@@ -16,11 +17,28 @@ export interface CollectionRecordId {
 /** A collection record as a record page loads it. */
 export interface LoadedRecord<Content = Record<string, unknown>> {
   id: string;
+  /** Its title, as the API evaluates its collection's `toTitle`. */
+  title?: string;
+  /** Its description, as the API evaluates its collection's `toDescription`: null for none. */
+  description?: string | null;
   content: Content;
   /** The records it links, resolved by Camox with the record as the first hop. */
   references?: ReferenceRecord["references"];
   /** When its content last changed. */
   updatedAt?: number;
+  /** When it was first and last published to Live. Absent from older APIs. */
+  firstPublishedAt?: number | null;
+  publishedAt?: number | null;
+  /** Its Structured Data, as the API evaluates it. Absent from older APIs. */
+  structuredData?: RecordPageStructuredData;
+}
+/**
+ * A record page's record as Structured Data: its node, when its collection has a template, and
+ * the nodes of the records it references and of those they link.
+ */
+export interface RecordPageStructuredData {
+  node?: EvaluatedNode;
+  records: RecordStructuredData;
 }
 //#endregion
 export {};

package/dist/core/structuredData.d.ts

@@ -0,0 +1,126 @@
+import { ARTICLE_TYPES } from "@camox/api-contract";
+import { AggregateRatingSimple, ArticleSimple, BookSimple, CourseSimple, EventSimple, HowToSimple, ImageSimple, JobPostingSimple, OfferSimple, OrganizationSimple, PersonSimple, PlaceSimple, ProductSimple, QuestionSimple, RecipeSimple, ReviewSimple, ServiceSimple, SoftwareAppSimple, VideoSimple, WebPageSimple } from "@unhead/schema-org";
+//#region src/core/structuredData.d.ts
+export type ArticleType = (typeof ARTICLE_TYPES)[number];
+/** The kinds of web page a layout can say its pages are. */
+export declare const WEB_PAGE_TYPES: readonly ["AboutPage", "CheckoutPage", "CollectionPage", "ContactPage", "FAQPage", "ItemPage", "MedicalWebPage", "ProfilePage", "QAPage", "RealEstateListing", "SearchResultsPage"];
+export type WebPageType = (typeof WEB_PAGE_TYPES)[number];
+/** A type's own properties, without the index signature that would let any key through. */
+type Known<T> = T extends unknown ? { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; } : never;
+/** The given properties of a type, required. */
+type Need<T, K extends keyof Known<T>> = { [P in K]-?: Exclude<Known<T>[P], undefined>; };
+/** Each curated `@type`, with the node whose properties it takes. */
+type NodeProperties = { [T in ArticleType]: ArticleSimple; } & {
+  Product: ProductSimple;
+  Offer: OfferSimple;
+  Event: EventSimple;
+  Person: PersonSimple;
+  Place: PlaceSimple;
+  Organization: OrganizationSimple;
+  Review: ReviewSimple;
+  AggregateRating: AggregateRatingSimple;
+  Question: QuestionSimple;
+  HowTo: HowToSimple;
+  Recipe: RecipeSimple;
+  Course: CourseSimple;
+  JobPosting: JobPostingSimple;
+  SoftwareApplication: SoftwareAppSimple;
+  VideoObject: VideoSimple;
+  ImageObject: ImageSimple;
+  Book: BookSimple;
+  Service: ServiceSimple;
+};
+/** Every `@type` a definition's nodes can have. */
+export type StructuredDataType = keyof NodeProperties;
+/** What search engines require of each type, including what Camox may fill in. */
+type NodeRequirements = { [T in ArticleType]: Need<ArticleSimple, "headline">; } & {
+  Product: Need<ProductSimple, "name"> & (Need<ProductSimple, "offers"> | Need<ProductSimple, "review"> | Need<ProductSimple, "aggregateRating">);
+  Offer: {
+    price: number | string;
+    priceCurrency: string;
+  };
+  Event: Need<EventSimple, "name" | "startDate" | "location">;
+  Person: Need<PersonSimple, "name">;
+  Place: Need<PlaceSimple, "name">;
+  Organization: Need<OrganizationSimple, "name">;
+  Review: Need<ReviewSimple, "author">;
+  AggregateRating: Need<AggregateRatingSimple, "ratingValue"> & (Need<AggregateRatingSimple, "ratingCount"> | Need<AggregateRatingSimple, "reviewCount">);
+  Question: Need<QuestionSimple, "name" | "acceptedAnswer">;
+  HowTo: Need<HowToSimple, "name" | "step">;
+  Recipe: Need<RecipeSimple, "name" | "image">;
+  Course: Need<CourseSimple, "name" | "description">;
+  JobPosting: Need<JobPostingSimple, "title" | "description" | "datePosted" | "hiringOrganization">;
+  SoftwareApplication: Need<SoftwareAppSimple, "name" | "offers"> & (Need<SoftwareAppSimple, "aggregateRating"> | Need<SoftwareAppSimple, "review">);
+  VideoObject: Need<VideoSimple, "name" | "thumbnailUrl" | "uploadDate">;
+  ImageObject: Need<ImageSimple, "contentUrl">;
+  Book: Need<BookSimple, "name" | "author">;
+  Service: Need<ServiceSimple, "name">;
+};
+/** Properties Camox sets on every node: its identity, and its link to its page. */
+type CamoxOwned = "@type" | "@id" | "mainEntityOfPage";
+/** A requirement, without the properties Camox fills. */
+type Unfilled<Requirement, Filled extends PropertyKey> = Requirement extends unknown ? Omit<Requirement, Filled> : never;
+type NodeOf<T extends StructuredDataType, Filled extends PropertyKey> = T extends unknown ? {
+  "@type": T;
+} & Partial<Omit<Known<NodeProperties[T]>, CamoxOwned>> & Unfilled<NodeRequirements[T], Filled> : never;
+/**
+ * A node of Camox's vocabulary. `Excluded` lists the types a definition can't emit, and `Filled`
+ * the properties Camox fills when the definition leaves them out.
+ */
+export type StructuredDataNode<Excluded extends StructuredDataType = never, Filled extends PropertyKey = never> = NodeOf<Exclude<StructuredDataType, Excluded>, Filled>;
+/** The properties Camox fills on a layout's main entity, from its page. */
+export type MainEntityFilled = "name" | "headline" | "description" | "url" | "image" | "datePublished" | "dateModified" | "publisher" | "inLanguage";
+/** What a page is about, beside its own node. Only collections' records can be organizations. */
+export type MainEntity = StructuredDataNode<"Organization", MainEntityFilled>;
+/** The properties Camox fills on a record's node, from the record's title and description. */
+export type RecordNodeFilled = "name" | "headline" | "description";
+/**
+ * What a collection's `toStructuredData` describes each record as. Records can be organizations,
+ * such as customers or partners, with their own `@id`s.
+ */
+export type RecordNode = StructuredDataNode<never, RecordNodeFilled>;
+/** What blocks and repeatable items describe: anything but an organization, as Camox emits the site's. */
+export type BlockNode = StructuredDataNode<"Organization">;
+declare const RepeatedNodesBrand: unique symbol;
+/**
+ * A repeater's token in a Structured Data template: its items' nodes, from their own template,
+ * where the token is placed.
+ */
+export type RepeatedNodes = never[] & {
+  readonly [RepeatedNodesBrand]: true;
+};
+/** What a block's or repeatable item's `toStructuredData` returns: one or more nodes. */
+export type BlockStructuredData = BlockNode | RepeatedNodes | ReadonlyArray<BlockNode | RepeatedNodes>;
+/** Requires nothing of a list of nodes, or a node, that only take their types' properties. */
+export type KnownNodesOnly<Nodes> = [Nodes] extends [readonly (infer Node)[]] ? KnownPropertiesOnly<Node, BlockNode> : KnownPropertiesOnly<Nodes, BlockNode>;
+/** The page node's properties that Camox alone sets, from the page and the layout's outputs. */
+type PageOwned = CamoxOwned | "url" | "name" | "description" | "isPartOf" | "inLanguage" | "datePublished" | "dateModified" | "primaryImageOfPage" | "breadcrumb" | "mainEntity" | "potentialAction";
+/** A kind of web page, merged into the page's node. */
+export type WebPageKind = {
+  "@type": WebPageType;
+} & Partial<Omit<Known<WebPageSimple>, PageOwned>>;
+/** What a layout's `toStructuredData` says its page is: a kind of web page, or a main entity. */
+export type LayoutStructuredData = WebPageKind | MainEntity;
+/** The members of a vocabulary a node of type `T` can be. */
+type MembersOf<Vocabulary, T> = Vocabulary extends {
+  "@type": infer U;
+} ? T extends U ? Vocabulary : never : never;
+/**
+ * A node's keys that hold a value. TypeScript gives each object of a list the others' keys as
+ * `?: undefined`, which say nothing.
+ */
+type SetKeys<Node> = { [K in keyof Node]-?: [Exclude<Node[K], undefined>] extends [never] ? never : K; }[keyof Node];
+/**
+ * The properties of a node that its type doesn't take. Object literals returned by a function
+ * escape TypeScript's excess property checks, so definitions infer their nodes and check them
+ * with `KnownPropertiesOnly`.
+ */
+export type UnknownProperties<Node, Vocabulary> = Node extends {
+  "@type": infer T;
+} ? Exclude<SetKeys<Node>, keyof MembersOf<Vocabulary, T>> : never;
+/** Requires nothing of a definition whose nodes only take their types' properties. */
+export type KnownPropertiesOnly<Node, Vocabulary> = [UnknownProperties<Node, Vocabulary>] extends [never] ? unknown : {
+  "❌ Camox: these structured data properties aren't in Camox's vocabulary": UnknownProperties<Node, Vocabulary>;
+};
+//#endregion
+export { ARTICLE_TYPES };

package/dist/core/structuredData.js

@@ -0,0 +1,40 @@
+import { ARTICLE_TYPES } from "@camox/api-contract";
+
+//#region src/core/structuredData.ts
+/** The kinds of web page a layout can say its pages are. */
+const WEB_PAGE_TYPES = [
+	"AboutPage",
+	"CheckoutPage",
+	"CollectionPage",
+	"ContactPage",
+	"FAQPage",
+	"ItemPage",
+	"MedicalWebPage",
+	"ProfilePage",
+	"QAPage",
+	"RealEstateListing",
+	"SearchResultsPage"
+];
+/** The curated types that are creative works, which pages contain rather than talk about. */
+const CREATIVE_WORK_TYPES = [
+	...ARTICLE_TYPES,
+	"Book",
+	"Course",
+	"HowTo",
+	"ImageObject",
+	"Question",
+	"Recipe",
+	"Review",
+	"SoftwareApplication",
+	"VideoObject"
+];
+const includes = (types, type) => types.includes(type);
+/** Whether a node is a kind of web page. */
+const isWebPageKind = (node) => includes(WEB_PAGE_TYPES, node["@type"]);
+/** Whether a node is an Article. */
+const isArticle = (node) => includes(ARTICLE_TYPES, node["@type"]);
+/** Whether a node is a creative work, rather than a thing a page talks about. */
+const isCreativeWork = (node) => includes(CREATIVE_WORK_TYPES, node["@type"]);
+
+//#endregion
+export { ARTICLE_TYPES, CREATIVE_WORK_TYPES, WEB_PAGE_TYPES, isArticle, isCreativeWork, isWebPageKind };