@valbuild/core 0.125.0 → 0.127.0

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

@@ -108,9 +108,81 @@ RO extends boolean = false> extends Schema<Src> {
      * sites.
      */
     externalLabel?: string | 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
+     *   .record(s.string())
+     *   .describe("Button labels, keyed by locale");
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
+     */
     describe(description: string | null): RecordSchema<T, K, 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 record. To validate one entry, put a
+     * `.validate(...)` on the ITEM schema instead — that reports the error on
+     * the entry's own row, and on a `.jsonValues()` record it does not force
+     * every entry to be loaded.
+     *
+     * @example
+     * const schema = s.record(s.string()).validate((val) =>
+     *   "en" in val ? false : "There has to be an 'en' entry",
+     * );
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
+     */
     validate(validationFunction: (src: Src) => false | string): RecordSchema<T, K, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    /**
+     * The check that a record with a DECLARED key set holds every one of them.
+     *
+     * `s.record(s.locale(), item)` has one entry per language and
+     * `s.record(s.union(s.literal("a"), s.literal("b")), item)` has both — the
+     * keys are part of the schema either way, so a missing one is a hole in the
+     * content rather than content nobody has written yet. TypeScript already
+     * demanded both keys of the second; this is the validator catching up, which
+     * is why the two now behave the same.
+     *
+     * Deferred to `resolveSchemaSourceFixes` even for the literal case, where the
+     * keys are known right here: a locale record's keys are in another file, and
+     * one code path for both is one message, one fix and one thing to be wrong.
+     */
+    private getDeclaredKeysValidation;
+    /**
+     * The key set this record's schema declares, computed once.
+     *
+     * `declaredKeySetOf` reads a SERIALIZED schema, and serializing the key
+     * schema walks it — twice per validate, and once per record instance, for an
+     * answer that is a property of the schema and cannot move between them. A
+     * schema is built once and validated against many times, so the walk happens
+     * on the first question and not on any after it.
+     */
+    private declaredKeys;
+    private declaredKeySet;
+    protected opensLocaleScope(): "field" | "key" | null;
+    protected localeScopeChildren(): {
+        key: string;
+        schema: Schema<SelectorSource>;
+    }[];
     private isRemoteUrl;
     /** Marks the validation errors reported at `path` as key errors (in place). */
     private markKeyErrorsAtPath;
@@ -128,10 +200,55 @@ RO extends boolean = false> extends Schema<Src> {
      * must come BEFORE `.external()`: afterwards the value is a `Schema`, and
      * there is no `.readonly()` left to call — which is the error the compiler
      * gives, and a clearer one than a runtime throw.
+     *
+     * @example
+     * const schema = s.record(s.string()).readonly();
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
      */
     readonly<B extends boolean = true>(isReadonly?: B): RecordSchema<T, K, Src, B>;
     hidden(isHidden?: boolean): RecordSchema<T, K, Src>;
+    /**
+     * Turn this record into a page router: its keys are route paths of your
+     * application, and they are validated against the router's conventions.
+     *
+     * `s.router(router, item)` builds the same thing in one call and is what
+     * most code should use — this is for adding a router to a record that
+     * already exists.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .record(s.object({ title: s.string() }))
+     *   .router(nextAppRouter);
+     * export default c.define("/app/[slug]/page.val.ts", schema, {
+     *   "/a-page-slug": { title: "First Page" },
+     * });
+     */
     router(router: ValRouter): RecordSchema<T, K, Src>;
+    /**
+     * Allow the files in this gallery to be stored on Val's remote content host
+     * instead of in your repository.
+     *
+     * For `s.images()` and `s.files()`, which are records of media. Remote is off
+     * until this is called.
+     *
+     * Each entry is then keyed by its URL on the content host rather than by a
+     * path under `/public`. That key is not something to write by hand: upload
+     * in the Studio, or add a local path and let `npx val validate --fix`
+     * upload it and rewrite the key.
+     *
+     * @example
+     * const schema = s.images({ directory: "/public/val/images" }).remote();
+     * export default c.define("/content/images.val.ts", schema, {
+     *   "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/hero.webp":
+     *     {
+     *       width: 1920,
+     *       height: 1080,
+     *       mimeType: "image/webp",
+     *       alt: "Hero image",
+     *     },
+     * });
+     */
     remote(): RecordSchema<T, K, Src>;
     /**
      * Store each entry's value in its own lazily-loaded `*.val.json` file instead
@@ -146,6 +263,20 @@ RO extends boolean = false> extends Schema<Src> {
      * nested inside an object/array/record is rejected at startup with a module
      * error, because the single-entry fetch endpoint, the Studio's content
      * substitution and content validation are all root-only.
+     *
+     * Must come BEFORE `.validate()` and `.preview()`: those are typed against
+     * the un-lazy source shape, so a validator or preview declared first cannot
+     * be carried over, and declaring one first throws rather than silently
+     * dropping it.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .router(nextAppRouter, s.object({ title: s.string(), body: s.string() }))
+     *   .jsonValues();
+     * export default c.define("/app/support/[slug]/page.val.ts", schema, {
+     *   "/support/faq": c.json(() => import("./content/faq.val.json")),
+     * });
      */
     jsonValues(): RecordSchema<T, K, JsonValuesRecordSrc<T, K>>;
     /**
@@ -166,6 +297,19 @@ RO extends boolean = false> extends Schema<Src> {
      * nested external record would leave a hole in the middle of a module's
      * source, and the Studio, patching and validation all assume a module's
      * source is complete apart from its entries.
+     *
+     * @example
+     * const schema = s.record(s.object({ title: s.string() })).external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
+     *
+     * @example
+     * // A read-only external record: `.readonly()` must come FIRST, because
+     * // afterwards there is no `.readonly()` left on the type to call.
+     * const schema = s
+     *   .record(s.object({ title: s.string() }))
+     *   .readonly()
+     *   .external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
      */
     external<L extends string>(label: L): RecordSchema<T, K, ExternalRecordSrc<SelectorOfSchema<T>, L, RO>, RO>;
     /**
@@ -197,6 +341,25 @@ RO extends boolean = false> extends Schema<Src> {
      * is the item of another container, in search, in references. What its
      * entries 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 RECORD, for where it is an item of something else.
+     * // What its own rows show is the ITEM schema's preview — see below.
+     * const labels = s.record(s.string()).preview(({ val }) => ({
+     *   title: `${Object.keys(val).length} locales`,
+     * }));
+     * export default c.define("/example.val.ts", s.array(labels), [
+     *   { en: "Read more" },
+     * ]);
+     *
+     * @example
+     * // Rows of a record come from the ITEM's preview, not the record'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.record(author), {
+     *   ada: { name: "Ada", role: "Engineer" },
+     * });
      */
     preview(select: ItemPreviewInput<Src>): RecordSchema<T, K, Src>;
     /**
@@ -205,9 +368,32 @@ RO extends boolean = false> 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.record(s.string()).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [{ en: "Read more" }]);
      */
     render(input: FieldRender): RecordSchema<T, K, Src>;
 }
-export declare function record<K extends Schema<string>, S extends Schema<SelectorSource>>(key: K, schema: S): RecordSchema<S, K, Record<SelectorOfSchema<K>, SelectorOfSchema<S>>>;
+/**
+ * The source of a record, given what its key schema says about its keys.
+ *
+ * A key schema that ENUMERATES its keys (a union of literals, or `s.locale()`)
+ * makes every one of them an entry of the record, and an entry nobody has
+ * written yet is `null` rather than absent — so the value type widens by
+ * `null`. That is the whole of option F at the type level: a half-translated
+ * record is a record with nulls in it, which is data you can count, filter and
+ * see in a diff, rather than keys that are simply not there.
+ *
+ * For a union of literals TypeScript already required every key, since
+ * `SelectorOfSchema<K>` is the literal union itself. `s.locale()` is a flavoured
+ * string, so it requires nothing here and the requirement is the validator's —
+ * deliberately: which languages exist is in the settings module, where the
+ * project can change it without a deploy.
+ */
+export type RecordSrcOf<K extends Schema<string>, S extends Schema<SelectorSource>> = K extends {
+    __declaresRecordKeys: true;
+} ? Record<SelectorOfSchema<K>, SelectorOfSchema<S> | null> : Record<SelectorOfSchema<K>, SelectorOfSchema<S>>;
+export declare function record<K extends Schema<string>, S extends Schema<SelectorSource>>(key: K, schema: S): RecordSchema<S, K, RecordSrcOf<K, S>>;
 export declare function record<S extends Schema<SelectorSource>>(schema: S): RecordSchema<S, Schema<string>, Record<string, SelectorOfSchema<S>>>;
 export {};

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

@@ -31,9 +31,71 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     private readonly renderInput;
     private readonly previewInput;
     constructor(options: O & ValidationOptions, 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.richtext().describe("The body of the article");
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
     describe(description: string | null): RichTextSchema<O, Src>;
+    /**
+     * Validate that the rich text holds at most `max` characters.
+     *
+     * Counted over the TEXT, not the markup: tags, attributes and the structure
+     * of the document do not add to it.
+     *
+     * @example
+     * const schema = s.richtext().maxLength(280);
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
     maxLength(max: number): RichTextSchema<O, Src>;
+    /**
+     * Validate that the rich text holds at least `min` characters.
+     *
+     * Counted over the TEXT, not the markup: tags, attributes and the structure
+     * of the document do not add to it.
+     *
+     * @example
+     * const schema = s.richtext().minLength(20).maxLength(280);
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Long enough to clear the minimum length."] },
+     * ]);
+     */
     minLength(min: number): RichTextSchema<O, 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.richtext().validate((val) =>
+     *   val.length > 0 ? false : "Write something",
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
     validate(validationFunction: (src: Src) => false | string): RichTextSchema<O, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     private internalValidate;
@@ -49,12 +111,28 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.richtext().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   [{ tag: "p", children: ["Hello"] }],
+     * ]);
      */
     render(input: FieldRender): RichTextSchema<O, 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.richtext().preview(({ val }) => ({
+     *     title: val.length > 0 ? "Rich text" : "Empty",
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   [{ tag: "p", children: ["Hello"] }],
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): RichTextSchema<O, Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -40,6 +40,20 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     private readonly renderInput;
     private readonly previewInput;
     constructor(options?: RouteOptions | undefined, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], 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.route().describe("Where the button goes");
+     * export default c.define("/example.val.ts", schema, "/a-page-slug");
+     */
     describe(description: string | null): RouteSchema<Src>;
     /**
      * Specify a pattern for which routes are allowed.
@@ -67,6 +81,26 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
      * s.route().include(/^\/api\//).exclude(/^\/api\/internal\//)  // API routes except internal
      */
     exclude(pattern: RegExp): RouteSchema<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.route().validate((val) =>
+     *   val.endsWith("/") ? "Leave off the trailing slash" : false,
+     * );
+     * export default c.define("/example.val.ts", schema, "/a-page-slug");
+     */
     validate(validationFunction: (src: Src) => false | string): RouteSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -80,12 +114,22 @@ export declare class RouteSchema<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.route().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["/a-page-slug"]);
      */
     render(input: FieldRender): RouteSchema<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.route().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["/a-page-slug"]);
      */
     preview(select: ItemPreviewInput<Src>): RouteSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -38,6 +38,19 @@ export type SerializedSettingsSchema = {
     readonly?: boolean;
     hidden?: boolean;
     description?: string;
+    /**
+     * Which of Val's sections this is, where it is one.
+     *
+     * The name rather than the rule itself, because the rule is a closure and a
+     * closure does not survive JSON. Val owns both ends — every section's rules
+     * are in {@link sectionValidators} in this file — so the name is enough for
+     * {@link deserializeSchema} to put the same rules back, and a Studio that
+     * does not recognise the name simply runs none (see `sectionValidate`).
+     *
+     * Absent on the settings module itself, which is a bag of sections and has no
+     * rules of its own.
+     */
+    section?: string;
 };
 /**
  * An object whose keys are all optional: absent means unset.
@@ -58,7 +71,47 @@ export declare class SettingsSchema<Src extends {
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(items: Record<string, Schema<SelectorSource>>, opt?: boolean, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    /**
+     * Which section this is, where Val has rules about it beyond its keys.
+     *
+     * Not the `validate` the class deliberately does not offer: that one is the
+     * schema author's, and `s.settings()` takes no arguments to declare it
+     * with. This names a rule Val states about a shape Val owns — no language
+     * declared twice in `locales.available` is true of every project, and
+     * there is nowhere else it can be said. A single value's rules stay on its
+     * own schema; this is for the ones that need to see more than one value,
+     * or to report on a row of a list.
+     *
+     * A NAME rather than the function, so it survives serialization: the schema
+     * reaches the Studio's validation worker as JSON, and a closure would be
+     * dropped on the way — which is how these rules once went missing there.
+     */
+    private readonly section?;
+    constructor(items: Record<string, Schema<SelectorSource>>, opt?: boolean, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, 
+    /**
+     * Which section this is, where Val has rules about it beyond its keys.
+     *
+     * Not the `validate` the class deliberately does not offer: that one is the
+     * schema author's, and `s.settings()` takes no arguments to declare it
+     * with. This names a rule Val states about a shape Val owns — no language
+     * declared twice in `locales.available` is true of every project, and
+     * there is nowhere else it can be said. A single value's rules stay on its
+     * own schema; this is for the ones that need to see more than one value,
+     * or to report on a row of a list.
+     *
+     * A NAME rather than the function, so it survives serialization: the schema
+     * reaches the Studio's validation worker as JSON, and a closure would be
+     * dropped on the way — which is how these rules once went missing there.
+     */
+    section?: string | undefined);
+    /**
+     * This section's rules, or `undefined` where there are none to run.
+     *
+     * A name this Val does not know means a schema written by a newer one. Its
+     * per-field validation still runs; only the section's own rule is missed,
+     * which is the mild half of the failure and better than refusing the schema.
+     */
+    private sectionValidate;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): SettingsSchema<Src | null>;

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

@@ -66,24 +66,113 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     private readonly previewInput;
     private readonly isMultiline;
     constructor(options?: StringOptions | undefined, opt?: boolean, isRaw?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], renderInput?: FieldRender | null, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null, isMultiline?: boolean);
+    /**
+     * 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
+     *   .string()
+     *   .describe("Shown in the browser tab and in search results");
+     * export default c.define("/example.val.ts", schema, "Hello");
+     */
     describe(description: string | null): StringSchema<Src>;
     /**
      * @deprecated Use `minLength` instead
+     *
+     * @example
+     * const schema = s.string().minLength(2);
+     * export default c.define("/example.val.ts", schema, "Hi");
      */
     min(minLength: number): StringSchema<Src>;
+    /**
+     * Validate that the string is at least `minLength` characters long.
+     *
+     * @example
+     * const schema = s.string().minLength(2);
+     * export default c.define("/example.val.ts", schema, "Hi");
+     */
     minLength(minLength: number): StringSchema<Src>;
     /**
      * @deprecated Use `maxLength` instead
+     *
+     * @example
+     * const schema = s.string().maxLength(60);
+     * export default c.define("/example.val.ts", schema, "A title that fits");
      */
     max(maxLength: number): StringSchema<Src>;
+    /**
+     * Validate that the string is at most `maxLength` characters long.
+     *
+     * @example
+     * const schema = s.string().maxLength(60);
+     * export default c.define("/example.val.ts", schema, "A title that fits");
+     */
     maxLength(maxLength: number): StringSchema<Src>;
+    /**
+     * Validate that the string matches `regexp`.
+     *
+     * `message` is what the editor is shown when it does not match. Without one
+     * the error names the pattern, which is rarely what a non-developer needs.
+     *
+     * @example
+     * const schema = s
+     *   .string()
+     *   .regexp(/^[a-z0-9-]+$/, "Lower case letters, digits and dashes only");
+     * export default c.define("/example.val.ts", schema, "my-slug");
+     */
     regexp(regexp: RegExp, message?: string): StringSchema<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.string().validate((val) =>
+     *   val.trim() === val ? false : "Must not start or end with a space",
+     * );
+     * export default c.define("/example.val.ts", schema, "Hello");
+     */
     validate(validationFunction: (src: Src) => false | string): StringSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): StringSchema<Src | null>;
     readonly(isReadonly?: boolean): StringSchema<Src>;
     hidden(isHidden?: boolean): StringSchema<Src>;
+    /**
+     * Do not stega encode this string.
+     *
+     * Val normally encodes an invisible pointer back to the source into every
+     * string it hands your app, which is what makes click-to-edit work. A raw
+     * string is handed over exactly as written — use it wherever the value is
+     * not rendered as visible text: a slug, a class name, an `id`, a URL,
+     * anything parsed or compared.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string(),
+     *   slug: s.string().raw(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   title: "Hello",
+     *   slug: "hello",
+     * });
+     */
     raw(): StringSchema<Src extends null ? RawString | null : RawString>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
@@ -107,12 +196,22 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
      *
      * Static configuration, not a callback — see `render.ts`. What a CONTAINER
      * shows for its items is a `preview`, which is a different thing entirely.
+     *
+     * @example
+     * const schema = s.array(s.string().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
      */
     render(input: FieldRender): StringSchema<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.string().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
      */
     preview(select: ItemPreviewInput<Src>): StringSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;