@nonext/husk 0.2.3

package/dist/core/index.d.ts

@@ -0,0 +1,1267 @@
+import { C as CmsAdapter, q as SortSpec, E as EntryFilter, L as ListQuery, n as MigrationAdapter } from '../adapter-C_0mhENy.js';
+export { D as DEFAULT_PAGE_SIZE, a as EntryInputData, F as FieldDataAdapter, b as FieldPurgeOptions, c as FieldPurgeResult, d as FilterOperator, M as MAX_FIELD_PURGE, e as MAX_PAGE_SIZE, f as MEDIA_USAGE_LIMIT, g as MediaAdapter, h as MediaInput, i as MediaQuery, j as MediaRefreshResult, k as MediaUsage, l as MediaUsageQuery, m as MediaUsageReference, o as MigrationWrite, P as Page, S as SchemaAdapter, p as SettingsAdapter, r as StoredEntryRecord, s as normalizeLimit } from '../adapter-C_0mhENy.js';
+export { C as Cms, a as CmsConfig, b as CmsCountQuery, c as CmsQuery, d as CmsReadConfig, e as CollectionReader, f as ContentTypeMap, E as EntryOf, K as KnownSlug, M as MediaReader, S as SettingsReader, g as SingleReader, h as SlugOf, i as assertDeletable, j as assertListable, k as assertSingletonCreatable, l as assertSingletonEntryId, m as createCMS, n as isCollection, o as isSingleton, s as singletonEntryId } from '../cms-9fSA3uQV.js';
+import { k as RemovedFieldMap, C as ContentType, c as ContentTypeLike, f as Entry, F as FieldError, h as EntryMeta, i as EntryStatus, b as ContentTypeKind, d as ContentTypeSource, j as RemovedField } from '../entry-D3kiE8T1.js';
+import { c as FieldMap, a as FieldDefinition, V as ValidationRules, d as FieldType } from '../field-Diyf5siF.js';
+import { f as FieldTypeRegistry } from '../field-type-D25Vojb0.js';
+import { b as AuthUser, e as Role } from '../auth-B2gBtHl5.js';
+export { A as ALLOWED_MEDIA_TYPES, C as Clock, F as FIRESTORE_DOCUMENT_BYTES, M as MAX_ARRAY_ITEMS, a as MAX_CONTENT_TYPE_FIELDS, b as MAX_ENTRY_FIELDS, c as MAX_IMAGE_BYTES, d as MAX_MEDIA_BYTES, e as MAX_NESTING_DEPTH, f as MAX_SETTINGS_FIELDS, g as MAX_WRITE_BYTES, h as MEDIA_ACCEPT_ATTRIBUTE, i as MIN_WRITE_INTERVAL_MS, j as MediaCategory, k as MediaFileFacts, l as MediaRejection, m as MediaRejectionCode, n as MediaTypeRule, P as PayloadLimits, W as WRITE_BURST_LIMIT, o as WRITE_BURST_WINDOW_MS, p as WriteLimitCode, q as WriteLimitRejection, r as WriteRateLimiter, s as approximateBytes, t as checkMediaFile, u as checkWritePayload, v as createWriteRateLimiter, w as fileExtension, x as mediaTypeRule, y as normalizeMediaType, z as safeFileName } from '../write-limits-Djmm6L3R.js';
+import { R as Registry } from '../registry-CUC25qay.js';
+export { I as InvalidContentType, a as RegistryEntry, b as assertSchemaWritable, c as buildRegistry, i as isSchemaReadOnly } from '../registry-CUC25qay.js';
+import 'react';
+
+/**
+ * The cache tag vocabulary, as plain strings.
+ *
+ * A cached read and the thing that invalidates it have to agree on a name, and they are
+ * almost never the same file: one is a page in the customer's app, the other is a route
+ * handler, a script, or a person typing into a terminal. Two hand-written strings that must
+ * match is exactly the kind of agreement that rots, so the names are computed here and both
+ * sides import the same function.
+ *
+ * Nothing in this module imports Next. The functions are pure, which is what lets the same
+ * names be used with `cacheTag` under Cache Components, with `unstable_cache({ tags })`
+ * without it, with a CDN's surrogate keys, or with nothing at all. Husk does not decide the
+ * caching strategy for a customer's website; it only makes the names available.
+ *
+ * What Husk cannot do with them is call `revalidateTag` by itself. The admin writes from the
+ * browser through the client SDK, so there is no server-side write hook in this architecture
+ * to hang an invalidation on. See `docs/caching.md` and
+ * `.docs/decisions/2026-09-19-caching-and-revalidation.md` for the seam and what closes it.
+ */
+/**
+ * The namespace every Husk tag starts with.
+ *
+ * A customer's own cache tags share the tag space with these, so they carry a prefix that
+ * says where they came from. It also means a customer can reason about "everything Husk"
+ * when reading a list of tags in a log.
+ */
+declare const HUSK_TAG_PREFIX = "husk";
+/**
+ * Everything of one content type: the list, the counts, every entry of it.
+ *
+ * This is the tag a list page uses. It is also the one an editor's publish has to clear,
+ * because a new entry has no entry tag anything could have cached under yet.
+ */
+declare function contentTypeTag(slug: string): string;
+/**
+ * One entry.
+ *
+ * Narrow on purpose: editing one project should not have to discard the cached page of
+ * every other project. A detail page tags both this and the content type, so either level
+ * of invalidation reaches it.
+ */
+declare function entryTag(slug: string, entryId: string): string;
+/**
+ * One entry, named by the value of its slug field rather than by its id.
+ *
+ * A URL-addressed page knows the slug and does not know the id until it has read the entry,
+ * which is one read too late to tag a cache entry with. The publish side knows both, so the
+ * two meet: a page caches under the slug it was asked for, and an invalidation clears the
+ * slug the entry carries. Renaming a slug moves the page to a new URL and leaves the old
+ * tag holding a page nothing links to any more, which expires on its own.
+ */
+declare function entrySlugTag(slug: string, value: string): string;
+/** The pair a detail page caches under. Order is stable, so it is comparable. */
+declare function entryTags(slug: string, entryId: string): readonly string[];
+/**
+ * One media item.
+ *
+ * Replacing a file keeps the media id and mints a new download URL, so a page that cached
+ * the old URL is stale in a way no entry-level tag describes.
+ */
+declare function mediaTag(mediaId: string): string;
+/** One settings document, by key. */
+declare function settingsTag(key: string): string;
+/** Whether a string is one of the names above, for a revalidation endpoint to check. */
+declare function isHuskTag(value: string): boolean;
+
+/**
+ * Declares a content type and infers its entry shape from its field map.
+ *
+ * The `const` type parameter is what makes inference work: without it, `required: true`
+ * widens to `boolean` and every field would read as nullable, and select options would
+ * widen to `string` instead of the union of the declared values.
+ *
+ * Structural mistakes throw here rather than at first write, so a code-defined type fails
+ * at module load and never reaches Firestore.
+ */
+declare function defineContentType<const TFields extends FieldMap>(definition: ContentType<TFields>): ContentType<TFields>;
+/**
+ * The structural checks, separated from `defineContentType` so that a database-defined type
+ * read out of Firestore goes through exactly the same guards as a code-defined one. The
+ * registry calls this; it must never trust a stored definition more than a written one.
+ */
+declare function assertValidContentType(definition: {
+    slug: string;
+    kind: unknown;
+    fields: FieldMap;
+    removedFields?: RemovedFieldMap | undefined;
+    titleField?: string | undefined;
+    defaultSort?: {
+        field: string;
+        direction: "asc" | "desc";
+    } | undefined;
+    permissions?: unknown;
+}): void;
+
+/**
+ * The phrase a destructive confirmation asks the user to type, and what counts as typing
+ * it. Canonical source: .docs/styleguide/04-components.md section 12, "Destructive
+ * confirmation".
+ *
+ * Two failure modes bound this, and they pull in opposite directions. A phrase the user
+ * cannot produce is a trap: the delete becomes impossible and the only way out is the
+ * cancel button. A phrase any keypress satisfies is theatre: it costs a gesture and buys
+ * no attention. So the phrase is always printed in the dialog, always typeable, and always
+ * specific to what is about to be destroyed.
+ *
+ * None of it renders, so all of it is testable without a DOM, and the dialog and any
+ * future bulk flow cannot disagree about what "the name" is.
+ */
+/**
+ * What to type to delete one entry.
+ *
+ * The entry's title, when it has one. When it does not (no `titleField`, a non-string
+ * value, or a blank string) `entryTitle` answers "Untitled", and "Untitled" is a
+ * placeholder rather than a name: it is the same word for every untitled entry in the
+ * collection, so typing it proves nothing about which entry is meant. The document id is
+ * used instead. It is ugly and it is unique, and the dialog prints it, so it is typeable.
+ *
+ * Two entries can still legitimately share a title. That ambiguity is harmless here,
+ * because the dialog is already pointed at one entry: the phrase is a gate on attention,
+ * not a lookup key.
+ */
+declare function deleteConfirmationName(type: ContentTypeLike, entry: Entry): string;
+/**
+ * What to type to delete several entries at once.
+ *
+ * Not a list of names: ten names is a transcription exercise, and an editor would paste it
+ * or give up. The count and the content type is the fact worth confirming, because the
+ * mistake a bulk delete actually makes is about how many rows were selected.
+ */
+declare function deleteConfirmationPhrase(type: ContentTypeLike, count: number): string;
+/**
+ * The comparison form of a confirmation phrase.
+ *
+ * Forgiving of whitespace: leading and trailing space, and any run of spaces, tabs or
+ * newlines inside, collapse to one space. None of that is visible in the input, so
+ * refusing it would fail a user who typed the phrase correctly and cannot see why it was
+ * rejected. Unicode is normalized to NFC for the same reason: an accented character typed
+ * on one keyboard and stored from another can be two byte sequences that read identically.
+ *
+ * Deliberately not forgiving of case. Case is visible, the phrase is printed right above
+ * the input, and matching it is the deliberate act the gate exists to require. This is the
+ * same choice GitHub makes for deleting a repository, and it is the line between a
+ * confirmation and a formality.
+ */
+declare function normalizeConfirmation(value: string): string;
+/**
+ * Whether what was typed confirms the phrase.
+ *
+ * An empty expected phrase never matches. A caller that cannot name what it is about to
+ * delete has no business unlocking the button, and an empty input would otherwise satisfy
+ * an empty phrase on an empty dialog.
+ */
+declare function confirmationMatches(expected: string, typed: string): boolean;
+
+/**
+ * The entry form as data: which fields it renders, what it starts from, which error
+ * belongs to which control, and whether anything has changed.
+ *
+ * None of it renders, so all of it is testable in the node project, and the create screen
+ * and the edit screen cannot drift apart by deriving the same answers twice. The field
+ * type registry arrives as an argument rather than as an import, because `src/fields`
+ * pulls in React and core must not.
+ */
+interface FormField {
+    key: string;
+    field: FieldDefinition;
+}
+/**
+ * The fields the form renders, in the order the schema declares them.
+ *
+ * A hidden field is skipped: it still stores and still validates (see the note on
+ * `hidden` in types/field.ts), it simply has no control. That is exactly why an error on
+ * a hidden field is reported at form level by `unroutableIssues` instead of vanishing.
+ */
+declare function formFields(type: ContentTypeLike): readonly FormField[];
+/** What a new entry starts with: every field at its own field type's default. */
+declare function initialFormValues(type: ContentTypeLike, registry: FieldTypeRegistry): Record<string, unknown>;
+/**
+ * The values of a stored entry, narrowed to the fields the schema declares.
+ *
+ * Metadata is deliberately dropped: `status`, `createdBy` and the timestamps belong to the
+ * adapter, and a form that carried them in its value map could write one back. A field the
+ * entry predates falls back to the field type's default rather than to `undefined`, so the
+ * control is not handed a value it has no state for.
+ */
+declare function formValuesFromEntry(type: ContentTypeLike, entry: Entry, registry: FieldTypeRegistry): Record<string, unknown>;
+/**
+ * The errors belonging to one field and everything nested under it.
+ *
+ * Path-based, which is what lets a server error reach the control that owns it: the
+ * validator and the adapter both report `blocks.1.items.0.text`, and passing that whole
+ * subtree to the `blocks` input lets the repeater hand it down row by row. A prefix match
+ * on the dot is required, or `title` would also claim `titleImage`.
+ */
+declare function errorsUnder<TError extends FieldError>(errors: readonly TError[], path: string): TError[];
+/** Where an error came from. The two are told apart because they expire differently. */
+type ErrorOrigin = "client" | "server";
+interface FormIssue extends FieldError {
+    origin: ErrorOrigin;
+}
+/**
+ * The errors on screen, from the two sources that produce them.
+ *
+ * A client error is recomputed from the current values on every keystroke, so it is always
+ * about what is in the form right now. A server error is a verdict about the values that
+ * were submitted, and only another submission can retract it: uniqueness is the clearest
+ * case, because nothing in the browser can know that a slug is free.
+ *
+ * So they cannot simply be concatenated. A client error wins its own path, because it is
+ * the more current statement about that value; a server error survives on every path the
+ * client has nothing to say about, which is what keeps "that slug is taken" on screen
+ * while the editor types the next character.
+ */
+declare function mergeIssues(client: readonly FieldError[], server: readonly FieldError[]): readonly FormIssue[];
+/**
+ * Issues no control will render, which is the only case where a toast or a form-level
+ * message is the right answer.
+ *
+ * Three ways an error gets here: it names a hidden field, it names a field the schema no
+ * longer declares, or it names nothing at all. In each case the form has to say it
+ * somewhere, and saying it next to an unrelated control would be worse than saying it at
+ * the top.
+ */
+declare function unroutableIssues<TError extends FieldError>(issues: readonly TError[], type: ContentTypeLike): readonly TError[];
+/**
+ * Whether the form holds anything the baseline does not.
+ *
+ * Structural rather than by reference, because every field input replaces the value it
+ * owns on each edit, and a repeater rebuilds its whole array to move one row. Reference
+ * equality would call an entry dirty for having been touched and untouched again, and the
+ * unsaved-changes guard is only worth having if it is quiet when nothing changed.
+ */
+declare function valuesChanged(baseline: Record<string, unknown>, current: Record<string, unknown>): boolean;
+/**
+ * Whether the stored entry moved since the editor read it.
+ *
+ * `updatedAt` is stamped by the adapter on every write, so a difference means somebody
+ * else saved. The editor asks this immediately before its own write rather than
+ * subscribing: a live listener would be a second read path, a second failure mode, and an
+ * interruption in the middle of typing. It closes the wide window, not the narrow one; two
+ * writes in the same second still resolve last-write-wins, which the adapter's document
+ * semantics already decide.
+ */
+declare function entryChangedSince(baseline: Pick<EntryMeta, "updatedAt">, current: Pick<EntryMeta, "updatedAt">): boolean;
+
+/**
+ * What the status control may offer, and to whom.
+ *
+ * Status is the one piece of entry metadata an editor writes, so it is not a display: it
+ * is a set of transitions out of the status the entry is in, each one answered by `can()`
+ * against the entry itself. A denied transition keeps its reason rather than disappearing,
+ * because "you cannot publish this" is information and an empty panel is not.
+ *
+ * Hiding or disabling a transition here is presentation. The adapter validates the write
+ * and the security rules check the same matrix again, so a user who reaches past this list
+ * gains nothing.
+ */
+interface StatusTransition {
+    to: EntryStatus;
+    /** Imperative label for the control: "Publish", "Unpublish", "Archive". */
+    label: string;
+    /** What it does to the public site, in one sentence. */
+    effect: string;
+    allowed: boolean;
+    /** Why it is not offered. Null when it is. */
+    reason: string | null;
+}
+/** Just enough of an entry to answer a transition question. */
+type StatusSubject = Pick<EntryMeta, "status" | "createdBy">;
+/** How a status reads in the sidebar, under the badge. */
+declare const STATUS_EFFECT: Readonly<Record<EntryStatus, string>>;
+/**
+ * The transitions for one entry, in a fixed order.
+ *
+ * `entry` is null for an entry that has not been created yet. A new entry is a draft that
+ * does not exist, so the only move it has is the one that brings it into existence
+ * published, and the permission question is `create` rather than `update`.
+ */
+declare function statusTransitions(user: AuthUser, type: ContentTypeLike, entry: StatusSubject | null): readonly StatusTransition[];
+/**
+ * Whether this user may save the values of this entry at all.
+ *
+ * Separate from the transitions because saving without changing the status is its own
+ * action, and because the create screen asks the question before an entry exists.
+ */
+declare function canSaveEntry(user: AuthUser, type: ContentTypeLike, entry: StatusSubject | null): boolean;
+
+/**
+ * The live uniqueness answer the form hands to the field layer.
+ *
+ * `unique` is the one validation rule that cannot be answered without reading other
+ * entries, so the shared validator leaves it to the adapter, which checks it again on
+ * every write. This is only the hint in front of that check, and it is deliberately narrow.
+ *
+ * It answers for the content type's slug field and for nothing else. That is not a
+ * shortcut: `getBySlug` is a single equality query that Firestore serves from an automatic
+ * single-field index, while asking the same question about an arbitrary field would need a
+ * composite index per field, generated per content type, for a hint. Any other path is
+ * rejected rather than answered "free", because telling an editor a value is available
+ * when nobody looked is worse than telling them nothing. The rejection is what the slug
+ * input reads as "no answer", and it then shows no availability hint at all.
+ */
+interface EntryUniqueOptions {
+    adapter: CmsAdapter;
+    type: ContentTypeLike;
+    /** The entry being edited, so its own value does not count as taken. Null on create. */
+    entryId: string | null;
+}
+declare function entryUniqueCheck(options: EntryUniqueOptions): (path: string, value: string) => Promise<boolean>;
+
+/** What an entry is called when its title field is empty or was never declared. */
+declare const UNTITLED_ENTRY = "Untitled";
+/**
+ * The one-line name of an entry, resolved from the content type rather than guessed.
+ *
+ * Every screen that lists entries needs this: the dashboard, the collection list, a
+ * relation picker, a delete confirmation. Resolving it in one place is what keeps an entry
+ * from being called two different things on two screens.
+ *
+ * `titleField` is optional and its stored value is untrusted, so a missing field, a
+ * non-string value and a blank string all fall back to `UNTITLED_ENTRY`. An entry with no
+ * usable title still has to be nameable, or it cannot be listed at all.
+ */
+declare function entryTitle(type: ContentTypeLike, entry: Entry): string;
+
+/**
+ * The one error taxonomy the admin renders from.
+ *
+ * Before this existed the treatments were real but scattered: the entry editor routed a
+ * `ValidationError` to the offending field and fell back to a form-level message, the
+ * Schema Builder put every failure in one banner, the media screens put every failure in a
+ * toast, and a permission refusal read as "something went wrong" in all three. Each of
+ * those was defensible on its own and none of them agreed with the others.
+ *
+ * This module is not a second system layered over them. It is the first one, factored out:
+ * the M6 rule that a validation error lands on the field and only an unroutable path
+ * reaches the form is preserved exactly, as the `field` treatment, and every other screen
+ * now asks the same question instead of answering it privately.
+ *
+ * Five categories, one treatment each:
+ *
+ * | category     | treatment | what the user sees                                        |
+ * |--------------|-----------|-----------------------------------------------------------|
+ * | `validation` | `field`   | the message on the control that owns the path; never a bare toast |
+ * | `permission` | `banner`  | a form-level notice naming the action, the subject and the role |
+ * | `not-found`  | `state`   | an empty state with a way back; no alert, no red            |
+ * | `conflict`   | `resolve` | a banner that names both resolutions and offers them        |
+ * | `transport`  | `retry`   | a banner or state carrying the one action that can help     |
+ *
+ * `unknown` is the sixth, for a failure that fits none of them. It takes the `banner`
+ * treatment and says plainly that the cause is unknown, rather than guessing at a category
+ * and offering a retry that cannot work.
+ *
+ * The toast is deliberately not a treatment. It is the announcement channel for a failure
+ * whose surface has already closed (a dialog that dismissed itself, a background upload),
+ * and when it is used it prints this same `title` and `message`, so a failure can never be
+ * worded twice.
+ *
+ * No React and no Firebase here, so the classification is testable in the node project and
+ * callable from the adapter as well as from a render.
+ */
+declare const ERROR_CATEGORIES: readonly ["validation", "permission", "not-found", "conflict", "transport", "unknown"];
+type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
+/** The chrome a category is rendered in. Exactly one per category; see the table above. */
+type ErrorTreatment = "field" | "banner" | "state" | "resolve" | "retry";
+/** The treatment a category must be rendered in. The single mapping, used by every screen. */
+declare function treatmentFor(category: ErrorCategory): ErrorTreatment;
+interface ClassifiedError {
+    category: ErrorCategory;
+    treatment: ErrorTreatment;
+    /** A short heading. Used as the banner's first line and as a toast title. */
+    title: string;
+    /** One or two sentences: what happened, and what the user can do about it. */
+    message: string;
+    /**
+     * The field errors, for `validation` only. Every other category leaves this empty, which
+     * is what stops a non-validation failure from being routed onto a control.
+     */
+    fieldErrors: readonly FieldError[];
+    /** True only for `transport`. A retry of anything else repeats the same refusal. */
+    retryable: boolean;
+    /** What was thrown, kept for a boundary that wants to log it. Never rendered. */
+    cause: unknown;
+}
+interface ErrorContext {
+    /** The signed-in role, so a permission refusal can name who was refused. */
+    role?: Role | undefined;
+    /**
+     * What the user was doing, as a verb phrase that completes "could not ...": "save this
+     * entry", "delete these entries". Used for transport and unknown failures, where the
+     * error itself says nothing a reader can act on.
+     */
+    action?: string | undefined;
+    /** What was acted on, named the way the UI names it: a content type label, a file name. */
+    subject?: string | undefined;
+}
+/**
+ * Classifies anything that was thrown into exactly one category with its treatment.
+ *
+ * Order matters and is by certainty. A class the package defines is conclusive, a
+ * Firestore code is strong evidence, and a message match is the last resort.
+ */
+declare function classifyError(thrown: unknown, context?: ErrorContext): ClassifiedError;
+/**
+ * The conflict the entry editor detects for itself.
+ *
+ * A stale write is noticed by comparing timestamps before the write, not by catching
+ * something, so there is nothing to classify. It still has to arrive as a `ClassifiedError`
+ * or the editor would be writing its own sentence for a category this module owns, which is
+ * exactly the split this module exists to close.
+ */
+declare function staleWriteError(subject: string): ClassifiedError;
+/** The other locally detected case: the thing being edited is gone. A state, not an error. */
+declare function missingError(subject: string): ClassifiedError;
+/** The locally detected permission refusal, for a screen that asked `can()` and got false. */
+declare function deniedError(what: string, role: Role | undefined): ClassifiedError;
+
+/**
+ * A content type, field map, or registry is malformed. Thrown at definition time, which
+ * for a code-defined type means at module load, so the mistake surfaces before any data
+ * is written.
+ */
+declare class SchemaError extends Error {
+    readonly name = "SchemaError";
+    constructor(message: string);
+}
+/** Entry data failed the compiled validator. Carries one error per offending field path. */
+declare class ValidationError extends Error {
+    readonly name = "ValidationError";
+    readonly errors: readonly FieldError[];
+    constructor(errors: readonly FieldError[]);
+}
+/** A schema write was attempted against a content type that does not accept one. */
+declare class LockedTypeError extends Error {
+    readonly name = "LockedTypeError";
+    readonly slug: string;
+    constructor(slug: string, reason?: string);
+}
+/** A singleton was asked to hold more than the one entry it is allowed. */
+declare class SingletonError extends Error {
+    readonly name = "SingletonError";
+    readonly slug: string;
+    constructor(slug: string, message: string);
+}
+/**
+ * The caller is not allowed to do this. Thrown by the adapter, from the same `can()` the
+ * UI asked before it drew the button and the same matrix firestore.rules enforces.
+ *
+ * It exists as its own class because "you may not" and "that is malformed" need different
+ * answers: a permission refusal is never fixed by editing the value. Carrying the action
+ * and the content type lets a caller say which one without parsing the message.
+ */
+declare class PermissionError extends Error {
+    readonly name = "PermissionError";
+    readonly action: string;
+    /** Content type slug. Absent for an action that is not scoped to one. */
+    readonly contentType: string | undefined;
+    constructor(action: string, contentType?: string, message?: string);
+}
+/**
+ * A write was refused for its size, its shape, or its timing rather than its content.
+ * See core/write-limits.ts for which of these the security rules enforce as well and
+ * which are the adapter's alone.
+ */
+declare class WriteLimitError extends Error {
+    readonly name = "WriteLimitError";
+    readonly code: string;
+    readonly path: string;
+    constructor(rejection: {
+        code: string;
+        path: string;
+        message: string;
+    });
+}
+
+/**
+ * The composite indexes a collection list needs, derived from the content types.
+ *
+ * `.docs/rules/firestore-indexes.md` requires every query to ship with its index, and the
+ * list view's queries are generated, so the index entries have to be generated too. A
+ * filter on a field plus an ordering on another field is a composite index, and the field
+ * paths come from the customer's schema, which no hand-written file can know in advance.
+ *
+ * Entries of every content type live in a subcollection called `entries`, so one
+ * `COLLECTION`-scoped index serves every type that uses the same field path. That is why
+ * the result is deduplicated across types rather than emitted per type.
+ *
+ * What is deliberately not emitted: a query with no filter at all. Ordering by one field
+ * with `__name__` as the tiebreaker in the same direction is served by Firestore's
+ * automatic single-field indexes, and emitting it would waste an index slot.
+ */
+type IndexOrder = "ASCENDING" | "DESCENDING";
+interface FirestoreIndexField {
+    fieldPath: string;
+    order: IndexOrder;
+}
+interface FirestoreIndex {
+    collectionGroup: string;
+    queryScope: "COLLECTION";
+    fields: readonly FirestoreIndexField[];
+}
+declare const ENTRY_COLLECTION_GROUP = "entries";
+/**
+ * Firestore allows 200 composite indexes per database. Passing it is not a warning to be
+ * ignored later: the deploy fails. Better to fail here, where the schema that caused it is
+ * in hand, than in a customer's deploy log.
+ */
+declare const MAX_ENTRY_INDEXES = 200;
+/**
+ * Every index the generated list view can ask for, across the given content types.
+ *
+ * The shape of each query it covers is: an optional `status` equality, zero or more field
+ * equalities, then the ordering field and `__name__` in the same direction. A prefix
+ * search needs no extra entry: it ranges over the title field and orders by it, which is
+ * the ordering already emitted for the title column.
+ */
+declare function requiredEntryIndexes(types: readonly ContentTypeLike[]): readonly FirestoreIndex[];
+/** Whether a checked-in index file already covers one required index. */
+declare function indexCovered(file: {
+    indexes?: readonly FirestoreIndex[];
+}, required: FirestoreIndex): boolean;
+/** The required indexes missing from a checked-in index file, for a drift test. */
+declare function missingEntryIndexes(file: {
+    indexes?: readonly FirestoreIndex[];
+}, types: readonly ContentTypeLike[]): readonly FirestoreIndex[];
+
+/**
+ * What a collection list is, derived from a content type.
+ *
+ * The screen renders this; it never decides it. Columns, the sortable set, the filter
+ * controls and the query that reads a page are all computed here from the schema, which is
+ * what makes a new content type a data change and not a screen change.
+ *
+ * Nothing in this file imports React, Firebase or the field registry, so it is domain
+ * logic: it runs in the node test project, in the SDK, and in a server component.
+ */
+/** How a column's cells are typeset. The cell itself never inspects the field type. */
+type ColumnAlign = "text" | "numeric" | "date";
+type ColumnKind = "title" | "field" | "status" | "updated";
+interface ListColumn {
+    /** Field key, or `status` / `updatedAt` for the two metadata columns. */
+    key: string;
+    label: string;
+    kind: ColumnKind;
+    align: ColumnAlign;
+    /**
+     * Whether the header offers sorting. Bounded on purpose: every sortable column costs a
+     * pair of composite indexes per filter combination, so the list sorts by title, by the
+     * type's declared default sort field, and by last update, and not by every column it
+     * shows. See `sortableFieldKeys` and core/indexes.ts.
+     */
+    sortable: boolean;
+}
+interface ListFilterOption {
+    value: string;
+    label: string;
+}
+interface ListFilterDescriptor {
+    /** Field key the filter applies to. */
+    key: string;
+    label: string;
+    options: readonly ListFilterOption[];
+    /**
+     * `array-contains` for a multi-select, whose stored value is an array; `==` otherwise.
+     * The screen passes this straight through, so it never decides an operator.
+     */
+    op: EntryFilter["op"];
+    /** Filter values are strings in the UI; a boolean field converts back on the way out. */
+    valueType: "string" | "boolean";
+}
+/** Everything the reader has narrowed the list to, as one serializable value. */
+interface ListViewState {
+    /** Prefix term for the title field. Empty means no search. */
+    search: string;
+    status: EntryStatus | "any";
+    /** Field key to selected option value. A key absent means that filter is off. */
+    filters: Readonly<Record<string, string>>;
+    sort: SortSpec;
+    /** Opaque, from a previous page. The UI stores it and never builds one. */
+    cursor: string | null;
+}
+/** Last touched first: what an editor who just saved something expects to see at the top. */
+declare const FALLBACK_SORT: SortSpec;
+declare function defaultListSort(type: ContentTypeLike): SortSpec;
+declare function initialListState(type: ContentTypeLike): ListViewState;
+/** A content type can only be searched when it names the field to match against. */
+declare function canSearch(type: ContentTypeLike): boolean;
+/** True while a term is narrowing the list, which is also when sorting is not on offer. */
+declare function isSearching(state: ListViewState): boolean;
+/**
+ * The keys a list may sort by: the title, the type's own default sort field, and the last
+ * update. Kept small deliberately; see `ListColumn.sortable`.
+ */
+declare function sortableFieldKeys(type: ContentTypeLike): readonly string[];
+/** How many schema fields get their own column before the row would stop being readable. */
+declare const MAX_FIELD_COLUMNS = 2;
+interface ListColumnOptions {
+    maxFieldColumns?: number;
+}
+/**
+ * The columns, in reading order: title, up to two field columns, status, updated.
+ *
+ * Hidden fields are skipped because the form does not show them either, and the title
+ * field is not repeated as a field column. A type with no `titleField` still gets a title
+ * column: `entryTitle` names the entry "Untitled" and the row remains clickable, which is
+ * better than a list whose rows have no handle at all.
+ */
+declare function listColumns(type: ContentTypeLike, { maxFieldColumns }?: ListColumnOptions): readonly ListColumn[];
+/** Whether a field definition can back a filter control. */
+declare function isFilterableField(field: FieldDefinition): boolean;
+/**
+ * The field filters a content type offers, in schema order.
+ *
+ * Status is not among them: it is entry metadata rather than a field, every content type
+ * has it, and the adapter takes it as its own argument.
+ */
+declare function listFilters(type: ContentTypeLike): readonly ListFilterDescriptor[];
+/**
+ * The active filters as adapter filters.
+ *
+ * A stored value the schema no longer offers is dropped rather than sent: a filter for a
+ * select option that was removed from the content type would return nothing and read as
+ * "there are no entries".
+ */
+declare function listFilterQuery(type: ContentTypeLike, filters: Readonly<Record<string, string>>): readonly EntryFilter[];
+interface BuildListQueryOptions {
+    pageSize?: number;
+}
+/**
+ * The read for one page.
+ *
+ * The sort is omitted while a search is active rather than sent and ignored: the adapter
+ * forces title order for a prefix range, and a query object that still claimed another
+ * order would be a lie the caller could act on.
+ */
+declare function buildListQuery(type: ContentTypeLike, state: ListViewState, { pageSize }?: BuildListQueryOptions): ListQuery;
+/** The same narrowing as a count: no order, no cursor, no page size. */
+declare function buildCountQuery(type: ContentTypeLike, state: ListViewState): Pick<ListQuery, "filters" | "status" | "search">;
+/** Whether anything is narrowing the list, which is what tells an empty result apart. */
+declare function isNarrowed(state: ListViewState): boolean;
+/**
+ * The next sort after a header is clicked.
+ *
+ * Clicking the sorted column flips it. Clicking another column starts in the direction
+ * that column is usually read in: newest first for a date, A to Z for everything else.
+ */
+declare function nextSort(current: SortSpec, column: ListColumn, key?: string): SortSpec;
+
+/**
+ * A registry that can change while the admin is running.
+ *
+ * Creating a content type in the Schema Builder has to put it in the sidebar, give it
+ * routes and give it working CRUD without a rebuild and without a reload. The code half of
+ * the registry is fixed for the lifetime of the process; only the database half moves, so
+ * this holds the code half and swaps the database half.
+ *
+ * **How the change arrives, and what it costs.** `SchemaAdapter.watch` opens one Firestore
+ * listener on the whole `schemas` collection and hands every snapshot to `setDatabaseTypes`.
+ * One listener per open admin tab. It bills the documents of the initial snapshot once, then
+ * one document read per changed schema document, and nothing at all while nobody is editing
+ * structure. `schemas` holds one small document per database-defined content type, so a
+ * customer with twenty of them pays twenty reads when an admin tab opens.
+ *
+ * The alternative considered was refetching the collection on every navigation inside the
+ * admin. It needs no listener, but it bills the whole collection again on every screen
+ * change, which for one editor clicking through twenty screens in an hour is already an
+ * order of magnitude more reads than the listener, and it is still stale in the tab where
+ * nobody navigated. The listener is both cheaper in the steady state and the only one of
+ * the two that actually refreshes without an interaction. See
+ * .docs/decisions/2026-09-18-schema-field-removal.md.
+ *
+ * A snapshot that produces an identical registry is dropped rather than published, because
+ * Firestore replays a local write as a second snapshot once the server acknowledges it and
+ * a re-render of every admin screen for a change nobody made is a visible cost.
+ */
+interface RegistryStore {
+    /** The current registry. Replaced, never mutated, so a React snapshot stays stable. */
+    readonly registry: Registry;
+    /**
+     * Swaps the database half. Returns true when the registry actually changed, which is what
+     * the caller subscribes for.
+     */
+    setDatabaseTypes(types: readonly ContentTypeLike[]): boolean;
+    /** Notified after every real change. Returns the unsubscribe. */
+    subscribe(listener: (registry: Registry) => void): () => void;
+    /**
+     * Changes counter, monotonic. `useSyncExternalStore` compares it instead of deep
+     * comparing the registry, and a server render can send it to the client to detect that
+     * the two disagree.
+     */
+    readonly revision: number;
+}
+declare function createRegistryStore(code: readonly ContentTypeLike[], initialDatabase?: readonly ContentTypeLike[]): RegistryStore;
+
+/**
+ * The migration runner: enough to move stored entries from one schema version to the next,
+ * and deliberately not a migration framework.
+ *
+ * `content/{slug}.schemaVersion` says what shape the type declares today and every entry
+ * carries the version it was last written at (see core/schema-version.ts). A migration is
+ * the transform between two consecutive versions of one content type. This module owns the
+ * registry of those transforms, the plan that chains them, and the loop that applies them.
+ *
+ * Four properties, because a migration that has any of them wrong is worse than none:
+ *
+ * 1. **Idempotent.** An entry is selected only while its stored version is behind, and the
+ *    write is conditional on that version still being what was read. Running twice migrates
+ *    nothing the first run finished, and two runners racing cannot both apply a step.
+ * 2. **Resumable.** There is no run state to keep. A run that is interrupted leaves every
+ *    entry either fully at the old version or fully at the new one, so the next run is
+ *    simply the same run again over what is left.
+ * 3. **Bounded.** It works in batches and returns what remains rather than walking a
+ *    collection of unknown size inside one call.
+ * 4. **Honest when it fails.** A failing entry is named and the run stops rather than
+ *    grinding through thousands of entries repeating the same error. Nothing is rolled
+ *    back, because rolling back a partially migrated collection would need a second
+ *    migration to be correct; the entries that succeeded are at the new version and the
+ *    rest are untouched, which is a state the next run understands.
+ *
+ * What it is not: it does not create a migration for you, does not infer one from a schema
+ * diff, and does not run automatically. A schema change that needs one says so (the Schema
+ * Builder warns on a storage shape change) and somebody writes the transform.
+ */
+/** The context a transform gets besides the values. */
+interface MigrationContext {
+    entryId: string;
+    slug: string;
+    /** The version the stored entry is at, which is this migration's `from`. */
+    fromVersion: number;
+}
+/**
+ * One step, from one version to the next.
+ *
+ * `from` and `to` are consecutive by construction: a transform that jumped two versions
+ * could not be composed with one that filled the gap, and the registry would have no way
+ * to migrate an entry that is stuck in between.
+ */
+interface EntryMigration {
+    slug: string;
+    from: number;
+    to: number;
+    /** One line, shown before a run so somebody can decide whether to start it. */
+    describe: string;
+    /**
+     * Returns the new values. Pure: no IO, no clock, no randomness, because it may be
+     * replayed on a later run over a different slice of the same collection and has to give
+     * the same answer.
+     */
+    migrate(values: Record<string, unknown>, context: MigrationContext): Record<string, unknown>;
+}
+interface MigrationRegistry {
+    /** Every registered migration for one content type, in version order. */
+    forType(slug: string): readonly EntryMigration[];
+    /**
+     * The steps that take an entry from `fromVersion` to the type's current version.
+     *
+     * A version with no registered step is an identity step, not an error. The stamp moves
+     * on any change to the stored shape, and most of those changes (adding a field, removing
+     * one) need no transform at all, so requiring a migration per version would mean writing
+     * an empty one after every schema edit. What a gap costs is stated rather than hidden: a
+     * transform that was needed and never written is not detected here, and the place that
+     * flags one is the Schema Builder's breaking-change warning at the moment of the edit.
+     */
+    plan(type: ContentTypeLike, fromVersion: number): readonly EntryMigration[];
+}
+declare function createMigrationRegistry(migrations: readonly EntryMigration[]): MigrationRegistry;
+/** Applies a plan to one entry's values. Exported so a dry run can show the result. */
+declare function applyPlan(plan: readonly EntryMigration[], values: Record<string, unknown>, context: Omit<MigrationContext, "fromVersion">): Record<string, unknown>;
+interface MigrationFailure {
+    entryId: string;
+    /** The version the entry was at when the attempt was made. */
+    fromVersion: number;
+    reason: string;
+}
+interface MigrationRunResult {
+    slug: string;
+    /** The version every entry is being moved to: the type's current schema version. */
+    targetVersion: number;
+    /** Entries looked at. */
+    scanned: number;
+    /** Entries whose values were rewritten and whose version now equals the target. */
+    migrated: number;
+    /**
+     * Entries another runner had already moved between the read and the write. Not an error:
+     * it is the conditional write doing its job.
+     */
+    skipped: number;
+    failed: readonly MigrationFailure[];
+    /** True when entries are still behind, either because the cap was hit or a step failed. */
+    remaining: boolean;
+}
+interface MigrationRunOptions {
+    /** Entries per batch. Bounded so one call cannot become an unbounded read. */
+    batchSize?: number;
+    /** Batches per call. The run returns `remaining: true` when this is reached. */
+    maxBatches?: number;
+    /** Called after each batch, so a long run can show progress. */
+    onProgress?: (progress: {
+        scanned: number;
+        migrated: number;
+    }) => void;
+}
+declare const MIGRATION_BATCH_SIZE = 50;
+declare const MIGRATION_MAX_BATCHES = 20;
+interface MigrationRunDeps {
+    migrations: MigrationAdapter;
+    registry: MigrationRegistry;
+    type: ContentTypeLike;
+}
+/**
+ * Moves every entry of one content type up to its current schema version.
+ *
+ * The plan is computed per entry, from the version that entry is actually at, because a
+ * collection can hold entries at several versions at once: one written before a change,
+ * one written after, one left behind by an interrupted run.
+ *
+ * Failure behaviour, stated exactly. A transform that throws and a write that is refused
+ * are the same thing here: the entry is named in `failed`, its stored document is
+ * untouched, and the batch finishes so one bad entry does not hide the rest. The run then
+ * stops, because the selection is "everything still behind" and a failing entry would be
+ * picked up again on the next batch forever. `remaining` is true, the caller fixes the
+ * transform or the data, and runs again; everything that already moved stays moved.
+ */
+declare function runMigration(deps: MigrationRunDeps, options?: MigrationRunOptions): Promise<MigrationRunResult>;
+
+/**
+ * Moving one item of a list, as a pure function.
+ *
+ * It lives in core rather than beside either of its callers because both of them reorder
+ * for the same reason and must behave identically: the repeater field moves a row, and the
+ * Schema Builder moves a field. A drag and an arrow key are two ways to call this, never
+ * two implementations of it.
+ */
+/**
+ * Returns a new list with the item at `from` placed at `to`.
+ *
+ * An out-of-range index returns the list unchanged rather than throwing. Every caller is an
+ * event handler (the last row pressing ArrowDown, a drop outside the list), and none of
+ * them has anything useful to do with an exception.
+ */
+declare function moveItem<TItem>(items: readonly TItem[], from: number, to: number): TItem[];
+
+/**
+ * The field editor as data: the order fields are shown in, what a new field starts as,
+ * whether a key may be used, and which options are still unanswered.
+ *
+ * Nothing here renders and nothing here writes. The Schema Builder screen calls it to
+ * decide what to show and what to enable, and the same functions are callable from a test
+ * or a script without a DOM.
+ *
+ * None of it switches on a field type. The per-type answers come from each field type's own
+ * `editor` spec through the registry, which is why adding a thirteenth field type adds it
+ * to the Schema Builder with no edit in this file and none in any screen.
+ */
+interface FieldRow {
+    key: string;
+    field: FieldDefinition;
+}
+/**
+ * The field keys of a content type, in display order.
+ *
+ * `fieldOrder` leads, then any field it does not mention, in map order. Both halves are
+ * needed: a stored type's map order is whatever came back from storage, which is not a
+ * guarantee to build on, and a `fieldOrder` written before a field was added does not
+ * mention that field. An unknown key in `fieldOrder` is skipped rather than trusted, so a
+ * stale entry cannot conjure a field.
+ */
+declare function orderedFieldKeys(type: Pick<ContentTypeLike, "fields" | "fieldOrder">): readonly string[];
+/** The fields of a content type as an ordered list, which is what a form renders. */
+declare function orderedFields(type: Pick<ContentTypeLike, "fields" | "fieldOrder">): readonly FieldRow[];
+/** Moves one field. An out-of-range index is a no-op; see `moveItem`. */
+declare function moveFieldRow(rows: readonly FieldRow[], from: number, to: number): FieldRow[];
+/**
+ * Rebuilds a content type from an ordered list of fields.
+ *
+ * Writes both halves: the map, because that is what every consumer reads, and `fieldOrder`,
+ * because a map's key order carries no promise across a round trip. Validated here, so the
+ * editor fails on the form rather than on the round trip.
+ */
+declare function withFieldRows(type: ContentTypeLike, rows: readonly FieldRow[]): ContentTypeLike;
+/**
+ * Deep equality for two stored definitions, independent of key order.
+ *
+ * `JSON.stringify` is not enough on its own, and the reason is the same one `fieldOrder`
+ * exists for: a field map is an object, the editor rebuilds it in display order, and the
+ * stored copy is in whatever order it came back in. Comparing the two literally would
+ * report a difference after a load that reordered nothing, and leave the Save button
+ * enabled on a draft nobody has touched.
+ *
+ * Arrays keep their order, which is what makes a reorder, an option list and a
+ * `fieldOrder` change all register as real differences.
+ */
+declare function sameDefinition(left: ContentTypeLike, right: ContentTypeLike): boolean;
+type FieldKeyRejection = "invalid" | "reserved" | "live" | "removed";
+interface FieldKeyAvailability {
+    available: boolean;
+    reason?: FieldKeyRejection;
+    /** Ready to print, and it names what is in the way. */
+    message?: string;
+}
+/**
+ * May this content type take this field key?
+ *
+ * The removed case is the one that matters. A key whose values are still stored is not
+ * free, and saying only "already used" would send an editor looking for a field that is not
+ * on the screen; the message points at the restore instead.
+ */
+declare function checkFieldKey(type: ContentTypeLike, key: string): FieldKeyAvailability;
+/**
+ * The same question one level down, inside a repeater's nested map.
+ *
+ * Reserved keys are not checked here, and deliberately so: `status` is entry metadata at
+ * the top level and an ordinary key inside a row, and the validator agrees. Nothing is
+ * parked at this level either, because `removedFields` describes top-level keys only.
+ */
+declare function checkNestedFieldKey(fields: FieldMap, key: string): FieldKeyAvailability;
+/**
+ * A field key suggested from a label, so an editor types "Job title" and gets "jobTitle".
+ *
+ * A suggestion only: the editor can overwrite it, and `checkFieldKey` answers whether what
+ * ends up in the box is usable. A label with nothing usable in it yields an empty string
+ * rather than a made-up key, and the form then asks for one.
+ */
+declare function suggestFieldKey(label: string): string;
+/**
+ * What a newly added field of this type starts as.
+ *
+ * The per-type part comes from the field type's own `editor.defaults`, so a select starts
+ * with one option and a repeater with one nested field without this function knowing that
+ * either of them exists. An unregistered type is refused rather than guessed at.
+ */
+declare function newFieldDefinition(registry: FieldTypeRegistry, type: FieldType, label: string): FieldDefinition;
+interface FieldOptionIssue {
+    /** The option key the issue belongs to, so the control can show it. */
+    option: string;
+    message: string;
+}
+/**
+ * The options of one field that are still unanswered, named by option.
+ *
+ * Generic: a descriptor marked `required` whose value is empty is an issue, and that is the
+ * whole rule. A relation with no target and a select with no options are both reported by
+ * it, and a field type added later gets the same treatment from its own descriptors.
+ */
+declare function fieldOptionIssues(registry: FieldTypeRegistry, field: FieldDefinition): readonly FieldOptionIssue[];
+/** Every unanswered option across a whole draft, each carrying the field it belongs to. */
+declare function draftIssues(registry: FieldTypeRegistry, rows: readonly FieldRow[]): readonly (FieldOptionIssue & {
+    key: string;
+})[];
+type ValidationRuleName = keyof ValidationRules;
+interface ValidationRuleControl {
+    label: string;
+    control: "boolean" | "number" | "text";
+    help: string;
+}
+/**
+ * How each shared validation rule is edited, and what it means.
+ *
+ * Keyed by the rule rather than by the field type: `maxLength` is the same rule and the
+ * same control wherever it is offered. Which of them a given field type offers is that
+ * field type's own answer, on `editor.rules`.
+ */
+declare const VALIDATION_RULE_CONTROLS: {
+    readonly [TRule in ValidationRuleName]: ValidationRuleControl;
+};
+/** Sets or clears one rule, dropping `validation` entirely once nothing is left in it. */
+declare function withValidationRule(field: FieldDefinition, rule: ValidationRuleName, value: string | number | boolean | undefined): FieldDefinition;
+/** Sets or clears one per-type option, dropping the key when the value is empty. */
+declare function withFieldOption(field: FieldDefinition, option: string, value: unknown): FieldDefinition;
+
+/**
+ * Creating a database-defined content type: the domain half.
+ *
+ * Everything here is pure. The Schema Builder screen calls it to decide what to enable and
+ * what to say; the adapter calls the same functions again before it writes, so a request
+ * that skipped the screen is answered identically.
+ */
+/**
+ * Slugs a content type may not take.
+ *
+ * Under the layout in .docs/decisions/2026-09-18-firestore-layout.md a content type slug
+ * never becomes a top-level collection, so none of these can actually collide today. They
+ * are reserved anyway: the names are the CMS's own vocabulary, a type called `users` or
+ * `settings` would read as the admin's own section in every sidebar and URL, and a future
+ * layout change must not be blocked by a customer having taken the name.
+ *
+ * `src/firebase/paths.ts` re-exports this as `RESERVED_COLLECTIONS`, so the list is written
+ * once and the storage layer and the Schema Builder cannot drift apart.
+ */
+declare const RESERVED_TYPE_SLUGS: readonly string[];
+type SlugRejection = "invalid" | "reserved" | "taken-by-code" | "taken-by-database";
+interface SlugAvailability {
+    available: boolean;
+    reason?: SlugRejection;
+    /** Ready to print. Names the source, because "that slug is taken" is a dead end. */
+    message?: string;
+    /** Which source holds the slug already. Absent for `invalid` and `reserved`. */
+    source?: ContentTypeSource;
+}
+/**
+ * Is this slug free for a new database-defined content type?
+ *
+ * Checked against **both** sources. A slug defined in code is not available even though
+ * `schemas/` is empty and the Schema Builder's own list shows nothing, which is precisely
+ * why the message has to say where the collision is: an editor looking at an empty list and
+ * being told the name is taken has nowhere to go.
+ */
+declare function checkTypeSlug(registry: Registry, slug: string): SlugAvailability;
+/** Throws the message `checkTypeSlug` would have printed. The adapter's create guard. */
+declare function assertTypeSlugAvailable(registry: Registry, slug: string): void;
+interface NewContentTypeInput {
+    name: string;
+    slug: string;
+    kind: ContentTypeKind;
+    /** Lucide icon name from the vocabulary in .docs/styleguide/05-icons.md. */
+    icon?: string;
+    namePlural?: string;
+    description?: string;
+}
+/**
+ * The single field every new content type starts with.
+ *
+ * A content type with no fields is invalid, so creation has to seed one. A required title
+ * is the one field that is right for every content type: it is what the list view, the
+ * relation picker and the entry header all print, and an editor who wanted something else
+ * renames it rather than starting from an unusable empty type.
+ */
+declare const INITIAL_FIELD_KEY = "title";
+/**
+ * Builds the content type document a create writes, stamped at version 1.
+ *
+ * Validated here rather than at the write, so the Schema Builder fails on the form instead
+ * of on the round trip.
+ */
+declare function newContentType(input: NewContentTypeInput): ContentTypeLike;
+/**
+ * The create path in one call: collision check against both sources, then the draft.
+ *
+ * The adapter runs this again before writing, which is what makes a bypassed UI change
+ * nothing.
+ */
+declare function createContentType(registry: Registry, input: NewContentTypeInput): ContentTypeLike;
+
+/**
+ * Adding, removing, re-adding and purging one field of a database-defined content type.
+ *
+ * The rule the whole file exists for: **removing a field never destroys its values.** The
+ * definition moves from `fields` to `removedFields` and the stored values stay on every
+ * entry until somebody explicitly purges them. Two properties elsewhere are what make that
+ * work, and both are asserted by tests rather than assumed:
+ *
+ * - `schema/validate.ts` only validates keys the schema declares, so a value left behind by
+ *   a removed field cannot make an entry unsaveable.
+ * - `firebase/converters.ts#valuesToStored` carries keys it does not recognise through
+ *   untouched, so saving an entry after a removal rewrites the declared fields and leaves
+ *   the parked one exactly where it was.
+ *
+ * Every function here is pure and returns a new content type. Nothing writes.
+ */
+interface RemovalContext {
+    /** uid recorded on the parked definition. */
+    removedBy: string;
+    /** ISO 8601. Injected so a test and a migration can both be deterministic. */
+    removedAt?: string;
+}
+/** What a key currently is on a content type. Drives what the field editor may offer. */
+type FieldKeyState = "free" | "live" | "removed";
+declare function fieldKeyState(type: ContentTypeLike, key: string): FieldKeyState;
+declare function removedFieldEntries(type: ContentTypeLike): readonly (RemovedField & {
+    key: string;
+})[];
+/**
+ * Removes a field and parks its definition.
+ *
+ * Refuses to remove the last field, because a content type with no fields is invalid, and
+ * refuses to remove the field the type names as its title or its default sort: a list view
+ * that sorts by a field nobody can edit any more is a broken screen, and pointing the type
+ * elsewhere silently would be a change the editor did not ask for. Repoint the type first.
+ */
+declare function removeField(type: ContentTypeLike, key: string, context: RemovalContext): ContentTypeLike;
+/** Adds a field. Rejects a key that is live, and routes a removed key to `restoreField`. */
+declare function addField(type: ContentTypeLike, key: string, field: FieldDefinition): ContentTypeLike;
+interface RestoreOptions {
+    /**
+     * A definition to restore under, instead of the one that was parked.
+     *
+     * Only accepted when it stores values the same way, which in practice means the same
+     * `type` and the same cardinality. Restoring a `text` key as a `number` would leave every
+     * preserved value the wrong shape, and the entry would fail validation the next time
+     * anyone opened it, on data they never touched. Purge first, then add it fresh.
+     */
+    field?: FieldDefinition;
+}
+/**
+ * Re-adds a removed key, and with it the values that were preserved.
+ *
+ * This is the whole point of parking the definition rather than deleting it: the values
+ * were never dropped, so declaring the key again makes them readable exactly as they were.
+ * Nothing is written to any entry.
+ */
+declare function restoreField(type: ContentTypeLike, key: string, options?: RestoreOptions): ContentTypeLike;
+/**
+ * Drops the parked definition, after the values have been purged from the entries.
+ *
+ * The definition side of a purge only. The data side is `CmsAdapter.fieldData.purge`, and
+ * the adapter runs both in that order: values first, then this, so an interrupted purge
+ * leaves the field still listed as removed with some values gone, which is recoverable,
+ * rather than unlisted with values nobody can see, which is not.
+ */
+declare function forgetRemovedField(type: ContentTypeLike, key: string): ContentTypeLike;
+/**
+ * Do two definitions put the same shape in Firestore?
+ *
+ * Deliberately about storage, not about presentation: a label, a description, a
+ * placeholder or a validation rule may change freely across a restore, because none of them
+ * changes what is already in the document.
+ */
+declare function storesTheSameWay(left: FieldDefinition, right: FieldDefinition): boolean;
+/**
+ * The storage-relevant part of one field definition, as a string.
+ *
+ * What is in it: the type, and every option that changes the stored value. `multiple` and
+ * `many` turn a scalar into an array. `to` decides which content type a stored relation id
+ * points at. A repeater's nested map is the shape of each stored row. A date's precision
+ * decides between `YYYY-MM-DD` and a full instant.
+ *
+ * What is deliberately not in it: label, description, placeholder, hidden, readonly,
+ * validation, select option labels, and the order of the keys. Changing any of those
+ * changes the form, not the document, and a version stamp that moved for them would tell a
+ * migration runner nothing.
+ */
+declare function storageSignatureOf(field: FieldDefinition): string;
+declare function fieldMapSignature(fields: FieldMap): string;
+
+/**
+ * The schema version stamp, and the one question it answers.
+ *
+ * `content/{slug}.schemaVersion` is what the M10 migration runner reads, and every entry
+ * carries the version it was last written at. The runner's only question is: *is this entry
+ * stored in the shape the type declares today?* So the stamp has to move exactly when the
+ * answer can change, and not otherwise. A stamp that moves on every save tells the runner
+ * nothing, because every entry is then behind; a stamp that never moves tells it nothing
+ * either, because no entry is ever behind.
+ *
+ * **Bumps:** adding a field, removing a field, changing a field's type, changing a select's
+ * option values or its `multiple`, changing a relation's target or its `many`, changing a
+ * date's precision, changing a repeater's nested field map.
+ *
+ * **Does not bump:** label, plural, description, icon, placeholder, hidden, readonly,
+ * validation rules, select option labels, field order, title field, default sort,
+ * permissions, and lock state. None of them changes a stored document, so an entry written
+ * before the change is still stored exactly as the type describes.
+ *
+ * Purging a removed field's values does not bump either. The purge deletes data that the
+ * type had already stopped declaring, so the declared shape is the same before and after.
+ */
+/** Everything the stamp is computed from. Anything absent from here cannot move it. */
+declare function storageSignature(type: Pick<ContentTypeLike, "kind" | "fields">): string;
+declare const INITIAL_SCHEMA_VERSION = 1;
+declare function schemaVersionOf(type: Pick<ContentTypeLike, "schemaVersion">): number;
+/**
+ * The version the next write should carry.
+ *
+ * Computed from the stored definition and the new one, never supplied by a caller, so a
+ * client cannot stamp a version that does not describe what it is writing.
+ */
+declare function nextSchemaVersion(previous: ContentTypeLike | null, next: ContentTypeLike): number;
+/** True when the two definitions would be stamped differently. Drives the "this is a breaking change" warning. */
+declare function storageShapeChanged(previous: ContentTypeLike, next: ContentTypeLike): boolean;
+
+/**
+ * The field a content type is addressed by in a URL, if it has one.
+ *
+ * It lives in core rather than in the adapter because two callers need it and only one of
+ * them may import Firebase: the adapter looks an entry up by its slug value, and the entry
+ * form asks whether a field is the one it can answer a uniqueness question about without a
+ * composite index. A second copy of this rule would let the two disagree about which field
+ * the slug is.
+ */
+declare function slugFieldKey(type: ContentTypeLike): string | null;
+
+/**
+ * The reverse index that answers "which entries use this media item".
+ *
+ * Firestore has no reverse lookup and no join. A media reference lives inside an entry's
+ * field values, possibly several levels down inside a repeater row, and nothing about the
+ * media document names the entries that point at it. Two ways out of that were available:
+ *
+ * 1. **Scan.** On every usage question, read every entry of every content type and look
+ *    inside each one. Correct for all data, past and present, and priced at one document
+ *    read per entry per question. A customer with 20,000 entries pays 20,000 reads to
+ *    learn whether one photo may be deleted, and pays it again for the next photo. That is
+ *    not a cost a CMS may hide inside a delete button.
+ * 2. **Index.** Every entry write also writes the flat list of media ids that entry
+ *    references, into a `mediaRefs` array on the entry document itself. The question then
+ *    becomes one indexed collection-group query whose cost is the number of answers, not
+ *    the size of the database.
+ *
+ * Husk takes the index. It is written in the same document write as the values it
+ * summarizes, so it cannot drift from them: there is no second document, no transaction
+ * spanning two collections, and no background job that can fall behind. Deleting an entry
+ * deletes its index with it.
+ *
+ * Both functions below walk the stored data and recognize a reference by its shape: an
+ * object carrying a string `mediaId`. That is deliberate, and it is the reason neither of
+ * them takes a content type, a field map or a field type registry.
+ *
+ * - The shape is the contract. `types/media.ts` defines `MediaReference` as exactly this,
+ *   and nothing else in the product stores an object with a `mediaId` key.
+ * - A walk over the data cannot be wrong about what the data contains. A schema walk would
+ *   have to know which field types can hold media, recurse through repeater definitions,
+ *   and it would still miss a reference stored under a field the schema no longer declares.
+ * - It needs no registry, so the adapter indexes every entry it writes, including one
+ *   written by a script that never loads the admin's React field components.
+ *
+ * **Where the bound is, stated rather than implied.** The index exists only on entries
+ * written by a version that writes it. An entry stored before this change, or written
+ * straight into the Firestore console, carries no `mediaRefs` field and is therefore
+ * invisible to every usage question until it is saved once. The consequence is named in
+ * the UI rather than hidden: the delete warning says what the count is based on. See
+ * .docs/decisions/2026-09-18-media-usage-index.md.
+ */
+/** The entry-document field the reverse index is written to. */
+declare const MEDIA_REFS_KEY = "mediaRefs";
+/**
+ * The ceiling on indexed ids per entry.
+ *
+ * An array field is part of the document and a document is capped at 1 MiB, but the real
+ * reason for a limit is the index itself: Firestore writes one index entry per array
+ * element, so an entry holding a thousand references would cost a thousand index writes on
+ * every save. A hundred is far above any real page and low enough that the write stays
+ * ordinary. Beyond it the list is truncated rather than the save refused, because a save
+ * that fails over a bookkeeping field would be the worse outcome; the consequence is that
+ * usage for the truncated ids is under-reported, which is why the number is generous.
+ */
+declare const MAX_MEDIA_REFS = 100;
+/**
+ * Every media id an entry's stored values reference, deduplicated and ordered.
+ *
+ * Ordered because two arrays holding the same ids in a different order are the same index,
+ * and a stable order is what lets a caller compare one write against the last. Deduplicated
+ * because the same photo used twice on one page is one reference.
+ */
+declare function collectMediaIds(data: Record<string, unknown>): string[];
+/**
+ * Rewrites the denormalized `url` of every reference to one media item, anywhere in a
+ * stored entry document.
+ *
+ * Returns a new object when anything changed and `null` when nothing did, so a caller can
+ * skip a write instead of touching an entry's `updatedAt` for no reason.
+ */
+declare function retargetMediaUrls(data: Record<string, unknown>, mediaId: string, url: string): Record<string, unknown> | null;
+
+export { type BuildListQueryOptions, type ClassifiedError, CmsAdapter, type ColumnAlign, type ColumnKind, ENTRY_COLLECTION_GROUP, ERROR_CATEGORIES, EntryFilter, type EntryMigration, type EntryUniqueOptions, type ErrorCategory, type ErrorContext, type ErrorOrigin, type ErrorTreatment, FALLBACK_SORT, type FieldKeyAvailability, type FieldKeyRejection, type FieldKeyState, type FieldOptionIssue, type FieldRow, type FirestoreIndex, type FirestoreIndexField, type FormField, type FormIssue, HUSK_TAG_PREFIX, INITIAL_FIELD_KEY, INITIAL_SCHEMA_VERSION, type IndexOrder, type ListColumn, type ListColumnOptions, type ListFilterDescriptor, type ListFilterOption, ListQuery, type ListViewState, LockedTypeError, MAX_ENTRY_INDEXES, MAX_FIELD_COLUMNS, MAX_MEDIA_REFS, MEDIA_REFS_KEY, MIGRATION_BATCH_SIZE, MIGRATION_MAX_BATCHES, MigrationAdapter, type MigrationContext, type MigrationFailure, type MigrationRegistry, type MigrationRunDeps, type MigrationRunOptions, type MigrationRunResult, type NewContentTypeInput, PermissionError, RESERVED_TYPE_SLUGS, Registry, type RegistryStore, type RemovalContext, type RestoreOptions, STATUS_EFFECT, SchemaError, SingletonError, type SlugAvailability, type SlugRejection, SortSpec, type StatusSubject, type StatusTransition, UNTITLED_ENTRY, VALIDATION_RULE_CONTROLS, ValidationError, type ValidationRuleControl, type ValidationRuleName, WriteLimitError, addField, applyPlan, assertTypeSlugAvailable, assertValidContentType, buildCountQuery, buildListQuery, canSaveEntry, canSearch, checkFieldKey, checkNestedFieldKey, checkTypeSlug, classifyError, collectMediaIds, confirmationMatches, contentTypeTag, createContentType, createMigrationRegistry, createRegistryStore, defaultListSort, defineContentType, deleteConfirmationName, deleteConfirmationPhrase, deniedError, draftIssues, entryChangedSince, entrySlugTag, entryTag, entryTags, entryTitle, entryUniqueCheck, errorsUnder, fieldKeyState, fieldMapSignature, fieldOptionIssues, forgetRemovedField, formFields, formValuesFromEntry, indexCovered, initialFormValues, initialListState, isFilterableField, isHuskTag, isNarrowed, isSearching, listColumns, listFilterQuery, listFilters, mediaTag, mergeIssues, missingEntryIndexes, missingError, moveFieldRow, moveItem, newContentType, newFieldDefinition, nextSchemaVersion, nextSort, normalizeConfirmation, orderedFieldKeys, orderedFields, removeField, removedFieldEntries, requiredEntryIndexes, restoreField, retargetMediaUrls, runMigration, sameDefinition, schemaVersionOf, settingsTag, slugFieldKey, sortableFieldKeys, staleWriteError, statusTransitions, storageShapeChanged, storageSignature, storageSignatureOf, storesTheSameWay, suggestFieldKey, treatmentFor, unroutableIssues, valuesChanged, withFieldOption, withFieldRows, withValidationRule };