@elytracms/core 0.0.6

package/dist/cms-core/documents.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+/**
+ * A locale code (BCP-47-ish, e.g. `en`, `en-US`, `de`). Kept as a plain
+ * non-empty string so unusual locales still parse; validity against a project's
+ * declared locale set is checked semantically (EC-018).
+ */
+export const localeSchema = z.string().min(1);
+/**
+ * A document identity (EC-017): the stable pointer to a piece of content. A
+ * document belongs to exactly one collection and has a stable id. For localized
+ * content the *identity* is collection+id; a specific localized variant is
+ * addressed by additionally carrying a locale (see `LocaleAwareDocumentRef`).
+ */
+export const documentRefSchema = z.object({
+    collection: z.string().min(1),
+    id: z.string().min(1),
+});
+/** A document identity together with a specific locale (EC-018). */
+export const localeAwareDocumentRefSchema = documentRefSchema.extend({
+    locale: localeSchema,
+});
+/** Stable string key for a document identity. */
+export function documentKey(ref) {
+    return `${ref.collection}:${ref.id}`;
+}
+/** Stable string key for a locale-aware document identity. */
+export function localeAwareDocumentKey(ref) {
+    return `${ref.collection}:${ref.id}@${ref.locale}`;
+}
+/** Equality on document identity (collection + id), ignoring locale. */
+export function documentRefEquals(a, b) {
+    return a.collection === b.collection && a.id === b.id;
+}
+/**
+ * Target state of a publish/unpublish *action* (EC-021). No longer a stored
+ * document field (EC-224 retired it — publish-ness is the version pointer, see
+ * `publishedVersion`); this enum names the *intent* of a bulk publish/unpublish
+ * action (the studio's `applyState` contract), not a property a row carries.
+ */
+export const publicationStateSchema = z.enum(['draft', 'published']);
+/**
+ * A stored document (EC-016/017/018). The live row is the continuous DRAFT
+ * (the Sanity model, EC-224). Holds:
+ * - identity (`collection` + `id`),
+ * - non-localized field values in `values`,
+ * - per-locale field values in `localized` (only for localized fields).
+ *
+ * Publish-ness is NOT a field here: a document is published when an append-only
+ * version is pinned via the record's `publishedVersion` pointer (EC-224). The
+ * delivery `published` perspective serves that pinned snapshot; this live row
+ * is always the working draft.
+ */
+export const documentSchema = z.object({
+    collection: z.string().min(1),
+    id: z.string().min(1),
+    /** Non-localized field values shared across locales. */
+    values: z.record(z.string(), z.unknown()).default({}),
+    /** Per-locale overrides for localized fields: `{ [locale]: { [field]: value } }`. */
+    localized: z.record(localeSchema, z.record(z.string(), z.unknown())).optional(),
+    /** The default locale this document was authored in (EC-018 fallback source). */
+    defaultLocale: localeSchema.optional(),
+});
+/** The identity of a stored document. */
+export function refOf(doc) {
+    return { collection: doc.collection, id: doc.id };
+}
+//# sourceMappingURL=documents.js.map

package/dist/cms-core/documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../src/cms-core/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAG7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACtB,CAAC,CAAA;AAGF,oEAAoE;AACpE,MAAM,CAAC,MAAM,4BAA4B,GAAG,iBAAiB,CAAC,MAAM,CAAC;IACnE,MAAM,EAAE,YAAY;CACrB,CAAC,CAAA;AAGF,iDAAiD;AACjD,MAAM,UAAU,WAAW,CAAC,GAAgB;IAC1C,OAAO,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,EAAE,EAAE,CAAA;AACtC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,sBAAsB,CAAC,GAA2B;IAChE,OAAO,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,EAAE,CAAA;AACpD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,iBAAiB,CAAC,CAAc,EAAE,CAAc;IAC9D,OAAO,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAA;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAA;AAUpE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrD,qFAAqF;IACrF,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC/E,iFAAiF;IACjF,aAAa,EAAE,YAAY,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAA;AAGF,yCAAyC;AACzC,MAAM,UAAU,KAAK,CAAC,GAAgB;IACpC,OAAO,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAA;AACnD,CAAC"}

package/dist/cms-core/envelopes.d.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import type { DocumentRef } from './documents';
+/**
+ * Self-describing content envelopes (EC-277, vision AD-15).
+ *
+ * A value's *type* used to be inferred from the schema at read time — a stored
+ * relation was a bare `{ collection, id }`, an asset a bare id string, a rich-text
+ * internal link a fuzzy `elytra:document/…` href. Interpreting those required the
+ * schema (or the component manifest), which is exactly why structural derivation
+ * (the reference index, where-used, validation) had to run in client/app code.
+ *
+ * Self-describing data inverts this: every node that *isn't* a plain scalar carries
+ * an explicit `type` discriminator at rest, so a structural walk over content can
+ * recognise references/assets/blocks **without the schema** — making derivation a
+ * pure function of data the backend holds (AD-6 maintained-in-Convex).
+ *
+ * One discriminator, `type`, unifies with rich-text — ProseMirror nodes already
+ * self-describe via `type` (`{ type: 'paragraph' }`), and a typed reference/asset/
+ * block node is the *same* concept, not a separate one. `_type` elsewhere would
+ * manufacture a seam through one content model.
+ *
+ * Scope note: only the *fixed-shape* nodes we fully own get an envelope here —
+ * references, assets, blocks. User-content objects / array-items stay structural
+ * (a plain bag walked key-by-key); their self-description comes free from their
+ * typed subfields, and NOT wrapping them avoids `type` colliding with a user field
+ * literally named `type`. A block already self-types via `componentId`; `type:
+ * 'block'` is added only for walk-uniformity and is accepted-but-not-required.
+ */
+/** Node `type` discriminators owned by the envelope layer. */
+export declare const REFERENCE_NODE_TYPE = "reference";
+export declare const ASSET_NODE_TYPE = "asset";
+export declare const BLOCK_NODE_TYPE = "block";
+/**
+ * Field names reserved by the self-describing layer. The write-time schema lens
+ * (validation) rejects a user field declared with one of these names — the single
+ * cost of unifying on a plain `type` discriminator instead of a `_`-namespaced one,
+ * enforced at the one write chokepoint we already own.
+ */
+export declare const RESERVED_NODE_KEYS: ReadonlySet<string>;
+/**
+ * A self-typed reference to a document (EC-277). Wraps the collection-scoped
+ * {@link DocumentRef} payload (kept as-is — it matches the reference index key
+ * `collection:id`) behind an explicit `type: 'reference'` discriminator.
+ */
+export declare const referenceNodeSchema: z.ZodObject<{
+    collection: z.ZodString;
+    id: z.ZodString;
+    type: z.ZodLiteral<"reference">;
+}, z.core.$strip>;
+export type ReferenceNode = z.infer<typeof referenceNodeSchema>;
+/** A self-typed reference to an asset (EC-277). Replaces the bare asset-id string. */
+export declare const assetNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"asset">;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type AssetNode = z.infer<typeof assetNodeSchema>;
+/** Wrap a document identity in a self-typed reference node. */
+export declare function referenceNode(ref: DocumentRef): ReferenceNode;
+/** Wrap an asset id in a self-typed asset node. */
+export declare function assetNode(id: string): AssetNode;
+/** Structural test for a self-typed reference node. */
+export declare function isReferenceNode(value: unknown): value is ReferenceNode;
+/** Structural test for a self-typed asset node. */
+export declare function isAssetNode(value: unknown): value is AssetNode;
+/** The document identity carried by a reference node (strips the discriminator). */
+export declare function refOfReferenceNode(node: ReferenceNode): DocumentRef;
+/**
+ * Read a document identity out of a stored relation value, accepting BOTH the
+ * self-typed envelope (`{ type: 'reference', collection, id }`) and a legacy bare
+ * `{ collection, id }`. This is the single unwrap every relation reader routes
+ * through — and the lazy-on-read half of the EC-277 migration: content that has not
+ * yet been upgraded still reads correctly. Returns `undefined` for anything else.
+ */
+export declare function readDocumentRef(value: unknown): DocumentRef | undefined;
+/**
+ * Read an asset id out of a stored asset value, accepting BOTH the self-typed
+ * envelope (`{ type: 'asset', id }`) and a legacy bare id string. The asset twin of
+ * {@link readDocumentRef}. Returns `undefined` for anything else.
+ */
+export declare function readAssetId(value: unknown): string | undefined;

package/dist/cms-core/envelopes.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { documentRefSchema } from './documents';
+/**
+ * Self-describing content envelopes (EC-277, vision AD-15).
+ *
+ * A value's *type* used to be inferred from the schema at read time — a stored
+ * relation was a bare `{ collection, id }`, an asset a bare id string, a rich-text
+ * internal link a fuzzy `elytra:document/…` href. Interpreting those required the
+ * schema (or the component manifest), which is exactly why structural derivation
+ * (the reference index, where-used, validation) had to run in client/app code.
+ *
+ * Self-describing data inverts this: every node that *isn't* a plain scalar carries
+ * an explicit `type` discriminator at rest, so a structural walk over content can
+ * recognise references/assets/blocks **without the schema** — making derivation a
+ * pure function of data the backend holds (AD-6 maintained-in-Convex).
+ *
+ * One discriminator, `type`, unifies with rich-text — ProseMirror nodes already
+ * self-describe via `type` (`{ type: 'paragraph' }`), and a typed reference/asset/
+ * block node is the *same* concept, not a separate one. `_type` elsewhere would
+ * manufacture a seam through one content model.
+ *
+ * Scope note: only the *fixed-shape* nodes we fully own get an envelope here —
+ * references, assets, blocks. User-content objects / array-items stay structural
+ * (a plain bag walked key-by-key); their self-description comes free from their
+ * typed subfields, and NOT wrapping them avoids `type` colliding with a user field
+ * literally named `type`. A block already self-types via `componentId`; `type:
+ * 'block'` is added only for walk-uniformity and is accepted-but-not-required.
+ */
+/** Node `type` discriminators owned by the envelope layer. */
+export const REFERENCE_NODE_TYPE = 'reference';
+export const ASSET_NODE_TYPE = 'asset';
+export const BLOCK_NODE_TYPE = 'block';
+/**
+ * Field names reserved by the self-describing layer. The write-time schema lens
+ * (validation) rejects a user field declared with one of these names — the single
+ * cost of unifying on a plain `type` discriminator instead of a `_`-namespaced one,
+ * enforced at the one write chokepoint we already own.
+ */
+export const RESERVED_NODE_KEYS = new Set(['type']);
+/**
+ * A self-typed reference to a document (EC-277). Wraps the collection-scoped
+ * {@link DocumentRef} payload (kept as-is — it matches the reference index key
+ * `collection:id`) behind an explicit `type: 'reference'` discriminator.
+ */
+export const referenceNodeSchema = documentRefSchema.extend({
+    type: z.literal(REFERENCE_NODE_TYPE),
+});
+/** A self-typed reference to an asset (EC-277). Replaces the bare asset-id string. */
+export const assetNodeSchema = z.object({
+    type: z.literal(ASSET_NODE_TYPE),
+    id: z.string().min(1),
+});
+// --- Constructors -----------------------------------------------------------------
+/** Wrap a document identity in a self-typed reference node. */
+export function referenceNode(ref) {
+    return { type: REFERENCE_NODE_TYPE, collection: ref.collection, id: ref.id };
+}
+/** Wrap an asset id in a self-typed asset node. */
+export function assetNode(id) {
+    return { type: ASSET_NODE_TYPE, id };
+}
+// --- Guards -----------------------------------------------------------------------
+function asNodeRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Structural test for a self-typed reference node. */
+export function isReferenceNode(value) {
+    const record = asNodeRecord(value);
+    return (record !== undefined &&
+        record.type === REFERENCE_NODE_TYPE &&
+        typeof record.collection === 'string' &&
+        record.collection.length > 0 &&
+        typeof record.id === 'string' &&
+        record.id.length > 0);
+}
+/** Structural test for a self-typed asset node. */
+export function isAssetNode(value) {
+    const record = asNodeRecord(value);
+    return (record !== undefined &&
+        record.type === ASSET_NODE_TYPE &&
+        typeof record.id === 'string' &&
+        record.id.length > 0);
+}
+/** The document identity carried by a reference node (strips the discriminator). */
+export function refOfReferenceNode(node) {
+    return { collection: node.collection, id: node.id };
+}
+// --- Tolerant readers (the lazy-on-read migration net) ----------------------------
+/**
+ * Read a document identity out of a stored relation value, accepting BOTH the
+ * self-typed envelope (`{ type: 'reference', collection, id }`) and a legacy bare
+ * `{ collection, id }`. This is the single unwrap every relation reader routes
+ * through — and the lazy-on-read half of the EC-277 migration: content that has not
+ * yet been upgraded still reads correctly. Returns `undefined` for anything else.
+ */
+export function readDocumentRef(value) {
+    if (isReferenceNode(value))
+        return { collection: value.collection, id: value.id };
+    const record = asNodeRecord(value);
+    if (record !== undefined &&
+        record.type === undefined &&
+        typeof record.collection === 'string' &&
+        record.collection.length > 0 &&
+        typeof record.id === 'string' &&
+        record.id.length > 0) {
+        return { collection: record.collection, id: record.id };
+    }
+    return undefined;
+}
+/**
+ * Read an asset id out of a stored asset value, accepting BOTH the self-typed
+ * envelope (`{ type: 'asset', id }`) and a legacy bare id string. The asset twin of
+ * {@link readDocumentRef}. Returns `undefined` for anything else.
+ */
+export function readAssetId(value) {
+    if (isAssetNode(value))
+        return value.id;
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    return undefined;
+}
+//# sourceMappingURL=envelopes.js.map

package/dist/cms-core/envelopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopes.js","sourceRoot":"","sources":["../../src/cms-core/envelopes.ts"],"names":[],"mappings":"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"}

package/dist/cms-core/fields.d.ts

@@ -0,0 +1,220 @@
+import { z } from 'zod';
+/**
+ * Provider-neutral field type catalogue (brief §7.4). Relation and asset are
+ * first-class field types but carry extra config (target collection, cardinality),
+ * so they're modelled as discriminated variants below rather than bare strings.
+ */
+export declare const fieldTypeSchema: z.ZodEnum<{
+    number: "number";
+    boolean: "boolean";
+    object: "object";
+    date: "date";
+    text: "text";
+    select: "select";
+    richText: "richText";
+    relation: "relation";
+    asset: "asset";
+    blocks: "blocks";
+}>;
+export type FieldType = z.infer<typeof fieldTypeSchema>;
+/** How many related documents a relation field points at. */
+export declare const cardinalitySchema: z.ZodEnum<{
+    one: "one";
+    many: "many";
+}>;
+export type Cardinality = z.infer<typeof cardinalitySchema>;
+/**
+ * Where a field-def is valid (EC-190 "props as fields"): a CMS document field, a
+ * component prop, or both. The same field-def vocabulary drives documents AND
+ * component props through one inspector/form engine — `context` only gates which
+ * document-only attributes apply, never the stored value or emitted JSON Schema.
+ */
+export declare const fieldContextSchema: z.ZodEnum<{
+    document: "document";
+    prop: "prop";
+    both: "both";
+}>;
+export type FieldContext = z.infer<typeof fieldContextSchema>;
+/**
+ * Preferred input control when a field type maps to several presentation forms
+ * (e.g. a `text` field rendered as a single input, a textarea, a colour picker, or
+ * a JSON editor). Presentation only — never affects validation or stored values.
+ */
+export declare const fieldControlSchema: z.ZodEnum<{
+    input: "input";
+    textarea: "textarea";
+    color: "color";
+    json: "json";
+}>;
+export type FieldControl = z.infer<typeof fieldControlSchema>;
+/**
+ * Form/authoring metadata for a field (brief §7.4: groups/tabs/labels/order).
+ * Pure presentation hints — never affects validation or stored values.
+ */
+export declare const fieldFormMetaSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+    tab: z.ZodOptional<z.ZodString>;
+    order: z.ZodOptional<z.ZodNumber>;
+    readOnly: z.ZodOptional<z.ZodBoolean>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    control: z.ZodOptional<z.ZodEnum<{
+        input: "input";
+        textarea: "textarea";
+        color: "color";
+        json: "json";
+    }>>;
+    inlineEditable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type FieldFormMeta = z.infer<typeof fieldFormMetaSchema>;
+/**
+ * Declarative validation metadata for a field (brief §7.4). These constraints
+ * are provider-neutral and drive both runtime validation (`validateDocument`)
+ * and JSON Schema output. They never throw — violations surface as structured
+ * issues.
+ */
+export declare const fieldValidationSchema: z.ZodObject<{
+    required: z.ZodOptional<z.ZodBoolean>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    pattern: z.ZodOptional<z.ZodString>;
+    unique: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type FieldValidation = z.infer<typeof fieldValidationSchema>;
+/** A single allowed option for a `select` field. */
+export declare const selectOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SelectOption = z.infer<typeof selectOptionSchema>;
+/** A schema of just the shared base attributes — the source for {@link BaseFieldDef}. */
+declare const baseFieldObjectSchema: z.ZodObject<{
+    name: z.ZodString;
+    localized: z.ZodOptional<z.ZodBoolean>;
+    filterable: z.ZodOptional<z.ZodBoolean>;
+    context: z.ZodOptional<z.ZodEnum<{
+        document: "document";
+        prop: "prop";
+        both: "both";
+    }>>;
+    default: z.ZodOptional<z.ZodUnknown>;
+    form: z.ZodOptional<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        group: z.ZodOptional<z.ZodString>;
+        tab: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+        readOnly: z.ZodOptional<z.ZodBoolean>;
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        control: z.ZodOptional<z.ZodEnum<{
+            input: "input";
+            textarea: "textarea";
+            color: "color";
+            json: "json";
+        }>>;
+        inlineEditable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    validation: z.ZodOptional<z.ZodObject<{
+        required: z.ZodOptional<z.ZodBoolean>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        pattern: z.ZodOptional<z.ZodString>;
+        unique: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Attributes every field-def carries, derived from {@link baseFieldShape}. */
+type BaseFieldDef = z.infer<typeof baseFieldObjectSchema>;
+/**
+ * A field definition (the shape {@link fieldDefSchema} parses to). Written
+ * explicitly rather than via `z.infer` because the `object` variant is recursive
+ * — its `fields` reference `FieldDef` itself — and TypeScript cannot infer a
+ * self-referential `z.infer`. The schema below is annotated with this type and the
+ * two are kept in lock-step (`object-field.test.ts` round-trips against drift).
+ *
+ * A discriminated union on `type` so relation/asset/select/object carry exactly
+ * the extra config they need and nothing more.
+ */
+export type FieldDef = (BaseFieldDef & {
+    type: 'text';
+}) | (BaseFieldDef & {
+    type: 'number';
+}) | (BaseFieldDef & {
+    type: 'boolean';
+}) | (BaseFieldDef & {
+    type: 'date';
+}) | (BaseFieldDef & {
+    type: 'select';
+    options: SelectOption[];
+    multiple?: boolean;
+}) | (BaseFieldDef & {
+    type: 'richText';
+    allow?: string[];
+}) | (BaseFieldDef & {
+    type: 'relation';
+    target: string;
+    cardinality: Cardinality;
+    populate?: boolean;
+    strict?: boolean;
+}) | (BaseFieldDef & {
+    type: 'asset';
+    cardinality: Cardinality;
+    accept?: string[];
+}) | (BaseFieldDef & {
+    type: 'blocks';
+    allow?: string[];
+    cardinality: Cardinality;
+}) | (BaseFieldDef & {
+    type: 'object';
+    fields: FieldDef[];
+    cardinality: Cardinality;
+});
+/**
+ * The Zod schema mirroring {@link FieldDef}. The `object` member's `fields` is
+ * wrapped in `z.lazy` so the schema can reference itself, while the discriminator
+ * stays a static `z.literal('object')` so `discriminatedUnion` can still read it
+ * at construction time. The explicit `z.ZodType<FieldDef>` annotation breaks the
+ * self-referential inference cycle; the cast reconciles the parsed output (where
+ * defaulted `cardinality` is always present) with the union's optional-input type.
+ */
+export declare const fieldDefSchema: z.ZodType<FieldDef>;
+/** A relation field, narrowed. */
+export type RelationFieldDef = Extract<FieldDef, {
+    type: 'relation';
+}>;
+/** An asset field, narrowed. */
+export type AssetFieldDef = Extract<FieldDef, {
+    type: 'asset';
+}>;
+/** A select field, narrowed. */
+export type SelectFieldDef = Extract<FieldDef, {
+    type: 'select';
+}>;
+/** A composition (blocks) field, narrowed (EC-186). */
+export type BlocksFieldDef = Extract<FieldDef, {
+    type: 'blocks';
+}>;
+/** A rich-text field, narrowed (EC-159/EC-189: carries the embed `allow` list). */
+export type RichTextFieldDef = Extract<FieldDef, {
+    type: 'richText';
+}>;
+/** An object / repeater field, narrowed (EC-253). */
+export type ObjectFieldDef = Extract<FieldDef, {
+    type: 'object';
+}>;
+/** Narrowing helpers. */
+export declare function isRelationField(field: FieldDef): field is RelationFieldDef;
+export declare function isAssetField(field: FieldDef): field is AssetFieldDef;
+export declare function isSelectField(field: FieldDef): field is SelectFieldDef;
+export declare function isBlocksField(field: FieldDef): field is BlocksFieldDef;
+export declare function isRichTextField(field: FieldDef): field is RichTextFieldDef;
+export declare function isObjectField(field: FieldDef): field is ObjectFieldDef;
+/** Resolve a field-def's context, defaulting to `document` (EC-190). */
+export declare function fieldContext(field: FieldDef): FieldContext;
+/** True if the field-def may be used as a component prop (EC-190). */
+export declare function isPropContext(field: FieldDef): boolean;
+/** True if the field-def may be used as a CMS document field (EC-190). */
+export declare function isDocumentContext(field: FieldDef): boolean;
+export {};