@valbuild/core 0.129.0 → 0.134.0

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

@@ -62,10 +62,13 @@ export declare class DiscriminatedUnionSchema<Key extends string, T extends Disc
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -165,6 +168,6 @@ export declare class DiscriminatedUnionSchema<Key extends string, T extends Disc
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedDiscriminatedUnionSchema;
-    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
 }
 export declare const discriminatedUnion: <Key extends string, T extends DiscriminatedUnionItems<Key>>(key: Key, ...objects: T) => DiscriminatedUnionSchema<Key, T, DiscriminatedUnionSourceOf<Key, T>>;

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -51,10 +51,13 @@ export declare class EnumSchema<Src extends string | null> extends Schema<Src> {
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -120,7 +123,6 @@ export declare class EnumSchema<Src extends string | null> extends Schema<Src> {
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedEnumSchema;
-    protected executePreview(): ReifiedPreview;
 }
 /**
  * Define a string that must be one of a fixed set of values.

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

@@ -4,7 +4,7 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema }
 import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ValModule } from "../index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { FilesetEntryMetadata } from "./fileset.js";
 export type FileOptions = {
@@ -40,10 +40,13 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -145,7 +148,6 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 /**
  * A file picked from a gallery. Its mime type lives in the gallery, so the

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

@@ -3,7 +3,7 @@ import { GalleryImageSource, ImageSource } from "../source/media.js";
 import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ValModule } from "../index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { AltSource, ImagesetEntryMetadata } from "./imageset.js";
 /**
@@ -85,10 +85,13 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -219,7 +222,6 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 /**
  * An image picked from a gallery. Its dimensions and mime type live in the

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

@@ -5,6 +5,7 @@ import { SerializedBooleanSchema } from "./boolean.js";
 import { SerializedFileSchema } from "./file.js";
 import { SerializedImageSchema } from "./image.js";
 import { SerializedKeyOfSchema } from "./keyOf.js";
+import { SerializedValViewSchema } from "./view.js";
 import { SerializedLiteralSchema } from "./literal.js";
 import { SerializedNumberSchema } from "./number.js";
 import { SerializedObjectSchema } from "./object.js";
@@ -24,7 +25,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 | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedLocaleSchema | SerializedSettingsSchema | SerializedImageSchema;
+export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedLocaleSchema | SerializedSettingsSchema | SerializedImageSchema | SerializedValViewSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
     message: string;
@@ -270,13 +271,41 @@ export declare abstract class Schema<Src extends SelectorSource> {
     abstract hidden(isHidden?: boolean): Schema<Src>;
     protected abstract executeSerialize(): SerializedSchema;
     /**
+     * This value's preview, and every preview below it.
+     *
+     * The default is the whole of it for a LEAF: a leaf has nothing below it, so
+     * all it can contribute is {@link PreviewNode.self}. Containers override this
+     * and recurse; object and discriminated union add nothing of their own beyond
+     * the self they inherit here, and array and record add `rows`.
+     *
      * @param scope Which paths the caller needs a preview for. Absent means the
      * whole module, which is what every caller passed before scoping existed.
      * See {@link PreviewScope}: a container prunes recursion where nothing is
      * wanted, and previews a WINDOW when its own path is not wanted but some of
      * its items are — which is the single-visible-row case.
+     * @param selfIsReifiedByParent Set by an array or record on its DIRECT items,
+     * and by nothing else. Such an item's preview is the same closure the
+     * container is already running into {@link PreviewNode.rows}, so emitting a
+     * `self` for it as well would call the user's closure twice per row — which
+     * it did, and which the scoped-preview tests caught by counting. The flag
+     * does not travel further down: a grandchild is nobody's row.
+     */
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
+    /**
+     * THIS value as a preview, at its own path — `{ self }` and nothing else.
+     *
+     * Every schema can produce one, which is the point: before this existed a
+     * value's preview was reified only by its CONTAINER, so a value with no
+     * container had none. A module root is exactly that, and `.preview(...)` on
+     * a module's own schema was therefore dead code — the studio showed the file
+     * name and nothing a developer wrote could change it. So is any field of an
+     * object, which reifies no rows.
+     *
+     * Gated on {@link PreviewScope.wants} rather than `wantsUnder`: a caller
+     * asking about a CONTAINER wants its rows, and computing a self for every
+     * descendant on the way past would run each item's closure twice.
      */
-    protected abstract executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executeSelfPreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
     /**
      * This value AS A PREVIEW — what a container's row, a reference dropdown or
      * a search hit shows for it. Runs the schema's own `preview` closure;

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

@@ -5,7 +5,7 @@ import { Source, SourceObject } from "../source/index.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { RawString } from "./string.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 export type SerializedKeyOfSchema = {
     type: "keyOf";
@@ -45,10 +45,13 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -117,7 +120,6 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const keyOf: <Src extends GenericSelector<SourceObject> & ValModuleBrand>(valModule: Src) => KeyOfSchema<Src, KeyOfSelector<Src>>;
 export {};

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -31,10 +31,13 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -99,6 +102,5 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const literal: <T extends string>(value: T) => LiteralSchema<T>;

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

@@ -1,5 +1,5 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -115,7 +115,6 @@ export declare class LocaleSchema<Src extends string | null> extends Schema<Src>
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 /**
  * Define one of the project's languages.

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -33,10 +33,13 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -115,7 +118,6 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const number: (options?: NumberOptions) => NumberSchema<number>;
 export {};

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

@@ -28,6 +28,16 @@ type ObjectSchemaProps = {
     _type?: never;
     /** Cannot create object with key: _ref. It is a reserved name */
     _ref?: never;
+    /**
+     * Cannot create object with key: view. It is a reserved name.
+     *
+     * A view field's source is `{ view: "/other.val.ts" }`, and the read side
+     * maps that shape to an opaque {@link ValView} handle. An ordinary object
+     * with a single `view: string` key is structurally identical, so it would be
+     * mapped the same way and lose every one of its fields — silently. Reserving
+     * the key is what makes the shape unambiguous.
+     */
+    view?: never;
     /** Cannot create object with key: andThen. It is a reserved name */
     andThen?: never;
     /** Cannot create object with key: assert. It is a reserved name */
@@ -53,10 +63,13 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -145,7 +158,7 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
 }
 export declare const object: <Props extends ObjectSchemaProps>(schema: Props) => ObjectSchema<Props, ObjectSchemaSrcOf<Props>>;
 export {};

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

@@ -111,10 +111,13 @@ RO extends boolean = false> extends Schema<Src> {
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -333,7 +336,7 @@ RO extends boolean = false> extends Schema<Src> {
      * defers).
      */
     validateJsonEntryContent(path: SourcePath, content: SelectorSource): ValidationErrors;
-    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     /**

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { RichTextSource, RichTextOptions, SerializedRichTextOptions } from "../source/richtext.js";
 import { SourcePath } from "../val/index.js";
@@ -34,10 +34,13 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -138,7 +141,6 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const richtext: <O extends RichTextOptions>(options?: O) => RichTextSchema<O, RichTextSource<O>>;
 export {};

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

@@ -1,6 +1,6 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { SourcePath } from "../val/index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type RouteOptions = {
@@ -43,10 +43,13 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -135,7 +138,6 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(): ReifiedPreview;
 }
 export declare const route: <T extends string>(options?: Record<string, never>) => RouteSchema<T>;
 export {};

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

@@ -119,7 +119,7 @@ export declare class SettingsSchema<Src extends {
     hidden(): SettingsSchema<Src>;
     protected executeCustomValidateAt(): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope, selfIsReifiedByParent?: boolean): ReifiedPreview;
 }
 /**
  * Define the project's settings.

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

@@ -1,5 +1,5 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -69,10 +69,13 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     /**
      * 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.
+     * The description is INPUT HELP: it is shown where this field's value is
+     * entered — beside its input in the Val editor, and for a record's key
+     * schema in every form that asks for a key — so it is where you say what an
+     * editor needs to know to fill it in RIGHT, which the field name cannot
+     * carry. It is not a name for the value: that is `.preview(...)`, and it is
+     * read somewhere else. The description 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.
      *
@@ -216,12 +219,6 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     preview(select: ItemPreviewInput<Src>): StringSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
     protected declaresItemPreview(): boolean;
-    /**
-     * Nothing: a string has no items, so there is nothing to preview. Its layout
-     * is a `render`, which travels in the serialized schema instead of through
-     * this pipeline.
-     */
-    protected executePreview(): ReifiedPreview;
 }
 export declare const string: <T extends string>(options?: Record<string, never>) => StringSchema<T>;
 export {};

package/dist/declarations/src/schema/validation/ValidationFix.d.ts

@@ -1,2 +1,2 @@
-export declare const ValidationFix: readonly ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "images:check-remote", "images:upload-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote", "files:check-remote", "files:upload-remote", "keyof:check-keys", "router:check-route", "locale:check-locale", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry", "record:fill-keys", "external:upload"];
+export declare const ValidationFix: readonly ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "images:check-remote", "images:upload-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote", "files:check-remote", "files:upload-remote", "keyof:check-keys", "router:check-route", "locale:check-locale", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry", "record:fill-keys", "external:upload", "view:check-module"];
 export type ValidationFix = (typeof ValidationFix)[number];