@valbuild/core 0.102.0 → 0.105.0

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

@@ -1,11 +1,9 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { FileSource } from "../source/file.js";
-import { ImageSource } from "../source/image.js";
+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 { RemoteSource } from "../source/remote.js";
-import { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { ImagesEntryMetadata } from "./images.js";
 export type ImageOptions = {
     ext?: ["jpg"] | ["webp"];
@@ -34,7 +32,7 @@ export type ImageMetadata = {
         y: number;
     };
 };
-export declare class ImageSchema<Src extends FileSource<ImageMetadata | undefined> | RemoteSource<ImageMetadata | undefined> | null> extends Schema<Src> {
+export declare class ImageSchema<Src extends ImageSource | null> extends Schema<Src> {
     private readonly options?;
     private readonly opt;
     protected readonly isRemote: boolean;
@@ -45,15 +43,26 @@ export declare class ImageSchema<Src extends FileSource<ImageMetadata | undefine
     private readonly description?;
     constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
     describe(description: string | null): ImageSchema<Src>;
-    remote(): ImageSchema<Src | RemoteSource<ImageMetadata | undefined>>;
+    remote(): ImageSchema<Src>;
     validate(validationFunction: CustomValidateFunction<Src>): ImageSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    /**
+     * The entries of the gallery this field points at, or null when it is a
+     * standalone field.
+     */
+    private galleryEntries;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): ImageSchema<Src | null>;
     readonly(): ImageSchema<Src>;
     hidden(): ImageSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
-export declare const image: (options?: ImageOptions | ValModule<Record<string, ImagesEntryMetadata>>) => ImageSchema<ImageSource | RemoteSource<ImageMetadata | undefined>>;
+/**
+ * An image picked from a gallery. Its dimensions and mime type live in the
+ * gallery, so the field carries only what a person typed.
+ */
+export declare function image(galleryModule: ValModule<Record<string, ImagesEntryMetadata>>): ImageSchema<GalleryImageSource>;
+/** An image of its own, carrying its own dimensions and mime type. */
+export declare function image(options?: ImageOptions): ImageSchema<ImageSource>;

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

@@ -17,9 +17,9 @@ import { SerializedDateSchema } from "./date.js";
 import { SerializedDateTimeSchema } from "./datetime.js";
 import { SerializedRouteSchema } from "./route.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
-import { FileSource } from "../source/file.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,12 +1,9 @@
 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/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 { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type MediaOptions = {
     type: "files" | "images";
@@ -20,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";
@@ -48,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 | RemoteSource<ImageMetadata> | 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;
@@ -71,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;
@@ -115,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 | RemoteSource<ImageMetadata> | 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/remote.d.ts

@@ -1,11 +1 @@
-import { Json } from "../index.js";
-import { RemoteSource } from "../source/remote.js";
 export declare const DEFAULT_VAL_REMOTE_HOST = "https://remote.val.build";
-export declare function convertRemoteSource<Metadata extends {
-    readonly [key: string]: Json;
-} | undefined = {
-    readonly [key: string]: Json;
-} | undefined>(src: RemoteSource<Metadata>): {
-    url: string;
-    metadata?: Metadata;
-};

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 {};

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 { ReifiedRender } from "../render.js";
+import { ReifiedPreview } from "../preview.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type RouteOptions = {
     include?: RegExp;
@@ -68,7 +68,7 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     hidden(): RouteSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    protected executeRender(): ReifiedRender;
+    protected executePreview(): ReifiedPreview;
 }
 export declare const route: <T extends string>(options?: Record<string, never>) => RouteSchema<T>;
 export {};

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

@@ -1,6 +1,7 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { CodeLanguage, ReifiedRender, RenderScope } from "../render.js";
-import { ModuleFilePath, SourcePath } from "../val/index.js";
+import { ReifiedPreview } from "../preview.js";
+import { StringRender } from "../render.js";
+import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type StringOptions = {
     maxLength?: number;
@@ -10,8 +11,16 @@ type StringOptions = {
 };
 export type SerializedStringSchema = {
     type: "string";
-    /** Set when this schema declares a `render`. See `SerializedArraySchema`. */
-    render?: true;
+    /**
+     * How this field is laid out in the editor, carried WHOLE rather than as a
+     * marker.
+     *
+     * A render is static configuration — no closure, no dependency on source — so
+     * unlike a `preview` it serializes in full, and the editor reads it straight
+     * off the schema it already has. See `render.ts` for what that assumption
+     * buys, and what to do if a render ever needs to stop being static.
+     */
+    render?: StringRender;
     options?: {
         maxLength?: number;
         minLength?: number;
@@ -42,12 +51,7 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: StringOptions | undefined, opt?: boolean, isRaw?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], renderInput?: {
-        as: "textarea";
-    } | {
-        as: "code";
-        language: CodeLanguage;
-    } | null, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    constructor(options?: StringOptions | undefined, opt?: boolean, isRaw?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], renderInput?: StringRender | null, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
     describe(description: string | null): StringSchema<Src>;
     /**
      * @deprecated Use `minLength` instead
@@ -69,13 +73,20 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     raw(): StringSchema<Src extends null ? RawString | null : RawString>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
-    render(input: {
-        as: "textarea";
-    } | {
-        as: "code";
-        language: CodeLanguage;
-    }): StringSchema<Src>;
-    protected executeRender(sourcePath: SourcePath | ModuleFilePath, src: Src, _scope?: RenderScope): ReifiedRender;
+    /**
+     * How this field is laid out in the editor: a textarea, or a code editor for
+     * the given language.
+     *
+     * Static configuration, not a callback — see `render.ts`. What a CONTAINER
+     * shows for its items is a `preview`, which is a different thing entirely.
+     */
+    render(input: StringRender): StringSchema<Src>;
+    /**
+     * 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/union.d.ts

@@ -1,5 +1,5 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedRender, RenderScope } from "../render.js";
+import { ReifiedPreview, PreviewScope } from "../preview.js";
 import { SelectorSource } from "../selector/index.js";
 import { SourceObject } from "../source/index.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
@@ -57,7 +57,7 @@ export declare class UnionSchema<Key extends string | Schema<string>, T extends
     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, scope?: RenderScope): ReifiedRender;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
 }
 export declare const union: <Key extends string | Schema<string>, T extends Schema<Key extends string ? SourceObject & { [k in Key]: string; } : Key extends Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => UnionSchema<Key, T, SourceOf<Key, T>>;
 export {};

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

@@ -1,8 +1,15 @@
 import { GenericSelector } from "./index.js";
 import { Source } from "../source/index.js";
-import { ModulePath, SourcePath } from "../val/index.js";
+import { ModuleFilePath, ModulePath, SourcePath } from "../val/index.js";
 export declare function isSelector(source: any): source is GenericSelector<Source>;
 export declare function newSelectorProxy(source: any, path?: SourcePath, moduleSchema?: any): any;
-export declare function createValPathOfItem(arrayPath: SourcePath | ModulePath | undefined, prop: string | number | symbol): SourcePath | undefined;
+export declare function createValPathOfItem(
+/**
+ * `ModuleFilePath` is accepted because the no-separator branch below is
+ * exactly that case: a path with no `?p=` yet gets one, and the key becomes
+ * the first module-path segment. Callers walking a module from its root had
+ * to widen the type themselves, and hand-rolled the concatenation instead.
+ */
+arrayPath: SourcePath | ModulePath | ModuleFilePath | undefined, prop: string | number | symbol): SourcePath | undefined;
 export declare function unsafeCreateSourcePath(path: string, itemKey: string | number | symbol): SourcePath;
 export declare function selectorToVal(s: any): any;

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

@@ -4,22 +4,18 @@ import { Selector as NumberSelector } from "./number.js";
 import { Selector as StringSelector } from "./string.js";
 import { Selector as BooleanSelector } from "./boolean.js";
 import { Selector as PrimitiveSelector } from "./primitive.js";
-import { FileSelector } from "./file.js";
 import { SourcePath } from "../val/index.js";
 import { Source, SourceArray, SourceObject, SourcePrimitive } from "../source/index.js";
 import { Schema } from "../schema/index.js";
 import type { A } from "ts-toolbelt";
-import { FileSource } from "../source/file.js";
+import { MediaSource } from "../source/media.js";
 import { AllRichTextOptions, RichTextSource } from "../source/richtext.js";
-import { ImageSelector } from "./image.js";
 import { RichTextSelector } from "./richtext.js";
-import { ImageSource } from "../source/image.js";
-import { RemoteSource } from "../source/remote.js";
 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 Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : 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 | JsonSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | MediaSource | JsonSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */

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

@@ -1,28 +1,10 @@
-import { VAL_EXTENSION } from "./index.js";
-import { ValConfig } from "../initVal.js";
-import { Json } from "../Json.js";
-export declare const FILE_REF_PROP: "_ref";
-export declare const FILE_REF_SUBTYPE_TAG: "_tag";
-export type FileMetadata = {
-    mimeType?: string;
-};
 /**
- * A file source represents the path to a (local) file.
- *
- * It will be resolved into a Asset object.
+ * What Val computes from a file's bytes.
  *
+ * Not part of the source any more — a media source carries these fields
+ * directly — but still the unit the upload and `--fix` pipelines work in:
+ * "here is what reading this file told us".
  */
-export type FileSource<Metadata extends FileMetadata | undefined = FileMetadata | undefined> = {
-    readonly [FILE_REF_PROP]: string;
-    readonly [VAL_EXTENSION]: "file";
-    readonly [FILE_REF_SUBTYPE_TAG]?: string;
-    readonly metadata?: Metadata;
-    readonly patch_id?: string;
-};
-export declare const initFile: (config?: ValConfig) => {
-    <Metadata extends {
-        readonly [key: string]: Json;
-    }>(ref: `${import("../initVal.js").ConfigDirectory}/${string}`, metadata: Metadata): FileSource<Metadata>;
-    (ref: `${import("../initVal.js").ConfigDirectory}/${string}`, metadata?: undefined): FileSource<undefined>;
+export type FileMetadata = {
+    mimeType?: string;
 };
-export declare function isFile(obj: unknown): obj is FileSource;

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

@@ -1,9 +1,7 @@
-import { FileSource } from "./file.js";
-import { ImageSource } from "./image.js";
 import { JsonSource } from "./json.js";
-import { RemoteSource } from "./remote.js";
+import { MediaSource } from "./media.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | RemoteSource | FileSource | ImageSource | JsonSource | RichTextSource<RichTextOptions>;
+export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {
@@ -14,8 +12,6 @@ export type SourceObject = {
     /** Reserved name */
     andThen?: never;
     /** Reserved name */
-    _ref?: never;
-    /** Reserved name */
     _type?: never;
     /** Reserved name */
     val?: never;
@@ -25,7 +21,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" | "json" | null | undefined;
+export declare function getValExtension(source: Source): false | "" | 0 | "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

@@ -30,7 +30,7 @@ export type JsonImportThunk<T = unknown> = () => Promise<{
  */
 export type JsonSource<T = unknown> = {
     readonly [VAL_EXTENSION]: typeof JSON_VAL_EXTENSION_TAG;
-    /** Set on uncommitted/draft entries (mirrors FileSource/RemoteSource). */
+    /** Set on uncommitted/draft entries (mirrors a media source's). */
     readonly patch_id?: string;
 } & PhantomType<T>;
 export declare function json<T = Json>(importThunk: JsonImportThunk<T>): JsonSource<T>;

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

@@ -0,0 +1,98 @@
+/**
+ * Media — images and files — is a plain object carrying a `path`.
+ *
+ * There is no marker on the value: nothing may decide "this is an image" by
+ * looking at it. The **schema** says so (`type === "image" | "file"`), which is
+ * what lets the same object be written in a `.val.ts` and in a `*.val.json`
+ * entry, where a function call cannot be written at all.
+ *
+ * `path` is a plain `string` rather than a `` `/public/${string}` `` template so
+ * a field can move between local and remote without a type error. Remote-ness
+ * is read off the path: anything not under `/public` is remote.
+ */
+/** What must stay in frame when a page crops an image. */
+export type MediaHotspot = {
+    x: number;
+    y: number;
+};
+/**
+ * The authored fields of a gallery-backed image (`s.image(galleryModule)`):
+ * `width`/`height`/`mimeType` live in the gallery, so they are not repeated
+ * here. One place per fact.
+ */
+export type GalleryImageSource = {
+    readonly path: string;
+    readonly alt?: string;
+    readonly hotspot?: MediaHotspot;
+    /**
+     * Set on a source whose bytes are not committed yet. Injected server-side and
+     * consumed only by {@link mediaUrl} — never written to a `.val.ts`.
+     */
+    readonly patch_id?: string;
+};
+export type ImageSource = GalleryImageSource & {
+    readonly width?: number;
+    readonly height?: number;
+    readonly mimeType?: string;
+};
+export type GalleryFileSource = {
+    readonly path: string;
+    readonly patch_id?: string;
+};
+export type FileSource = GalleryFileSource & {
+    readonly mimeType?: string;
+};
+/**
+ * The structural supertype of every media source.
+ *
+ * It is a named member of the `Source` / `SelectorSource` unions rather than
+ * "just an object" because `SourceObject` is `{[key: string]: Source}` and
+ * `Source` excludes `undefined` — an object with optional properties does not
+ * satisfy it.
+ */
+export type MediaSource = ImageSource;
+/** A path is remote unless it is under `/public`. */
+export declare function isRemoteMediaPath(path: string): boolean;
+/**
+ * Where the bytes of a media source are actually served from.
+ *
+ * Two states, and conflating them is the recurring bug: uncommitted bytes live
+ * in the patch directory and are served by the API with the `patch_id` that put
+ * them there; committed bytes live at the path itself, with `/public` stripped.
+ */
+export declare function mediaUrl(src: {
+    readonly path: string;
+    readonly patch_id?: string;
+}): string;
+/**
+ * A media source plus the URL its bytes are served from.
+ *
+ * `url` is the only generated field: everything else the consumer sees was
+ * either authored or filled in from the gallery.
+ */
+export declare function resolveMedia<S extends {
+    readonly path: string;
+}>(src: S): S & {
+    url: string;
+};
+/**
+ * Fill in what a gallery-backed field does not carry itself.
+ *
+ * `s.image(galleryModule)` stores only `{path, alt?, hotspot?}` — the
+ * dimensions and mime type live in the gallery module, keyed by path. This is
+ * the single implementation of that lookup; core, stega/RSC and the Studio all
+ * call it rather than each rolling their own.
+ *
+ * `alt` is filled in too, because a gallery holds the alt text an editor typed
+ * once for a file used in several places — but only when the field does not
+ * have its own, so a per-image override wins. A gallery whose `alt` schema is a
+ * locale record holds an object rather than a string; that is left alone rather
+ * than copied into a field typed `string`, and making the override
+ * locale-shaped is a separate change.
+ *
+ * The double lookup is load-bearing: a remote gallery keys its entries by the
+ * remote URL while the file itself stays on disk under its local path.
+ */
+export declare function fillFromGallery<S extends {
+    readonly path: string;
+}>(src: S, schema: unknown, getModuleSource: (modulePath: string) => unknown): S;

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

@@ -1,17 +1,3 @@
-import { VAL_EXTENSION } from "./index.js";
-import { ValConfig } from "../initVal.js";
-import { ImageMetadata } from "../schema/image.js";
-import { FILE_REF_PROP, FileMetadata } from "./file.js";
-/**
- * A remote source represents data that is not stored locally.
- */
-export type RemoteSource<Metadata extends FileMetadata | undefined = FileMetadata | undefined> = {
-    readonly [FILE_REF_PROP]: string;
-    readonly [VAL_EXTENSION]: "remote";
-    readonly metadata?: Metadata;
-    readonly patch_id?: string;
-};
-export declare const initRemote: (config?: ValConfig) => <Metadata extends FileMetadata | ImageMetadata>(ref: RemoteRef, metadata?: Metadata) => RemoteSource<Metadata>;
 export type RemoteRef = `${string}/file/p/${string}/b/${string}/v/${string}/h/${string}/f/${string}/p/public/${string}`;
 export declare function createRemoteRef(remoteHost: string, { publicProjectId, coreVersion, validationHash, fileHash, filePath, bucket, }: {
     publicProjectId: string;