@valbuild/core 0.125.0 → 0.126.0

package/dist/declarations/src/schema/file.d.ts

@@ -37,8 +37,71 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     private readonly renderInput;
     private readonly previewInput;
     constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s.file().describe("The PDF offered for download");
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
+     */
     describe(description: string | null): FileSchema<Src>;
+    /**
+     * Store the file on Val's remote content host instead of in your repository.
+     *
+     * The bytes still go into the patch store when the file is uploaded — the
+     * push to the remote host happens at publish. What changes is where the
+     * published file lives: `path` becomes a remote URL rather than a path under
+     * `/public`, so the repository does not grow with every upload.
+     *
+     * The `path` of a remote file is a URL on the content host, and it is not
+     * something to write by hand: upload the file in the Studio, or write a
+     * local path and let `npx val validate --fix` upload it and rewrite the
+     * `path` to the ref below.
+     *
+     * @example
+     * const schema = s.file({ accept: "application/pdf" }).remote();
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
+     */
     remote(): FileSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The second argument carries the `path` of the field being validated, for
+     * when the message needs to say where the problem is.
+     *
+     * @example
+     * const schema = s.file().validate((val) =>
+     *   val.path.endsWith(".pdf") ? false : "Must be a PDF",
+     * );
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.pdf",
+     *   mimeType: "application/pdf",
+     * });
+     */
     validate(validationFunction: CustomValidateFunction<Src>): FileSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     /**
@@ -57,12 +120,26 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.file().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   { path: "/public/val/example.pdf", mimeType: "application/pdf" },
+     * ]);
      */
     render(input: FieldRender): FileSchema<Src>;
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.file().preview(({ val }) => ({ title: val.path })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   { path: "/public/val/example.pdf", mimeType: "application/pdf" },
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): FileSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

package/dist/declarations/src/schema/image.d.ts

@@ -82,8 +82,82 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     private readonly renderInput;
     private readonly previewInput;
     constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s
+     *   .image()
+     *   .describe("Shown at the top of the page, 16:9 works best");
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.png",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/png",
+     * });
+     */
     describe(description: string | null): ImageSchema<Src>;
+    /**
+     * Store the image on Val's remote content host instead of in your repository.
+     *
+     * The bytes still go into the patch store when the image is uploaded — the
+     * push to the remote host happens at publish. What changes is where the
+     * published image lives: `path` becomes a remote URL rather than a path
+     * under `/public`, so the repository does not grow with every upload.
+     *
+     * The `path` of a remote image is a URL on the content host, and it is not
+     * something to write by hand: upload the image in the Studio, or write a
+     * local path and let `npx val validate --fix` upload it and rewrite the
+     * `path` to the ref below.
+     *
+     * @example
+     * const schema = s
+     *   .image({ accept: "image/webp", directory: "/public/val/images" })
+     *   .remote();
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/example.webp",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/webp",
+     * });
+     */
     remote(): ImageSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * The second argument carries the `path` of the field being validated, for
+     * when the message needs to say where the problem is.
+     *
+     * @example
+     * const schema = s.image().validate((val) =>
+     *   val.alt ? false : "Every image needs alt text",
+     * );
+     * export default c.define("/example.val.ts", schema, {
+     *   path: "/public/val/example.png",
+     *   width: 100,
+     *   height: 100,
+     *   mimeType: "image/png",
+     *   alt: "An example",
+     * });
+     */
     validate(validationFunction: CustomValidateFunction<Src>): ImageSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     /**
@@ -102,12 +176,40 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.image().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   {
+     *     path: "/public/val/example.png",
+     *     width: 100,
+     *     height: 100,
+     *     mimeType: "image/png",
+     *   },
+     * ]);
      */
     render(input: FieldRender): ImageSchema<Src>;
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.image().preview(({ val }) => ({
+     *     title: val.alt ?? "Image",
+     *     image: val,
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   {
+     *     path: "/public/val/example.png",
+     *     width: 100,
+     *     height: 100,
+     *     mimeType: "image/png",
+     *     alt: "An example",
+     *   },
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): ImageSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

package/dist/declarations/src/schema/index.d.ts

@@ -11,7 +11,8 @@ import { SerializedObjectSchema } from "./object.js";
 import { SerializedRecordSchema } from "./record.js";
 import { SerializedRichTextSchema } from "./richtext.js";
 import { RawString, SerializedStringSchema } from "./string.js";
-import { SerializedUnionSchema } from "./union.js";
+import { SerializedDiscriminatedUnionSchema } from "./discriminatedUnion.js";
+import { SerializedEnumSchema } from "./enum.js";
 import { SerializedCodeSchema } from "./code.js";
 import { SerializedColorSchema } from "./color.js";
 import { SerializedDateSchema } from "./date.js";
@@ -22,7 +23,7 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 import { FileSource } from "../source/media.js";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext.js";
 import { ReifiedPreview, PreviewScope, PreviewItem } from "../preview.js";
-export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedSettingsSchema | SerializedImageSchema;
+export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedSettingsSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
     message: string;
@@ -92,6 +93,25 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * For example, if you have an object schema, you must assert each key / value pair manually.
      */
     protected abstract executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    /**
+     * Allow `null` as a value for this field.
+     *
+     * The editor gets a way to clear the field, and the type of the source
+     * widens to include `null` — so consuming code has to handle it.
+     *
+     * Declare `.validate(...)` AFTER `.nullable()`: on most schema types a
+     * validator added before it is not carried over.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string(),
+     *   subtitle: s.string().nullable(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   title: "Hello",
+     *   subtitle: null,
+     * });
+     */
     abstract nullable(): Schema<Src | null>;
     /**
      * Mark this field as read-only in the Val editor.
@@ -102,6 +122,16 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * The flag defaults to `true`, so `.readonly()` and `.readonly(true)` are the
      * same thing. `.readonly(false)` leaves the field editable, which is what a
      * schema is anyway - pass it when the decision comes from a variable.
+     *
+     * @example
+     * const schema = s.object({
+     *   id: s.string().readonly(),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   id: "generated-by-the-build",
+     *   title: "Hello",
+     * });
      */
     abstract readonly(isReadonly?: boolean): Schema<Src>;
     /**
@@ -113,6 +143,16 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * The flag defaults to `true`, so `.hidden()` and `.hidden(true)` are the
      * same thing. `.hidden(false)` leaves the field visible, which is what a
      * schema is anyway - pass it when the decision comes from a variable.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string(),
+     *   internalNotes: s.string().hidden(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   title: "Hello",
+     *   internalNotes: "Not shown in the editor",
+     * });
      */
     abstract hidden(isHidden?: boolean): Schema<Src>;
     protected abstract executeSerialize(): SerializedSchema;

package/dist/declarations/src/schema/keyOf.d.ts

@@ -42,7 +42,45 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     private readonly renderInput;
     private readonly previewInput;
     constructor(schema?: SerializedRefSchema | undefined, sourcePath?: SourcePath | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.keyOf(authorsVal).describe("Who wrote this post");
+     * export default c.define("/example.val.ts", schema, "ada");
+     */
     describe(description: string | null): KeyOfSchema<Sel, Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s
+     *   .keyOf(authorsVal)
+     *   .validate((val) =>
+     *     val === "placeholder" ? "Pick a real author" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, "ada");
+     */
     validate(validationFunction: (src: Src) => false | string): KeyOfSchema<Sel, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -56,12 +94,24 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.array(s.keyOf(authorsVal).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["ada"]);
      */
     render(input: FieldRender): KeyOfSchema<Sel, Src>;
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.array(
+     *   s.keyOf(authorsVal).preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["ada"]);
      */
     preview(select: ItemPreviewInput<Src>): KeyOfSchema<Sel, Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

package/dist/declarations/src/schema/literal.d.ts

@@ -26,7 +26,43 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     private readonly renderInput;
     private readonly previewInput;
     constructor(value: string, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s
+     *   .literal("hero")
+     *   .describe("The block type — it identifies the variant");
+     * export default c.define("/example.val.ts", schema, "hero");
+     */
     describe(description: string | null): LiteralSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.literal("hero").validate((val) =>
+     *   val === "hero" ? false : "Unknown block type",
+     * );
+     * export default c.define("/example.val.ts", schema, "hero");
+     */
     validate(validationFunction: (src: Src) => false | string): LiteralSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -40,12 +76,22 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.literal("hero").render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["hero"]);
      */
     render(input: FieldRender): LiteralSchema<Src>;
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.literal("hero").preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["hero"]);
      */
     preview(select: ItemPreviewInput<Src>): LiteralSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

package/dist/declarations/src/schema/number.d.ts

@@ -30,14 +30,62 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     private readonly renderInput;
     private readonly previewInput;
     constructor(options?: NumberOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s.number().describe("How many columns the grid uses");
+     * export default c.define("/example.val.ts", schema, 3);
+     */
     describe(description: string | null): NumberSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.number().validate((val) =>
+     *   Number.isInteger(val) ? false : "Must be a whole number",
+     * );
+     * export default c.define("/example.val.ts", schema, 3);
+     */
     validate(validationFunction: (src: Src) => false | string): NumberSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): NumberSchema<Src | null>;
     readonly(isReadonly?: boolean): NumberSchema<Src>;
     hidden(isHidden?: boolean): NumberSchema<Src>;
+    /**
+     * Validate that the number is at most `max` (inclusive).
+     *
+     * @example
+     * const schema = s.number().max(4);
+     * export default c.define("/example.val.ts", schema, 3);
+     */
     max(max: number): NumberSchema<Src>;
+    /**
+     * Validate that the number is at least `min` (inclusive).
+     *
+     * @example
+     * const schema = s.number().min(1).max(4);
+     * export default c.define("/example.val.ts", schema, 3);
+     */
     min(min: number): NumberSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
@@ -46,12 +94,22 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.number().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [1, 2]);
      */
     render(input: FieldRender): NumberSchema<Src>;
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.number().preview(({ val }) => ({ title: String(val) })),
+     * );
+     * export default c.define("/example.val.ts", schema, [1, 2]);
      */
     preview(select: ItemPreviewInput<Src>): NumberSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

package/dist/declarations/src/schema/object.d.ts

@@ -50,7 +50,52 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     private readonly renderInput;
     private readonly previewInput;
     constructor(items: Props, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s
+     *   .object({ street: s.string(), city: s.string() })
+     *   .describe("Where the office is — shown on the contact page");
+     * export default c.define("/example.val.ts", schema, {
+     *   street: "Torggata 1",
+     *   city: "Oslo",
+     * });
+     */
     describe(description: string | null): ObjectSchema<Props, Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * An object validator is the place for a rule that spans FIELDS — one field
+     * validated on its own belongs on that field's schema, where the error lands
+     * on the field itself.
+     *
+     * @example
+     * const schema = s
+     *   .object({ from: s.number(), to: s.number() })
+     *   .validate((val) =>
+     *     val.from <= val.to ? false : "'from' must not be after 'to'",
+     *   );
+     * export default c.define("/example.val.ts", schema, { from: 1, to: 4 });
+     */
     validate(validationFunction: (src: Src) => false | string): ObjectSchema<Props, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -64,12 +109,30 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * // A page builder: each row edits the object in place, instead of
+     * // navigating to it.
+     * const block = s
+     *   .object({ heading: s.string(), body: s.string() })
+     *   .render({ as: "inline" });
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { heading: "Hello", body: "World" },
+     * ]);
      */
     render(input: FieldRender): ObjectSchema<Props, Src>;
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field
      * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.array(author), [
+     *   { name: "Ada", role: "Engineer" },
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): ObjectSchema<Props, Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;