@valbuild/core 0.99.0 → 0.100.0

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

@@ -8,6 +8,7 @@ export type { FileMetadata } from "./schema/file.js";
 export type { ValModule, SerializedModule, InferValModuleType } from "./module.js";
 export type { SourceObject, SourcePrimitive, Source } from "./source/index.js";
 export type { FileSource } from "./source/file.js";
+export type { JsonSource, JsonOf, JsonImportThunk } from "./source/json.js";
 export type { RemoteSource, RemoteRef } from "./source/remote.js";
 export { DEFAULT_VAL_REMOTE_HOST } from "./schema/remote.js";
 export type { RawString } from "./schema/string.js";
@@ -34,6 +35,7 @@ import { getMimeType, mimeTypeToFileExt, filenameToMimeType } from "./mimeType/i
 import { type ImageMetadata } from "./schema/image.js";
 import { type FileMetadata } from "./schema/file.js";
 import { isFile } from "./source/file.js";
+import { isJson, getJsonImport, resolveJsonValues } from "./source/json.js";
 import { createRemoteRef } from "./source/remote.js";
 import { getValidationBasis, getValidationHash } from "./remote/validationBasis.js";
 import { getFileHash, hashToRemoteFileHash } from "./remote/fileHash.js";
@@ -88,6 +90,9 @@ declare const Internal: {
     validate: (val: ValModule<SelectorSource>, path: SourcePath, src: unknown) => import("./schema/validation/ValidationError.js").ValidationErrors | undefined;
     isVal: typeof isVal;
     isFile: typeof isFile;
+    isJson: typeof isJson;
+    getJsonImport: typeof getJsonImport;
+    resolveJsonValues: typeof resolveJsonValues;
     createValPathOfItem: typeof createValPathOfItem;
     getSHA256Hash: (bits: Uint8Array) => string;
     initSchema: typeof initSchema;

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

@@ -3,12 +3,14 @@ import { InitSchema } from "./initSchema.js";
 import { getValPath as getPath } from "./val/index.js";
 import { initFile } from "./source/file.js";
 import { initImage } from "./source/image.js";
+import { json } from "./source/json.js";
 import { initRemote } from "./source/remote.js";
 export type ContentConstructor = {
     define: typeof define;
     file: ReturnType<typeof initFile>;
     image: ReturnType<typeof initImage>;
     remote: ReturnType<typeof initRemote>;
+    json: typeof json;
 };
 export type ValConstructor = {
     unstable_getPath: typeof getPath;

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

@@ -3,7 +3,7 @@ import { RenderSelector, ReifiedRender } from "../render.js";
 import { SelectorSource } from "../selector/index.js";
 import { ImageSource } from "../source/image.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedArraySchema = {
     type: "array";
     item: SerializedSchema;
@@ -13,6 +13,16 @@ export type SerializedArraySchema = {
     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;
+    };
+};
 export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends SelectorOfSchema<T>[] | null> extends Schema<Src> {
     private readonly item;
     private readonly opt;
@@ -20,7 +30,8 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(item: T, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    constructor(item: T, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: ArrayRenderInput<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;
@@ -28,18 +39,10 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     nullable(): ArraySchema<T, Src | null>;
     readonly(): ArraySchema<T, Src>;
     hidden(): ArraySchema<T, Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedArraySchema;
-    private renderInput;
     protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src): ReifiedRender;
-    render(input: {
-        as: "list";
-        select: (input: {
-            val: RenderSelector<T>;
-        }) => {
-            title: string;
-            subtitle?: string | null;
-            image?: ImageSource | null;
-        };
-    }): this;
+    render(input: ArrayRenderInput<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,7 +1,7 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { ReifiedRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedBooleanSchema = {
     type: "boolean";
     opt: boolean;
@@ -24,6 +24,7 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
     nullable(): BooleanSchema<Src | null>;
     readonly(): BooleanSchema<Src>;
     hidden(): BooleanSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

@@ -2,7 +2,7 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema }
 import { ReifiedRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { RawString } from "./string.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type DateOptions = {
     /**
      * Validate that the date is this date or after (inclusive).
@@ -45,6 +45,7 @@ export declare class DateSchema<Src extends string | null> extends Schema<Src> {
     nullable(): DateSchema<Src | null>;
     readonly(): DateSchema<Src>;
     hidden(): DateSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

@@ -2,7 +2,7 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema }
 import { ReifiedRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { RawString } from "./string.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type DateTimeOptions = {
     /**
      * Validate that the datetime is this datetime or after (inclusive).
@@ -49,6 +49,7 @@ export declare class DateTimeSchema<Src extends string | null> extends Schema<Sr
     nullable(): DateTimeSchema<Src | null>;
     readonly(): DateTimeSchema<Src>;
     hidden(): DateTimeSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

@@ -2,7 +2,7 @@ import { Json } from "../Json.js";
 import { FileSource } from "../source/file.js";
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { ModulePath, SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { RemoteSource, ValModule } from "../index.js";
 import { ReifiedRender } from "../render.js";
 import { FilesEntryMetadata } from "./files.js";
@@ -41,6 +41,7 @@ export declare class FileSchema<Src extends FileSource<FileMetadata | undefined>
     nullable(): FileSchema<Src | null>;
     readonly(): FileSchema<Src>;
     hidden(): FileSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

@@ -2,7 +2,7 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema }
 import { FileSource } from "../source/file.js";
 import { ImageSource } from "../source/image.js";
 import { ModulePath, SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ValModule } from "../index.js";
 import { RemoteSource } from "../source/remote.js";
 import { ReifiedRender } from "../render.js";
@@ -52,6 +52,7 @@ export declare class ImageSchema<Src extends FileSource<ImageMetadata | undefine
     nullable(): ImageSchema<Src | null>;
     readonly(): ImageSchema<Src>;
     hidden(): ImageSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

@@ -48,6 +48,28 @@ export type CustomValidateFunction<Src extends SelectorSource> = (src: Src, ctx:
 export declare abstract class Schema<Src extends SelectorSource> {
     /** Validate the value of source content */
     protected abstract executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    /**
+     * Runs the custom validate functions declared on THIS node (not its children)
+     * against `src`.
+     *
+     * Abstract because every schema class holds its validators in its own
+     * `private readonly customValidateFunctions`, which no base implementation can
+     * reach — and a base implementation returning `[]` would let a class that
+     * forgot to implement this silently skip its user's validators. A compile error
+     * is the better failure.
+     *
+     * `src` stays a PARAMETER (as in {@link executeValidate}) rather than the
+     * functions being returned: `CustomValidateFunction<Src>` puts `Src` in a
+     * parameter position, so returning them would make `Schema<Src>` invariant and
+     * break every `Schema<Source>` → `Schema<SelectorSource>` assignment in the
+     * codebase.
+     *
+     * Deliberately independent of `executeValidate`: the Studio gets its structural
+     * errors from a worker, which holds a DESERIALIZED schema where user functions
+     * cannot survive, and then executes the custom validators on the main thread
+     * against the real instance. Structural errors publish first; these merge in.
+     */
+    protected abstract executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeCustomValidateFunctions(src: Src, customValidateFunctions: CustomValidateFunction<Src>[], ctx: {
         path: SourcePath;
     }): ValidationError[];

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

@@ -3,7 +3,7 @@ import { ValModuleBrand } from "../module.js";
 import { GenericSelector } from "../selector/index.js";
 import { Source, SourceObject } from "../source/index.js";
 import { SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { RawString } from "./string.js";
 import { ReifiedRender } from "../render.js";
 export type SerializedKeyOfSchema = {
@@ -42,6 +42,7 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     nullable(): KeyOfSchema<Sel, Src | null>;
     readonly(): KeyOfSchema<Sel, Src>;
     hidden(): KeyOfSchema<Sel, Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

@@ -1,7 +1,7 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { ReifiedRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedLiteralSchema = {
     type: "literal";
     value: string;
@@ -26,6 +26,7 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     nullable(): LiteralSchema<Src | null>;
     readonly(): LiteralSchema<Src>;
     hidden(): LiteralSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

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

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

@@ -2,7 +2,7 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SelectorOfSchema, S
 import { ReifiedRender } from "../render.js";
 import { SelectorSource } from "../selector/index.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedObjectSchema = {
     type: "object";
     items: Record<string, SerializedSchema>;
@@ -50,6 +50,7 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     nullable(): ObjectSchema<Props, Src | null>;
     readonly(): ObjectSchema<Props, Src>;
     hidden(): ObjectSchema<Props, Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src): ReifiedRender;
 }

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

@@ -3,10 +3,11 @@ import { RenderSelector, ReifiedRender } from "../render.js";
 import { ValRouter } from "../router.js";
 import { SelectorSource } from "../selector/index.js";
 import { ImageSource } from "../source/image.js";
+import { JsonOf, JsonSource } from "../source/json.js";
 import { RemoteSource } from "../source/remote.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ImageMetadata } from "./image.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type MediaOptions = {
     type: "files" | "images";
     accept: string;
@@ -26,11 +27,37 @@ export type SerializedRecordSchema = {
     directory?: string;
     remote?: boolean;
     alt?: SerializedSchema;
+    jsonValues?: boolean;
     readonly?: boolean;
     hidden?: boolean;
     description?: string;
 };
-export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Schema<string>, Src extends Record<SelectorOfSchema<K>, SelectorOfSchema<T>> | null> extends Schema<Src> {
+/**
+ * The source type of a `.jsonValues()` record: every entry value is EITHER a
+ * lazily loaded {@link JsonSource} whose resolved content is the (loosened, see
+ * {@link JsonOf}) item type, OR the item value written inline.
+ *
+ * Inline values are accepted by the TYPE on purpose: hand-authoring an entry
+ * directly in the `.val.ts` (or copying one in from a non-jsonValues record) is
+ * the natural first thing to write, and a type error there is a dead end — the
+ * author cannot see what to write instead. Validation reports the inline entry
+ * (`jsonValues:extract-entry`) and `val validate --fix` moves it into its own
+ * `*.val.json`, so the mistake is caught and repaired instead of blocking
+ * 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 | RemoteSource<ImageMetadata> | null;
+    };
+};
+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;
     private readonly customValidateFunctions;
@@ -40,7 +67,12 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    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. */
+    private readonly isJsonValues;
+    private readonly renderInput;
+    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);
     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;
@@ -56,9 +88,31 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     hidden(): RecordSchema<T, K, Src>;
     router(router: ValRouter): RecordSchema<T, K, Src>;
     remote(): RecordSchema<T, K, Src>;
+    /**
+     * Store each entry's value in its own lazily-loaded `*.val.json` file instead
+     * of inlining it in the `.val.ts` module. Entry values become
+     * {@link JsonSource} thunks (`c.json(() => import("./entry.val.json"))`),
+     * which lets the runtime, the Studio and validation work one entry at a time
+     * so a record/router can scale to many thousands of entries.
+     *
+     * Not supported on image/file galleries (`s.images()` / `s.files()`).
+     *
+     * Only supported on a module's ROOT record/router — a `.jsonValues()` record
+     * 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.
+     */
+    jsonValues(): RecordSchema<T, K, JsonValuesRecordSrc<T, K>>;
     private getRouterValidations;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedRecordSchema;
-    private renderInput;
+    /**
+     * Validate the loaded content of a single `.jsonValues()` entry against the
+     * item schema. The server calls this once it has loaded the backing
+     * `*.val.json` for an entry (the deep validation that `executeValidate`
+     * defers).
+     */
+    validateJsonEntryContent(path: SourcePath, content: SelectorSource): ValidationErrors;
     protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src): ReifiedRender;
     render(input: {
         as: "list";
@@ -70,7 +124,7 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
             subtitle?: string | null;
             image?: ImageSource | RemoteSource<ImageMetadata> | null;
         };
-    }): this;
+    }): 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

@@ -2,7 +2,7 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema }
 import { ReifiedRender } from "../render.js";
 import { RichTextSource, RichTextOptions, SerializedRichTextOptions } from "../source/richtext.js";
 import { SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type ValidationOptions = {
     maxLength?: number;
     minLength?: number;
@@ -35,6 +35,7 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     nullable(): RichTextSchema<O, Src | null>;
     readonly(): RichTextSchema<O, Src>;
     hidden(): RichTextSchema<O, Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

@@ -1,7 +1,7 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { SourcePath } from "../val/index.js";
 import { ReifiedRender } from "../render.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type RouteOptions = {
     include?: RegExp;
     exclude?: RegExp;
@@ -66,6 +66,7 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     nullable(): RouteSchema<Src | null>;
     readonly(): RouteSchema<Src>;
     hidden(): RouteSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     protected executeRender(): ReifiedRender;
 }

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

@@ -1,7 +1,7 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { CodeLanguage, ReifiedRender } from "../render.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type StringOptions = {
     maxLength?: number;
     minLength?: number;
@@ -65,6 +65,7 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     readonly(): StringSchema<Src>;
     hidden(): StringSchema<Src>;
     raw(): StringSchema<Src extends null ? RawString | null : RawString>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     render(input: {
         as: "textarea";

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

@@ -5,7 +5,7 @@ import { SourceObject } from "../source/index.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { SerializedLiteralSchema } from "./literal.js";
 import { SerializedObjectSchema } from "./object.js";
-import { ValidationErrors } from "./validation/ValidationError.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedUnionSchema = SerializedStringUnionSchema | SerializedObjectUnionSchema;
 export type SerializedStringUnionSchema = {
     type: "union";
@@ -47,6 +47,14 @@ export declare class UnionSchema<Key extends string | Schema<string>, T extends
     nullable(): UnionSchema<Key, T, Src | null>;
     readonly(): UnionSchema<Key, T, Src>;
     hidden(): UnionSchema<Key, T, Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * The variant schema a value takes, for a TAGGED union (string `key`). `null`
+     * for a literal union (its variants are leaves with nothing to descend into) or
+     * when the value matches none of them — a structural error `executeValidate`
+     * already reports.
+     */
+    private matchedVariant;
     protected executeSerialize(): SerializedSchema;
     constructor(key: Key, items: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
     protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src): ReifiedRender;

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", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files"];
+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", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry"];
 export type ValidationFix = (typeof ValidationFix)[number];

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

@@ -15,10 +15,11 @@ import { ImageSelector } from "./image.js";
 import { RichTextSelector } from "./richtext.js";
 import { ImageSource } from "../source/image.js";
 import { RemoteSource } from "../source/remote.js";
-export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends ImageSource ? ImageSelector : T extends FileSource<infer M> ? FileSelector<M> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
+import { JsonSource } from "../source/json.js";
+export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends ImageSource ? ImageSelector : T extends FileSource<infer M> ? FileSelector<M> : T extends JsonSource ? GenericSelector<JsonSource> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
 export type SelectorSource = SourcePrimitive | undefined | readonly SelectorSource[] | {
     [key: string]: SelectorSource;
-} | ImageSource | FileSource | RemoteSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | ImageSource | FileSource | RemoteSource | JsonSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */

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

@@ -1,8 +1,9 @@
 import { FileSource } from "./file.js";
 import { ImageSource } from "./image.js";
+import { JsonSource } from "./json.js";
 import { RemoteSource } from "./remote.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | RemoteSource | FileSource | ImageSource | RichTextSource<RichTextOptions>;
+export type Source = SourcePrimitive | SourceObject | SourceArray | RemoteSource | FileSource | ImageSource | JsonSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {
@@ -24,7 +25,7 @@ export type SourceObject = {
 export type SourceArray = readonly Source[];
 export type SourcePrimitive = string | number | boolean | null;
 export declare const VAL_EXTENSION: "_type";
-export declare function getValExtension(source: Source): false | "" | 0 | "remote" | "file" | null | undefined;
+export declare function getValExtension(source: Source): false | "" | 0 | "remote" | "file" | "json" | null | undefined;
 /**
  * A phantom type parameter is one that doesn't show up at runtime, but is checked statically (and only) at compile time.
  *

package/dist/declarations/src/source/json.d.ts

@@ -0,0 +1,73 @@
+import { PhantomType, Source, VAL_EXTENSION } from "./index.js";
+import { Json } from "../Json.js";
+/**
+ * The string used as the `_type` discriminator of a {@link JsonSource}.
+ */
+export declare const JSON_VAL_EXTENSION_TAG: "json";
+/**
+ * The lazy import thunk a {@link JsonSource} carries at runtime. It is NOT part
+ * of the {@link JsonSource} type because `Source` must stay JSON-serializable
+ * (it is sent over the wire as `Json`); the thunk is a runtime-only detail,
+ * read via {@link getJsonImport}.
+ */
+export type JsonImportThunk<T = unknown> = () => Promise<{
+    default: T;
+}>;
+/**
+ * A JSON source represents a record/router entry whose value is stored in a
+ * separate `*.val.json` file and loaded lazily via a dynamic `import()` thunk.
+ *
+ * This is what `c.json(() => import("./entry.val.json"))` returns.
+ *
+ * The *type* is a pure-JSON marker (`{ _type: "json", patch_id? }`) so that
+ * `Source` stays JSON-serializable. At runtime the value additionally carries a
+ * lazy import thunk (read via {@link getJsonImport}); over the wire only the
+ * marker is sent.
+ *
+ * The phantom type parameter `T` is the (loosened, see {@link JsonOf}) type of
+ * the value the JSON file resolves to. It is covariant: a `JsonSource` of a
+ * narrower value type is assignable to a `JsonSource` of a wider one.
+ */
+export type JsonSource<T = unknown> = {
+    readonly [VAL_EXTENSION]: typeof JSON_VAL_EXTENSION_TAG;
+    /** Set on uncommitted/draft entries (mirrors FileSource/RemoteSource). */
+    readonly patch_id?: string;
+} & PhantomType<T>;
+export declare function json<T = Json>(importThunk: JsonImportThunk<T>): JsonSource<T>;
+export declare function isJson(obj: unknown): obj is JsonSource;
+/**
+ * Reads the runtime-only lazy import thunk from a {@link JsonSource}. Returns
+ * `undefined` for a transport marker (sent over the wire without the thunk).
+ */
+export declare function getJsonImport(source: JsonSource): JsonImportThunk | undefined;
+/**
+ * Recursively resolves every {@link JsonSource} marker in a source tree by
+ * invoking its lazy import thunk, returning a fully-inlined source. This backs
+ * the eager `fetchVal`/`useVal` path (load everything).
+ *
+ * Markers without a runtime thunk (transport markers received over the wire)
+ * are left as-is — there is nothing to load from them locally. Other branded
+ * leaf sources (file/image/remote/richtext) are returned untouched.
+ */
+export declare function resolveJsonValues(source: Source): Promise<Source>;
+/**
+ * Loosens a (strict) schema source type `T` into the type that a
+ * `resolveJsonModule` import of the backing `*.val.json` can actually satisfy.
+ *
+ * Why this is needed: TypeScript widens literals when it infers the type of a
+ * JSON module (e.g. `"a"` becomes `string`, `1` becomes `number`, and a branded
+ * `_type: "file"` becomes `_type: string`). A strict schema type (with literal
+ * unions, `RawString` brands, etc.) would therefore reject a perfectly valid
+ * JSON file. `JsonOf<T>` performs the same widening at the type level so the
+ * JSON content typechecks against the schema as strictly as JSON allows. Runtime
+ * validation enforces the rest.
+ *
+ * The transform distributes over unions and recurses through objects/arrays,
+ * preserving structure while widening every leaf literal. Val object-unions are
+ * always discriminated, so distribute-and-recurse is sufficient (the discriminant
+ * literal widens to its base type, but the per-variant shape stays distinct and a
+ * concrete JSON value still matches exactly one variant).
+ */
+export type JsonOf<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends null ? null : T extends undefined ? undefined : T extends readonly (infer E)[] ? JsonOf<E>[] : T extends object ? {
+    [K in keyof T]: JsonOf<T[K]>;
+} : T;