@valbuild/core 0.125.0 → 0.126.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # @valbuild/core
 
+## 0.126.0
+
+### Minor Changes
+
+- [#652](https://github.com/valbuild/val/pull/652) [`f2fe70d`](https://github.com/valbuild/val/commit/f2fe70dab2b65000dfaf289f09c70b4a8291467a) Thanks [@freekh](https://github.com/freekh)! - `s.union` is now `s.discriminatedUnion` and `s.enum`.
+
+  `s.union` did two unrelated jobs and worked out which one you meant from its
+  first argument: a string key meant a tagged union of objects, literal schemas
+  meant a set of allowed strings. Those are now two schemas with two names.
+
+  ```ts
+  // A fixed set of strings — presents as a dropdown
+  s.enum("primary", "secondary", "ghost"); // Schema<"primary" | "secondary" | "ghost">
+
+  // One of several object shapes, told apart by a tag field
+  s.discriminatedUnion(
+    "type",
+    s.object({ type: s.literal("hero"), heading: s.string() }),
+    s.object({ type: s.literal("quote"), text: s.string() }),
+  );
+  ```
+
+  `s.enum` takes the strings directly, so the `s.literal(...)` wrapper is gone.
+
+  **`s.union` still works** — it is deprecated, and it builds exactly the schema
+  above, so nothing has to change today:
+
+  ```ts
+  s.union(s.literal("one"), s.literal("two")); // → s.enum("one", "two")
+  s.union("type", pageA, pageB); // → s.discriminatedUnion("type", pageA, pageB)
+  ```
+
+  The two are different kinds of node, and that is the reason for the split. A
+  discriminated union is a container: the selected variant's fields are the fields
+  being edited, and everything that walks a schema descends through it. An enum is
+  a leaf — a string with a closed domain — so nothing recurses into it. Told apart
+  only by the shape of `key`, every consumer had to re-derive which one it was
+  holding; each now has its own serialized type (`"discriminated-union"` and
+  `"enum"`) and Val Studio has a field per kind rather than one field that
+  branches.
+
+  Two behaviour changes fall out of the split, both of them fixes:
+
+  - A value that is not a string at all now fails an enum's validation with a
+    type error. `s.union` of literals only ever checked the value against its
+    literals when the value WAS a string, so a number or an object where an enum
+    was declared validated clean.
+  - An enum field now shows its validation errors in Val Studio where the field
+    is opened on its own — the module editor and the canvas's fields column — and
+    gets the compact error layout inside an inline list row. It is a leaf now, so
+    it goes through the same error rendering as every other leaf field; the string
+    union bypassed it and showed nothing in those places.
+
+  Several latent crashes in the old `s.union` are fixed on the way past, all of
+  them cases where it threw a `TypeError` instead of reporting:
+
+  - A required discriminated union holding `null` now reports a type error rather
+    than throwing, and resolving a path underneath a nullable one that is `null`
+    gives the error the API promises instead of a crash.
+  - `s.literal("")` is a legal discriminator tag, and `s.enum("")` a legal value.
+    Both used to be treated as absent by a truthiness check — in path resolution,
+    in stega encoding, and in the message that lists a union's valid tags. The
+    editor's dropdowns handle them too: an empty value is reserved by the select
+    component and had to be mapped around.
+  - A variant that omits the discriminator entirely is now reported as the schema
+    error it is, instead of throwing while the check looked for it.
+  - An enum's value is now indexed for search, like every other string leaf. The
+    old string union was never indexed at all, so searching for one of its values
+    could not find the field.
+  - A nullable discriminated union set to `null` no longer renders a spinner that
+    never resolves.
+
+  `s.discriminatedUnion` also requires at least one variant, as `s.enum` requires
+  at least one value: a union with nothing to select is not a thing to write, and
+  everything downstream reads the first variant where it needs any.
+
+  If you read serialized schemas yourself, that is the breaking part: `type` is no
+  longer `"union"`, an enum carries `values: string[]` instead of a `key` plus
+  `items` of literal schemas, and `UnionSchema` is no longer a class.
+  `SerializedUnionSchema`, `SerializedStringUnionSchema`,
+  `SerializedObjectUnionSchema` and `UnionSchema` remain as deprecated type
+  aliases.
+
+### Patch Changes
+
+- [#661](https://github.com/valbuild/val/pull/661) [`171208a`](https://github.com/valbuild/val/commit/171208a20177e68ed5a8b1a6fdaabfe893a6aa5f) Thanks [@freekh](https://github.com/freekh)! - Every schema method now has a worked `@example` in its JSDoc, so hovering it in
+  your editor shows what to write.
+
+  That covers the whole builder surface — `.describe()`, `.validate()`,
+  `.nullable()`, `.readonly()`, `.hidden()`, `.preview()`, `.render()`, and the
+  per-type methods such as `.minLength()`, `.regexp()`, `.raw()`, `.multiline()`,
+  `.from()` / `.to()`, `.remote()`, `.jsonValues()` and `.external()` — as well as
+  `c.define()`, `c.json()`, `c.external()` and the `val` helpers (`val.attrs`,
+  `val.raw`, `val.unstable_getPath` and friends).
+
+  One of the examples corrected a real trap: a custom validator returns
+  `false | string`, so the natural-looking
+
+  ```ts
+  s.string().validate((val) => val.trim() === val || "No surrounding spaces");
+  ```
+
+  does not type check — `||` yields `true`, and `true` is not one of the two
+  answers. Write it as a ternary instead:
+
+  ```ts
+  s.string().validate((val) =>
+    val.trim() === val ? false : "No surrounding spaces",
+  );
+  ```
+
+  The examples are checked in CI, not just written: one test asks the TypeScript
+  checker for the doc each method actually resolves to and fails if it has no
+  `@example`, and another compiles every example it finds.
+
 ## 0.125.0
 
 ### Minor Changes

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

@@ -63,7 +63,9 @@ export { type SerializedDateTimeSchema, DateTimeSchema, } from "./schema/datetim
 export { type SerializedKeyOfSchema, KeyOfSchema } from "./schema/keyOf.js";
 export { type SerializedRouteSchema, RouteSchema } from "./schema/route.js";
 export { type SerializedRichTextSchema, RichTextSchema, } from "./schema/richtext.js";
-export { type SerializedUnionSchema, UnionSchema, type SerializedStringUnionSchema, type SerializedObjectUnionSchema, } from "./schema/union.js";
+export { type SerializedDiscriminatedUnionSchema, type DiscriminatedUnionSourceOf, DiscriminatedUnionSchema, } from "./schema/discriminatedUnion.js";
+export { type SerializedEnumSchema, EnumSchema } from "./schema/enum.js";
+export { type SerializedUnionSchema, type UnionSchema, type SerializedStringUnionSchema, type SerializedObjectUnionSchema, } from "./schema/union.js";
 export { type SerializedLiteralSchema, LiteralSchema } from "./schema/literal.js";
 export { deserializeSchema } from "./schema/deserialize.js";
 export { type PreviewItem, type ItemPreviewInput, type RecordPreview, type ArrayPreview, type ReifiedPreview, type PreviewScope, previewScope, } from "./preview.js";

package/dist/declarations/src/initSchema.d.ts

@@ -4,6 +4,8 @@ import { object } from "./schema/object.js";
 import { string } from "./schema/string.js";
 import { boolean } from "./schema/boolean.js";
 import { union } from "./schema/union.js";
+import { discriminatedUnion } from "./schema/discriminatedUnion.js";
+import { enumSchema } from "./schema/enum.js";
 import { richtext } from "./schema/richtext.js";
 import { image } from "./schema/image.js";
 import { literal } from "./schema/literal.js";
@@ -67,32 +69,58 @@ export type InitSchema = {
      */
     readonly number: typeof number;
     /**
-     * Define a union.
+     * Define one of several object shapes, told apart by a tag field.
      *
-     * @example // union of string literals
-     * const schema = s.union(s.literal("test"), s.literal("test2"));
-     * export default c.define("/example.val.ts", schema, "test");
+     * The first argument names the field that carries the tag; every object must
+     * set it to a distinct `s.literal(...)`. The editor shows a dropdown of the
+     * tags and the fields of whichever one is selected.
      *
-     * @example // union of string literals
-     * const schema = s.union("type", s.object({
-     *   type: s.literal("test"),
-     *   value: s.string()
-     * }), s.object({
-     *   type: s.literal("test2"),
-     *   value: s.string()
-     * }));
+     * @example
+     * const schema = s.discriminatedUnion("type",
+     *   s.object({ type: s.literal("text"), value: s.string() }),
+     *   s.object({ type: s.literal("image"), value: s.image() }),
+     * );
      * export default c.define("/example.val.ts", schema, {
-     *   type: "test",
+     *   type: "text",
      *   value: "test"
      * });
      *
      */
+    readonly discriminatedUnion: typeof discriminatedUnion;
+    /**
+     * Define a string that must be one of a fixed set of values.
+     *
+     * The editor shows a dropdown of the values, in the order they are given.
+     *
+     * @example
+     * const schema = s.enum("primary", "secondary", "ghost");
+     * export default c.define("/example.val.ts", schema, "primary");
+     *
+     */
+    readonly enum: typeof enumSchema;
+    /**
+     * Define a union.
+     *
+     * @deprecated Use `s.discriminatedUnion` for a tagged union of objects, or
+     * `s.enum` for one of a fixed set of strings.
+     *
+     * @example // was: a union of string literals
+     * const schema = s.enum("test", "test2");
+     *
+     * @example // was: a tagged union of objects
+     * const schema = s.discriminatedUnion("type",
+     *   s.object({ type: s.literal("test"), value: s.string() }),
+     *   s.object({ type: s.literal("test2"), value: s.string() }),
+     * );
+     *
+     */
     readonly union: typeof union;
     /**
      * Define a rich text.
      *
      * @example
-     * const schema = s.richtext();
+     * // Every tag and style is off until the options ask for it.
+     * const schema = s.richtext({ h1: true, bold: true });
      * export default c.define("/example.val.ts", schema, [
      *   { tag: "h1", children: ["Title 1"] },
      * ]);
@@ -119,6 +147,7 @@ export type InitSchema = {
      *
      * @example
      * // Backed by a gallery: width, height and mimeType live there.
+     * import galleryVal from "./gallery.val"; // an s.images() module
      * const schema = s.image(galleryVal);
      * export default c.define("/example.val.ts", schema, {
      *   path: "/public/val/example.png",
@@ -346,7 +375,9 @@ export declare function initSchema(): {
         max?: number;
         min?: number;
     }) => import("./index.js").NumberSchema<number>;
-    union: <Key extends string | import("./schema/index.js").Schema<string>, T extends import("./schema/index.js").Schema<Key extends string ? import("./source/index.js").SourceObject & { [k in Key]: string; } : Key extends import("./schema/index.js").Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => import("./index.js").UnionSchema<Key, T, T extends import("./schema/index.js").Schema<infer S extends import("./selector/index.js").SelectorSource>[] ? S extends import("./selector/index.js").SelectorSource ? S | (Key extends import("./schema/index.js").Schema<infer K extends import("./selector/index.js").SelectorSource> ? K : never) : never : never>;
+    discriminatedUnion: <Key extends string, T extends import("./schema/discriminatedUnion.js").DiscriminatedUnionItems<Key>>(key: Key, ...objects: T) => import("./index.js").DiscriminatedUnionSchema<Key, T, import("./index.js").DiscriminatedUnionSourceOf<Key, T>>;
+    enum: <T extends string>(values_0: T, ...values: T[]) => import("./index.js").EnumSchema<T>;
+    union: typeof union;
     richtext: <O extends import("./index.js").RichTextOptions>(options?: O) => import("./index.js").RichTextSchema<O, import("./index.js").RichTextSource<O>>;
     image: typeof image;
     literal: <T extends string>(value: T) => import("./index.js").LiteralSchema<T>;

package/dist/declarations/src/initVal.d.ts

@@ -4,11 +4,71 @@ import { getValPath as getPath } from "./val/index.js";
 import { json } from "./source/json.js";
 import { external } from "./source/external.js";
 export type ContentConstructor = {
+    /**
+     * Define a content module: a schema, and source that matches it.
+     *
+     * The first argument is the module's own file path, starting at the root of
+     * the project. It has to match the file the call is written in - that is how
+     * the Studio, validation and patching find the module again - so a
+     * `c.define` is always the default export of one `*.val.ts` file.
+     *
+     * @example
+     * const schema = s.object({ title: s.string() });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     * });
+     */
     define: typeof define;
+    /**
+     * Put one entry of a `.jsonValues()` record in its own `*.val.json` file,
+     * loaded lazily.
+     *
+     * What is written in the module is the `import()` thunk, not the content: the
+     * `.val.ts` stays small, and the runtime, the Studio and validation each work
+     * an entry at a time. That is what lets a record or a router hold many
+     * thousands of entries.
+     *
+     * Only for the entries of a record that said `.jsonValues()`.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .router(nextAppRouter, s.object({ title: s.string() }))
+     *   .jsonValues();
+     * export default c.define("/app/support/[slug]/page.val.ts", schema, {
+     *   "/support/faq": c.json(() => import("./content/faq.val.json")),
+     * });
+     */
     json: typeof json;
+    /**
+     * The source of a record whose entries live behind an adapter - a database,
+     * an HTTP API, a bucket - instead of in the module.
+     *
+     * It takes no arguments, and there is nothing to fill in: it says only that
+     * the entries are somewhere else. WHICH adapter is the schema's business
+     * (`.external("posts")`), and the binding is registered where the app is set
+     * up.
+     *
+     * @example
+     * const schema = s.record(s.object({ title: s.string() })).external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
+     */
     external: typeof external;
 };
 export type ValConstructor = {
+    /**
+     * The source path of a value inside a module, or `undefined` for something
+     * that did not come from Val.
+     *
+     * A path is what every Val API addresses content by, so this is the way from
+     * a value you are holding back to the thing the Studio, a patch or a
+     * validation error names. Unstable: the shape of a path is not part of the
+     * public API yet.
+     *
+     * @example
+     * import pageVal from "./page.val";
+     * const path = val.unstable_getPath(pageVal); // "/page.val.ts"
+     */
     unstable_getPath: typeof getPath;
 };
 export type ConfigDirectory = `/public` | `/public/${string}`;
@@ -39,9 +99,57 @@ export type ValConfig = {
     };
 };
 export type InitVal = {
+    /**
+     * The content constructor: `c.define` for a module, `c.json` and
+     * `c.external` for entries that live outside it.
+     *
+     * @example
+     * const schema = s.object({ title: s.string() });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     * });
+     */
     c: ContentConstructor;
+    /**
+     * Helpers for working with content your app is already holding, rather than
+     * for declaring it.
+     *
+     * `@valbuild/next` and `@valbuild/tanstack` add to this: `val.attrs` for
+     * visual editing, `val.raw` to strip the stega encoding off a string.
+     *
+     * @example
+     * import pageVal from "./page.val";
+     * const path = val.unstable_getPath(pageVal);
+     */
     val: ValConstructor;
+    /**
+     * The schema constructor: one method per type of content Val can hold.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string().describe("Shown in the browser tab"),
+     *   image: s.image().nullable(),
+     * });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     *   image: null,
+     * });
+     */
     s: InitSchema;
+    /**
+     * The config this `initVal` was called with, as the rest of Val reads it.
+     *
+     * Exported from `val.config.ts` so that the Val API route and the Studio get
+     * the same object the content modules were built with.
+     *
+     * @example
+     * import { initVal } from "@valbuild/core";
+     * const { s, c, val, config } = initVal({
+     *   project: "myorg/myproject",
+     *   files: { directory: "/public/val" },
+     * });
+     * export { s, c, val, config };
+     */
     config: ValConfig;
 };
 export declare const initVal: (config?: ValConfig) => InitVal;

package/dist/declarations/src/render.d.ts

@@ -59,10 +59,11 @@ export type FieldRender = InlineRender;
  * question, and a disagreement between them is a row you can edit in place but
  * that "add" navigates away from.
  *
- * A tagged union counts as inline when the union itself declares it OR when
- * ANY of its variants does. A page-builder list is `s.array(s.union("type",
- * block, block, ...))` and the natural place to write the render is on the
- * blocks, one per block type — the union is a dispatch, not something the
+ * A discriminated union counts as inline when the union itself declares it OR
+ * when ANY of its variants does. A page-builder list is
+ * `s.array(s.discriminatedUnion("type", block, block, ...))` and the natural
+ * place to write the render is on the blocks, one per block type — the union
+ * is a dispatch, not something the
  * author thinks of as the field. `some` rather than `every` because the row
  * draws the union's own editor (the tag selector plus the matched variant's
  * fields), which handles every variant either way: with `every`, adding one

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

@@ -38,7 +38,47 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     private readonly previewInput;
     private readonly renderInput;
     constructor(item: T, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null, renderInput?: FieldRender | 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
+     *   .array(s.string())
+     *   .describe("Bullet points shown under the heading");
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
+     */
     describe(description: string | null): ArraySchema<T, 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 function is given the whole array. To validate one item, put a
+     * `.validate(...)` on the ITEM schema instead — that reports the error on
+     * the item's own row.
+     *
+     * @example
+     * const schema = s.array(s.string()).validate((val) =>
+     *   val.length <= 3 ? false : "At most 3 items",
+     * );
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
+     */
     validate(validationFunction: (src: Src) => false | string): ArraySchema<T, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -55,6 +95,25 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
      * is the item of another container, in search, in references. What its rows
      * show is the ITEM schema's `preview`, not this. Never how the field is
      * edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * // The preview of the ARRAY, for where it is an item of something else.
+     * // What its own rows show is the ITEM schema's preview — see below.
+     * const tags = s.array(s.string()).preview(({ val }) => ({
+     *   title: `${val.length} tags`,
+     * }));
+     * export default c.define("/example.val.ts", s.record(tags), {
+     *   "a-post": ["news", "release"],
+     * });
+     *
+     * @example
+     * // Rows of an array come from the ITEM's preview, not the array's:
+     * 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>): ArraySchema<T, Src>;
     /**
@@ -63,6 +122,12 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.record(s.array(s.string()).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, {
+     *   "a-post": ["news", "release"],
+     * });
      */
     render(input: FieldRender): ArraySchema<T, Src>;
 }

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

@@ -24,7 +24,41 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
     private readonly renderInput;
     private readonly previewInput;
     constructor(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.boolean().describe("Show this item in the main menu");
+     * export default c.define("/example.val.ts", schema, true);
+     */
     describe(description: string | null): BooleanSchema<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.boolean().validate((val) =>
+     *   val === true ? false : "This has to be on for now",
+     * );
+     * export default c.define("/example.val.ts", schema, true);
+     */
     validate(validationFunction: (src: Src) => false | string): BooleanSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -38,12 +72,22 @@ export declare class BooleanSchema<Src extends boolean | 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.boolean().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [true, false]);
      */
     render(input: FieldRender): BooleanSchema<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.boolean().preview(({ val }) => ({ title: val ? "On" : "Off" })),
+     * );
+     * export default c.define("/example.val.ts", schema, [true, false]);
      */
     preview(select: ItemPreviewInput<Src>): BooleanSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -55,7 +55,52 @@ export declare class CodeSchema<Src extends string | null> extends Schema<Src> {
     private readonly renderInput;
     private readonly previewInput;
     constructor(options?: CodeOptions | 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
+     *   .code({ language: "css" })
+     *   .describe("Injected into the page head — keep it small");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   ".hero { color: red; }",
+     * );
+     */
     describe(description: string | null): CodeSchema<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.code({ language: "json" }).validate((val) => {
+     *   try {
+     *     JSON.parse(val);
+     *     return false;
+     *   } catch {
+     *     return "Must be valid JSON";
+     *   }
+     * });
+     * export default c.define("/example.val.ts", schema, '{ "a": 1 }');
+     */
     validate(validationFunction: (src: Src) => false | string): CodeSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -69,12 +114,30 @@ export declare class CodeSchema<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.code({ language: "css" }).render({ as: "inline" }),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   ".hero { color: red; }",
+     * ]);
      */
     render(input: FieldRender): CodeSchema<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.code({ language: "css" }).preview(({ val }) => ({
+     *     title: val.split("\n")[0],
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   ".hero { color: red; }",
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): CodeSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;