camox 0.47.0 → 0.48.0

package/dist/core/createLayout.d.ts

@@ -1,15 +1,13 @@
-import { ReferenceScope } from "./lib/reference.js";
-import { CollectionRecordId, LayoutRequestContext, LoadedRecord } from "./requestContext.js";
+import { AnyLayoutContext, CuratedLayoutContext, LayoutPage, LayoutProject, LoadedLayoutContext, RecordLayoutContext } from "./layoutContext.js";
+import { ReferenceKeys, ReferenceListKeys, ReferenceScope } from "./lib/reference.js";
+import { CollectionRecordId, LayoutRequestContext, LoadedRecord, RecordPageStructuredData } from "./requestContext.js";
+import { KnownPropertiesOnly, LayoutStructuredData, MainEntity, StructuredDataNode, StructuredDataType, WebPageKind } from "./structuredData.js";
 import { notFound } from "./notFound.js";
 import { ContentProxy } from "./lib/contentType.js";
 import * as React from "react";
+import { RecordLink } from "@camox/api-contract";
 import { TSchema } from "@sinclair/typebox";
 //#region src/core/createLayout.d.ts
-export interface OgImageParams {
-  title: string;
-  description: string;
-  projectName: string;
-}
 export interface LayoutBlockData {
   _id: string;
   type: string;
@@ -74,6 +72,13 @@ export interface LayoutCollectionItemResult<Content = Record<string, unknown>, C
   kind: "collection-item";
   collectionId: CollectionId;
   data: LoadedRecord<Content>;
+  /** The record's Structured Data, for its page's graph. Set by `collection.pages()`. */
+  structuredData?: RecordPageStructuredData;
+  /** When the record was first and last published to Live, for its page's graph. */
+  published?: {
+    first: number | null;
+    last: number | null;
+  };
   /**
    * Type only, never set: the collection's fields, which type `layout.Item`. Invariant, so that
    * records of two collections never merge into one.
@@ -103,8 +108,8 @@ type LoaderReturn = AnyLayoutLoaderResult | PromiseLike<AnyLayoutLoaderResult>;
 /** The record a discovered page renders, independent of its current params. */
 export interface LayoutRouteTarget extends CollectionRecordId {
   kind: "collection-item";
-  /** The record's Label, which names its page where pages are listed (llms.txt). */
-  label?: string;
+  /** The record's title, which names its page where pages are listed (llms.txt). */
+  title?: string;
 }
 /** Route discovery result: the params of each page a derived layout can render. */
 export interface LayoutRoutesResult<Params = Record<string, string>> {
@@ -126,10 +131,6 @@ type RecordFields<Result> = [Awaited<Result>] extends [never] ? never : [Awaited
 type StringFieldKeys<F> = { [K in keyof F & string]: F[K] extends {
   fieldType: "String";
 } ? K : never; }[keyof F & string];
-/** Record pages' meta callbacks also get the record's String fields as plain text. */
-type MetaItem<F> = [F] extends [never] ? {} : {
-  item: { [K in StringFieldKeys<F>]: string; };
-};
 /** Record pages' `toMarkdown` also gets `item`, the reference-list Markdown builder. */
 type MarkdownItem<F> = [F] extends [never] ? {} : F extends Record<string, TSchema> ? {
   item: ContentProxy<F>;
@@ -141,39 +142,51 @@ type ItemScope<F> = [F] extends [never] ? {} : F extends Record<string, TSchema>
     children: (item: ReferenceScope<F>) => React.ReactNode;
   }) => React.ReactNode;
 } : {};
-/** What a page's metadata callbacks know about it. Curated pages have no loader data or params. */
-export interface PageMetaContext<Data = unknown, Params = Record<string, string>> {
-  projectName: string;
-  pageFullPath: string;
-  data: Data;
-  params: Params;
-}
-/** On singleton and derived pages, `pageMetaTitle` is the layout's `title`. */
-type BuildMetaTitle<Data, Params, F = never> = (params: PageMetaContext<Data, Params> & {
-  pageMetaTitle: string;
-} & MetaItem<F>) => string;
-/** Without it, curated pages use the editor's description and other pages have none. */
-type BuildMetaDescription<Data, Params, F = never> = (params: PageMetaContext<Data, Params> & {
-  pageMetaDescription: string | undefined;
-} & MetaItem<F>) => string | undefined;
 /** The Markdown Representation of a code-owned page, between its layout blocks. */
 type LayoutToMarkdown<Data, Params, F = never> = (context: {
   data: Data;
   params: Params;
 } & MarkdownItem<F>) => readonly string[];
-/** The collection a layout's record pages render, and the field each record is found by. */
+/**
+ * On record pages, the context's `content` holds the record's String fields as plain text, and
+ * its references as links to their records' nodes, for `toStructuredData`.
+ */
+type RecordContent<F> = [F] extends [never] ? {} : F extends Record<string, TSchema> ? {
+  content: { [K in StringFieldKeys<F>]: string; } & { [K in ReferenceKeys<F>]: RecordLink | undefined; } & { [K in ReferenceListKeys<F>]: RecordLink[]; };
+} : {
+  content: { [K in StringFieldKeys<F>]: string; };
+};
+/** The context a singleton or derived layout's `to*` options receive. */
+type LoadedContext<Data, Params, F = never> = LoadedLayoutContext<Data, Params> & RecordContent<F>;
+/**
+ * A layout's outputs, each receiving the page's context: `toReact`, `toTitle`, `toDescription`,
+ * `toImage` and `toStructuredData`.
+ */
+type LayoutOutputs<Context, Children, Declared extends LayoutStructuredData | undefined> = {
+  toReact: React.ComponentType<Context & Children>;
+  toTitle: (context: Context) => string;
+  /** Required, but may return nothing, such as `({ page }) => page.description`. */
+  toDescription: (context: Context) => string | undefined;
+  toImage?: (context: Context) => React.ReactElement;
+  /**
+   * What the page is: a kind of web page (`AboutPage`, `ContactPage`, …), which its node
+   * becomes, or a main entity (`BlogPosting`, `Product`, `Event`, …), which Camox emits as the
+   * page's `mainEntity`. Camox fills the main entity's name or headline, description, URL,
+   * image, dates, publisher and language where the layout leaves them out.
+   */
+  toStructuredData?: (context: Context) => Declared & KnownPropertiesOnly<Declared, LayoutStructuredData>;
+};
+/**
+ * The collection a layout's record pages render, and the field each record is found by. `param`
+ * names the route param holding that field's value; only the collection and field are synced.
+ */
 export type RecordPages = {
   collectionId: string;
   field: string;
+  param?: string;
 };
-interface CreateLayoutOptions<TBefore extends readonly LayoutBlock[], TAfter extends readonly LayoutBlock[], TInitial extends readonly InitialBlockImport[], Result extends LoaderReturn = LoaderReturn> {
+interface LayoutBaseOptions<TBefore extends readonly LayoutBlock[], TAfter extends readonly LayoutBlock[], TInitial extends readonly InitialBlockImport[]> {
   id: string;
-  kind?: "curated" | "derived" | "singleton";
-  loader?: (context: LayoutLoaderContext) => Result;
-  /** Lists the pages of a derived layout, for the sitemap and the Canvas. */
-  routes?: (context: LayoutRoutesContext) => RoutesReturn<Record<string, string>>;
-  /** A derived layout's record pages, set by spreading `collection.pages(...)`. */
-  recordPages?: RecordPages;
   title: string;
   description: string;
   blocks: {
@@ -185,16 +198,33 @@ interface CreateLayoutOptions<TBefore extends readonly LayoutBlock[], TAfter ext
      */
     initial?: ValidatePageContentBlocks<TInitial>;
   };
-  component: React.ComponentType<{
-    children: React.ReactNode;
-  }>;
-  buildMetaTitle: BuildMetaTitle<LoaderData<Result>, Record<string, string>, RecordFields<Result>>;
-  buildMetaDescription?: BuildMetaDescription<LoaderData<Result>, Record<string, string>, RecordFields<Result>>;
+}
+type CreateLayoutOptions<TBefore extends readonly LayoutBlock[], TAfter extends readonly LayoutBlock[], TInitial extends readonly InitialBlockImport[], Result extends LoaderReturn = LoaderReturn, Declared extends LayoutStructuredData | undefined = LayoutStructuredData | undefined> = LayoutBaseOptions<TBefore, TAfter, TInitial> & {
+  kind?: "curated" | "derived" | "singleton";
+  loader?: (context: LayoutLoaderContext) => Result;
+  /** Lists the pages of a derived layout, for the sitemap and the Canvas. */
+  routes?: (context: LayoutRoutesContext) => RoutesReturn<Record<string, string>>;
+  /** A derived layout's record pages, set by spreading `collection.pages(...)`. */
+  recordPages?: RecordPages;
   /** Singleton and derived layouts only. */
   toMarkdown?: LayoutToMarkdown<LoaderData<Result>, Record<string, string>, RecordFields<Result>>;
-  buildOgImage?: (params: OgImageParams) => React.ReactElement;
-}
-declare function createLayoutDefinition<const TBefore extends readonly LayoutBlock[], const TAfter extends readonly LayoutBlock[], const TInitial extends readonly InitialBlockImport[] = []>(options: CreateLayoutOptions<TBefore, TAfter, TInitial>): {
+} & LayoutOutputs<LoadedContext<LoaderData<Result>, Record<string, string>, RecordFields<Result>>, {
+  children: React.ReactNode;
+}, Declared>;
+/** Every option a layout may define, as the implementation reads them. */
+type AnyLayoutOptions = LayoutBaseOptions<any, any, any> & {
+  kind?: "curated" | "derived" | "singleton";
+  loader?: (context: LayoutLoaderContext) => LoaderReturn;
+  routes?: (context: LayoutRoutesContext) => RoutesReturn<Record<string, string>>;
+  recordPages?: RecordPages;
+  toMarkdown?: LayoutToMarkdown<any, any, any>;
+  toReact: React.ComponentType<any>;
+  toTitle: (context: any) => string;
+  toDescription: (context: any) => string | undefined;
+  toImage?: (context: any) => React.ReactElement;
+  toStructuredData?: (context: any) => LayoutStructuredData | undefined;
+};
+declare function createLayoutDefinition(options: AnyLayoutOptions): {
   BeforeBlocks: {
     (): React.JSX.Element;
     displayName: string;
@@ -218,14 +248,19 @@ declare function createLayoutDefinition<const TBefore extends readonly LayoutBlo
     recordPages: RecordPages | undefined;
     title: string;
     description: string;
-    buildMetaTitle: BuildMetaTitle<unknown, unknown>;
-    buildMetaDescription: BuildMetaDescription<unknown, unknown> | undefined;
+    /** The page's title, from the page's context. */
+    toTitle: (context: AnyLayoutContext) => string;
+    /** The page's description, from the page's context. */
+    toDescription: (context: AnyLayoutContext) => string | undefined;
     toMarkdown: ((context: {
       data: unknown;
       params: unknown;
       item?: unknown;
     }) => readonly string[]) | undefined;
-    buildOgImage: ((params: OgImageParams) => Promise<Response>) | undefined;
+    /** The page's shared image, which `/og` renders. Without one, Camox's default image. */
+    toImage: ((context: AnyLayoutContext) => React.ReactElement) | undefined;
+    /** What the page is, from the page's context. Without it, a plain web page. */
+    toStructuredData: (context: AnyLayoutContext) => LayoutStructuredData | undefined;
     blockDefinitions: ({
       type: string;
       content: Record<string, unknown>;
@@ -263,8 +298,9 @@ declare function createLayoutDefinition<const TBefore extends readonly LayoutBlo
         position: string;
       }[];
     }[]>) | undefined;
-    component: React.ComponentType<{
-      children: React.ReactNode;
+    /** Renders the layout around the page, with the page's context as props. */
+    toReact: React.ComponentType<AnyLayoutContext & {
+      children?: React.ReactNode;
     }>;
     Provider: ({ layoutBlocks, children, result }: {
       layoutBlocks: Record<string, LayoutBlockData>;
@@ -284,18 +320,15 @@ type Params<Id extends string> = Id extends `${infer Head}.${infer Tail}` ? Para
 type RouteParams<Id extends string> = Id extends keyof LayoutFileRoutes ? LayoutFileRoutes[Id] extends {
   params: infer P;
 } ? P : Params<Id> : Params<Id>;
-type FileOptions<Id extends string, Result extends LoaderReturn, B extends readonly LayoutBlock[], A extends readonly LayoutBlock[], I extends readonly InitialBlockImport[]> = Omit<CreateLayoutOptions<B, A, I>, "id" | "kind" | "loader" | "routes" | "recordPages" | "component" | "buildMetaTitle" | "buildMetaDescription" | "toMarkdown"> & ({
+type FileOptions<Id extends string, Result extends LoaderReturn, B extends readonly LayoutBlock[], A extends readonly LayoutBlock[], I extends readonly InitialBlockImport[], Declared extends LayoutStructuredData | undefined> = Omit<LayoutBaseOptions<B, A, I>, "id"> & (({
   kind: "curated";
-  component: React.ComponentType<{
-    children: React.ReactNode;
-  }>;
   loader?: never;
   routes?: never;
   recordPages?: never;
   toMarkdown?: never;
-  buildMetaTitle: BuildMetaTitle<undefined, Record<string, never>>;
-  buildMetaDescription?: BuildMetaDescription<undefined, Record<string, never>>;
-} | {
+} & LayoutOutputs<CuratedLayoutContext, {
+  children: React.ReactNode;
+}, Declared>) | ({
   kind: "singleton";
   blocks: {
     before: ValidateLayoutOnlyBlocks<B>;
@@ -306,12 +339,9 @@ type FileOptions<Id extends string, Result extends LoaderReturn, B extends reado
   routes?: never;
   recordPages?: never;
   toMarkdown?: LayoutToMarkdown<LoaderData<Result>, Record<string, never>, RecordFields<Result>>;
-  component: React.ComponentType<{
-    children?: never;
-  }>;
-  buildMetaTitle: BuildMetaTitle<LoaderData<Result>, Record<string, never>, RecordFields<Result>>;
-  buildMetaDescription?: BuildMetaDescription<LoaderData<Result>, Record<string, never>, RecordFields<Result>>;
-} | {
+} & LayoutOutputs<LoadedContext<LoaderData<Result>, Record<string, never>, RecordFields<Result>>, {
+  children?: never;
+}, Declared>) | ({
   kind: "derived";
   blocks: {
     before: ValidateLayoutOnlyBlocks<B>;
@@ -322,13 +352,10 @@ type FileOptions<Id extends string, Result extends LoaderReturn, B extends reado
   routes?: (context: LayoutRoutesContext) => RoutesReturn<RouteParams<Id>>;
   recordPages?: RecordPages;
   toMarkdown?: LayoutToMarkdown<LoaderData<Result>, RouteParams<Id>, RecordFields<Result>>;
-  component: React.ComponentType<{
-    children?: never;
-  }>;
-  buildMetaTitle: BuildMetaTitle<LoaderData<Result>, RouteParams<Id>, RecordFields<Result>>;
-  buildMetaDescription?: BuildMetaDescription<LoaderData<Result>, RouteParams<Id>, RecordFields<Result>>;
-});
-export declare function createLayout<const B extends readonly LayoutBlock[], const A extends readonly LayoutBlock[], const I extends readonly InitialBlockImport[] = [], Result extends LoaderReturn = never>(options: CreateLayoutOptions<B, A, I, Result>): LayoutFor<Result>;
-export declare function createLayout<const Id extends string>(id: Id): <Result extends LoaderReturn = never, const B extends readonly LayoutBlock[] = [], const A extends readonly LayoutBlock[] = [], const I extends readonly InitialBlockImport[] = []>(options: FileOptions<Id, Result, B, A, I>) => LayoutFor<Result>;
+} & LayoutOutputs<LoadedContext<LoaderData<Result>, RouteParams<Id>, RecordFields<Result>>, {
+  children?: never;
+}, Declared>));
+export declare function createLayout<const B extends readonly LayoutBlock[], const A extends readonly LayoutBlock[], const I extends readonly InitialBlockImport[] = [], Result extends LoaderReturn = never, Declared extends LayoutStructuredData | undefined = undefined>(options: CreateLayoutOptions<B, A, I, Result, Declared>): LayoutFor<Result>;
+export declare function createLayout<const Id extends string>(id: Id): <Result extends LoaderReturn = never, const B extends readonly LayoutBlock[] = [], const A extends readonly LayoutBlock[] = [], const I extends readonly InitialBlockImport[] = [], Declared extends LayoutStructuredData | undefined = undefined>(options: FileOptions<Id, Result, B, A, I, Declared>) => LayoutFor<Result>;
 //#endregion
-export { type LayoutRequestContext, notFound };
+export { type CuratedLayoutContext, type LayoutPage, type LayoutProject, type LayoutRequestContext, type LayoutStructuredData, type LoadedLayoutContext, type MainEntity, type RecordLayoutContext, type StructuredDataNode, type StructuredDataType, type WebPageKind, notFound };

package/dist/core/createLayout.js

@@ -2,7 +2,7 @@ import { notFound } from "./notFound.js";
 import { useOptionalCamoxApp } from "../features/provider/components/CamoxAppContext.js";
 import { useBlockEditingRuntime } from "./editing/BlockEditingRuntime.js";
 import { BlockErrorBoundary } from "../features/preview/components/BlockErrorBoundary.js";
-import { asCollectionItem, fieldPlainText } from "./recordItem.js";
+import { asCollectionItem } from "./recordItem.js";
 import { RecordScope } from "./lib/recordScope.js";
 import { c } from "react/compiler-runtime";
 import * as React from "react";
@@ -133,12 +133,13 @@ function createLayoutDefinition(options) {
 					t2 = null;
 					break bb0;
 				}
-				const { contentSchema, label } = collection._internal;
+				const { contentSchema } = collection._internal;
 				const { id, content, references } = result.data;
 				const readOnly = /* @__PURE__ */ jsx(RecordScope, {
 					record: {
 						id,
-						label: fieldPlainText(content[label]),
+						title: result.data.title ?? "",
+						description: result.data.description ?? null,
 						content,
 						references
 					},
@@ -152,7 +153,7 @@ function createLayoutDefinition(options) {
 				}
 				t1 = editingRuntime.renderLayoutItem({
 					collectionId: result.collectionId,
-					labelField: label,
+					collection,
 					properties: contentSchema.properties,
 					record: result.data,
 					children,
@@ -192,14 +193,6 @@ function createLayoutDefinition(options) {
 			slot: "after"
 		};
 	})];
-	const buildOgImage = options.buildOgImage ? async (params) => {
-		if (import.meta.env?.SSR === false) throw new Error("OG images can only be rendered on the server.");
-		const { ImageResponse } = await import("camox/_internal/imageResponse");
-		return new ImageResponse(options.buildOgImage(params), {
-			width: 1200,
-			height: 630
-		});
-	} : void 0;
 	const loadInitialBlockBundles = initialBlocks && (() => Promise.all(initialBlocks.map(async (load) => {
 		const { block } = await load();
 		if (block._internal.layoutOnly) throw new Error(`${INITIAL_LAYOUT_ONLY_ERROR} (block "${block._internal.id}")`);
@@ -228,13 +221,14 @@ function createLayoutDefinition(options) {
 			recordPages: options.recordPages,
 			title: options.title,
 			description: options.description,
-			buildMetaTitle: options.buildMetaTitle,
-			buildMetaDescription: options.buildMetaDescription,
+			toTitle: (context) => options.toTitle(context),
+			toDescription: (context) => options.toDescription(context),
 			toMarkdown: options.toMarkdown,
-			buildOgImage,
+			toImage: options.toImage,
+			toStructuredData: (context) => options.toStructuredData?.(context),
 			blockDefinitions,
 			loadInitialBlockBundles,
-			component: options.component,
+			toReact: options.toReact,
 			Provider
 		}
 	};

package/dist/core/derivedRoutes.js

@@ -55,7 +55,7 @@ function targetRecord(entry) {
 	if (typeof target?.id !== "string") return {};
 	return {
 		recordId: target.id,
-		...typeof target.label === "string" && { label: target.label }
+		...typeof target.title === "string" && { title: target.title }
 	};
 }
 /**

package/dist/core/editing/BlockEditingRuntime.d.ts

@@ -1,11 +1,12 @@
 import { LoadedRecord } from "../requestContext.js";
+import { Collection } from "../createCollection.js";
 import * as React from "react";
 //#region src/core/editing/BlockEditingRuntime.d.ts
 /** A record page's record, as `layout.Item` hands it to the editing runtime. */
 export interface LayoutItemProps {
   collectionId: string;
-  /** The collection's label field. */
-  labelField: string;
+  /** The record's collection, whose templates title and describe it. */
+  collection: Collection;
   /** The collection's field schemas. */
   properties: Record<string, unknown>;
   record: LoadedRecord;

package/dist/core/editing/CompleteBlockEditingRuntime.js

@@ -40,7 +40,8 @@ const layoutItemOptions = {
 	description: "",
 	content: () => ({}),
 	toMarkdown: () => [],
-	component: () => null
+	toReact: () => null,
+	toTitle: () => ""
 };
 const completeEditingRuntime = {
 	renderLayoutItem(props) {

package/dist/core/editing/createEditableBlock.d.ts

@@ -3,13 +3,14 @@ import { ArtifactRenderProps } from "../lib/artifact.js";
 import { InlineStyle, InlineTextStyles, TextLinkStyleData, TextStyleData } from "../lib/textStyles.js";
 import "../lib/lexicalReact.js";
 import { ReferenceContent, ReferenceKeys, ReferenceListKeys, ReferenceScope } from "../lib/reference.js";
+import { BlockStructuredData } from "../structuredData.js";
 import { IconValue } from "../lib/iconTypes.js";
-import { ArtifactDataCheck, ArtifactSource, ContentFieldBuilder, EmbedURL, FileValue, ImageValue, ItemSettingsBrand, LinkValue, SettingBuilder, ToMarkdownBuilder } from "../lib/contentType.js";
+import { ArtifactDataCheck, ArtifactSource, ContentFieldBuilder, EmbedURL, FileValue, ImageValue, ItemSettingsBrand, LinkValue, SettingBuilder, ToMarkdownBuilder, ToStructuredDataBuilder, ToTitleBuilder } from "../lib/contentType.js";
 import { LayoutItemProps } from "./BlockEditingRuntime.js";
 import * as React from "react";
 import { Static, TArray, TObject, TSchema, Type } from "@sinclair/typebox";
 //#region src/core/editing/createEditableBlock.d.ts
-interface CreateBlockOptions<TSchemaShape extends Record<string, TSchema> = Record<string, TSchema>, TSettingsShape extends Record<string, TSchema> = Record<string, TSchema>, TLayoutOnly extends boolean = false> {
+interface BlockBaseOptions<TSchemaShape extends Record<string, TSchema>, TSettingsShape extends Record<string, TSchema>, TLayoutOnly extends boolean, TNodes extends BlockStructuredData = BlockStructuredData> {
   id: string;
   /**
    * Human-readable title for the block (JSON Schema `title`).
@@ -31,7 +32,8 @@ interface CreateBlockOptions<TSchemaShape extends Record<string, TSchema> = Reco
    *     content: (field) => ({ name: field.string({ default: "Item" }) }),
    *     minItems: 1,
    *     maxItems: 10,
-   *     toMarkdown: (c) => [c.name],
+   *     toTitle: ({ content }) => content.name,
+   *     toMarkdown: ({ content }) => [content.name],
    *   }),
    * })
    */
@@ -54,28 +56,62 @@ interface CreateBlockOptions<TSchemaShape extends Record<string, TSchema> = Reco
   layoutOnly?: TLayoutOnly;
   /** Share content and settings across all placements of this block definition. Defaults to false. */
   synced?: boolean;
-  /**
-   * React component that renders the block.
-   * Must be defined as a separate function (not inline, not an arrow function).
-   * Should use the Field component returned by createBlock to render editable content.
-   */
-  component: React.ComponentType<{
-    content: Static<ReturnType<typeof Type.Object<TSchemaShape>>>;
-  }>;
   /**
    * Builder for rendering block content as markdown.
-   * `c` is a proxy typed on `content` keys — `c.title`, `c.description`, etc.
-   * `s` is a proxy typed on `settings` keys — call a boolean setting with a line
-   * (`s.showCta(c.cta)`) or an enum with a value (`s.variant("banner", [...])`)
-   * to wrap lines in a conditional. Each returned entry becomes a paragraph
-   * (joined with `\n\n`). Lines where all referenced fields resolve to empty
+   * `content` is a proxy typed on `content` keys — `content.title`, `content.description`, etc.
+   * `settings` is a proxy typed on `settings` keys — call a boolean setting with a line
+   * (`settings.showCta(content.cta)`) or an enum with a value
+   * (`settings.variant("banner", [...])`) to wrap lines in a conditional. Each returned entry
+   * becomes a paragraph (joined with `\n\n`). Lines where all referenced fields resolve to empty
    * (or whose condition is false) are omitted at render time.
    *
    * @example
-   * toMarkdown: (c, s) => [`# ${c.title}`, c.description, s.showCta(c.cta)]
+   * toMarkdown: ({ content, settings }) => [
+   *   `# ${content.title}`,
+   *   content.description,
+   *   settings.showCta(content.cta),
+   * ]
    */
   toMarkdown: ToMarkdownBuilder<TSchemaShape, TSettingsShape>;
+  /**
+   * Names the block in the studio and to agents until it has a Summary: one line from
+   * `{ content, settings }`, read like `toMarkdown`'s, on the default locale's content.
+   *
+   * @example
+   * toTitle: ({ content }) => content.title
+   */
+  toTitle: ToTitleBuilder<TSchemaShape, TSettingsShape>;
+  /**
+   * The things the block shows, as Structured Data nodes from `{ content, settings }`: one node,
+   * or a list. A repeater's token places its items' nodes. Camox links each node to the page,
+   * and each placement gets its own. Blocks never say what the page is, and can't describe an
+   * `Organization`: Camox emits the site's.
+   *
+   * @example
+   * toStructuredData: ({ content }) => ({
+   *   "@type": "VideoObject",
+   *   name: content.title,
+   *   embedUrl: content.video,
+   *   thumbnailUrl: content.thumbnail,
+   *   uploadDate: content.uploadDate,
+   * })
+   */
+  toStructuredData?: ToStructuredDataBuilder<TSchemaShape, TSettingsShape, TNodes>;
 }
+/** What a block's `toReact` receives as props: its content and settings. */
+export interface BlockContext<TSchemaShape extends Record<string, TSchema>, TSettingsShape extends Record<string, TSchema>> {
+  content: Static<ReturnType<typeof Type.Object<TSchemaShape>>>;
+  settings: Static<ReturnType<typeof Type.Object<TSettingsShape>>>;
+}
+/**
+ * The React component that renders the block. Should use the Field component returned by
+ * createBlock to render editable content.
+ */
+type BlockToReact<TSchemaShape extends Record<string, TSchema>, TSettingsShape extends Record<string, TSchema>> = {
+  /** Renders the block, with its content and settings as props. */
+  toReact: React.ComponentType<BlockContext<TSchemaShape, TSettingsShape>>;
+};
+type CreateBlockOptions<TSchemaShape extends Record<string, TSchema> = Record<string, TSchema>, TSettingsShape extends Record<string, TSchema> = Record<string, TSchema>, TLayoutOnly extends boolean = false, TNodes extends BlockStructuredData = BlockStructuredData> = BlockBaseOptions<TSchemaShape, TSettingsShape, TLayoutOnly, TNodes> & BlockToReact<TSchemaShape, TSettingsShape>;
 interface BlockData<TContent> {
   _id: string;
   type: string;
@@ -99,6 +135,7 @@ export interface PeekItem {
   content: unknown;
   settings: Record<string, unknown> | null;
   summary: string;
+  title: string;
   position: string;
   createdAt: number;
   updatedAt: number;
@@ -115,7 +152,7 @@ export interface RepeatableItemSeed {
   settings?: Record<string, unknown>;
   position: string;
 }
-export declare function createEditableBlock<TSchemaShape extends Record<string, TSchema>, TSettingsShape extends Record<string, TSchema> = Record<string, never>, TLayoutOnly extends boolean = false>(options: CreateBlockOptions<TSchemaShape, TSettingsShape, TLayoutOnly>): {
+export declare function createEditableBlock<TSchemaShape extends Record<string, TSchema>, TSettingsShape extends Record<string, TSchema> = Record<string, never>, TLayoutOnly extends boolean = false, TNodes extends BlockStructuredData = BlockStructuredData>(options: CreateBlockOptions<TSchemaShape, TSettingsShape, TLayoutOnly, TNodes>): {
   Detached: ({ children }: {
     children: (props: {
       "data-camox-block-id"?: string;
@@ -1657,17 +1694,19 @@ export declare function createEditableBlock<TSchemaShape extends Record<string,
       params: unknown[] & [];
     })["static"]; }, Exclude<keyof TSchemaShape, { [K_1 in keyof TSchemaShape]: TSchemaShape[K_1] extends import("@sinclair/typebox").TReadonly<TSchema> ? TSchemaShape[K_1] extends import("@sinclair/typebox").TOptional<TSchemaShape[K_1]> ? K_1 : never : never; }[keyof TSchemaShape] | { [K_2 in keyof TSchemaShape]: TSchemaShape[K_2] extends import("@sinclair/typebox").TReadonly<TSchema> ? TSchemaShape[K_2] extends import("@sinclair/typebox").TOptional<TSchemaShape[K_2]> ? never : K_2 : never; }[keyof TSchemaShape] | { [K_3 in keyof TSchemaShape]: TSchemaShape[K_3] extends import("@sinclair/typebox").TOptional<TSchema> ? TSchemaShape[K_3] extends import("@sinclair/typebox").TReadonly<TSchemaShape[K_3]> ? never : K_3 : never; }[keyof TSchemaShape]>>>>>) => React.JSX.Element;
     /** Renders a record page's record; see `BlockEditingRuntime.renderLayoutItem`. */
-    LayoutItem: ({ collectionId, labelField, properties, record, children, fallback }: LayoutItemProps) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
+    LayoutItem: ({ collectionId, collection, properties, record, children, fallback }: LayoutItemProps) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
     id: string;
     title: string;
     description: string;
     contentSchema: {
+      toStructuredData?: unknown;
       type: "object";
       title: string;
       description: string;
       properties: TSchemaShape;
       required: string[];
       toMarkdown: string[];
+      toTitle: string;
     };
     settingsSchema: {
       type: "object";
@@ -1705,6 +1744,7 @@ export declare function createEditableBlock<TSchemaShape extends Record<string,
         settings: Record<string, unknown>;
         slot: null;
         summary: string;
+        title: string;
         position: string;
         createdAt: number;
         updatedAt: number;