@dyrected/core 2.8.0 → 2.8.2

package/dist/app-config-B5tYsZaH.d.cts

@@ -0,0 +1,2404 @@
+import { icons } from 'lucide-react';
+import { LoggerOptions, DestinationStream, Logger } from 'pino';
+
+/**
+ * Minimum HTTP request context passed to every server-side hook and resolver.
+ *
+ * The full Web Standard `Request` is available as `raw` when you need it, but
+ * most hooks only need `query` (URL search parameters).
+ */
+interface HookRequestContext {
+    /** Parsed URL query-string parameters, e.g. `{ page: '2', search: 'hello' }`. */
+    query: Record<string, string>;
+    /** Incoming HTTP headers, lowercased. */
+    headers: Record<string, string>;
+    /** The raw Web Standard `Request` object. Useful for streaming or advanced header inspection. */
+    raw?: Request;
+}
+/**
+ * Base shape of an authenticated user as decoded from the JWT.
+ *
+ * The actual shape will include every field on your auth collection — this
+ * interface only guarantees the properties that Dyrected always stamps on the
+ * token. Extend it in your own codebase for stronger typing:
+ *
+ * @example
+ * declare module '@dyrected/core' {
+ *   interface AuthenticatedUser {
+ *     role: 'admin' | 'editor'
+ *     organizationId: string
+ *   }
+ * }
+ */
+interface AuthenticatedUser {
+    /** The user's document ID in the database. */
+    sub: string;
+    /** The user's email address. */
+    email?: string;
+    /** Slug of the collection this user was authenticated against. */
+    collection: string;
+    /** Array of role strings, if your auth collection has a `roles` field. */
+    roles?: string[];
+    /** Any additional fields from the auth collection document. */
+    [key: string]: unknown;
+}
+
+interface AccessFunctionArgs<TDoc extends object = Record<string, unknown>, TUser extends AuthenticatedUser = AuthenticatedUser> {
+    user: TUser | undefined;
+    doc?: TDoc;
+    data?: Partial<TDoc>;
+    req: HookRequestContext;
+}
+interface NamedAccessPolicy<TDoc extends object = Record<string, unknown>> {
+    policy: string;
+    params?: Record<string, unknown>;
+}
+type AccessResult = boolean | Record<string, unknown>;
+/**
+ * A function that determines whether the current user can perform an operation.
+ *
+ * Return `true` to allow, `false` to deny.
+ * Return a `where`-style object to allow access only to matching documents
+ * (useful for multi-tenant setups where users can only see their own data).
+ *
+ * Can also be expressed as a Jexl expression **string** for simple role checks
+ * that need to be serialised (e.g. stored in the database or sent to the Admin UI).
+ *
+ * @template TDoc  The shape of the collection's document.
+ *
+ * @example
+ * // Simple role check
+ * access: {
+ *   delete: ({ user }) => user?.roles?.includes('admin') ?? false,
+ * }
+ *
+ * @example
+ * // Row-level: users can only read their own documents
+ * access: {
+ *   read: ({ user }) => ({ owner: { equals: user?.sub } }),
+ * }
+ *
+ * @example
+ * // Jexl string — evaluated server-side
+ * access: {
+ *   update: "user.roles contains 'editor'",
+ * }
+ */
+type AccessFunction<TDoc extends object = Record<string, unknown>, TUser extends AuthenticatedUser = AuthenticatedUser> = (args: AccessFunctionArgs<TDoc, TUser>) => AccessResult | Promise<AccessResult>;
+type AccessRule<TDoc extends object = Record<string, unknown>, TUser extends AuthenticatedUser = AuthenticatedUser> = boolean | string | AccessFunction<TDoc, TUser> | NamedAccessPolicy<TDoc>;
+type AccessPolicyResolver<TDoc extends object = Record<string, unknown>, TUser extends AuthenticatedUser = AuthenticatedUser> = (args: AccessFunctionArgs<TDoc, TUser> & {
+    params?: Record<string, unknown>;
+}) => AccessResult | Promise<AccessResult>;
+
+/**
+ * The minimum shape of every document returned by the database layer.
+ *
+ * All documents have an `id` field assigned by the adapter. Additional fields
+ * are stored as `unknown` until you narrow them with your own interface.
+ *
+ * Use this as the base when declaring your collection document types:
+ * ```ts
+ * interface Post extends BaseDocument {
+ *   title: string
+ *   slug: string
+ * }
+ * ```
+ */
+interface BaseDocument {
+    /** The document's unique identifier, assigned by the database adapter. */
+    id: string;
+    [key: string]: any;
+}
+/**
+ * The envelope returned by collection list endpoints (`GET /api/collections/:slug`).
+ *
+ * @template T  The document type.
+ */
+interface PaginatedResult<T = Record<string, any>> {
+    /** The documents on the current page. */
+    docs: T[];
+    /** Total number of documents matching the query (across all pages). */
+    total: number;
+    /** Maximum number of documents per page as requested. */
+    limit: number;
+    /** The current page number (1-indexed). */
+    page: number;
+    /** Total number of pages given the current `limit`. */
+    totalPages: number;
+    /** Whether a next page exists. */
+    hasNextPage: boolean;
+    /** Whether a previous page exists. */
+    hasPrevPage: boolean;
+}
+/**
+ * Metadata returned after a file is uploaded and stored.
+ * Stored on the document in upload collections.
+ */
+interface FileData {
+    filename: string;
+    filesize?: number;
+    mimeType: string;
+    /** Public URL of the stored file. */
+    url: string;
+    width?: number;
+    height?: number;
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Base64-encoded BlurHash string for progressive image loading. */
+    blurhash?: string;
+    /** `'upload'` for server-stored files; `'external'` for provider-managed files. */
+    type?: "upload" | "external";
+    provider?: string;
+    provider_metadata?: unknown;
+    [key: string]: unknown;
+}
+
+/** A valid icon component name from the Lucide icon set bundled with Dyrected Admin. */
+type AdminIconName = keyof typeof icons;
+/** Ordered custom component keys rendered around the built-in Admin dashboard. */
+interface AdminDashboardComponentSlots {
+    beforeDashboard?: string[];
+    afterDashboard?: string[];
+}
+/** Ordered custom component keys rendered around a collection's list content. */
+interface CollectionListComponentSlots {
+    beforeList?: string[];
+    beforeListTable?: string[];
+    afterListTable?: string[];
+    afterList?: string[];
+}
+/**
+ * Branding and metadata options for the Dyrected Admin UI.
+ *
+ * @example
+ * admin: {
+ *   branding: {
+ *     logo: '/logo.svg',
+ *     primaryColor: '#6366f1',
+ *   },
+ *   meta: {
+ *     titleSuffix: '- My App',
+ *   },
+ * }
+ */
+interface AdminConfig {
+    /** Custom component slots around the built-in dashboard. */
+    components?: AdminDashboardComponentSlots;
+    branding?: {
+        /** Full logo image shown in the expanded sidebar. URL or imported image asset. */
+        logo?: string;
+        /** Compact logo mark used in the collapsed sidebar state. */
+        logoMark?: string;
+        /** Text alternative or addition to the logo image. */
+        logoText?: string;
+        /**
+         * Brand colour used for committed, filled actions — Save, Create, Upload —
+         * and active/selected states. Accepts a hex string, a named colour
+         * (`amber`, `lime`, `violet`, `green`, `blue`, `red`, `purple`, `orange`),
+         * or a raw HSL triplet (`"217 91% 60%"`). Applied in both light and dark mode.
+         *
+         * This is one half of the two-colour brand model. Use {@link accentColor}
+         * for links and navigation accents. If you only set `primaryColor`, it is
+         * reused for accents too, matching the single-brand-colour look.
+         * @example '#6366f1'
+         * @example 'blue'
+         * @example 'hsl(240 50% 60%)'
+         */
+        primaryColor?: string;
+        /**
+         * Brand colour used for links, active navigation details, hover text, and
+         * focus rings — the "accent" half of the two-colour brand model, mapped to
+         * the admin's `--intelligence` token. Accepts the same formats as
+         * {@link primaryColor} and applies in both light and dark mode.
+         *
+         * Set this when your brand has a distinct link/accent colour separate from
+         * your primary action colour. When omitted, accents fall back to
+         * `primaryColor` (if set) or the built-in default.
+         * @example '#8b5cf6'
+         * @example 'violet'
+         */
+        accentColor?: string;
+        /** Browser tab favicon URL. */
+        favicon?: string;
+        /** Font family for body and UI text. Must be loaded separately. */
+        fontSans?: string;
+        /** Font family for headings. Must be loaded separately. */
+        fontSerif?: string;
+    };
+    meta?: {
+        /**
+         * String appended to every Admin page's `<title>`.
+         * @default '- Dyrected'
+         */
+        titleSuffix?: string;
+    };
+    /**
+     * The canonical/base URL of the frontend website for links and iframe live previews.
+     */
+    siteUrl?: string;
+}
+
+type DeclarativeHookExpression = string;
+/**
+ * @deprecated Use {@link FieldBeforeChangeHook} or `FieldAfterReadHook` instead.
+ * This alias remains for backwards compatibility.
+ */
+type FieldHook<TDoc extends object = Record<string, unknown>, TValue = unknown> = FieldBeforeChangeHook<TValue, TDoc>;
+/**
+ * Runs before Dyrected queries the database for a list or single-document fetch.
+ *
+ * Return a new `where` query object to override or extend the current filter.
+ * Return `undefined` (or nothing) to leave the query unchanged.
+ */
+type CollectionBeforeReadHook = (args: {
+    req: HookRequestContext;
+    query?: Record<string, unknown>;
+    user?: AuthenticatedUser;
+    db: ReadonlyDatabaseAdapter;
+}) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
+type CollectionBeforeReadHookEntry = CollectionBeforeReadHook | DeclarativeHookExpression;
+/**
+ * Runs after a document (or list of documents) is fetched from the database,
+ * before the response is sent to the client.
+ */
+type CollectionAfterReadHook<TDoc extends object = Record<string, unknown>> = (args: {
+    doc: TDoc;
+    req: HookRequestContext;
+    user?: AuthenticatedUser;
+    db: ReadonlyDatabaseAdapter;
+}) => TDoc | Promise<TDoc>;
+type CollectionAfterReadHookEntry<TDoc extends object = Record<string, unknown>> = CollectionAfterReadHook<TDoc> | DeclarativeHookExpression;
+/**
+ * Runs **before** a document is created or updated in the database.
+ */
+type CollectionBeforeChangeHook<TDoc extends object = Record<string, unknown>> = (args: {
+    data: Partial<TDoc>;
+    doc?: TDoc;
+    req: HookRequestContext;
+    user?: AuthenticatedUser;
+    operation: "create" | "update";
+    db: ReadonlyDatabaseAdapter;
+}) => Partial<TDoc> | void | Promise<Partial<TDoc> | void>;
+type CollectionBeforeChangeHookEntry<TDoc extends object = Record<string, unknown>> = CollectionBeforeChangeHook<TDoc> | DeclarativeHookExpression;
+/**
+ * Runs **after** a document is created or updated in the database.
+ */
+type CollectionAfterChangeHook<TDoc extends object = Record<string, unknown>> = (args: {
+    doc: TDoc;
+    previousDoc?: TDoc;
+    req: HookRequestContext;
+    user?: AuthenticatedUser;
+    operation: "create" | "update";
+    db: DatabaseAdapter;
+}) => void | Promise<void>;
+/**
+ * Runs **before** a document is deleted from the database.
+ */
+type CollectionBeforeDeleteHook<TDoc extends object = Record<string, unknown>> = (args: {
+    id: string;
+    doc: TDoc;
+    req: HookRequestContext;
+    user?: AuthenticatedUser;
+    db: ReadonlyDatabaseAdapter;
+}) => void | Promise<void>;
+/**
+ * Runs **after** a document has been deleted from the database.
+ */
+type CollectionAfterDeleteHook<TDoc extends object = Record<string, unknown>> = (args: {
+    id: string;
+    doc: TDoc;
+    req: HookRequestContext;
+    user?: AuthenticatedUser;
+    db: DatabaseAdapter;
+}) => void | Promise<void>;
+/** @see {@link CollectionBeforeReadHook} */
+type GlobalBeforeReadHook = CollectionBeforeReadHook;
+type GlobalBeforeReadHookEntry = CollectionBeforeReadHookEntry;
+/**
+ * Runs after the global document is fetched, before the response is sent.
+ */
+type GlobalAfterReadHook<TDoc extends object = Record<string, unknown>> = (args: {
+    doc: TDoc;
+    req: HookRequestContext;
+    user?: AuthenticatedUser;
+    db: ReadonlyDatabaseAdapter;
+}) => TDoc | Promise<TDoc>;
+type GlobalAfterReadHookEntry<TDoc extends object = Record<string, unknown>> = GlobalAfterReadHook<TDoc> | DeclarativeHookExpression;
+/**
+ * Runs before the global document is updated.
+ * Operation is always `'update'` (globals cannot be created or deleted).
+ */
+type GlobalBeforeChangeHook<TDoc extends object = Record<string, unknown>> = (args: {
+    data: Partial<TDoc>;
+    doc?: TDoc;
+    req: HookRequestContext;
+    user?: AuthenticatedUser;
+    operation: "update";
+    db: ReadonlyDatabaseAdapter;
+}) => Partial<TDoc> | void | Promise<Partial<TDoc> | void>;
+type GlobalBeforeChangeHookEntry<TDoc extends object = Record<string, unknown>> = GlobalBeforeChangeHook<TDoc> | DeclarativeHookExpression;
+/**
+ * Runs after the global document is updated. Side-effects only.
+ */
+type GlobalAfterChangeHook<TDoc extends object = Record<string, unknown>> = (args: {
+    doc: TDoc;
+    previousDoc?: TDoc;
+    req: HookRequestContext;
+    user?: AuthenticatedUser;
+    operation: "update";
+    db: DatabaseAdapter;
+}) => void | Promise<void>;
+/**
+ * @deprecated Use the specific hook types instead:
+ * `CollectionBeforeChangeHook`, `CollectionAfterReadHook`, etc.
+ *
+ * This broad type remains for backwards compatibility with the internal hook runner.
+ */
+type HookFunction<TDoc extends object = Record<string, unknown>> = (args: {
+    data?: Partial<TDoc>;
+    doc?: TDoc;
+    user?: AuthenticatedUser;
+    req?: HookRequestContext;
+    operation?: "create" | "update" | "delete";
+    db?: DatabaseAdapter;
+    [key: string]: unknown;
+}) => unknown | Promise<unknown>;
+
+declare const LIFECYCLE_EVENT_NAMES: readonly ["revision.created", "workflow.transitioned", "entry.published", "entry.unpublished"];
+type LifecycleEventName = (typeof LIFECYCLE_EVENT_NAMES)[number];
+interface WorkflowState {
+    /** Stable machine-readable state key. */
+    name: string;
+    /** Label rendered in the Admin UI. */
+    label: string;
+    /** Marks the state whose revision is visible to public readers. */
+    published?: boolean;
+    /** Optional visual tone used by the Admin UI. */
+    color?: "neutral" | "warning" | "success" | "danger" | "info";
+}
+interface WorkflowTransition {
+    /** Stable transition key used by the REST and SDK APIs. */
+    name: string;
+    label: string;
+    from: string | string[];
+    to: string;
+    /** Every listed capability is required. */
+    requiredCapabilities?: string[];
+    /** Require a non-empty comment when performing the transition. */
+    requireComment?: boolean;
+    /** Remove the public snapshot after this transition commits. */
+    unpublish?: boolean;
+}
+interface WorkflowRole {
+    /** Existing user role value, for example `editor` or `publisher`. */
+    role: string;
+    capabilities: string[];
+}
+/**
+ * Configuration for a collection's editorial workflow: the states a document
+ * can be in, the transitions between them, and the roles allowed to perform
+ * each. Attach it to a collection's `workflow`, or build one with
+ * `definePublishingWorkflow`.
+ */
+interface WorkflowConfig<TDoc extends object = Record<string, unknown>> {
+    /** The state every new document starts in, e.g. `"draft"`. */
+    initialState: string;
+    /** State used for a new working revision created from published content. */
+    draftState?: string;
+    /** All states a document can occupy. Exactly one should be marked `published`. */
+    states: WorkflowState[];
+    /** The allowed moves between states, each with its own capability and comment rules. */
+    transitions: WorkflowTransition[];
+    /** Maps values in `user.roles` to workflow capabilities. */
+    roles?: WorkflowRole[];
+    /** Server-side hooks that run around every transition. */
+    hooks?: {
+        /** Runs before a transition commits — throw to validate or block the move. */
+        beforeTransition?: CollectionBeforeTransitionHook<TDoc>[];
+        /** Runs after a transition commits — trigger notifications or downstream work. */
+        afterTransition?: CollectionAfterTransitionHook<TDoc>[];
+    };
+}
+interface WorkflowMetadata {
+    /** The document's current workflow state, e.g. `"draft"` or `"published"`. */
+    state: string;
+    /** Revision counter, incremented on every committed transition. */
+    revision: number;
+    /** Revision number currently exposed as the public snapshot, once published. */
+    publishedRevision?: number;
+    /** ISO timestamp of the most recent publish. */
+    publishedAt?: string;
+    /** Id of the user who last published this document. */
+    publishedBy?: string;
+    /** Transitions currently allowed for the requesting user. Response-only. */
+    availableTransitions?: string[];
+}
+interface WorkflowTransitionContext<TDoc extends object = Record<string, unknown>> {
+    /** The transition being performed. */
+    transition: WorkflowTransition;
+    /** State the document is moving out of. */
+    from: string;
+    /** State the document is moving into. */
+    to: string;
+    /** The document as it stands before the transition commits. */
+    doc: TDoc;
+    /** The user performing the transition, when the request is authenticated. */
+    user?: AuthenticatedUser;
+    /** Comment supplied with the transition; required when `requireComment` is set. */
+    comment?: string;
+    /** Request context for the transition. */
+    req: HookRequestContext;
+    /** Transaction-scoped database adapter for reads and writes inside the hook. */
+    db: DatabaseAdapter;
+}
+type CollectionBeforeTransitionHook<TDoc extends object = Record<string, unknown>> = (args: WorkflowTransitionContext<TDoc>) => void | Promise<void>;
+type CollectionAfterTransitionHook<TDoc extends object = Record<string, unknown>> = (args: WorkflowTransitionContext<TDoc> & {
+    event: LifecycleEvent;
+}) => void | Promise<void>;
+interface LifecycleEvent<TPayload = Record<string, unknown>> {
+    /** Unique id for this event. */
+    id: string;
+    /** The lifecycle event name, e.g. `"workflow.transitioned"` or `"entry.published"`. */
+    name: LifecycleEventName;
+    /** Slug of the collection the event is about. */
+    collection: string;
+    /** Id of the document the event is about. */
+    documentId: string;
+    /** ISO timestamp of when the event occurred. */
+    occurredAt: string;
+    /** Id of the user who triggered the event, when known. */
+    actorId?: string;
+    /** Event-specific data, such as the transition name and affected revision. */
+    payload: TPayload;
+    /** Number of delivery attempts made so far. */
+    attempts: number;
+    /** Current delivery status as the dispatcher works through the queue. */
+    status: "pending" | "processing" | "delivered" | "failed";
+    /** ISO timestamp of the next delivery retry, while pending. */
+    nextAttemptAt?: string;
+    /** ISO timestamp of successful delivery. */
+    deliveredAt?: string;
+    /** Message from the most recent failed delivery attempt. */
+    lastError?: string;
+}
+type LifecycleEventHandler = (event: LifecycleEvent) => void | Promise<void>;
+
+type DetailSpan = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+type DisplayVariant = "text" | "badge" | "code-badge" | "code" | "copyable" | "link" | "url" | "email" | "phone" | "currency" | "percent" | "progress" | "star" | "star-rating" | "boolean" | "date" | "datetime" | "time" | "relative" | "image" | "avatar" | "color" | "color-swatches" | "icon" | "key-value" | "table" | "tags" | "badges" | "json";
+interface DisplayFieldOptions {
+    label?: string;
+    hideLabel?: boolean;
+    tooltip?: string;
+    span?: DetailSpan;
+    display?: DisplayVariant;
+    format?: "currency" | "date" | "datetime" | "relative" | "number" | "percent" | string;
+    currency?: string;
+    badgeColors?: Record<string, string>;
+    keyLabel?: string;
+    valueLabel?: string;
+    emptyText?: string;
+    hideIfEmpty?: boolean;
+    /**
+     * When true, allows inline editing of this field in the Detail View
+     * via an interactive toggle.
+     */
+    editable?: boolean;
+    /**
+     * Visibility condition for this field item.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     * When false or evaluating to falsy, this item is hidden in the Detail View.
+     *
+     * @example `visible: "doc.status == 'published'"`
+     * @example `visible: false`
+     */
+    visible?: string | boolean;
+}
+interface DetailField {
+    type: "field";
+    field: string;
+    options?: DisplayFieldOptions;
+}
+interface DetailSectionOptions {
+    icon?: string;
+    badge?: string;
+    badgeColor?: string;
+    description?: string;
+    span?: DetailSpan;
+    columns?: number;
+    collapsible?: boolean;
+    collapsedByDefault?: boolean;
+    /**
+     * Visibility condition for this section.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     *
+     * @example `visible: "user.roles != null and 'admin' in user.roles"`
+     */
+    visible?: string | boolean;
+}
+interface DetailSection {
+    type: "section";
+    title: string;
+    items: DetailItem[];
+    options?: DetailSectionOptions;
+}
+interface DetailTabOptions {
+    icon?: string;
+    badge?: string;
+    badgeColor?: string;
+    /**
+     * Visibility condition for this individual tab.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     */
+    visible?: string | boolean;
+}
+interface DetailTab {
+    type: "tab";
+    label: string;
+    items: DetailItem[];
+    options?: DetailTabOptions;
+}
+interface DetailTabsOptions {
+    span?: DetailSpan;
+    defaultTab?: string;
+    /**
+     * Visibility condition for this tab container.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     */
+    visible?: string | boolean;
+}
+interface DetailTabs {
+    type: "tabs";
+    tabs: DetailTab[];
+    options?: DetailTabsOptions;
+}
+interface DetailGridOptions {
+    span?: DetailSpan;
+    /**
+     * Visibility condition for this grid container.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     */
+    visible?: string | boolean;
+}
+interface DetailGrid {
+    type: "grid";
+    columns: number;
+    items: DetailItem[];
+    options?: DetailGridOptions;
+}
+interface DetailRepeatOptions {
+    layout?: "table" | "cards" | "list";
+    emptyText?: string;
+    span?: DetailSpan;
+    /**
+     * Visibility condition for this repeat container.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     */
+    visible?: string | boolean;
+    /** Field name in each row to use as the card header title (e.g. 'title', 'key', 'name') */
+    useAsTitle?: string;
+    /** Field name in each row to use as the card header title (alias for useAsTitle) */
+    titleField?: string;
+    /** Static card title prefix or template (e.g. 'Category' or 'Card #{index}') */
+    title?: string;
+    /** Optional icon name for card header */
+    icon?: string;
+    /** Number of grid columns for cards layout (1, 2, 3, or 4; defaults to 3) */
+    columns?: 1 | 2 | 3 | 4;
+}
+interface DetailRepeat {
+    type: "repeat";
+    field: string;
+    items: DetailItem[];
+    options?: DetailRepeatOptions;
+}
+type ComputedHandler<TDoc = any> = (context: {
+    doc: TDoc;
+    user?: any;
+    db?: any;
+}) => any | Promise<any>;
+interface DetailComputedOptions<TDoc = any> {
+    id?: string;
+    expression?: string;
+    handler?: ComputedHandler<TDoc>;
+    span?: DetailSpan;
+    format?: string;
+    currency?: string;
+    /**
+     * Visibility condition for this computed card.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     */
+    visible?: string | boolean;
+}
+interface DetailComputed<TDoc = any> {
+    type: "computed";
+    id?: string;
+    label: string;
+    expression?: string;
+    handler?: ComputedHandler<TDoc>;
+    options?: DetailComputedOptions<TDoc>;
+}
+interface DetailDividerOptions {
+    span?: DetailSpan;
+    /**
+     * Visibility condition for this divider.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     */
+    visible?: string | boolean;
+    spacing?: "sm" | "md" | "lg" | "none";
+}
+interface DetailDivider {
+    type: "divider";
+    options?: DetailDividerOptions;
+}
+interface DetailTextOptions {
+    span?: DetailSpan;
+    /**
+     * Visibility condition for this text block.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     */
+    visible?: string | boolean;
+    variant?: "body" | "heading" | "subheading" | "muted" | "caption" | "callout" | "info" | "warning";
+    className?: string;
+}
+interface DetailText {
+    type: "text";
+    content: string;
+    options?: DetailTextOptions;
+}
+interface DetailCustomOptions<TDoc = any> {
+    span?: DetailSpan;
+    /**
+     * Visibility condition for this custom component.
+     * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
+     */
+    visible?: string | boolean;
+    props?: Record<string, any>;
+    render?: (context: {
+        doc: TDoc;
+        user?: any;
+        [key: string]: any;
+    }) => any;
+}
+interface DetailCustom<TDoc = any> {
+    type: "custom";
+    name: string;
+    options?: DetailCustomOptions<TDoc>;
+}
+type DetailItem<TDoc = any> = DetailSection | DetailTabs | DetailGrid | DetailField | DetailRepeat | DetailComputed<TDoc> | DetailDivider | DetailText | DetailCustom<TDoc> | string;
+type DetailSchema<TDoc = any> = DetailItem<TDoc>[];
+
+/**
+ * Configures account lockout behavior for an auth-enabled collection.
+ *
+ * This protects collection login endpoints from repeated password guessing by
+ * temporarily locking an account after too many failed attempts.
+ */
+interface AuthConfig {
+    /**
+     * How many failed login attempts are allowed before the account is locked.
+     *
+     * Defaults to `5`. Set to `0` to disable Dyrected's built-in account lockout
+     * for this collection.
+     */
+    maxLoginAttempts?: number;
+    /**
+     * How long, in milliseconds, an account stays locked after reaching the
+     * failed-attempt limit.
+     *
+     * Defaults to `10 * 60 * 1000` (10 minutes).
+     */
+    lockTime?: number;
+}
+/**
+ * Use this contract when you want the exact shape of a collection config.
+ *
+ * Most collection work comes down to a small set of top-level options: giving
+ * the collection a stable slug, defining its fields, deciding how it should
+ * appear in the Admin UI, and choosing whether it also handles access, hooks,
+ * auth, uploads, workflows, or other optional behavior.
+ *
+ * Pass your document's TypeScript type as the generic parameter `TDoc` to get
+ * fully typed hooks and access functions.
+ *
+ * @example
+ * ```ts
+ * interface Post {
+ *   id: string
+ *   title: string
+ *   slug: string
+ *   status: 'draft' | 'published'
+ *   publishedAt?: string
+ * }
+ *
+ * export const Posts = defineCollection<Post>({
+ *   slug: 'posts',
+ *   hooks: {
+ *     beforeChange: [({ data, operation }) => {
+ *       // `data` is typed as Partial<Post>
+ *       if (operation === 'create') return { ...data, status: 'draft' }
+ *       return data
+ *     }],
+ *     afterChange: [({ doc, previousDoc }) => {
+ *       // `doc` and `previousDoc` are typed as Post
+ *       if (doc.status !== previousDoc?.status) notifySubscribers(doc)
+ *     }],
+ *   },
+ *   fields: [...],
+ * })
+ * ```
+ *
+ * @see {@link https://dyrected.com/docs/model-content/configuration/collections Collections documentation}
+ * @template TDoc The TypeScript shape of a document in this collection.
+ * Defaults to `Record<string, unknown>` for untyped usage.
+ */
+interface CollectionConfig<TDoc extends object = Record<string, unknown>> {
+    /**
+     * Unique identifier for this collection.
+     *
+     * Dyrected uses the slug for API routes, SDK calls, Admin URLs, and as the
+     * underlying database table or collection name. Treat it as part of the
+     * long-term data contract rather than a cosmetic label.
+     *
+     * Use kebab-case, for example `'blog-posts'`, `'team-members'`, or
+     * `'contact-submissions'`.
+     */
+    slug: string;
+    /**
+     * Restricts this collection to one specific site in a multi-tenant setup.
+     *
+     * Use this when the collection should belong to a single site rather than
+     * the whole installation. When set, only requests bearing a matching
+     * `X-Site-Id` header can access it.
+     */
+    siteId?: string;
+    /**
+     * If `true`, this collection is shared across all sites in a multi-tenant
+     * setup and accessible regardless of the `X-Site-Id` header.
+     *
+     * Use this for content that should stay common across sites, such as shared
+     * taxonomies, reusable assets, or centrally managed reference data.
+     */
+    shared?: boolean;
+    /**
+     * Human-readable names for documents in this collection, shown in the Admin UI.
+     *
+     * Use this when the slug is technical or when you want the dashboard to read
+     * more naturally. For example, `slug: 'people'` might use
+     * `labels: { singular: 'Person', plural: 'People' }`.
+     *
+     * @see {@link https://dyrected.com/docs/model-content/configuration/collections#labels Collections labels}
+     */
+    labels?: {
+        singular: string;
+        plural: string;
+    };
+    /**
+     * If `true` or an auth config object, this collection is an auth collection. It gains
+     * `POST /api/collections/:slug/login` and `POST /api/collections/:slug/logout`
+     * endpoints, and documents are expected to have a `password` field.
+     *
+     * Turn this on when each document should behave like an account that can log
+     * in, hold credentials, and participate in user flows. Typical examples are
+     * `users`, `admins`, `members`, or `customers`.
+     *
+     * Pass an object when you want to tune built-in account lockout behavior for
+     * repeated failed logins.
+     *
+     * @see {@link https://dyrected.com/docs/editor-experience/editor-accounts Authentication overview}
+     */
+    auth?: boolean | AuthConfig;
+    /**
+     * If `true` or a config object, this collection supports file uploads.
+     * Documents gain file-related fields (`url`, `filename`, `mimeType`, etc.)
+     * and the create endpoint accepts `multipart/form-data`.
+     *
+     * Turn this on when each document in the collection should represent a
+     * stored file, such as an image, PDF, video, or downloadable asset.
+     *
+     * @see {@link https://docs.dyrected.com/docs/self-hosted/model-content/media/overview Upload overview}
+     */
+    upload?: boolean | UploadConfig;
+    /**
+     * Field definitions that make up the document schema for this collection.
+     *
+     * This is the main schema contract for every document in the collection. It
+     * decides what editors can fill in, how data is validated, how records are
+     * stored, and what the API and SDK return.
+     *
+     * In practice, fields are where you model the actual content structure of the
+     * collection: simple values such as text and dates, relationships to other
+     * collections, nested objects and arrays, and flexible `blocks` fields for
+     * reusable page sections or long-form layouts.
+     *
+     * @see {@link https://dyrected.com/docs/model-content/fields/overview Fields overview}
+     * @see {@link https://dyrected.com/docs/model-content/fields/blocks Blocks and page sections}
+     */
+    fields: Field[];
+    /**
+     * If `true`, Dyrected automatically adds the built-in system fields
+     * `createdAt`, `updatedAt`, `createdBy`, and `updatedBy` to every document.
+     * Defaults to `true`.
+     */
+    timestamps?: boolean;
+    /**
+     * Initial documents to seed into this collection the first time it is
+     * fetched and found to be empty.
+     *
+     * Use this for starter records, demo content, or sensible defaults that
+     * should appear automatically before editors create anything themselves.
+     */
+    initialData?: Partial<TDoc>[];
+    /**
+     * If `true`, every create, update, and delete operation on this collection
+     * is logged to the `__audit` collection with before/after snapshots and the
+     * acting user's identity.
+     *
+     * Turn this on when you need accountability around changes, such as knowing
+     * who changed what, inspecting before-and-after state, or supporting
+     * compliance and operational review.
+     */
+    audit?: boolean;
+    /**
+     * Optional state-machine workflow for this collection. Workflow-enabled
+     * entries keep an editable working revision and an independent public
+     * snapshot, so editing published content never changes the live response.
+     *
+     * Use this when content moves through stages such as draft, review, and
+     * published, or when teams need an approval process before changes go live.
+     */
+    workflow?: WorkflowConfig<TDoc>;
+    /**
+     * If `true`, enables zero-config draft and publish functionality.
+     * Documents start as drafts, editors can save working drafts without affecting
+     * live content, and any authorized editor can publish or unpublish entries.
+     */
+    drafts?: boolean;
+    /**
+     * Collection-level access control.
+     *
+     * Each key is an operation; the value can be a function, a Jexl string, a
+     * boolean, or a named policy reference. Returning `true` allows access and
+     * `false` denies it. Returning a `where`-style object grants access only to
+     * matching documents.
+     *
+     * @example
+     * access: {
+     *   read: () => true,
+     *   create: ({ user }) => !!user,
+     *   update: ({ user }) => user?.roles?.includes('editor') ?? false,
+     *   delete: ({ user }) => user?.roles?.includes('admin') ?? false,
+     * }
+     *
+     * @see {@link https://docs.dyrected.com/docs/self-hosted/model-content/content-rules/access-control/overview Access control overview}
+     */
+    access?: {
+        read?: AccessRule<TDoc>;
+        create?: AccessRule<TDoc>;
+        update?: AccessRule<TDoc>;
+        delete?: AccessRule<TDoc>;
+        /**
+         * Controls who can read this collection's audit log (`GET /:slug/__audit`),
+         * for collections with `audit` enabled. Falls back to the `read` rule when
+         * omitted, so the audit trail is visible to whoever can read the documents.
+         * Set it explicitly to gate the audit log separately — for example, admins
+         * only, even on a collection anyone can read.
+         */
+        readAudit?: AccessRule<TDoc>;
+    };
+    /**
+     * Collection-level lifecycle hooks.
+     *
+     * Hooks run in the order they appear in the array. The return value of each
+     * hook is passed as the input to the next. Throwing inside any hook aborts
+     * the operation and returns a `500` error.
+     *
+     * See the Hooks reference for the full lifecycle diagram.
+     *
+     * @see {@link https://docs.dyrected.com/docs/self-hosted/model-content/content-rules/hooks Hooks overview}
+     * @see {@link https://docs.dyrected.com/docs/self-hosted/deployment-and-operations/server-runtime/hooks/collections Collection hooks}
+     */
+    hooks?: {
+        /**
+         * Runs before the database is queried. Return a modified `where` object
+         * to override the query filter.
+         */
+        beforeRead?: CollectionBeforeReadHookEntry[];
+        /**
+         * Runs after documents are fetched. Return a modified doc to change what
+         * the client receives. Runs on every document in a list response.
+         */
+        afterRead?: CollectionAfterReadHookEntry<TDoc>[];
+        /**
+         * Runs before create or update. Return modified data to change what is
+         * written to the database. Throw to abort the write entirely.
+         */
+        beforeChange?: CollectionBeforeChangeHookEntry<TDoc>[];
+        /**
+         * Runs after create or update is committed. For side-effects only:
+         * webhooks, cache busting, and notifications. Return value is ignored.
+         *
+         * Errors are isolated: caught, logged, and discarded so a failing
+         * side-effect never turns a successful write into an HTTP 500.
+         * See `CollectionAfterChangeHook` for await-vs-fire-and-forget guidance.
+         */
+        afterChange?: CollectionAfterChangeHook<TDoc>[];
+        /** Runs before a document is deleted. Throw to cancel the deletion. */
+        beforeDelete?: CollectionBeforeDeleteHook<TDoc>[];
+        /**
+         * Runs after a document has been deleted. For cleanup side-effects only.
+         *
+         * Errors are isolated: caught, logged, and discarded. The deletion is
+         * already committed and will not be undone.
+         */
+        afterDelete?: CollectionAfterDeleteHook<TDoc>[];
+    };
+    /**
+     * Admin UI configuration for this collection.
+     *
+     * @see {@link https://dyrected.com/docs/model-content/configuration/collections#admin-options Admin options}
+     */
+    admin?: {
+        /**
+         * Lucide icon displayed beside this collection in the Admin sidebar.
+         * Uses Lucide component names, e.g. `'Newspaper'` or `'ShoppingBag'`.
+         */
+        icon?: AdminIconName;
+        /** Custom component slots for this collection's list view. */
+        components?: CollectionListComponentSlots;
+        /**
+         * The field name used as the document's display title in the Admin list
+         * view and breadcrumbs. Defaults to `'title'` if the field exists.
+         */
+        useAsTitle?: string;
+        /**
+         * Field names to show as columns in the Admin list view.
+         * Defaults to a sensible set of the first few non-structural fields.
+         */
+        defaultColumns?: string[];
+        /** Short helper copy rendered under the collection title in the Admin list view. */
+        description?: string;
+        /**
+         * Field names included in backend free-text search for this collection.
+         * When omitted, Dyrected infers a conservative default from common text-like fields.
+         */
+        searchableFields?: string[];
+        /**
+         * Groups this collection under a named section in the Admin sidebar.
+         * Collections with the same `group` are visually grouped together.
+         */
+        group?: string;
+        /** If `true`, this collection is not shown in the Admin UI sidebar. */
+        hidden?: boolean;
+        /** If `false`, disables the filter UI entirely for this collection. Defaults to `true`. */
+        filterable?: boolean;
+        /**
+         * Enables draft autosave in the Admin editor for workflow-enabled
+         * collections. Defaults to `true` when the collection uses `workflow` or
+         * `drafts: true`.
+         */
+        autosave?: boolean;
+        /**
+         * Debounce duration in milliseconds for Admin draft autosave.
+         * Defaults to `1500`.
+         */
+        autosaveDelayMs?: number;
+        /**
+         * URL to open in the Live Preview pane when editing a document.
+         *
+         * Pass a Jexl string to keep the config serializable, for example
+         * `'slug == "home" ? "/" : "/" + slug'`. This is usually the best
+         * default, especially when the schema needs to stay portable across
+         * environments such as Dyrected Cloud.
+         *
+         * Pass a function when you need custom runtime logic in a self-hosted
+         * project.
+         *
+         * @example
+         * previewUrl: 'slug == "home" ? "/" : "/" + slug'
+         *
+         * @example
+         * previewUrl: (doc) => `/blog/${doc.slug}`
+         */
+        previewUrl?: string | ((doc: TDoc, opts: {
+            locale?: string;
+        }) => string | null);
+        /**
+         * How the Live Preview pane communicates with the frontend.
+         * - `postMessage` sends a `postMessage` with the current doc data.
+         * - `token` passes a short-lived preview token as a query parameter.
+         */
+        previewMode?: "postMessage" | "token";
+        /**
+         * Frontend URL pattern for this collection, used by `url` fields to
+         * resolve internal links. Use `{fieldName}` placeholders.
+         *
+         * This is a plain route pattern string, not a Jexl expression.
+         *
+         * @example
+         * urlPattern: '/blog/{slug}' // /blog/my-post
+         * urlPattern: '/{slug}' // /about
+         */
+        urlPattern?: string;
+    };
+    /**
+     * Custom detail view layout configuration for the Admin UI.
+     */
+    detail?: DetailSchema<TDoc> | false;
+}
+/**
+ * Defines a Dyrected global — a singleton document without pagination or IDs.
+ *
+ * Globals are ideal for site-wide settings, feature flags, or any data where
+ * there is always exactly one record, such as `site-settings`, `navigation`,
+ * or `theme`.
+ *
+ * Pass your document's TypeScript type as the generic parameter `TDoc` to get
+ * fully typed hooks.
+ *
+ * @example
+ * ```ts
+ * interface SiteSettings {
+ *   siteName: string
+ *   tagline: string
+ *   maintenanceMode: boolean
+ * }
+ *
+ * export const Settings = defineGlobal<SiteSettings>({
+ *   slug: 'site-settings',
+ *   hooks: {
+ *     afterChange: [({ doc }) => {
+ *       // `doc` is typed as SiteSettings
+ *       if (doc.maintenanceMode) alertOnCall()
+ *     }],
+ *   },
+ *   fields: [...],
+ * })
+ * ```
+ *
+ * @template TDoc The TypeScript shape of this global's document.
+ */
+interface GlobalConfig<TDoc extends object = Record<string, unknown>> {
+    /**
+     * Unique identifier for this global.
+     * Used as the URL segment (`/api/globals/:slug`) and the storage key.
+     */
+    slug: string;
+    /** Restricts this global to a specific site in a multi-tenant deployment. */
+    siteId?: string;
+    /**
+     * If `true`, this global is shared across all sites in a multi-tenant
+     * deployment.
+     */
+    shared?: boolean;
+    /** Human-readable label shown in the Admin UI sidebar. */
+    label?: string;
+    /** Field definitions for this global's document schema. */
+    fields: Field[];
+    /** Access control for reading and updating this global. */
+    access?: {
+        read?: AccessRule<TDoc>;
+        update?: AccessRule<TDoc>;
+    };
+    /**
+     * Global-level lifecycle hooks.
+     * Globals support `beforeRead`, `afterRead`, `beforeChange`, and `afterChange`.
+     * There are no delete hooks since globals cannot be deleted.
+     */
+    hooks?: {
+        beforeRead?: GlobalBeforeReadHookEntry[];
+        afterRead?: GlobalAfterReadHookEntry<TDoc>[];
+        beforeChange?: GlobalBeforeChangeHookEntry<TDoc>[];
+        afterChange?: GlobalAfterChangeHook<TDoc>[];
+    };
+    /** Admin UI configuration for this global. */
+    admin?: {
+        /**
+         * Lucide icon displayed beside this global in the Admin sidebar.
+         * Uses Lucide component names, e.g. `'Settings2'` or `'Palette'`.
+         */
+        icon?: AdminIconName;
+        /** Groups this global under a named section in the Admin sidebar. */
+        group?: string;
+        /** If `true`, this global is not shown in the Admin UI sidebar. */
+        hidden?: boolean;
+    };
+    /**
+     * Initial data to seed this global with the first time it is fetched and
+     * found to be empty.
+     */
+    initialData?: Partial<TDoc>;
+    /**
+     * Custom detail view layout configuration for the Admin UI.
+     */
+    detail?: DetailSchema<TDoc> | false;
+}
+
+/**
+ * The set of type-cast operations supported during aggregation.
+ *
+ * Each adapter maps these to its own native conversion primitive
+ * (e.g. `$toDouble` in MongoDB, `CAST(x AS REAL)` in SQLite).
+ * The public API is always database-independent.
+ */
+type AggregateCastType = "number" | "integer" | "float" | "string" | "boolean" | "date";
+/**
+ * A `count` aggregate operation.
+ *
+ * - `count: "*"` — count every document matched by `where`.
+ * - `cast` is intentionally absent: counting is document-level,
+ *   not field-value-level, so type conversion has no meaning here.
+ */
+interface CountOperation {
+    count: "*";
+    where?: Record<string, unknown>;
+}
+/**
+ * A `sum`, `avg`, `min`, or `max` aggregate operation on a named field.
+ *
+ * - `cast` converts stored values before the aggregation runs.
+ *   Invalid values (e.g. `"unknown"` cast to `number`) become `null`
+ *   and are ignored by `sum`, `avg`, `min`, and `max`.
+ */
+interface NumericOperation {
+    sum?: string;
+    avg?: string;
+    min?: string;
+    max?: string;
+    cast?: AggregateCastType;
+    where?: Record<string, unknown>;
+}
+/**
+ * A single named aggregate request — either a count or a numeric operation.
+ */
+type AggregateOperation = CountOperation | NumericOperation;
+/**
+ * The map of named aggregate operations sent in a single aggregate request.
+ *
+ * @example
+ * ```ts
+ * {
+ *   totalSubmitted: { count: "*" },
+ *   totalAsoebiYards: { sum: "asoebiYards", cast: "number", where: { wantsAsoebi: { equals: true } } },
+ * }
+ * ```
+ */
+type AggregateInput = Record<string, AggregateOperation>;
+/**
+ * The arguments passed to `DatabaseAdapter.aggregate`.
+ */
+interface AggregateArgs {
+    /** Collection slug. */
+    collection: string;
+    /** Named aggregate operations to compute. */
+    aggregates: AggregateInput;
+}
+/**
+ * The result returned by `DatabaseAdapter.aggregate`.
+ *
+ * Every named key maps to a `number | null`.
+ * `null` is returned when no documents matched the aggregate's `where`
+ * (applicable to `sum`, `avg`, `min`, `max`).
+ * `count` also returns `null` only if the database errors — it normally
+ * returns `0` for an empty match set.
+ */
+type AggregateResult = Record<string, number | null>;
+/**
+ * Derives the typed result shape from an `AggregateInput`.
+ * Every named key maps to `number | null`.
+ *
+ * @example
+ * ```ts
+ * type Input = { totalSubmitted: CountOperation; totalYards: NumericOperation };
+ * type Result = InferAggregateResult<Input>;
+ * // => { totalSubmitted: number | null; totalYards: number | null }
+ * ```
+ */
+type InferAggregateResult<T extends AggregateInput> = {
+    [K in keyof T]: number | null;
+};
+
+/**
+ * The interface every database adapter must implement.
+ *
+ * Dyrected ships adapters for PostgreSQL, MySQL, SQLite, and MongoDB.
+ * Implement this interface to connect any other database.
+ */
+interface DatabaseAdapter {
+    /** Find a paginated list of documents in a collection. */
+    find(args: {
+        collection: string;
+        where?: Record<string, unknown>;
+        limit?: number;
+        page?: number;
+        sort?: string;
+        /**
+         * The collection's field definitions. Optional, so simple adapters can
+         * ignore it; SQL adapters use it to sort numeric fields by magnitude.
+         */
+        fields?: Field[];
+    }): Promise<PaginatedResult>;
+    /** Find a single document by its ID. Returns `null` if not found. */
+    findOne(args: {
+        collection: string;
+        id: string;
+    }): Promise<BaseDocument | null>;
+    /** Insert a new document and return it with its generated `id`. */
+    create(args: {
+        collection: string;
+        data: Record<string, unknown>;
+    }): Promise<BaseDocument>;
+    /** Update a document by ID and return the updated document. */
+    update(args: {
+        collection: string;
+        id: string;
+        data: Record<string, unknown>;
+    }): Promise<BaseDocument>;
+    /** Delete a document by ID. Return value is intentionally untyped — callers do not use it. */
+    delete(args: {
+        collection: string;
+        id: string;
+    }): Promise<unknown>;
+    /**
+     * Compute aggregate statistics across a collection without returning documents.
+     *
+     * Each named key in `args.aggregates` maps to a `count`, `sum`, `avg`, `min`,
+     * or `max` operation, with optional `where` filtering and `cast` conversion.
+     * The result is a flat object of the same named keys mapped to `number | null`.
+     */
+    aggregate(args: AggregateArgs): Promise<AggregateResult>;
+    /** Fetch the singleton document for a global. Returns an empty object if not yet initialised. */
+    getGlobal(args: {
+        slug: string;
+    }): Promise<Record<string, unknown>>;
+    /** Create or replace the singleton document for a global. */
+    updateGlobal(args: {
+        slug: string;
+        data: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Sync the database schema with the current collection and global configs.
+     * Called on startup to create tables/collections that don't exist yet.
+     * Not all adapters implement this (e.g. MongoDB is schema-less).
+     */
+    sync?(collections: CollectionConfig[], globals: GlobalConfig[]): Promise<void>;
+    /**
+     * Execute a raw SQL query or database command.
+     * Optional — not all adapters support raw access.
+     */
+    execute?(query: string, params?: unknown[]): Promise<unknown>;
+    /**
+     * Run all adapter operations in `callback` as one atomic transaction.
+     * Shipped adapters implement this; workflow transitions require it.
+     */
+    transaction?<T>(callback: (db: DatabaseAdapter) => Promise<T>): Promise<T>;
+}
+/**
+ * Read-only view of the database adapter. Exposes only `find`, `findOne`,
+ * `getGlobal`, and `aggregate` — no write operations.
+ *
+ * Passed to `beforeChange`, `beforeDelete`, `beforeRead`, `afterRead`,
+ * and field-level hooks. Write operations are available in `afterChange`
+ * and `afterDelete` hooks where the full {@link DatabaseAdapter} is provided.
+ */
+type ReadonlyDatabaseAdapter = Pick<DatabaseAdapter, "find" | "findOne" | "getGlobal" | "aggregate">;
+/**
+ * The interface every storage adapter must implement.
+ *
+ * Dyrected ships adapters for local disk, AWS S3 and other S3-compatible
+ * services through the S3 adapter, Cloudinary, and Backblaze B2. Implement
+ * this interface to use any other storage provider.
+ */
+interface StorageAdapter {
+    /**
+     * Upload a file and return its metadata (URL, dimensions, etc.).
+     * The `prefix` is a path prefix used for multi-tenant setups.
+     */
+    upload(args: {
+        filename: string;
+        buffer: Uint8Array;
+        mimeType: string;
+        prefix?: string;
+    }): Promise<FileData>;
+    /** Delete a file by its stored filename. */
+    delete(args: {
+        filename: string;
+    }): Promise<void>;
+    /** Return the public URL for a stored file. */
+    getURL(args: {
+        filename: string;
+    }): string;
+    /**
+     * Retrieve the file's raw bytes and MIME type for serving via the API.
+     * Only needed by adapters that serve files through the Dyrected API
+     * (e.g. `LocalStorage`). Cloud adapters return `null` here and rely on
+     * direct CDN URLs instead.
+     */
+    resolve?(args: {
+        filename: string;
+    }): Promise<{
+        buffer: Uint8Array;
+        mimeType: string;
+    } | null>;
+}
+/**
+ * Processes uploaded images — generates metadata (dimensions, BlurHash) and
+ * produces resized variants defined in `UploadConfig.imageSizes`.
+ *
+ * @example
+ * import { SharpImageService } from '@dyrected/image-sharp'
+ * defineConfig({ image: new SharpImageService(), ... })
+ */
+interface ImageService {
+    process(args: {
+        buffer: Uint8Array;
+        mimeType: string;
+        config?: boolean | UploadConfig;
+        focalPoint?: {
+            x: number;
+            y: number;
+        };
+    }): Promise<{
+        metadata: {
+            width?: number;
+            height?: number;
+            /** Base64-encoded BlurHash for progressive loading. */
+            blurhash?: string;
+        };
+        /** Generated image sizes keyed by their `name`. */
+        sizes?: Record<string, {
+            buffer: Uint8Array;
+            width: number;
+            height: number;
+            filename: string;
+        }>;
+    }>;
+}
+
+type FieldType = "text" | "textarea" | "richText" | "number" | "boolean" | "date" | "datetime" | "time" | "select" | "multiSelect" | "radio" | "relationship" | "array" | "object" | "json" | "blocks" | "image" | "email" | "url" | "icon" | "join" | "row";
+interface DynamicOptionsResolverArgs {
+    /** Database adapter available to server-side option resolvers. */
+    db?: DatabaseAdapter;
+    /** Authenticated user making the request, if any. */
+    user?: AuthenticatedUser;
+    /** Current HTTP request context, including query parameters. */
+    req: HookRequestContext;
+}
+type DynamicOptionsResolver = (args: DynamicOptionsResolverArgs) => Promise<DynamicOptionItem[]> | DynamicOptionItem[];
+interface DynamicOptionsConfig {
+    /** Resolver function executed on the server to produce option items. */
+    resolve: DynamicOptionsResolver;
+    /** Cache duration in seconds for identical resolver calls. */
+    cacheTTL?: number;
+}
+type DynamicOptionItem = string | {
+    label: string;
+    value: unknown;
+};
+interface Block {
+    /** Stable identifier stored in each block row as `blockType`. */
+    slug: string;
+    /** Human-readable labels shown in the Admin block picker. */
+    labels?: {
+        /** Singular label, for example `Hero`. */
+        singular: string;
+        /** Plural label, for example `Heroes`. */
+        plural: string;
+    };
+    /**
+     * Lucide icon name shown on the block card and in the block library.
+     * Falls back to a generic layout icon when omitted.
+     */
+    icon?: AdminIconName;
+    /** Short one-line summary shown under the block name (block card subtitle). */
+    description?: string;
+    /**
+     * Presentation variants for this block. All variants share the same `fields`;
+     * only the rendered layout differs. The chosen variant is stored on each block
+     * row under the reserved `variant` key and passed to the render component as a
+     * `variant` prop. Switching variant preserves the author's content.
+     */
+    variants?: BlockVariant[];
+    /** Fields that make up this block's payload. */
+    fields: Field[];
+}
+/**
+ * A single presentation variant of a {@link Block}. Variants are a layout choice
+ * over a shared field set — for example a Hero rendered "centered" vs "split".
+ */
+interface BlockVariant {
+    /** Stable identifier stored on the block row as `variant`. */
+    slug: string;
+    /** Human-readable label shown in the variant switcher. Defaults to `slug`. */
+    label?: string;
+    /** Lucide icon name shown beside the variant label. */
+    icon?: AdminIconName;
+    /** Short one-line summary of what this variant looks like. */
+    description?: string;
+}
+interface FieldBase {
+    /** Stored key for this field. Omit only for layout-only fields such as `row` or `join`. */
+    name?: string;
+    /** Human-readable label shown in the Admin UI. */
+    label?: string;
+    /** Whether the field must have a value when saving. */
+    required?: boolean;
+    /** Whether values for this field must be unique across the collection. */
+    unique?: boolean;
+    /** Default value used when a new document omits this field. */
+    defaultValue?: unknown;
+    /** Static or dynamic option source for supported selection fields. */
+    options?: string[] | {
+        label: string;
+        value: unknown;
+    }[] | DynamicOptionsResolver | DynamicOptionsConfig;
+    /** Target collection slug for `relationship` fields. */
+    relationTo?: string;
+    /** Whether the field stores multiple values instead of one. */
+    hasMany?: boolean;
+    /** Child fields for `object` and `array` field types. */
+    fields?: Field[];
+    /** Allowed block definitions for a `blocks` field. */
+    blocks?: Block[];
+    /**
+     * Shared block slugs pulled from the root `defineConfig({ blocks: [...] })`
+     * registry for a `blocks` field.
+     *
+     * Use this when the same block types should be reused across multiple fields
+     * without inlining the full block schema into each field definition.
+     */
+    blockReferences?: string[];
+    /** Target collection slug for `join` fields. */
+    collection?: string;
+    /** Back-reference field name on the joined collection. */
+    on?: string;
+    /** Maximum number of joined documents returned by a `join` field. */
+    limit?: number;
+    /** Field-level read, create, and update access rules. Supports functions, Jexl strings, booleans, and named policies. */
+    access?: {
+        /** Controls whether this field is returned in API responses. */
+        read?: AccessRule;
+        /** Controls whether this field may be set when creating a document. Falls back to `update` when omitted. */
+        create?: AccessRule;
+        /** Controls whether incoming writes may change this field on update. */
+        update?: AccessRule;
+    };
+    /** Admin-only presentation options for this field. */
+    admin?: BaseFieldAdmin;
+    /** Previous storage key this field falls back to. When the field has no value, its value is read from the old key at read time, then rewritten under the new key on the next save. */
+    renameTo?: string;
+    /** Whether SQL adapters should promote this field into a first-class column. */
+    promoted?: boolean;
+}
+interface BaseFieldAdmin {
+    /** Placeholder text shown when the input has no value. */
+    placeholder?: string;
+    /** For nested object-like fields, choose which child field should summarize the value in admin surfaces. */
+    useAsTitle?: string;
+    /** Custom component key registered in the Admin UI. */
+    component?: string;
+    /** Help text rendered below the field. */
+    description?: string;
+    /** Hides the field from the Admin form without deleting stored data. */
+    hidden?: boolean;
+    /** Excludes the field from Admin list filtering. */
+    filterable?: boolean;
+    /** Renders the field as non-editable in the Admin UI. */
+    readOnly?: boolean;
+    /** Hides the field's label in the Admin form (e.g. single-field array rows where the label is redundant). */
+    hideLabel?: boolean;
+    /** Reactive condition controlling whether the field is visible in the Admin UI. */
+    condition?: ((data: Record<string, unknown>, siblingData: Record<string, unknown>) => boolean) | string;
+    /** Tab name used when the edit form is rendered as tabs. */
+    tab?: string;
+    /** CSS width hint used when the field appears inside a `row`. */
+    width?: string;
+}
+interface FieldBeforeChangeHookArgs<TValue = unknown, TDoc extends object = Record<string, unknown>> {
+    /** Current field value after previous hooks in the chain. */
+    value: TValue;
+    /** Existing stored document before the write, if this is an update. */
+    originalDoc?: TDoc;
+    /** Full incoming payload being written. */
+    data: Record<string, unknown>;
+    /** Authenticated user performing the write, if any. */
+    user?: AuthenticatedUser;
+    /** Read-only database adapter for related lookups. */
+    db: ReadonlyDatabaseAdapter;
+}
+type FieldBeforeChangeHook<TValue = unknown, TDoc extends object = Record<string, unknown>> = (args: FieldBeforeChangeHookArgs<TValue, TDoc>) => unknown;
+interface FieldAfterReadHookArgs<TValue = unknown, TDoc extends object = Record<string, unknown>> {
+    /** Raw stored field value before this hook transforms it. */
+    value: TValue;
+    /** Full document currently being returned to the caller. */
+    doc: TDoc;
+    /** Authenticated user requesting the document, if any. */
+    user?: AuthenticatedUser;
+    /** Read-only database adapter for related lookups. */
+    db: ReadonlyDatabaseAdapter;
+}
+type FieldAfterReadHook<TValue = unknown, TDoc extends object = Record<string, unknown>> = (args: FieldAfterReadHookArgs<TValue, TDoc>) => unknown;
+type FieldHooks<TValue> = {
+    hooks?: {
+        beforeChange?: Array<FieldBeforeChangeHook<TValue> | DeclarativeHookExpression>;
+        afterRead?: Array<FieldAfterReadHook<TValue>>;
+    };
+};
+interface FieldAdminOnChangeHookArgs<TValue = unknown> {
+    /** Current field value in the form state. */
+    value: TValue;
+    /** Current values for sibling fields at the same nesting level. */
+    siblingData: Record<string, unknown>;
+    /** Current values for the entire form. */
+    data: Record<string, unknown>;
+    /** Imperative setter for async or derived updates. */
+    setValue: (value: unknown) => void;
+}
+type FieldAdminOnChangeHook<TValue = unknown> = (args: FieldAdminOnChangeHookArgs<TValue>) => unknown;
+type FieldAdminHooks<TValue> = {
+    admin?: {
+        hooks?: {
+            onChange?: FieldAdminOnChangeHook<TValue> | DeclarativeHookExpression;
+        };
+    };
+};
+interface FieldAdminOptionsHookArgs {
+    /** Current values for sibling fields at the same nesting level. */
+    siblingData: Record<string, unknown>;
+    /** Current values for the entire form. */
+    data: Record<string, unknown>;
+}
+type FieldAdminOptionsHookResult = Array<string | {
+    label: string;
+    value: unknown;
+}>;
+type FieldAdminOptionsHook = (args: FieldAdminOptionsHookArgs) => FieldAdminOptionsHookResult | Promise<FieldAdminOptionsHookResult>;
+type TypedField<TType extends FieldType, TValue, TAdminExtra = Record<never, never>> = Omit<FieldBase, "admin"> & {
+    type: TType;
+    admin?: BaseFieldAdmin & TAdminExtra;
+} & FieldHooks<TValue> & FieldAdminHooks<TValue>;
+/**
+ * A semantic color for a badge or status pill in the Admin UI. The Admin panel
+ * maps each tone to a themed color, so you pick meaning (`success`, `danger`)
+ * rather than a raw color and it stays consistent in light and dark mode.
+ */
+type DisplayTone = "neutral" | "primary" | "success" | "warning" | "danger" | "info";
+/**
+ * How a `select`, `radio`, or `multiSelect` value is presented in read-only
+ * Admin surfaces (list cells). Renders the chosen option as a colored badge —
+ * ideal for statuses like `draft`/`published`. Display only and
+ * JSON-serializable so it round-trips through Dyrected Cloud.
+ *
+ * Pass the shorthand `"badge"` for neutral badges, or an object to color and
+ * relabel each value.
+ */
+type OptionFormat = 
+/** Shorthand for `{ type: "badge" }` — every value renders as a neutral badge. */
+"badge" | {
+    type: "badge";
+    /** Maps an option value to a color tone. Values not listed use `defaultTone`. */
+    tones?: Record<string, DisplayTone>;
+    /** Overrides the displayed text per option value. Falls back to the option's label. */
+    labels?: Record<string, string>;
+    /** Tone for values missing from `tones`. Defaults to `"neutral"`. */
+    defaultTone?: DisplayTone;
+};
+/**
+ * How a `boolean` value is presented in read-only Admin surfaces. Replaces the
+ * default `Yes`/`No` badge with your own labels and tones — for example
+ * `Active`/`Inactive` or `In stock`/`Sold out`. Display only.
+ */
+type BooleanFormat = {
+    type: "boolean";
+    /** Presentation for a `true` value. */
+    true?: {
+        label?: string;
+        tone?: DisplayTone;
+    };
+    /** Presentation for a `false` value. */
+    false?: {
+        label?: string;
+        tone?: DisplayTone;
+    };
+};
+/**
+ * How a `text` or `textarea` value is presented in read-only Admin surfaces.
+ * Display only — the stored string is unchanged. Pass a shorthand string for the
+ * simple transforms, or an object for `truncate` and `mask`.
+ */
+type TextFormat = 
+/** Shorthand for the matching object form. */
+"uppercase" | "lowercase" | "capitalize" | "code"
+/** Change the letter case for display. */
+ | {
+    type: "uppercase" | "lowercase" | "capitalize";
+}
+/** Render in a monospace pill — good for IDs, SKUs, and short codes. */
+ | {
+    type: "code";
+}
+/** Cut the text to `length` characters with a trailing ellipsis. */
+ | {
+    type: "truncate";
+    length: number;
+}
+/**
+ * Hide all but the last few characters — for tokens, keys, or reference
+ * numbers you don't want fully visible in a list.
+ */
+ | {
+    type: "mask";
+    /** How many trailing characters stay visible. Defaults to `4`. */
+    reveal?: number;
+    /** Character used for the hidden portion. Defaults to `"•"`. */
+    character?: string;
+};
+/**
+ * How a `url` or `email` value is presented in read-only Admin surfaces.
+ * Renders the value as a clickable link (a `mailto:` link for `email`) instead
+ * of plain text. Display only.
+ */
+type LinkFormat = 
+/** Shorthand for `{ type: "link" }`. */
+"link" | {
+    type: "link";
+    /** Open the link in a new tab. Defaults to `true`. */
+    newTab?: boolean;
+};
+/**
+ * How a `json` value is presented in read-only Admin surfaces. Display only.
+ */
+type JsonFormat = 
+/** Shorthand for the matching object form. */
+"summary" | "code"
+/** A compact key count, e.g. `{ 3 keys }`. */
+ | {
+    type: "summary";
+}
+/** A truncated inline monospace preview of the raw JSON. */
+ | {
+    type: "code";
+};
+type BooleanFieldAdmin = {
+    /** Boolean presentation style. */
+    layout?: "checkbox" | "switch";
+    /** How the value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: BooleanFormat;
+};
+type SelectFieldAdmin = {
+    /** Select presentation style. */
+    layout?: "radio" | "select";
+    /** Radio orientation when `layout: 'radio'` is used. */
+    direction?: "horizontal" | "vertical";
+    /** How the value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: OptionFormat;
+    hooks?: {
+        /** Client-side option recalculation for dependent dropdowns or radios. */
+        options?: FieldAdminOptionsHook;
+    };
+};
+type RadioFieldAdmin = {
+    /** Radio group orientation. */
+    direction?: "horizontal" | "vertical";
+    /** How the value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: OptionFormat;
+    hooks?: {
+        /** Client-side option recalculation for dependent radio groups. */
+        options?: FieldAdminOptionsHook;
+    };
+};
+type MultiSelectFieldAdmin = {
+    /** How each selected value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: OptionFormat;
+    hooks?: {
+        /** Client-side option recalculation for dependent multi-select fields. */
+        options?: FieldAdminOptionsHook;
+    };
+};
+interface CharacterLimitFieldConfig {
+    /** Advisory maximum character count exposed to editors and client tooling. */
+    maxLength?: number;
+}
+interface WordLimitFieldConfig {
+    /** Advisory maximum word count exposed to editors and client tooling. */
+    maxWords?: number;
+}
+interface NumberLimitFieldConfig {
+    /** Advisory minimum numeric value exposed to editors and client tooling. */
+    min?: number;
+    /** Advisory maximum numeric value exposed to editors and client tooling. */
+    max?: number;
+}
+type CharacterLimitFieldAdmin = {
+    /** Admin-only compatibility alias for `field.maxLength`. Prefer the top-level field property. */
+    maxLength?: number;
+};
+type WordLimitFieldAdmin = {
+    /** Admin-only compatibility alias for `field.maxWords`. Prefer the top-level field property. */
+    maxWords?: number;
+};
+type NumberLimitFieldAdmin = {
+    /** Admin-only compatibility alias for `field.min`. Prefer the top-level field property. */
+    min?: number;
+    /** Admin-only compatibility alias for `field.max`. Prefer the top-level field property. */
+    max?: number;
+};
+/**
+ * How a `number` field's value is presented in read-only Admin surfaces (list
+ * cells and read-only inputs). Display only — the stored value is unchanged, and
+ * editing still uses a plain numeric input. Every option is JSON-serializable so
+ * it round-trips through Dyrected Cloud.
+ *
+ * Pass a shorthand string for defaults (`format: "currency"`) or an object to
+ * configure it (`format: { type: "currency", currency: "NGN" }`).
+ */
+type NumberFormat = 
+/** Shorthand for the matching object form, using that format's defaults. */
+"decimal" | "currency" | "percent" | "compact" | "bytes" | "rating"
+/** Grouped number, e.g. `1234.5` → `1,234.5`. */
+ | {
+    type: "decimal";
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+/** Currency amount, e.g. `1234.5` → `$1,234.50`. */
+ | {
+    type: "currency";
+    /** ISO 4217 currency code, e.g. `"USD"`, `"NGN"`, `"EUR"`. Defaults to `"USD"`. */
+    currency?: string;
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+/**
+ * Percentage. By default the stored value is a ratio, so `0.5` → `50%`. Set
+ * `scale: false` when the stored value is already a percentage, so `50` → `50%`.
+ */
+ | {
+    type: "percent";
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+    /** `false` when the stored number is already scaled to 0–100. Defaults to `true`. */
+    scale?: boolean;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+}
+/** A measurement unit, e.g. `5` → `5 km` with `unit: "kilometer"`. */
+ | {
+    type: "unit";
+    /** A [sanctioned Intl unit](https://tc39.es/proposal-unified-intl-numberformat/section6/locales-currencies-tz_proposed_out.html#sec-issanctionedsimpleunitidentifier), e.g. `"kilometer"`, `"liter"`, `"celsius"`. */
+    unit: string;
+    unitDisplay?: "short" | "long" | "narrow";
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+    maximumFractionDigits?: number;
+}
+/** Abbreviated large numbers, e.g. `1200` → `1.2K`. */
+ | {
+    type: "compact";
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+    maximumFractionDigits?: number;
+}
+/** A byte count rendered with units, e.g. `1536` → `1.5 KB`. */
+ | {
+    type: "bytes";
+    /** Use 1024-based units (`KiB`, `MiB`) instead of 1000-based (`KB`, `MB`). Defaults to `false`. */
+    binary?: boolean;
+    maximumFractionDigits?: number;
+}
+/** A star rating, e.g. `4` → `★★★★☆` with `max: 5`. */
+ | {
+    type: "rating";
+    /** Total number of stars. Defaults to `5`. */
+    max?: number;
+};
+/**
+ * How a `date`, `datetime`, or `time` field's value is presented in read-only
+ * Admin surfaces. Display only and JSON-serializable so it round-trips through
+ * Dyrected Cloud.
+ *
+ * Pass a shorthand string (`format: "relative"`) or an object for finer control
+ * (`format: { type: "date", dateStyle: "long" }`).
+ */
+type DateFormat = 
+/** Shorthand for the matching object form, using that format's defaults. */
+"date" | "datetime" | "time" | "relative"
+/** Calendar date, e.g. `Jan 5, 2026`. */
+ | {
+    type: "date";
+    dateStyle?: "short" | "medium" | "long" | "full";
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+}
+/** Date and time together, e.g. `Jan 5, 2026, 2:30 PM`. */
+ | {
+    type: "datetime";
+    dateStyle?: "short" | "medium" | "long" | "full";
+    timeStyle?: "short" | "medium" | "long" | "full";
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+}
+/** Time of day, e.g. `2:30 PM`. */
+ | {
+    type: "time";
+    timeStyle?: "short" | "medium" | "long" | "full";
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+}
+/** Relative to now, e.g. `3 days ago`, `in 2 hours`. */
+ | {
+    type: "relative";
+    /** BCP 47 locale tag. Defaults to the viewer's browser locale. */
+    locale?: string;
+};
+type TextFieldAdmin = CharacterLimitFieldAdmin & WordLimitFieldAdmin & {
+    /** How the value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: TextFormat;
+};
+type TextareaFieldAdmin = CharacterLimitFieldAdmin & WordLimitFieldAdmin & {
+    /** How the value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: TextFormat;
+};
+type EmailFieldAdmin = CharacterLimitFieldAdmin & {
+    /** How the value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: LinkFormat;
+};
+type UrlFieldAdmin = CharacterLimitFieldAdmin & {
+    /** How the value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: LinkFormat;
+};
+type IconFieldAdmin = CharacterLimitFieldAdmin;
+type JsonFieldAdmin = {
+    /** How the value is displayed in read-only Admin surfaces. Does not affect storage or editing. */
+    format?: JsonFormat;
+};
+type NumberFieldAdmin = NumberLimitFieldAdmin & {
+    /** How the value is displayed in read-only Admin surfaces (list cells, read-only inputs). Does not affect storage or editing. */
+    format?: NumberFormat;
+};
+type DateFieldAdmin = {
+    /** How the value is displayed in read-only Admin surfaces (list cells, read-only inputs). Does not affect storage or editing. */
+    format?: DateFormat;
+};
+type JoinFieldAdmin = {
+    /** Whether the join field should show the "Create new" action in the Admin UI. Defaults to `true`. */
+    showCreateButton?: boolean;
+    /** Whether the join field should show the "View all" action in the Admin UI. Defaults to `true`. */
+    showViewButton?: boolean;
+};
+interface UrlLinkValue {
+    /** Whether the link is a custom URL or a reference to an internal document. */
+    type: "custom" | "internal";
+    /** The link URL. Absolute for custom links; may be a site-relative path for internal links. */
+    url?: string;
+    /** For internal links, the collection slug of the referenced document. */
+    relationTo?: string;
+    /** For internal links, the ID of the referenced document. */
+    value?: string;
+    /** Optional display label shown for the link. */
+    label?: string;
+}
+/**
+ * Editor capabilities available on a `richText` field. Each feature maps to a
+ * formatting control in the Admin editor toolbar and to the underlying editor
+ * schema, so disabling a feature removes both its toolbar button and the
+ * capability itself (including keyboard shortcuts and paste handling).
+ */
+type RichTextFeature = "bold" | "italic" | "underline" | "strike" | "heading" | "bulletList" | "orderedList" | "blockquote" | "align" | "link" | "table" | "image";
+/** Heading levels offered by the `heading` rich-text feature. */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+interface RichTextFieldConfig {
+    /**
+     * Editor capabilities to enable, in toolbar order. When omitted, every
+     * {@link RichTextFeature} is enabled (the default toolbar). Provide a subset
+     * to restrict what editors can do — for example `['bold', 'italic', 'link']`
+     * for a lightweight inline editor.
+     */
+    features?: RichTextFeature[];
+    /**
+     * Heading levels offered when the `heading` feature is enabled.
+     * Defaults to `[1, 2, 3]`.
+     */
+    headingLevels?: HeadingLevel[];
+    /**
+     * Upload collection slug used by the `image` feature's media picker.
+     * Defaults to the first collection configured with `upload: true`.
+     */
+    uploadCollection?: string;
+}
+type TextField = TypedField<"text", string, TextFieldAdmin> & CharacterLimitFieldConfig & WordLimitFieldConfig;
+type TextareaField = TypedField<"textarea", string, TextareaFieldAdmin> & CharacterLimitFieldConfig & WordLimitFieldConfig;
+type EmailField = TypedField<"email", string, EmailFieldAdmin> & CharacterLimitFieldConfig;
+type UrlField = TypedField<"url", string | UrlLinkValue, UrlFieldAdmin> & CharacterLimitFieldConfig;
+type IconField = TypedField<"icon", string, IconFieldAdmin> & CharacterLimitFieldConfig;
+/** A calendar day, stored and returned as an ISO date string. */
+type DateField = TypedField<"date", string, DateFieldAdmin>;
+/** A specific instant, stored and returned as an ISO date-time string. */
+type DateTimeField = TypedField<"datetime", string, DateFieldAdmin>;
+/** A local time of day, stored as a string when the date is modeled elsewhere. */
+type TimeField = TypedField<"time", string, DateFieldAdmin>;
+/** A single choice from a fixed or dynamically-resolved set of options, stored as the chosen value. */
+type SelectField = TypedField<"select", string, SelectFieldAdmin>;
+/** A single choice shown as radio buttons, stored as the chosen value. */
+type RadioField = TypedField<"radio", string, RadioFieldAdmin>;
+/** A numeric value. Optional advisory `min`/`max` guide editors without enforcing server-side validation. */
+type NumberField = TypedField<"number", number, NumberFieldAdmin> & NumberLimitFieldConfig;
+/** A `true`/`false` value, shown to editors as a checkbox or switch. */
+type BooleanField = TypedField<"boolean", boolean, BooleanFieldAdmin>;
+/** Several choices from a fixed or dynamically-resolved set, stored as an array of the chosen values. */
+type MultiSelectField = TypedField<"multiSelect", string[], MultiSelectFieldAdmin>;
+/** A reference to one or more documents in another collection, stored as an ID or array of IDs. Use `relationTo` to name the target and `hasMany` for multiple. */
+type RelationshipField = TypedField<"relationship", string | string[]>;
+/** A reference to one or more documents in an upload-enabled collection, stored as an ID or array of IDs. Use `relationTo` to name the target and `hasMany` for multiple. */
+type ImageField = TypedField<"image", string | string[]>;
+/** Formatted content authored in the admin editor, stored as an HTML string. */
+type RichTextField = TypedField<"richText", string> & RichTextFieldConfig;
+/** An arbitrary JSON value. Dyrected stores it as-is and does not validate its shape. */
+type JsonField = TypedField<"json", Record<string, unknown>, JsonFieldAdmin>;
+/** A group of nested `fields` stored as an embedded object under this field's `name`. */
+type ObjectField = TypedField<"object", unknown>;
+/** A repeatable list of rows that all share the same `fields`, stored as an array of objects. */
+type ArrayField = TypedField<"array", unknown>;
+/** Flexible content built from a controlled set of typed `blocks`, stored as an ordered array where each row records its `blockType`. */
+type BlocksField = TypedField<"blocks", unknown>;
+/** A virtual reverse relationship that surfaces documents pointing back at this one via `collection` and `on`. Read-only; nothing is stored on this document. */
+type JoinField = TypedField<"join", unknown, JoinFieldAdmin>;
+/** A layout-only container that arranges its child `fields` horizontally in the admin UI. Stores no value of its own. */
+type RowField = TypedField<"row", unknown>;
+type Field = TextField | TextareaField | EmailField | UrlField | IconField | DateField | DateTimeField | TimeField | SelectField | RadioField | NumberField | BooleanField | MultiSelectField | RelationshipField | ImageField | RichTextField | JsonField | ObjectField | ArrayField | BlocksField | JoinField | RowField;
+interface UploadConfig {
+    /** Allowed MIME types for uploaded files. */
+    allowedMimeTypes?: string[];
+    /** Maximum upload size in bytes. */
+    maxFileSize?: number;
+    /** Local filesystem destination used by disk-based storage adapters. */
+    staticDir?: string;
+    /** Public URL prefix for disk-based uploads. */
+    staticURL?: string;
+    /** Generated image size name used as the Admin media thumbnail. */
+    adminThumbnail?: string;
+    imageSizes?: {
+        /** Stable name used to reference this generated size. */
+        name: string;
+        /** Target width in pixels. */
+        width?: number;
+        /** Target height in pixels. */
+        height?: number;
+        /** Crop strategy forwarded to the image processor. */
+        crop?: string;
+        /** Resize fit strategy forwarded to the image processor. */
+        fit?: string;
+        /** Prevents upscaling smaller source images. */
+        withoutEnlargement?: boolean;
+        /** Format-specific options forwarded to the image processor. */
+        formatOptions?: Record<string, unknown>;
+    }[];
+}
+
+interface AdminAuthMember {
+    id: string;
+    email: string;
+    name?: string;
+    roles: string[];
+    siteAccess?: string[];
+    status?: "active" | "pending";
+    [key: string]: any;
+}
+type AdminAuthProvisioningMode = "jit_only" | "jit_plus_membership_management" | "preprovisioned_only";
+interface AdminAuthClaimMapping {
+    sub?: string;
+    email?: string;
+    name?: string;
+    roles?: string;
+    groups?: string;
+    siteIds?: string;
+    workspaceIds?: string;
+}
+interface AdminAuthResolvedIdentity {
+    sub: string;
+    email?: string;
+    name?: string;
+    roles?: string[];
+    groups?: string[];
+    siteIds?: string[];
+    workspaceIds?: string[];
+    rawClaims?: Record<string, unknown>;
+}
+interface AdminAuthAccessResolution {
+    allowed: boolean;
+    roles?: string[];
+    data?: Record<string, unknown>;
+}
+interface AdminAuthResolveAccessArgs {
+    identity: AdminAuthResolvedIdentity;
+    providerId: string;
+    siteId?: string;
+    workspaceId?: string;
+    req: {
+        method: string;
+        path: string;
+        url: string;
+        headers: Record<string, string | undefined>;
+    };
+    user: Record<string, unknown> | null;
+}
+interface AdminAuthProviderMembersConfig {
+    list?: (args: {
+        limit?: number;
+        page?: number;
+        sort?: string;
+        where?: Record<string, any>;
+        req: HookRequestContext;
+    }) => Promise<{
+        docs: AdminAuthMember[];
+        totalDocs: number;
+        limit: number;
+        page: number;
+        totalPages: number;
+        hasNextPage: boolean;
+        hasPrevPage: boolean;
+    }>;
+    get?: (args: {
+        externalSubject: string;
+        req: HookRequestContext;
+    }) => Promise<AdminAuthMember | null>;
+    create?: (args: {
+        data: Record<string, any>;
+        req: HookRequestContext;
+    }) => Promise<AdminAuthMember>;
+    update?: (args: {
+        externalSubject: string;
+        data: Record<string, any>;
+        req: HookRequestContext;
+    }) => Promise<AdminAuthMember>;
+    delete?: (args: {
+        externalSubject: string;
+        req: HookRequestContext;
+    }) => Promise<void>;
+}
+interface BaseAdminAuthProvider {
+    id: string;
+    type: "oidc" | "custom" | "cloud";
+    displayName?: string;
+    autoRedirect?: boolean;
+    allowJitProvisioning?: boolean;
+    claimMapping?: AdminAuthClaimMapping;
+    members?: AdminAuthProviderMembersConfig;
+}
+interface OIDCAdminAuthProvider extends BaseAdminAuthProvider {
+    type: "oidc";
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri?: string;
+    scopes?: string[];
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    userInfoEndpoint?: string;
+}
+interface CustomAdminAuthProvider extends BaseAdminAuthProvider {
+    type: "custom" | "cloud";
+    startUrl?: string;
+    issuer?: string;
+    audience?: string;
+    secret?: string;
+    jwksUri?: string;
+    tokenParam?: string;
+}
+type AdminAuthProvider = OIDCAdminAuthProvider | CustomAdminAuthProvider;
+interface PublicAdminAuthProvider {
+    id: string;
+    type: AdminAuthProvider["type"];
+    displayName: string;
+    autoRedirect?: boolean;
+}
+interface PublicAdminAuthConfig {
+    mode: "local" | "external";
+    collectionSlug?: string;
+    provisioningMode?: AdminAuthProvisioningMode;
+    providers: PublicAdminAuthProvider[];
+}
+interface AdminAuthConfig {
+    mode: "local" | "external";
+    collectionSlug?: string;
+    provisioningMode?: AdminAuthProvisioningMode;
+    providers: AdminAuthProvider[];
+    resolveAccess?: (args: AdminAuthResolveAccessArgs) => Promise<AdminAuthAccessResolution> | AdminAuthAccessResolution;
+}
+
+type DyrectedLoggerConfig = {
+    options: LoggerOptions;
+    destination?: DestinationStream;
+} | Logger;
+interface DyrectedObservabilityConfig {
+    requestLogging?: {
+        enabled?: boolean;
+        logBodies?: boolean;
+        maxBodyBytes?: number;
+        redactPaths?: string[];
+        includeHeaders?: string[];
+        redactHeaders?: string[];
+    };
+    sampling?: {
+        successRate?: number;
+        traceSuccessRate?: number;
+        bodySuccessRate?: number;
+        alwaysKeep4xx?: boolean;
+        alwaysKeep5xx?: boolean;
+    };
+    tracing?: {
+        enabled?: boolean;
+        serviceName?: string;
+        exporter?: "otlp" | "console" | "none";
+        headers?: Record<string, string>;
+        endpoint?: string;
+    };
+    metrics?: {
+        enabled?: boolean;
+        exporter?: "otlp" | "prometheus" | "none";
+        endpoint?: string;
+        path?: string;
+    };
+    transports?: {
+        targets?: Array<{
+            type: "stdout";
+        } | {
+            type: "stderr";
+        } | {
+            type: "file";
+            path: string;
+        } | {
+            type: "otlp";
+            endpoint: string;
+            headers?: Record<string, string>;
+        }>;
+    };
+}
+type TrustProxyConfig = boolean | number;
+interface RateLimitConfig {
+    /**
+     * Enable in-process request rate limiting for HTTP API routes.
+     *
+     * This protects routes at the Dyrected app layer. For production you should
+     * still prefer an edge or proxy limit in front of it when possible.
+     */
+    enabled?: boolean;
+    /**
+     * Time window, in milliseconds, used to count requests from the same client.
+     *
+     * Defaults to `15 * 60 * 1000` (15 minutes).
+     */
+    window?: number;
+    /**
+     * Maximum number of requests a client may make within the current window.
+     *
+     * Defaults to `500`.
+     */
+    max?: number;
+    /**
+     * Trust upstream proxy forwarding headers when resolving the client IP.
+     *
+     * Set to `true` when Dyrected is deployed behind a reverse proxy or
+     * platform edge that correctly sets `X-Forwarded-For`. Set to a number to
+     * trust that many proxy hops from the right side of the header chain.
+     */
+    trustProxy?: TrustProxyConfig;
+    /**
+     * Route prefixes that should be subject to rate limiting.
+     *
+     * Defaults to `['/api']`.
+     */
+    paths?: string[];
+    /**
+     * Optional escape hatch for requests that should bypass the in-app limiter.
+     *
+     * Return `true` to skip limiting for the current request.
+     */
+    skip?: (args: {
+        ip: string;
+        path: string;
+        method: string;
+        req: HookRequestContext;
+    }) => boolean | Promise<boolean>;
+}
+/**
+ * The root configuration object passed to `createDyrectedApp`.
+ *
+ * This is the single source of truth for your entire Dyrected instance —
+ * collections, globals, database adapter, storage, email, and more.
+ *
+ * @example
+ * import { defineConfig } from '@dyrected/core'
+ * import { SQLiteAdapter } from '@dyrected/db-sqlite'
+ *
+ * export default defineConfig({
+ *   db: new SQLiteAdapter({ filename: './db.sqlite' }),
+ *   collections: [Posts, Users],
+ *   globals: [SiteSettings],
+ * })
+ */
+interface DyrectedConfig<TUser extends AuthenticatedUser = AuthenticatedUser> {
+    /**
+     * Reusable block definitions that `blocks` fields can reference by slug via
+     * `blockReferences`.
+     */
+    blocks?: Block[];
+    /** Collection definitions. Each collection maps to a database table/collection. */
+    collections: CollectionConfig<any>[];
+    /** Global (singleton) definitions. Each global maps to a single document. */
+    globals: GlobalConfig<any>[];
+    /**
+     * The database adapter. Required for all data operations.
+     * @see DatabaseAdapter
+     */
+    db?: DatabaseAdapter;
+    /**
+     * The storage adapter for file uploads.
+     * Required when any collection has `upload: true`.
+     * @see StorageAdapter
+     */
+    storage?: StorageAdapter;
+    /**
+     * The image processing service. Required when any upload collection
+     * defines `imageSizes`.
+     * @see ImageService
+     */
+    image?: ImageService;
+    /**
+     * Runtime logger configuration. Accepts either logger options/destination or
+     * a fully-instantiated Pino logger.
+     */
+    logger?: DyrectedLoggerConfig;
+    /**
+     * Request logging, redaction, sampling, tracing, metrics, and transport
+     * configuration for the Dyrected server runtime.
+     */
+    observability?: DyrectedObservabilityConfig;
+    /** Admin UI branding and metadata. */
+    admin?: AdminConfig;
+    /**
+     * Deployment-level authentication strategy for the CMS dashboard (`/admin`).
+     * This is separate from collection-level `auth: true`, which continues to
+     * power application/customer auth independently.
+     */
+    adminAuth?: AdminAuthConfig;
+    /**
+     * Named access policies available to collection, global, and field access
+     * rules via `{ policy: 'name' }`.
+     *
+     * A policy can be a **function** (full server logic, evaluated to a static
+     * boolean when serialized for the admin panel) or a **Jexl string** (or
+     * boolean). String policies are inlined when the schema is sent to the admin,
+     * so the admin panel evaluates them live against the current form — the same
+     * way it evaluates inline Jexl rules.
+     */
+    accessPolicies?: Record<string, AccessPolicyResolver<Record<string, unknown>, TUser> | string | boolean>;
+    /**
+     * Email transport configuration. Required for welcome emails, password
+     * resets, and invite links.
+     *
+     * @example
+     * email: {
+     *   from: 'no-reply@myapp.com',
+     *   send: async ({ to, subject, html }) => {
+     *     await resend.emails.send({ from, to, subject, html })
+     *   },
+     * }
+     */
+    email?: {
+        /** The `From` address for all outbound emails. */
+        from: string;
+        /** The send function. Wire in any email provider (Resend, SendGrid, SES, etc.). */
+        send: (args: {
+            to: string;
+            subject: string;
+            html: string;
+        }) => Promise<void>;
+        /** Override the default email templates. */
+        templates?: {
+            welcome?: (args: {
+                email: string;
+            }) => {
+                subject?: string;
+                html: string;
+            };
+            invite?: (args: {
+                token: string;
+                invitedByEmail?: string;
+                url?: string;
+            }) => {
+                subject?: string;
+                html: string;
+            };
+            resetPassword?: (args: {
+                token: string;
+                url?: string;
+            }) => {
+                subject?: string;
+                html: string;
+            };
+            passwordChanged?: (args: {
+                email: string;
+            }) => {
+                subject?: string;
+                html: string;
+            };
+        };
+    };
+    /**
+     * Redis connection URL. Required for distributed caching of dynamic option
+     * resolvers and other server-side caches in multi-instance deployments.
+     *
+     * @example
+     * redis: { url: process.env.REDIS_URL }
+     */
+    redis?: {
+        url: string;
+    };
+    /** Durable lifecycle-event delivery configuration. */
+    events?: {
+        handlers: LifecycleEventHandler[];
+        /** Maximum delivery attempts before an event remains failed. Defaults to 8. */
+        maxAttempts?: number;
+        /** Initial exponential-backoff delay in milliseconds. Defaults to 1000. */
+        retryDelayMs?: number;
+    };
+    /**
+     * Cross-Origin Resource Sharing (CORS) configuration.
+     * List all origins that are allowed to call the Dyrected API.
+     *
+     * @example
+     * cors: { origins: ['https://myapp.com', 'https://www.myapp.com'] }
+     */
+    cors?: {
+        origins: string[];
+    };
+    /**
+     * App-level HTTP request rate limiting.
+     *
+     * Similar to Payload's `rateLimit` option, this counts requests by client IP
+     * over a rolling time window and returns `429` responses once the limit is
+     * exhausted.
+     */
+    rateLimit?: RateLimitConfig;
+    /**
+     * Callback to dynamically fetch additional collections and globals for a
+     * given site ID at request time. Used in multi-tenant deployments where each
+     * site has its own schema stored in the database.
+     */
+    onSchemaFetch?: (siteId: string) => Promise<{
+        blocks?: Block[];
+        collections?: CollectionConfig<any>[];
+        globals?: GlobalConfig<any>[];
+        accessPolicies?: Record<string, AccessPolicyResolver<Record<string, unknown>, TUser> | string | boolean>;
+        admin?: AdminConfig;
+        adminAuth?: AdminAuthConfig;
+    }>;
+}
+
+export { type RadioField as $, type AdminAuthConfig as A, type Block as B, type CollectionConfig as C, type DyrectedConfig as D, type DetailText as E, type Field as F, type GlobalConfig as G, type HookRequestContext as H, type DetailSchema as I, type ArrayField as J, type BlocksField as K, type LifecycleEventName as L, type BooleanField as M, type AuthConfig as N, type AccessPolicyResolver as O, type PublicAdminAuthConfig as P, type DateField as Q, type DateTimeField as R, type EmailField as S, type IconField as T, type ImageField as U, type JoinField as V, type WorkflowConfig as W, type JsonField as X, type MultiSelectField as Y, type NumberField as Z, type ObjectField as _, type DeclarativeHookExpression as a, type FieldAdminOnChangeHook as a$, type RelationshipField as a0, type RichTextField as a1, type RowField as a2, type SelectField as a3, type TextField as a4, type TextareaField as a5, type TimeField as a6, type UrlField as a7, type AccessFunction as a8, type AccessFunctionArgs as a9, type CollectionAfterDeleteHook as aA, type CollectionAfterReadHook as aB, type CollectionAfterReadHookEntry as aC, type CollectionAfterTransitionHook as aD, type CollectionBeforeChangeHook as aE, type CollectionBeforeChangeHookEntry as aF, type CollectionBeforeDeleteHook as aG, type CollectionBeforeReadHook as aH, type CollectionBeforeReadHookEntry as aI, type CollectionBeforeTransitionHook as aJ, type CollectionListComponentSlots as aK, type CountOperation as aL, type CustomAdminAuthProvider as aM, type DatabaseAdapter as aN, type DateFieldAdmin as aO, type DateFormat as aP, type DetailSpan as aQ, type DisplayTone as aR, type DisplayVariant as aS, type DynamicOptionItem as aT, type DynamicOptionsConfig as aU, type DynamicOptionsResolver as aV, type DynamicOptionsResolverArgs as aW, type DyrectedLoggerConfig as aX, type DyrectedObservabilityConfig as aY, type EmailFieldAdmin as aZ, type FieldAdminHooks as a_, type AccessResult as aa, type AccessRule as ab, type AdminAuthAccessResolution as ac, type AdminAuthClaimMapping as ad, type AdminAuthMember as ae, type AdminAuthProvider as af, type AdminAuthProviderMembersConfig as ag, type AdminAuthProvisioningMode as ah, type AdminAuthResolveAccessArgs as ai, type AdminAuthResolvedIdentity as aj, type AdminConfig as ak, type AdminDashboardComponentSlots as al, type AdminIconName as am, type AggregateArgs as an, type AggregateCastType as ao, type AggregateInput as ap, type AggregateOperation as aq, type AggregateResult as ar, type BaseAdminAuthProvider as as, type BaseFieldAdmin as at, type BlockVariant as au, type BooleanFieldAdmin as av, type BooleanFormat as aw, type CharacterLimitFieldAdmin as ax, type CharacterLimitFieldConfig as ay, type CollectionAfterChangeHook as az, type AuthenticatedUser as b, type FieldAdminOnChangeHookArgs as b0, type FieldAdminOptionsHook as b1, type FieldAdminOptionsHookArgs as b2, type FieldAdminOptionsHookResult as b3, type FieldAfterReadHook as b4, type FieldAfterReadHookArgs as b5, type FieldBase as b6, type FieldBeforeChangeHook as b7, type FieldBeforeChangeHookArgs as b8, type FieldHook as b9, type NumberLimitFieldConfig as bA, type NumericOperation as bB, type OIDCAdminAuthProvider as bC, type OptionFormat as bD, type PaginatedResult as bE, type PublicAdminAuthProvider as bF, type RadioFieldAdmin as bG, type RateLimitConfig as bH, type ReadonlyDatabaseAdapter as bI, type RichTextFeature as bJ, type RichTextFieldConfig as bK, type SelectFieldAdmin as bL, type StorageAdapter as bM, type TextFieldAdmin as bN, type TextFormat as bO, type TextareaFieldAdmin as bP, type TrustProxyConfig as bQ, type TypedField as bR, type UploadConfig as bS, type UrlFieldAdmin as bT, type UrlLinkValue as bU, type WordLimitFieldAdmin as bV, type WordLimitFieldConfig as bW, type WorkflowMetadata as bX, type WorkflowRole as bY, type WorkflowState as bZ, type WorkflowTransitionContext as b_, type FieldHooks as ba, type FieldType as bb, type FileData as bc, type GlobalAfterChangeHook as bd, type GlobalAfterReadHook as be, type GlobalAfterReadHookEntry as bf, type GlobalBeforeChangeHook as bg, type GlobalBeforeChangeHookEntry as bh, type GlobalBeforeReadHook as bi, type GlobalBeforeReadHookEntry as bj, type HeadingLevel as bk, type HookFunction as bl, type IconFieldAdmin as bm, type ImageService as bn, type InferAggregateResult as bo, type JoinFieldAdmin as bp, type JsonFieldAdmin as bq, type JsonFormat as br, LIFECYCLE_EVENT_NAMES as bs, type LifecycleEventHandler as bt, type LinkFormat as bu, type MultiSelectFieldAdmin as bv, type NamedAccessPolicy as bw, type NumberFieldAdmin as bx, type NumberFormat as by, type NumberLimitFieldAdmin as bz, type WorkflowTransition as c, type LifecycleEvent as d, type BaseDocument as e, type DetailComputedOptions as f, type ComputedHandler as g, type DetailComputed as h, type DetailCustomOptions as i, type DetailCustom as j, type DetailDividerOptions as k, type DetailDivider as l, type DisplayFieldOptions as m, type DetailField as n, type DetailItem as o, type DetailGridOptions as p, type DetailGrid as q, type DetailRepeatOptions as r, type DetailRepeat as s, type DetailSectionOptions as t, type DetailSection as u, type DetailTabOptions as v, type DetailTab as w, type DetailTabsOptions as x, type DetailTabs as y, type DetailTextOptions as z };