canopycms 0.0.62 → 0.0.64

package/dist/entry-schema-registry.js

@@ -1,5 +1,6 @@
 import { countTitleFields, findInvalidTitleFields, findTitleFieldsInLists, } from './utils/title-field.js';
-import { countBodyFields, findInvalidBodyFields } from './utils/body-field.js';
+import { countBodyFields, findInvalidBodyFields, findReservedBodyFieldName, } from './utils/body-field.js';
+import { RESOLVED_REFERENCE_KEYS } from './entry-schema.js';
 import { flattenGroupFields } from './utils/flatten-group-fields.js';
 import { ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, } from './config/validation.js';
 /** Look up a field's type by dotted path (e.g., "meta.order").
@@ -124,6 +125,10 @@ export function createEntrySchemaRegistry(registry) {
         if (invalidBodyFields.length > 0) {
             throw new Error(`Entry schema registry entry "${key}": field "${invalidBodyFields[0]}" has isBody: true but is type "${findFieldType(schema, invalidBodyFields[0])}" — isBody is only valid on markdown or mdx fields`);
         }
+        const reservedBodyField = findReservedBodyFieldName(schema, RESOLVED_REFERENCE_KEYS);
+        if (reservedBodyField) {
+            throw new Error(`Entry schema registry entry "${key}": field "${reservedBodyField}" has isBody: true but "${reservedBodyField}" is reserved — reference resolution sets ${RESOLVED_REFERENCE_KEYS.map((k) => `"${k}"`).join(', ')} on a resolved reference, and a body field with one of those names would overwrite it. Rename the field (the body's field name is yours to choose; only these four are reserved).`);
+        }
         // Field-shape checks moved here from validateCanopyConfig — these used to walk
         // the (now-removed) inline-config schema; the registry is now the canonical
         // entry point for entry schemas, so they run here.
@@ -193,4 +198,3 @@ export async function validateEntrySchemaRegistry(entrySchemaRegistry, contentPa
         throw new Error(`Entry schema registry validation failed:\n${errors.map((e) => `  - ${e}`).join('\n')}`);
     }
 }
-//# sourceMappingURL=entry-schema-registry.js.map

package/dist/entry-schema.d.ts

@@ -1,3 +1,4 @@
+import type { ComponentType } from 'react';
 /** Structural constraint for fields that can be inferred by TypeFromEntrySchema. */
 type InferableField = {
     name: string;
@@ -11,13 +12,88 @@ type InferableField = {
         name: string;
         fields: readonly 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.
+     */
+    options?: readonly (string | {
+        label: string;
+        value: string;
+    })[];
     /** For reference fields: the target collection's schema (from defineEntrySchema) to infer resolved types. */
     resolvedSchema?: readonly InferableField[];
     /** For reference fields: filter by entry type name (e.g., ['partner']). */
     entryTypes?: readonly string[];
     /** For reference fields: collection paths to scope the search. */
     collections?: readonly string[];
+    /** For reference fields: resolve the target's body too. See ReferenceFieldConfig.includeBody. */
+    includeBody?: boolean;
 };
+/**
+ * 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.
+ */
+export declare const RESOLVED_REFERENCE_KEYS: readonly ["id", "slug", "collection", "urlPath"];
+/**
+ * Runtime counterpart of {@link ResolvedReferenceMeta}'s keys — the names reference resolution
+ * reserves on a resolved value. Kept beside the type so the two cannot drift, and consumed by
+ * both the resolver (which applies these last, so a target cannot shadow them) and the entry
+ * schema registry (which rejects a body field named one of them, since the body is assigned by
+ * key and would otherwise be the one way around that ordering).
+ */
+export interface ResolvedReferenceMeta {
+    /** The referenced entry's 12-char content ID. */
+    id: string;
+    /** The referenced entry's slug. */
+    slug: string;
+    /** The referenced entry's collection logical path (e.g. `content/snippets`). */
+    collection: string;
+    /** URL path for the referenced entry, e.g. `/guides/getting-started`. */
+    urlPath: string;
+}
+/**
+ * Assemble a resolved reference: the target's own data, then its body if the field asked to
+ * 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.
+ */
+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
@@ -30,11 +106,61 @@ type FlattenInlineGroups<Fields extends readonly InferableField[]> = Fields exte
     type: 'group';
     fields: infer GFields extends readonly InferableField[];
 } ? [...FlattenInlineGroups<GFields>, ...FlattenInlineGroups<Rest>] : [Head, ...FlattenInlineGroups<Rest>] : [];
-type RequiredValue<F extends InferableField, V> = F['required'] extends false ? V | undefined : V;
-type ScalarValue<F extends InferableField, V> = RequiredValue<F, F['list'] extends true ? V[] : V>;
+/**
+ * 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.
+ */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * The value type of a field, WITHOUT any optionality. Optionality is carried solely by
+ * the `?` modifier that InferContentShape applies, never duplicated as `| undefined`.
+ */
+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`.
+ */
+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.
+ */
+type SelectValue<F extends InferableField> = F extends {
+    options: infer O extends readonly unknown[];
+} ? [O[number]] extends [never] ? string : SelectOptionValue<O[number]> : string;
 type ObjectValue<F extends InferableField & {
     fields: readonly InferableField[];
-}> = RequiredValue<F, F['list'] extends true ? Array<InferContentShape<F['fields']>> : InferContentShape<F['fields']>>;
+}> = 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.
  *
@@ -55,7 +181,7 @@ type BlockValue<F extends InferableField & {
         name: string;
         fields: readonly InferableField[];
     }>;
-}> = RequiredValue<F, Array<DistributeBlockTemplate<F['templates'][number]>>>;
+}> = 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
@@ -88,10 +214,10 @@ type FieldValue<F extends InferableField> = F extends {
     }>>>;
 }> : F extends {
     type: 'select';
-} ? ScalarValue<F, string | number> : F extends {
+} ? ScalarValue<F, SelectValue<F>> : F extends {
     type: 'reference';
     resolvedSchema: infer S;
-} ? ScalarValue<F, InferContentShape<Extract<S, readonly InferableField[]>> | null> : F extends {
+} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>> & ResolvedReferenceMeta) | null> : F extends {
     type: 'reference';
 } ? ScalarValue<F, string | null> : F extends {
     type: 'image';
@@ -107,15 +233,23 @@ type FieldValue<F extends InferableField> = F extends {
  * - Objects become nested objects
  * - Blocks become arrays of tagged templates with their value shapes
  * - Lists become arrays of the scalar/object type
- * - Non-required fields include `undefined`
+ * - 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.
  *
  * Works with any structurally compatible array; importing FieldConfig is not required.
  */
-type InferContentShape<Fields extends readonly InferableField[]> = {
-    [F in FlattenInlineGroups<Fields>[number] as F['name']]: FieldValue<F>;
-};
+type InferContentShape<Fields extends readonly InferableField[]> = Simplify<{
+    [F in FlattenInlineGroups<Fields>[number] as F['required'] extends false ? never : F['name']]: FieldValue<F>;
+} & {
+    [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`.
  */
@@ -187,6 +321,117 @@ export declare const defineInlineFieldGroup: <const T extends {
 }>(group: T) => T & {
     readonly type: "group";
 };
+/**
+ * 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.
+ *
+ * **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`.
+ *
+ * @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; ... }
+ *
+ * @example
+ * // Nested: frontmatter carries `seo: { metaTitle: … }`.
+ * const pageSchema = 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";
+    readonly type: "string";
+    readonly label: "Meta Title";
+    readonly description: "Overrides the page title in search results and social cards.";
+    readonly required: false;
+}, {
+    readonly name: "metaDescription";
+    readonly type: "string";
+    readonly label: "Meta Description";
+    readonly description: "Summary shown under the title in search results.";
+    readonly required: false;
+}, {
+    readonly name: "ogImage";
+    readonly type: "string";
+    readonly label: "Social Image URL";
+    readonly description: "Image for social cards. Site-relative or absolute.";
+    readonly required: false;
+}, {
+    readonly name: "ogType";
+    readonly type: "select";
+    readonly label: "OpenGraph Type";
+    readonly options: readonly ["website", "article", "profile"];
+    readonly required: false;
+}, {
+    readonly name: "canonical";
+    readonly type: "string";
+    readonly label: "Canonical URL";
+    readonly description: "Set only to point at a different canonical copy of this page.";
+    readonly required: false;
+}, {
+    readonly name: "noindex";
+    readonly type: "boolean";
+    readonly label: "Hide from search engines";
+    readonly description: "Marks the page noindex AND drops it from the sitemap.";
+    readonly required: false;
+}, {
+    readonly name: "twitterCard";
+    readonly type: "select";
+    readonly label: "Twitter Card";
+    readonly options: readonly ["summary", "summary_large_image"];
+    readonly required: false;
+}];
+/** The seven recommended SEO fields, as a literal-typed field tuple. */
+export type SeoGroupFields = typeof SEO_GROUP_FIELDS;
+interface SeoFieldGroupOptions {
+    /** Editor label for the group. Default 'SEO'. */
+    label?: string;
+    /** Editor description for the group. */
+    description?: string;
+}
+/** Flat (inline) SEO group: fields are stored at the top level of the content file. */
+export type InlineSeoFieldGroup = {
+    name: 'seo';
+    label: string;
+    description?: string;
+    fields: SeoGroupFields;
+    type: 'group';
+};
+/** Nested SEO group: fields are stored under the group's own key in the content file. */
+export type NestedSeoFieldGroup<G extends string> = {
+    name: G;
+    label: string;
+    description?: 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`.
+     */
+    required: false;
+};
+export declare function defineSeoFieldGroup(opts?: SeoFieldGroupOptions & {
+    group?: undefined;
+}): InlineSeoFieldGroup;
+export declare function defineSeoFieldGroup<const G extends string>(opts: SeoFieldGroupOptions & {
+    /**
+     * Nest the fields under this data key instead of storing them flat. Must match the `group`
+     * option passed to `extractSeoFields` / `entryToMetadata`.
+     */
+    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.
@@ -250,5 +495,91 @@ export declare const defineBlockTemplate: <const T extends {
     description?: string;
     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.
+ *
+ * @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 }
+ */
+export type BlockValueOf<Blocks extends {
+    template: string;
+    value: unknown;
+}, N extends Blocks['template']> = Extract<Blocks, {
+    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.
+ *
+ * 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.
+ *
+ * @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> = {
+ *   hero: ({ data, index }) => <HeroSection {...data} position={index} />,
+ * }
+ */
+export type BlockComponentRegistry<Blocks extends {
+    template: string;
+    value: unknown;
+}, ExtraProps extends object = object> = {
+    [N in Blocks['template']]: ComponentType<{
+        data: BlockValueOf<Blocks, N>;
+    } & 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
+ * `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.
+ *
+ * @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,
+ * ])
+ */
+export declare const defineFieldFragment: <const T extends readonly InferableField[]>(fields: T) => T;
 export {};
-//# sourceMappingURL=entry-schema.d.ts.map

package/dist/entry-schema.js

@@ -1,3 +1,52 @@
+// The recommended SEO field names, shared with the read side (extractSeoFields) so the schema
+// this module emits and the fields that module looks for cannot drift apart.
+import { DEFAULT_SEO_FIELD_NAMES } from './static/seo.js';
+/**
+ * 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.
+ */
+export const RESOLVED_REFERENCE_KEYS = ['id', 'slug', 'collection', 'urlPath'];
+/**
+ * Assemble a resolved reference: the target's own data, then its body if the field asked to
+ * 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.
+ */
+export function buildResolvedReference(data, meta, body) {
+    const resolved = { ...data };
+    // Truthiness, matching `readEntryData`'s own merge: a listed md entry with an empty body
+    // carries no body key, so resolving one to `''` would reintroduce a listed-vs-resolved
+    // shape disagreement.
+    if (body && body.value)
+        resolved[body.fieldName] = body.value;
+    resolved.id = meta.id;
+    resolved.slug = meta.slug;
+    resolved.collection = meta.collection;
+    resolved.urlPath = meta.urlPath;
+    return resolved;
+}
 /**
  * Helper to define entry schema field arrays with literal inference without sprinkling `as const`.
  */
@@ -24,6 +73,97 @@ export const defineEntrySchema = (fields) => fields;
  * // TypeFromEntrySchema: { ..., metaTitle: string, metaDescription: string }
  */
 export const defineInlineFieldGroup = (group) => ({ ...group, type: 'group' });
+/**
+ * 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.
+ *
+ * **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`.
+ *
+ * @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; ... }
+ *
+ * @example
+ * // Nested: frontmatter carries `seo: { metaTitle: … }`.
+ * const pageSchema = 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.
+ */
+const SEO_GROUP_FIELDS = [
+    {
+        name: DEFAULT_SEO_FIELD_NAMES.title,
+        type: 'string',
+        label: 'Meta Title',
+        description: 'Overrides the page title in search results and social cards.',
+        required: false,
+    },
+    {
+        name: DEFAULT_SEO_FIELD_NAMES.description,
+        type: 'string',
+        label: 'Meta Description',
+        description: 'Summary shown under the title in search results.',
+        required: false,
+    },
+    {
+        name: DEFAULT_SEO_FIELD_NAMES.ogImage,
+        type: 'string',
+        label: 'Social Image URL',
+        description: 'Image for social cards. Site-relative or absolute.',
+        required: false,
+    },
+    {
+        name: DEFAULT_SEO_FIELD_NAMES.ogType,
+        type: 'select',
+        label: 'OpenGraph Type',
+        options: ['website', 'article', 'profile'],
+        required: false,
+    },
+    {
+        name: DEFAULT_SEO_FIELD_NAMES.canonical,
+        type: 'string',
+        label: 'Canonical URL',
+        description: 'Set only to point at a different canonical copy of this page.',
+        required: false,
+    },
+    {
+        name: DEFAULT_SEO_FIELD_NAMES.noindex,
+        type: 'boolean',
+        label: 'Hide from search engines',
+        description: 'Marks the page noindex AND drops it from the sitemap.',
+        required: false,
+    },
+    {
+        name: DEFAULT_SEO_FIELD_NAMES.twitterCard,
+        type: 'select',
+        label: 'Twitter Card',
+        options: ['summary', 'summary_large_image'],
+        required: false,
+    },
+];
+export function defineSeoFieldGroup(opts = {}) {
+    const base = {
+        label: opts.label ?? 'SEO',
+        ...(opts.description ? { description: opts.description } : {}),
+        fields: SEO_GROUP_FIELDS,
+    };
+    // 'object' nests the fields under `name`; 'group' is the inline (flat) container, whose name
+    // is an editor-only label anchor and contributes no key to the content file.
+    return opts.group
+        ? { ...base, name: opts.group, type: 'object', required: false }
+        : { ...base, name: 'seo', type: 'group' };
+}
 /**
  * Define a reusable nested field group — a visual container in the editor that groups
  * related fields under a named key in the content file.
@@ -78,4 +218,33 @@ export const defineNestedFieldGroup = (group) => ({ ...group, type: 'object' });
  * //        | { template: 'cta';  value: { label: string; href: string } }>
  */
 export const defineBlockTemplate = (template) => template;
-//# sourceMappingURL=entry-schema.js.map
+/**
+ * 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
+ * `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.
+ *
+ * @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,
+ * ])
+ */
+export const defineFieldFragment = (fields) => fields;

package/dist/git-manager.d.ts

@@ -1,5 +1,5 @@
 import { type SimpleGitOptions, type StatusResult } from 'simple-git';
-import type { OperatingMode } from './operating-mode';
+import type { OperatingMode } from './operating-mode/index.js';
 /**
  * Exported for GitManager's own use (see `this.git.env(...)` above),
  * worker/cms-worker.ts's push-rejection-classified GitHub calls
@@ -423,4 +423,3 @@ export declare class GitManager {
     createOrphanSettingsBranch(branchName: string, initialFiles: Record<string, string>): Promise<void>;
     private createOrphanSettingsBranchInner;
 }
-//# sourceMappingURL=git-manager.d.ts.map

package/dist/git-manager.js

@@ -1282,4 +1282,3 @@ export class GitManager {
         log.debug('git', 'Orphan settings branch created', { branchName });
     }
 }
-//# sourceMappingURL=git-manager.js.map

package/dist/github-service.d.ts

@@ -1,5 +1,5 @@
 import { Octokit } from '@octokit/rest';
-import type { CanopyConfig } from './config';
+import type { CanopyConfig } from './config/index.js';
 /**
  * Retry primary rate limits at most twice and only for short waits; beyond
  * that, task-level retry/backoff (worker) or the caller's error path takes
@@ -156,4 +156,3 @@ export declare class GitHubService {
  * Returns null if not applicable (missing token, not GitHub, etc.)
  */
 export declare const createGitHubService: (config: CanopyConfig, remoteUrl?: string) => GitHubService | null;
-//# sourceMappingURL=github-service.d.ts.map

package/dist/github-service.js

@@ -359,4 +359,3 @@ export const createGitHubService = (config, remoteUrl) => {
         return null;
     }
 };
-//# sourceMappingURL=github-service.js.map