@thebes/cadmus 0.2.1 → 0.4.0

package/dist/index-sB3YOadC.d.cts

@@ -0,0 +1,1304 @@
+import { BaseSQLiteDatabase, SQLiteTableWithColumns, sqliteTable } from "drizzle-orm/sqlite-core";
+import { InferInsertModel, InferSelectModel, SQL } from "drizzle-orm";
+
+//#region src/cms/blocks.d.ts
+/**
+ * Renderer registry for block/document content (issue #13) — adopts the
+ * Portable Text + `@portabletext/react` pattern (idea, not code): a content
+ * document is a serializable **array of typed blocks**, and rendering is a
+ * lookup of `block.type → renderer`, not a hand-rolled `switch`. Adding a
+ * new block type becomes "register a renderer" with no edit to a central
+ * branch.
+ *
+ * Framework-agnostic on purpose: `TRenderer` is whatever a host wants a
+ * block's renderer to be — a string-producing function (SSR/preview HTML),
+ * an Astro component, a Solid component, etc. The registry only does lookup,
+ * fallback, and introspection; it never assumes a rendering technology.
+ */
+/**
+ * The minimal shape every block must have: a string discriminant under
+ * `type`. (Portable Text uses `_type`; Cadmea content is TipTap-JSON-shaped
+ * and already keyed on `type`, so the registry keys on `type` to stay
+ * drop-in with stored content — the editor can stay TipTap.)
+ */
+interface PortableBlockLike {
+  type: string;
+}
+interface BlockRegistry<TRenderer> {
+  /** Register (or replace) the renderer for a block type. Chainable. */
+  register(type: string, renderer: TRenderer): BlockRegistry<TRenderer>;
+  /** Register several at once. Chainable. */
+  registerMany(renderers: Record<string, TRenderer>): BlockRegistry<TRenderer>;
+  /** The renderer registered for `type`, or `undefined`. */
+  get(type: string): TRenderer | undefined;
+  /** Whether a renderer is registered for `type`. */
+  has(type: string): boolean;
+  /** Every registered block type, in registration order. */
+  types(): string[];
+  /** Set the fallback used when a type has no registered renderer. Chainable. */
+  setFallback(renderer: TRenderer): BlockRegistry<TRenderer>;
+  /** The renderer for `type`, else the fallback, else `undefined`. */
+  resolve(type: string): TRenderer | undefined;
+}
+/**
+ * Create a block renderer registry. Seed it with an initial `type → renderer`
+ * map and/or an `options.fallback` for unknown types.
+ *
+ * ```ts
+ * const registry = createBlockRegistry<StringBlockRenderer>({
+ *   divider: () => "<hr>",
+ * });
+ * registry.register("hero", (b) => `<h1>${b.heading}</h1>`);
+ * renderBlocksToString(blocks, registry);
+ * ```
+ */
+declare function createBlockRegistry<TRenderer>(initial?: Record<string, TRenderer>, options?: {
+  fallback?: TRenderer;
+}): BlockRegistry<TRenderer>;
+/**
+ * A renderer that turns one block into an HTML string — the registry value
+ * type for SSR/preview paths that build markup as strings (e.g. a Hono
+ * preview route) rather than mounting components.
+ */
+type StringBlockRenderer<TBlock extends PortableBlockLike = PortableBlockLike> = (block: TBlock) => string;
+/**
+ * Render an array of blocks to a single HTML string via a registry of
+ * {@link StringBlockRenderer}s. Blocks whose type resolves to no renderer
+ * (and no fallback) contribute the empty string — the same forgiving
+ * behavior the old hand-rolled `switch` had for unknown types.
+ */
+declare function renderBlocksToString<TBlock extends PortableBlockLike>(blocks: readonly TBlock[], registry: BlockRegistry<StringBlockRenderer<TBlock>>): string;
+//#endregion
+//#region src/errors.d.ts
+declare global {
+  interface ErrorConstructor {
+    captureStackTrace?(targetObject: object, constructorOpt?: Function): void;
+  }
+}
+/**
+ * Base class for all Cadmus errors.
+ * All primitives throw CadmusError or a typed subclass — never a raw Error.
+ *
+ * @example
+ * try {
+ *   await createMagicLink({ kv, email, to })
+ * } catch (e) {
+ *   if (e instanceof CadmusAuthError) {
+ *     // auth-specific handling
+ *   } else if (e instanceof CadmusError) {
+ *     // any cadmus error — e.code tells you which primitive threw
+ *   } else {
+ *     throw e // re-throw unknown errors
+ *   }
+ * }
+ */
+declare class CadmusError extends Error {
+  readonly code: string;
+  readonly cause?: unknown | undefined;
+  constructor(message: string, code: string, cause?: unknown | undefined);
+}
+/** Thrown by @thebes/cadmus/auth primitives */
+declare class CadmusAuthError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/db primitives */
+declare class CadmusDbError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/storage primitives */
+declare class CadmusStorageError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/cache primitives */
+declare class CadmusCacheError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/email primitives */
+declare class CadmusEmailError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/session primitives */
+declare class CadmusSessionError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/rate-limit primitives */
+declare class CadmusRateLimitError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/queues primitives */
+declare class CadmusQueueError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/cms primitives */
+declare class CadmusCmsError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown by @thebes/cadmus/cms's createLocalApi when a collection's
+ * `access` function rejects an operation. A distinct subclass (rather than
+ * a plain CadmusCmsError) so consumers like mountCmsRoutes can map it to
+ * 403 by `instanceof`, not by matching on message text.
+ */
+declare class CadmusAccessDeniedError extends CadmusCmsError {
+  constructor(message: string, cause?: unknown);
+}
+/**
+ * One failed field-validation rule (issue #16). `path` is the field's key
+ * (flattened, e.g. `shippingAddress_city` for a group subfield). `severity`
+ * lets a rule warn without blocking the write — only `"error"` violations
+ * cause createLocalApi to throw; `"warning"` ones are carried through for
+ * the studio to surface non-blockingly.
+ */
+interface ValidationViolation {
+  path: string;
+  message: string;
+  severity: "error" | "warning";
+}
+/**
+ * Thrown by createLocalApi when a collection's field-validation rules
+ * (Sanity-style chainable `Rule` API — see cms/validation.ts) reject a
+ * create/update. Carries the structured `violations` so the studio can
+ * surface per-field messages, and `mountCmsRoutes` can map it to HTTP 422
+ * by `instanceof` rather than message matching. A subclass of
+ * CadmusCmsError, so existing `instanceof CadmusCmsError` handling still
+ * catches it. Only `"error"`-severity violations are ever thrown.
+ */
+declare class CadmusValidationError extends CadmusCmsError {
+  readonly violations: ValidationViolation[];
+  constructor(message: string, violations: ValidationViolation[], cause?: unknown);
+}
+/**
+ * Thrown by @thebes/cadmus/hono's `createCmsApiClient` when a request
+ * against a `mountCmsRoutes` surface returns a non-2xx response. Carries
+ * the HTTP status and parsed body so callers can branch on `status`
+ * (e.g. 403 → access denied, 404 → not found) instead of re-parsing
+ * `{ error: string }` response bodies by hand.
+ */
+declare class CadmusApiError extends CadmusError {
+  readonly status: number;
+  readonly body: unknown;
+  constructor(message: string, status: number, body: unknown);
+}
+//#endregion
+//#region src/cms/patch.d.ts
+/**
+ * Patch model + field-level diff (issue #14) — adopts Sanity's mutation/patch
+ * idea (pattern, not code): represent a content change as a small set of
+ * field operations, and compute a field-level diff between two document
+ * snapshots. Underpins version-history display (what changed between two
+ * versions) and the content-migration runner (#18), which expresses a
+ * transform's effect as a {@link Patch} and applies it.
+ *
+ * Scope: operations are keyed by **top-level field** (a document's own
+ * fields), matching "field-level diff" — a changed `blocks` array reads as
+ * one changed field, not a deep per-node diff. Deep/array-aware diffing is a
+ * deliberate later extension, not built here.
+ */
+/** A single field operation. `set` writes a value; `unset` removes the field. */
+type PatchOp = {
+  op: "set";
+  path: string;
+  value: JsonValue;
+} | {
+  op: "unset";
+  path: string;
+};
+/** An ordered set of field operations transforming one document into another. */
+type Patch = PatchOp[];
+type FieldChangeKind = "added" | "removed" | "changed";
+/** One field's difference between two document snapshots. */
+interface FieldChange {
+  /** Top-level field key. */
+  path: string;
+  kind: FieldChangeKind;
+  /** Value in the "before" snapshot (absent for `added`). */
+  before?: JsonValue;
+  /** Value in the "after" snapshot (absent for `removed`). */
+  after?: JsonValue;
+}
+type Doc$1 = Record<string, JsonValue>;
+interface DiffOptions {
+  /**
+   * Restrict the diff to these field keys. Omit to diff the union of both
+   * documents' own keys. Useful for ignoring bookkeeping columns
+   * (`id`/`createdAt`/`publishedVersionId`) in a version-history view.
+   */
+  fields?: readonly string[];
+  /** Field keys to skip (e.g. `["id", "createdAt"]`). */
+  ignore?: readonly string[];
+}
+/**
+ * Field-level diff between two document snapshots — the per-field
+ * added/removed/changed list a version-history UI renders. Values are
+ * compared structurally (deep-equal), so a field only shows as `changed`
+ * when its content actually differs.
+ */
+declare function diffDocuments(before: Doc$1, after: Doc$1, options?: DiffOptions): FieldChange[];
+/**
+ * The {@link Patch} that transforms `before` into `after`: `set` for each
+ * added/changed field, `unset` for each removed field. `applyPatch(before,
+ * computePatch(before, after))` deep-equals `after`.
+ */
+declare function computePatch(before: Doc$1, after: Doc$1): Patch;
+/**
+ * Apply a {@link Patch} to a document, returning a new document (the input is
+ * never mutated). Unknown ops are ignored defensively.
+ */
+declare function applyPatch(doc: Doc$1, patch: Patch): Doc$1;
+//#endregion
+//#region src/cms/localApi.d.ts
+type AnyTable$1 = SQLiteTableWithColumns<any>;
+/**
+ * `TContext` is the per-request value passed to every method and forwarded
+ * unchanged to the collection's `access` functions (see {@link CollectionAccess}).
+ * Cadmus doesn't standardize its shape — Cadmea types it as `{ session }`,
+ * other consumers may type it differently. `context` is a required first
+ * argument on every method (not optional) so a call site can't forget it.
+ */
+interface LocalApi<TTable extends AnyTable$1, TContext = unknown> {
+  /**
+   * `depth: 0` (default) returns relationship fields as bare ids; `depth: 1`
+   * batch-resolves `hasMany: false` relationship fields into the related
+   * row, gated by that collection's own `read` access fn — see
+   * `resolveRelationships` below. Requires `createLocalApi`'s `registry`
+   * param; throws CadmusCmsError if `depth: 1` is requested without one.
+   */
+  find(context: TContext, options?: {
+    where?: SQL;
+    depth?: RelationshipDepth; /** Row cap, applied after `where` — for paginated list views. */
+    limit?: number; /** Rows to skip, applied after `where` — pairs with `limit`. */
+    offset?: number; /** One or more `asc(table.col)`/`desc(table.col)` expressions. */
+    orderBy?: SQL | SQL[];
+  }): Promise<InferSelectModel<TTable>[]>;
+  findByID(context: TContext, id: number, options?: {
+    depth?: RelationshipDepth;
+  }): Promise<InferSelectModel<TTable>>;
+  /**
+   * Total row count for `where` (ignoring `limit`/`offset`) — pairs with
+   * `find` to compute page counts/next-page availability without fetching
+   * every row. Gated by the same `read` access check as `find`.
+   */
+  count(context: TContext, options?: {
+    where?: SQL;
+  }): Promise<number>;
+  /**
+   * Full-text search over this collection's `search.fields`-configured
+   * companion FTS5 table — see types.ts's `CollectionConfig.search` and
+   * codegen.ts's `collectionSearchTableSQL`. Gated by `read` access, same
+   * as `find`/`findByID`. Throws `CadmusCmsError` if the collection has no
+   * `search` config.
+   */
+  search(context: TContext, query: string, options?: {
+    limit?: number;
+  }): Promise<InferSelectModel<TTable>[]>;
+  create(context: TContext, input: InferInsertModel<TTable>): Promise<InferSelectModel<TTable>>;
+  update(context: TContext, id: number, input: Partial<InferInsertModel<TTable>>): Promise<InferSelectModel<TTable>>;
+  deleteByID(context: TContext, id: number): Promise<InferSelectModel<TTable>>;
+}
+/**
+ * Lets `createLocalApi` resolve `depth: 1` relationship fields without
+ * importing every other collection's Local API (which would be a circular
+ * dependency the moment two collections relate to each other). The
+ * registry is just the raw ingredients — a table and a config per
+ * collection slug — built once by the app (e.g. from `cadmeaConfig.collections`)
+ * and passed to every `createLocalApi` call that has relationship fields.
+ *
+ * `apis` is a second, optional registry on the same object, for a
+ * different problem: a *hook* (not `createLocalApi` itself) on one
+ * collection that needs to write to *another* collection's Local API —
+ * e.g. a CRM upsert hook on a lead-capture collection that creates/updates
+ * `contacts`/`activities` rows. `tables`/`configs` can't serve this, since
+ * a hook needs a real `LocalApi` (with its own access/hooks/search wiring
+ * already applied), not raw ingredients to rebuild one from.
+ *
+ * The chicken-and-egg problem this solves: building collection A's
+ * `LocalApi` might need to reference collection B's `LocalApi` (for a
+ * hook), but collection B's `LocalApi` doesn't exist yet at the point A's
+ * is constructed — and vice versa if B also has a hook referencing A.
+ * The fix is **late binding**: build one `CmsRegistry` object, pass the
+ * *same reference* into every `createLocalApi` call (so every collection's
+ * hooks close over the same mutable object), construct every `LocalApi`,
+ * then fill in `registry.apis` afterwards:
+ *
+ * ```ts
+ * const registry: CmsRegistry = { tables, configs, apis: {} };
+ * const contactsApi = createLocalApi(db, contactsTable, contactsCollection, registry);
+ * const inquiriesApi = createLocalApi(db, inquiriesTable, inquiriesCollection, registry);
+ * // populate *after* every createLocalApi call returns — any hook that
+ * // reads registry.apis lazily (inside its returned function body, not
+ * // at hook-factory-call time) sees the fully-populated map, since hooks
+ * // only ever run once real requests start landing.
+ * Object.assign(registry.apis!, { contacts: contactsApi, inquiries: inquiriesApi });
+ * ```
+ *
+ * See `getRegisteredApi` for the accessor a hook factory should use to
+ * read from this map, rather than indexing `registry.apis` directly.
+ */
+interface CmsRegistry {
+  tables: Record<string, AnyTable$1>;
+  configs: Record<string, CollectionConfig>;
+  apis?: Record<string, LocalApi<AnyTable$1, any>>;
+}
+/**
+ * Reads collection `slug`'s `LocalApi` out of `registry.apis` — the
+ * accessor hook factories should use (see `CmsRegistry`'s doc comment for
+ * the late-binding pattern this assumes) instead of indexing
+ * `registry.apis` directly, so every caller gets the same clear error if
+ * the registry wasn't built/populated correctly. `TContext` is a type-only
+ * parameter (the registry itself is stored with `never` to stay variance-
+ * safe across collections with different context shapes) — callers assert
+ * the context type they expect, the same way `resolveRelationships`'s own
+ * registry lookups do.
+ */
+declare function getRegisteredApi<TContext>(registry: CmsRegistry | undefined, slug: string): LocalApi<AnyTable$1, TContext>;
+/**
+ * Non-throwing counterpart to `checkAccess` below, for UI code that wants
+ * to hide/disable an action a context can't perform rather than let it
+ * fail server-side after a click (see Phase 6 / issue #26's
+ * `getPageCapabilities`). `checkAccess` calls through this same function
+ * rather than duplicating the "no access fn = allowed" logic, so `can()`'s
+ * answer and the real operation's enforcement can never disagree.
+ */
+declare function can<TContext>(config: CollectionConfig, operation: keyof CollectionAccess, context: TContext): Promise<boolean>;
+declare function createLocalApi<TTable extends AnyTable$1, TContext = unknown>(db: BaseSQLiteDatabase<"async", unknown>, table: TTable, config: CollectionConfig, registry?: CmsRegistry): LocalApi<TTable, TContext>;
+/**
+ * Extends {@link LocalApi} with draft/publish operations for a collection
+ * that opted in via `CollectionConfig.versions.drafts` (see codegen.ts's
+ * `collectionVersionsTable`). A separate interface (not a wider
+ * `LocalApi`) so non-versioned collections' types don't grow these methods
+ * — TypeScript can't conditionally widen `createLocalApi`'s return type
+ * off a runtime config value, so this is `createVersionedLocalApi`'s own
+ * factory rather than a branch inside `createLocalApi`.
+ *
+ * Scope, deliberately: a document is always created via the inherited
+ * `create()` first (existing behavior, unaffected by versioning) — these
+ * methods operate against an *existing* row. `saveDraft` never validates
+ * required fields (an incomplete draft is valid); `publish` runs the same
+ * full validation `create`/`update` do, since publishing is what makes a
+ * version the public-facing document. Plain `find`/`findByID` are
+ * unchanged by any of this — they always return the main table's current
+ * row regardless of `publishedVersionId`; filtering reads to
+ * published-only content is not this phase's concern.
+ */
+interface VersionedLocalApi<TTable extends AnyTable$1, TVersionsTable extends AnyTable$1, TContext = unknown> extends LocalApi<TTable, TContext> {
+  findVersions(context: TContext, parentId: number): Promise<InferSelectModel<TVersionsTable>[]>;
+  /** Inserts a new version row holding `input` as a draft snapshot. */
+  saveDraft(context: TContext, id: number, input: Partial<InferInsertModel<TTable>>): Promise<InferSelectModel<TVersionsTable>>;
+  /** Copies a version's snapshot onto the main row and marks it published. */
+  publish(context: TContext, versionId: number): Promise<InferSelectModel<TTable>>;
+  /** Clears the main row's published pointer; the row's data is untouched. */
+  unpublish(context: TContext, id: number): Promise<InferSelectModel<TTable>>;
+  /**
+   * Field-level diff (issue #14) between two version snapshots' `versionData`
+   * — the per-field added/removed/changed list a version-history UI renders.
+   * Both versions must belong to the same parent. Bookkeeping keys
+   * (`id`/`createdAt`/`status`/`publishedVersionId`) are ignored.
+   */
+  diffVersions(context: TContext, fromVersionId: number, toVersionId: number): Promise<FieldChange[]>;
+}
+declare function createVersionedLocalApi<TTable extends AnyTable$1, TVersionsTable extends AnyTable$1, TContext = unknown>(db: BaseSQLiteDatabase<"async", unknown>, table: TTable, versionsTable: TVersionsTable, config: CollectionConfig, registry?: CmsRegistry): VersionedLocalApi<TTable, TVersionsTable, TContext>;
+//#endregion
+//#region src/cms/validation.d.ts
+type AnyTable = SQLiteTableWithColumns<any>;
+/**
+ * Chainable field validation for Cadmea (issue #16) — adopts Sanity's
+ * `defineField`/`Rule` validation API (pattern, not code). A field declares
+ * `validation: (rule) => rule.required().min(2).custom(...)`; this module
+ * turns that chain into a list of declarative checks and evaluates them at
+ * write time (server-side, in createLocalApi) as well as anywhere the studio
+ * wants synchronous feedback.
+ *
+ * Design notes:
+ * - The builder is **immutable** — every method returns a new {@link Rule}
+ *   with one more check appended, so a shared base rule can't be mutated by
+ *   a consumer's chain (mirrors Sanity).
+ * - Most checks are synchronous and pure (min/max/regex/custom over the
+ *   value alone). Two — `unique` and `reference` — need the database and so
+ *   only run where {@link validateDocument} is given a `db` (i.e. the Local
+ *   API); they're skipped (not failed) in a pure client-side pass.
+ */
+type ValidationSeverity = "error" | "warning";
+/**
+ * What a {@link CustomValidator} may return:
+ * - `true` / `undefined` → valid
+ * - `false` → invalid, generic message
+ * - `string` → invalid, that message
+ * - `{ message, severity? }` → invalid, that message at the given severity
+ */
+type CustomValidatorResult = boolean | undefined | string | {
+  message: string;
+  severity?: ValidationSeverity;
+};
+interface ValidationFieldContext {
+  /** The whole document being validated (nested shape, post-hooks). */
+  document: Record<string, unknown>;
+  /** This field's flattened key (e.g. `slug`, `shippingAddress_city`). */
+  path: string;
+  /** Whether this is a create or an update. */
+  operation: "create" | "update";
+  /** The document's id on update — lets `unique` exclude the row itself. */
+  id?: number;
+}
+type CustomValidator = (value: unknown, context: ValidationFieldContext) => CustomValidatorResult | Promise<CustomValidatorResult>;
+type Check = ({
+  kind: "required";
+} | {
+  kind: "min";
+  n: number;
+} | {
+  kind: "max";
+  n: number;
+} | {
+  kind: "length";
+  n: number;
+} | {
+  kind: "regex";
+  re: RegExp;
+  label: string;
+} | {
+  kind: "integer";
+} | {
+  kind: "positive";
+} | {
+  kind: "unique";
+} | {
+  kind: "reference";
+} | {
+  kind: "custom";
+  fn: CustomValidator;
+}) & {
+  message?: string;
+  severity?: ValidationSeverity;
+};
+/**
+ * Immutable, chainable rule builder — the value a field's `validation`
+ * function receives and returns. Build a `Rule` with the module-level
+ * {@link rule} factory, or accept the one passed to your `validation`
+ * callback.
+ */
+declare class Rule {
+  private readonly checks;
+  constructor(checks?: readonly Check[]);
+  private add;
+  /** Override the message of the most recently added check. */
+  error(message: string): Rule;
+  /**
+   * Demote the most recently added check to a warning (non-blocking),
+   * optionally with a message. Sanity's `Rule.warning()` analogue.
+   */
+  warning(message?: string): Rule;
+  private withLast;
+  required(): Rule;
+  /** Minimum string length / array length / numeric value. */
+  min(n: number): Rule;
+  /** Maximum string length / array length / numeric value. */
+  max(n: number): Rule;
+  /** Exact string/array length. */
+  length(n: number): Rule;
+  regex(re: RegExp, label?: string): Rule;
+  email(): Rule;
+  /** Lowercase kebab-case slug format. Pair with `.unique()` for slugs. */
+  slug(): Rule;
+  integer(): Rule;
+  positive(): Rule;
+  /**
+   * Value must be unique across the collection (DB-backed; skipped in a
+   * pure client-side pass). A first-class rule rather than the hand-rolled
+   * column `unique` flag, so the failure is a clear field message instead of
+   * a raw UNIQUE-constraint write error.
+   */
+  unique(): Rule;
+  /**
+   * For a `relationship` field: the referenced id must exist in the related
+   * collection (DB-backed; skipped client-side).
+   */
+  reference(): Rule;
+  custom(fn: CustomValidator): Rule;
+  /** Internal: the accumulated checks, read by {@link validateDocument}. */
+  toChecks(): readonly Check[];
+}
+/** Fresh, empty rule — the root of a chain. */
+declare function rule(): Rule;
+/**
+ * A field's `validation` value: a function from a fresh Rule to the
+ * configured chain (Sanity's signature). Returning an array lets a field
+ * carry several independent rule chains.
+ */
+type ValidationBuilder = (r: Rule) => Rule | Rule[];
+/**
+ * Identity helper mirroring Sanity's `defineField` — returns the field
+ * config unchanged but gives editors autocomplete and a single, greppable
+ * call site for field definitions. Optional: a plain object literal is still
+ * a valid field.
+ */
+declare function defineField<T extends FieldConfig>(field: T): T;
+interface ValidateDocumentOptions {
+  operation: "create" | "update";
+  /** Document id (update only) — passed to `unique`/custom validators. */
+  id?: number;
+  /**
+   * Restrict validation to these flattened field keys. Used by update(),
+   * which only receives a partial document — validating absent fields would
+   * spuriously fail their rules. Omit to validate every field (create).
+   */
+  onlyFields?: ReadonlySet<string>;
+  /**
+   * Database handle for DB-backed rules (`unique`, `reference`). When
+   * omitted, those rules are skipped — so the same function powers a pure
+   * client-side validation pass.
+   */
+  db?: BaseSQLiteDatabase<"async", unknown>;
+  /** This collection's own table (for `unique`). */
+  table?: AnyTable;
+  /** Registry of tables by slug (for `reference` target lookups). */
+  registry?: CmsRegistry;
+}
+/**
+ * Evaluate every field's validation rules against `doc`, returning all
+ * violations (both errors and warnings). `doc` is the nested document; field
+ * values are read from its flattened form so group subfields validate too.
+ */
+declare function validateDocument(config: CollectionConfig, doc: Record<string, unknown>, options: ValidateDocumentOptions): Promise<ValidationViolation[]>;
+/**
+ * Run {@link validateDocument} and throw {@link CadmusValidationError} if any
+ * `"error"`-severity violations are found. Warnings are returned (never
+ * thrown) so a caller can still surface them. The thrown error's message is
+ * a readable, joined summary of every blocking violation.
+ */
+declare function assertValid(config: CollectionConfig, doc: Record<string, unknown>, options: ValidateDocumentOptions): Promise<ValidationViolation[]>;
+//#endregion
+//#region src/cms/types.d.ts
+interface BaseFieldConfig {
+  /** column name override; defaults to the config key */
+  name?: string;
+  required?: boolean;
+  unique?: boolean;
+  defaultValue?: unknown;
+  /**
+   * Chainable validation rules (issue #16), Sanity's `defineField`
+   * `validation` analogue: `validation: (rule) => rule.required().min(2)`.
+   * Evaluated server-side by createLocalApi on every create/update (and by
+   * the studio for client-side feedback). Independent of the `required`/
+   * `unique` flags above — those still drive the DB schema; these drive
+   * value-level checks with clear, per-field error messages. See
+   * {@link ValidationBuilder} and `validation.ts`.
+   */
+  validation?: ValidationBuilder;
+}
+interface TextFieldConfig extends BaseFieldConfig {
+  type: "text";
+  defaultValue?: string;
+}
+interface SelectFieldConfig<TOption extends string = string> extends BaseFieldConfig {
+  type: "select";
+  options: readonly TOption[];
+  defaultValue?: TOption;
+}
+interface NumberFieldConfig extends BaseFieldConfig {
+  type: "number";
+  /** marks this field as the table's auto-incrementing primary key */
+  autoIncrement?: boolean;
+  defaultValue?: number;
+}
+interface DateFieldConfig extends BaseFieldConfig {
+  type: "date";
+  /** mirrors drizzle's integer(..., { mode: "timestamp" | "timestamp_ms" }) */
+  mode?: "timestamp" | "timestamp_ms";
+  defaultValue?: "now" | Date;
+}
+interface RichTextFieldConfig extends BaseFieldConfig {
+  type: "richText";
+}
+/**
+ * The TS type every JSON-mode column (`richText`/`array` fields,
+ * `versionData`) is given via drizzle's `.$type<JsonValue>()` — see
+ * codegen.ts's and schema-gen.ts's richText/array cases. Without it,
+ * drizzle infers a JSON column as `unknown`, which TanStack Start's
+ * server-function return-type validator rejects outright (`unknown`
+ * doesn't structurally match its `Serializable` check the way a plain
+ * object/array/primitive union does). Recursive on purpose — that's what
+ * lets the validator recurse through it instead of bottoming out at
+ * `unknown`.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+interface CheckboxFieldConfig extends BaseFieldConfig {
+  type: "checkbox";
+  defaultValue?: boolean;
+}
+interface RelationshipFieldConfig extends BaseFieldConfig {
+  type: "relationship";
+  relationTo: string;
+  /**
+   * `false` (default): a plain integer column on this collection's own
+   * table storing the related row's id.
+   * `true`: no column on this table — represented by a generated join
+   * table instead (see codegen.ts's relationshipJoinTables).
+   */
+  hasMany?: boolean;
+}
+/**
+ * `0` (default): a relationship field's column comes back as the bare
+ * related-row id. `1`: `createLocalApi`'s `registry` param is used to
+ * batch-resolve `hasMany: false` relationship fields into the related
+ * row's full document — see localApi.ts's `resolveRelationships`. Depths
+ * beyond 1 (resolving a relationship's own relationships) aren't
+ * implemented; there's no nested-relationship fixture yet to validate
+ * that design against.
+ */
+type RelationshipDepth = 0 | 1;
+interface ArrayFieldConfig extends BaseFieldConfig {
+  type: "array";
+  /**
+   * Fields shown for every item, regardless of variant — must include
+   * `discriminator.key`'s own field (typically a `select`) if set.
+   */
+  fields: Record<string, FieldConfig>;
+  /**
+   * Lets one array field model a union of item shapes (e.g. page-builder
+   * blocks: image vs hero vs richText vs...) instead of one fixed field
+   * set for every item. `key` names a field already present in `fields`
+   * (rendered as the item's type switcher); `variants` maps each of that
+   * field's possible values to *additional* fields layered on top, shown
+   * only for items whose `key` field currently holds that value. Fields
+   * not listed under any variant (i.e. everything in `fields`) render
+   * unconditionally — that's the place for fields shared across every
+   * variant (e.g. a `caption` every block type has).
+   *
+   * Storage is unaffected either way — `array` is always one JSON column
+   * (see codegen.ts); this only changes what `CollectionEdit` renders.
+   */
+  discriminator?: {
+    key: string;
+    variants: Record<string, Record<string, FieldConfig>>;
+  };
+}
+interface UploadFieldConfig extends BaseFieldConfig {
+  type: "upload";
+  defaultValue?: string;
+}
+/**
+ * A freeform JSON-blob column — the `json` field type from Section 3 (issue
+ * #20-adjacent field-type gap, see DECISIONS.md). Storage-identical to
+ * `richText`/`array` (one `.$type<JsonValue>()` text column, see
+ * codegen.ts's `fieldToColumn`) but with no TipTap/array-item connotation —
+ * use this for genuinely unstructured data (webhook audit payloads, CRM
+ * activity metadata), not page-builder content.
+ */
+interface JsonFieldConfig extends BaseFieldConfig {
+  type: "json";
+  defaultValue?: JsonValue;
+}
+/**
+ * A fixed-shape, queryable sub-object — the `group` field type from Section
+ * 3. Unlike `array` (JSON-blob storage, variable length), `group` flattens
+ * to real prefixed columns at the Drizzle level (`<key>_<subKey>`, see
+ * codegen.ts's `collectionToTable` and `flattenFields` below) so SQL-level
+ * querying/sorting on a subfield (e.g. `shippingAddress.city`) still works.
+ * `required`/`unique`/`defaultValue` on the group itself are meaningless —
+ * set them on the individual nested `fields` instead; codegen ignores them
+ * at the group level.
+ */
+interface GroupFieldConfig extends BaseFieldConfig {
+  type: "group";
+  fields: Record<string, FieldConfig>;
+}
+type FieldConfig = TextFieldConfig | SelectFieldConfig | NumberFieldConfig | DateFieldConfig | RichTextFieldConfig | CheckboxFieldConfig | RelationshipFieldConfig | ArrayFieldConfig | UploadFieldConfig | JsonFieldConfig | GroupFieldConfig;
+/**
+ * Expands every `group` field in `fields` into its flattened equivalents
+ * (`<key>_<subKey>`, recursively — a group nested inside a group flattens
+ * all the way down), and passes every other field through unchanged. This
+ * is the single canonicalization step codegen, schema-gen, and the Local
+ * API's field-shape validation (`validateRequiredFields`/
+ * `rejectUnknownFields`) all run before touching `group` fields, so none of
+ * them need their own group-aware branch — see localApi.ts's `flattenDoc`/
+ * `nestDoc` for the matching document-level transform.
+ *
+ * Known limitation: a flattened key can collide if two different group
+ * nestings produce the same combined name (e.g. a group `a_b` containing
+ * field `c` collides with group `a` containing field `b_c`) — not guarded
+ * against, since no current collection nests groups deeply enough to hit
+ * it.
+ */
+declare function flattenFields(fields: Record<string, FieldConfig>): Record<string, FieldConfig>;
+/**
+ * The document-level counterpart to `flattenFields` — turns a `group`
+ * field's nested object value (`{ shippingAddress: { city: "..." } }`) into
+ * its flattened equivalent (`{ shippingAddress_city: "..." }`) for writing
+ * to the DB, recursively. Fields not present in `doc` are simply omitted
+ * from the result (lets `update()`'s partial inputs flatten correctly —
+ * an absent group means every one of its flattened keys is absent too, not
+ * `undefined`-valued). See `nestDoc` for the inverse, used on read.
+ */
+declare function flattenDoc(fields: Record<string, FieldConfig>, doc: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The inverse of `flattenDoc` — re-nests a flat DB row's `<key>_<subKey>`
+ * columns back into `{ key: { subKey: ... } }` for everything the Local
+ * API returns to a caller, so a `group` field's document shape always
+ * matches its config shape regardless of how it's actually stored.
+ */
+declare function nestDoc(fields: Record<string, FieldConfig>, flatRow: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Per-operation access check, modeled on Payload's own `access` shape.
+ * @returns whether the operation is allowed. Implementations decide their
+ * own context shape (auth/session info isn't standardized by Cadmus) — see
+ * {@link LocalApi}'s `TContext` generic, which every operation now requires
+ * a value for.
+ *
+ * Enforced by `createLocalApi` since Section 2 — see
+ * {@link CollectionConfig.access}.
+ */
+type AccessFn<TContext = any> = (context: TContext) => boolean | Promise<boolean>;
+interface CollectionAccess {
+  create?: AccessFn;
+  read?: AccessFn;
+  update?: AccessFn;
+  delete?: AccessFn;
+  /**
+   * Gates `VersionedLocalApi.publish`/`unpublish` (see createVersionedLocalApi
+   * in localApi.ts). Separate from `update` — publishing is a distinct
+   * privilege from editing a draft, matching Payload's own model.
+   */
+  publish?: AccessFn;
+}
+/**
+ * Lifecycle hooks, modeled on Payload's own hook points. Each is an
+ * ordered array, run in sequence. Enforced by `createLocalApi` — see
+ * {@link CollectionConfig.hooks}.
+ */
+interface CollectionHooks<TDoc = Record<string, unknown>> {
+  beforeChange?: Array<(args: {
+    data: Partial<TDoc>;
+  }) => Partial<TDoc> | Promise<Partial<TDoc>>>;
+  /**
+   * `operation` distinguishes a freshly-inserted doc from an edited one —
+   * `publish()` (versioned collections) counts as `"update"`, since it
+   * writes to an already-existing row rather than creating one. Lets
+   * webhook config (see `cms/webhooks.ts`) filter which events it fires
+   * on without the hook itself tracking state.
+   */
+  afterChange?: Array<(args: {
+    doc: TDoc;
+    operation: "create" | "update";
+  }) => void | Promise<void>>;
+  beforeRead?: Array<(args: {
+    doc: TDoc;
+  }) => TDoc | Promise<TDoc>>;
+  afterRead?: Array<(args: {
+    doc: TDoc;
+  }) => TDoc | Promise<TDoc>>;
+  beforeDelete?: Array<(args: {
+    id: number;
+  }) => void | Promise<void>>;
+  afterDelete?: Array<(args: {
+    id: number;
+  }) => void | Promise<void>>;
+}
+/**
+ * Studio-presentation hints for a collection, modeled on Sanity's Structure
+ * Builder (`sanity/structure`). Purely about how the admin sidebar/editor
+ * *presents* a collection — never affects the DB schema, the Local API, or
+ * access control. Consumed by {@link buildStudioStructure} (see
+ * `structure.ts`); a collection with no `admin` block falls back to sensible
+ * defaults (visible, editable, listed, grouped under the default group,
+ * label = capitalized slug). Plugin-injected collections can't carry an
+ * `admin` block in hand-written config, so `buildStudioStructure` also
+ * accepts per-slug overrides at the call site — see its `overrides` option.
+ */
+interface CollectionAdminConfig {
+  /**
+   * Sidebar group heading this collection appears under (e.g. "Content",
+   * "Store"). Collections without a group fall into the builder's default
+   * group. Decoupling nav grouping from the raw collection list is the whole
+   * point of the Structure Builder.
+   */
+  group?: string;
+  /**
+   * Sort order within a group — lower sorts first. Ties (and the absence of
+   * an explicit order) break by the collection's position in the config
+   * array, so config order is the stable default.
+   */
+  order?: number;
+  /**
+   * Drop this collection from the sidebar entirely. For pure system/log
+   * tables a human never browses (e.g. `webhook_events`).
+   */
+  hidden?: boolean;
+  /**
+   * Mark as read-only in the studio — still navigable/viewable, but the UI
+   * suppresses create/edit/delete affordances. For machine-written tables a
+   * human should inspect but never edit (e.g. `payments`).
+   */
+  readOnly?: boolean;
+  /**
+   * Singleton: exactly one document. The sidebar links straight to its
+   * editor (`/admin/<slug>`) instead of a list-then-create flow — Sanity's
+   * singleton-document structure pattern. (Storage is unchanged; this only
+   * changes navigation.)
+   */
+  singleton?: boolean;
+  /** Display label override; defaults to a capitalized slug. */
+  label?: string;
+  /**
+   * Optional icon identifier passed through to the sidebar renderer (e.g. a
+   * Phosphor icon name). The builder treats it as an opaque string.
+   */
+  icon?: string;
+}
+interface CollectionConfig {
+  /** table name in D1; also the Local API's collection slug (later step) */
+  slug: string;
+  fields: Record<string, FieldConfig>;
+  /**
+   * Per-operation access control, enforced by `createLocalApi` (Section 2).
+   * Reserved per issue #16 step 7 ("reserve typed config keys now,
+   * implementation deferred to Section 2+") — that deferral is over: every
+   * `LocalApi` method now requires a `context` argument and runs the
+   * matching access function (`read` for `find`/`findByID`, `create` for
+   * `create`, etc.) before touching the database. No access function
+   * configured for an operation means that operation is unconditionally
+   * allowed, matching the pre-enforcement default.
+   */
+  access?: CollectionAccess;
+  /** Lifecycle hooks, enforced by `createLocalApi`. See {@link CollectionHooks}. */
+  hooks?: CollectionHooks;
+  /**
+   * Opts this collection into draft/version history. When `drafts` is
+   * true, codegen (see codegen.ts/schema-gen.ts) generates a companion
+   * `${slug}_versions` table and a nullable `published_version_id` pointer
+   * column on the main table, and `createVersionedLocalApi` (localApi.ts)
+   * becomes usable against it. Collections without this stay exactly as
+   * before — no versions table, no extra column, only `createLocalApi`.
+   */
+  versions?: {
+    drafts?: boolean; /** Reserved for future pruning of old versions; not enforced yet. */
+    maxPerDoc?: number;
+  };
+  /**
+   * Opts this collection into full-text search (issue #29). `fields` names
+   * which of this collection's own `text`/`richText`/`upload` fields are
+   * indexed — `defineCmsConfig`/`defineCollection` reject any other field
+   * type or an unknown key. When set, codegen (see codegen.ts's
+   * `collectionSearchTableSQL`) describes a companion `${slug}_fts` SQLite
+   * FTS5 virtual table, and `createLocalApi` both becomes able to run
+   * `.search()` and keeps that table in sync on every create/update/delete
+   * — see localApi.ts's `syncSearchIndex`. `richText` fields are flattened
+   * to plain text (TipTap JSON's `text` leaves, concatenated) before being
+   * indexed; nested `array`/block content is out of scope for this phase.
+   */
+  search?: {
+    fields: readonly string[];
+  };
+  /**
+   * Studio-presentation hints — grouping, ordering, hidden/read-only,
+   * singleton, label, icon. Consumed only by {@link buildStudioStructure}
+   * (the Structure Builder); never affects schema, Local API, or access.
+   * See {@link CollectionAdminConfig}.
+   */
+  admin?: CollectionAdminConfig;
+}
+/**
+ * A Cadmea plugin — a synchronous transform over the whole CMS config,
+ * modeled on Payload's `plugins: [(config) => config]` shape. A plugin may
+ * add or modify collections, inject fields, or register lifecycle hooks.
+ * `defineCmsConfig` runs plugins in array order, each receiving the output
+ * of the previous one, *before* validation — so a plugin's output is held
+ * to the same rules as a hand-written config.
+ *
+ * Synchronous in Section 2 by design: the resolved config is consumed by
+ * schema codegen and runtime config loading, both of which are sync. An
+ * async variant is a deliberate later extension, not an oversight.
+ */
+type CadmeaPlugin = (config: CmsConfig) => CmsConfig;
+interface CmsConfig {
+  collections: CollectionConfig[];
+  /**
+   * Config transforms run in order by `defineCmsConfig` before validation.
+   * See {@link CadmeaPlugin}. Omit for a plain, plugin-free config.
+   */
+  plugins?: CadmeaPlugin[];
+}
+//#endregion
+//#region src/cms/codegen.d.ts
+declare function collectionToTable(config: CollectionConfig): import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+  name: string;
+  schema: undefined;
+  columns: {
+    [x: string]: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: string;
+      tableName: string;
+      dataType: import("drizzle-orm").ColumnDataType;
+      columnType: string;
+      data: unknown;
+      driverParam: unknown;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: string[] | undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  };
+  dialect: "sqlite";
+}>;
+declare function collectionVersionsTable(config: CollectionConfig): import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+  name: `${string}_versions`;
+  schema: undefined;
+  columns: {
+    id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "id";
+      tableName: `${string}_versions`;
+      dataType: "number";
+      columnType: "SQLiteInteger";
+      data: number;
+      driverParam: number;
+      notNull: true;
+      hasDefault: true;
+      isPrimaryKey: true;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    parentId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "parent_id";
+      tableName: `${string}_versions`;
+      dataType: "number";
+      columnType: "SQLiteInteger";
+      data: number;
+      driverParam: number;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+    versionData: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "version_data";
+      tableName: `${string}_versions`;
+      dataType: "json";
+      columnType: "SQLiteTextJson";
+      data: JsonValue;
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      $type: JsonValue;
+    }>;
+    status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "status";
+      tableName: `${string}_versions`;
+      dataType: "string";
+      columnType: "SQLiteText";
+      data: "draft" | "published";
+      driverParam: string;
+      notNull: true;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: ["draft", "published"];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: number | undefined;
+    }>;
+    createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+      name: "created_at";
+      tableName: `${string}_versions`;
+      dataType: "date";
+      columnType: "SQLiteTimestamp";
+      data: Date;
+      driverParam: number;
+      notNull: false;
+      hasDefault: true;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: true;
+      enumValues: undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  };
+  dialect: "sqlite";
+}>;
+declare function relationshipJoinTables(config: CollectionConfig): Record<string, ReturnType<typeof sqliteTable>>;
+declare function collectionSearchTableName(config: CollectionConfig): string;
+declare function collectionSearchTableSQL(config: CollectionConfig): string;
+declare function extractSearchText(config: CollectionConfig, doc: Record<string, unknown>): string[];
+declare function cmsConfigToSchema(config: CmsConfig): Record<string, ReturnType<typeof collectionToTable> | ReturnType<typeof collectionVersionsTable>>;
+//#endregion
+//#region src/cms/defineCollection.d.ts
+declare function defineCollection(config: CollectionConfig): CollectionConfig;
+declare function defineCmsConfig(config: CmsConfig): CmsConfig;
+//#endregion
+//#region src/cms/meta.d.ts
+interface CollectionMeta {
+  slug: string;
+  fields: CollectionConfig["fields"];
+  /** Whether `LocalApi.search()` is usable for this collection — see `CollectionConfig.search`. */
+  searchable: boolean;
+}
+declare function getCollectionsMeta(config: CmsConfig): CollectionMeta[];
+//#endregion
+//#region src/cms/migrate.d.ts
+/**
+ * Content-migration runner (issue #18) — adopts Sanity's `sanity/migrate`
+ * idea (pattern, not code): a versioned, repeatable transform over a
+ * collection's stored documents, for reshaping content when a block/field
+ * type changes (distinct from Drizzle *schema* migrations, which only touch
+ * columns — this reshapes the JSON content inside them).
+ *
+ * A migration declares a per-document `document(doc)` transform; the runner
+ * streams every document, computes the {@link Patch} from old→new (reusing
+ * #14's patch model), and either reports it (`dryRun`) or applies it via the
+ * collection's Local API. Idempotent by construction: a transform that's
+ * already been applied produces an empty patch, so re-running changes
+ * nothing.
+ */
+type Doc = Record<string, JsonValue>;
+interface Migration<TDoc extends Doc = Doc> {
+  /** Stable identifier — name the checked-in migration file after this. */
+  name: string;
+  /**
+   * Transform one document. Return the reshaped document, or `undefined`
+   * (or the unchanged doc) to leave it as-is. Must be pure and idempotent —
+   * applying it twice yields the same result as once.
+   */
+  document: (doc: TDoc) => TDoc | undefined | Promise<TDoc | undefined>;
+}
+/** Identity helper — gives a migration definition its type + a greppable call site. */
+declare function defineMigration<TDoc extends Doc = Doc>(migration: Migration<TDoc>): Migration<TDoc>;
+interface MigrationChange {
+  id: number;
+  patch: Patch;
+}
+interface MigrationResult {
+  migration: string;
+  dryRun: boolean;
+  scanned: number;
+  changed: number;
+  /** Per-document patches (always populated — the dry-run report). */
+  changes: MigrationChange[];
+  errors: string[];
+}
+interface RunMigrationOptions<TContext> {
+  api: LocalApi<any, TContext>;
+  /** Context passed to the Local API's read/update (access + hooks). */
+  context: TContext;
+  /** When true, compute + report patches but write nothing. Default false. */
+  dryRun?: boolean;
+}
+/**
+ * Run a migration over every document in a collection. Reads all documents
+ * through `api.find`, applies `migration.document`, and (unless `dryRun`)
+ * writes the resulting patch through `api.update`. Returns a report of what
+ * changed — run it `dryRun` first, then apply.
+ */
+declare function runMigration<TContext>(migration: Migration, options: RunMigrationOptions<TContext>): Promise<MigrationResult>;
+//#endregion
+//#region src/cms/schema-gen.d.ts
+declare function generateSchemaSource(config: CmsConfig): string;
+//#endregion
+//#region src/cms/structure.d.ts
+/**
+ * Cadmea's Structure Builder — the framework half of issue #12.
+ *
+ * Adopts Sanity's `sanity/structure` idea (pattern, not code): **decouple
+ * the admin nav from the raw collection list.** Instead of mapping every
+ * `config.collections` entry to an `/admin/<slug>` link — which surfaces
+ * system/log tables as editable links and produces dead links — the sidebar
+ * renders from an explicit, grouped structure derived here from each
+ * collection's `admin` hints (see {@link CollectionAdminConfig}) plus
+ * optional per-slug overrides supplied at the call site.
+ *
+ * Pure data in / pure data out: no SolidJS, no DOM, no server imports — so
+ * it's safe to import from a client studio component (e.g. the site's
+ * `PanelNav`) and trivially testable.
+ */
+/** Default group heading for collections that don't declare `admin.group`. */
+declare const DEFAULT_STUDIO_GROUP = "Content";
+/** One navigable collection entry in the studio sidebar. */
+interface StudioStructureItem {
+  /** The collection's slug. */
+  slug: string;
+  /** Human label — `admin.label`, else the capitalized slug. */
+  label: string;
+  /** Where the sidebar link points (`/admin/<slug>`, configurable prefix). */
+  href: string;
+  /** Read-only collections are viewable but not editable in the studio. */
+  readOnly: boolean;
+  /**
+   * Singletons link straight to their editor rather than a list+create
+   * flow. (The href is identical; the renderer uses this to skip the list.)
+   */
+  singleton: boolean;
+  /** Opaque icon identifier from `admin.icon`, if any. */
+  icon?: string;
+}
+/** A titled group of sidebar items, in render order. */
+interface StudioStructureGroup {
+  title: string;
+  items: StudioStructureItem[];
+}
+interface BuildStudioStructureOptions {
+  /**
+   * Per-slug presentation overrides, merged over each collection's own
+   * `admin` block (override keys win). The escape hatch for plugin-injected
+   * collections (`products`, `payments`, `webhook_events`, …) that can't
+   * carry an `admin` block in hand-written config — the studio declares
+   * their presentation here, exactly like Sanity defines structure at the
+   * studio level rather than on the schema.
+   */
+  overrides?: Record<string, CollectionAdminConfig>;
+  /**
+   * Explicit group ordering by title. Groups listed here render first, in
+   * this order; any remaining groups follow in first-appearance order. A
+   * group title absent from `config`'s collections simply doesn't appear.
+   */
+  groupOrder?: readonly string[];
+  /**
+   * Link prefix for each item's `href`. Defaults to `/admin`, producing
+   * `/admin/<slug>`. No trailing slash.
+   */
+  basePath?: string;
+}
+/**
+ * Build the studio sidebar structure from a resolved CMS config.
+ *
+ * - Hidden collections (`admin.hidden`) are dropped entirely.
+ * - Each remaining collection is placed in its `admin.group` (or
+ *   {@link DEFAULT_STUDIO_GROUP}).
+ * - Within a group, items sort by `admin.order` (ascending; unset sorts
+ *   after set), then by their original position in `config.collections` —
+ *   so config order is the stable tiebreaker.
+ * - Groups render in `options.groupOrder` first, then first-appearance
+ *   order for the rest.
+ *
+ * The input is expected to be the *resolved* config (post-plugins), since
+ * that's what carries plugin-injected collections like `products`.
+ */
+declare function buildStudioStructure(config: CmsConfig, options?: BuildStudioStructureOptions): StudioStructureGroup[];
+//#endregion
+//#region src/cms/visual-editing.d.ts
+/**
+ * Visual editing / click-to-edit (issue #15) — adopts Sanity's
+ * Presentation/visual-editing idea (pattern, not code): the rendered page
+ * (in a preview context) tags editable regions with the source field they
+ * came from, and an overlay turns those regions into click targets that tell
+ * the studio which field to focus.
+ *
+ * This module ships the two reusable, framework-agnostic primitives:
+ * 1. **Encoding** — `editAttr({ collection, id, field })` produces a data
+ *    attribute the server renderer spreads onto an element; `decodeEditRef`
+ *    reads it back. Pure, testable.
+ * 2. **Overlay** — `mountVisualEditing()` (browser-only; references `document`
+ *    lazily, so importing it server-side is harmless) highlights tagged
+ *    elements on hover and, on click, calls `onSelect` and `postMessage`s the
+ *    ref to the parent window (the studio shell hosting the preview iframe).
+ *
+ * The studio side listens for that message and navigates to
+ * `/admin/<collection>/<id>` (and may focus `<field>`); that wiring is
+ * consumer-side and not prescribed here.
+ */
+/** A reference from a rendered region back to the field that produced it. */
+interface EditRef {
+  collection: string;
+  id: number;
+  field: string;
+}
+/** The data attribute editable regions are tagged with. */
+declare const EDIT_ATTR = "data-cadmus-edit";
+/** `postMessage` payload type for a click-to-edit selection. */
+declare const VISUAL_EDIT_MESSAGE = "cadmus:visual-edit";
+declare function encodeEditRef(ref: EditRef): string;
+/** Parse an {@link EditRef} string, or null if malformed. */
+declare function decodeEditRef(value: string): EditRef | null;
+/**
+ * Attribute object to spread onto a rendered element so the overlay can map
+ * it back to its source field, e.g. `<h1 {...editAttr({collection:'pages',
+ * id, field:'title'})}>`.
+ */
+declare function editAttr(ref: EditRef): Record<string, string>;
+interface VisualEditingMessage {
+  type: typeof VISUAL_EDIT_MESSAGE;
+  ref: EditRef;
+}
+interface VisualEditingOptions {
+  /** Called with the decoded ref when an editable region is clicked. */
+  onSelect?: (ref: EditRef, element: Element) => void;
+  /**
+   * Origin to `postMessage` the selection to the parent window. Default
+   * `"*"`. Set to the studio origin in production.
+   */
+  targetOrigin?: string;
+  /** Outline color for the hover highlight. Default a teal accent. */
+  highlightColor?: string;
+}
+/**
+ * Mount the click-to-edit overlay. Browser-only — call from a preview page's
+ * client script. Highlights `[data-cadmus-edit]` elements on hover and, on
+ * click, calls `onSelect` and posts a {@link VisualEditingMessage} to the
+ * parent window. Returns a cleanup function that removes the listeners.
+ */
+declare function mountVisualEditing(options?: VisualEditingOptions): () => void;
+//#endregion
+//#region src/cms/webhooks.d.ts
+interface WebhookConfig {
+  /** Endpoint this webhook POSTs to on every matching event. */
+  url: string;
+  /** Restricts delivery to these operations. Default: both. */
+  events?: Array<"create" | "update">;
+  /**
+   * When set, every delivery carries an `X-Cadmus-Signature` header —
+   * HMAC-SHA256 (hex) over the raw JSON body — so the receiver can verify
+   * the payload actually came from this Cadmus instance.
+   */
+  secret?: string;
+}
+/** The shape enqueued by `createWebhookHook`, consumed by `deliverWebhookMessage`. */
+interface WebhookMessage {
+  url: string;
+  secret?: string;
+  event: "create" | "update";
+  doc: Record<string, unknown>;
+  /** ms since epoch, included in the signed/delivered payload. */
+  timestamp: number;
+}
+/**
+ * Builds an `afterChange` hook that enqueues a `WebhookMessage` for every
+ * matching write — append the result to a collection's
+ * `hooks.afterChange` array. `queue` is whatever `Queue<WebhookMessage>`
+ * binding the caller's Worker has configured for webhook dispatch (see
+ * wrangler.jsonc's webhook queue producer binding).
+ */
+declare function createWebhookHook(queue: Queue<WebhookMessage>, config: WebhookConfig): NonNullable<CollectionHooks["afterChange"]>[number];
+/**
+ * Delivers a single `WebhookMessage` via `fetch()`. Throws
+ * `CadmusQueueError` on any non-2xx response or network failure — meant
+ * to be called from inside `processBatch`'s handler, where a thrown error
+ * becomes a `message.retry()`.
+ */
+declare function deliverWebhookMessage(message: WebhookMessage): Promise<void>;
+//#endregion
+export { RelationshipDepth as $, cmsConfigToSchema as A, PatchOp as At, CadmeaPlugin as B, CadmusEmailError as Bt, RunMigrationOptions as C, createLocalApi as Ct, getCollectionsMeta as D, FieldChange as Dt, CollectionMeta as E, DiffOptions as Et, extractSearchText as F, CadmusApiError as Ft, CollectionConfig as G, CadmusStorageError as Gt, CmsConfig as H, CadmusQueueError as Ht, relationshipJoinTables as I, CadmusAuthError as It, FieldConfig as J, BlockRegistry as Jt, CollectionHooks as K, CadmusValidationError as Kt, AccessFn as L, CadmusCacheError as Lt, collectionSearchTableSQL as M, computePatch as Mt, collectionToTable as N, diffDocuments as Nt, defineCmsConfig as O, FieldChangeKind as Ot, collectionVersionsTable as P, CadmusAccessDeniedError as Pt, NumberFieldConfig as Q, renderBlocksToString as Qt, ArrayFieldConfig as R, CadmusCmsError as Rt, MigrationResult as S, can as St, runMigration as T, getRegisteredApi as Tt, CollectionAccess as U, CadmusRateLimitError as Ut, CheckboxFieldConfig as V, CadmusError as Vt, CollectionAdminConfig as W, CadmusSessionError as Wt, JsonFieldConfig as X, StringBlockRenderer as Xt, GroupFieldConfig as Y, PortableBlockLike as Yt, JsonValue as Z, createBlockRegistry as Zt, StudioStructureItem as _, rule as _t, EDIT_ATTR as a, flattenDoc as at, Migration as b, LocalApi as bt, VisualEditingMessage as c, CustomValidator as ct, editAttr as d, ValidateDocumentOptions as dt, RelationshipFieldConfig as et, encodeEditRef as f, ValidationBuilder as ft, StudioStructureGroup as g, defineField as gt, DEFAULT_STUDIO_GROUP as h, assertValid as ht, deliverWebhookMessage as i, UploadFieldConfig as it, collectionSearchTableName as j, applyPatch as jt, defineCollection as k, Patch as kt, VisualEditingOptions as l, CustomValidatorResult as lt, BuildStudioStructureOptions as m, ValidationSeverity as mt, WebhookMessage as n, SelectFieldConfig as nt, EditRef as o, flattenFields as ot, mountVisualEditing as p, ValidationFieldContext as pt, DateFieldConfig as q, ValidationViolation as qt, createWebhookHook as r, TextFieldConfig as rt, VISUAL_EDIT_MESSAGE as s, nestDoc as st, WebhookConfig as t, RichTextFieldConfig as tt, decodeEditRef as u, Rule as ut, buildStudioStructure as v, validateDocument as vt, defineMigration as w, createVersionedLocalApi as wt, MigrationChange as x, VersionedLocalApi as xt, generateSchemaSource as y, CmsRegistry as yt, BaseFieldConfig as z, CadmusDbError as zt };
+//# sourceMappingURL=index-sB3YOadC.d.cts.map