@thebes/cadmus 0.3.0 → 0.4.1

package/dist/hono/index.d.cts

@@ -1,4 +1,4 @@
-import { at as LocalApi } from "../index-BRZrCTsN.cjs";
+import { xt as LocalApi } from "../index-CWrSoiPh.cjs";
 import { Context, Hono } from "hono";
 
 //#region src/hono/client.d.ts

package/dist/hono/index.d.ts

@@ -1,4 +1,4 @@
-import { at as LocalApi } from "../index-BRZrCTsN.js";
+import { xt as LocalApi } from "../index-CWrSoiPh.js";
 import { Context, Hono } from "hono";
 
 //#region src/hono/client.d.ts

package/dist/{index-BRZrCTsN.d.cts → index-CWrSoiPh.d.cts}

@@ -180,6 +180,72 @@ declare class CadmusApiError extends CadmusError {
   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>;
 /**
@@ -322,6 +388,13 @@ interface VersionedLocalApi<TTable extends AnyTable$1, TVersionsTable extends An
   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
@@ -495,12 +568,42 @@ declare function validateDocument(config: CollectionConfig, doc: Record<string,
 declare function assertValid(config: CollectionConfig, doc: Record<string, unknown>, options: ValidateDocumentOptions): Promise<ValidationViolation[]>;
 //#endregion
 //#region src/cms/types.d.ts
+/**
+ * Editor-only presentation hints for a single field (issue #16 follow-on) —
+ * the field-level counterpart to {@link CollectionAdminConfig}. Purely about
+ * how the studio renders the field; absent → sensible defaults (a humanized
+ * key for the label, no help text, full width, always shown, editable). None
+ * of this touches the DB schema or the Local API.
+ */
+interface FieldAdminConfig {
+  /** Human-friendly label; defaults to a humanized field key (`metaDescription` → "Meta description"). */
+  label?: string;
+  /** Help text rendered beneath the label. */
+  description?: string;
+  /** Placeholder for text-like inputs. */
+  placeholder?: string;
+  /** Groups the field into a titled fieldset in the editor, in first-seen order. */
+  group?: string;
+  /** Editor column width on >= md screens. Defaults to "full". */
+  width?: "full" | "half";
+  /**
+   * Show the field only when this predicate — given the whole in-progress
+   * form value — returns true (Payload's `admin.condition`). A function, so
+   * it's evaluated by the studio directly from the imported config, not from
+   * a serialized meta payload.
+   */
+  condition?: (values: Record<string, unknown>) => boolean;
+  /** Render the field read-only in the editor. */
+  readOnly?: boolean;
+}
 interface BaseFieldConfig {
   /** column name override; defaults to the config key */
   name?: string;
   required?: boolean;
   unique?: boolean;
   defaultValue?: unknown;
+  /** Editor-only presentation hints — see {@link FieldAdminConfig}. */
+  admin?: FieldAdminConfig;
   /**
    * Chainable validation rules (issue #16), Sanity's `defineField`
    * `validation` analogue: `validation: (rule) => rule.required().min(2)`.
@@ -599,6 +702,16 @@ interface ArrayFieldConfig extends BaseFieldConfig {
   discriminator?: {
     key: string;
     variants: Record<string, Record<string, FieldConfig>>;
+    /**
+     * Optional per-variant presentation for the studio's "Add block" picker
+     * (the visual block builder). `label` defaults to a humanized variant
+     * name; `icon` is an opaque CSS class the studio applies to an `<i>`
+     * (e.g. a Phosphor `"ph ph-image"`), keeping cadmea icon-library-agnostic.
+     */
+    variantsAdmin?: Record<string, {
+      label?: string;
+      icon?: string;
+    }>;
   };
 }
 interface UploadFieldConfig extends BaseFieldConfig {
@@ -987,6 +1100,62 @@ interface CollectionMeta {
 }
 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
@@ -1070,6 +1239,69 @@ interface BuildStudioStructureOptions {
  */
 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. */
@@ -1108,5 +1340,5 @@ declare function createWebhookHook(queue: Queue<WebhookMessage>, config: Webhook
  */
 declare function deliverWebhookMessage(message: WebhookMessage): Promise<void>;
 //#endregion
-export { ValidationSeverity as $, CollectionConfig as A, RichTextFieldConfig as B, ArrayFieldConfig as C, CadmusValidationError as Ct, CmsConfig as D, StringBlockRenderer as Dt, CheckboxFieldConfig as E, PortableBlockLike as Et, JsonFieldConfig as F, flattenFields as G, TextFieldConfig as H, JsonValue as I, CustomValidatorResult as J, nestDoc as K, NumberFieldConfig as L, DateFieldConfig as M, FieldConfig as N, CollectionAccess as O, createBlockRegistry as Ot, GroupFieldConfig as P, ValidationFieldContext as Q, RelationshipDepth as R, AccessFn as S, CadmusStorageError as St, CadmeaPlugin as T, BlockRegistry as Tt, UploadFieldConfig as U, SelectFieldConfig as V, flattenDoc as W, ValidateDocumentOptions as X, Rule as Y, ValidationBuilder as Z, collectionSearchTableSQL as _, CadmusEmailError as _t, BuildStudioStructureOptions as a, LocalApi as at, extractSearchText as b, CadmusRateLimitError as bt, StudioStructureItem as c, createLocalApi as ct, CollectionMeta as d, CadmusAccessDeniedError as dt, assertValid as et, getCollectionsMeta as f, CadmusApiError as ft, collectionSearchTableName as g, CadmusDbError as gt, cmsConfigToSchema as h, CadmusCmsError as ht, deliverWebhookMessage as i, CmsRegistry as it, CollectionHooks as j, CollectionAdminConfig as k, renderBlocksToString as kt, buildStudioStructure as l, createVersionedLocalApi as lt, defineCollection as m, CadmusCacheError as mt, WebhookMessage as n, rule as nt, DEFAULT_STUDIO_GROUP as o, VersionedLocalApi as ot, defineCmsConfig as p, CadmusAuthError as pt, CustomValidator as q, createWebhookHook as r, validateDocument as rt, StudioStructureGroup as s, can as st, WebhookConfig as t, defineField as tt, generateSchemaSource as u, getRegisteredApi as ut, collectionToTable as v, CadmusError as vt, BaseFieldConfig as w, ValidationViolation as wt, relationshipJoinTables as x, CadmusSessionError as xt, collectionVersionsTable as y, CadmusQueueError as yt, RelationshipFieldConfig as z };
-//# sourceMappingURL=index-BRZrCTsN.d.cts.map
+export { NumberFieldConfig as $, renderBlocksToString as $t, cmsConfigToSchema as A, Patch as At, CadmeaPlugin as B, CadmusDbError as Bt, RunMigrationOptions as C, can as Ct, getCollectionsMeta as D, DiffOptions as Dt, CollectionMeta as E, getRegisteredApi as Et, extractSearchText as F, CadmusAccessDeniedError as Ft, CollectionConfig as G, CadmusSessionError as Gt, CmsConfig as H, CadmusError as Ht, relationshipJoinTables as I, CadmusApiError as It, FieldAdminConfig as J, ValidationViolation as Jt, CollectionHooks as K, CadmusStorageError as Kt, AccessFn as L, CadmusAuthError as Lt, collectionSearchTableSQL as M, applyPatch as Mt, collectionToTable as N, computePatch as Nt, defineCmsConfig as O, FieldChange as Ot, collectionVersionsTable as P, diffDocuments as Pt, JsonValue as Q, createBlockRegistry as Qt, ArrayFieldConfig as R, CadmusCacheError as Rt, MigrationResult as S, VersionedLocalApi as St, runMigration as T, createVersionedLocalApi as Tt, CollectionAccess as U, CadmusQueueError as Ut, CheckboxFieldConfig as V, CadmusEmailError as Vt, CollectionAdminConfig as W, CadmusRateLimitError as Wt, GroupFieldConfig as X, PortableBlockLike as Xt, FieldConfig as Y, BlockRegistry as Yt, JsonFieldConfig as Z, StringBlockRenderer as Zt, StudioStructureItem as _, defineField as _t, EDIT_ATTR as a, UploadFieldConfig as at, Migration as b, CmsRegistry as bt, VisualEditingMessage as c, nestDoc as ct, editAttr as d, Rule as dt, RelationshipDepth as et, encodeEditRef as f, ValidateDocumentOptions as ft, StudioStructureGroup as g, assertValid as gt, DEFAULT_STUDIO_GROUP as h, ValidationSeverity as ht, deliverWebhookMessage as i, TextFieldConfig as it, collectionSearchTableName as j, PatchOp as jt, defineCollection as k, FieldChangeKind as kt, VisualEditingOptions as l, CustomValidator as lt, BuildStudioStructureOptions as m, ValidationFieldContext as mt, WebhookMessage as n, RichTextFieldConfig as nt, EditRef as o, flattenDoc as ot, mountVisualEditing as p, ValidationBuilder as pt, DateFieldConfig as q, CadmusValidationError as qt, createWebhookHook as r, SelectFieldConfig as rt, VISUAL_EDIT_MESSAGE as s, flattenFields as st, WebhookConfig as t, RelationshipFieldConfig as tt, decodeEditRef as u, CustomValidatorResult as ut, buildStudioStructure as v, rule as vt, defineMigration as w, createLocalApi as wt, MigrationChange as x, LocalApi as xt, generateSchemaSource as y, validateDocument as yt, BaseFieldConfig as z, CadmusCmsError as zt };
+//# sourceMappingURL=index-CWrSoiPh.d.cts.map

package/dist/index-CWrSoiPh.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CWrSoiPh.d.cts","names":[],"sources":["../src/cms/blocks.ts","../src/errors.ts","../src/cms/patch.ts","../src/cms/localApi.ts","../src/cms/validation.ts","../src/cms/types.ts","../src/cms/codegen.ts","../src/cms/defineCollection.ts","../src/cms/meta.ts","../src/cms/migrate.ts","../src/cms/schema-gen.ts","../src/cms/structure.ts","../src/cms/visual-editing.ts","../src/cms/webhooks.ts"],"mappings":"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"}

package/dist/{index-BRZrCTsN.d.ts → index-CWrSoiPh.d.ts}

@@ -180,6 +180,72 @@ declare class CadmusApiError extends CadmusError {
   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>;
 /**
@@ -322,6 +388,13 @@ interface VersionedLocalApi<TTable extends AnyTable$1, TVersionsTable extends An
   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
@@ -495,12 +568,42 @@ declare function validateDocument(config: CollectionConfig, doc: Record<string,
 declare function assertValid(config: CollectionConfig, doc: Record<string, unknown>, options: ValidateDocumentOptions): Promise<ValidationViolation[]>;
 //#endregion
 //#region src/cms/types.d.ts
+/**
+ * Editor-only presentation hints for a single field (issue #16 follow-on) —
+ * the field-level counterpart to {@link CollectionAdminConfig}. Purely about
+ * how the studio renders the field; absent → sensible defaults (a humanized
+ * key for the label, no help text, full width, always shown, editable). None
+ * of this touches the DB schema or the Local API.
+ */
+interface FieldAdminConfig {
+  /** Human-friendly label; defaults to a humanized field key (`metaDescription` → "Meta description"). */
+  label?: string;
+  /** Help text rendered beneath the label. */
+  description?: string;
+  /** Placeholder for text-like inputs. */
+  placeholder?: string;
+  /** Groups the field into a titled fieldset in the editor, in first-seen order. */
+  group?: string;
+  /** Editor column width on >= md screens. Defaults to "full". */
+  width?: "full" | "half";
+  /**
+   * Show the field only when this predicate — given the whole in-progress
+   * form value — returns true (Payload's `admin.condition`). A function, so
+   * it's evaluated by the studio directly from the imported config, not from
+   * a serialized meta payload.
+   */
+  condition?: (values: Record<string, unknown>) => boolean;
+  /** Render the field read-only in the editor. */
+  readOnly?: boolean;
+}
 interface BaseFieldConfig {
   /** column name override; defaults to the config key */
   name?: string;
   required?: boolean;
   unique?: boolean;
   defaultValue?: unknown;
+  /** Editor-only presentation hints — see {@link FieldAdminConfig}. */
+  admin?: FieldAdminConfig;
   /**
    * Chainable validation rules (issue #16), Sanity's `defineField`
    * `validation` analogue: `validation: (rule) => rule.required().min(2)`.
@@ -599,6 +702,16 @@ interface ArrayFieldConfig extends BaseFieldConfig {
   discriminator?: {
     key: string;
     variants: Record<string, Record<string, FieldConfig>>;
+    /**
+     * Optional per-variant presentation for the studio's "Add block" picker
+     * (the visual block builder). `label` defaults to a humanized variant
+     * name; `icon` is an opaque CSS class the studio applies to an `<i>`
+     * (e.g. a Phosphor `"ph ph-image"`), keeping cadmea icon-library-agnostic.
+     */
+    variantsAdmin?: Record<string, {
+      label?: string;
+      icon?: string;
+    }>;
   };
 }
 interface UploadFieldConfig extends BaseFieldConfig {
@@ -987,6 +1100,62 @@ interface CollectionMeta {
 }
 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
@@ -1070,6 +1239,69 @@ interface BuildStudioStructureOptions {
  */
 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. */
@@ -1108,5 +1340,5 @@ declare function createWebhookHook(queue: Queue<WebhookMessage>, config: Webhook
  */
 declare function deliverWebhookMessage(message: WebhookMessage): Promise<void>;
 //#endregion
-export { ValidationSeverity as $, CollectionConfig as A, RichTextFieldConfig as B, ArrayFieldConfig as C, CadmusValidationError as Ct, CmsConfig as D, StringBlockRenderer as Dt, CheckboxFieldConfig as E, PortableBlockLike as Et, JsonFieldConfig as F, flattenFields as G, TextFieldConfig as H, JsonValue as I, CustomValidatorResult as J, nestDoc as K, NumberFieldConfig as L, DateFieldConfig as M, FieldConfig as N, CollectionAccess as O, createBlockRegistry as Ot, GroupFieldConfig as P, ValidationFieldContext as Q, RelationshipDepth as R, AccessFn as S, CadmusStorageError as St, CadmeaPlugin as T, BlockRegistry as Tt, UploadFieldConfig as U, SelectFieldConfig as V, flattenDoc as W, ValidateDocumentOptions as X, Rule as Y, ValidationBuilder as Z, collectionSearchTableSQL as _, CadmusEmailError as _t, BuildStudioStructureOptions as a, LocalApi as at, extractSearchText as b, CadmusRateLimitError as bt, StudioStructureItem as c, createLocalApi as ct, CollectionMeta as d, CadmusAccessDeniedError as dt, assertValid as et, getCollectionsMeta as f, CadmusApiError as ft, collectionSearchTableName as g, CadmusDbError as gt, cmsConfigToSchema as h, CadmusCmsError as ht, deliverWebhookMessage as i, CmsRegistry as it, CollectionHooks as j, CollectionAdminConfig as k, renderBlocksToString as kt, buildStudioStructure as l, createVersionedLocalApi as lt, defineCollection as m, CadmusCacheError as mt, WebhookMessage as n, rule as nt, DEFAULT_STUDIO_GROUP as o, VersionedLocalApi as ot, defineCmsConfig as p, CadmusAuthError as pt, CustomValidator as q, createWebhookHook as r, validateDocument as rt, StudioStructureGroup as s, can as st, WebhookConfig as t, defineField as tt, generateSchemaSource as u, getRegisteredApi as ut, collectionToTable as v, CadmusError as vt, BaseFieldConfig as w, ValidationViolation as wt, relationshipJoinTables as x, CadmusSessionError as xt, collectionVersionsTable as y, CadmusQueueError as yt, RelationshipFieldConfig as z };
-//# sourceMappingURL=index-BRZrCTsN.d.ts.map
+export { NumberFieldConfig as $, renderBlocksToString as $t, cmsConfigToSchema as A, Patch as At, CadmeaPlugin as B, CadmusDbError as Bt, RunMigrationOptions as C, can as Ct, getCollectionsMeta as D, DiffOptions as Dt, CollectionMeta as E, getRegisteredApi as Et, extractSearchText as F, CadmusAccessDeniedError as Ft, CollectionConfig as G, CadmusSessionError as Gt, CmsConfig as H, CadmusError as Ht, relationshipJoinTables as I, CadmusApiError as It, FieldAdminConfig as J, ValidationViolation as Jt, CollectionHooks as K, CadmusStorageError as Kt, AccessFn as L, CadmusAuthError as Lt, collectionSearchTableSQL as M, applyPatch as Mt, collectionToTable as N, computePatch as Nt, defineCmsConfig as O, FieldChange as Ot, collectionVersionsTable as P, diffDocuments as Pt, JsonValue as Q, createBlockRegistry as Qt, ArrayFieldConfig as R, CadmusCacheError as Rt, MigrationResult as S, VersionedLocalApi as St, runMigration as T, createVersionedLocalApi as Tt, CollectionAccess as U, CadmusQueueError as Ut, CheckboxFieldConfig as V, CadmusEmailError as Vt, CollectionAdminConfig as W, CadmusRateLimitError as Wt, GroupFieldConfig as X, PortableBlockLike as Xt, FieldConfig as Y, BlockRegistry as Yt, JsonFieldConfig as Z, StringBlockRenderer as Zt, StudioStructureItem as _, defineField as _t, EDIT_ATTR as a, UploadFieldConfig as at, Migration as b, CmsRegistry as bt, VisualEditingMessage as c, nestDoc as ct, editAttr as d, Rule as dt, RelationshipDepth as et, encodeEditRef as f, ValidateDocumentOptions as ft, StudioStructureGroup as g, assertValid as gt, DEFAULT_STUDIO_GROUP as h, ValidationSeverity as ht, deliverWebhookMessage as i, TextFieldConfig as it, collectionSearchTableName as j, PatchOp as jt, defineCollection as k, FieldChangeKind as kt, VisualEditingOptions as l, CustomValidator as lt, BuildStudioStructureOptions as m, ValidationFieldContext as mt, WebhookMessage as n, RichTextFieldConfig as nt, EditRef as o, flattenDoc as ot, mountVisualEditing as p, ValidationBuilder as pt, DateFieldConfig as q, CadmusValidationError as qt, createWebhookHook as r, SelectFieldConfig as rt, VISUAL_EDIT_MESSAGE as s, flattenFields as st, WebhookConfig as t, RelationshipFieldConfig as tt, decodeEditRef as u, CustomValidatorResult as ut, buildStudioStructure as v, rule as vt, defineMigration as w, createLocalApi as wt, MigrationChange as x, LocalApi as xt, generateSchemaSource as y, validateDocument as yt, BaseFieldConfig as z, CadmusCmsError as zt };
+//# sourceMappingURL=index-CWrSoiPh.d.ts.map