@valbuild/core 0.103.0 → 0.105.0

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

@@ -59,7 +59,8 @@ export { type SerializedRichTextSchema, RichTextSchema, } from "./schema/richtex
 export { type SerializedUnionSchema, 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 ListRecordRender, type ListArrayRender, type ReifiedRender, type RenderScope, type CodeLanguage, type CodeRender, renderScope, } from "./render.js";
+export { type PreviewItem, type RecordPreview, type ArrayPreview, type ReifiedPreview, type PreviewScope, previewScope, } from "./preview.js";
+export { type CodeLanguage, type StringRender, CODE_LANGUAGES } from "./render.js";
 export type { ValRouter, RouteValidationError } from "./router.js";
 export { getSourcePathFromRoute } from "./getSourcePathFromRoute.js";
 export declare const FATAL_ERROR_TYPES: readonly ["no-schema", "no-source", "invalid-id", "no-module", "invalid-patch"];

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

@@ -0,0 +1,98 @@
+import { Schema } from "./schema/index.js";
+import { SelectorSource } from "./selector/index.js";
+import { ImageSource } from "./source/media.js";
+import { ModuleFilePath, SourcePath } from "./val/index.js";
+/**
+ * What a container shows for ONE of its items: the user's `preview` callback
+ * returns this, and the Studio draws a row from it.
+ *
+ * NB: {@link ArrayPreview} / {@link RecordPreview} name the DATA a container
+ * previews with. The Studio also has React components called `ArrayPreview` /
+ * `RecordPreview` (the fallback rendering of an array / record field, part of
+ * the `<Type>Preview` convention in `components/Preview.tsx`). They do not
+ * collide today because no file needs both - if one ever does, alias this type
+ * at the import rather than renaming that convention.
+ */
+export type PreviewItem = {
+    title: string;
+    subtitle?: string | null;
+    image?: ImageSource | null;
+};
+export type RecordPreview = {
+    parent: "record";
+    items: [key: string, value: PreviewItem][];
+};
+export type ArrayPreview = {
+    parent: "array";
+    /**
+     * The previewed items, each PAIRED WITH ITS INDEX - the same
+     * `[key, value][]` shape {@link RecordPreview} uses.
+     *
+     * Not a positionally-indexed array, and the reason is
+     * {@link PreviewScope}: a preview computed for a subset of paths carries only
+     * those items, so `items[i]` would silently read the wrong row. Carrying the
+     * index makes a windowed preview impossible to misread - a consumer looks its
+     * index up rather than trusting a position - and makes the array and record
+     * shapes symmetric.
+     */
+    items: [index: number, value: PreviewItem][];
+};
+/**
+ * Main preview type.
+ *
+ * Deliberately not exported: `parent` is the discriminant, and every consumer
+ * narrows on it rather than on the union as a whole. There is no `layout` here
+ * on purpose - how a preview is laid out is the editor's business, not the
+ * schema's.
+ */
+type PreviewTypes = RecordPreview | ArrayPreview;
+type WithStatus<T> = {
+    status: "error";
+    message: string;
+} | {
+    status: "loading";
+    data?: T;
+} | {
+    status: "success";
+    data: T;
+};
+export type ReifiedPreview = Record<SourcePath | ModuleFilePath, WithStatus<PreviewTypes>>;
+/**
+ * Which paths a preview is being computed FOR.
+ *
+ * `executePreview` takes a whole module, so one request has always walked every
+ * node in it and run every `preview` closure - for `handboka`, with `preview` at
+ * two nested array levels, that is every chapter and every section to serve one
+ * visible row. A scope is what makes the walk proportional to what is being
+ * looked at instead of to the project.
+ *
+ * Two questions, because a container and its items need different answers:
+ *
+ * - {@link PreviewScope.wants} - is a preview AT this exact path wanted? A
+ *   container answers `true` here when the whole of it is being shown, and its
+ *   preview is then computed in full.
+ * - {@link PreviewScope.wantsUnder} - could anything at or below this path be
+ *   wanted? Recursion is pruned where this is `false`, and a container whose own
+ *   path is not wanted but which has wanted descendants previews a WINDOW: only
+ *   the items that were asked for. That is the case a single visible row is, and
+ *   it is why {@link ArrayPreview} carries indices.
+ *
+ * Absent scope means the whole module, which is what every existing caller
+ * passes and what every existing caller got.
+ */
+export type PreviewScope = {
+    wants(path: SourcePath | ModuleFilePath): boolean;
+    wantsUnder(path: SourcePath | ModuleFilePath): boolean;
+};
+/**
+ * A scope covering exactly `paths` and their subtrees.
+ *
+ * Compares SEGMENTS rather than string prefixes. A source path's module path is
+ * a quoted, dot-joined encoding (`?p="a".1."b"`), so `startsWith` gets the
+ * ancestor test wrong wherever a key is a prefix of a sibling key or contains a
+ * dot or a quote - `"title"` against `"titles"` being the cheapest example.
+ * Segments are parsed once here, not per comparison.
+ */
+export declare function previewScope(paths: readonly SourcePath[]): PreviewScope;
+export type PreviewSelector<T extends Schema<SelectorSource>> = T extends Schema<infer S> ? S : never;
+export {};

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

@@ -1,98 +1,36 @@
-import { Schema } from "./schema/index.js";
-import { SelectorSource } from "./selector/index.js";
-import { ImageSource } from "./source/media.js";
-import { ModuleFilePath, SourcePath } from "./val/index.js";
-export type ListRecordRender = {
-    layout: "list";
-    parent: "record";
-    items: [
-        key: string,
-        value: {
-            title: string;
-            subtitle?: string | null;
-            image?: ImageSource | null;
-        }
-    ][];
-};
-export type ListArrayRender = {
-    layout: "list";
-    parent: "array";
-    /**
-     * The rendered items, each PAIRED WITH ITS INDEX — the same
-     * `[key, value][]` shape {@link ListRecordRender} uses.
-     *
-     * Not a positionally-indexed array, and the reason is
-     * {@link RenderScope}: a render computed for a subset of paths carries only
-     * those items, so `items[i]` would silently read the wrong row. Carrying the
-     * index makes a windowed render impossible to misread — a consumer looks its
-     * index up rather than trusting a position — and makes the array and record
-     * shapes symmetric.
-     */
-    items: [
-        index: number,
-        value: {
-            title: string;
-            subtitle?: string | null;
-            image?: ImageSource | null;
-        }
-    ][];
-};
-export type TextareaRender = {
-    layout: "textarea";
-};
-export type CodeLanguage = "typescript" | "javascript" | "javascriptreact" | "typescriptreact" | "json" | "java" | "html" | "css" | "xml" | "markdown" | "sql" | "python" | "rust" | "php" | "go" | "cpp" | "sass" | "vue" | "angular";
-export type CodeRender = {
-    layout: "code";
-    language: CodeLanguage;
-};
-type RenderTypes = ListRecordRender | ListArrayRender | TextareaRender | CodeRender;
-type WithStatus<T> = {
-    status: "error";
-    message: string;
-} | {
-    status: "loading";
-    data?: T;
-} | {
-    status: "success";
-    data: T;
-};
-export type ReifiedRender = Record<SourcePath | ModuleFilePath, WithStatus<RenderTypes>>;
 /**
- * Which paths a render is being computed FOR.
+ * A RENDER is how one field is laid out in the editor: `s.string().render({ as:
+ * "textarea" })`, `.render({ as: "code", language })`.
  *
- * `executeRender` takes a whole module, so one request has always walked every
- * node in it and run every `select` closure — for `handboka`, with `select` at
- * two nested array levels, that is every chapter and every section to serve one
- * visible row. A scope is what makes the walk proportional to what is being
- * looked at instead of to the project.
+ * It is static configuration - plain data, with no closure behind it and no
+ * dependency on source - which is why it lives in the SERIALIZED schema
+ * (`SerializedStringSchema.render`) and is read straight off it where the field
+ * is drawn. There is no render pipeline, no store and no host round-trip.
  *
- * Two questions, because a container and its items need different answers:
+ * That "static" is an ASSUMPTION we are taking deliberately, for simplicity,
+ * not a law. A future render could plausibly want to depend on source - a
+ * layout that varies with the value, a callback of its own. If that day comes,
+ * the shape it needs back is `executePreview`'s, and the honest move is to give
+ * `render` its own execute/store pair again. It is NOT to re-merge the two:
+ * conflating them is what this file was split up to undo.
  *
- * - {@link RenderScope.wants} — is a render AT this exact path wanted? A
- *   container answers `true` here when the whole of it is being shown, and its
- *   list render is then computed in full.
- * - {@link RenderScope.wantsUnder} — could anything at or below this path be
- *   wanted? Recursion is pruned where this is `false`, and a container whose own
- *   path is not wanted but which has wanted descendants renders a WINDOW: only
- *   the items that were asked for. That is the case a single visible row is, and
- *   it is why {@link ListArrayRender} carries indices.
- *
- * Absent scope means the whole module, which is what every existing caller
- * passes and what every existing caller got.
+ * The dynamic, source-dependent, demand-scoped thing - what a container shows
+ * for its items - is a PREVIEW. See `preview.ts`.
  */
-export type RenderScope = {
-    wants(path: SourcePath | ModuleFilePath): boolean;
-    wantsUnder(path: SourcePath | ModuleFilePath): boolean;
-};
 /**
- * A scope covering exactly `paths` and their subtrees.
- *
- * Compares SEGMENTS rather than string prefixes. A source path's module path is
- * a quoted, dot-joined encoding (`?p="a".1."b"`), so `startsWith` gets the
- * ancestor test wrong wherever a key is a prefix of a sibling key or contains a
- * dot or a quote — `"title"` against `"titles"` being the cheapest example.
- * Segments are parsed once here, not per comparison.
+ * The list is the declaration and {@link CodeLanguage} is derived from it, so
+ * that a validator elsewhere (`shared`'s zod schema) can enumerate the same
+ * languages without a second copy that drifts. Same shape as `COLOR_FORMATS`.
+ */
+export declare const CODE_LANGUAGES: readonly ["typescript", "javascript", "javascriptreact", "typescriptreact", "json", "java", "html", "css", "xml", "markdown", "sql", "python", "rust", "php", "go", "cpp", "sass", "vue", "angular"];
+export type CodeLanguage = (typeof CODE_LANGUAGES)[number];
+/**
+ * What `s.string().render(...)` takes, and what the serialized schema carries
+ * verbatim.
  */
-export declare function renderScope(paths: readonly SourcePath[]): RenderScope;
-export type RenderSelector<T extends Schema<SelectorSource>> = T extends Schema<infer S> ? S : never;
-export {};
+export type StringRender = {
+    as: "textarea";
+} | {
+    as: "code";
+    language: CodeLanguage;
+};

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

@@ -1,7 +1,6 @@
 import { Schema, SchemaAssertResult, SelectorOfSchema, SerializedSchema } from "./index.js";
-import { RenderSelector, ReifiedRender, RenderScope } from "../render.js";
+import { PreviewItem, PreviewSelector, ReifiedPreview, PreviewScope } from "../preview.js";
 import { SelectorSource } from "../selector/index.js";
-import { ImageSource } from "../source/media.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedArraySchema = {
@@ -9,30 +8,23 @@ export type SerializedArraySchema = {
     item: SerializedSchema;
     opt: boolean;
     /**
-     * Set when this schema declares a `render`.
+     * Set when this schema declares a `preview`.
      *
-     * The render itself cannot be serialized — `select` is a user closure — but
-     * whether one EXISTS can be, and that is worth carrying: it lets the non-host
-     * side skip asking the host to render a module that cannot produce one.
-     * Measured in a browser: mounting 260 fields across 141 modules spent ~2.3ms
-     * of 3.1ms calling `executeRender` on modules that returned nothing.
+     * The preview itself cannot be serialized — it is a user closure — but whether
+     * one EXISTS can be, and that is worth carrying: it lets the non-host side
+     * skip asking the host to preview a module that cannot produce one. Measured
+     * in a browser: mounting 260 fields across 141 modules spent ~2.3ms of 3.1ms
+     * calling `executePreview` on modules that returned nothing.
      */
-    render?: true;
+    preview?: true;
     customValidate?: boolean;
     readonly?: boolean;
     hidden?: boolean;
     description?: string;
 };
-type ArrayRenderInput<T extends Schema<SelectorSource>> = {
-    as: "list";
-    select: (input: {
-        val: RenderSelector<T>;
-    }) => {
-        title: string;
-        subtitle?: string | null;
-        image?: ImageSource | null;
-    };
-};
+type ArrayPreviewInput<T extends Schema<SelectorSource>> = (input: {
+    val: PreviewSelector<T>;
+}) => PreviewItem;
 export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends SelectorOfSchema<T>[] | null> extends Schema<Src> {
     private readonly item;
     private readonly opt;
@@ -40,8 +32,8 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    private readonly renderInput;
-    constructor(item: T, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: ArrayRenderInput<T> | null);
+    private readonly previewInput;
+    constructor(item: T, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ArrayPreviewInput<T> | null);
     describe(description: string | null): ArraySchema<T, Src>;
     validate(validationFunction: (src: Src) => false | string): ArraySchema<T, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -51,8 +43,15 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     hidden(): ArraySchema<T, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedArraySchema;
-    protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: RenderScope): ReifiedRender;
-    render(input: ArrayRenderInput<T>): ArraySchema<T, Src>;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    /**
+     * What the editor shows for each ITEM of this array: a title, and optionally a
+     * subtitle and an image.
+     *
+     * `select` is your own code over the item's source, so it is run on demand for
+     * the rows that are actually being looked at — see `PreviewScope`.
+     */
+    preview(select: ArrayPreviewInput<T>): ArraySchema<T, Src>;
 }
 export declare const array: <S extends Schema<SelectorSource>>(schema: S) => ArraySchema<S, SelectorOfSchema<S>[]>;
 export {};

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedBooleanSchema = {
@@ -26,6 +26,6 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
     hidden(): BooleanSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
 export declare const boolean: () => BooleanSchema<boolean>;

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { SourcePath } from "../val/index.js";
 import { ColorFormat } from "./colorFormat.js";
 import { RawString } from "./string.js";
@@ -52,6 +52,6 @@ export declare class ColorSchema<Src extends string | null> extends Schema<Src>
     readonly(): ColorSchema<Src>;
     hidden(): ColorSchema<Src>;
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
 export declare const color: (options?: ColorOptions) => ColorSchema<RawString>;

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { SourcePath } from "../val/index.js";
 import { RawString } from "./string.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -47,7 +47,7 @@ export declare class DateSchema<Src extends string | null> extends Schema<Src> {
     hidden(): DateSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
 export declare const date: (options?: Record<string, never>) => DateSchema<RawString>;
 export {};

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { SourcePath } from "../val/index.js";
 import { RawString } from "./string.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -51,7 +51,7 @@ export declare class DateTimeSchema<Src extends string | null> extends Schema<Sr
     hidden(): DateTimeSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
 export declare const datetime: (options?: Record<string, never>) => DateTimeSchema<RawString>;
 export {};

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 { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { FilesEntryMetadata } from "./files.js";
 export type FileOptions = {
     accept?: string;
@@ -45,7 +45,7 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     hidden(): FileSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    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 { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { ImagesEntryMetadata } from "./images.js";
 export type ImageOptions = {
     ext?: ["jpg"] | ["webp"];
@@ -57,7 +57,7 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     hidden(): ImageSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    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

@@ -19,7 +19,7 @@ import { SerializedRouteSchema } from "./route.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { FileSource } from "../source/media.js";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext.js";
-import { ReifiedRender, RenderScope } from "../render.js";
+import { ReifiedPreview, PreviewScope } from "../preview.js";
 export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedRouteSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
@@ -107,13 +107,13 @@ export declare abstract class Schema<Src extends SelectorSource> {
     abstract hidden(): Schema<Src>;
     protected abstract executeSerialize(): SerializedSchema;
     /**
-     * @param scope Which paths the caller needs a render for. Absent means the
+     * @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 RenderScope}: a container prunes recursion where nothing is
-     * wanted, and renders a WINDOW when its own path is not wanted but some of its
-     * items are — which is the single-visible-row case.
+     * 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.
      */
-    protected abstract executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: RenderScope): ReifiedRender;
+    protected abstract executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
     /** MUTATES! since internal and perf sensitive */
     protected appendValidationError(current: ValidationErrors, path: SourcePath, message: string, value: unknown, schemaError?: boolean): ValidationErrors;
     /**

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 { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 export type SerializedKeyOfSchema = {
     type: "keyOf";
     path: SourcePath;
@@ -44,7 +44,7 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     hidden(): KeyOfSchema<Sel, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    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 { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedLiteralSchema = {
@@ -28,6 +28,6 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     hidden(): LiteralSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
 export declare const literal: <T extends string>(value: T) => LiteralSchema<T>;

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type NumberOptions = {
@@ -34,7 +34,7 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     min(min: number): NumberSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
 export declare const number: (options?: NumberOptions) => NumberSchema<number>;
 export {};

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SelectorOfSchema, SerializedSchema } from "./index.js";
-import { ReifiedRender, RenderScope } from "../render.js";
+import { ReifiedPreview, PreviewScope } from "../preview.js";
 import { SelectorSource } from "../selector/index.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -52,7 +52,7 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     hidden(): ObjectSchema<Props, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: RenderScope): ReifiedRender;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
 }
 export declare const object: <Props extends ObjectSchemaProps>(schema: Props) => ObjectSchema<Props, ObjectSchemaSrcOf<Props>>;
 export {};

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

@@ -1,8 +1,7 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SelectorOfSchema, SerializedSchema } from "./index.js";
-import { RenderSelector, ReifiedRender, RenderScope } from "../render.js";
+import { PreviewItem, PreviewSelector, ReifiedPreview, PreviewScope } from "../preview.js";
 import { ValRouter } from "../router.js";
 import { SelectorSource } from "../selector/index.js";
-import { ImageSource } from "../source/media.js";
 import { JsonOf, JsonSource } from "../source/json.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -18,8 +17,8 @@ export type SerializedRecordSchema = {
     item: SerializedSchema;
     key?: SerializedSchema;
     opt: boolean;
-    /** Set when this schema declares a `render`. See `SerializedArraySchema`. */
-    render?: true;
+    /** Set when this schema declares a `preview`. See `SerializedArraySchema`. */
+    preview?: true;
     router?: string;
     customValidate?: boolean;
     mediaType?: "files" | "images";
@@ -46,17 +45,10 @@ export type SerializedRecordSchema = {
  * authoring.
  */
 export type JsonValuesRecordSrc<T extends Schema<SelectorSource>, K extends Schema<string>> = Record<SelectorOfSchema<K>, JsonSource<JsonOf<SelectorOfSchema<T>>> | SelectorOfSchema<T>>;
-type RecordRenderInput<T extends Schema<SelectorSource>> = {
-    layout: "list";
-    select: (input: {
-        key: string;
-        val: RenderSelector<T>;
-    }) => {
-        title: string;
-        subtitle?: string | null;
-        image?: ImageSource | null;
-    };
-};
+type RecordPreviewInput<T extends Schema<SelectorSource>> = (input: {
+    key: string;
+    val: PreviewSelector<T>;
+}) => PreviewItem;
 export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Schema<string>, Src extends Record<SelectorOfSchema<K>, SelectorOfSchema<T>> | JsonValuesRecordSrc<T, K> | null> extends Schema<Src> {
     private readonly item;
     private readonly opt;
@@ -69,10 +61,10 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     private readonly description?;
     /** When true, entry values are lazily loaded {@link JsonSource} thunks. */
     private readonly isJsonValues;
-    private readonly renderInput;
+    private readonly previewInput;
     constructor(item: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], currentRouter?: ValRouter | null, keySchema?: Schema<string> | null, mediaOptions?: MediaOptions | undefined, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, 
     /** When true, entry values are lazily loaded {@link JsonSource} thunks. */
-    isJsonValues?: boolean, renderInput?: RecordRenderInput<T> | null);
+    isJsonValues?: boolean, previewInput?: RecordPreviewInput<T> | null);
     describe(description: string | null): RecordSchema<T, K, Src>;
     validate(validationFunction: (src: Src) => false | string): RecordSchema<T, K, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -113,18 +105,16 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
      * defers).
      */
     validateJsonEntryContent(path: SourcePath, content: SelectorSource): ValidationErrors;
-    protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: RenderScope): ReifiedRender;
-    render(input: {
-        as: "list";
-        select: (input: {
-            key: string;
-            val: RenderSelector<T>;
-        }) => {
-            title: string;
-            subtitle?: string | null;
-            image?: ImageSource | null;
-        };
-    }): RecordSchema<T, K, Src>;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    /**
+     * What the editor shows for each ENTRY of this record: a title, and optionally
+     * a subtitle and an image.
+     *
+     * `select` is your own code over the entry's key and source, so it is run on
+     * demand for the entries that are actually being looked at — see
+     * `PreviewScope`.
+     */
+    preview(select: RecordPreviewInput<T>): 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>>>;
 export declare function record<S extends Schema<SelectorSource>>(schema: S): RecordSchema<S, Schema<string>, Record<string, SelectorOfSchema<S>>>;

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

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { RichTextSource, RichTextOptions, SerializedRichTextOptions } from "../source/richtext.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -37,7 +37,7 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     hidden(): RichTextSchema<O, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
 export declare const richtext: <O extends RichTextOptions>(options?: O) => RichTextSchema<O, RichTextSource<O>>;
 export {};