canopycms 0.0.67-int.90 → 0.0.67

package/dist/entry-schema.d.ts

@@ -1,22 +1,15 @@
 /**
  * The entry-schema authoring API — the surface ADOPTERS write against.
- *
  * `defineEntrySchema`, `defineInlineFieldGroup`, `defineNestedFieldGroup` and
- * `defineSeoFieldGroup` are how a host app declares its content model in
- * TypeScript, with the field list inferring the entry's data type. Changing a
- * signature here is an adopter-facing breaking change, not an internal one.
- *
- * This is the type-level half of the schema story. The runtime half — loading
- * `.collection.json`, resolving it, and validating content against it — lives in
- * `schema/` and `validation/`.
+ * `defineSeoFieldGroup` declare a host app's content model in TypeScript, with the
+ * field list inferring the entry's data type, so changing a signature here is an
+ * adopter-facing breaking change, not an internal one.
  *
+ * Type-level half only: loading `.collection.json`, resolving it and validating
+ * content against it live in `schema/` and `validation/`.
  * `RESOLVED_REFERENCE_KEYS`/`buildResolvedReference` define the shape a resolved
- * reference takes; `validation/entry-validator.ts`'s `normalizeReferenceValues`
- * is the inverse, and the two must agree.
- *
- * `DEFAULT_SEO_FIELD_NAMES` is imported from `static/seo.ts` rather than
- * redeclared, so the schema this module emits and the fields that module reads
- * cannot drift apart.
+ * reference takes and must agree with `validation/entry-validator.ts`'s inverse
+ * `normalizeReferenceValues`.
  *
  * Module map: ./AGENTS.md.
  */
@@ -38,16 +31,12 @@ type InferableField = {
      * For select fields: the option list. Inferring the literal union of these values is
      * what makes a select field's type its own options rather than a bare `string`.
      *
-     * MUST stay `readonly` even though `SelectFieldConfig.options` (config/types.ts) is a
-     * mutable `SelectOption[]` — but NOT for the reason you might assume. A mutable
-     * constraint does not defeat `const` inference here: verified against this repo's tsc,
-     * `<const T>` still infers `['a', 'b']` with the literals intact under a mutable
-     * constraint, so the union would survive. The real failure is louder. An adopter who
-     * declares the option list separately and shares it across schemas writes
-     * `as const`, producing a `readonly` tuple — and a `readonly` array is not assignable
-     * to a mutable one (TS4104), so every such schema would stop compiling at the
-     * definition site. `readonly` here accepts both the inline literal and the shared
-     * `as const` array.
+     * MUST stay `readonly`, though `SelectFieldConfig.options` (config/types.ts) is a mutable
+     * `SelectOption[]`: an adopter who declares the option list separately and shares it
+     * across schemas writes `as const`, and a `readonly` array is not assignable to a mutable
+     * one (TS4104), so every such schema would stop compiling at its definition site.
+     * `readonly` accepts both the inline literal and the shared `as const` array. (A mutable
+     * constraint would not by itself defeat `const` inference — that is not the reason.)
      */
     options?: readonly (string | {
         label: string;
@@ -66,12 +55,6 @@ type InferableField = {
  * The fields reference resolution adds to a target's own data, on top of whatever
  * `resolvedSchema` declares.
  *
- * These have always been returned at runtime (`resolveSingleReferenceOnce` in
- * content-store.ts) but were missing from the inferred type, so a resolved reference typed
- * narrower than it actually is — which is why reading `ref.id` needed a cast, and one source
- * of the library-internal type error `adopter-migration.md` records under
- * `exactOptionalPropertyTypes` + `skipLibCheck: false`.
- *
  * `urlPath` is what makes a resolved reference linkable without a second lookup; it follows
  * the same collection+slug rule `listEntries` publishes as `item.urlPath`, so an index entry
  * collapses to its parent path.
@@ -99,27 +82,23 @@ export interface ResolvedReferenceMeta {
  * embed it, then the reserved metadata.
  *
  * Exists so the two places that construct one — the server resolver in content-store.ts and
- * the editor's live-preview endpoint in api/resolve-references.ts — cannot drift. They already
- * had: the preview endpoint kept the old `{ id, ...data }` order and carried none of the other
- * three keys, so a component rendering `<a href={ref.urlPath}>` showed `undefined` while
- * previewing and a real URL once published.
- *
- * The ordering is the contract, not a detail. Metadata last means a target that models `id` as
- * a content field cannot shadow the real content ID — which matters because the write boundary
- * recovers a reference's id from `value.id` (`referenceValueId`), so shadowing it made a
- * re-save persist the wrong value and silently repoint the reference. Body before metadata
- * closes the same hole for a body field named `id`; that schema is also rejected outright by
- * the entry schema registry, so this ordering is the guarantee and that check is the loud
- * error rather than a silent drop.
+ * the editor's live-preview endpoint in api/resolve-references.ts — cannot drift.
+ *
+ * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
+ * a content field cannot shadow the real content ID, which the write boundary recovers from
+ * `value.id` (`referenceValueId`) — a shadowed id makes a re-save persist the wrong value and
+ * silently repoint the reference. Body before metadata closes the same hole for a body field
+ * named `id`; the entry schema registry also rejects that schema outright, so this ordering is
+ * the guarantee and that check is the loud error rather than a silent drop.
  */
 export declare function buildResolvedReference(data: Record<string, unknown>, meta: ResolvedReferenceMeta, body?: {
     fieldName: string;
     value: string | undefined;
 }): Record<string, unknown>;
 /**
- * Recursively flatten inline groups (type: 'group') out of a field tuple so that
- * InferContentShape sees only data-carrying fields. Inline groups contribute no
- * key to the content shape — their children are merged into the parent level.
+ * Recursively flatten inline groups (type: 'group') out of a field tuple: they contribute
+ * no key to the content shape, so their children merge into the parent level and
+ * InferContentShape sees only data-carrying fields.
  */
 type FlattenInlineGroups<Fields extends readonly InferableField[]> = Fields extends readonly [
     infer Head,
@@ -129,11 +108,10 @@ type FlattenInlineGroups<Fields extends readonly InferableField[]> = Fields exte
     fields: infer GFields extends readonly InferableField[];
 } ? [...FlattenInlineGroups<GFields>, ...FlattenInlineGroups<Rest>] : [Head, ...FlattenInlineGroups<Rest>] : [];
 /**
- * Collapse an intersection of mapped types into one object type, preserving the `?`
- * modifier (the mapped type is homomorphic over `keyof T`, so optionality survives).
- * Without it, InferContentShape would surface as `{ a: string } & { b?: string }` —
- * structurally equivalent, but it reads badly in editor tooltips and is not accepted
- * by strict type-equality assertions.
+ * Collapse an intersection of mapped types into one object type, preserving the `?` modifier
+ * (homomorphic over `keyof T`, so optionality survives). Without it InferContentShape surfaces
+ * as `{ a: string } & { b?: string }` — structurally equivalent, but it reads badly in editor
+ * tooltips and fails strict type-equality assertions.
  */
 type Simplify<T> = {
     [K in keyof T]: T[K];
@@ -144,38 +122,30 @@ type Simplify<T> = {
  */
 type ScalarValue<F extends InferableField, V> = F['list'] extends true ? V[] : V;
 /**
- * The value one `select` option contributes to the field's value union. A bare string
- * option contributes itself; a `{ label, value }` option contributes its `value`, not
- * the whole object. Mixed arrays of both forms work because this distributes.
- *
- * Falls back to `string` for an option whose literal type is gone — an options array
- * annotated as `SelectOption[]` rather than inferred by `defineEntrySchema` widens to
- * `string | { label: string; value: string }`, and both arms then land on `string`.
+ * The value one `select` option contributes to the field's value union: a bare string option
+ * contributes itself, a `{ label, value }` option its `value`. Mixed arrays work because this
+ * distributes. Falls back to `string` for an option whose literal type is gone — an array
+ * annotated `SelectOption[]` rather than inferred by `defineEntrySchema` widens to
+ * `string | { label: string; value: string }`, and both arms land on `string`.
  */
 type SelectOptionValue<O> = O extends {
     value: infer V extends string;
 } ? V : O extends string ? O : string;
 /**
- * The value type of a `select` field: the literal union of its OWN `options`.
- *
- * A select value is always a string — `SelectOption` (config/types.ts) carries
- * `value: string` in both arms, `normalizeOptions` (editor/FormRenderer.tsx) emits
- * strings, and `validateEntryData` (validation/entry-validator.ts) rejects anything
- * that is not one. This type says WHICH strings.
- *
- * Like the rest of InferContentShape, this models the SCHEMA'S declared shape, not
- * every byte the validator will tolerate on disk — the same stance that types a field
- * omitting `required` as a required property. Notably the validator also accepts `''`
- * as "not filled in" for any field that is not explicitly `required: true`, and `''` is
- * deliberately NOT in this union.
- *
- * Degrades to `string` when there is nothing to infer: no `options` key at all, or an
- * empty one. Both are schema mistakes that `ensureSelectFieldsHaveOptions`
- * (config/validation.ts) rejects — but note it runs from `createEntrySchemaRegistry`,
- * NOT from `validateCanopyConfig`, so a schema that is only ever fed to
- * `TypeFromEntrySchema` and never registered gets no runtime rejection at all.
- * Returning `never` here would type such a field as unsatisfiable, which is a worse
- * error than the bare `string` this falls back to.
+ * The value type of a `select` field: the literal union of its OWN `options`. A select value is
+ * always a string — `SelectOption` (config/types.ts) carries `value: string` in both arms,
+ * `normalizeOptions` (editor/FormRenderer.tsx) emits strings, and `validateEntryData`
+ * (validation/entry-validator.ts) rejects anything else — so this says WHICH strings.
+ *
+ * Like the rest of InferContentShape, it models the SCHEMA'S declared shape, not every byte the
+ * validator tolerates on disk: the validator also accepts `''` as "not filled in" for any field
+ * that is not explicitly `required: true`, and `''` is deliberately NOT in this union.
+ *
+ * Degrades to `string` when there is nothing to infer (no `options` key, or an empty one). Both
+ * are schema mistakes `ensureSelectFieldsHaveOptions` (config/validation.ts) rejects — but it
+ * runs from `createEntrySchemaRegistry`, so a schema only ever fed to `TypeFromEntrySchema` and
+ * never registered gets no runtime rejection. `never` here would type such a field as
+ * unsatisfiable, a worse error than this bare `string`.
  */
 type SelectValue<F extends InferableField> = F extends {
     options: infer O extends readonly unknown[];
@@ -184,12 +154,9 @@ type ObjectValue<F extends InferableField & {
     fields: readonly InferableField[];
 }> = F['list'] extends true ? Array<InferContentShape<F['fields']>> : InferContentShape<F['fields']>;
 /**
- * Distributes over each member of a block templates union to produce a discriminated union.
- *
- * Uses a bare type parameter `T` so that the conditional type distributes:
- * given `T = { name: 'hero'; fields: [...] } | { name: 'cta'; fields: [...] }`,
- * produces `{ template: 'hero'; value: { ... } } | { template: 'cta'; value: { ... } }`
- * rather than collapsing into a single merged object.
+ * Distributes over each member of a block-templates union to produce a discriminated union. The
+ * bare type parameter `T` is what makes the conditional distribute: `{ name: 'hero'; ... } |
+ * { name: 'cta'; ... }` yields two `{ template; value }` members rather than one merged object.
  */
 type DistributeBlockTemplate<T> = T extends {
     name: infer N;
@@ -205,9 +172,8 @@ type BlockValue<F extends InferableField & {
     }>;
 }> = Array<DistributeBlockTemplate<F['templates'][number]>>;
 /**
- * Structural mirror of `ImageFieldValue` (config/types.ts). Kept inline
- * rather than imported so this module stays free of a FieldConfig import
- * (see the module doc comment: "importing FieldConfig is not required").
+ * Structural mirror of `ImageFieldValue` (config/types.ts), inline rather than imported so this
+ * module stays free of a FieldConfig import.
  */
 type ImageValue = {
     src: string;
@@ -251,19 +217,15 @@ type FieldValue<F extends InferableField> = F extends {
     type: 'date';
 } ? ScalarValue<F, string> : ScalarValue<F, string>;
 /**
- * Infer a TypeScript data shape from a CanopyCMS FieldConfig-like array.
- * - Objects become nested objects
- * - Blocks become arrays of tagged templates with their value shapes
- * - Lists become arrays of the scalar/object type
- * - A field with an explicit `required: false` becomes an OPTIONAL property
- *   (`subheading?: string`), so a literal may omit it entirely rather than spelling it
- *   out as `undefined`. Reading it still yields `string | undefined`.
- * - A field that OMITS `required` stays a REQUIRED property. `F['required']` infers as
- *   `boolean | undefined` there, which does not extend `false`. This three-way
- *   distinction (`true` / `false` / absent) is deliberate and pinned by tests — only an
- *   explicit `required: false` opts a key into `?:`.
- * - Inline groups (type: 'group') are flattened — their fields contribute directly
- *   to the parent shape with no intermediate key.
+ * Infer a TypeScript data shape from a CanopyCMS FieldConfig-like array: objects nest, blocks
+ * become arrays of tagged templates, lists become arrays of the scalar/object type, and inline
+ * groups (type: 'group') flatten into the parent shape with no intermediate key.
+ *
+ * Optionality is three-way (`true` / `false` / absent), deliberate and pinned by tests: only an
+ * explicit `required: false` opts a key into `?:` (`subheading?: string`, so a literal may omit
+ * it rather than spell out `undefined`; reading it still yields `string | undefined`). A field
+ * that OMITS `required` stays REQUIRED, because `F['required']` infers there as
+ * `boolean | undefined`, which does not extend `false`.
  *
  * Works with any structurally compatible array; importing FieldConfig is not required.
  */
@@ -272,13 +234,9 @@ type InferContentShape<Fields extends readonly InferableField[]> = Simplify<{
 } & {
     [F in FlattenInlineGroups<Fields>[number] as F['required'] extends false ? F['name'] : never]?: FieldValue<F>;
 }>;
-/**
- * Helper to define entry schema field arrays with literal inference without sprinkling `as const`.
- */
+/** Define an entry schema's field array with literal inference, without sprinkling `as const`. */
 export declare const defineEntrySchema: <const T extends readonly InferableField[]>(fields: T) => T;
-/**
- * Convenience alias to derive the content shape from a `defineEntrySchema` result.
- */
+/** Content shape derived from a `defineEntrySchema` result. */
 export type TypeFromEntrySchema<T extends readonly InferableField[]> = InferContentShape<T>;
 /**
  * Derive a map of entry-type-name → content-shape from an `entrySchemaRegistry`.
@@ -290,50 +248,32 @@ export type TypeFromEntrySchema<T extends readonly InferableField[]> = InferCont
  *
  * @example
  * ```ts
- * export const entrySchemaRegistry = createEntrySchemaRegistry({
- *   partner: partnerSchema,
- *   doc: docSchema,
- *   home: homeSchema,
- * })
- *
  * export type EntryTypes = EntryTypesFromRegistry<typeof entrySchemaRegistry>
- *
- * // Then per-schema aliases stay one line each, anchored to the registry:
+ * // Per-schema aliases stay one line each, anchored to the registry:
  * export type PartnerContent = EntryTypes['partner']
  *
- * // And the tree-builder narrows on entryType:
- * await canopy.buildContentTree<NavFields, EntryTypes>({
- *   extract: (data, meta) => {
- *     if (meta.kind === 'collection' && meta.indexEntry?.entryType === 'partner') {
- *       // meta.indexEntry.data is typed PartnerContent
- *     }
- *   },
- * })
+ * // And the tree-builder narrows on entryType: inside this extract,
+ * // meta.indexEntry.data is typed PartnerContent once meta.indexEntry?.entryType
+ * // has been checked against 'partner'.
+ * await canopy.buildContentTree<NavFields, EntryTypes>({ extract: (data, meta) => { … } })
  * ```
  */
 export type EntryTypesFromRegistry<T extends Record<string, readonly InferableField[]>> = {
     [K in keyof T]: TypeFromEntrySchema<T[K]>;
 };
 /**
- * Define a reusable inline field group — a visual container in the editor that groups
- * related fields together without creating a nested data key. The group's fields are
- * stored flat alongside the other fields in the content file.
- *
- * Use this when you want consistent visual organization across schemas without
- * changing your content file structure.
- *
- * For data-nested grouping (fields stored under a named key), use defineNestedFieldGroup().
+ * Define a reusable inline field group — a visual container in the editor that groups related
+ * fields without creating a nested data key, so they are stored FLAT alongside the other fields.
+ * Use it for consistent visual organization across schemas without changing the content file
+ * structure; for data-nested grouping, use defineNestedFieldGroup().
  *
  * @example
  * const seoGroup = defineInlineFieldGroup({
  *   name: 'seo',
  *   label: 'SEO',
- *   fields: [
- *     { name: 'metaTitle', type: 'string', label: 'Meta Title' },
- *     { name: 'metaDescription', type: 'string', label: 'Meta Description' },
- *   ],
+ *   fields: [{ name: 'metaTitle', type: 'string', label: 'Meta Title' }],
  * })
- * // TypeFromEntrySchema: { ..., metaTitle: string, metaDescription: string }
+ * // TypeFromEntrySchema: { ..., metaTitle: string }
  */
 export declare const defineInlineFieldGroup: <const T extends {
     name: string;
@@ -346,30 +286,24 @@ export declare const defineInlineFieldGroup: <const T extends {
 /**
  * The recommended SEO field group, ready to drop into any entry schema.
  *
- * Emits the seven fields `extractSeoFields()` reads by default (`metaTitle`,
- * `metaDescription`, `ogImage`, `ogType`, `canonical`, `noindex`, `twitterCard`), so schema and
- * read side agree with no configuration. Every field is `required: false` — SEO metadata is
- * always optional, and an unset field must fall back rather than fail validation.
+ * Emits the seven fields `extractSeoFields()` reads by default (`metaTitle`, `metaDescription`,
+ * `ogImage`, `ogType`, `canonical`, `noindex`, `twitterCard`), so schema and read side agree with
+ * no configuration. Every field is `required: false`: SEO metadata is always optional, and an
+ * unset field must fall back rather than fail validation.
  *
- * **Flat by default.** The fields are stored flat in the content file (an inline group: a
- * visual container in the editor that adds no data key). Pass `group: 'seo'` for the nested
- * convention, which stores them under that key — and then pass the same `{ group: 'seo' }` to
- * `extractSeoFields` / `entryToMetadata`.
+ * **Flat by default** — an inline group, stored at the top level of the content file with no data
+ * key of its own. `group: 'seo'` nests them under that key instead, and the same
+ * `{ group: 'seo' }` must then be passed to `extractSeoFields` / `entryToMetadata`.
  *
  * @example
  * // Flat (recommended): frontmatter carries `metaTitle:` at the top level.
- * const pageSchema = defineEntrySchema([
- *   { name: 'title', type: 'string' },
- *   defineSeoFieldGroup(),
- * ])
- * // TypeFromEntrySchema: { title: string; metaTitle?: string; metaDescription?: string; ... }
+ * defineEntrySchema([{ name: 'title', type: 'string' }, defineSeoFieldGroup()])
+ * // TypeFromEntrySchema: { title: string; metaTitle?: string; ... }
  *
  * @example
- * // Nested: frontmatter carries `seo: { metaTitle: … }`.
- * const pageSchema = defineEntrySchema([defineSeoFieldGroup({ group: 'seo' })])
+ * // Nested: frontmatter carries `seo: { metaTitle: … }`, and the `seo` key is itself optional.
+ * defineEntrySchema([defineSeoFieldGroup({ group: 'seo' })])
  * const metadata = entryToMetadata(data, { group: 'seo' })
- * // TypeFromEntrySchema: { seo?: { metaTitle?: string; ... } } — the wrapper key itself is
- * // optional too, so an entry that sets no SEO fields at all can omit `seo` entirely.
  */
 declare const SEO_GROUP_FIELDS: readonly [{
     readonly name: "metaTitle";
@@ -438,9 +372,8 @@ export type NestedSeoFieldGroup<G extends string> = {
     fields: SeoGroupFields;
     type: 'object';
     /**
-     * The wrapper object itself is optional — an entry that sets no SEO fields at all omits the
-     * `seo` key entirely, matching the runtime validator (`entry-validator.ts`), which only
-     * enforces fields with `required: true`.
+     * The wrapper object itself is optional: an entry that sets no SEO fields omits the key
+     * entirely, matching `entry-validator.ts`, which enforces only `required: true` fields.
      */
     required: false;
 };
@@ -455,24 +388,18 @@ export declare function defineSeoFieldGroup<const G extends string>(opts: SeoFie
     group: G;
 }): NestedSeoFieldGroup<G>;
 /**
- * Define a reusable nested field group — a visual container in the editor that groups
- * related fields under a named key in the content file.
- *
- * Use this when the fields logically belong together as a sub-object (e.g., seo.metaTitle)
- * and you want that structure reflected in your content files.
- *
- * For visual-only grouping without data nesting, use defineInlineFieldGroup().
+ * Define a reusable nested field group — a visual container in the editor whose fields are
+ * stored under a named key in the content file (e.g. seo.metaTitle). Use it when the fields
+ * belong together as a sub-object and that structure should be reflected on disk; for
+ * visual-only grouping without data nesting, use defineInlineFieldGroup().
  *
  * @example
  * const seoGroup = defineNestedFieldGroup({
  *   name: 'seo',
  *   label: 'SEO',
- *   fields: [
- *     { name: 'metaTitle', type: 'string', label: 'Meta Title' },
- *     { name: 'metaDescription', type: 'string', label: 'Meta Description' },
- *   ],
+ *   fields: [{ name: 'metaTitle', type: 'string', label: 'Meta Title' }],
  * })
- * // TypeFromEntrySchema: { ..., seo: { metaTitle: string, metaDescription: string } }
+ * // TypeFromEntrySchema: { ..., seo: { metaTitle: string } }
  */
 export declare const defineNestedFieldGroup: <const T extends Omit<InferableField, "type"> & {
     fields: readonly InferableField[];
@@ -482,11 +409,10 @@ export declare const defineNestedFieldGroup: <const T extends Omit<InferableFiel
 /**
  * Define a reusable block template once and embed it in multiple entry schemas' `block` fields.
  *
- * A `block` field holds an ordered, repeatable list of heterogeneous section blocks discriminated by
- * a `template` key (the "flexible content" / "page blocks" pattern). Defining each template inline in
- * every schema's `templates` array duplicates the field definitions; this const-inference identity
- * helper (like defineEntrySchema) lets you define a template once and reuse it across schemas while
- * still deriving the correct discriminated-union type via TypeFromEntrySchema.
+ * A `block` field holds an ordered, repeatable list of heterogeneous section blocks discriminated
+ * by a `template` key (the "flexible content" / "page blocks" pattern). This const-inference
+ * identity helper (like defineEntrySchema) keeps a template's field definitions in one place
+ * across schemas while TypeFromEntrySchema still derives the discriminated union.
  *
  * @example
  * const heroBlock = defineBlockTemplate({
@@ -501,10 +427,7 @@ export declare const defineNestedFieldGroup: <const T extends Omit<InferableFiel
  *   name: 'cta',
  *   fields: [{ name: 'label', type: 'string' }, { name: 'href', type: 'string' }],
  * })
- *
- * // Reuse the same templates across multiple page schemas:
  * const pageSchema = defineEntrySchema([
- *   { name: 'title', type: 'string' },
  *   { name: 'sections', type: 'block', templates: [heroBlock, ctaBlock] },
  * ])
  * // TypeFromEntrySchema<typeof pageSchema>['sections'] narrows to:
@@ -518,20 +441,11 @@ export declare const defineBlockTemplate: <const T extends {
     fields: readonly InferableField[];
 }>(template: T) => T;
 /**
- * Extract one template's value shape out of a block field's discriminated union.
- *
- * `Blocks` is the union itself — e.g. `Page['sections'][number]`, the element type of
- * a `block` field as derived by `TypeFromEntrySchema` — not the surrounding array.
- * `N` is one of that union's `template` literals.
+ * Extract one template's value shape out of a block field's discriminated union. `Blocks` is the
+ * union itself — e.g. `Page['sections'][number]`, the element type of a `block` field as derived
+ * by `TypeFromEntrySchema` — not the surrounding array; `N` is one of its `template` literals.
  *
  * @example
- * const heroBlock = defineBlockTemplate({
- *   name: 'hero',
- *   fields: [{ name: 'headline', type: 'string' }],
- * })
- * const pageSchema = defineEntrySchema([
- *   { name: 'sections', type: 'block', templates: [heroBlock] },
- * ])
  * type Sections = TypeFromEntrySchema<typeof pageSchema>['sections'][number]
  * type HeroValue = BlockValueOf<Sections, 'hero'> // { headline: string }
  */
@@ -542,27 +456,18 @@ export type BlockValueOf<Blocks extends {
     template: N;
 }>['value'];
 /**
- * A mapped type over a block field's template names, requiring exactly one component
- * per template — no more, no fewer. This makes a block → component registry exhaustive
- * *by construction*: adding a template to the schema without adding its component is a
- * compile error, and a stray/renamed key in the registry is a compile error too. That is
- * strictly stronger than a runtime "did I handle every template?" guard, since it fails
- * the build instead of failing silently at render time.
+ * A mapped type over a block field's template names requiring exactly one component per template
+ * — no more, no fewer. That makes a block → component registry exhaustive *by construction*: a
+ * template added to the schema without its component, or a stray/renamed registry key, is a
+ * compile error rather than a silent gap at render time.
  *
- * Deliberately a type, not a `renderBlocks()` helper — the type says nothing about key
- * strategy, unknown-template handling, or how extra props reach each component, so it
- * imposes no rendering shape. Adopters write their own small loop (see the README's
- * "Block Component Registries" section for the recipe) and get exhaustiveness for free.
+ * Deliberately a type, not a `renderBlocks()` helper — it says nothing about key strategy,
+ * unknown-template handling or how extra props reach each component, so it imposes no rendering
+ * shape. Adopters write their own small loop (README, "Block Component Registries").
  *
  * @example
- * const registry: BlockComponentRegistry<Sections> = {
- *   hero: ({ data }) => <HeroSection {...data} />,
- *   // TS error here if 'hero' is missing, or if a key doesn't match a template name.
- * }
- *
- * // With extra props threaded to every block component:
- * type Props = { index: number }
- * const registryWithProps: BlockComponentRegistry<Sections, Props> = {
+ * // Extra props are threaded to every block component through the second parameter:
+ * const registry: BlockComponentRegistry<Sections, { index: number }> = {
  *   hero: ({ data, index }) => <HeroSection {...data} position={index} />,
  * }
  */
@@ -575,33 +480,23 @@ export type BlockComponentRegistry<Blocks extends {
     } & ExtraProps>;
 };
 /**
- * Const-inference identity helper for a reusable field fragment — a plain array of field
- * configs (not a group, not a template) that you spread into multiple schemas' `fields`.
- * Exists purely for discoverability: `defineEntrySchema` and `defineBlockTemplate` already
- * infer literal types from a `const fields = [...] as const` array, so spreading it works
- * without this helper too. Wrapping the definition site in `defineFieldFragment(...)` just
- * makes the pattern easy to find (and to grep for) alongside `defineInlineFieldGroup` and
+ * Const-inference identity helper for a reusable field fragment — a plain array of field configs
+ * (not a group, not a template) spread into several schemas' `fields`. Purely for
+ * discoverability: `defineEntrySchema` and `defineBlockTemplate` already infer literal types from
+ * a `const fields = [...] as const` array, so spreading works without this helper; wrapping the
+ * definition site just makes the pattern easy to find alongside `defineInlineFieldGroup` and
  * `defineNestedFieldGroup`.
  *
- * Use this over a field group when you don't want the fields visually boxed together in
- * the editor, or when different schemas need to override one field (e.g. a different
- * `label` or `required`) — spread the fragment, then follow it with an object that
- * overrides just the field(s) that differ for that schema.
+ * Use it over a field group when the fields should not be visually boxed together in the editor,
+ * or when schemas need to override one field (a different `label` or `required`) — spread the
+ * fragment, then follow it with an object overriding just the fields that differ.
  *
  * @example
  * const ctaFields = defineFieldFragment([
  *   { name: 'ctaLabel', type: 'string', label: 'Button Label' },
  *   { name: 'ctaHref', type: 'string', label: 'Button Link' },
  * ])
- *
- * const heroSchema = defineEntrySchema([
- *   { name: 'headline', type: 'string' },
- *   ...ctaFields,
- * ])
- * const bannerSchema = defineEntrySchema([
- *   { name: 'message', type: 'string' },
- *   ...ctaFields,
- * ])
+ * const heroSchema = defineEntrySchema([{ name: 'headline', type: 'string' }, ...ctaFields])
  */
 export declare const defineFieldFragment: <const T extends readonly InferableField[]>(fields: T) => T;
 export {};